Library /sys$common/syshlp/helplib.hlb  —  CRTL  getpwuid
    The getpwuid function returns information about a user database
    entry for the specified uid.

    The getpwuid_r function is a reentrant version of getpwuid.

    These functions are OpenVMS Alpha only.

    Format

      #include  <pwd.h>

      struct passwd *getpwuid  (uid_t uid); (ISO POSIX-1)

      struct passwd *getpwuid  (uid_t uid, . . . ); (DEC C Extension)

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

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

1  –  Function Variants

    The getpwuid and getpwuid_r functions have variants named __32_
    getpwuid, _getpwuid_r32 and __64_getpwuid, _getpwuid_r64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

2  –  Arguments

 uid

    The user ID (UID) for which the attributes are to be read.

 pwd

    The location where the retrieved passwd structure is to be
    placed.

 buffer

    A working buffer for the result argument that is able to hold the
    entry in the passwd structure. Storage referenced by the passwd
    structure is allocated from the memory provided with the buffer
    argument, which is bufsize characters in size.

 bufsize

    The length of the character array that buffer points to.

 result

    Upon successful return, result is set to pwd. Upon unsuccessful
    return, result is set to NULL.

  . . .

    An optional argument that can be either 1 or 0. If you specify
    1, the directory specification is returned in OpenVMS format. If
    you specify 0, the directory specification (pathname) is returned
    in UNIX style format. If you omit this argument, the function
    returns the directory specification according to your current
    command-language interpreter.

3  –  Description

    The getpwuid function searches the user database for an entry
    with the specified uid. The function returns the first user entry
    in the database with a pw_uid member of the passwd structure that
    matches the uid argument.

    The passwd structure is defined in the <pwd.h> header file as
    follows:

    pw_name    The user's login name.
    pw_uid     The numerical user ID.
    pw_gid     The numerical group ID.
    pw_dir     The home directory of the user.
    pw_shell   The initial program for the user.

                                   NOTE

       All information generated by the getpwuid function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

    The getpwuid_r function is the reentrant version of getpwuid.
    The getpwuid_r function updates the passwd structure pointed to
    by pwd and stores a pointer to that structure at the location
    pointed to by result. The structure will contain an entry from
    the user database with a matching uid. Storage referenced by the
    structure is allocated from the memory provided with the buffer
    argument, which is bufsize characters in size. The maximum size
    needed for this buffer can be determined with the _SC_GETPW_R_
    SIZE_MAX parameter of the sysconf function. On error or if the
    requested entry is not found, a NULL pointer is returned at the
    location pointed to by result.

    Applications wishing to check for error situations should set
    errno to 0 before calling getpwuid. If getpwuid returns a NULL
    pointer and errno is nonzero, an error occurred.

    See also getuid to know how UIC is represented.

4  –  Return Values

    x                  getpwuid returns a pointer to a valid passwd
                       structure, if a matching entry is found.
    NULL               getpwuid returns NULL if an error occurred or
                       a matching entry was not found. errno is set
                       to indicate the error. The getpwuid function
                       may fail if:

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getpwnam.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

    0                  When successful, getpwuid_r returns 0 and
                       stores a pointer to the updated passwd
                       structure at the location pointed to by
                       result.
    0                  When unsuccessful (on error or if the
                       requested entry is not found), getpwuid_r
                       returns 0 and stores a NULL pointer at the
                       location pointed to by result. The getpwuid_r
                       function may fail if:

                       o  ERANGE - Insufficient storage was supplied
                          through buffer and bufsize to contain the
                          data to be referenced by the resulting
                          passwd structure.
Close Help