chiark / gitweb /
Regenerated formatted documentation (spec.ps, spec.html).
[userv.git] / spec.html / ch-envir.html
index 64819a3..40b79cd 100644 (file)
-<html><head>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+
+<html>
+
+<head>
+
 <title>User service daemon and client specification - Execution environment of the service program</title>
-<link rev=made href="mailto:ian@davenant.greenend.org.uk">
-</head><body>
+
+</head>
+
+<body>
+
+<hr>
+
+[<a href="ch-client.html">back</a>]
+ [<a href="index.html#abstract">Abstract</a>]
+ [<a href="index.html#copyright">Copyright Notice</a>]
+ [<a href="index.html#contents">Contents</a>]
+ [<a href="ch-config.html">next</a>]
+
+<hr>
+
 <h1>
-User service daemon and client specification - chapter 3<br>
+User service daemon and client specification - Chapter 3<br>
 Execution environment of the service program
 </h1>
 
+<hr>
+
+<p>
 The daemon which is handling the service user side of things will read
 configuration files to decide what to do.  If it decides to allow the
 service to be provided it will fork a subprocess to execute the
-service.<P>
+service.
+</p>
 
+<p>
 The service will have no controlling terminal, but it will be a
-process group leader.<P>
+process group leader.
+</p>
 
+<p>
 If the client is killed or times out or a file or descriptor being
 read or written by the client process gets an error then the service
 will be disconnected from the client.  The client will return an exit
 status of 255 and some the service's pipes may be closed at the other
-end.  The service will become a child of <kbd>init</kbd>.  The service may
+end.  The service will become a child of <code>init</code>.  The service may
 well not notice the disconnection, though writing to a pipe after this
-may produce a <kbd>SIGPIPE</kbd> and the facility exists to have a
-<kbd>SIGHUP</kbd> sent to the service on disconnection.
+may produce a <code>SIGPIPE</code> and the facility exists to have a
+<code>SIGHUP</code> sent to the service on disconnection.
+</p>
+
 <hr>
-<h2><A name="s3.1">
-3.1 File descriptors
-</A></h2>
 
+<h2>
+<a name="s3.1">3.1 File descriptors</a>
+</h2>
+
+<p>
 The service program's standard filedescriptors, and possibly other
 file descriptors, will be connected to pipes or to
-<kbd>/dev/null</kbd>.  The <kbd>userv</kbd> client/daemon pair will arrange
+<code>/dev/null</code>.  The <code>userv</code> client/daemon pair will arrange
 that data is copied between the files or file descriptors specified to
-to the client by the caller and these these pipes.<P>
+to the client by the caller and these these pipes.
+</p>
 
+<p>
 Pipes which may be written to will be closed if a write error occurs
 on the corresponding client-side file or descriptor, which may result
-in a <kbd>SIGPIPE</kbd> in the service program; pipes open for reading
-will get <kbd>EOF</kbd> if the client-side file descriptor gets <kbd>EOF</kbd>
-or an error.<P>
+in a <code>SIGPIPE</code> in the service program; pipes open for reading
+will get <code>EOF</code> if the client-side file descriptor gets <code>EOF</code>
+or an error.
+</p>
 
+<p>
 If the service closes one of its reading file descriptors the writing
-end of the corresponding pipe will generate a <kbd>SIGPIPE</kbd> when
+end of the corresponding pipe will generate a <code>SIGPIPE</code> when
 attempts are made by the client/daemon pair to write to it.  This will
 not be considered an error; rather, the relevant pipe will be
 discarded and the corresponding file or file descriptor held by the
-client will be closed.<P>
+client will be closed.
+</p>
 
+<p>
 Likewise, if one of the file descriptors held by the client for
 writing by the service is a pipe whose other end is closed by the
 caller then the client/daemon pair will see an error when trying to
 copy data provided by the service.  This too will not be considered an
 error; rather, the pipe correspondong to that descriptor will be
 closed and any further writes will cause the service to get a
-<kbd>SIGPIPE</kbd>.<P>
+<code>SIGPIPE</code>.
+</p>
 
+<p>
 Note that not all write errors or broken pipes on file descriptors may
 be visible to the service, since buffered data may be discarded by the
 operating system and there will be a finite interval between the error
 happening and the service being disconnected from the client or the
-next write causing a <kbd>SIGPIPE</kbd>.<P>
+next write causing a <code>SIGPIPE</code>.
+</p>
 
+<p>
 Read errors on file descriptors (and disconnection) will only be
 visible to the service and distinguishable from normal end of file if
-<kbd>disconnect-hup</kbd> is in effect.<P>
+<code>disconnect-hup</code> is in effect.
+</p>
 
+<p>
 Read and write errors (other than broken pipes, as described above)
 will always be visible to the caller; they are system errors, and will
 therefore cause the client to print an error message to stderr and
-return with an exit status of 255.<P>
+return with an exit status of 255.
+</p>
 
+<p>
 If the main service program process exits while it still has running
 children any file descriptors held by those children can remain open,
-depending on the use of <code>wait</code>, <code>nowait</code> or <code>close</code> for the
+depending on the use of <samp>wait</samp>, <samp>nowait</samp> or <samp>close</samp> for the
 relevant file descriptor in the client's arguments.  By default
 writing filedescriptors remain open and the client will wait for them
 to be closed at the service end, and reading file descriptors are
 closed immediately.  These leftover child processes will not get a any
-<kbd>SIGHUP</kbd> even if a read or write error occurs or the client
+<code>SIGHUP</code> even if a read or write error occurs or the client
 disconnects before then.
+</p>
+
 <hr>
-<h2><A name="s3.2">
-3.2 Environment
-</A></h2>
 
+<h2>
+<a name="s3.2">3.2 Environment</a>
+</h2>
+
+<p>
 The service will have some information in environment variables:
 <dl compact>
-<dt><code>USERV_USER</code><dd>The login name of the calling user.  If the <kbd>LOGNAME</kbd> variable is
-set (or, if that is unset, if the <kbd>USER</kbd> variable is set) in the
+<dt><samp>USERV_USER</samp><dd>The login name of the calling user.  If the <code>LOGNAME</code> variable is
+set (or, if that is unset, if the <code>USER</code> variable is set) in the
 environment passed to the client by the caller then the password entry
 for that login name will be looked up; if that password entry's uid is
 the same as that of the calling process then that login name will be
-used, otherwise (or if neither <kbd>LOGNAME</kbd> nor <kbd>USER</kbd> is set)
+used, otherwise (or if neither <code>LOGNAME</code> nor <code>USER</code> is set)
 the calling process's uid will be looked up to determine their login
 name (and if this lookup fails then the service will not be invoked).
-<dt><code>USERV_UID</code><dd>The uid of the calling process.
-<dt><code>USERV_GID</code><dd>The gid and supplementary group list of the calling process: first the
+
+<dt><samp>USERV_UID</samp><dd>The uid of the calling process.
+
+<dt><samp>USERV_GID</samp><dd>The gid and supplementary group list of the calling process: first the
 group in gid and then those in the supplementary group list, in
 decimal, separated by spaces.
-<dt><code>USERV_GROUP</code><dd>The group names of the calling process, listed in the same way as the
-ids are in <kbd>USERV_GID</kbd>.  If no name can be found for any of the
+
+<dt><samp>USERV_GROUP</samp><dd>The group names of the calling process, listed in the same way as the
+ids are in <code>USERV_GID</code>.  If no name can be found for any of the
 calling process's group(s) then the service will not be invoked.
-<dt><code>USERV_CWD</code><dd>The client's current working directory name (this directory may not be
+
+<dt><samp>USERV_CWD</samp><dd>The client's current working directory name (this directory may not be
 accessible to the service).  If it could not be determined or the
-<kbd>--hidecwd</kbd> flag was used then this variable will be set to an
+<code>--hidecwd</code> flag was used then this variable will be set to an
 empty string (this is not considered an error).
-<dt><code>USERV_SERVICE</code><dd>The service name requested by the caller.
-<dt><code>USERV_U_</code><var>name</var><code></code><dd>The value supplied to the client by the caller using -D<var>name</var>.
+
+<dt><samp>USERV_SERVICE</samp><dd>The service name requested by the caller.
+
+<dt><samp>USERV_U_<var>name</var></samp><dd>The value supplied to the client by the caller using -D<var>name</var>.
+
 </dl>
 
 
-<kbd>HOME</kbd>, <kbd>PATH</kbd>, <kbd>SHELL</kbd>, <kbd>LOGNAME</kbd> and <kbd>USER</kbd>
+<code>HOME</code>, <code>PATH</code>, <code>SHELL</code>, <code>LOGNAME</code> and <code>USER</code>
 will be set appropriately (according to the details of the service
 user).
+</p>
 
 <hr>
-User service daemon and client specification
-- <A href="index.html#copyright"><kbd>userv</kbd> is Copyright 1996-1999 Ian Jackson.</A>
-<br>
-<A href="index.html#toc">Contents</A>; <A href="index.html#abstract">abstract</A>; <A href="ch-config.html">next</A>; <A href="ch-client.html">back</A>.
-<br>
-<address>0.62<br>
-Ian Jackson <A href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</A></address>
-</body></html>
+
+[<a href="ch-client.html">back</a>]
+ [<a href="index.html#abstract">Abstract</a>]
+ [<a href="index.html#copyright">Copyright Notice</a>]
+ [<a href="index.html#contents">Contents</a>]
+ [<a href="ch-config.html">next</a>]
+
+<hr>
+
+User service daemon and client specification<br>
+
+<address>
+0.62<br>
+Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
+</address>
+
+</body>
+
+</html>
+