acb9a3c446
literal blocks. update_copyrights has been fixed to cope with the lack of empty lines around the cvs id tag's line in each man source.
229 lines
5.4 KiB
Groff
229 lines
5.4 KiB
Groff
.\" Copyright (C) 2000, 2001 Internet Software Consortium.
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software 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: isc_app.3,v 1.5.4.2 2001/06/14 06:20:11 tale Exp $
|
|
.\"
|
|
.Dd Jun 30, 2000
|
|
.Dt ISC_APP 3
|
|
.Os BIND9 9
|
|
.ds vT BIND9 Programmer's Manual
|
|
.Sh NAME
|
|
.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 isc_result_t
|
|
.Fo isc_app_start
|
|
.Fa void
|
|
.Fc
|
|
.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
|
|
.Fo isc_app_run
|
|
.Fa void
|
|
.Fc
|
|
.Ft isc_result_t
|
|
.Fo isc_app_shutdown
|
|
.Fa void
|
|
.Fc
|
|
.Ft isc_result_t
|
|
.Fo isc_app_reload
|
|
.Fa void
|
|
.Fc
|
|
.Ft void
|
|
.Fo isc_app_finish
|
|
.Fa void
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
These functions define the interface for creating and terminating
|
|
applications which use the BIND9 library.
|
|
.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 handler was 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
|