Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
GETLOGIN(2)		  FreeBSD System Calls Manual		   GETLOGIN(2)

     getlogin, getlogin_r, setlogin -- get/set login name

     #include <unistd.h>

     char *

     getlogin_r(char *name, size_t namelen);

     setlogin(const char *name);

     The getlogin() routine returns the	login name of the user associated with
     the current session, as previously	set by setlogin().  The	name is	nor-
     mally associated with a login shell at the	time a session is created, and
     is	inherited by all processes descended from the login shell.  (This is
     true even if some of those	processes assume another user ID, for example
     when su(1)	is used.)

     The getlogin_r() routine is a reentrant version of	getlogin().  It	is
     functionally identical to getlogin() except that the caller must provide
     a buffer, name, in	which to store the user's login	name and a correspond-
     ing length	parameter, namelen, that specifies the size of the buffer.
     The buffer	should be large	enough to store	the login name and a trailing
     NUL (typically LOGIN_NAME_MAX bytes).

     setlogin()	sets the login name of the user	associated with	the current
     session to	name.  This call is restricted to the superuser, and is	nor-
     mally used	only when a new	session	is being created on behalf of the
     named user	(for example, at login time, or	when a remote shell is in-

     NOTE: There is only one login name	per session.

     It	is CRITICALLY important	to ensure that setlogin() is only ever called
     after the process has taken adequate steps	to ensure that it is detached
     from its parent's session.	 The ONLY way to do this is via	the setsid()
     function.	The daemon() function calls setsid() which is an ideal way of
     detaching from a controlling terminal and forking into the	background.

     In	particular, neither ioctl(ttyfd, TIOCNOTTY, ...) nor setpgrp(...) is
     sufficient	to create a new	session.

     Once a parent process has called setsid(),	it is acceptable for some
     child of that process to then call	setlogin(), even though	it is not the
     session leader.  Beware, however, that ALL	processes in the session will
     change their login	name at	the same time, even the	parent.

     This is different from traditional	UNIX privilege inheritance and as such
     can be counter-intuitive.

     Since the setlogin() routine is restricted	to the super-user, it is as-
     sumed that	(like all other	privileged programs) the programmer has	taken
     adequate precautions to prevent security violations.

     If	a call to getlogin() succeeds, it returns a pointer to a NUL-termi-
     nated string in a static buffer.  If the name has not been	set, it	re-
     turns NULL.  If a call to getlogin_r() succeeds, a	value of 0 is re-
     turned, else the error number is returned.	 If a call to setlogin() suc-
     ceeds, a value of 0 is returned.  If setlogin() fails, a value of -1 is
     returned and an error code	is placed in the global	location errno.

     getlogin_r() and setlogin() will succeed unless:

     [EFAULT]		The name parameter points to an	invalid	address.

     In	addition, getlogin_r() may return the following	error:

     [ERANGE]		The value of namelen is	not large enough to store the
			user's login name and a	trailing NUL.

     setlogin()	may return the following errors:

     [EINVAL]		The name parameter pointed to a	string that was	too
			long.  Login names are limited to LOGIN_NAME_MAX-1
			characters, currently 31.

     [EPERM]		The caller tried to set	the login name and was not the


     The getlogin() and	getlogin_r() functions conform to IEEE Std 1003.1-2008

     A getlogin() function which used utmp(5) first appeared in	Version	7 AT&T
     UNIX.  The	getlogin() and setlogin() system calls first appeared in

     In	earlier	versions of the	system,	getlogin() failed unless the process
     was associated with a login terminal.  The	current	implementation (using
     setlogin()) allows	getlogin to succeed even when the process has no con-
     trolling terminal.	 In earlier versions of	the system, the	value returned
     by	getlogin() could not be	trusted	without	checking the user ID.  Porta-
     ble programs should probably still	make this check.

FreeBSD	13.0		       February	9, 2020			  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help