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: app.man,v 1.2 2000/06/22 00:52:05 tale Exp $
.Dd Jun 30, 2000 .Dt APP 3 .Os BIND9 9 .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.
p .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.
p 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.
p .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 .
p 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.
p 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.
p 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.
p .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.
p .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.
p .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 .
p .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.
p .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 .
p 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