[thirdparty/man-pages.git] / man3 / getlogin.3

.\" Copyright 1995  James R. Van Zandt <jrv@vanzandt.mv.com>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3
.\"  added ref to /etc/utmp, added BUGS section, etc.
.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use
.TH GETLOGIN 3 2017-09-15 "GNU" "Linux Programmer's Manual"
.SH NAME
getlogin, getlogin_r, cuserid \- get username
.SH SYNOPSIS
.B #include <unistd.h>
.PP
.B "char *getlogin(void);"
.br
.BI "int getlogin_r(char *" buf ", size_t " bufsize );
.PP
.B #include <stdio.h>
.PP
.BI "char *cuserid(char *" string );
.PP
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.PP
.BR getlogin_r ():
.\" Deprecated: _REENTRANT ||
_POSIX_C_SOURCE\ >=\ 199506L
.PP
.BR cuserid ():
.nf
    Since glibc 2.24:
        (_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
        || _GNU_SOURCE
    Up to and including glibc 2.23:
        _XOPEN_SOURCE
.fi
.SH DESCRIPTION
.BR getlogin ()
returns a pointer to a string containing the name of
the user logged in on the controlling terminal of the process, or a
null pointer if this information cannot be determined.
The string is
statically allocated and might be overwritten on subsequent calls to
this function or to
.BR cuserid ().
.PP
.BR getlogin_r ()
returns this same username in the array
.I buf
of size
.IR bufsize .
.PP
.BR cuserid ()
returns a pointer to a string containing a username
associated with the effective user ID of the process.
If \fIstring\fP
is not a null pointer, it should be an array that can hold at least
\fBL_cuserid\fP characters; the string is returned in this array.
Otherwise, a pointer to a string in a static area is returned.
This
string is statically allocated and might be overwritten on subsequent
calls to this function or to
.BR getlogin ().
.PP
The macro \fBL_cuserid\fP is an integer constant that indicates how
long an array you might need to store a username.
\fBL_cuserid\fP is declared in \fI<stdio.h>\fP.
.PP
These functions let your program identify positively the user who is
running
.RB ( cuserid ())
or the user who logged in this session
.RB ( getlogin ()).
(These can differ when set-user-ID programs are involved.)
.PP
For most purposes, it is more useful to use the environment variable
\fBLOGNAME\fP to find out who the user is.
This is more flexible
precisely because the user can set \fBLOGNAME\fP arbitrarily.
.SH RETURN VALUE
.BR getlogin ()
returns a pointer to the username when successful,
and NULL on failure, with
.I errno
set to indicate the cause of the error.
.BR getlogin_r ()
returns 0 when successful, and nonzero on failure.
.SH ERRORS
POSIX specifies
.TP
.B EMFILE
The per-process limit on the number of open file descriptors has been reached.
.TP
.B ENFILE
The system-wide limit on the total number of open files has been reached.
.TP
.B ENXIO
The calling process has no controlling terminal.
.TP
.B ERANGE
(getlogin_r)
The length of the username, including the terminating null byte (\(aq\\0\(aq),
is larger than
.IR bufsize .
.PP
Linux/glibc also has
.TP
.B ENOENT
There was no corresponding entry in the utmp-file.
.TP
.B ENOMEM
Insufficient memory to allocate passwd structure.
.TP
.B ENOTTY
Standard input didn't refer to a terminal.
(See BUGS.)
.SH FILES
.TP
\fI/etc/passwd\fP
password database file
.TP
\fI/var/run/utmp\fP
(traditionally \fI/etc/utmp\fP;
some libc versions used \fI/var/adm/utmp\fP)
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lb lb lb
l l l.
Interface	Attribute	Value
T{
.BR getlogin ()
T}	Thread safety	T{
MT-Unsafe race:getlogin race:utent
.br
sig:ALRM timer locale
T}
T{
.BR getlogin_r ()
T}	Thread safety	T{
MT-Unsafe race:utent sig:ALRM timer
.br
locale
T}
T{
.BR cuserid ()
T}	Thread safety	MT-Unsafe race:cuserid/!string locale
.TE
.sp 1
In the above table,
.I utent
in
.I race:utent
signifies that if any of the functions
.BR setutent (3),
.BR getutent (3),
or
.BR endutent (3)
are used in parallel in different threads of a program,
then data races could occur.
.BR getlogin ()
and
.BR getlogin_r ()
call those functions,
so we use race:utent to remind users.
.SH CONFORMING TO
.BR getlogin ()
and
.BR getlogin_r ():
POSIX.1-2001, POSIX.1-2008.
.PP
System V has a
.BR cuserid ()
function which uses the real
user ID rather than the effective user ID.
The
.BR cuserid ()
function
was included in the 1988 version of POSIX,
but removed from the 1990 version.
It was present in SUSv2, but removed in POSIX.1-2001.
.PP
OpenBSD has
.BR getlogin ()
and
.BR setlogin (),
and a username
associated with a session, even if it has no controlling terminal.
.SH BUGS
Unfortunately, it is often rather easy to fool
.BR getlogin ().
Sometimes it does not work at all, because some program messed up
the utmp file.
Often, it gives only the first 8 characters of
the login name.
The user currently logged in on the controlling terminal
of our program need not be the user who started it.
Avoid
.BR getlogin ()
for security-related purposes.
.PP
Note that glibc does not follow the POSIX specification and uses
.I stdin
instead of
.IR /dev/tty .
A bug.
(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
all return the login name also when
.I stdin
is redirected.)
.PP
Nobody knows precisely what
.BR cuserid ()
does; avoid it in portable programs.
Or avoid it altogether: use
.I getpwuid(geteuid())
instead, if that is
what you meant.
.B Do not use
.BR cuserid ().
.SH SEE ALSO
.BR logname (1),
.BR geteuid (2),
.BR getuid (2),
.BR utmp (5)
Commit	Line	Data
	1	.\" Copyright 1995 James R. Van Zandt <jrv@vanzandt.mv.com>
	2	.\"
	3	.\" %%%LICENSE_START(VERBATIM)
	4	.\" Permission is granted to make and distribute verbatim copies of this
	5	.\" manual provided the copyright notice and this permission notice are
	6	.\" preserved on all copies.
	7	.\"
	8	.\" Permission is granted to copy and distribute modified versions of this
	9	.\" manual under the conditions for verbatim copying, provided that the
	10	.\" entire resulting derived work is distributed under the terms of a
	11	.\" permission notice identical to this one.
	12	.\"
	13	.\" Since the Linux kernel and libraries are constantly changing, this
	14	.\" manual page may be incorrect or out-of-date. The author(s) assume no
	15	.\" responsibility for errors or omissions, or for damages resulting from
	16	.\" the use of the information contained herein. The author(s) may not
	17	.\" have taken the same level of care in the production of this manual,
	18	.\" which is licensed free of charge, as they might when working
	19	.\" professionally.
	20	.\"
	21	.\" Formatted or processed versions of this manual, if unaccompanied by
	22	.\" the source, must acknowledge the copyright and authors of this work.
	23	.\" %%%LICENSE_END
	24	.\"
	25	.\" Changed Tue Sep 19 01:49:29 1995, aeb: moved from man2 to man3
	26	.\" added ref to /etc/utmp, added BUGS section, etc.
	27	.\" modified 2003 Walter Harms, aeb - added getlogin_r, note on stdin use
	28	.TH GETLOGIN 3 2017-09-15 "GNU" "Linux Programmer's Manual"
	29	.SH NAME
	30	getlogin, getlogin_r, cuserid \- get username
	31	.SH SYNOPSIS
	32	.B #include <unistd.h>
	33	.PP
	34	.B "char *getlogin(void);"
	35	.br
	36	.BI "int getlogin_r(char *" buf ", size_t " bufsize );
	37	.PP
	38	.B #include <stdio.h>
	39	.PP
	40	.BI "char cuserid(char " string );
	41	.PP
	42	.in -4n
	43	Feature Test Macro Requirements for glibc (see
	44	.BR feature_test_macros (7)):
	45	.in
	46	.PP
	47	.BR getlogin_r ():
	48	.\" Deprecated: _REENTRANT \|\|
	49	_POSIX_C_SOURCE\ >=\ 199506L
	50	.PP
	51	.BR cuserid ():
	52	.nf
	53	Since glibc 2.24:
	54	(_XOPEN_SOURCE && ! (_POSIX_C_SOURCE >= 200112L)
	55	\|\| _GNU_SOURCE
	56	Up to and including glibc 2.23:
	57	_XOPEN_SOURCE
	58	.fi
	59	.SH DESCRIPTION
	60	.BR getlogin ()
	61	returns a pointer to a string containing the name of
	62	the user logged in on the controlling terminal of the process, or a
	63	null pointer if this information cannot be determined.
	64	The string is
	65	statically allocated and might be overwritten on subsequent calls to
	66	this function or to
	67	.BR cuserid ().
	68	.PP
	69	.BR getlogin_r ()
	70	returns this same username in the array
	71	.I buf
	72	of size
	73	.IR bufsize .
	74	.PP
	75	.BR cuserid ()
	76	returns a pointer to a string containing a username
	77	associated with the effective user ID of the process.
	78	If \fIstring\fP
	79	is not a null pointer, it should be an array that can hold at least
	80	\fBL_cuserid\fP characters; the string is returned in this array.
	81	Otherwise, a pointer to a string in a static area is returned.
	82	This
	83	string is statically allocated and might be overwritten on subsequent
	84	calls to this function or to
	85	.BR getlogin ().
	86	.PP
	87	The macro \fBL_cuserid\fP is an integer constant that indicates how
	88	long an array you might need to store a username.
	89	\fBL_cuserid\fP is declared in \fI<stdio.h>\fP.
	90	.PP
	91	These functions let your program identify positively the user who is
	92	running
	93	.RB ( cuserid ())
	94	or the user who logged in this session
	95	.RB ( getlogin ()).
	96	(These can differ when set-user-ID programs are involved.)
	97	.PP
	98	For most purposes, it is more useful to use the environment variable
	99	\fBLOGNAME\fP to find out who the user is.
	100	This is more flexible
	101	precisely because the user can set \fBLOGNAME\fP arbitrarily.
	102	.SH RETURN VALUE
	103	.BR getlogin ()
	104	returns a pointer to the username when successful,
	105	and NULL on failure, with
	106	.I errno
	107	set to indicate the cause of the error.
	108	.BR getlogin_r ()
	109	returns 0 when successful, and nonzero on failure.
	110	.SH ERRORS
	111	POSIX specifies
	112	.TP
	113	.B EMFILE
	114	The per-process limit on the number of open file descriptors has been reached.
	115	.TP
	116	.B ENFILE
	117	The system-wide limit on the total number of open files has been reached.
	118	.TP
	119	.B ENXIO
	120	The calling process has no controlling terminal.
	121	.TP
	122	.B ERANGE
	123	(getlogin_r)
	124	The length of the username, including the terminating null byte (\(aq\\0\(aq),
	125	is larger than
	126	.IR bufsize .
	127	.PP
	128	Linux/glibc also has
	129	.TP
	130	.B ENOENT
	131	There was no corresponding entry in the utmp-file.
	132	.TP
	133	.B ENOMEM
	134	Insufficient memory to allocate passwd structure.
	135	.TP
	136	.B ENOTTY
	137	Standard input didn't refer to a terminal.
	138	(See BUGS.)
	139	.SH FILES
	140	.TP
	141	\fI/etc/passwd\fP
	142	password database file
	143	.TP
	144	\fI/var/run/utmp\fP
	145	(traditionally \fI/etc/utmp\fP;
	146	some libc versions used \fI/var/adm/utmp\fP)
	147	.SH ATTRIBUTES
	148	For an explanation of the terms used in this section, see
	149	.BR attributes (7).
	150	.TS
	151	allbox;
	152	lb lb lb
	153	l l l.
	154	Interface Attribute Value
	155	T{
	156	.BR getlogin ()
	157	T} Thread safety T{
	158	MT-Unsafe race:getlogin race:utent
	159	.br
	160	sig:ALRM timer locale
	161	T}
	162	T{
	163	.BR getlogin_r ()
	164	T} Thread safety T{
	165	MT-Unsafe race:utent sig:ALRM timer
	166	.br
	167	locale
	168	T}
	169	T{
	170	.BR cuserid ()
	171	T} Thread safety MT-Unsafe race:cuserid/!string locale
	172	.TE
	173	.sp 1
	174	In the above table,
	175	.I utent
	176	in
	177	.I race:utent
	178	signifies that if any of the functions
	179	.BR setutent (3),
	180	.BR getutent (3),
	181	or
	182	.BR endutent (3)
	183	are used in parallel in different threads of a program,
	184	then data races could occur.
	185	.BR getlogin ()
	186	and
	187	.BR getlogin_r ()
	188	call those functions,
	189	so we use race:utent to remind users.
	190	.SH CONFORMING TO
	191	.BR getlogin ()
	192	and
	193	.BR getlogin_r ():
	194	POSIX.1-2001, POSIX.1-2008.
	195	.PP
	196	System V has a
	197	.BR cuserid ()
	198	function which uses the real
	199	user ID rather than the effective user ID.
	200	The
	201	.BR cuserid ()
	202	function
	203	was included in the 1988 version of POSIX,
	204	but removed from the 1990 version.
	205	It was present in SUSv2, but removed in POSIX.1-2001.
	206	.PP
	207	OpenBSD has
	208	.BR getlogin ()
	209	and
	210	.BR setlogin (),
	211	and a username
	212	associated with a session, even if it has no controlling terminal.
	213	.SH BUGS
	214	Unfortunately, it is often rather easy to fool
	215	.BR getlogin ().
	216	Sometimes it does not work at all, because some program messed up
	217	the utmp file.
	218	Often, it gives only the first 8 characters of
	219	the login name.
	220	The user currently logged in on the controlling terminal
	221	of our program need not be the user who started it.
	222	Avoid
	223	.BR getlogin ()
	224	for security-related purposes.
	225	.PP
	226	Note that glibc does not follow the POSIX specification and uses
	227	.I stdin
	228	instead of
	229	.IR /dev/tty .
	230	A bug.
	231	(Other recent systems, like SunOS 5.8 and HP-UX 11.11 and FreeBSD 4.8
	232	all return the login name also when
	233	.I stdin
	234	is redirected.)
	235	.PP
	236	Nobody knows precisely what
	237	.BR cuserid ()
	238	does; avoid it in portable programs.
	239	Or avoid it altogether: use
	240	.I getpwuid(geteuid())
	241	instead, if that is
	242	what you meant.
	243	.B Do not use
	244	.BR cuserid ().
	245	.SH SEE ALSO
	246	.BR logname (1),
	247	.BR geteuid (2),
	248	.BR getuid (2),
	249	.BR utmp (5)