diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2017-11-20 14:51:36 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska-skaware@skarnet.org> | 2017-11-20 14:51:36 +0000 |
| commit | 4ba5ae5776c2e9ba4f297115c19923a928cf3e87 (patch) | |
| tree | 5a67f39a64dc5df84fc20307aa95d7536890b8b5 /doc/libutmps | |
| download | utmps-4ba5ae5776c2e9ba4f297115c19923a928cf3e87.tar.xz | |
Initial release / rename to utmps
Diffstat (limited to 'doc/libutmps')
| -rw-r--r-- | doc/libutmps/index.html | 171 |
1 files changed, 171 insertions, 0 deletions
diff --git a/doc/libutmps/index.html b/doc/libutmps/index.html new file mode 100644 index 0000000..0372726 --- /dev/null +++ b/doc/libutmps/index.html @@ -0,0 +1,171 @@ +<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> + +<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 as long +as the <tt>utmps/utmpx.h</tt> header is accessible in your header +search path. </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>, </li> +<tt>`cat $SYSDEPS/socket.lib`</tt> and +<tt>`cat $SYSDEPS/tainnow.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, stores the result into <em>*b</em> and 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 is 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> |