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.4 2000/08/01 01:18:55 tale Exp $
.Dd Jun 30, 2000 .Dt ISC_APP 3 .Os BIND9 9 .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.
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 handler was 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