From: Andreas Gustafsson Date: Fri, 28 Jul 2000 01:44:38 +0000 (+0000) Subject: removed old man page files from release branch (they had X-Git-Tag: v9.0.0rc2~42 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=73e9b7f6cb4a56ed7f3cd93cf6114ddf8f5025c3;p=thirdparty%2Fbind9.git removed old man page files from release branch (they had already been removed from the mainline --- diff --git a/doc/man/app.3 b/doc/man/app.3 deleted file mode 100644 index 66a8e573e6c..00000000000 --- a/doc/man/app.3 +++ /dev/null @@ -1,234 +0,0 @@ -.\" -.\" 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 diff --git a/doc/man/app.man b/doc/man/app.man deleted file mode 100644 index 15928f6b59b..00000000000 --- a/doc/man/app.man +++ /dev/null @@ -1,233 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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 -.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 diff --git a/doc/man/dir.3 b/doc/man/dir.3 deleted file mode 100644 index 695a05869b9..00000000000 --- a/doc/man/dir.3 +++ /dev/null @@ -1,155 +0,0 @@ -.\" -.\" 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: dir.3,v 1.1 2000/06/23 00:30:11 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt FSDIR 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 -.Fn isc_dir_init "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_open "isc_dir_t *dir, const char *dirname" -.Ft isc_result_t -.Fn isc_dir_read "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_close "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_chdir "const char *dirname" -.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/dir.man b/doc/man/dir.man deleted file mode 100644 index c3840a445eb..00000000000 --- a/doc/man/dir.man +++ /dev/null @@ -1,152 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: dir.man,v 1.2 2000/06/22 00:52:08 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt FSDIR 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 -.Fn isc_dir_init "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_open "isc_dir_t *dir, const char *dirname" -.Ft isc_result_t -.Fn isc_dir_read "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_close "isc_dir_t *dir" -.Ft isc_result_t -.Fn isc_dir_chdir "const char *dirname" -.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/error.3 b/doc/man/error.3 deleted file mode 100644 index 55e7b806d8f..00000000000 --- a/doc/man/error.3 +++ /dev/null @@ -1,90 +0,0 @@ -.\" -.\" 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: error.3,v 1.1 2000/06/23 00:30:11 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 -.Fn isc__errno2result "int posixerrno" -.Sh DESCRIPTION -.Fn isc__errno2result -maps the POSIX error code -.Fa posixerrno -to its equivalent BIND9 error code. -.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/error.man b/doc/man/error.man deleted file mode 100644 index b4242003d1a..00000000000 --- a/doc/man/error.man +++ /dev/null @@ -1,89 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: error.man,v 1.2 2000/06/22 00:52:09 tale 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 -.Fn isc__errno2result "int posixerrno" -.Sh DESCRIPTION -.Fn isc__errno2result -maps the POSIX error code -.Fa posixerrno -to its equivalent BIND9 error code. -.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/file.3 b/doc/man/file.3 deleted file mode 100644 index 63a895dfb4d..00000000000 --- a/doc/man/file.3 +++ /dev/null @@ -1,155 +0,0 @@ -.\" -.\" 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: file.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn file_stats "const char *file" "struct stat *stats" -.Ft isc_result_t -.Fn isc_file_getmodtime "const char *file" "isc_time_t *time" -.Ft isc_result_t -.Fn isc_file_settime "const char *file" "isc_time_t *time" -.Ft isc_result_t -.Fn isc_file_mktemplate "const char *path" "char *buf" "size_t buflen" -.Ft isc_result_t -.Fn isc_file_openunique "char *templet" "FILE **fp" -.Ft isc_result_t -.Fn isc_file_remove "const char *filename" -.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/file.man b/doc/man/file.man deleted file mode 100644 index caa97010d03..00000000000 --- a/doc/man/file.man +++ /dev/null @@ -1,154 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: file.man,v 1.2 2000/06/22 00:52:10 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn file_stats "const char *file" "struct stat *stats" -.Ft isc_result_t -.Fn isc_file_getmodtime "const char *file" "isc_time_t *time" -.Ft isc_result_t -.Fn isc_file_settime "const char *file" "isc_time_t *time" -.Ft isc_result_t -.Fn isc_file_mktemplate "const char *path" "char *buf" "size_t buflen" -.Ft isc_result_t -.Fn isc_file_openunique "char *templet" "FILE **fp" -.Ft isc_result_t -.Fn isc_file_remove "const char *filename" -.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/ipproto.3 b/doc/man/ipproto.3 deleted file mode 100644 index 84c3471b4b7..00000000000 --- a/doc/man/ipproto.3 +++ /dev/null @@ -1,98 +0,0 @@ -.\" -.\" 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: ipproto.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn try_proto "int domain" -.Ft static void -.Fn initialize_action -.Ft isc_result_t -.Fn isc_net_probeipv4 void -.Ft isc_result_t -.Fn isc_net_probeipv4 void -.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/ipproto.man b/doc/man/ipproto.man deleted file mode 100644 index 55d9922deb7..00000000000 --- a/doc/man/ipproto.man +++ /dev/null @@ -1,97 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: ipproto.man,v 1.2 2000/06/22 00:52:11 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn try_proto "int domain" -.Ft static void -.Fn initialize_action -.Ft isc_result_t -.Fn isc_net_probeipv4 void -.Ft isc_result_t -.Fn isc_net_probeipv4 void -.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/netif.3 b/doc/man/netif.3 deleted file mode 100644 index 33f41c98591..00000000000 --- a/doc/man/netif.3 +++ /dev/null @@ -1,242 +0,0 @@ -.\" -.\" 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: netif.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_interfaceiter_create "isc_mem_t *mctx" "isc_interfaceiter_t **iterp" -.Ft static isc_result_t -.Fn internal_current -.Ft static isc_result_t -.Fn internal_next -.Ft static void -.Fn internal_destroy -.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 -.Fn isc_interfaceiter_first "isc_interfaceiter_t *iter" -.Ft isc_result_t -.Fn isc_interfaceiter_next "isc_interfaceiter_t *iter" -.Ft void -.Fn isc_interfaceiter_destroy "isc_interfaceiter_t **iter" -.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. -The -.Dv isc_interfaceiter_t -structure is not accessed directly. -Information is\p -obtained using -.Fa isc_interfaceiter_current , -.Fa isc_interfaceiter_first -and -.Fa 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 -.Fa iter 's -list 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 isc_interfaceiter_current 3 , -.Xr isc_interfaceiter_first 3 , -.Xr isc_interfaceiter_next 3 , -.Xr isc_interfaceiter_destroy 3 , -.Xr ifconfig 8 . diff --git a/doc/man/netif.man b/doc/man/netif.man deleted file mode 100644 index 853d0206f83..00000000000 --- a/doc/man/netif.man +++ /dev/null @@ -1,241 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: netif.man,v 1.2 2000/06/22 00:52:12 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_interfaceiter_create "isc_mem_t *mctx" "isc_interfaceiter_t **iterp" -.Ft static isc_result_t -.Fn internal_current -.Ft static isc_result_t -.Fn internal_next -.Ft static void -.Fn internal_destroy -.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 -.Fn isc_interfaceiter_first "isc_interfaceiter_t *iter" -.Ft isc_result_t -.Fn isc_interfaceiter_next "isc_interfaceiter_t *iter" -.Ft void -.Fn isc_interfaceiter_destroy "isc_interfaceiter_t **iter" -.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. -The -.Dv isc_interfaceiter_t -structure is not accessed directly. -Information is\p -obtained using -.Fa isc_interfaceiter_current , -.Fa isc_interfaceiter_first -and -.Fa 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 -.Fa iter 's -list 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 isc_interfaceiter_current 3 , -.Xr isc_interfaceiter_first 3 , -.Xr isc_interfaceiter_next 3 , -.Xr isc_interfaceiter_destroy 3 , -.Xr ifconfig 8 . diff --git a/doc/man/socket.3 b/doc/man/socket.3 deleted file mode 100644 index a770bb8dd1d..00000000000 --- a/doc/man/socket.3 +++ /dev/null @@ -1,900 +0,0 @@ -.\" -.\" 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: socket.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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/socket.man b/doc/man/socket.man deleted file mode 100644 index 741946a9117..00000000000 --- a/doc/man/socket.man +++ /dev/null @@ -1,220 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: socket.man,v 1.2 2000/06/22 00:52:13 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt XXXXXX 3 -.Os BIND9 9 -.ds vT BIND9 Programmer's Manual -.Sh NAME -FUNCTION NAME/RETURN COUNT MISMATCH -.Nm select_poke , -.Nm select_readmsg , -.Nm make_nonblock , -.Nm process_cmsg , -.Nm dump_msg , -.Nm doio_recv , -.Nm doio_send , -.Nm destroy , -.Nm free_socket , -.Nm isc_socket_attach , -.Nm isc_socket_detach , -.Nm dispatch_recv , -.Nm dispatch_send , -.Nm dispatch_accept , -.Nm dispatch_connect , -.Nm internal_accept , -.Nm internal_recv , -.Nm internal_send , -.Nm watcher , -.Nm isc_socketmgr_create , -.Nm isc_socketmgr_destroy , -.Nm isc_socket_bind , -.Nm isc_socket_listen , -.Nm internal_connect , -.Nm isc_socket_getpeername , -.Nm isc_socket_getsockname , -.Nm isc_socket_cancel , -.Nm isc_socket_gettype , -.Nm isc_socket_isbound -.Nd XXX -.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 struct isc_socket { -.Fo select_poke -.Fa "isc_socketmgr_t *mgr" -.Fa "int msg" -.Fc -.Ft struct isc_socketmgr { -.Fo select_readmsg -.Fa "isc_socketmgr_t *mgr" -.Fc -.Ft static void -.Fo make_nonblock -.Fa "int fd" -.Fc -.Ft static void -.Fo process_cmsg -.Fa "isc_socket_t *sock" -.Fa "struct msghdr *msg" -.Fa "isc_socketevent_t *dev" -.Fc -.Ft static void -.Fo dump_msg -.Fa "struct msghdr *msg" -.Fc -.Ft static int -.Fo doio_recv -.Fa "isc_socket_t *sock" -.Fa "isc_socketevent_t *dev" -.Fc -.Ft static isc_result_t -.Fo doio_send -.Fa "isc_socket_t *sock" -.Fa "isc_socketevent_t *dev" -.Fc -.Ft static void -.Fo destroy -.Fa "isc_socket_t **sockp" -.Fc -.Ft static void -.Fo free_socket -.Fa "isc_socket_t **socketp" -.Fc -.Ft static void -.Fo isc_socket_attach -.Fa "isc_socket_t *sock" -.Fa "isc_socket_t **socketp" -.Fc -.Ft static void -.Fo isc_socket_detach -.Fa "isc_socket_t **socketp" -.Fc -.Ft static isc_socketevent_t * -.Fo dispatch_recv -.Fa "isc_socket_t *sock" -.Fc -.Ft static void -.Fo dispatch_send -.Fa "isc_socket_t *sock" -.Fc -.Ft static int -.Fo dispatch_accept -.Fa "isc_socket_t *sock" -.Fc -.Ft static int -.Fo dispatch_connect -.Fa "isc_socket_t *sock" -.Fc -.Ft static void -.Fo internal_accept -.Fa "isc_task_t *me" -.Fa "isc_event_t *ev" -.Fc -.Ft static isc_result_t -.Fo internal_recv -.Fa "isc_task_t *me" -.Fa "isc_event_t *ev" -.Fc -.Ft static void -.Fo internal_send -.Fa "isc_task_t *me" -.Fa "isc_event_t *ev" -.Fc -.Ft isc_result_t -.Fo watcher -.Fa "void *uap" -.Fc -.Ft void -.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 static void -.Fo isc_socket_bind -.Fa "isc_socket_t *sock" -.Fa "isc_sockaddr_t *sockaddr" -.Fc -.Ft static void -.Fo isc_socket_listen -.Fa "isc_socket_t *sock" -.Fa "unsigned int backlog" -.Fc -.Ft static void -.Fo internal_connect -.Fa "isc_task_t *me" -.Fa "isc_event_t *ev" -.Fc -.Ft static void -.Fo isc_socket_getpeername -.Fa "isc_socket_t *sock" -.Fa "isc_sockaddr_t *addressp" -.Fc -.Ft static void -.Fo isc_socket_getsockname -.Fa "isc_socket_t *sock" -.Fa "isc_sockaddr_t *addressp" -.Fc -.Ft static void -.Fo isc_socket_cancel -.Fa "isc_socket_t *sock" -.Fa "isc_task_t *task" -.Fa "unsigned int how" -.Fc -.Ft static void -.Fo isc_socket_gettype -.Fa "isc_socket_t *sock" -.Fc -.Ft static void -.Fo isc_socket_isbound -.Fa "isc_socket_t *sock" -.Fc -.Sh DESCRIPTION -.Sh RETURN VALUES -.Sh SEE ALSO -.Sh BUGS diff --git a/doc/man/stdio.3 b/doc/man/stdio.3 deleted file mode 100644 index 3d275105ee3..00000000000 --- a/doc/man/stdio.3 +++ /dev/null @@ -1,179 +0,0 @@ -.\" -.\" 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: stdio.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_stdio_open "const char *filename" "const char *mode" "FILE **fp" -.Ft isc_result_t -.Fn isc_stdio_close "FILE *f" -.Ft isc_result_t -.Fn isc_stdio_seek "FILE *f" "long offset" "int whence" -.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 -.Fn isc_stdio_flush "FILE *f" -.Ft isc_result_t -.Fn isc_stdio_sync "FILE *f" -.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/stdio.man b/doc/man/stdio.man deleted file mode 100644 index 49e59181519..00000000000 --- a/doc/man/stdio.man +++ /dev/null @@ -1,178 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: stdio.man,v 1.2 2000/06/22 00:52:14 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_stdio_open "const char *filename" "const char *mode" "FILE **fp" -.Ft isc_result_t -.Fn isc_stdio_close "FILE *f" -.Ft isc_result_t -.Fn isc_stdio_seek "FILE *f" "long offset" "int whence" -.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 -.Fn isc_stdio_flush "FILE *f" -.Ft isc_result_t -.Fn isc_stdio_sync "FILE *f" -.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/stdtime.3 b/doc/man/stdtime.3 deleted file mode 100644 index c0f20b5c83e..00000000000 --- a/doc/man/stdtime.3 +++ /dev/null @@ -1,60 +0,0 @@ -.\" -.\" 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: stdtime.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_stdtime_get "isc_stdtime_t *t" -.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 -will 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/stdtime.man b/doc/man/stdtime.man deleted file mode 100644 index 3d12ac15c5b..00000000000 --- a/doc/man/stdtime.man +++ /dev/null @@ -1,59 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: stdtime.man,v 1.2 2000/06/22 00:52:16 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_stdtime_get "isc_stdtime_t *t" -.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 -will 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/time.3 b/doc/man/time.3 deleted file mode 100644 index df7d2c27e47..00000000000 --- a/doc/man/time.3 +++ /dev/null @@ -1,283 +0,0 @@ -.\" -.\" 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: time.3,v 1.1 2000/06/23 00:30:12 jim Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_interval_iszero "isc_interval_t *" -.Ft void -.Fo isc_time_set -.Fa "isc_time_t *t" -.Fa "unsigned int seconds" -.Fa "unsigned int nanoseconds" -.Fc -.Ft void -.Fn isc_time_settoepoch "isc_time_t *t" -.Ft isc_boolean_t -.Fn isc_time_isepoch "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_now "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_nowplusinterval "isc_time_t *t, isc_interval_t *i -.Ft int -.Fn isc_time_compare "isc_time_t *t1, isc_time_t *t2" -.Ft isc_result_t -.Fn isc_time_add "isc_time_t *t, isc_interval_t *i, isc_time_t *result" -.Ft isc_result_t -.Fn isc_time_subtract "isc_time_t *t, isc_interval_t *i, isc_time_t *result" -.Ft isc_uint64_t -.Fn isc_time_microdiff "isc_time_t *t1, isc_time_t *t2" -.Ft isc_uint32_t -.Fn isc_time_seconds "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_secondsastimet "isc_time_t *t, time_t *secondsp" -.Ft isc_uint32_t -.Fn isc_time_nanoseconds "isc_time_t *t" -.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 -.Fn *t -and -.Fn *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 -.Nm time_t -struct pointed at by -.Fa *secondsp . -It takes great care to ensure that the number of seconds represented -by -.Nm t->seconds -can be represented by a -.Nm time_t . -This is not as straightforward as it might seem because a -.Nm 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 it cannot 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 -.Nm "unsigned int" . -A result of -.Er ISC_R_SUCCESS -is returned on success. -.Pp -Calls to -.Fn isc_time_add , -.Fn isc_time_subtract -and -.Fn isc_time_secondsastimet -only return -.Er ISC_R_SUCCESS . -.ft B -So perhaps they should be void functions? - JR -.ft -.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 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 can delay the processing of real-time events. -For most DNS activity such as decrementing TTLs or zone refreshes, -this loss of accuracy does not matter. -.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. diff --git a/doc/man/time.man b/doc/man/time.man deleted file mode 100644 index 1422c5545ec..00000000000 --- a/doc/man/time.man +++ /dev/null @@ -1,282 +0,0 @@ -.\" Copyright (C) 2000 Internet Software Consortium. -.\" -.\" 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: time.man,v 1.2 2000/06/22 00:52:17 tale Exp $ -.\" -.Dd Jun 30, 2000 -.Dt 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 -.Fn isc_interval_iszero "isc_interval_t *" -.Ft void -.Fo isc_time_set -.Fa "isc_time_t *t" -.Fa "unsigned int seconds" -.Fa "unsigned int nanoseconds" -.Fc -.Ft void -.Fn isc_time_settoepoch "isc_time_t *t" -.Ft isc_boolean_t -.Fn isc_time_isepoch "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_now "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_nowplusinterval "isc_time_t *t, isc_interval_t *i -.Ft int -.Fn isc_time_compare "isc_time_t *t1, isc_time_t *t2" -.Ft isc_result_t -.Fn isc_time_add "isc_time_t *t, isc_interval_t *i, isc_time_t *result" -.Ft isc_result_t -.Fn isc_time_subtract "isc_time_t *t, isc_interval_t *i, isc_time_t *result" -.Ft isc_uint64_t -.Fn isc_time_microdiff "isc_time_t *t1, isc_time_t *t2" -.Ft isc_uint32_t -.Fn isc_time_seconds "isc_time_t *t" -.Ft isc_result_t -.Fn isc_time_secondsastimet "isc_time_t *t, time_t *secondsp" -.Ft isc_uint32_t -.Fn isc_time_nanoseconds "isc_time_t *t" -.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 -.Fn *t -and -.Fn *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 -.Nm time_t -struct pointed at by -.Fa *secondsp . -It takes great care to ensure that the number of seconds represented -by -.Nm t->seconds -can be represented by a -.Nm time_t . -This is not as straightforward as it might seem because a -.Nm 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 it cannot 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 -.Nm "unsigned int" . -A result of -.Er ISC_R_SUCCESS -is returned on success. -.Pp -Calls to -.Fn isc_time_add , -.Fn isc_time_subtract -and -.Fn isc_time_secondsastimet -only return -.Er ISC_R_SUCCESS . -.ft B -So perhaps they should be void functions? - JR -.ft -.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 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 can delay the processing of real-time events. -For most DNS activity such as decrementing TTLs or zone refreshes, -this loss of accuracy does not matter. -.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.