From 41bf69a3ce42506855d9dfa78ef87ea3505d60bc Mon Sep 17 00:00:00 2001 From: Jim Reid Date: Fri, 23 Jun 2000 00:17:06 +0000 Subject: [PATCH] app.man renamed to app.3 --- doc/man/app.3 | 234 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 doc/man/app.3 diff --git a/doc/man/app.3 b/doc/man/app.3 new file mode 100644 index 0000000000..66a8e573e6 --- /dev/null +++ b/doc/man/app.3 @@ -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 + +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.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