Add man pages for all librc functions.
This commit is contained in:
Roy Marples
244
man/rc_service.3
Normal file
244
man/rc_service.3
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user