]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/getlogin.2
xnu-7195.101.1.tar.gz
[apple/xnu.git] / bsd / man / man2 / getlogin.2
CommitLineData
9bccf70c
A
1.\" $NetBSD: getlogin.2,v 1.4 1995/02/27 12:33:03 cgd 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 BSD 4.2
39.Sh NAME
40.Nm getlogin ,
41.Nm setlogin
42.Nd get/set login name
43.Sh SYNOPSIS
44.Fd #include <unistd.h>
45.Ft char *
2d21ac55
A
46.Fo getlogin
47.Fa void
48.Fc
9bccf70c 49.Ft int
2d21ac55
A
50.Fo setlogin
51.Fa "const char *name"
52.Fc
9bccf70c
A
53.Sh DESCRIPTION
54The
55.Fn getlogin
56routine
57returns the login name of the user associated with the current session,
58as previously set by
59.Fn setlogin .
60The name is normally associated with a login shell
61at the time a session is created,
62and is inherited by all processes descended from the login shell.
63(This is true even if some of those processes assume another user ID,
64for example when
65.Xr su 1
66is used.)
67.Pp
39037602 68.Fn setlogin
9bccf70c
A
69sets the login name of the user associated with the current session to
70.Fa name .
71This call is restricted to the super-user, and
72is normally used only when a new session is being created on behalf
73of the named user
74(for example, at login time, or when a remote shell is invoked).
75.Sh RETURN VALUES
76If a call to
77.Fn getlogin
78succeeds, it returns a pointer to a null-terminated string in a static buffer.
79If the name has not been set, it returns
80.Dv NULL .
81If a call to
82.Fn setlogin
83succeeds, a value of 0 is returned. If
84.Fn setlogin
85fails, a value of -1 is returned and an error code is
86placed in the global location
87.Va errno .
88.Sh ERRORS
89The following errors may be returned by these calls:
90.Bl -tag -width Er
91.It Bq Er EFAULT
92The
93.Fa name
94parameter gave an
95invalid address.
96.It Bq Er EINVAL
97The
98.Fa name
99parameter
100pointed to a string that was too long.
101Login names are limited to
102.Dv MAXLOGNAME
103(from
104.Ao Pa sys/param.h Ac )
105characters, currently 12.
106.It Bq Er EPERM
107The caller tried to set the login name and was not the super-user.
108.El
109.Sh SEE ALSO
110.Xr setsid 2
111.Sh BUGS
112Login names are limited in length by
113.Fn setlogin .
114However, lower limits are placed on login names elsewhere in the system
115.Pf ( Dv UT_NAMESIZE
116in
117.Ao Pa utmp.h Ac ) .
118.Pp
119In earlier versions of the system,
120.Fn getlogin
121failed unless the process was associated with a login terminal.
122The current implementation (using
123.Fn setlogin )
124allows getlogin to succeed even when the process has no controlling terminal.
125In earlier versions of the system, the value returned by
126.Fn getlogin
127could not be trusted without checking the user ID.
128Portable programs should probably still make this check.
129.Sh HISTORY
130The
131.Fn getlogin
132function first appeared in 4.4BSD.