Debian Codegraph @

upstream/debian-trixie/man3/login.3

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