1GETPWNAM(P)                POSIX Programmer's Manual               GETPWNAM(P)
2
3
4

NAME

6       getpwnam, getpwnam_r - search user database for a name
7

SYNOPSIS

9       #include <pwd.h>
10
11       struct passwd *getpwnam(const char *name);
12
13
14       int getpwnam_r(const char *name, struct passwd *pwd, char *buffer,
15              size_t bufsize, struct passwd **result);
16
17

DESCRIPTION

19       The  getpwnam()  function  shall  search the user database for an entry
20       with a matching name.
21
22       The getpwnam() function need not be reentrant. A function that  is  not
23       required to be reentrant is not required to be thread-safe.
24
25       Applications  wishing to check for error situations should set errno to
26       0 before calling getpwnam(). If getpwnam() returns a null  pointer  and
27       errno is non-zero, an error occurred.
28
29       The  getpwnam_r() function shall update the passwd structure pointed to
30       by pwd and store a pointer to that structure at the location pointed to
31       by  result. The structure shall contain an entry from the user database
32       with a matching name. Storage referenced by the structure is  allocated
33       from  the  memory  provided with the buffer parameter, which is bufsize
34       bytes in size. The maximum size needed for this buffer  can  be  deter‐
35       mined  with  the  {_SC_GETPW_R_SIZE_MAX}  sysconf()  parameter.  A NULL
36       pointer shall be returned at the location pointed to by result on error
37       or if the requested entry is not found.
38

RETURN VALUE

40       The  getpwnam() function shall return a pointer to a struct passwd with
41       the structure as defined in <pwd.h> with a matching entry if  found.  A
42       null  pointer shall be returned if the requested entry is not found, or
43       an error occurs. On error, errno shall be set to indicate the error.
44
45       The return value may point to a static area which is overwritten  by  a
46       subsequent call to getpwent(), getpwnam(), or getpwuid().
47
48       If  successful, the getpwnam_r() function shall return zero; otherwise,
49       an error number shall be returned to indicate the error.
50

ERRORS

52       The getpwnam() and getpwnam_r() functions may fail if:
53
54       EIO    An I/O error has occurred.
55
56       EINTR  A signal was caught during getpwnam().
57
58       EMFILE {OPEN_MAX} file descriptors are currently open  in  the  calling
59              process.
60
61       ENFILE The  maximum  allowable number of files is currently open in the
62              system.
63
64
65       The getpwnam_r() function may fail if:
66
67       ERANGE Insufficient storage was supplied via buffer and bufsize to con‐
68              tain  the  data  to be referenced by the resulting passwd struc‐
69              ture.
70
71
72       The following sections are informative.
73

EXAMPLES

75   Getting an Entry for the Login Name
76       The following example uses the getlogin() function to return  the  name
77       of the user who logged in; this information is passed to the getpwnam()
78       function to get the user database entry for that user.
79
80
81              #include <sys/types.h>
82              #include <pwd.h>
83              #include <unistd.h>
84              #include <stdio.h>
85              #include <stdlib.h>
86              ...
87              char *lgn;
88              struct passwd *pw;
89              ...
90              if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) {
91                  fprintf(stderr, "Get of user information failed.\n"); exit(1);
92              }
93              ...
94

APPLICATION USAGE

96       Three names associated with the current process can be determined: get‐
97       pwuid(  geteuid())  returns the name associated with the effective user
98       ID of the process; getlogin() returns the name associated with the cur‐
99       rent  login  activity; and getpwuid( getuid()) returns the name associ‐
100       ated with the real user ID of the process.
101
102       The getpwnam_r() function is thread-safe and returns values in a  user-
103       supplied  buffer  instead of possibly using a static data area that may
104       be overwritten by each call.
105

RATIONALE

107       None.
108

FUTURE DIRECTIONS

110       None.
111

SEE ALSO

113       getpwuid() , the Base Definitions volume of IEEE Std 1003.1-2001, <lim‐
114       its.h>, <pwd.h>, <sys/types.h>
115

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