getpwnam()

NAME

getpwnam(), getpwuid(), getpwuid_ex() - user accounts database operations

SYNOPSIS

#include <sys/types.h>
#include <pwd.h>


struct passwd * getpwnam (const char *login)
struct passwd * getpwuid (uid_t uid)
struct passwd * getpwuid_ex (uid_t uid, int flags)

These functions operate on the user accounts database file. Each function returns information in a struct passwd structure, which contains the following members (defined in the header file <pwd.h>):

struct passwd {
   char * pw_name;   /* user name */
   uid_t pw_uid;  /* user ID number */
   gid_t pw_gid;  /* user's group ID number */
   char * pw_dir; /* initial working directory */
   char * pw_shell;  /* initial shell program */
   char * pw_passwd; /* always * */
   char * pw_gecos;  /* user information; see text */
   time_t pw_change; /* time until password must be changed */
   time_t pw_expire; /* time when user's account expires */
};

The functions getpwnam(2) and getpwuid(2) search the user accounts database for the given login name or user uid, respectively. Every Windows NT and Windows 2000 system has its own security database, which is identified by its domain name. Every user and group account defined on that system is stored in this database. User and group names are unique with in a database because they share the same name address space.

Fully-qualified user and group names always include this domain name using the following notations:

domain\logname
domain+logname
logname

With the following meanings:

domain\logname: The user logname in the specified domain.
domain+logname: The user logname in the specified domain. This is the format returned by Interix calls.
logname: The user logname is a member of the principal domain. By default, the principal domain is the domain to which the computer belongs or, in the case of a computer that belongs to a workgroup, the name of the computer itself.

Some user and group names are well-known in Windows and are always prefixed with a bare +. This is an Interix shorthand notation where + is the same as builtin+. These well-known users can be referred to by either notation; examples include SYSTEM, Everyone and Administrators.

The value returned in passwd.pw_name is a fully-qualified name in the format domain+name. The value returned in passwd.pw_shell is taken from the USERCOMMENT field; by default it is /bin/sh, but can be changed using the chsh(1) utility or the Win32 net.exe program. The value returned in passwd.pw_gecos is the user description string in the user database.

The getpwuid_ex(2) function is the same as getpwuid(2) when the flags argument is zero. If PW_FULLNAME is set in flags, all names returned in the resulting struct passwd are fully qualified by their domain. For example, instead of "+Administrator", the result is "computername+Administrator".

RETURN VALUES

The functions getpwnam(2) and getpwuid(2) return a valid pointer to a passwd structure on success or a NULL pointer if no matching entry is found (which is not considered an error).

If an error occurs, the functions return a NULL pointer and set the value of errno.

The return values may point to static data that is overwritten on each call.

ERRORS

The getpwuid(2) and getpwnam(2) calls may fail for the following reasons:

[EIO]: An I/O error occurred.
[EINTR]: A signal was caught during the call.
[EMFILE]: The calling process already had {OPEN_MAX} file descriptors open.
[ENFILE]: The system already had the maximum allowable number of files open.

NOTES

There is a long-standing convention that the pw_gecos member contains a string of comma-separated fields, traditionally:

fullname,office#,workphone#,homephone#

It is not reasonable to assume that Windows administrators will follow this convention. Therefore, code such as this may not return the expected information:

char *cp = strtok(Sender->pw_gecos,",;");