---
name: "cap_endpwent"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/cap_endpwent"
---

# cap\_endpwent(3)

library for password database operations in capability mode

## NAME

**cap\_getpwent**, **cap\_getpwnam**, **cap\_getpwuid**, **cap\_getpwent\_r**, **cap\_getpwnam\_r**, **cap\_getpwuid\_r**, **cap\_setpassent**, **cap\_setpwent**, **cap\_endpwent**, **cap\_pwd\_limit\_cmds**, **cap\_pwd\_limit\_fields**, **cap\_pwd\_limit\_users** – library for password database operations in capability mode

## LIBRARY

library “libcap\_pwd”

## SYNOPSIS

**#include \<libcasper.h\>**

**#include \<casper/cap\_pwd.h\>**

*struct* *passwd* *\**\

**cap\_getpwent**(*cap\_channel\_t \*chan*);

*struct* *passwd* *\**\

**cap\_getpwnam**(*cap\_channel\_t \*chan*, *const char \*login*);

*struct* *passwd* *\**\

**cap\_getpwuid**(*cap\_channel\_t \*chan*, *uid\_t uid*);

*int*\

**cap\_getpwent\_r**(*cap\_channel\_t \*chan*, *struct passwd \*pwd*, *char \*buffer*, *size\_t bufsize*, *struct passwd \*\*result*);

*int*\

**cap\_getpwnam\_r**(*cap\_channel\_t \*chan*, *const char \*name*, *struct passwd \*pwd*, *char \*buffer*, *size\_t bufsize*, *struct passwd \*\*result*);

*int*\

**cap\_getpwuid\_r**(*cap\_channel\_t \*chan*, *uid\_t uid*, *struct passwd \*pwd*, *char \*buffer*, *size\_t bufsize*, *struct passwd \*\*result*);

*int*\

**cap\_setpassent**(*cap\_channel\_t \*chan*, *int stayopen*);

*void*\

**cap\_setpwent**(*cap\_channel\_t \*chan*);

*void*\

**cap\_endpwent**(*cap\_channel\_t \*chan*);

*int*\

**cap\_pwd\_limit\_cmds**(*cap\_channel\_t \*chan*, *const char \* const \*cmds*, *size\_t ncmds*);

*int*\

**cap\_pwd\_limit\_fields**(*cap\_channel\_t \*chan*, *const char \* const \*fields*, *size\_t nfields*);

*int*\

**cap\_pwd\_limit\_users**(*cap\_channel\_t \*chan*, *const char \* const \*names*, *size\_t nnames*, *uid\_t \*uids*, *size\_t nuids*);

## DESCRIPTION

The functions **cap\_getpwent**(), **cap\_getpwnam**(), **cap\_getpwuid**(), **cap\_getpwent\_r**(), **cap\_getpwnam\_r**(), **cap\_getpwuid\_r**(), **cap\_setpassent**(), **cap\_setpwent**(), and **cap\_endpwent**() are respectively equivalent to [getpwent(3)](/getpwent/3.md), [getpwnam(3)](/getpwnam/3.md), [getpwuid(3)](/getpwuid/3.md), [getpwent\_r(3)](/getpwent_r/3.md), [getpwnam\_r(3)](/getpwnam_r/3.md), [getpwuid\_r(3)](/getpwuid_r/3.md), [setpassent(3)](/setpassent/3.md), [setpwent(3)](/setpwent/3.md), and [cap\_endpwent(3)](/cap_endpwent/3.md) except that the connection to the **system.pwd** service needs to be provided.

The **cap\_pwd\_limit\_cmds**() function limits the functions allowed in the service. The *cmds* variable can be set to getpwent, getpwnam, getpwuid, getpwent\_r, getpwnam\_r, getpwuid\_r, setpassent, setpwent, or endpwent which will allow to use the function associated with the name. The *ncmds* variable contains the number of *cmds* provided.

The **cap\_pwd\_limit\_fields**() function allows limit fields returned in the structure *passwd*. The *fields* variable can be set to pw\_name, pw\_passwd, pw\_uid, pw\_gid, pw\_change, pw\_class, pw\_gecos, pw\_dir, pw\_shell, pw\_expire or pw\_fields The field which was set as the limit will be returned, while the rest of the values not set this way will have default values. The *nfields* variable contains the number of *fields* provided.

The **cap\_pwd\_limit\_users**() function allows to limit access to users. The *names* variable allows to limit users by name and the *uids* variable by the user number. The *nnames* and *nuids* variables provide numbers of limited names and uids.

All of these functions are reentrant but not thread-safe. That is, they may be called from separate threads only with different *cap\_channel\_t* arguments or with synchronization.

## EXAMPLES

The following example first opens a capability to casper and then uses this capability to create the **system.pwd** casper service and uses it to get a user name.

```
cap_channel_t *capcas, *cappwd;
const char *cmds[] = { "getpwuid" };
const char *fields[] = { "pw_name" };
uid_t uid[] = { 1 };
struct passwd *passwd;
/* Open capability to Casper. */
capcas = cap_init();
if (capcas == NULL)
        err(1, "Unable to contact Casper");
/* Enter capability mode sandbox. */
if (cap_enter() < 0 && errno != ENOSYS)
        err(1, "Unable to enter capability mode");
/* Use Casper capability to create capability to the system.pwd service. */
cappwd = cap_service_open(capcas, "system.pwd");
if (cappwd == NULL)
        err(1, "Unable to open system.pwd service");
/* Close Casper capability, we don't need it anymore. */
cap_close(capcas);
/* Limit service to one single function. */
if (cap_pwd_limit_cmds(cappwd, cmds, nitems(cmds)))
	err(1, "Unable to limit access to system.pwd service");
/* Limit service to one field as we only need name of the user. */
if (cap_pwd_limit_fields(cappwd, fields, nitems(fields)))
	err(1, "Unable to limit access to system.pwd service");
/* Limit service to one uid. */
if (cap_pwd_limit_users(cappwd, NULL, 0, uid, nitems(uid)))
	err(1, "Unable to limit access to system.pwd service");
passwd = cap_getpwuid(cappwd, uid[0]);
if (passwd == NULL)
	err(1, "Unable to get name of user");
printf("UID %d is associated with name %s.\n", uid[0], passwd->pw_name);
cap_close(cappwd);
```

## SEE ALSO

[cap\_enter(2)](/cap_enter/2.md), [endpwent(3)](/endpwent/3.md), [err(3)](/err/3.md), [getpwent(3)](/getpwent/3.md), [getpwent\_r(3)](/getpwent_r/3.md), [getpwnam(3)](/getpwnam/3.md), [getpwnam\_r(3)](/getpwnam_r/3.md), [getpwuid(3)](/getpwuid/3.md), [getpwuid\_r(3)](/getpwuid_r/3.md), [setpassent(3)](/setpassent/3.md), [setpwent(3)](/setpwent/3.md), [capsicum(4)](/capsicum/4.md), [nv(9)](/nv/9.md)

## HISTORY

The **cap\_pwd** service first appeared in FreeBSD 10.3.

## AUTHORS

The **cap\_pwd** service was implemented by Pawel Jakub Dawidek ⟨*pawel@dawidek.net*⟩ under sponsorship from the FreeBSD Foundation.

This manual page was written by Mariusz Zaborski ⟨*oshogbo@FreeBSD.org*⟩.