---
name: "pamtest"
section: "3"
platform: "linux"
package: "pam_wrapper-docs"
version: "1.1.8-2"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/pamtest/3"
---

# pamtest(3)

The pamtest API

## NAME

pamtest - The pamtest API

## SYNOPSIS

### Data Structures

struct **pam\_testcase**\
 The PAM testcase struction.  struct **pamtest\_conv\_data**\
 This structure should be used when using run\_pamtest, which uses an internal conversation function.

### Macros

\#define **pam\_test**(op,  expected)\
 Initializes a pam\_tescase structure.  #define **pam\_test\_flags**(op,  expected,  flags)\
 Initializes a CMUnitTest structure with additional PAM flags.

### Typedefs

typedef int(\* **pam\_conv\_fn**) (int num\_msg, const struct pam\_message \*\*msg, struct pam\_response \*\*resp, void \*appdata\_ptr)\
 PAM conversation function, defined in [pam\_conv(3)](/pam_conv/3.md).

### Enumerations

enum **pamtest\_err** { **PAMTEST\_ERR\_OK**, **PAMTEST\_ERR\_START**, **PAMTEST\_ERR\_CASE**, **PAMTEST\_ERR\_OP**, **PAMTEST\_ERR\_END**, **PAMTEST\_ERR\_KEEPHANDLE**, **PAMTEST\_ERR\_INTERNAL** }\
 The return code of the pamtest function.  enum **pamtest\_ops** { **PAMTEST\_AUTHENTICATE**, **PAMTEST\_SETCRED**, **PAMTEST\_ACCOUNT**, **PAMTEST\_OPEN\_SESSION**, **PAMTEST\_CLOSE\_SESSION**, **PAMTEST\_CHAUTHTOK**, **PAMTEST\_GETENVLIST** = 20, **PAMTEST\_KEEPHANDLE** }\
 The enum which describes the operations performed by pamtest().

### Functions

const struct **pam\_testcase** \* **pamtest\_failed\_case** (struct **pam\_testcase** \*test\_cases)\
 Helper you can call if **run\_pamtest()** fails.  void **pamtest\_free\_env** (char \*\*envlist)\
 This frees the string array returned by the PAMTEST\_GETENVLIST test.  const char \* **pamtest\_strerror** (enum **pamtest\_err** perr)\
 return a string representation of libpamtest error code.  enum **pamtest\_err** **run\_pamtest** (const char \*service, const char \*user, struct **pamtest\_conv\_data** \*conv\_data, struct **pam\_testcase** test\_cases\[\], pam\_handle\_t \*pam\_handle)\
 Run libpamtest test cases.  enum **pamtest\_err** **run\_pamtest\_conv** (const char \*service, const char \*user, **pam\_conv\_fn** conv\_fn, void \*conv\_userdata, struct **pam\_testcase** test\_cases\[\], pam\_handle\_t \*pam\_handle)\
 Run libpamtest test cases.

## Detailed Description

## Typedef Documentation

### typedef int(\* pam\_conv\_fn) (int num\_msg, const struct pam\_message \*\*msg, struct pam\_response \*\*resp, void \*appdata\_ptr)

PAM conversation function, defined in [pam\_conv(3)](/pam_conv/3.md). This is just a typedef to use in our declarations. See man [pam\_conv(3)](/pam_conv/3.md) for more details.

## Enumeration Type Documentation

### enum pamtest\_err

The return code of the pamtest function.

**Enumerator**

- ***PAMTEST\_ERR\_OK***

  Testcases returns correspond with input.

- ***PAMTEST\_ERR\_START***

  pam\_start() failed

- ***PAMTEST\_ERR\_CASE***

  A testcase failed. Use pamtest\_failed\_case

- ***PAMTEST\_ERR\_OP***

  Could not run a test case.

- ***PAMTEST\_ERR\_END***

  pam\_end failed

- ***PAMTEST\_ERR\_KEEPHANDLE***

  Handled internally.

- ***PAMTEST\_ERR\_INTERNAL***

  Internal error - bad input or similar.

### enum pamtest\_ops

The enum which describes the operations performed by pamtest().

**Enumerator**

- ***PAMTEST\_AUTHENTICATE***

  run pam\_authenticate to authenticate the account

- ***PAMTEST\_SETCRED***

  run pam\_setcred() to establish/delete user credentials

- ***PAMTEST\_ACCOUNT***

  run pam\_acct\_mgmt() to validate the PAM account

- ***PAMTEST\_OPEN\_SESSION***

  run pam\_open\_session() to start a PAM session

- ***PAMTEST\_CLOSE\_SESSION***

  run pam\_close\_session() to end a PAM session

- ***PAMTEST\_CHAUTHTOK***

  run pam\_chauthtok() to update the authentication token

- ***PAMTEST\_GETENVLIST***

  If this option is set the test will call pam\_getenvlist() and copy the environment into case\_out.envlist.

- ***PAMTEST\_KEEPHANDLE***

  This will prevent calling pam\_end() and will just return the PAM handle in case\_out.ph.

## Function Documentation

### const struct pam\_testcase \* pamtest\_failed\_case (struct pam\_testcase \* test\_cases)

Helper you can call if **run\_pamtest()** fails. If PAMTEST\_ERR\_CASE is returned by **run\_pamtest()** you should call this function get a pointer to the failed test case.

**Parameters**

*test\_cases* The array of tests.

**Returns**

a pointer to the array of test\_cases\[\] that corresponds to the first test case where the expected error code doesn't match the real error code.

### void pamtest\_free\_env (char \*\* envlist)

This frees the string array returned by the PAMTEST\_GETENVLIST test.

**Parameters**

*envlist* The array to free.

### const char \* pamtest\_strerror (enum pamtest\_err perr)

return a string representation of libpamtest error code.

**Parameters**

*perr* libpamtest error code

**Returns**

String representation of the perr argument. Never returns NULL.

References **PAMTEST\_ERR\_CASE**, **PAMTEST\_ERR\_END**, **PAMTEST\_ERR\_INTERNAL**, **PAMTEST\_ERR\_KEEPHANDLE**, **PAMTEST\_ERR\_OK**, **PAMTEST\_ERR\_OP**, and **PAMTEST\_ERR\_START**.

### enum pamtest\_err run\_pamtest (const char \* service, const char \* user, struct pamtest\_conv\_data \* conv\_data, struct pam\_testcase test\_cases\[\], pam\_handle\_t \* pam\_handle)

Run libpamtest test cases. This is using the default libpamtest conversation function.

**Parameters**

*service* The PAM service to use in the conversation\
 *user* The user to run conversation as\
 *conv\_data* Test-specific conversation data\
 *test\_cases* List of libpamtest test cases. Must end with PAMTEST\_CASE\_SENTINEL\
 *pam\_handle* The PAM handle to use to run the tests

```
int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };
    rc = run_pamtest(tests, NULL, NULL);
    return rc;
}
```

**Returns**

PAMTEST\_ERR\_OK on success, else the error code matching the failure.

### enum pamtest\_err run\_pamtest\_conv (const char \* service, const char \* user, pam\_conv\_fn conv\_fn, void \* conv\_userdata, struct pam\_testcase test\_cases\[\], pam\_handle\_t \* pam\_handle)

Run libpamtest test cases. This is using the default libpamtest conversation function.

**Parameters**

*service* The PAM service to use in the conversation\
 *user* The user to run conversation as\
 *conv\_fn* Test-specific conversation function\
 *conv\_userdata* Test-specific conversation data\
 *test\_cases* List of libpamtest test cases. Must end with PAMTEST\_CASE\_SENTINEL\
 *pam\_handle* The PAM handle to use to run the tests

```
int main(void) {
    int rc;
    const struct pam_testcase tests[] = {
        pam_test(PAM_AUTHENTICATE, PAM_SUCCESS),
    };
    rc = run_pamtest(tests, NULL, NULL);
    return rc;
}
```

**Returns**

PAMTEST\_ERR\_OK on success, else the error code matching the failure.

## Author

Generated automatically by Doxygen for pam\_wrapper from the source code.