spec.html/ch-envir.html

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