bind9/doc/man/app.man

.\"
.\" 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.man,v 1.1 2000/06/01 03:19: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