1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
|
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="Content-Language" content="en" />
<title>utmps: the utmps library interface</title>
<meta name="Description" content="utmps: the utmps library interface" />
<meta name="Keywords" content="utmps utmp wtmp library libutmps" />
<!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
</head>
<body>
<p>
<a href="../">utmps</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>
<h1> The <tt>utmps</tt> library interface </h1>
<h2> General information </h2>
<p>
<tt>libutmps</tt> is a client library meant to be used by client
programs needing utmp functionality. It interacts with the
<a href="../utmps-utmpd.html">utmps-utmpd</a> and
<a href="../utmps-wtmpd.html">utmps-wtmpd</a> daemons.
</p>
<p>
Application programs can use it directly, but most existing programs
simply use the standard
<a href="http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/utmpx.h.html">utmpx.h</a>
interface, which in utmps is implemented as a series of thin wrappers
around the utmps library.
</p>
<p>
A suitable <tt>utmpx.h</tt> header can be found in the <tt>utmps/</tt>
subdirectory of
the header installation directory; if the <tt>--enable-libc-includes</tt>
option has been given to configure, it can also be found directly
in that directory. (Example: <tt>/usr/include/utmps/utmpz.h</tt> is
always installed, but if the option has been given at nsss build time,
<tt>/usr/include/utmpx.h</tt> is also installed and replaces the
version provided by the libc.)
</p>
<h2> Compiling </h2>
<ul>
<li> Make sure the utmps headers, as well as the skalibs headers,
are visible in your header search path. </li>
<li> Use <tt>#include <utmps/utmps.h></tt> </li>
<li> To use the standard <tt>utmpx.h</tt> interface, you can
just <tt>#include <utmpx.h></tt>, which will work:
<ul>
<li> either if the <tt>--enable-libc-includes</tt> option
has been given at utmps build time </li>
<li> or if you give the <tt>-I/usr/include/utmps</tt> option
to your compiler. (Depending on your standard header location,
specify that the header search path should include the
<tt>utmps</tt> subdirectory of that location.) This is useful when
the administrator did not want to overwrite the libc-provided
<tt>utmpx.h</tt> file when they installed utmps. </li>
</ul> </li>
</ul>
<h2> Linking </h2>
<ul>
<li> Make sure the utmps library, as well as the skalibs library,
are visible in your library search path. </li>
<li> Link against <tt>-lutmps</tt>, <tt>-lskarnet</tt>,
<tt>`cat $SYSDEPS/socket.lib`</tt> and
<tt>`cat $SYSDEPS/sysclock.lib`</tt>, $SYSDEPS being your skalibs
sysdeps directory. </li>
</ul>
<h2> Programming </h2>
<p>
Check the <tt>utmps/utmps.h</tt> header for the exact function list,
and the <tt>utmps/utmpx.h</tt> header for the definition of the standard
<tt>struct utmpx</tt> data type.
</p>
<h3> Synchronous functions with a specified maximum execution time </h3>
<p>
The standard utmpx.h functions are fully synchronous. They were not
initially meant to perform inter-processus communication; however, in
utmps, they do. Their synchronous nature is obviously not changed here,
but the underlying utmps functions use a safety mechanism to bound their
execution time in case daemons fail to respond. This mechanism is described,
for instance,
<a href="//skarnet.org/libs6/ftrigr.html#synctimed">here</a>.
</p>
<h3> Starting and ending a session </h3>
<p>
<code>int utmps_start (utmps *a, char const *path, tain_t const *deadline, tain_t *stamp)</code> <br />
Connects to a <tt>utmps-utmpd</tt> service listening on a Unix domain socket at <em>path</em>.
<em>a</em> must point to a previously allocated <em>utmps</em> object, which is flat and can
be allocated in the stack. This object must have been initialized to UTMPS_ZERO before the call.
<em>a</em> will be a handle describing the session, and must be given to all utmps functions
called in that session.
<em>deadline</em> and <em>stamp</em> are used to bound the execution time as described in the
above link. The function returns 1 if it succeeds; it returns 0, and sets errno, if it fails.
</p>
<p>
<code>void utmps_end (utmps *a)</code> <br />
Ends the session described by <em>a</em>, and releases all used resources.
</p>
<h3> Reading from the utmp database </h3>
<p>
Any user authorized to connect to the utmpd service can call these functions. In other
words, if <tt>utmps_start()</tt> succeeded, then these functions should not fail due to
insufficient permissions.
</p>
<p>
<code>int utmps_rewind (utmps *a, tain_t const *deadline, tain_t *stamp)</code> <br />
Performs the <tt>setutxent()</tt> functionality on the utmp database addressed via <em>a</em>,
i.e. sets the internal pointer at the start of the database.
On success, returns 1. On failure, returns 0 and sets errno.
</p>
<p>
<code>int utmps_getent (utmps *a, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br />
Performs the <tt>getutxent()</tt> functionality on the utmp database addressed via <em>a</em>.
On success, stores the result into <em>*b</em> and returns 1. On failure, returns 0 and sets errno.
</p>
<p>
<code>int utmps_getid (utmps *a, unsigned short type, char const *id, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br />
Performs the <tt>getutxid()</tt> functionality on the utmp database addressed via <em>a</em>,
using ut_type <em>type</em> and ut_id <em>id</em>. <em>id</em> must be a null-terminated
string; only its first UTMPS_UT_IDSIZE-1 characters will be taken into account.
On success, the function stores the result into <em>*b</em> and returns 1. On failure,
it returns 0 and sets errno.
</p>
<p>
<code>int utmps_getline (utmps *a, char const *line, struct utmpx *b, tain_t const *deadline, tain_t *stamp)</code> <br />
Performs the <tt>getutxline()</tt> functionality on the utmp database addressed via <em>a</em>,
using ut_line <em>line</em>. <em>line</em> must be a null-terminated
string; only its first UTMPS_UT_LINESIZE-1 characters will be taken into account.
On success, the function stores the result into <em>*b</em> and returns 1. On failure,
it returns 0 and sets errno.
</p>
<h3> Writing to the utmp database </h3>
<p>
Currently, only the super-user, and users belonging to the same group
<tt>utmps-utmpd</tt> is running as, are allowed to use this function.
</p>
<p>
<code>int utmps_putline (utmps *a, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)</code> <br />
Performs the <tt>pututxline()</tt> functionality on the utmp database addressed via <em>a</em>,
i.e. writes the <em>*b</em> structure into the utmp database looking for an appropriate
record to replace, and appending to the database if no such record can be found.
On success, the function returns 1. On failure, it returns 0 and sets errno.
</p>
<h3> Writing to the wtmp database </h3>
<p>
<code>int utmps_updwtmpx (char const *path, struct utmpx const *b, tain_t const *deadline, tain_t *stamp)</code> <br />
Unlike the previous functions, <tt>utmps_updwtmpx()</tt> does not use a utmps handle, because
it does not connect to an utmpd service. Instead, it connects to a wtmpd service listening
on Unix domain socket <em>path</em>, once for every call. It appends the <em>*b</em> structure
to the wtmp database, returning 1 on success and 0 (and setting errno) on failure.
</p>
<p>
<tt>utmps_updwtmpx()</tt> will only succeed if the caller is root, or if
<em>b→ut_user</em> resolves (according to <tt>getpwnam()</tt>) to the
effective uid of the caller. In other words: users can append phony records
for themselves, but not for others, and only root can spoof the whole
wtmp database.
</p>
</body>
</html>
|
