---
name: "pam_start"
section: "3"
platform: "linux"
package: "pam"
version: "1.7.3-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/pam_start"
---

# pam\_start(3)

initialization of PAM transaction

## NAME

pam\_start, pam\_start\_confdir - initialization of PAM transaction

## SYNOPSIS

```
#include <security/pam_appl.h>
```

**int pam\_start(const char \****service\_name***, const char \****user***, const struct pam\_conv \****pam\_conversation***, pam\_handle\_t \*\****pamh***);**

**int pam\_start\_confdir(const char \****service\_name***, const char \****user***, const struct pam\_conv \****pam\_conversation***, const char \****confdir***, pam\_handle\_t \*\****pamh***);**

## DESCRIPTION

The **pam\_start** function creates the PAM context and initiates the PAM transaction. It is the first of the PAM functions that needs to be called by an application. The transaction state is contained entirely within the structure identified by this handle, so it is possible to have multiple transactions in parallel. But it is not possible to use the same handle for different transactions, a new one is needed for every new context.

The *service\_name* argument specifies the name of the service to apply and will be stored as PAM\_SERVICE item in the new context. The policy for the service will be read from the file /etc/pam.d/service\_name or, if that file does not exist, from /etc/pam.conf.

The *user* argument can specify the name of the target user and will be stored as PAM\_USER item. If the argument is NULL, the module has to ask for this item if necessary.

The *pam\_conversation* argument points to a *struct pam\_conv* describing the conversation function to use. An application must provide this for direct communication between a loaded module and the application.

Following a successful return (PAM\_SUCCESS) the contents of *pamh* is a handle that contains the PAM context for successive calls to the PAM functions. In an error case is the content of *pamh* undefined.

The *pam\_handle\_t* is a blind structure and the application should not attempt to probe it directly for information. Instead the PAM library provides the functions [**pam\_set\_item**(3)](/pam_set_item/3.md) and [**pam\_get\_item**(3)](/pam_get_item/3.md). The PAM handle cannot be used for multiple authentications at the same time as long as **pam\_end** was not called on it before.

The **pam\_start\_confdir** function behaves like the **pam\_start** function but it also allows setting *confdir* argument with a path to a directory to override the default (/etc/pam.d) path for service policy files. If the *confdir* is NULL, the function works exactly the same as **pam\_start**.

## RETURN VALUES

PAM\_ABORT

General failure.

PAM\_BUF\_ERR

Memory buffer error.

PAM\_SUCCESS

Transaction was successfully started.

PAM\_SYSTEM\_ERR

System error, for example a NULL pointer was submitted instead of a pointer to data.

## SEE ALSO

[**pam\_get\_data**(3)](/pam_get_data/3.md), [**pam\_set\_data**(3)](/pam_set_data/3.md), [**pam\_end**(3)](/pam_end/3.md), [**pam\_strerror**(3)](/pam_strerror/3.md)