getlogin(3p)

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

NAME

6       getlogin, getlogin_r - get login name
7

SYNOPSIS

9       #include <unistd.h>
10
11       char *getlogin(void);
12
13
14       int getlogin_r(char *name, size_t namesize);
15
16

DESCRIPTION

18       The  getlogin()  function shall return a pointer to a string containing
19       the user name associated by the login  activity  with  the  controlling
20       terminal  of  the  current  process.  If  getlogin() returns a non-null
21       pointer, then that pointer points to the name that the user  logged  in
22       under, even if there are several login names with the same user ID.
23
24       The  getlogin()  function need not be reentrant. A function that is not
25       required to be reentrant is not required to be thread-safe.
26
27       The getlogin_r() function shall put the name associated  by  the  login
28       activity  with  the  controlling terminal of the current process in the
29       character array pointed to by name. The array  is  namesize  characters
30       long  and should have space for the name and the terminating null char‐
31       acter. The maximum size of the login name is {LOGIN_NAME_MAX}.
32
33       If getlogin_r() is successful, name points to the name the user used at
34       login, even if there are several login names with the same user ID.
35

RETURN VALUE

37       Upon  successful  completion,  getlogin() shall return a pointer to the
38       login name or a null pointer if the user's login name cannot be  found.
39       Otherwise, it shall return a null pointer and set errno to indicate the
40       error.
41
42       The return value from getlogin() may point to static data whose content
43       is overwritten by each call.
44
45       If  successful, the getlogin_r() function shall return zero; otherwise,
46       an error number shall be returned to indicate the error.
47

ERRORS

49       The getlogin() and getlogin_r() functions may fail if:
50
51       EMFILE {OPEN_MAX} file descriptors are currently open  in  the  calling
52              process.
53
54       ENFILE The  maximum  allowable number of files is currently open in the
55              system.
56
57       ENXIO  The calling process has no controlling terminal.
58
59
60       The getlogin_r() function may fail if:
61
62       ERANGE The value of namesize is smaller than the length of  the  string
63              to be returned including the terminating null character.
64
65
66       The following sections are informative.
67

EXAMPLES

69   Getting the User Login Name
70       The  following example calls the getlogin() function to obtain the name
71       of the user associated with the calling process, and passes this infor‐
72       mation  to  the getpwnam() function to get the associated user database
73       information.
74
75
76              #include <unistd.h>
77              #include <sys/types.h>
78              #include <pwd.h>
79              #include <stdio.h>
80              ...
81              char *lgn;
82              struct passwd *pw;
83              ...
84              if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) {
85                  fprintf(stderr, "Get of user information failed.\n"); exit(1);
86                  }
87

APPLICATION USAGE

89       Three names associated with the current process can be determined: get‐
90       pwuid(  geteuid())  shall return the name associated with the effective
91       user ID of the process; getlogin() shall  return  the  name  associated
92       with  the  current login activity; and getpwuid( getuid()) shall return
93       the name associated with the real user ID of the process.
94
95       The getlogin_r() function is thread-safe and returns values in a  user-
96       supplied  buffer  instead of possibly using a static data area that may
97       be overwritten by each call.
98

RATIONALE

100       The getlogin() function returns a pointer to the user's login name. The
101       same  user ID may be shared by several login names. If it is desired to
102       get the user database entry that is used during login,  the  result  of
103       getlogin()  should  be  used  to provide the argument to the getpwnam()
104       function. (This might be used to determine the user's login shell, par‐
105       ticularly  where  a single user has multiple login shells with distinct
106       login names, but the same user ID.)
107
108       The information provided by the cuserid() function,  which  was  origi‐
109       nally  defined  in  the POSIX.1-1988 standard and subsequently removed,
110       can be obtained by the following:
111
112
113              getpwuid(geteuid())
114
115       while  the  information  provided  by  historical  implementations   of
116       cuserid() can be obtained by:
117
118
119              getpwuid(getuid())
120
121       The  thread-safe  version  of  this  function places the user name in a
122       user-supplied buffer and returns a non-zero value if it fails. The non-
123       thread-safe  version may return the name in a static data area that may
124       be overwritten by each call.
125

FUTURE DIRECTIONS

127       None.
128

COPYRIGHT

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