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