app.man renamed to app.3
This commit is contained in:
Jim Reid
234
doc/man/app.3
Normal file
234
doc/man/app.3
Normal file
@@ -0,0 +1,234 @@
|
||||
.\"
|
||||
.\" Copyright (C) 2000 Internet Software Consortium.
|
||||
.\"
|
||||
.\" Permission to use, copy, modify, and distribute this document for any
|
||||
.\" purpose with or without fee is hereby granted, provided that the above
|
||||
.\" copyright notice and this permission notice appear in all copies.
|
||||
.\"
|
||||
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
||||
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
||||
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
||||
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
||||
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
||||
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
||||
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||
.\"
|
||||
.\" $Id: app.3,v 1.1 2000/06/23 00:17:06 jim Exp $
|
||||
.\"
|
||||
.Dd Jun 30, 2000
|
||||
.Dt APP 3
|
||||
.Os BIND9 9
|
||||
.ds vT BIND9 Programmer's Manual
|
||||
.Sh NAME
|
||||
.Nm handle_signal ,
|
||||
.Nm isc_app_start ,
|
||||
.Nm isc_app_onrun ,
|
||||
.Nm isc_app_run ,
|
||||
.Nm isc_app_shutdown ,
|
||||
.Nm isc_app_reload ,
|
||||
.Nm isc_app_finish
|
||||
.Nd application management functions
|
||||
.Sh SYNOPSIS
|
||||
.Fd #include <config.h>
|
||||
|
||||
.Fd #include <pthread.h>
|
||||
|
||||
.Fd #include <sys/types.h>
|
||||
|
||||
.Fd #include <stddef.h>
|
||||
.Fd #include <errno.h>
|
||||
.Fd #include <unistd.h>
|
||||
.fd #include <signal.h>
|
||||
|
||||
.Fd #include <isc/app.h>
|
||||
.Fd #include <isc/boolean.h>
|
||||
.Fd #include <isc/mutex.h>
|
||||
.Fd #include <isc/event.h>
|
||||
.Fd #include <isc/string.h>
|
||||
.Fd #include <isc/task.h>
|
||||
.Fd #include <isc/util.h>
|
||||
.Ft static isc_result_t
|
||||
.Fn handle_signal "int sig" "void (*handler)(int)"
|
||||
.Ft isc_result_t
|
||||
.Fn isc_app_start "void"
|
||||
.Ft isc_result_t
|
||||
.Fo isc_app_onrun
|
||||
.Fa "isc_mem_t *mctx"
|
||||
.Fa "isc_task_t *task"
|
||||
.Fa "isc_taskaction_t action"
|
||||
.Fa "void *arg"
|
||||
.Fc
|
||||
.Ft isc_result_t
|
||||
.Fn isc_app_run "void"
|
||||
.Ft isc_result_t
|
||||
.Fn isc_app_shutdown "void"
|
||||
.Ft isc_result_t
|
||||
.Fn isc_app_reload "void"
|
||||
.Ft void
|
||||
.Fn isc_app_finish "void"
|
||||
.Sh DESCRIPTION
|
||||
These functions define the interface for creating and terminating
|
||||
applications which use the BIND9 library.
|
||||
.Pp
|
||||
.Fn handle_signal
|
||||
sets up a signal handler for signal
|
||||
.Fa sig .
|
||||
.Fa handler
|
||||
is a pointer to the function that will be called whenever signal
|
||||
.Fa sig
|
||||
is delivered to the name server.
|
||||
The signal handler is a void function which is passed an
|
||||
.Ft int
|
||||
argument: the number of the signal
|
||||
.Fa sig
|
||||
that has been delivered.
|
||||
.Pp
|
||||
Applications which use the BIND9 library should begin by calling
|
||||
.Fn isc_app_start .
|
||||
It sets up a signal handler to ignore
|
||||
.Dv SIGPIPE .
|
||||
.Fn isc_app_start
|
||||
blocks signals
|
||||
.Dv SIGHUP ,
|
||||
.Dv SIGINT
|
||||
and
|
||||
.Dv SIGTERM
|
||||
This ensures that all subsequent threads will have these signals blocked by
|
||||
default.
|
||||
Any thread which wants to take delivery of these signals will have to
|
||||
arrange its own signal handlers for them.
|
||||
.Fn isc_app_start
|
||||
then initialises a queue of runnable tasks for the application.
|
||||
Calls to
|
||||
.Fn isc_app_start
|
||||
should be made before any other BIND9 library call, ideally as
|
||||
close to the beginning of the application as possible.
|
||||
.Pp
|
||||
.Fn isc_app_onrun
|
||||
arranges for delivery of an event to an application when it is executing.
|
||||
This function should only be invoked after
|
||||
.Fn isc_app_start
|
||||
has been called.
|
||||
It creates an
|
||||
.Ft isc_event_t
|
||||
structure from memory context
|
||||
.Fa mctx
|
||||
for task
|
||||
.Fa task .
|
||||
.Fa arg
|
||||
is a pointer to some structure that can be referenced by the event
|
||||
handler
|
||||
.Fa action
|
||||
which is invoked when the application takes delivery of a shutdown
|
||||
event
|
||||
.Dv ISC_APPEVENT_SHUTDOWN .
|
||||
.Pp
|
||||
An ISC library application is executed by calling
|
||||
.Fn isc_app_run .
|
||||
It should only be used after
|
||||
.Fn isc_app_start
|
||||
has been called.
|
||||
.Fn isc_app_run
|
||||
will not block until any events that have been requested with
|
||||
.Fn isc_app_onrun
|
||||
have been posted.
|
||||
These events will be in FIFO order.
|
||||
Typically
|
||||
.Fn isc_app_run
|
||||
will be called by the initial thread of an application which will then
|
||||
block until shutdown is requested.
|
||||
When a call to
|
||||
.Fn isc_app_run
|
||||
returns, the caller should arrange to shutdown the application.
|
||||
.Pp
|
||||
Applications should be shutdown using
|
||||
.Fn isc_app_shutdown .
|
||||
It can only be invoked after
|
||||
.Fn isc_app_run
|
||||
has been called.
|
||||
.Fn isc_app_shutdown
|
||||
sends a
|
||||
.Dv SIGTERM
|
||||
signal to the current process.
|
||||
Multiple calls to
|
||||
.Fn isc_app_shutdown
|
||||
can be made.
|
||||
Only one shutdown attempt will be carried out.
|
||||
.Pp
|
||||
The reload signal
|
||||
.Dv SIGHUP
|
||||
is sent to the process by
|
||||
.Fn isc_app_reload .
|
||||
The function returns
|
||||
.Er ISC_R_SUCCESS
|
||||
on success or
|
||||
.Er ISC_R_UNEXPECTED
|
||||
if the attempt to send the reload signal fails.
|
||||
.Pp
|
||||
.Fn isc_app_finish
|
||||
should be called at the end of an application which uses the BIND9
|
||||
library.
|
||||
It should be invoked at or near to the end of
|
||||
.Dv main() .
|
||||
The function ensures that any resources allocated by
|
||||
.Fn isc_app_start
|
||||
get released.
|
||||
It therefore follows that
|
||||
.Fn isc_app_finish
|
||||
should only be used if
|
||||
.Fn isc_app_start
|
||||
was called earlier in the application.
|
||||
.Sh RETURN VALUES
|
||||
A successful call to
|
||||
.Fn handle_signal
|
||||
returns
|
||||
.Er ISC_R_SUCCESS
|
||||
and
|
||||
.Er ISC_R_UNEXPECTED
|
||||
is returned if it was unable to set up a signal handler.
|
||||
.Pp
|
||||
.Fn isc_app_start
|
||||
returns
|
||||
.Er ISC_R_SUCCESS
|
||||
or
|
||||
.Er ISC_R_UNEXPECTED
|
||||
depending on whether the signal handlers were successfully installed
|
||||
or not.
|
||||
.Pp
|
||||
.Fn isc_app_onrun
|
||||
returns
|
||||
.Er ISC_R_SUCCESS
|
||||
unless it was not possible to create the event structure
|
||||
.Ft isc_event_t
|
||||
in which case it returns
|
||||
.Er ISC_R_NOMEMORY .
|
||||
.Pp
|
||||
.Fn isc_app_run
|
||||
returns
|
||||
.Er ISC_R_SUCCESS
|
||||
if shutdown has been requested and
|
||||
.Er ISC_R_RELOAD
|
||||
if a reload was requested.
|
||||
.Er ISC_R_UNEXPECTED
|
||||
is returned by
|
||||
.Fn isc_app_run
|
||||
when attempts to set or reset signal handlers fail.
|
||||
.Pp
|
||||
.Er ISC_R_UNEXPECTED
|
||||
is returned by
|
||||
.Fn isc_app_shutdown
|
||||
if the signal was not sent successfully.
|
||||
Otherwise
|
||||
.Fn isc_app_shutdown
|
||||
returns
|
||||
.Er ISC_R_SUCCESS .
|
||||
.Pp
|
||||
Functions which return
|
||||
.Er ISC_R_UNEXPECTED
|
||||
will print an error message on the standard error output,
|
||||
.Dv stderr .
|
||||
.Sh SEE ALSO
|
||||
.Xr sigsetops 3 ,
|
||||
.Xr pthreads 3 ,
|
||||
.Xr kill 2
|
||||
Reference in New Issue
Block a user