Debian Codegraph @

upstream/debian-unstable/man3/login.3

raw
1 '\" t
2 .\" Copyright 2002, Martin Schulze <[email protected]>
3 .\" Copyright, Paul Thompson
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH login 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 login, logout \- write utmp and wtmp entries
11 .SH LIBRARY
12 System utilities library
13 .RI ( libutil ,\~ \-lutil )
14 .SH SYNOPSIS
15 .nf
16 .B #include <utmp.h>
17 .P
18 .BI "void login(const struct utmp *" ut );
19 .BI "int logout(const char *" ut_line );
20 .fi
21 .SH DESCRIPTION
22 The
23 .I utmp
24 file records who is currently using the system.
25 The
26 .I wtmp
27 file records all logins and logouts.
28 See
29 .BR utmp (5).
30 .P
31 The function
32 .BR login ()
33 takes the supplied
34 .IR "struct utmp" ,
35 .IR ut ,
36 and writes it to both the
37 .I utmp
38 and the
39 .I wtmp
40 file.
41 .P
42 The function
43 .BR logout ()
44 clears the entry in the
45 .I utmp
46 file again.
47 .SS GNU details
48 More precisely,
49 .BR login ()
50 takes the argument
51 .I ut
52 struct, fills the field
53 .I ut\->ut_type
54 (if there is such a field) with the value
55 .BR USER_PROCESS ,
56 and fills the field
57 .I ut\->ut_pid
58 (if there is such a field) with the process ID of the calling process.
59 Then it tries to fill the field
60 .IR ut\->ut_line .
61 It takes the first of
62 .IR stdin ,
63 .IR stdout ,
64 .I stderr
65 that is a terminal, and
66 stores the corresponding pathname minus a possible leading
67 .I /dev/
68 into this field, and then writes the struct to the
69 .I utmp
70 file.
71 On the other hand,
72 if no terminal name was found, this field is filled with "???"
73 and the struct is not written to the
74 .I utmp
75 file.
76 After this, the struct is written to the
77 .I wtmp
78 file.
79 .P
80 The
81 .BR logout ()
82 function searches the
83 .I utmp
84 file for an entry matching the
85 .I ut_line
86 argument.
87 If a record is found, it is updated by zeroing out the
88 .I ut_name
89 and
90 .I ut_host
91 fields, updating the
92 .I ut_tv
93 timestamp field and setting
94 .I ut_type
95 (if there is such a field) to
96 .BR DEAD_PROCESS .
97 .SH RETURN VALUE
98 The
99 .BR logout ()
100 function returns 1 if the entry was successfully written to the
101 database, or 0 if an error occurred.
102 .SH FILES
103 .TP
104 .I /var/run/utmp
105 user accounting database, configured through
106 .B _PATH_UTMP
107 in
108 .I <paths.h>
109 .TP
110 .I /var/log/wtmp
111 user accounting log file, configured through
112 .B _PATH_WTMP
113 in
114 .I <paths.h>
115 .SH ATTRIBUTES
116 For an explanation of the terms used in this section, see
117 .BR attributes (7).
118 .TS
119 allbox;
120 lb lb lbx
121 l l l.
122 Interface Attribute Value
123 T{
124 .na
125 .nh
126 .BR login (),
127 .BR logout ()
128 T} Thread safety T{
129 .na
130 .nh
131 MT-Unsafe race:utent
132 sig:ALRM timer
133 T}
134 .TE
135 .P
136 In the above table,
137 .I utent
138 in
139 .I race:utent
140 signifies that if any of the functions
141 .BR setutent (3),
142 .BR getutent (3),
143 or
144 .BR endutent (3)
145 are used in parallel in different threads of a program,
146 then data races could occur.
147 .BR login ()
148 and
149 .BR logout ()
150 calls those functions,
151 so we use race:utent to remind users.
152 .SH VERSIONS
153 The member
154 .I ut_user
155 of
156 .I struct utmp
157 is called
158 .I ut_name
159 in BSD.
160 Therefore,
161 .I ut_name
162 is defined as an alias for
163 .I ut_user
164 in
165 .IR <utmp.h> .
166 .SH STANDARDS
167 BSD.
168 .SH SEE ALSO
169 .BR getutent (3),
170 .BR utmp (5)