+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <pthread.h>
-
-.Fd #include <sys/types.h>
-
-.Fd #include <stddef.h>
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-.fd #include <signal.h>
-
-.Fd #include <isc/app.h>
-.Fd #include <isc/boolean.h>
-.Fd #include <isc/mutex.h>
-.Fd #include <isc/event.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/task.h>
-.Fd #include <isc/util.h>
-.Ft static isc_result_t
-.Fn handle_signal "int sig" "void (*handler)(int)"
-.Ft isc_result_t
-.Fn isc_app_start "void"
-.Ft isc_result_t
-.Fo isc_app_onrun
-.Fa "isc_mem_t *mctx"
-.Fa "isc_task_t *task"
-.Fa "isc_taskaction_t action"
-.Fa "void *arg"
-.Fc
-.Ft isc_result_t
-.Fn isc_app_run "void"
-.Ft isc_result_t
-.Fn isc_app_shutdown "void"
-.Ft isc_result_t
-.Fn isc_app_reload "void"
-.Ft void
-.Fn isc_app_finish "void"
-.Sh DESCRIPTION
-These functions define the interface for creating and terminating
-applications which use the BIND9 library.
-.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
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <pthread.h>
-
-.Fd #include <sys/types.h>
-
-.Fd #include <stddef.h>
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-.fd #include <signal.h>
-
-.Fd #include <isc/app.h>
-.Fd #include <isc/boolean.h>
-.Fd #include <isc/mutex.h>
-.Fd #include <isc/event.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/task.h>
-.Fd #include <isc/util.h>
-.Ft static isc_result_t
-.Fn handle_signal "int sig" "void (*handler)(int)"
-.Ft isc_result_t
-.Fn isc_app_start "void"
-.Ft isc_result_t
-.Fo isc_app_onrun
-.Fa "isc_mem_t *mctx"
-.Fa "isc_task_t *task"
-.Fa "isc_taskaction_t action"
-.Fa "void *arg"
-.Fc
-.Ft isc_result_t
-.Fn isc_app_run "void"
-.Ft isc_result_t
-.Fn isc_app_shutdown "void"
-.Ft isc_result_t
-.Fn isc_app_reload "void"
-.Ft void
-.Fn isc_app_finish "void"
-.Sh DESCRIPTION
-These functions define the interface for creating and terminating
-applications which use the BIND9 library.
-.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
+++ /dev/null
-.\"
-.\" 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 <config.h>
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/dir.h>
-.Fd #include <isc/magic.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/util.h>
-
-.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
+++ /dev/null
-.\" 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 <config.h>
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/dir.h>
-.Fd #include <isc/magic.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/util.h>
-
-.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
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-
-.Fd #include <isc/result.h>
-
-.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.
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-
-.Fd #include <isc/result.h>
-
-.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.
+++ /dev/null
-.\"
-.\" 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 <config.h>
-.Fd #include <errno.h>
-.Fd #include <limits.h>
-.Fd #include <stdlib.h>
-.Fd #include <unistd.h>
-
-.Fd #include <sys/stat.h>
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/file.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/time.h>
-.Fd #include <isc/util.h>
-
-.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
+++ /dev/null
-.\" 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 <config.h>
-.Fd #include <errno.h>
-.Fd #include <limits.h>
-.Fd #include <stdlib.h>
-.Fd #include <unistd.h>
-
-.Fd #include <sys/stat.h>
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/file.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/time.h>
-.Fd #include <isc/util.h>
-
-.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
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/net.h>
-.Fd #include <isc/once.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/util.h>
-
-.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 .
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/net.h>
-.Fd #include <isc/once.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/util.h>
-
-.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 .
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <sys/types.h>
-.Fd #include <sys/ioctl.h>
-.Fd #ifdef HAVE_SYS_SOCKIO_H
-.Fd #include <sys/sockio.h> /* Required for ifiter_ioctl.c. */
-.Fd #endif
-
-.Fd #include <stdio.h>
-.Fd #include <stdlib.h>
-.Fd #include <unistd.h>
-.Fd #include <errno.h>
-
-.Fd #include <isc/mem.h>
-.Fd #include <isc/net.h>
-.Fd #include <isc/result.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/types.h>
-.Fd #include <isc/interfaceiter.h>
-.Fd #include <isc/util.h>
-
-.Fd #include <net/if.h> /* Must follow <isc/net.h>. */
-
-.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 .
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <sys/types.h>
-.Fd #include <sys/ioctl.h>
-.Fd #ifdef HAVE_SYS_SOCKIO_H
-.Fd #include <sys/sockio.h> /* Required for ifiter_ioctl.c. */
-.Fd #endif
-
-.Fd #include <stdio.h>
-.Fd #include <stdlib.h>
-.Fd #include <unistd.h>
-.Fd #include <errno.h>
-
-.Fd #include <isc/mem.h>
-.Fd #include <isc/net.h>
-.Fd #include <isc/result.h>
-.Fd #include <isc/string.h>
-.Fd #include <isc/types.h>
-.Fd #include <isc/interfaceiter.h>
-.Fd #include <isc/util.h>
-
-.Fd #include <net/if.h> /* Must follow <isc/net.h>. */
-
-.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 .
+++ /dev/null
-.\"
-.\" 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 <config.h>
-.Fd
-.Fd #include <sys/param.h>
-.Fd #include <sys/types.h>
-.Fd #include <sys/socket.h>
-.Fd #include <sys/time.h>
-.Fd #include <sys/uio.h>
-.Fd
-.Fd #include <errno.h>
-.Fd #include <stddef.h>
-.Fd #include <stdlib.h>
-.Fd #include <string.h>
-.Fd #include <unistd.h>
-.Fd #include <fcntl.h>
-.Fd
-.Fd #include <isc/buffer.h>
-.Fd #include <isc/bufferlist.h>
-.Fd #include <isc/condition.h>
-.Fd #include <isc/list.h>
-.Fd #include <isc/log.h>
-.Fd #include <isc/mem.h>
-.Fd #include <isc/net.h>
-.Fd #include <isc/print.h>
-.Fd #include <isc/region.h>
-.Fd #include <isc/socket.h>
-.Fd #include <isc/task.h>
-.Fd #include <isc/thread.h>
-.Fd #include <isc/util.h>
-.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 .
-
+++ /dev/null
-.\" 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 <config.h>
-.Fd
-.Fd #include <sys/param.h>
-.Fd #include <sys/types.h>
-.Fd #include <sys/socket.h>
-.Fd #include <sys/time.h>
-.Fd #include <sys/uio.h>
-.Fd
-.Fd #include <errno.h>
-.Fd #include <stddef.h>
-.Fd #include <stdlib.h>
-.Fd #include <string.h>
-.Fd #include <unistd.h>
-.Fd #include <fcntl.h>
-.Fd
-.Fd #include <isc/buffer.h>
-.Fd #include <isc/bufferlist.h>
-.Fd #include <isc/condition.h>
-.Fd #include <isc/list.h>
-.Fd #include <isc/log.h>
-.Fd #include <isc/mem.h>
-.Fd #include <isc/net.h>
-.Fd #include <isc/print.h>
-.Fd #include <isc/region.h>
-.Fd #include <isc/socket.h>
-.Fd #include <isc/task.h>
-.Fd #include <isc/thread.h>
-.Fd #include <isc/util.h>
-.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
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/stdio.h>
-
-.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 .
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <unistd.h>
-
-.Fd #include <isc/stdio.h>
-
-.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 .
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/stdtime.h>
-.Fd #include <isc/util.h>
-
-.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 .
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/stdtime.h>
-.Fd #include <isc/util.h>
-
-.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 .
+++ /dev/null
-.\"
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <limits.h>
-.Fd #include <time.h>
-
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/string.h>
-.Fd #include <isc/time.h>
-.Fd #include <isc/util.h>
-.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.
+++ /dev/null
-.\" 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 <config.h>
-
-.Fd #include <errno.h>
-.Fd #include <limits.h>
-.Fd #include <time.h>
-
-.Fd #include <sys/time.h>
-
-.Fd #include <isc/string.h>
-.Fd #include <isc/time.h>
-.Fd #include <isc/util.h>
-.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.
projects / thirdparty / bind9.git / commitdiff
