-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
+<meta http-equiv="content-type" content="text/html; charset=iso-8859-1">
+
<title>User service daemon and client specification - Execution environment of the service program</title>
</head>
<body>
+<a name="ch-envir"></a>
<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>]
+[ <a href="ch-client.html">previous</a> ]
+[ <a href="index.html#contents">Contents</a> ]
+[ <a href="ch-intro.html">1</a> ]
+[ <a href="ch-client.html">2</a> ]
+[ 3 ]
+[ <a href="ch-config.html">4</a> ]
+[ <a href="ch-ipass.html">5</a> ]
+[ <a href="ch-notes.html">6</a> ]
+[ <a href="ch-config.html">next</a> ]
<hr>
<h1>
-User service daemon and client specification - Chapter 3<br>
-Execution environment of the service program
+User service daemon and client specification
+<br>Chapter 3 - 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>
+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>
-The service will have no controlling terminal, but it will be a
-process group leader.
-</p>
+The service will have no controlling terminal, but it will be a process group
+leader.
<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 <code>init</code>. The service may
-well not notice the disconnection, though writing to a pipe after this
-may produce a <code>SIGPIPE</code> and the facility exists to have a
-<code>SIGHUP</code> sent to the service on disconnection.
-</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 <code>init</code>. The service may well not notice the
+disconnection, though writing to a pipe after this may produce a
+<code>SIGPIPE</code> and the facility exists to have a <code>SIGHUP</code> sent
+to the service on disconnection.
<hr>
-<h2>
-<a name="s3.1">3.1 File descriptors</a>
-</h2>
+<a name="s3.1"></a>
+<h2>3.1 File descriptors</h2>
<p>
-The service program's standard filedescriptors, and possibly other
-file descriptors, will be connected to pipes or to
-<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>
+The service program's standard filedescriptors, and possibly other file
+descriptors, will be connected to pipes or to <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>
-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 <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>
+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
+<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>
-If the service closes one of its reading file descriptors the writing
-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>
+If the service closes one of its reading file descriptors the writing 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>
-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
-<code>SIGPIPE</code>.
-</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 <code>SIGPIPE</code>.
<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 <code>SIGPIPE</code>.
-</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
+<code>SIGPIPE</code>.
<p>
-Read errors on file descriptors (and disconnection) will only be
-visible to the service and distinguishable from normal end of file if
+Read errors on file descriptors (and disconnection) will only be visible to the
+service and distinguishable from normal end of file if
<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>
+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>
-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 <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
-<code>SIGHUP</code> even if a read or write error occurs or the client
-disconnects before then.
-</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 <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 <code>SIGHUP</code> even if a read
+or write error occurs or the client disconnects before then.
<hr>
-<h2>
-<a name="s3.2">3.2 Environment</a>
-</h2>
+<a name="s3.2"></a>
+<h2>3.2 Environment</h2>
<p>
The service will have some information in environment variables:
-<dl compact>
-<dt><samp>USERV_USER</samp><dd>The login name of the calling user. If the <code>LOGNAME</code> variable is
+<dl>
+<dt><samp>USERV_USER</samp></dt>
+<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 <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><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><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><samp>USERV_CWD</samp><dd>The client's current working directory name (this directory may not be
+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 <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).
+</dd>
+<dt><samp>USERV_UID</samp></dt>
+<dd>
+The uid of the calling process.
+</dd>
+<dt><samp>USERV_GID</samp></dt>
+<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.
+</dd>
+<dt><samp>USERV_GROUP</samp></dt>
+<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.
+</dd>
+<dt><samp>USERV_CWD</samp></dt>
+<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
-<code>--hidecwd</code> flag was used then this variable will be set to an
-empty string (this is not considered an error).
-
-<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>.
-
+<code>--hidecwd</code> flag was used then this variable will be set to an empty
+string (this is not considered an error).
+</dd>
+<dt><samp>USERV_SERVICE</samp></dt>
+<dd>
+The service name requested by the caller.
+</dd>
+<dt><samp>USERV_U_<var>name</var></samp></dt>
+<dd>
+The value supplied to the client by the caller using -D<var>name</var>.
+</dd>
</dl>
-
-<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>
+<p>
+<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).
<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>]
+[ <a href="ch-client.html">previous</a> ]
+[ <a href="index.html#contents">Contents</a> ]
+[ <a href="ch-intro.html">1</a> ]
+[ <a href="ch-client.html">2</a> ]
+[ 3 ]
+[ <a href="ch-config.html">4</a> ]
+[ <a href="ch-ipass.html">5</a> ]
+[ <a href="ch-notes.html">6</a> ]
+[ <a href="ch-config.html">next</a> ]
<hr>
-User service daemon and client specification<br>
+<p>
+User service daemon and client specification
<address>
-1.0.1<br>
-Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
+1.0.3<br>
+Ian Jackson <code><a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a></code>
</address>
+<hr>
+
</body>
</html>
~ian / userv.git / blobdiff