VMS Help  —  CRTL  getpwnam
    The getpwnam function returns information about a user database
    entry for the specified name.

    The getpwnam_r function is a reentrant version of getpwnam.

    Format

      #include  <pwd.h>

      struct passwd *getpwnam  (const char *name); (ISO POSIX-1)

      struct passwd *getpwnam  (const char *name, . . . );
                               (DEC C Extension)

      int getpwnam_r  (const char *name, struct passwd *pwd,
                      char *buffer, size_t bufsize, struct
                      passwd **result); (ISO POSIX-1),
                      (Integrity servers, Alpha)

      int getpwnam_r  (const char *name, struct passwd *pwd,
                      char *buffer, size_t bufsize, struct
                      passwd **result, . . . ); (DEC C Extension),
                      (Integrity servers, Alpha)

1  –  Function Variants

    The getpwnam and getpwnam_r functions have variants named __32_
    getpwnam, _getpwnam_r32 and __64_getpwnam, _getpwnam_r64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

2  –  Arguments

 name

    The name of the user for which the attributes are to be read.

 pwd

    The address of a passwd structure into which the function writes
    its results.

 buffer

    A working buffer for the result argument that is able to hold the
    largest 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 length.

 bufsize

    The length of the character array that buffer points to.

 result

    Upon successful return, is set to pwd. Upon unsuccessful return,
    the 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 getpwnam function searches the user database for an entry
    with the specified name. The function returns the first user
    entry in the database with the pw_name member of the passwd
    structure that matches the name 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 getpwnam function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

    The getpwnam_r function is the reentrant version of getpwnam.
    The getpwnam_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 that matches the specified name. Storage
    referenced by the structure is allocated from the memory provided
    with the buffer argument, which is bufsize characters in length.
    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 getpwnam. If getpwnam returns a NULL
    pointer and errno is nonzero, an error occurred.

4  –  Return Values

    x                  getpwnam returns a pointer to a valid passwd
                       structure, if a matching entry is found.
    NULL               getpwnam returns NULL if an error occurred
                       or a the specified entry was not found. errno
                       is set to indicate the error. The getpwnam
                       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, getpwnam_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), getpwnam_r
                       returns 0 and stores a NULL pointer at the
                       location pointed to by result. The getpwnam_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.

5  –  Example

      When building a sample program with /def=_USE_STD_STAT, you can
      observe the following:

      o  When the DECC$POSIX_STYLE_UID logical is enabled:

         -  For a system, that supports POSIX style identifiers:

            - getpwnam_r API reads information from the TCP/IP proxy
            database and fills UID and GID with values from the
            TCP/IP proxy database.

            - getgrgid_r API returns gr_name and gr_mem from
            the right's database associated with GID returned by
            getpwnam_r API.

         -  System with no support for POSIX style identifiers,
            getpwnam_r fills GID and UID with SYSGEN parameters as
            "DEFUID" and "DEFGID".

      o  When the DECC$POSIX_STYLE_UID logical is not defined:

         getpwnam function returns information about a user database
         entry for the specified name, which is specified in
         SYSUAF.DAT

        #include <unistd>  // getuid()
        #include <pwd>     // getpwuid_r()
        #include <grp>
        #include <errno.h>
        #include <stdio.h>
        #include <string.h>

        main()
        {

        struct passwd pwd2;
        const unsigned int PWD_BUFF_SIZE = 1024;
        const unsigned int GRP_BUFF_SIZE = 1024;

        struct passwd *p_passwd;
        struct passwd *result;
        struct group *grpresult;
        struct group grp;
        char pwdBuffer[PWD_BUFF_SIZE],*name;
        char grpBuffer[GRP_BUFF_SIZE];
        char buf[PWD_BUFF_SIZE];

        gid_t gid;
        uid_t uid;

        int status;
        p_passwd = getpwnam("user1");
        uid=p_passwd->pw_uid;
        gid=p_passwd->pw_gid;

        printf("User id is %u\n", uid);
        printf("Group id is %u\n", gid);

        status = getpwnam_r("user1", &pwd2, pwdBuffer, PWD_BUFF_SIZE, &result);

        gid = pwd2.pw_gid;

        status = getgrgid_r(gid, &grp, grpBuffer, GRP_BUFF_SIZE, &grpresult);

        gid=grp.gr_gid; name=grp.gr_name;

        strcpy(name,grp.gr_name);

        printf("Group id is %u\n", gid);
        printf("Group name is %s\n", name);

        }

      Running the example program with /def=_USE_STD_STAT produces
      the following result:

      o  When the DECC$POSIX_STYLE_UID logical is NOT enabled, prints
         uid as 11010118 (result of 65536*168+ 70) and gid as 168
         with group name as RTL.

      o  When the DECC$POSIX_STYLE_UID logical is enabled and POSIX
         style identifiers are supported, prints uid as 70, gid as
         168 with group name as FOR_POSIX_TEST (retrieved from TCP/IP
         proxy database).

      o  When the DECC$POSIX_STYLE_UID logical is enabled, but POSIX
         style identifiers are not supported, prints uid as DEFUID,
         gid as DEFGID with group name as invalid buffer.
Close Help