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: src/lib/libc/sys/getlogin.2,v 1.14.2.6 2001/12/14 18:34:00 ru Exp $ 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 69.Fn getlogin_r 70provides the same service as 71.Fn getlogin 72except the caller must provide the buffer 73.Fa name 74with length 75.Fa len 76bytes 77to hold the result. The buffer should be at least 78.Dv MAXLOGNAME 79bytes in length. 80.Pp 81.Fn Setlogin 82sets the login name of the user associated with the current session to 83.Fa name . 84This call is restricted to the super-user, and 85is normally used only when a new session is being created on behalf 86of the named user 87(for example, at login time, or when a remote shell is invoked). 88.Pp 89.Em NOTE : 90There is only one login name per session. 91.Pp 92It is 93.Em CRITICALLY 94important to ensure that 95.Fn setlogin 96is only ever called after the process has taken adequate steps to ensure 97that it is detached from its parent's session. 98Making a 99.Fn setsid 100system call is the 101.Em ONLY 102way to do this. The 103.Fn daemon 104library call calls 105.Fn setsid 106which is an ideal way of detaching from a controlling terminal and 107forking into the background. 108.Pp 109In particular, doing a 110.Fn ioctl ttyfd TIOCNOTTY ...\& 111or 112.Fn setpgrp ...\& 113is 114.Em NOT 115sufficient. 116.Pp 117Once a parent process does a 118.Fn setsid 119call, it is acceptable for some child of that process to then do a 120.Fn setlogin 121even though it is not the session leader, but beware that ALL processes 122in the session will change their login name at the same time, even the 123parent. 124.Pp 125This is not the same as the traditional UNIX behavior of inheriting privilege. 126.Pp 127Since the 128.Fn setlogin 129system call is restricted to the super-user, it is assumed that (like 130all other privileged programs) the programmer has taken adequate 131precautions to prevent security violations. 132.Sh RETURN VALUES 133If a call to 134.Fn getlogin 135succeeds, it returns a pointer to a null-terminated string in a static buffer, 136or 137.Dv NULL 138if the name has not been set. 139.Fn getlogin_r 140returns zero if successful, or the error number upon failure. 141.Pp 142.Rv -std setlogin 143.Sh ERRORS 144The following errors may be returned by these calls: 145.Bl -tag -width Er 146.It Bq Er EFAULT 147The 148.Fa name 149parameter gave an 150invalid address. 151.It Bq Er EINVAL 152The 153.Fa name 154parameter 155pointed to a string that was too long. 156Login names are limited to 157.Dv MAXLOGNAME 158(from 159.Ao Pa sys/param.h Ac ) 160characters, currently 17 including null. 161.It Bq Er EPERM 162The caller tried to set the login name and was not the super-user. 163.It Bq Er ERANGE 164The size of the buffer is smaller than the result to be returned. 165.El 166.Sh SEE ALSO 167.Xr setsid 2 , 168.Xr daemon 3 169.Sh BUGS 170In earlier versions of the system, 171.Fn getlogin 172failed unless the process was associated with a login terminal. 173The current implementation (using 174.Fn setlogin ) 175allows getlogin to succeed even when the process has no controlling terminal. 176In earlier versions of the system, the value returned by 177.Fn getlogin 178could not be trusted without checking the user ID. 179Portable programs should probably still make this check. 180.Sh HISTORY 181The 182.Fn getlogin 183function first appeared in 184.Bx 4.4 . 185The return value of 186.Fn getlogin_r 187was changed from earlier versions of 188.Fx 189to be conformant with 190.St -p1003.1-96 . 191.Sh STANDARDS 192.Fn getlogin 193and 194.Fn getlogin_r 195conform to 196.St -p1003.1-96 . 197