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