1.\" $NetBSD: getlogin.2,v 1.12 2002/02/08 01:28:17 ross Exp $ 2.\" 3.\" Copyright (c) 1989, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)getlogin.2 8.1 (Berkeley) 6/9/93 35.\" 36.Dd June 9, 1993 37.Dt GETLOGIN 2 38.Os 39.Sh NAME 40.Nm getlogin , 41.Nm setlogin 42.Nd get/set login name 43.Sh LIBRARY 44.Lb libc 45.Sh SYNOPSIS 46.Fd #include \*[Lt]unistd.h\*[Gt] 47.Ft char * 48.Fn getlogin void 49.Ft int 50.Fn setlogin "const char *name" 51.Sh DESCRIPTION 52The 53.Fn getlogin 54routine 55returns the login name of the user associated with the current session, 56as previously set by 57.Fn setlogin . 58The name is normally associated with a login shell 59at the time a session is created, 60and is inherited by all processes descended from the login shell. 61(This is true even if some of those processes assume another user ID, 62for example when 63.Xr su 1 64is used.) 65.Pp 66.Fn setlogin 67sets the login name of the user associated with the current session to 68.Fa name . 69This call is restricted to the super-user, and 70is normally used only when a new session is being created on behalf 71of the named user 72(for example, at login time, or when a remote shell is invoked). 73.Sh RETURN VALUES 74If a call to 75.Fn getlogin 76succeeds, it returns a pointer to a null-terminated string in a static buffer. 77If the name has not been set, it returns 78.Dv NULL . 79If a call to 80.Fn setlogin 81succeeds, a value of 0 is returned. If 82.Fn setlogin 83fails, a value of -1 is returned and an error code is 84placed in the global location 85.Va errno . 86.Sh ERRORS 87The following errors may be returned by these calls: 88.Bl -tag -width Er 89.It Bq Er EFAULT 90The 91.Fa name 92parameter gave an 93invalid address. 94.It Bq Er EINVAL 95The 96.Fa name 97parameter 98pointed to a string that was too long. 99Login names are limited to 100.Dv MAXLOGNAME 101(from 102.Ao Pa sys/param.h Ac ) 103characters, currently 16. 104.It Bq Er EPERM 105The caller tried to set the login name and was not the super-user. 106.El 107.Sh SEE ALSO 108.Xr setsid 2 109.Sh STANDARDS 110The 111.Fn getlogin 112function conforms to 113.St -p1003.1-90 . 114.Sh HISTORY 115The 116.Fn getlogin 117function first appeared in 118.Bx 4.4 . 119.Sh BUGS 120Login names are limited in length by 121.Fn setlogin . 122However, lower limits are placed on login names elsewhere in the system 123.Pf ( Dv UT_NAMESIZE 124in 125.Ao Pa utmp.h Ac ) . 126.Pp 127In earlier versions of the system, 128.Fn getlogin 129failed unless the process was associated with a login terminal. 130The current implementation (using 131.Fn setlogin ) 132allows getlogin to succeed even when the process has no controlling terminal. 133In earlier versions of the system, the value returned by 134.Fn getlogin 135could not be trusted without checking the user ID. 136Portable programs should probably still make this check. 137