spec.html/ch-envir.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
   2
   3 <html>
   4
   5 <head>
   6
   7 <title>User service daemon and client specification - Execution environment of the service program</title>
   8
   9 </head>
  10
  11 <body>
  12
  13 <hr>
  14
  15 [<a href="ch-client.html">back</a>]
  16  [<a href="index.html#abstract">Abstract</a>]
  17  [<a href="index.html#copyright">Copyright Notice</a>]
  18  [<a href="index.html#contents">Contents</a>]
  19  [<a href="ch-config.html">next</a>]
  20
  21 <hr>
  22
  23 <h1>
  24 User service daemon and client specification - Chapter 3<br>
  25 Execution environment of the service program
  26 </h1>
  27
  28 <hr>
  29
  30 <p>
  31 The daemon which is handling the service user side of things will read
  32 configuration files to decide what to do.  If it decides to allow the
  33 service to be provided it will fork a subprocess to execute the
  34 service.
  35 </p>
  36
  37 <p>
  38 The service will have no controlling terminal, but it will be a
  39 process group leader.
  40 </p>
  41
  42 <p>
  43 If the client is killed or times out or a file or descriptor being
  44 read or written by the client process gets an error then the service
  45 will be disconnected from the client.  The client will return an exit
  46 status of 255 and some the service's pipes may be closed at the other
  47 end.  The service will become a child of <code>init</code>.  The service may
  48 well not notice the disconnection, though writing to a pipe after this
  49 may produce a <code>SIGPIPE</code> and the facility exists to have a
  50 <code>SIGHUP</code> sent to the service on disconnection.
  51 </p>
  52
  53 <hr>
  54
  55 <h2>
  56 <a name="s3.1">3.1 File descriptors</a>
  57 </h2>
  58
  59 <p>
  60 The service program's standard filedescriptors, and possibly other
  61 file descriptors, will be connected to pipes or to
  62 <code>/dev/null</code>.  The <code>userv</code> client/daemon pair will arrange
  63 that data is copied between the files or file descriptors specified to
  64 to the client by the caller and these these pipes.
  65 </p>
  66
  67 <p>
  68 Pipes which may be written to will be closed if a write error occurs
  69 on the corresponding client-side file or descriptor, which may result
  70 in a <code>SIGPIPE</code> in the service program; pipes open for reading
  71 will get <code>EOF</code> if the client-side file descriptor gets <code>EOF</code>
  72 or an error.
  73 </p>
  74
  75 <p>
  76 If the service closes one of its reading file descriptors the writing
  77 end of the corresponding pipe will generate a <code>SIGPIPE</code> when
  78 attempts are made by the client/daemon pair to write to it.  This will
  79 not be considered an error; rather, the relevant pipe will be
  80 discarded and the corresponding file or file descriptor held by the
  81 client will be closed.
  82 </p>
  83
  84 <p>
  85 Likewise, if one of the file descriptors held by the client for
  86 writing by the service is a pipe whose other end is closed by the
  87 caller then the client/daemon pair will see an error when trying to
  88 copy data provided by the service.  This too will not be considered an
  89 error; rather, the pipe correspondong to that descriptor will be
  90 closed and any further writes will cause the service to get a
  91 <code>SIGPIPE</code>.
  92 </p>
  93
  94 <p>
  95 Note that not all write errors or broken pipes on file descriptors may
  96 be visible to the service, since buffered data may be discarded by the
  97 operating system and there will be a finite interval between the error
  98 happening and the service being disconnected from the client or the
  99 next write causing a <code>SIGPIPE</code>.
 100 </p>
 101
 102 <p>
 103 Read errors on file descriptors (and disconnection) will only be
 104 visible to the service and distinguishable from normal end of file if
 105 <code>disconnect-hup</code> is in effect.
 106 </p>
 107
 108 <p>
 109 Read and write errors (other than broken pipes, as described above)
 110 will always be visible to the caller; they are system errors, and will
 111 therefore cause the client to print an error message to stderr and
 112 return with an exit status of 255.
 113 </p>
 114
 115 <p>
 116 If the main service program process exits while it still has running
 117 children any file descriptors held by those children can remain open,
 118 depending on the use of <samp>wait</samp>, <samp>nowait</samp> or <samp>close</samp> for the
 119 relevant file descriptor in the client's arguments.  By default
 120 writing filedescriptors remain open and the client will wait for them
 121 to be closed at the service end, and reading file descriptors are
 122 closed immediately.  These leftover child processes will not get a any
 123 <code>SIGHUP</code> even if a read or write error occurs or the client
 124 disconnects before then.
 125 </p>
 126
 127 <hr>
 128
 129 <h2>
 130 <a name="s3.2">3.2 Environment</a>
 131 </h2>
 132
 133 <p>
 134 The service will have some information in environment variables:
 135 <dl compact>
 136 <dt><samp>USERV_USER</samp><dd>The login name of the calling user.  If the <code>LOGNAME</code> variable is
 137 set (or, if that is unset, if the <code>USER</code> variable is set) in the
 138 environment passed to the client by the caller then the password entry
 139 for that login name will be looked up; if that password entry's uid is
 140 the same as that of the calling process then that login name will be
 141 used, otherwise (or if neither <code>LOGNAME</code> nor <code>USER</code> is set)
 142 the calling process's uid will be looked up to determine their login
 143 name (and if this lookup fails then the service will not be invoked).
 144
 145 <dt><samp>USERV_UID</samp><dd>The uid of the calling process.
 146
 147 <dt><samp>USERV_GID</samp><dd>The gid and supplementary group list of the calling process: first the
 148 group in gid and then those in the supplementary group list, in
 149 decimal, separated by spaces.
 150
 151 <dt><samp>USERV_GROUP</samp><dd>The group names of the calling process, listed in the same way as the
 152 ids are in <code>USERV_GID</code>.  If no name can be found for any of the
 153 calling process's group(s) then the service will not be invoked.
 154
 155 <dt><samp>USERV_CWD</samp><dd>The client's current working directory name (this directory may not be
 156 accessible to the service).  If it could not be determined or the
 157 <code>--hidecwd</code> flag was used then this variable will be set to an
 158 empty string (this is not considered an error).
 159
 160 <dt><samp>USERV_SERVICE</samp><dd>The service name requested by the caller.
 161
 162 <dt><samp>USERV_U_<var>name</var></samp><dd>The value supplied to the client by the caller using -D<var>name</var>.
 163
 164 </dl>
 165
 166
 167 <code>HOME</code>, <code>PATH</code>, <code>SHELL</code>, <code>LOGNAME</code> and <code>USER</code>
 168 will be set appropriately (according to the details of the service
 169 user).
 170 </p>
 171
 172 <hr>
 173
 174 [<a href="ch-client.html">back</a>]
 175  [<a href="index.html#abstract">Abstract</a>]
 176  [<a href="index.html#copyright">Copyright Notice</a>]
 177  [<a href="index.html#contents">Contents</a>]
 178  [<a href="ch-config.html">next</a>]
 179
 180 <hr>
 181
 182 User service daemon and client specification<br>
 183
 184 <address>
 185 1.0.1<br>
 186 Ian Jackson <a href="mailto:ian@davenant.greenend.org.uk">ian@davenant.greenend.org.uk</a>
 187 </address>
 188
 189 </body>
 190
 191 </html>
 192