diff --git a/doc/man/isc/isc_app.3 b/doc/man/isc/isc_app.3 new file mode 100644 index 0000000000..c8c803af6f --- /dev/null +++ b/doc/man/isc/isc_app.3 @@ -0,0 +1,247 @@ +.\" +.\" 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: isc_app.3,v 1.1 2000/06/27 21:51:43 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_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 +.Fo handle_signal +.Fa "int sig" +.Fa "void (*handler)(int)" +.Fc +.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 +.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 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 diff --git a/doc/man/isc/isc_dir.3 b/doc/man/isc/isc_dir.3 new file mode 100644 index 0000000000..2b83bfb6d0 --- /dev/null +++ b/doc/man/isc/isc_dir.3 @@ -0,0 +1,166 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" 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: isc_dir.3,v 1.1 2000/06/27 21:51:44 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_DIR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_dir_init , +.Nm isc_dir_open , +.Nm isc_dir_read , +.Nm isc_dir_close , +.Nm isc_dir_reset , +.Nm isc_dir_chdir +.Nd file system directory operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include \*qerrno2result.h\*q +.Ft void +.Fo isc_dir_init +.Fa "isc_dir_t *dir" +.Fc +.Ft isc_result_t +.Fo isc_dir_open +.Fa "isc_dir_t *dir, +.Fa "const char *dirname" +.Fc +.Ft isc_result_t +.Fo isc_dir_read +.Fa "isc_dir_t *dir" +.Fc +.Ft isc_result_t +.Fo isc_dir_close +.Fa "isc_dir_t *dir" +.Fc +.Ft isc_result_t +.Fo isc_dir_chdir +.Fa "const char *dirname" +.Fc +.Sh DESCRIPTION +These functions define the operations performed on the file system's +directories by the name server. +They are intended to isolate BIND9 from the semantics of the underlying +directory access routines provided by the operating system, +BIND9 uses an internal structure of type +.Fa isc_dir_t +to reference a directory. +The contents of this structure are OS-specific. +.Fn isc_dir_init +initialises the directory structure pointed at +.Fa dir . +All functions taking a +.Fa dir +argument must ensure that +this parameter points at a valid +.Fa isc_dir_t +structure. +.Pp +.Fn isc_dir_open +opens the directory named by +.Fa dirname . +.Pp +.Fn isc_dir_read +retrieves the next entry from the file descriptor associated with directory +.Fa dir . +The name of that entry and the length of its name are copied to +.Fa dir . +A successful initial call to +.Fn isc_dir_read +on a directory will populate the +.Fa isc_dir_t +with details of the first valid directory entry. +Subsequent calls fetch the next entries. +.Pp +The +.Fn isc_dir_close +function +closes the file descriptor associated with +.Fa dir . +.Pp +.Fn isc_dir_reset +repositions +.Fa dir +to the start of the directory. +.Pp +The name server's current directory is changed to +.Fa dirname +by +.Fn isc_dir_chdir . +.Pp +.Sh RETURN VALUES +Successful calls to +.Fn isc_dir_open , +.Fn isc_dir_read , +.Fn isc_dir_reset , +.Fn isc_dir_read +and +.Fn isc_dir_chdir +return +.Er ISC_R_SUCCESS . +.Fn isc_dir_read +returns +.Er ISC_R_NOMORE +when there are no more entries in the directory. +.Er ISC_R_UNEXPECTED +is returned if the name of the next directory entry is too big +to fit in the +.Fa isc_dir_t +structure. +If +.Fn isc_dir_chdir +fails, +.Er ISC_R_INVALIDFILE +is returned if +.Fa dirname +is not a directory, or +.Er ISC_R_NOPERM +if access permission is denied or +.Er ISC_R_IOERROR +if an I/O error occurs. +The WinNT version of +.Fn isc_dir_chdir +returns +.Er ISC_R_NOTIMPLEMENTED +when the operating system reports an error that cannot be defined by +either a return value of +.Er ISC_R_NOTFOUND +or +.Er ISC_R_UNEXPECTED . +An error of +.Er ISC_R_FAILURE +can be returned in the WinNT versions of +.Fn isc_dir_open +and +.Fn isc_dir_reset . +.Sh SEE ALSO +.Xr opendir 3 , +.Xr readdir 3 , +.Xr closedir 3 , +.Xr rewinddir 3 , +.Xr chdir 2 diff --git a/doc/man/isc/isc_error.3 b/doc/man/isc/isc_error.3 new file mode 100644 index 0000000000..ca1fe4d186 --- /dev/null +++ b/doc/man/isc/isc_error.3 @@ -0,0 +1,96 @@ +.\" +.\" 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: isc_error.3,v 1.1 2000/06/27 21:51:44 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt error 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc__errno2result +.Nd map POSIX error codes to BIND9 error codes +.Sh SYNOPSIS +.Fd #include + +.Fd #include + +.Fd #include + +.Fd #include "errno2result.h" +.Ft isc_result_t +.Fo isc__errno2result +.Fa "int posixerrno" +.Fc +.Sh DESCRIPTION +.Fn isc__errno2result +maps the POSIX error code +.Fa posixerrno +to its equivalent BIND9 error code. +This function is internal to BIND9. +It is not intended to be called by applications using the BIND9 library. +The function is documented here to indicate how POSIX error codes +are mapped to their ISC equivalents. +.Pp +.Sh RETURN VALUES +When +.Fa posixerrno +is set to the POSIX error codes +.Er ENOTDIR , +.Er ELOOP , +.Er EINVAL , +.Er ENAMETOOLONG , +and +.Er EBADF , +.Fn isc__errno2result +returns +.Er ISC_R_INVALIDFILE . +.Er ISC_R_FILENOTFOUND +is returned when +.Fa posixerrno +is set to +.Er ENOENT . +A retun value of +.Er ISC_R_NOPERM +is produced when the POSIX error code is +.Er EACCES . +If +.Fa posixerrno +is set to +.Er EIO +.Fn isc__errno2result +returns +.Er ISC_R_IOERROR +and if the error code is +.Er ENOMEM , +.Er ISC_R_NOMEMORY +is returned. +For all other values of +.Fa posixerrno , +.Fn isc__errno2result +returns +.Er ISC_R_UNEXPECTED . +.Sh SEE ALSO +.Xr errno 2 , +.Xr perror 3 +.Sh BUGS +Returning +.Er ISC_R_UNEXPECTED +for so many error codes is a little unhelpful. +It would be nice if +.Fn isc__errno2result +produced something more descriptive like the system's error string for +these error codes. diff --git a/doc/man/isc/isc_file.3 b/doc/man/isc/isc_file.3 new file mode 100644 index 0000000000..fde111496d --- /dev/null +++ b/doc/man/isc/isc_file.3 @@ -0,0 +1,173 @@ +.\" +.\" 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: isc_file.3,v 1.1 2000/06/27 21:51:44 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_FILE 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm file_stats , +.Nm isc_file_getmodtime , +.Nm isc_file_settime , +.Nm isc_file_mktemplate , +.Nm isc_file_openunique , +.Nm isc_file_remove +.Nd BIND9 file operation 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 \*qerrno2result.h\*q +.Ft static isc_result_t +.Fo file_stats +.Fa "const char *file" +.Fa "struct stat *stats" +.Fc +.Ft isc_result_t +.Fo isc_file_getmodtime +.Fa "const char *file" +.Fa "isc_time_t *time" +.Fc +.Ft isc_result_t +.Fo isc_file_settime +.Fa "const char *file" +.Fa "isc_time_t *time" +.Fc +.Ft isc_result_t +.Fo isc_file_mktemplate +.Fa "const char *path" +.Fa "char *buf" +.Fa "size_t buflen" +.Fc +.Ft isc_result_t +.Fo isc_file_openunique +.Fa "char *templet" +.Fa "FILE **fp" +.Fc +.Ft isc_result_t +.Fo isc_file_remove +.Fa "const char *filename" +.Fc +.Sh DESCRIPTION +The BIND9 library provides these function calls to manipulate files. +.Pp +.Fn file_stats +performs a +.Fn stat +call on the filename +.Fa file +and stores the result in the +.Dv "struct stat" +.Fa stats . +.Pp +The modification date of filename +.Fa file +is obtained by a call to +.Fn isc_file_getmodtime . +.Fa time +is a pointer to an +.Dv isc_time_t +structure which contains the file's modification date. +.Pp +.Fn isc_file_settime +sets the access and modification times of the file named +.Fa file +to the value of the timestamp supplied in +.Fa time . +.Pp +Pathnames for temporary files are created with +.Fn isc_file_mktemplate . +It copies the pathname in +.Fa path +up to the last \*q/\*q character, if any, in +.Fa buf . +The 14-character string \*qtmp-XXXXXXXXXX\*q is then appended to that +buffer. +.Fa buflen +indicates the size of buffer +.Fa buf . +Calls to +.Fn isc_file_mktemplate +fail if the buffer is too small to hold for the newly-created pathname. +.Pp +.Fn isc_file_openunique +creates a unique file name with access permissions 0600 and opens the +file for reading and writing. +The name of the unique file is returned in +.Fa templet +and a pointer to a pointer to a +.Dv stdio stream +associated with the opened file is returned in +.Fa fp . +The file name template +.Fa templet +should be generated by calling +.Fn isc_file_mktemplate . +This ensures the last 10 characters of the template are the letter \*qX\*q +so that these can be overwritten by +.Fn mkstemp +to generate a unique file name. +.Pp +Files are deleted with +.Fn isc_file_remove . +It unlinks the file named +.Fa filename . +.Sh RETURN VALUES +Successful calls to these functions all return +.Er ISC_R_SUCCESS . +Apart from the exceptions listed below, failed calls return +a BIND9 error code by mapping the corresponding POSIX error code using\p +.Fn isc__errno2result . +.Fn file_stats , +.Fn isc_file_getmodtime +calls +.Fn file_stats +and returns whatever values can be returned by that function. +.Pp +.Fn isc_file_settime +will return +.Er ISC_R_RANGE +if the count of the number of seconds in +.Dv time +is too big to fit in a 32-bit quantity. +.Pp +An error of +.Ev ISC_R_NOSPACE +is returned by +.Fn isc_file_mktemplate +if the pathname overflows the allocated buffer. +.Sh SEE ALSO +.Xr perror 3 , +.Xr isc__errno2result 3 , +.Xr stat 2 , +.Xr isc_time_set 3 , +.Xr utimes 2 , +.Xr mkstemp 3 , +.Xr fdopen 3 , +.Xr unlink 2 . diff --git a/doc/man/isc/isc_ipproto.3 b/doc/man/isc/isc_ipproto.3 new file mode 100644 index 0000000000..856e03a1c3 --- /dev/null +++ b/doc/man/isc/isc_ipproto.3 @@ -0,0 +1,105 @@ +.\" +.\" 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: isc_ipproto.3,v 1.1 2000/06/27 21:51:44 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_IPPROTO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm try_proto , +.Nm initialize_action , +.Nm isc_net_probeipv4 , +.Nm isc_net_probeipv6 +.Nd protocol probe functions +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Ft static isc_result_t +.Fo try_proto +.Fa "int domain" +.Fc +.Ft static void +.Fo initialize_action +.Fc +.Ft isc_result_t +.Fo isc_net_probeipv4 +.Fa void +.Fc +.Ft isc_result_t +.Fo isc_net_probeipv4 +.Fa void +.Fc +.Sh DESCRIPTION +.Fn isc_net_probeipv4 +and +.Fn isc_net_probeipv6 +check that the operating system support the IPv4 and IPv6 protocols +respectively. +They call +.Fn try_proto +which tries to create a socket of type +.Dv SOCK_STREAM +for the appropriate protocol family, +.Fa domain . +.Pp +.Fn initialize_action +sets the external variables +.Dv ipv4_result +and +.Dv ipv6_result +to +.Er ISC_R_SUCCESS +if the IPv4 and IPv6 protocols respectively are supported by the +operating system. +These variables can be tested by applications which need to perform +protocol-specific tasks. +.Sh RETURN VALUES +.Fn isc_net_probeipv4 +returns +.Er ISC_R_SUCCESS +if the IPv4 protocol is supported by the kernel and +.Fn isc_net_probeipv6 +returns +.Er ISC_R_SUCCESS +if the operating system supports IPv6. +.Fn try_proto +returns +.Fn ISC_R_NOTFOUND +if the chosen protocol family +.Fa domain +is not supported by the kernel. +An error message is printed on +.Dv stderr +and +.Er ISC_R_UNEXPECTED +returned if another error occurred when the attempt was made to create +the +.Dv SOCK_STREAM +socket. +.Sh SEE ALSO +.Xr socket 2 , +.Xr ip 4 , +.Xr ipv6 4 . diff --git a/doc/man/isc/isc_netif.3 b/doc/man/isc/isc_netif.3 new file mode 100644 index 0000000000..10cca423b0 --- /dev/null +++ b/doc/man/isc/isc_netif.3 @@ -0,0 +1,259 @@ +.\" +.\" 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: isc_netif.3,v 1.1 2000/06/27 21:51:44 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_NETIF 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_interfaceiter_create , +.\" .Nm internal_current , +.\" .Nm internal_next , +.\" .Nm internal_destroy , +.\" .Nm get_addr , +.Nm isc_interfaceiter_current , +.Nm isc_interfaceiter_first , +.Nm isc_interfaceiter_next , +.Nm isc_interfaceiter_destroy +.Nd network interface management +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include +.Fd #ifdef HAVE_SYS_SOCKIO_H +.Fd #include /* Required for ifiter_ioctl.c. */ +.Fd #endif + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include /* Must follow . */ + +.Ft isc_result_t +.Fo isc_interfaceiter_create +.Fa "isc_mem_t *mctx" +.Fa "isc_interfaceiter_t **iterp" +.Fc +.\" .Ft static isc_result_t +.\" .Fo internal_current +.\" .Fc +.\" .Ft static isc_result_t +.\" .Fo internal_next +.\" .Fc +.\" .Ft static void +.\" .Fo internal_destroy +.\" .Fc +.\" .Ft static void +.\" .Fo get_addr +.\" .Fa "unsigned int family" +.\" .Fa "isc_netaddr_t *dst" +.\" .Fa "struct sockaddr *src" +.\" .Fc +.Ft isc_result_t +.Fo isc_interfaceiter_current +.Fa "isc_interfaceiter_t *iter" +.Fa "isc_interface_t *ifdata" +.Fc +.Ft isc_result_t +.Fo isc_interfaceiter_first +.Fa "isc_interfaceiter_t *iter" +.Fc +.Ft isc_result_t +.Fo isc_interfaceiter_next +.Fa "isc_interfaceiter_t *iter" +.Fc +.Ft void +.Fo isc_interfaceiter_destroy "isc_interfaceiter_t **iter" +.Fc +.Sh DESCRIPTION +Details of the system's network interfaces can be retrieved with +.Fn isc_interfaceiter_create . +It uses +.Xr sysctl 3 +or an +.Dv SIOCGLIFCONF +.Xr ioctl 2 +to get the information from the kernel. +Configuration details of the system's network interfaces - IP addresses, network +mask, status, MAC address, etc. - is stored in a buffer which is +accessed through +.Fa iterp . +Memory is allocated from the memory context +.Fa mctx +to store this information. +The maximum buffer size that can be used to store the configuration +data of all the network interfaces is 1 Megabyte +This data buffer should be far more than enough for a system with a +sensible number of network interfaces. +.Pp +The +.Dv isc_interfaceiter_t +structure is not accessed directly. +The contents of this structure are\p +operating system specific. +They depend on whether the kernel provides a +.Xr sysctl 3 +or +.Dv SIOCGLIFCONF +.Xr ioctl 2 +interface for retreiving network interface details. +Information from the +.Dv isc_interfaceiter_t +can be accessed using +.Fn isc_interfaceiter_current , +.Fn isc_interfaceiter_first +and +.Fn isc_interfaceiter_next . +.\" which use the internal functions +.\" .Fa internal_current +.\" and +.\" .Fa internal_next . +.\" .Pp +.\" .Fn internal_current +.\" gets information for the current network interface from +.\" .Fa iter . +.\" .Fn internal_current +.\" sets +.\" .Dv iter->current +.\" to point at the information about the current interface. +.\" .Fa internal_next +.\" gets the next interface in the list created by +.\" .Fn isc_interfaceiter_create . +.\" Unlike +.\" .Fn isc_interfaceiter_next , +.\" calls to +.\" .Fn internal_next +.\" can position the +.\" .Fa iter +.\" pointers at an interface which will be ignored because it uses an +.\" unsupported address family: a non-IP interface for example. +.\" .Pp +.\" .Fn internal_destroy +.\" does nothing. +.\" It serves as a stub for +.\" .Xr isc_interfaceiter_destroy 3 . +.\" .Pp +.\" .Fn get_addr +.\" extracts the network address part of the +.\" .Dv sockaddr +.\" struct referenced by +.\" .Fa src +.\" and copies it to +.\" .Fa dst . +.\" .Fa family +.\" indicates the address family \*- +.\" .Dv AF_INET +.\" or +.\" .Dv AF_INET6 . +.\" The address family is given explicitly because the network address might +.\" contain a netmask obtained by an +.\" .Dv SIOCGIFNETMASK +.\" .Xr ioctl 2 . +.\" which will not assign a valid address family to +.\" .Dv src->sa_family . +.Pp +.Fn isc_interfaceiter_current +copies the configuration details of +.Fa iter 's +current network interface to +.Fa ifdata . +.Pp +.Fn isc_interfaceiter_first +locates the first network interface in +.Fa iter +which has an address in a supported address family: i.e. an IPv4 or +IPv6 address. +.Fn isc_interfaceiter_next +find the next network interface in the list referenced by +.Fa iter +that has an IPv4 or IPv6 address. +.Pp +The +.Dv isc_interfaceiter_t +structure referenced by +.Fa iterp +is discarded by calling +.Fn isc_interfaceiter_destroy . +Any memory associated with +.Fa iterp is freed. +.Sh RETURN VALUES +Successful calls to +.Fn isc_interfaceiter_create +return +.Er ISC_R_SUCCESS . +The function returns +.Er ISC_R_NOMEMORY +if it was unable to allocate enough memory for the list if network +interfaces. +.Er ISC_R_UNEXPECTED +is returned and an error message printed on +.Dv stderr +if it was not possible to obtain a list of network interfaces. +.\" .Pp +.\" .Fa internal_current +.\" returns +.\" .Er ISC_R_SUCCESS +.\" on success. +.\" If the current interface uses an unsupported address family or if some +.\" operation on the interface fails, the function returns +.\" .Er ISC_R_IGNORE . +.\" .Pp +.\" .Er ISC_R_NOMORE +.\" is returned by +.\" .Fn internal_next +.\" when there are no more entries in the list of interfaces referenced +.\" via +.\" .Fa iter. +.\" It returns +.\" .Er ISC_R_SUCCESS +.\" otherwise. +.Pp +.Fn isc_interfaceiter_current +always returns +.Er ISC_R_SUCCESS +if +.Fa iter +points to a valid +.Dv isc_interfaceiter_t +structure. +.Pp +.Fn isc_interfaceiter_first +and +.Fn isc_interfaceiter_next +return +.Er ISC_R_SUCCESS +on success or +.Er ISC_R_NOMORE +if there are no more network interfaces in +.Fa iter . +.Sh SEE ALSO +.Xr netintro 4, +.Xr sysctl 3 , +.Xr ioctl 2 , +.Xr ifconfig 8 . diff --git a/doc/man/isc/isc_socket.3 b/doc/man/isc/isc_socket.3 new file mode 100644 index 0000000000..c2cc4e3147 --- /dev/null +++ b/doc/man/isc/isc_socket.3 @@ -0,0 +1,899 @@ +.\" +.\" 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: isc_socket.3,v 1.1 2000/06/27 21:51:45 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_SOCKET 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_socket_create , +.Nm isc_socket_attach , +.Nm isc_socket_detach , +.Nm isc_socketmgr_create , +.Nm isc_socketmgr_destroy , +.Nm isc_socket_recvv , +.Nm isc_socket_recv , +.Nm isc_socket_send , +.Nm isc_socket_sendto , +.Nm isc_socket_sendv , +.Nm isc_socket_sendtov , +.Nm isc_socket_bind , +.Nm isc_socket_listen , +.Nm isc_socket_accept , +.Nm isc_socket_connect , +.Nm isc_socket_getpeername , +.Nm isc_socket_getsockname , +.Nm isc_socket_cancel , +.Nm isc_socket_recvmark , +.Nm isc_socket_sendmark , +.Nm isc_socket_gettype , +.Nm isc_socket_isbound +.Nd name server network I/O +.Sh SYNOPSIS +.Fd #include +.Fd +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd +.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 +.Ft isc_result_t +.Fo isc_socket_create +.Fa "isc_socketmgr_t *manager" +.Fa "int pf" +.Fa "isc_sockettype_t type" +.Fa "isc_socket_t **socketp" +.Fc +.Ft void +.Fo isc_socket_attach +.Fa "isc_socket_t *sock" +.Fa "isc_socket_t **socketp" +.Fc +.Ft void +.Fo isc_socket_detach +.Fa "isc_socket_t **socketp" +.Fc +.Ft isc_result_t +.Fo isc_socketmgr_create +.Fa "isc_mem_t *mctx" +.Fa "isc_socketmgr_t **managerp" +.Fc +.Ft void +.Fo isc_socketmgr_destroy +.Fa "isc_socketmgr_t **managerp" +.Fc +.Ft isc_result_t +.Fo isc_socket_recvv +.Fa "isc_socket_t *sock" +.Fa "isc_bufferlist_t *buflist" +.Fa "unsigned int minimum" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_recv +.Fa "isc_socket_t *sock" +.Fa "isc_region_t *region" +.Fa "unsigned int minimum" +.Fa "sc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_send +.Fa "isc_socket_t *sock" +.Fa "isc_region_t *region" +.Fa "sc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_sendto +.Fa "isc_socket_t *sock" +.Fa "isc_region_t *region" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fa "isc_sockaddr_t *address" +.Fa "struct in6_pktinfo *pktinfo" +.Fc +.Ft isc_result_t +.Fo isc_socket_sendv +.Fa "isc_socket_t *sock" +.Fa "isc_bufferlist_t *buflist" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_sendtov +.Fa "isc_socket_t *sock" +.Fa "isc_bufferlist_t *buflist" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fa "isc_sockaddr_t *address" +.Fa "struct in6_pktinfo *pktinfo" +.Fc +.Ft isc_result_t +.Fo isc_socket_bind +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *sockaddr" +.Fc +.Ft isc_result_t +.Fo isc_socket_listen +.Fa "isc_socket_t *sock" +.Fa "unsigned int backlog" +.Fc +.Ft isc_result_t +.Fo isc_socket_accept +.Fa "isc_socket_t *sock" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_connect +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *addr" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_getpeername +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *addressp" +.Fc +.Ft isc_result_t +.Fo isc_socket_getsockname +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *addressp" +.Fc +.Ft void +.Fo isc_socket_cancel +.Fa "isc_socket_t *sock" +.Fa "isc_task_t *task" +.Fa "unsigned int how" +.Fc +.Ft isc_result_t +.Fo isc_socket_recvmark +.Fa "isc_socket_t *sock" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fo isc_socket_sendmark +.Fa "isc_socket_t *sock" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_sockettype_t +.Fo isc_socket_gettype +.Fa "isc_socket_t *sock" +.Fc +.Ft isc_boolean_t +.Fo isc_socket_isbound +.Fa "isc_socket_t *sock" +.Fc +.Sh DESCRIPTION +Applications using the BIND9 library should use the following +functions for interfacing with the operating system's networking +subsystem. +These functions make extensive make use of the two data +structures below which are abstractions from the +.Xr socket 2 +interface provided by most +.Ux +systems. +The contents of these structures should not be manipulated directly. +They should be altered using the functions described below. +.Bd -literal -offset indent +struct isc_socket { + /* Not locked. */ + unsigned int magic; + isc_socketmgr_t *manager; + isc_mutex_t lock; + isc_sockettype_t type; + + /* Locked by socket lock. */ + unsigned int references; + int fd; + isc_result_t recv_result; + isc_result_t send_result; + + ISC_LIST(isc_socketevent_t) send_list; + ISC_LIST(isc_socketevent_t) recv_list; + ISC_LIST(isc_socket_newconnev_t) accept_list; + isc_socket_connev_t *connect_ev; + + /* + * Internal events. Posted when a descriptor is readable or + * writable. These are statically allocated and never freed. + * They will be set to non-purgable before use. + */ + intev_t readable_ev; + intev_t writable_ev; + + isc_sockaddr_t address; /* remote address */ + + unsigned int pending_recv : 1, + pending_send : 1, + pending_accept : 1, + listener : 1, /* listener socket */ + connected : 1, + connecting : 1, /* connect pending */ + bound : 1; /* bound to local addr */ + +#ifdef ISC_NET_RECVOVERFLOW + unsigned char overflow; /* used for MSG_TRUNC fake */ +#endif +#ifdef USE_CMSG + unsigned char *cmsg; + unsigned int cmsglen; +#endif +}; + +typedef struct isc_socket isc_socket_t; +.Ed +.Bd -literal -offset indent +struct isc_socketmgr { + /* Not locked. */ + unsigned int magic; + isc_mem_t *mctx; + isc_mutex_t lock; + /* Locked by manager lock. */ + unsigned int nsockets; /* sockets managed */ + isc_thread_t watcher; + isc_condition_t shutdown_ok; + fd_set read_fds; + fd_set write_fds; + isc_socket_t *fds[FD_SETSIZE]; + int fdstate[FD_SETSIZE]; + int maxfd; + int pipe_fds[2]; +}; + +typedef struct isc_socketmgr isc_socketmgr_t; +.Ed +.Pp +.Fn isc_socket_create +creates a new socket of protocol family +.Fa pf +which is either +.Dv PF_INET +or +.Dv PF_INET6 . +The socket manager +.Fa manager +will be used to control the socket. +.Fa manager +must be a valid socket manager and +.Fa socketp +should be a pointer to a NULL pointer. +The newly-created socket is returned through +.Fa *socketp . +.Pp +.Fn isc_socket_attach +increments the reference count to +to the socket +.Fa sock +and attaches +.Fa *socketp +to socket +.Fa sock . +.Fa sock +must be a pointer to a valid socket. +The reference count on a socket is decremented by calling +.Fn isc_socket_detach . +.Fa *socketp +must be a valid socket pointer. +When the socket's last reference is removed, its reference count +will be zero. +The socket will then be destroyed and any resources associated with it +will be discarded. +.Pp +Socket manager structures +.Dv "struct isc_socketmgr" +are set up and torn down by +.Fn isc_socketmgr_create +and +.Fn isc_socketmgr_destroy +respectively. +Memory from context +.Fa mctx +is allocated for the structure and +.Fa managerp +should point to a NULL +.Dv isc_socketmgr_t . +If +.Fn isc_socketmgr_create +succeeds, +.Fa *managerp +will be a pointer to the created +.Dv "struct isc_socketmgr" . +Calls to +.Fn isc_socketmgr_destroy +will block until there are no sockets left in the manager referenced +by +.Fa *managerp . +If the caller uses this manager to hold any socket references, it will +deadlock itself. +Therefore those sockets should be detached by calling +.Xr isc_socket_detach 3 +before invoking +.Fn isc_socketmgr_destroy . +.Pp +Reading data from a socket is performed by +.Fn isc_socket_recvv +and +.Fn isc_socket_recv . +.Fn isc_socket_recv +reads data into a single region, +.Fa region +while +.Fn isc_socket_recvv +uses a list of buffers +.Fa buflist +for storing the data. +.Fa minimum +indicates how many bytes should be read. +A read done event - +.Dv ISC_SOCKEVENT_RECVDONE +- with the given action +.Fa action +and argument +.Fa arg +gets posted to the event queue of task +.Fa task . +When +.Fa minimum +is non-zero, the completion event will be posted +when at least that number of bytes have been read from the socket +.Fa sock . +If +.Fa minimum +is zero, the completion event is posted when the exact number of bytes +in +.Fa region +or +.Fa buflist +have been read. +This only makes sense for TCP sockets where there is a reasonable guarantee +that a predictable number of bytes can be received. +For UDP sockets, +.Fa minimum +is always set to 1. +The read completes when the requested number of bytes have been +received or if either an error or end of input occurs. +Buffers or regions passed to +.Fn isc_socket_recv +or +.Fn isc_socket_recvv +or any data they refer to +should not be modified by the caller until the completion event has +been received. +When a successful call to +.Fn isc_socket_recvv +completes, +.Fa *buflist +will be empty. +The list of buffers that store the data which has been read are +returned in the done event's +.Dv bufferlist . +.Fa *buflist is unchanged if +.Fn isc_socket_recvv +returns an error. +.Pp +A number of assertion checks are performed by +.Fn isc_socket_recv +and +.Fn isc_socket_recvv . +For both functions, +.Fa sock +should be a valid socket and +.Fa task +should be a valid task. +.Fa action +has to be a valid action. +It must not be NULL. +.Fn isc_socket_recv +checks that +.Fa region +is a valid region. +.Fn isc_socket_recvv +demands that +.Fa buflist +is not NULL and that there is at least one buffer in +.Fa *buflist . +.Pp +The functions +.Fn isc_socket_send , +.Fn isc_socket_sendto , +.Fn isc_socket_sendv +and +.Fn isc_socket_sendtov +are used to send data to the peer for socket +.Fa sock . +The data to be sent are held in either the region +.Fa region +or in multiple buffers referenced through +.Fa buflist . +The contents of the +.Fa region +and +.Fa buflist +structures and their underlying buffers must not be modified by the +caller until the completion event has been received. +A send done event +.Dv ISC_SOCKEVENT_SENDDONE +with action +.Fa action +and argument +.Fa arg +is quueued for task +.Fa task +when the data have been sent. +If +.Fa action +is NULL, no completion event is posted. +.Pp +For +.Fn isc_socket_sendto +and +.Fn isc_socket_sendtov , +.Fa address +is a pointer to the +.Dv "struct isc_sockaddr" +containing the destination address. +If +.Fa sock +is an IPv6 socket (protocol family +.Dv PF_INET6 ) +.Fa pktinfo +is a pointer to the packet info structure +.Dv "struct in6_pktinfo" +for the socket. +.Pp +When +.Fn isc_socket_sendv +or +.Fn isc_socket_sendtov +complete successfully, +.Fa *buflist +will be empty. +The done event's +.Dv bufferlist +will contain the list of the buffers that were used. +.Fa *buflist +is not altered if an error occurs in +.Fn isc_socket_sendv +or +.Fn isc_socket_sendtov . +.Pp +These functions perform a number of assertion checks. +.Fa task +has to be a valid task and +.Fa sock +must be a valid, bound socket. +\fBCONFIRM THIS! Recall recent discussion/bug report about OSes that +don't allow sending data on unnamed sockets - JR\fP +.Fa action +must be either NULL or a valid action. +.Fn isc_socket_send +and +.Fn isc_socket_sendto +insist that +.Fa region +is a valid region. +.Fn isc_socket_sendv +and +.Fn isc_socket_sendtov +check that +.Fa buflist +is non-NULL and that there is at least one buffer in +.Fa *buflist . +.Pp +.Fn isc_socket_send +is a trivial "wrapper" function to +.Fn isc_socket_sendto +while +.Fn isc_socket_sendv +offers a similar service for calls to +.Fn isc_socket_sendtov . +If a task is shut down while it has any writes pending, the outcome is +system-dependent. +Data that has not yet been sent may be discarded or successfully written +to the socket's peer. +.Pp +.Fn isc_socket_bind +associates a name with socket +.Fa sock . +The name that is bound to the socket is given by +.Fa *addressp . +.Pp +To put a socket into listen mode, +.Fn isc_socket_listen +is called. +.Fa sock +must be a valid socket. +Once the socket +.Fa sock +is in listen mode, it can only be used in calls to +.Fn isc_socket_accept , +.Fn isc_socket_attach +and +.Fn isc_socket_detach . +.Fa backlog +has the usual meaning for the +.Xr listen 2 +system call in +.Ux . +It specifies the maximum number of pending connections that can be +queued waiting for the application to +.Xr accept 2 +them. +If +.Fa backlog +is zero, a reasonable system default is used, typically +.Dv SOMAXCONN . +The value of +.Fa backlog +may be ignored on other operating systems. +.Pp +.Fn isc_socket_accept +is used to queue an accept event when an incoming connection request +is made. +Task +.Fa task +gets a +.Dv ISC_SOCKEVENT_NEWCONN +event with the sender set to socket +.Fa sock +which was previously put into listen mode by +.Fn isc_socket_listen . +The new socket structure is attached to task +.Fa task +It is made available through the +.Dv isc_socket_newconnev_t +event type. +The function has assertion checks to ensure that +.Fa sock +is a valid socket and is in listen mode. +.Pp +.Fn isc_socket_connect +connects socket +.Fa sock +to the peer with address +.Fa addr . +When the connection completes - either on success or if an error +occurs - a +.Dv ISC_SOCKEVENT_CONNECT +event with action +.Fa action +and argument +.Fa arg is posted to the event queue for task +.Fa task . +The function's assertion checks ensure that +.Fa sock +is a valid TCP socket and +.Fa addressp +points to a valid +.Dv "struct isc_sockaddr" . +The checks also make sure that +.Fa task +and +.Fa action +are valid tasks and actions respectively. +.Pp +.Fn isc_socket_getpeername +returns the name of the peer connected to socket +.Fa sock . +and copies it to +.Fa addressp . +.Fn isc_socket_getsockname +gets the name of socket +.Fa sock +and copies it to +.Fa addressp . +Both functions have assertion checks to ensure that +.Fa sock +is a valid socket +and that +.Fa *addressp +is not NULL. +.Pp +Socket events that hav been queued for some task can be cancelled using +.Fn isc_socket_cancel . +.Fa sock +and +.Fa task +are a valid socket and task pointers respectively. +.Fa how +is a bitmask of the events that are to be cancelled. +Possible values for +.Fa how +are any combination of +.Dv ISC_SOCKCANCEL_RECV , +.Dv ISC_SOCKCANCEL_SEND , +.Dv ISC_SOCKCANCEL_ACCEPT +and +.Dv ISC_SOCKCANCEL_CONNECT . +When the events are cancelled, +.Fn isc_socket_cancel +attempts to remove it from the task's queue. +If this fails, the event is marked as cancelled and the task +is expected to clean it up later. +A done event with status +.Dv ISC_R_CANCELED +is posted for each cancelled event and any necessary state information +is reset. +.Pp +.Fn isc_socket_recvmark +and +.Fn isc_socket_sendmark +insert a receive or send marker for socket +.Fa sock . +The marker gets processed when all I/O requests in the the task +.Fa task 's +queue have been processed. +If that queue is empty, the event is posted immediately to that task. +Both functions check that +.Fa sock , +.Fa task +and +.Fa action +are a valid socket, task and action respectively. +.Pp +When the event handler returns, its +.Dv result +member can sometimes contain useful information. +Depending on the marker type, the event's +.Dv result member +will contain the same error that the last +.Fn isc_socket_recv , +.Fn isc_socket_send +.Fn isc_socket_sendto +if the mark was processed after a fatal error. +.Pp +.Fn isc_socket_gettype +returns the type of socket - UDP or TCP - for +.Fa sock , +which must be a valid socket. +.Fn isc_socket_isbound +returns +.Er ISC_TRUE +or +.Er ISC_FALSE +depending on whether the socket +.Fa sock +has been bound to a name or not: in other words if +.Fn isc_socket_bind +has been successfully invoked on the socket. +.Sh RETURN VALUES +A successful call to +.Fn isc_socket_create +returns +.Er ISC_R_SUCCESS . +.Er ISC_R_NORESOURCES +if the operating system was unable to allocate resources for the +socket: typically buffers or file descriptors. +If the +.Fn isc_socket_create +is unable to allocate memory for the socket, +.Er ISC_R_NOMEMORY +is returned. +Unexpected errors - for instance when setting options on the new +socket - return +.Er ISC_R_UNEXPECTED . +.Pp +.Fn isc_socketmgr_create +returns +.Er ISC_R_SUCCESS +on success. +The function returns +.Er ISC_R_NOMEMORY +if the BIND9 library was unable to allocate memory for the socket +manager structure. +.Er ISC_R_UNEXPECTED +is returned if it was not possible to initialise the +.Dv "struct isc_socketmgr" . +.Pp +Successful calls to +.Fn isc_socket_recv +and +.Fn isc_socket_recvv +return +.Er ISC_R_SUCCESS . +They return +.Er ISC_R_NOMEMORY +if it was not possible to allocate memory for a +socket event handler. +The handler that is invoked for +the +.Dv ISC_SOCKEVENT_RECVDONE +when the socket read +completes will return +.Er ISC_R_SUCCESS +on success or +.Er ISC_R_UNEXPECTED +if it encounters an error. +.Pp +The functions +.Fn isc_socket_sendto , +.Fn isc_socket_sendtov , +.Fn isc_socket_send +and +.Fn isc_socket_sendv +all return +.Er ISC_R_SUCCESS +on success. +If these four functions are unable to allocate memory when setting up +an event handler, they return +.Er ISC_R_NOMEMORY . +The event handler that is invoked when a +.Dv ISC_SOCKEVENT_SENDDONE +event is posted when socket write +completes returns +.Er ISC_R_SUCCESS +on success. +It returns +.Er ISC_R_UNEXPECTED +if an error occurs. +.Pp +Successful calls to +.Fn isc_socket_bind +return +.Er ISC_R_SUCCESS . +The function returns +.Er ISC_R_NOPERM +if the requested address needs a privileged port, and the current user +does no have sufficient permission to access it. +.Er ISC_R_ADDRNOTAVAIL +is returned if the specified address is not available. +.Fn isc_socket_bind +returns +.Er ISC_R_ADDRINUSE +if the address is already in use and +.Er ISC_R_BOUND +if +.Fa sock had already been bound to an address. +.Er ISC_R_UNEXPECTED +is returned for any other error conditions that are reported by +.Xr bind 2 +and an error message printed on +.Dv stderr . +.Pp +.Fn isc_socket_listen +returns +.Er ISC_R_SUCCESS +on success. +.Er ISC_R_UNEXPECTED +is returned and an error message printed on +.Dv stderr +if the +.Xr listen 2 +system call fails. +.Pp +.Er ISC_R_NOMEMORY +is returned by +.Fn isc_socket_accept +if it was unable to allocate memory for the new socket or the event +handler. +.Er ISC_R_SUCCESS +is returned on success. +.Pp +.Fn isc_socket_connect +returns +.Er ISC_R_NOMEMORY +if there was a memory allocation problem +or +.Er ISC_R_UNEXPECTED +if the call to +.Xr connect 2 +fails. +.Er ISC_R_SUCCESS +is returned otherwise. +The event handler returns +.Er ISC_R_SUCCESS +when the connection attempt completes successfully. +It returns +.Er ISC_R_TIMEDOUT +when the connection attempt times out or +.Er ISC_R_CONNREFUSED +if the peer +.Fa addr +refused the connection. +An error of +.Er ISC_R_NETUNREACH +if the peer's network isn't reachable. +Other error conditions from +.Xr connect 2 +return +.Er ISC_R_UNEXPECTED . +.Pp +If the socket +.Fa sock +is connected, +.Fa isc_socket_getpeername +returns +.Er ISC_R_SUCCESS +and +.Er ISC_R_NOTCONNECTED +otherwise. +.Fn isc_socket_getsockname +normally returns +.Er ISC_R_SUCCESS. +It returns +.Er ISC_R_NOTBOUND +if +.Fa sock +is not bound. +.Er ISC_R_UNEXPECTED +is returned and an error message logged on +.Dv stderr +if +.Xr getsockname 2 +failed +.Pp +.Fn isc_socket_recvmark +and +.Fn isc_socket_sendmark +always return +.Er ISC_R_SUCCESS +unless they were unable to set up an event handler, in which case they +return +.Er ISC_R_NOMEMORY . +.Sh SEE ALSO +.Xr socket 2 , +.Xr readv 2 +.Xr recv 2 , +.Xr writev 2 , +.Xr send 2 , +.Xr sendto 2 , +.Xr bind 2 , +.Xr listen 2 , +.Xr accept 2 , +.Xr connect 2 , +.Xr getpeername 2 , +.Xr getsockname 2 . diff --git a/doc/man/isc/isc_stdio.3 b/doc/man/isc/isc_stdio.3 new file mode 100644 index 0000000000..2959e008c7 --- /dev/null +++ b/doc/man/isc/isc_stdio.3 @@ -0,0 +1,193 @@ +.\" +.\" 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: isc_stdio.3,v 1.1 2000/06/27 21:51:45 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_STDIO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_stdio_open , +.Nm isc_stdio_close , +.Nm isc_stdio_seek , +.Nm isc_stdio_read , +.Nm isc_stdio_write , +.Nm isc_stdio_flush , +.Nm isc_stdio_sync +.Nd BIND9 interface to stdio functions +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include + +.Fd #include + +.Fd #include \*qerrno2result.h\*q + +.Ft isc_result_t +.Fo isc_stdio_open +.Fa "const char *filename" +.Fa "const char *mode" +.Fa "FILE **fp" +.Fc +.Ft isc_result_t +.Fo isc_stdio_close +.Fa "FILE *f" +.Fc +.Ft isc_result_t +.Fo isc_stdio_seek +.Fa "FILE *f" +.Fa "long offset" +.Fa "int whence" +.Fc +.Ft isc_result_t +.Fo isc_stdio_read +.Fa "void *ptr" +.Fa "size_t size" +.Fa "size_t nmemb" +.Fa "FILE *f" +.Fa "size_t *nret" +.Fc +.Ft isc_result_t +.Fo isc_stdio_write +.Fa "void *ptr" +.Fa "size_t size" +.Fa "size_t nmemb" +.Fa "FILE *f" +.Fa "size_t *nret" +.Fc +.Ft isc_result_t +.Fo isc_stdio_flush +.Fa "FILE *f" +.Fc +.Ft isc_result_t +.Fo isc_stdio_sync +.Fa "FILE *f" +.Fc +.Sh DESCRIPTION +The BIND9 library uses the following routines for standard I/O +operations. +These functions call their equivalents in the operating system's stdio +library. +.Pp +.Fn isc_stdio_open +opens the file +.Fa filename +with access mode +.Fa mode . +The string +.Fa mode +should correspond to the +.Fa mode +parameter in +.Xr fopen 3 . +If the file open succeeds, +.Fa fp +contains a pointer to the pointer to the relevant stdio +.Dv FILE +structure. +Files get closed by calling +.Fn isc_stdio_close . +.Fa fp +should be a pointer to the +.DV FILE +structure that was returned by an earlier call to +.Fn isc_stdio_open . +.Pp +The file position indicator for a stdio stream is adjusted with +.Fn isc_stdio_seek . +.Fa f +is the +.Dv FILE +pointer and +.Fa offset +and +.Fa whence +have the usual meanings. +The new position is found by adding +.Fa offset +bytes to the position specified by +.Fa whence +which is set to the values +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END . +These values indicate the new position is calculated relative to the start +of the file, the current position indicator, or end of file +respectively. +.Pp +Reading and writing on a stdio stream is performed using +.Fn isc_stdio_read +and +.Fn isc_stdio_write +respectively. +The function +.Fn isc_stdio_read +reads reads +.Fa nmemb +objects, each +.Fa size +bytes long, from the stream pointed to by +.Fa f . +The objects are stored at the location given by +.Fa ptr . +.Fa isc_stdio_write +writes +.Fa nmemb +objects, each +.Fa size +bytes long, from location +.Fa ptr +to the stream +.Fa f . +The number of objects written is returned via +.Fa nret . +If this is less than +.Fa nmemb , +some type of write error occurred. +.Pp +A +.Xr write 2 +of buffered data associated with the output +.Fa f +can be forced with +.Fn isc_stdio_flush . +This data can be committed to permanent storage by +.Fn isc_stdio_sync +which will invoke +.Xr fsync 2 . +.Sh RETURN VALUES +Successful calls to all these functions return +.Er ISC_R_SUCCESS . +If the calls fail, the error code returned by the operating system is +mapped to the appropriate BIND9 error code by calling +.Xr isc__errno2result 3 . +.Fn isc_stdio_read +returns +.Er ISC_R_EOF +at end of file. +.Sh SEE ALSO +.Xr stdio 3 , +.Xr fopen 3 , +.Xr fclose 3 , +.Xr fread 3 , +.Xr fwrite 3 , +.Xr fflush 3 , +.Xr fsync 2 , +.Xr isc__errno2result 3 . diff --git a/doc/man/isc/isc_stdtime.3 b/doc/man/isc/isc_stdtime.3 new file mode 100644 index 0000000000..e604e1f060 --- /dev/null +++ b/doc/man/isc/isc_stdtime.3 @@ -0,0 +1,62 @@ +.\" +.\" 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: isc_stdtime.3,v 1.1 2000/06/27 21:51:45 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_STDTIME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_stdtime_get +.Nd get the current date and time +.Sh SYNOPSIS +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include + +.Ft void +.Fo isc_stdtime_get +.Fa "isc_stdtime_t *t" +.Fc +.Sh DESCRIPTION +.Fn isc_stdtime_get +sets +.Fa t +to the number of seconds since the UNIX epoch, 00:00:00 UTC, January +1, 1970. +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr isc_time_now 3 . +.Sh BUGS +A time synchronisation protocol such as NTP is needed to ensure that +the kernel's concept of the current time is accurate. +.Pp +At 03:14:08 GMT on Tue Jan 19 2038, the number of seconds since +the UNIX epoch will overflow a 32-bit signed integer. +This may cause unpredictable behaviour on systems which treat these +timestamps as 32-bit signed quantities. +.Dv isc_stdtime_t +is defined as a 32-bit unsigned quantity, which means +.Fn isc_stdtime_get +should be safe until some time in 2106. +Applications that +want maximum portability should not assume anything about the size +of a +.Dv isc_stdtime_t . diff --git a/doc/man/isc/isc_time.3 b/doc/man/isc/isc_time.3 new file mode 100644 index 0000000000..cd5280f0a8 --- /dev/null +++ b/doc/man/isc/isc_time.3 @@ -0,0 +1,338 @@ +.\" +.\" 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: isc_time.3,v 1.1 2000/06/27 21:51:45 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt ISC_TIME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm time +.Nd time-related operations +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Ft void +.Fo "isc_interval_set" +.Fa "isc_interval_t *i" +.Fa "unsigned int seconds" +.Fa "unsigned int nanoseconds" +.Fc +.Ft isc_boolean_t +.Fo isc_interval_iszero +.Fa "isc_interval_t *" +.Fc +.Ft void +.Fo isc_time_set +.Fa "isc_time_t *t" +.Fa "unsigned int seconds" +.Fa "unsigned int nanoseconds" +.Fc +.Ft void +.Fo isc_time_settoepoch +.Fa "isc_time_t *t" +.Fc +.Ft isc_boolean_t +.Fo isc_time_isepoch +.Fa "isc_time_t *t" +.Fc +.Ft isc_result_t +.Fo isc_time_now +.Fa "isc_time_t *t" +.Fc +.Ft isc_result_t +.Fo isc_time_nowplusinterval +.Fa "isc_time_t *t" +.Fa "isc_interval_t *i" +.Fc +.Ft int +.Fo isc_time_compare +.Fa "isc_time_t *t1" +.Fa "isc_time_t *t2" +.Fc +.Ft isc_result_t +.Fo isc_time_add +.Fa "isc_time_t *t" +.Fa "isc_interval_t *i" +.Fa "isc_time_t *result" +.Fc +.Ft isc_result_t +.Fo isc_time_subtract +.Fa "isc_time_t *t" +.Fa "isc_interval_t *i" +.Fa "isc_time_t *result" +.Fc +.Ft isc_uint64_t +.Fo isc_time_microdiff +.Fa "isc_time_t *t1" +.Fa "isc_time_t *t2" +.Fc +.Ft isc_uint32_t +.Fo isc_time_seconds +.Fa "isc_time_t *t" +.Fc +.Ft isc_result_t +.Fo isc_time_secondsastimet +.Fa "isc_time_t *t" +.Fa "time_t *secondsp" +.Fc +.Ft isc_uint32_t +.Fo isc_time_nanoseconds +.Fa "isc_time_t *t" +.Fc +.Sh DESCRIPTION +These functions are used by the name server for any time-related activities. +They operate on the system's struct +.Nm time_t +and two local data structures: +.Bd -literal -offset indent +struct isc_interval { + unsigned int seconds; + unsigned int nanoseconds; +}; + +typedef struct isc_interval isc_interval_t; +.Ed +.Bd -literal -offset indent +struct isc_time { + unsigned int seconds; + unsigned int nanoseconds; +}; + +typedef struct isc_time isc_time_t; +.Ed +The contents of these structures are private +and MUST NOT be accessed by callers directly. +Details have only been provided so that callers can avoid +dynamic allocation. +The elements of these structures should only be manipulated via the +following functions. +.Pp +The function +.Fn isc_interval_set +initialises the +.Nm isc_interval_t +pointed at by +.Fa *i . +The elements +.Nm seconds +and +.Nm +nanoseconds +are set to the values of +.Fa seconds +and +.Fa nanoseconds +respectively. +.Pp +.Fn isc_interval_iszero +returns +.Er ISC_TRUE +if +.Fa *i +is the zero interval. +This condition should hold when the desired amount of time until an +event associated with interval +.Fa *i +has elapsed. +.Pp +.Fn isc_time_settoepoch +sets +.Fa *t +to the time of the epoch. +On +.Ux +systems this is 0 hours, 0 minutes, 0 seconds, January 1, 1970 UTC. +.Pp +The function +.Fn isc_time_isepoch +returns +.Er ISC_TRUE +if the time in +.Fa *t +is equal to the epoch time: "time zero". +It returns +.Er ISC_FALSE +otherwise. +.Pp +The current absolute time of day is obtained from +.Fn isc_time_now . +On a successful call to this function, the structure pointed at by +.Fa *t +is set to the number of seconds and nanoseconds since the epoch. +.Pp +.Fn isc_time_nowplusinterval +sets +.Fa *t +to the current time plus the interval specified in +.Fa *i . +.Pp +.Fn isc_time_compare +compares the times referenced by +.Fa *t1 +and +.Fa *t2 . +It returns 0 if the two times are equal. +A value of 1 is returned when +.Fa *t1 +is greater than +.Fa *t2 . +If +.Fa *t1 +is less than +.Fa *t2 +.Fn isc_time_compare +returns -1. +.Pp +The function +.Fn isc_time_add +adds +.Fa *i +to +.Fa *t +and +.Fa *result . +The converse operation is performed by +.Fa isc_time_subtract . +It subtracts +.Fa *i +from +.Fa *t +and stores the result in +.Fa result . +.Pp +.Fn isc_time_microdiff +returns the number of difference in microseconds between +.Fa *t1 +and +.Fa *t2. +Zero is returned if the time represented by +.Fa *t1 +is less than that given by +.Fa t2 . +.Pp +.Fn isc_time_seconds +and +.Fn isc_time_nanoseconds +return the number of seconds and nanoseconds respectively +in the time indicated by +.Fa *t . +.Pp +The function +.Fn isc_time_secondsastimet +converts the time value represented by +.Fa *t +to the system's +.Dv time_t +struct pointed at by +.Fa *secondsp . +It takes great care to ensure that the number of seconds represented +by +.Dv t->seconds +can be represented by a +.Dv time_t . +This is not as straightforward as it might seem because a +.Dv time_t +might not be an integral type. +Implementations may treat this type as a signed or unsigned quantity +which potentially creates sign extension problems. +.Sh RETURN VALUES +.Fn isc_time_now +and +.Fn isc_time_nowplusinterval +return +.Er ISC_R_UNEXPECTED +if they are unable to get the time of day or if the operating system returns +nonsense. +They return +.Er ISC_R_RANGE +if the number of seconds returned by the operating system is too big +to fit in a +.Dv "unsigned int" . +A result of +.Er ISC_R_SUCCESS +is returned when the functions are successful. +.Pp +Calls to +.Fn isc_time_add , +.Fn isc_time_subtract +and +.Fn isc_time_secondsastimet +normally return +.Er ISC_R_SUCCESS . +.Fn isc_time_add +returns +.Er ISC_R_RANGE +if the addition of the time values represented by +.Fa t +and +.Fa i +result in a number of seconds that are too big to fit in a +.Dv "unsigned int" +quantity. +If the time value given by +.Fa i +is less than that in +.Fa t , +.Er ISC_R_RANGE +is returned by +.Fn isc_time_subtract . +.Er ISC_R_RANGE +is returned by +.Fn isc_time_secondsastimet +when the number of seconds represented by +.Dv t->seconds +cannot be represented by the operating system's +.Dv time_t +type. +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr getitimer 2 , +.Xr ctime 3 +.Sh BUGS +Nanosecond and microsecond resolution time values are notoriously +inaccurate on most +.Ux +systems because few, if any, of them have +hardware or software which provides that level of precision. +Consult the vendor's documentation. +The resolution of the real-time clock in most systems is typically +100Hz which means the finest granularity of time-related activity is +at most 0.01 seconds. +Scheduling latency and process or thread context switching can also +delay the processing of real-time events. +For most DNS activity such as decrementing TTLs or zone refreshes, +this loss of accuracy is not significant. +.Pp +The accuracy of absolute times returned by +.Fn isc_time_now +and +.Fn isc_time_nowplusinterval +depend on the reliability of the system's time of day clock. +This should be synchronised to UTC using an external time source using +a good timekeeping protocol such as NTP. +Pedants might want to worry about whether the absolute time includes +leap seconds or not.