1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
|
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
.TH "GETLOGIN" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" getlogin
.SH NAME
getlogin, getlogin_r \- get login name
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
char *getlogin(void);
.br
\fP
.LP
\fBint getlogin_r(char *\fP\fIname\fP\fB, size_t\fP \fInamesize\fP\fB);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIgetlogin\fP() function shall return a pointer to a string containing
the user name associated by the login activity with
the controlling terminal of the current process. If \fIgetlogin\fP()
returns a non-null pointer, then that pointer points to the
name that the user logged in under, even if there are several login
names with the same user ID.
.LP
The \fIgetlogin\fP() function need not be reentrant. A function that
is not required to be reentrant is not required to be
thread-safe.
.LP
The \fIgetlogin_r\fP() function shall put the name associated by the
login activity with the controlling terminal of the current
process in the character array pointed to by \fIname\fP. The array
is \fInamesize\fP characters long and should have space for
the name and the terminating null character. The maximum size of the
login name is {LOGIN_NAME_MAX}.
.LP
If \fIgetlogin_r\fP() is successful, \fIname\fP points to the name
the user used at login, even if there are several login
names with the same user ID.
.SH RETURN VALUE
.LP
Upon successful completion, \fIgetlogin\fP() shall return a pointer
to the login name or a null pointer if the user's login
name cannot be found. Otherwise, it shall return a null pointer and
set \fIerrno\fP to indicate the error.
.LP
The return value from \fIgetlogin\fP() may point to static data whose
content is overwritten by each call.
.LP
If successful, the \fIgetlogin_r\fP() function shall return zero;
otherwise, an error number shall be returned to indicate the
error.
.SH ERRORS
.LP
The \fIgetlogin\fP() and \fIgetlogin_r\fP() functions may fail if:
.TP 7
.B EMFILE
{OPEN_MAX} file descriptors are currently open in the calling process.
.TP 7
.B ENFILE
The maximum allowable number of files is currently open in the system.
.TP 7
.B ENXIO
The calling process has no controlling terminal.
.sp
.LP
The \fIgetlogin_r\fP() function may fail if:
.TP 7
.B ERANGE
The value of \fInamesize\fP is smaller than the length of the string
to be returned including the terminating null character.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.SS Getting the User Login Name
.LP
The following example calls the \fIgetlogin\fP() function to obtain
the name of the user associated with the calling process,
and passes this information to the \fIgetpwnam\fP() function to get
the associated user
database information.
.sp
.RS
.nf
\fB#include <unistd.h>
#include <sys/types.h>
#include <pwd.h>
#include <stdio.h>
\&...
char *lgn;
struct passwd *pw;
\&...
if ((lgn = getlogin()) == NULL || (pw = getpwnam(lgn)) == NULL) {
fprintf(stderr, "Get of user information failed.\\n"); exit(1);
}
\fP
.fi
.RE
.SH APPLICATION USAGE
.LP
Three names associated with the current process can be determined:
\fIgetpwuid\fP( \fIgeteuid\fP()) shall return the name associated
with the effective user ID of the process;
\fIgetlogin\fP() shall return the name associated with the current
login activity; and \fIgetpwuid\fP( \fIgetuid\fP()) shall return the
name associated with the real user ID of the process.
.LP
The \fIgetlogin_r\fP() 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.
.SH RATIONALE
.LP
The \fIgetlogin\fP() function returns a pointer to the user's login
name. The same user ID may be shared by several login
names. If it is desired to get the user database entry that is used
during login, the result of \fIgetlogin\fP() should be used to
provide the argument to the \fIgetpwnam\fP() function. (This might
be used to determine
the user's login shell, particularly where a single user has multiple
login shells with distinct login names, but the same user
ID.)
.LP
The information provided by the \fIcuserid\fP() function, which was
originally defined in the POSIX.1-1988 standard and
subsequently removed, can be obtained by the following:
.sp
.RS
.nf
\fBgetpwuid(geteuid())
\fP
.fi
.RE
.LP
while the information provided by historical implementations of \fIcuserid\fP()
can be obtained by:
.sp
.RS
.nf
\fBgetpwuid(getuid())
\fP
.fi
.RE
.LP
The thread-safe version of this function places the user name in a
user-supplied buffer and returns a non-zero value if it
fails. The non-thread-safe version may return the name in a static
data area that may be overwritten by each call.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIgetpwnam\fP() , \fIgetpwuid\fP() , \fIgeteuid\fP() , \fIgetuid\fP()
, the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<limits.h>\fP, \fI<unistd.h>\fP
.SH 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 .
|
