Add man pages for all librc functions.

1 files changed, 244 insertions, 0 deletions

diff --git a/man/rc_service.3 b/man/rc_service.3
new file mode 100644
index 0000000..1e3a8f4
--- /dev/null
+++ b/man/rc_service.3
@@ -0,0 +1,244 @@
+.\" Copyright 2007 Roy Marples
+.\" All rights reserved
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd Dec 24, 2007
+.Dt RC_SERVICE 3 SMM
+.Os OpenRC
+.Sh NAME
+.Nm rc_service_add , rc_service_delete , rc_service_daemon_set ,
+.Nm rc_service_description , rc_service_exists , rc_service_in_runlevel ,
+.Nm rc_service_mark , rc_service_extra_commands , rc_service_plugable ,
+.Nm rc_service_resolve , rc_service_schedule_start , rc_services_scheduled_by ,
+.Nm rc_service_schedule_clear , rc_service_state ,
+.Nm rc_service_start , rc_service_stop ,
+.Nm rc_service_started_daemon , rc_service_value_get , rc_service_value_set ,
+.Nm rc_services_in_runlevel , rc_services_in_state , rc_services_scheduled ,
+.Nm rc_service_daemons_crashed
+.Nd functions to start, stop and query OpenRC services
+.Sh LIBRARY
+Run Command library (librc, -lrc)
+.Sh SYNOPSIS
+.In rc.h 
+.Ft bool Fn rc_service_add "const char *runlevel" "const char *service"
+.Ft bool Fn rc_service_delete "const char *runlevel" "const char *service"
+.Ft bool Fo rc_service_daemon_set
+.Fa "const char *service"
+.Fa "const char *exec"
+.Fa "const char *name"
+.Fa "const char *pidfile"
+.Fa "bool started"
+.Fc
+.Ft "char *" Fo rc_service_description
+.Fa "const char *service"
+.Fa "const char *option"
+.Fc
+.Ft bool Fn rc_service_exists "const char *service"
+.Ft bool Fn rc_service_in_runlevel "const char *service" "const char *runlevel"
+.Ft bool Fn rc_service_mark "const char *service" "rc_service_state_t state"
+.Ft "char **" Fn rc_service_extra_commands "const char *service"
+.Ft bool Fn rc_service_plugable "const char *service"
+.Ft "char *" rc_service_resolve "const char *service"
+.Ft bool Fo rc_service_schedule_start
+.Fa "const char *service"
+.Fa "const char *service_to_start"
+.Fc
+.Ft "char **" Fn rc_services_scheduled_by "const char *service"
+.Ft bool Fn rc_service_schedule_clear "const char *service"
+.Ft rc_service_state_t Fn rc_service_state "const char *service"
+.Ft pid_t Fn rc_service_start "const char *service"
+.Ft pid_t Fn rc_service_stop "const char *service"
+.Ft bool Fo rc_service_started_daemon
+.Fa "const char *service"
+.Fa "const char *exec"
+.Fa "int indx"
+.Fc
+.Ft "char *" Fn rc_service_value_get "const char *service" "const char *option"
+.Ft bool Fo rc_service_value_set
+.Fa "const char *service"
+.Fa "const char *option"
+.Fa "const char *value"
+.Fc
+.Ft "char **" Fn rc_services_in_runlevel "const char *runlevel"
+.Ft "char **" Fn rc_services_in_state "rc_service_state_t state"
+.Ft "char **" Fn rc_services_scheduled "const char *service"
+.Ft bool Fn rc_service_daemons_crashed "const char *service"
+.Sh DESCRIPTION
+These functions provide a means of querying OpenRC services to find out the
+state of each one, to start and stop it, and any other functions related
+to it.
+.Pp
+Most functions should be self descriptive as to what they do and what they
+return based on names and arguments.
+.Pp
+.Fn rc_service_add
+adds the
+.Fa service
+to the
+.Fa runlevel .
+.Pp
+.Fn rc_service_delete
+deletes the
+.Fa service
+from the
+.Fa runlevel .
+.Pp
+.Fn rc_service_daemon_set
+saves the arguments in the
+.Fa service
+state data so that
+.Fn rc_service_daemons_crashed
+can check to see if they are still running or not.
+.Pp
+.Fn rc_service_description
+returns the
+.Va description
+variable of the
+.Fa service .
+If
+.Fa option
+is not null then we return the
+.Fa description_$option
+variable instead.
+.Pp
+.Fn rc_service_exists
+returns true if the
+.Fa service
+exists, otherwise false.
+.Pp
+.Fn rc_service_in_runlevel
+returns true if the
+.Fa service
+is in the
+.Fa runlevel ,
+otherwise false.
+.Pp
+.Fn rc_service_mark
+puts the
+.Fa service
+into the given
+.Fa state .
+If the state is RC_SERVICE_STOPPED then all data associated with the
+.Fa service
+is lost.
+.Fn rc_service_extra_commands
+returns a list of extra commands the
+.Fa service
+supports beyond the default ones. See
+.Nm runscript
+for default commands.
+.Pp
+.Fn rc_service_plugable
+returns true if the service is allowed to be plugged by
+.Pa rc.conf .
+Default is true.
+.Pp
+.Fn rc_service_resolve
+resolves
+.Fa service
+to the full path of service that was started, or would be started.
+.Pp
+When
+.Fa service
+starts, it starts
+.Fa service_to_start
+afterswards as directed by
+.Fn rc_service_schedule_start .
+.Fn rc_services_scheduled
+returns a list of services that will be started when
+.Fa service
+starts.
+.Fn rc_service_schedule_clear
+clears these scheduled services for
+.Fa service .
+.Pp
+.Fn rc_service_state returns the state of
+.Fa service .
+The return value is a bitmask, where more than one state can apply.
+.Pp
+.Fn rc_service_start
+starts
+.Fa service ,
+returning the pid of new process.
+.Pp
+.Fn rc_service_stop
+stops
+.Fa service ,
+returning the pid of new process.
+.Pp
+.Fn rc_service_started_daemon
+checks to see if
+.Fa service
+started
+.Fa exec
+using
+.Nm start-stop-daemon .
+If
+.Fa indx
+is greater than zero, then it must also be the nth daemon started by
+.Fa service .
+.Fn rc_service_value_set
+saves the
+.Fa value
+under the name
+.Fa option .
+.Fn rc_service_value_get
+returns the value of the saved
+.Fa option .
+.Pp
+.Fn rc_services_in_runlevel
+returns a list of services in
+.Fa runlevel .
+If
+.Fa runlevel
+is not specified, then it returns a list of all available services.
+.Pp
+.Fn rc_services_in_state
+returns a list of all the services in
+.Fa state .
+.Sh IMPLEMENTATION NOTES
+Each function that returns
+.Fr "char *"
+returns a malloced NULL terminated string that should be freed when done.
+.Pp
+Each function that returns
+.Fr "char **"
+returns a malloced NULL terminated array of malloced NULL terminated strings,
+all of which need to be freed using
+.Fn rc_strlist_free
+when done.
+.Pp
+When a function fails it should either return false or NULL and set
+.Va errno
+unless specified otherwise as above.
+.Sh FILES
+.Pa /lib/rc/init.d
+normally holds the volatile state data for services on a RAM backed disk.
+.Sh SEE ALSO
+.Xr errno 3 ,
+.Xr malloc 3 ,
+.Xr free 3
+.Xr rc_strlist_free 3 ,
+.Xr start-stop-daemon 8
+.Sh AUTHORS
+.An "Roy Marples" Aq roy@marples.name