X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=blobdiff_plain;f=spec.html%2Fch-client.html;h=fe1b980cfe8d00ac852bb0d0a242159d519a3fa9;hp=2d4a3451b8ba9160a90df0f16c973b5d76d533a0;hb=dc9e0a48601e4dc7b3060c1e816692f07e6be095;hpb=d481e8196cc08ec6761f3a26da16d1e02dbbc712;ds=sidebyside diff --git a/spec.html/ch-client.html b/spec.html/ch-client.html index 2d4a345..fe1b980 100644 --- a/spec.html/ch-client.html +++ b/spec.html/ch-client.html @@ -1,110 +1,159 @@ -
-userv options [--] service-user service-name [argument ...] -userv options -B|--builtin [--] builtin-service [info-argument ...]
+
+
+userv options [--] service-user service-name [argument ...] +userv options -B|--builtin [--] builtin-service [info-argument ...] ++ + +
service-user specifies which user is to provide the service.
-The user may be a login name or a numeric uid, or -
to indicate
-that the service user is to be the same as the calling user.
+The user may be a login name or a numeric uid, or - to indicate +that the service user is to be the same as the calling user. +
-The service name is interpreted by the userv[1] ++The service name is interpreted by the userv[1] daemon on behalf of the service user. It will often be the name of a program. +
+Single-letter options may be combined as is usual with Unix programs, and the value for such an option may appear in the same argument or in the next.
-B
--builtin
-
(indicating the
-calling user).+
--override
option to specify a string consisting of
+execute-builtin
followed by the builtin-service
+requested, and requesting a service user of - (indicating the
+calling user).
If the builtin service being requested requires a
service-argument then this must be supplied to the client in the
-same argument as the builtin-service. See Directives for changing execution settings, subsection 4.2.4 for details of the builtin services available,
-and Security-overriding options, section 2.2 for details of the --override
-options.
+same argument as the builtin-service. See Directives for changing execution settings, subsection 4.2.4 for details of the builtin services available,
+and Security-overriding options, section 2.2 for details of the --override
+options.
The actual service name passed will be the builtin-service; note
that this actual service name (as opposed to the override data) and
the info-arguments supplied will be ignored by most builtin
-services; the override mechanism and execute-builtin will be
+services; the override mechanism and execute-builtin
will be
used to ensure that the right builtin service is called with the right
service-arguments.
-
-f
fd[
modifiers]=
filename
--file
fd[
modifiers]=
filename
cat
invoked by the client; the
+other file descriptor passed to cat
will be one inherited by
the client program from the caller or one opened by the client program
-on behalf of the caller.
+on behalf of the caller.
The descriptor in the service program that should be connected must be
specified as fd, either as a decimal number or as one of the
-strings stdin
, stdout
or stderr
. The next argument is
+strings stdin, stdout or stderr. The next argument is
a filename which will be opened by the client with the privileges of
the calling user.
-
+ modifiers is used to specify whether the file or descriptor is to be read from or written to. It consists of a series of words separated by commas. A comma may separate the modifiers from the fd and is required if fd is not numeric. -
+ +
The modifier words are:
read
O_RDONLY
: Allow reading and not writing. May not be used with
-write
or things that imply it.
-write
O_WRONLY
: Allow writing and not reading. Doesn't truncate or
-create without truncate
or create
. write
or things
-that imply it may not be used with read
.
-overwrite
write,create,truncate
.
-create
creat
O_CREAT
: Creates the file if necessary. Implies write
.
-exclusive
excl
O_EXCL
: Fails if the file already exists. Implies write
and
-create
. May not be used with truncate
.
-truncate
trunc
O_TRUNC
: Truncate any existing file. Implies write
.
-May not be used with exclusive
.
-append
O_APPEND
: All writes will append to the file. Implies write
-(but not create
).
-sync
O_SYNC
: Do writes synchronously. Implies write
.
-wait
nowait
close
fd
read
and write
must be specified, and no
-other words are allowed. The filename may also be stdin
,
-stdout
or stderr
for file descriptor 0, 1 or 2 respectively.
+
++
-If no modifiers which implyread
or write
are used it
-is as if write
had been specified, except that if the
+
+If no modifiers which imply read or write are used it
+is as if write had been specified, except that if the
filedescriptor 0 of the service is being opened (either specified
-numerically or with stdin
) it is as if overwrite
had been
-specified (or write
if only fd
was specified).
+numerically or with stdin) it is as if overwrite had been +specified (or write if only fd was specified). +
-The client will also useO_NOCTTY
when opening files specified by
-the caller, to avoid changing its controlling terminal.+
+The client will also use O_NOCTTY when opening files specified by +the caller, to avoid changing its controlling terminal. +
+By default stdin, stdout and stderr of the service will be connected to the corresponding descriptors on the client. Diagnostics from -the client and daemon will also appear on stderr.
+the client and daemon will also appear on stderr. +
-Ifwait
is specified, the client will wait for the pipe to be
++If wait is specified, the client will wait for the pipe to be closed, and only exit after this has happened. This means that either the receiving end of the pipe connection was closed while data was still available at the sending end, or that the end of file was @@ -112,102 +161,128 @@ reached on the reading file descriptor. Errors encountered reading or writing in the client at this stage will be considered a system error and cause the client to exit with status 255, but will not cause disconnection at the service side since the service has already -exited.
+exited. +
-Ifclose
is specified the client will immediately close the pipe
-connection by killing the relevant copy of cat. If the service
-uses the descriptor it will get SIGPIPE (or EPIPE) for a
+
+If close is specified the client will immediately close the pipe
+connection by killing the relevant copy of cat
. If the service
+uses the descriptor it will get SIGPIPE
(or EPIPE
) for a
writing descriptor or end of file for a reading one; the descriptor
-opened by or passed to the client will also be closed.
+opened by or passed to the client will also be closed. +
-Ifnowait
is specified then the client will not wait and the
+
+If nowait is specified then the client will not wait and the
connection will remain open after the client terminates. Data may
continue to be passed between the inheritors of the relevant
descriptor on the service side and the corresponding file or
descriptor on the client side until either side closes their
descriptor. This should not usually be specified for stderr (or
-stdout if --signals stdout
is used) since diagnostics from
+stdout if --signals stdout is used) since diagnostics from
the service side may arrive after the client has exited and be
-confused with expected output.
+confused with expected output. +
-The default iswait
for writing file descriptors and close
++The default is wait for writing file descriptors and close for reading ones. -
-w
fd=
action
--fdwait
fd=
action
wait
, nowait
or close
+
+
+--file
or --fdwait
option - even by a
+--file
which does not specify an action on termination (in this
case the default will be used, as described above).
--D
name=
value
--defvar
name=
value
u-
name
and are passed to the
-service in environment variables USERV_U_
name
. name
+language as the parameters u-name and are passed to the
+service in environment variables USERV_U_name. name
may contain only alphanumerics and underscores, and must start with a
letter. If several definitions are given for the same name then
only the last is effective.
--t
seconds
--timeout
seconds
-S
method--signals
method_exit
, so that only numbers from 0 to 255 can be returned and
not the full range of numbers and signal indications which can be
-returned by the wait family of system calls.)
+returned by the wait
family of system calls.)
+
The method may be one of the following:
number
number-nocore
number
is used rather than
-number-nocore
then 128 will be added if the service dumped core.
-number
is very like the exit code mangling done by the Bourne
+
+highbit
stdout
+
Problems such as client usage errors, the service not being found or permission being denied or failure of a system call are system errors. An error message describing the problem will be printed on the client's stderr, and the client's exit status will be 255. If the client dies due to a signal this should be treated as a serious system error. -
-H
--hidecwd
-P
--sigpipe
SIGPIPE
the exit
status of the client will be zero, even if it would have been
something else according to the exit status method specified. This
option has no effect on the code and description printed if the exit
-status method stdout
is in use.
--h
--help
--copyright
-h
or --help
prints the client's usage message;
---copyright
prints the copyright and lack of warranty notice.
+status method stdout is in use.
+
+There are also some options which are available for debugging and to allow the system administrator to override a user's policy. These options are available only if the client is called by root or if the calling user is the same as the service user.
--override
configuration-data
--override-file
filename
--spoof-user
user
--spoof-user
option will not affect which user is chosen if
-the service user is specified as just -
; in this case the service
+--spoof-user option will not affect which user is chosen if
+the service user is specified as just -; in this case the service
user will be the real calling user.
-