Man Linux: Main Page and Category List

NAME

       getpwuid, getpwuid_r - search user database for a user ID

SYNOPSIS

       #include <pwd.h>

       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  getpwuid()  function  shall  search the user database for an entry
       with a matching uid.

       The getpwuid() function need not be reentrant. A function that  is  not
       required to be reentrant is not required to be thread-safe.

       Applications  wishing to check for error situations should set errno to
       0 before calling getpwuid(). If getpwuid() returns a null  pointer  and
       errno is set to non-zero, an error occurred.

       The  getpwuid_r() function shall update the passwd structure pointed to
       by pwd and store a pointer to that structure at the location pointed to
       by  result. The structure shall 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 parameter, which is bufsize
       bytes in  size.  The  maximum  size  needed  for  this  buffer  can  be
       determined  with the {_SC_GETPW_R_SIZE_MAX} sysconf() parameter. A NULL
       pointer shall be returned at the location pointed to by result on error
       or if the requested entry is not found.

RETURN VALUE

       The  getpwuid() function shall return a pointer to a struct passwd with
       the structure as defined in <pwd.h> with a matching entry if  found.  A
       null  pointer shall be returned if the requested entry is not found, or
       an error occurs. On error, errno shall be set to indicate the error.

       The return value may point to a static area which is overwritten  by  a
       subsequent call to getpwent(), getpwnam(), or getpwuid().

       If  successful, the getpwuid_r() function shall return zero; otherwise,
       an error number shall be returned to indicate the error.

ERRORS

       The getpwuid() and getpwuid_r() functions may fail if:

       EIO    An I/O error has occurred.

       EINTR  A signal was caught during getpwuid().

       EMFILE {OPEN_MAX} file descriptors are currently open  in  the  calling
              process.

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

       The getpwuid_r() function may fail if:

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

       The following sections are informative.

EXAMPLES

   Getting an Entry for the Root User
       The following example gets the user database entry for  the  user  with
       user ID 0 (root).

              #include <sys/types.h>
              #include <pwd.h>
              ...
              uid_t id = 0;
              struct passwd *pwd;

              pwd = getpwuid(id);

   Finding the Name for the Effective User ID
       The  following  example defines pws as a pointer to a structure of type
       passwd, which is used to store the structure pointer  returned  by  the
       call  to  the  getpwuid() function. The geteuid() function shall return
       the effective user ID of the calling  process;  this  is  used  as  the
       search  criteria  for  the  getpwuid() function. The call to getpwuid()
       shall return a pointer to the structure containing that user ID  value.

              #include <unistd.h>
              #include <sys/types.h>
              #include <pwd.h>
              ...
              struct passwd *pws;
              pws = getpwuid(geteuid());

   Finding an Entry in the User Database
       The following example uses getpwuid() to search the user database for a
       user ID that was previously stored in a stat structure, then prints out
       the  user  name  if it is found.  If the user is not found, the program
       prints the numeric value of the user ID for the entry.

              #include <sys/types.h>
              #include <pwd.h>
              #include <stdio.h>
              ...
              struct stat statbuf;
              struct passwd *pwd;
              ...
              if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
                  printf(" %-8.8s", pwd->pw_name);
              else
                  printf(" %-8d", statbuf.st_uid);

APPLICATION USAGE

       Three names associated with the  current  process  can  be  determined:
       getpwuid(  geteuid())  returns  the  name associated with the effective
       user ID of the process; getlogin() returns the name associated with the
       current  login  activity;  and  getpwuid(  getuid())  returns  the name
       associated with the real user ID of the process.

       The getpwuid_r() function is thread-safe and returns values in a  user-
       supplied  buffer  instead of possibly using a static data area that may
       be overwritten by each call.

RATIONALE

       None.

FUTURE DIRECTIONS

       None.

SEE ALSO

       getpwnam() , geteuid() , getuid() , getlogin() , the  Base  Definitions
       volume of IEEE Std 1003.1-2001, <limits.h>, <pwd.h>, <sys/types.h>

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .