From: ian Date: Sun, 29 Jun 2003 21:12:38 +0000 (+0000) Subject: manpage improvements X-Git-Tag: debian_version_1_0_1_99_0~2 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?p=userv.git;a=commitdiff_plain;h=8e98342e91fc0cf56a3a16ccd737ebd98bda04af;ds=sidebyside manpage improvements --- diff --git a/INSTALL b/INSTALL index 97bb5db..46d3bdc 100644 --- a/INSTALL +++ b/INSTALL @@ -72,68 +72,9 @@ For debugging version (./configure --enable-debug): * initgroups(3) must use setgroups(2) and dynamic linking must allow overriding setgroups(2) for initgroups(3); -DAEMON INVOCATION: - -The daemon can be invoked with no arguments, in which case it will not -fork or detach itself. This is suitable for running from init and -similar arrangements. - -With -daemon it will attempt to detach itself from the controlling -terminal and fork/exit so that control returns at startup. - -In both cases diagnostics which prevent correct startup will appear on -stderr. - -SYSLOG MESSAGES: - -The daemon issues diagnostics of various kinds to syslog, usually with -facility LOG_DAEMON (though this can be changed in daemon.h if you want). -The syslog levels used are: - debug - verbose messages about the activity of the userv daemon. - info - two log message about the nature and outcome of each request. - notice - messages about the status of the daemon, including the - startup message and the hourly socket check messages. - warning - if the uservd exits because it believes that it no longer - controls the rendezvous socket (ie, its socket has become - orphaned), this level will receive messages indicating why - the daemon believes this and notifying of its shutdown. - err - a believed-recoverable error condition was detected by the - userv server in itself, the client or the operating system - (this includes resource shortages). The uservd will try to - continue. - crit - the uservd detected a non-recoverable error condition - after startup and will exit. - alert - not used. - emerg - not used. - -The service configuration language has the facility to direct error -and warning messages to syslog. The default facility and level is -user.err, but the author of the configuration file(s) can override -this. - -DAEMON EXIT STATUS: - -The daemon's exit code will reflect how well things went: - - 0 - The daemon was asked to detach itself from the controlling - terminal and this appears to have been done successfully. - 1* - The daemon got a SIGTERM or SIGINT and shut itself down. - 2* - The daemon believes that it was no longer the uservd and so has - exited to clean itself up. - 3 - uservd was started with incorrect arguments. - 4 - A system call failure or other environmental problem occurred - during startup. - 5* - There was a non-recoverable error after startup; the uservd had - to exit. - 6 - The daemon was asked to detach itself, but its detaching child - died for some unexpected reason. - - SIGABRT/SIGIOT* - an unexpected internal error, usually caused by a - bug in uservd. This can also occur if an attempt to block signals - using sigprocmask fails. - -Outcomes marked * are not possible if the daemon is asked to detach -itself - these exit statuses will be reaped by init instead. +EXIT STATUS CODES + +For information about uservd's exit status, see uservd(8). The daemon's per-request children will note the success level of its request in its exit status. This will not usually be logged unless it diff --git a/debian/changelog b/debian/changelog index f9d429e..999cd3b 100644 --- a/debian/changelog +++ b/debian/changelog @@ -20,7 +20,8 @@ userv (1.0.2) unstable; urgency=low * Specification's usage notes section improved. * --help and --version behaviour made to conform to GNU standards. * We do ship m4 and flex output now, so say so. - * Some groff warnings in userv(1) fixed. + * Some groff warnings in userv(1), and source version fixed. + * New userv(8) manpage. (Debian: Closes: #33777.) Debian: * Priority changed to optional as per override file. diff --git a/userv.1 b/userv.1 index 70553a0..e4f3fd9 100644 --- a/userv.1 +++ b/userv.1 @@ -3,7 +3,7 @@ .\" copyright section, below. .Dd November 3, 1999 .Dt USERV 1 -.Os "userv 1.0.0" +.Os "userv" .Sh NAME .Nm userv .Nd request user services diff --git a/uservd.8 b/uservd.8 new file mode 100644 index 0000000..581be28 --- /dev/null +++ b/uservd.8 @@ -0,0 +1,145 @@ +.\" +.\" This manpage is copyright, like the rest of userv, - see the +.\" copyright section, below. +.Dd November 3, 1999 +.Dt USERVD 8 +.Os "userv" +.Sh NAME +.Nm uservd +.Nd supply user services +.Sh SYNOPSIS +.Nm userv +.Op Fl daemon +.Sh DESCRIPTION +.Nm uservd +is the daemon called by +.Nm userv +to have a task performed under different userid while +maintaining limited trust between caller and callee. +.Sh OPTIONS +There is one optional argument: +.Bl -tag -width Fl +.It Fl daemon +Requests that the program daemonise. If this flag is supplied, +.Nm uservd +will fork and completely detach from the controlling terminal. +If this option is not supplied, +.Nm uservd +will remain in its starting process group and continue to use the +supplied stderr stream for any runtime system messages; this is useful +for running +.Nm uservd +as a child of +.Nm init Ns . +Errors +detected by +.Nm uservd +itself will be reported via +.Nm syslog +in either case. +.El +.Sh SYSLOG MESSAGES: +.Nm uservd +issues diagnostics of various kinds to syslog, with facility +.Nm LOG_DAEMON Ns . +The syslog levels used are: +.Bl -tag -width Nm +.It Nm debug +Verbose messages about the activity of the userv daemon. +.It Nm info +Two log messages about the nature and outcome of each request. +.It Nm notice +Messages about the status of the daemon, including the +startup message and the hourly socket check messages. +.It Nm warning +If the uservd exits because it believes that it no longer controls the +rendezvous socket (ie, its socket has become orphaned), this level +will receive messages indicating why the daemon believes this and +notifying of its shutdown. +.It Nm err +A believed-recoverable error condition was detected by the userv +server in itself, the client or the operating system (this includes +resource shortages). The uservd will try to continue. +.It Nm crit +The uservd detected a non-recoverable error condition after startup +and will exit. +.It Nm alert +not used. +.It Nm emerg +not used. +.El +.Pp +The service configuration language has the facility to direct error +and warning messages to syslog. The default facility and level is +.Nm user.err Ns , +but the author of the configuration file(s) can override this. +.Sh EXIT STATUS +The daemon's exit code will reflect how well things went: +.Bl -tag -width Nm +.It Nm 0 +The daemon was asked to detach itself from the controlling +terminal and this appears to have been done successfully. +.It Nm 1* +The daemon got a SIGTERM or SIGINT and shut itself down. +.It Nm 2* +The daemon believed that it was no longer the uservd and so exited to +clean up. +.It Nm 3 +uservd was started with incorrect arguments. +.It Nm 4 +A system call failure or other environmental problem occurred +during startup. +.It Nm 5* +There was a non-recoverable error after startup; the uservd had +to exit. +.It Nm 6 +The daemon was asked to detach itself, but its detaching child +died for some unexpected reason. +.It Nm SIGABRT/SIGIOT* +An unexpected internal error, usually caused by a bug in uservd. This +can also occur if an attempt to block signals using sigprocmask fails. +.El +.Pp +Outcomes marked * are not possible if the daemon is asked to detach +itself - these exit statuses will be reaped by init instead and so +will not usually be logged anywhere. +.Pp +The daemon's per-request children will report the success or otherwise +of its request in their exit status. These are not usually be logged +unless they indicate a serious problem. +.Sh ENVIRONMENT +All of the environment variables passed to +.Nm uservd +will be inherited by services as part of the default environment. +(If the +.Nm set-environment +configuration directive is used, then other system configuration files +can modify the environment. Consult the specification.) +.Sh SEE ALSO +.Xr userv 1 +.Xr init 8 +.Rs +.%T "User service daemon and client specification" +.%A Ian Jackson +.Re +.Sh COPYRIGHT +GNU userv, including this manpage, is Copyright (C)1996-2001,2003 Ian +Jackson, except that the +.Xr userv 1 +manpage is Copyright (C)2000 Ben Harris. +.Pp +GNU userv is licensed under the terms of the GNU General Public +Licence, version 2 or (at your option) any later version, and it comes +with NO WARRANTY, not even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for details. +.Pp +You should have received a copy of the GNU General Public License +along with userv, if not, write to the Free Software Foundation, 59 +Temple Place - Suite 330, Boston, MA 02111-1307, USA. +.Sh HISTORY +.Nm +was initially written in 1996 by Ian Jackson. It became +.Tn GNU +.Nm +in 1999, and version 1.0 was released in 2000.