1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)getlogin.2 8.1 (Berkeley) 6/9/93 29.\" $FreeBSD$ 30.\" 31.Dd September 9, 2020 32.Dt GETLOGIN 2 33.Os 34.Sh NAME 35.Nm getlogin , 36.Nm getlogin_r , 37.Nm setlogin 38.Nd get/set login name 39.Sh LIBRARY 40.Lb libc 41.Sh SYNOPSIS 42.In unistd.h 43.Ft char * 44.Fn getlogin void 45.In sys/param.h 46.Ft int 47.Fn getlogin_r "char *name" "size_t len" 48.Ft int 49.Fn setlogin "const char *name" 50.Sh DESCRIPTION 51The 52.Fn getlogin 53routine 54returns the login name of the user associated with the current session, 55as previously set by 56.Fn setlogin . 57The name is normally associated with a login shell 58at the time a session is created, 59and is inherited by all processes descended from the login shell. 60(This is true even if some of those processes assume another user ID, 61for example when 62.Xr su 1 63is used). 64.Pp 65The 66.Fn getlogin_r 67function 68provides the same service as 69.Fn getlogin 70except the caller must provide the buffer 71.Fa name 72with length 73.Fa len 74bytes 75to hold the result. 76The buffer should be at least 77.Dv MAXLOGNAME 78bytes in length. 79.Pp 80The 81.Fn setlogin 82system call 83sets the login name of the user associated with the current session to 84.Fa name . 85This system call is restricted to the super-user, and 86is normally used only when a new session is being created on behalf 87of the named user 88(for example, at login time, or when a remote shell is invoked). 89.Pp 90.Em NOTE : 91There is only one login name per session. 92.Pp 93It is 94.Em CRITICALLY 95important to ensure that 96.Fn setlogin 97is only ever called after the process has taken adequate steps to ensure 98that it is detached from its parent's session. 99Making a 100.Fn setsid 101system call is the 102.Em ONLY 103way to do this. 104The 105.Xr daemon 3 106function calls 107.Fn setsid 108which is an ideal way of detaching from a controlling terminal and 109forking into the background. 110.Pp 111In particular, doing a 112.Fn ioctl ttyfd TIOCNOTTY ...\& 113or 114.Fn setpgrp ...\& 115is 116.Em NOT 117sufficient. 118.Pp 119Once a parent process does a 120.Fn setsid 121system call, it is acceptable for some child of that process to then do a 122.Fn setlogin 123even though it is not the session leader, but beware that ALL processes 124in the session will change their login name at the same time, even the 125parent. 126.Pp 127This is not the same as the traditional UNIX behavior of inheriting privilege. 128.Pp 129Since the 130.Fn setlogin 131system call is restricted to the super-user, it is assumed that (like 132all other privileged programs) the programmer has taken adequate 133precautions to prevent security violations. 134.Sh RETURN VALUES 135If a call to 136.Fn getlogin 137succeeds, it returns a pointer to a null-terminated string in a static buffer, 138or 139.Dv NULL 140if the name has not been set. 141The 142.Fn getlogin_r 143function 144returns zero if successful, or the error number upon failure. 145.Pp 146.Rv -std setlogin 147.Sh ERRORS 148The following errors may be returned by these calls: 149.Bl -tag -width Er 150.It Bq Er EFAULT 151The 152.Fa name 153argument gave an 154invalid address. 155.It Bq Er EINVAL 156The 157.Fa name 158argument 159pointed to a string that was too long. 160Login names are limited to 161.Dv MAXLOGNAME 162(from 163.In sys/param.h ) 164characters, currently 33 including null. 165.It Bq Er EPERM 166The caller tried to set the login name and was not the super-user. 167.It Bq Er ERANGE 168The size of the buffer is smaller than the result to be returned. 169.El 170.Sh SEE ALSO 171.Xr setsid 2 , 172.Xr daemon 3 173.Sh STANDARDS 174The 175.Fn getlogin 176system call 177and 178the 179.Fn getlogin_r 180function 181conform to 182.St -p1003.1-96 . 183.Sh HISTORY 184The 185.Fn getlogin 186system call first appeared in 187.Bx 4.4 . 188The return value of 189.Fn getlogin_r 190was changed from earlier versions of 191.Fx 192to be conformant with 193.St -p1003.1-96 . 194.Sh BUGS 195In earlier versions of the system, 196.Fn getlogin 197failed unless the process was associated with a login terminal. 198The current implementation (using 199.Fn setlogin ) 200allows getlogin to succeed even when the process has no controlling terminal. 201In earlier versions of the system, the value returned by 202.Fn getlogin 203could not be trusted without checking the user ID. 204Portable programs should probably still make this check. 205