getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r() -- search user database for particular name or user ID

SYNOPSIS

#include <sys/types.h>

#include <pwd.h>

struct passwd *getpwnam(const char *name);

int getpwnam_r(const char *name, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result);

struct passwd *getpwuid(uid_t uid);

int getpwuid_r(uid_t uid, struct passwd *pwd, char *buffer, size_t bufsize, struct passwd **result);

DESCRIPTION

The getpwnam() routine searches the user database for an entry with a matching name. If found, it returns a pointer to a structure with information about that user. This function is not reentrant.

The getpwnam_r() routine searches the user database for an entry with a matching name. If found, it fills in the passwd structure using the specified buffer, and returns a pointer to the structure. This function is reentrant.

The getpwuid() routine searches the user database for an entry with a matching user ID. If found, it returns a pointer to a structure with information about that user. This function is not reentrant.

The getpwuid_r() routine searches the user database for an entry with a matching user ID. If found, it fills in the passwd structure using the specified buffer, and returns a pointer to the structure. This function is reentrant.

The correct size for the buffer for getpwnam_r() and getpwuid_r() can be determined by calling:

size = sysconf(_SC_GETPW_R_SIZE_MAX);

PARAMETERS

name: Is the name of the user to look up in the user database. getpwnam() and getpwnam_r() fill in the passwd structure with data about the user.
uid: Is the user ID of the user to look up in the user database. getpwuid() and getpwuid_r() fill in the passwd structure with data about the user.
pwd: Points to a passwd structure to be filled in.
buffer: Points to a buffer where the data needed for the passwd structure members is to be placed.
bufsize: Is the size of the buffer being passed.
result: Is a pointer that, on success, contains the address of pwd, or, on failure, contains NULL.

RETURN VALUES

If successful, getpwnam() and getpwuid() return a pointer to a static passwd structure. This structure may be overwritten by subsequent calls to getpwnam() or getpwuid().

If successful, getpwnam_r() and getpwuid_r() return 0.

If an error occurs or if the requested entry is not found, getpwnam() and getpwuid() return a null pointer, and errno is set to one of the following values, while getpwnam_r() and getpwuid_r() return one of the following values:

EFAULT: The name, pwd, buf, or result parameter is not a valid pointer.
EINVAL: The name parameter is not a valid user name, or the uid parameter is not a valid user ID.
ERANGE: Insufficient storage was supplied via buffer and bufsize to contain the data to be referenced by the resulting structure.

CONFORMANCE

POSIX.1 (1996).

MULTITHREAD SAFETY LEVEL

getpwnam(), getpwuid(): Unsafe.

getpwnam_r(), getpwuid_r(): MT-Safe.

PORTING ISSUES

Unlike UNIX platforms, there are common circumstances where getpwuid() may fail. Examples would include situations where a Windows domain controller is not reachable, or the case of a laptop that is undocked and not connected to the network. Applications should properly check the return value of this function, and not assume that NULL will never be returned.

For the case of accounts where no home directory has been defined, the default behavior is for the pw_dir returned to be an empty string. The behavior can be changed with the _NC_SET_PWNAME_PROFILE parameter to _NutConf(). This mode enables a fallback mode where the pw_dir field is set to the profile image path (typically the value of the USERPROFILE environment variable for logged-in users).

AVAILABILITY

PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Professional Developers 64-Bit Edition
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition

getpwnam(), getpwnam_r(), getpwuid(), getpwuid_r()
search user database for particular name or user ID

Function