getpwnam_r(2)                                             getpwnam_r(2)

  getpwnam()

  NAME

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

  SYNOPSIS

    #include 
    #include 

    struct passwd * getpwnam (const char *login)
    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)
    struct passwd * getpwuid_ex (uid_t uid, int flags)

  DESCRIPTION

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

    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
    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.

    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 passwd structure are fully qualified by their domain. For
    example, instead of "+Administrator", the result is
    "computername+Administrator".

    The reentrant getpwnam_r(2) and getpwuid_r(2) functions update the passwd
    structure identified by pwd and store a pointer to that structure at the
    location pointed to by result. The structure contains an entry from the
    user database with a name or uid matching the name or uid argument,
    respectively. Storage referenced by the structure is allocated from the
    memory provided by the buffer argument, which is bufsize bytes in size.
    The maximum size needed for this buffer can be determined with the
    {_SC_GETPW_R_SIZE_MAX} sysconf(2) parameter. A NULL pointer is returned at
    the location pointed to by result on error or if the requested entry is
    not found.

    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.

  RETURN VALUES

    The functions getpwnam(2) and getpwuid(2) functions 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.

    On success, the getpwnam_r(2) and getpwuid_r(2) functions return zero;
    otherwise, an error number is returned to indicate the error.

  ERRORS

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

    [EIO]
        An I/O error occurred.

    [EINTR]
        A signal was caught during the call.

    The getpwuid_r(2) and getpwnam_r(2) calls may fail for the following
    reason:

    [ERANGE]
        Insufficient storage was supplied by the buffer and bufsize arguments
        to contain the data to be referenced by the resulting passwd
        structure.

  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,",;");

  SEE ALSO

    getgrnam(2)

    getgroups(2)

    getlogin(2)

    stripdomainprefix(3)

  USAGE NOTES

    The following functions are thread safe: getpwnam_r, getpwuid_r. The
    following functions are not thread safe: getpwnam, getpwuid, getpwuid_ex.

    None of these functions are async-signal safe.