From a88ba6982b9a169021a8f67088525a32b202a655 Mon Sep 17 00:00:00 2001 From: Jim Reid Date: Thu, 1 Jun 2000 03:19:06 +0000 Subject: [PATCH] Import of PRM --- doc/man/app.man | 234 ++++++++++++++++++++++++++++++++++++ doc/man/ctoman | 71 +++++++++++ doc/man/dir.man | 155 ++++++++++++++++++++++++ doc/man/error.man | 90 ++++++++++++++ doc/man/file.man | 155 ++++++++++++++++++++++++ doc/man/ipproto.man | 98 +++++++++++++++ doc/man/netif.man | 242 +++++++++++++++++++++++++++++++++++++ doc/man/socket.man | 221 ++++++++++++++++++++++++++++++++++ doc/man/stdio.man | 179 ++++++++++++++++++++++++++++ doc/man/stdtime.man | 60 ++++++++++ doc/man/time.man | 283 ++++++++++++++++++++++++++++++++++++++++++++ 11 files changed, 1788 insertions(+) create mode 100644 doc/man/app.man create mode 100755 doc/man/ctoman create mode 100644 doc/man/dir.man create mode 100644 doc/man/error.man create mode 100644 doc/man/file.man create mode 100644 doc/man/ipproto.man create mode 100644 doc/man/netif.man create mode 100644 doc/man/socket.man create mode 100644 doc/man/stdio.man create mode 100644 doc/man/stdtime.man create mode 100644 doc/man/time.man diff --git a/doc/man/app.man b/doc/man/app.man new file mode 100644 index 0000000000..f65e038150 --- /dev/null +++ b/doc/man/app.man @@ -0,0 +1,234 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +.\" +.\" Permission to use, copy, modify, and distribute this document for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM +.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL +.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT, +.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING +.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, +.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION +.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" $Id: app.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt APP 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm handle_signal , +.Nm isc_app_start , +.Nm isc_app_onrun , +.Nm isc_app_run , +.Nm isc_app_shutdown , +.Nm isc_app_reload , +.Nm isc_app_finish +.Nd application management functions +.Sh SYNOPSIS +.Fd #include + +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Ft static isc_result_t +.Fn handle_signal "int sig" "void (*handler)(int)" +.Ft isc_result_t +.Fn isc_app_start "void" +.Ft isc_result_t +.Fo isc_app_onrun +.Fa "isc_mem_t *mctx" +.Fa "isc_task_t *task" +.Fa "isc_taskaction_t action" +.Fa "void *arg" +.Fc +.Ft isc_result_t +.Fn isc_app_run "void" +.Ft isc_result_t +.Fn isc_app_shutdown "void" +.Ft isc_result_t +.Fn isc_app_reload "void" +.Ft void +.Fn isc_app_finish "void" +.Sh DESCRIPTION +These functions define the interface for creating and terminating +applications which use the BIND9 library. +.Pp +.Fn handle_signal +sets up a signal handler for signal +.Fa sig . +.Fa handler +is a pointer to the function that will be called whenever signal +.Fa sig +is delivered to the name server. +The signal handler is a void function which is passed an +.Ft int +argument: the number of the signal +.Fa sig +that has been delivered. +.Pp +Applications which use the BIND9 library should begin by calling +.Fn isc_app_start . +It sets up a signal handler to ignore +.Dv SIGPIPE . +.Fn isc_app_start +blocks signals +.Dv SIGHUP , +.Dv SIGINT +and +.Dv SIGTERM +This ensures that all subsequent threads will have these signals blocked by +default. +Any thread which wants to take delivery of these signals will have to +arrange its own signal handlers for them. +.Fn isc_app_start +then initialises a queue of runnable tasks for the application. +Calls to +.Fn isc_app_start +should be made before any other BIND9 library call, ideally as +close to the beginning of the application as possible. +.Pp +.Fn isc_app_onrun +arranges for delivery of an event to an application when it is executing. +This function should only be invoked after +.Fn isc_app_start +has been called. +It creates an +.Ft isc_event_t +structure from memory context +.Fa mctx +for task +.Fa task . +.Fa arg +is a pointer to some structure that can be referenced by the event +handler +.Fa action +which is invoked when the application takes delivery of a shutdown +event +.Dv ISC_APPEVENT_SHUTDOWN . +.Pp +An ISC library application is executed by calling +.Fn isc_app_run . +It should only be used after +.Fn isc_app_start +has been called. +.Fn isc_app_run +will not block until any events that have been requested with +.Fn isc_app_onrun +have been posted. +These events will be in FIFO order. +Typically +.Fn isc_app_run +will be called by the initial thread of an application which will then +block until shutdown is requested. +When a call to +.Fn isc_app_run +returns, the caller should arrange to shutdown the application. +.Pp +Applications should be shutdown using +.Fn isc_app_shutdown . +It can only be invoked after +.Fn isc_app_run +has been called. +.Fn isc_app_shutdown +sends a +.Dv SIGTERM +signal to the current process. +Multiple calls to +.Fn isc_app_shutdown +can be made. +Only one shutdown attempt will be carried out. +.Pp +The reload signal +.Dv SIGHUP +is sent to the process by +.Fn isc_app_reload . +The function returns +.Er ISC_R_SUCCESS +on success or +.Er ISC_R_UNEXPECTED +if the attempt to send the reload signal fails. +.Pp +.Fn isc_app_finish +should be called at the end of an application which uses the BIND9 +library. +It should be invoked at or near to the end of +.Dv main() . +The function ensures that any resources allocated by +.Fn isc_app_start +get released. +It therefore follows that +.Fn isc_app_finish +should only be used if +.Fn isc_app_start +was called earlier in the application. +.Sh RETURN VALUES +A successful call to +.Fn handle_signal +returns +.Er ISC_R_SUCCESS +and +.Er ISC_R_UNEXPECTED +is returned if it was unable to set up a signal handler. +.Pp +.Fn isc_app_start +returns +.Er ISC_R_SUCCESS +or +.Er ISC_R_UNEXPECTED +depending on whether the signal handlers were successfully installed +or not. +.Pp +.Fn isc_app_onrun +returns +.Er ISC_R_SUCCESS +unless it was not possible to create the event structure +.Ft isc_event_t +in which case it returns +.Er ISC_R_NOMEMORY . +.Pp +.Fn isc_app_run +returns +.Er ISC_R_SUCCESS +if shutdown has been requested and +.Er ISC_R_RELOAD +if a reload was requested. +.Er ISC_R_UNEXPECTED +is returned by +.Fn isc_app_run +when attempts to set or reset signal handlers fail. +.Pp +.Er ISC_R_UNEXPECTED +is returned by +.Fn isc_app_shutdown +if the signal was not sent successfully. +Otherwise +.Fn isc_app_shutdown +returns +.Er ISC_R_SUCCESS . +.Pp +Functions which return +.Er ISC_R_UNEXPECTED +will print an error message on the standard error output, +.Dv stderr . +.Sh SEE ALSO +.Xr sigsetops 3 , +.Xr pthreads 3 , +.Xr kill 2 diff --git a/doc/man/ctoman b/doc/man/ctoman new file mode 100755 index 0000000000..3681687bf8 --- /dev/null +++ b/doc/man/ctoman @@ -0,0 +1,71 @@ +.\" +.\" Copyright (C) 2000 Internet Software Consortium. +#!/usr/bin/gawk -f +# +# $Id: ctoman,v 1.1 2000/06/01 03:19:06 jim Exp $ +# +# ctoman - an awk program that makes a passable job of +# converting ISC BIND9 C files into template +# man pages +# Author: Jim Reid 1/6/00 +# +BEGIN { quote = "\"" + ftc = inc = fnc = arc = 1 } + + +# skip typedefs +/typedef/ { next } +# skip initialisations: lines ending in a semicolon +$0 ~ /;$/ { next } +# function return types +/^[a-z]/ && $0 !~ /\(/ { functypes[ftc++] = $0 } + +# #include lines +/#include/ { while ((NF ==0) || ((NF > 0) && $0 ~ /#include/)) { + inclist[inc++] = $0 + getline + } + } + +# function names and argument prototypes +/^[a-z]/ && $0 ~ /\(/ { + str= $0 + while ($NF != "{" ) { + next + str += $0 + } + sub(/\(/, ":", str) + sub(/\).*{/, "", str) + gsub(/,./, ":", str) + arglist[arc++] = str + split(str, foo, ":") + funclist[fnc++] = foo[1] + } + +#END { for (i = 1; i < inc; i++) print i, inclist[i] } +END { + while (getline < "/home/jim/bind9/doc/comment") + print + if (ftc != fnc) + print "FUNCTION NAME/RETURN COUNT MISMATCH" + for (i = 1; i < fnc - 1; i++) + print ".Nm", funclist[i], "," + print ".Nm", funclist[fnc - 1] + print ".Nd XXX" + print ".Sh SYNOPSIS" + for (i = 1; i < inc; i++) + print ".Fd", inclist[i] + for (i = 1; i < fnc; i++ ) { + print ".Ft", functypes[i] + print ".Fo", funclist[i] + j = split(arglist[i], foo, ":") + for (k = 2; k <= j; k++) + print ".Fa", quote foo[k] quote + print ".Fc" + } + print ".Sh DESCRIPTION" + print ".Sh RETURN VALUES" + print ".Sh SEE ALSO" + print ".Sh BUGS" + +} diff --git a/doc/man/dir.man b/doc/man/dir.man new file mode 100644 index 0000000000..1e64675e5e --- /dev/null +++ b/doc/man/dir.man @@ -0,0 +1,155 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt FSDIR 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_dir_init , +.Nm isc_dir_open , +.Nm isc_dir_read , +.Nm isc_dir_close , +.Nm isc_dir_reset , +.Nm isc_dir_chdir +.Nd file system directory operations +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include \*qerrno2result.h\*q +.Ft void +.Fn isc_dir_init "isc_dir_t *dir" +.Ft isc_result_t +.Fn isc_dir_open "isc_dir_t *dir, const char *dirname" +.Ft isc_result_t +.Fn isc_dir_read "isc_dir_t *dir" +.Ft isc_result_t +.Fn isc_dir_close "isc_dir_t *dir" +.Ft isc_result_t +.Fn isc_dir_chdir "const char *dirname" +.Sh DESCRIPTION +These functions define the operations performed on the file system's +directories by the name server. +They are intended to isolate BIND9 from the semantics of the underlying +directory access routines provided by the operating system, +BIND9 uses an internal structure of type +.Fa isc_dir_t +to reference a directory. +The contents of this structure are OS-specific. +.Fn isc_dir_init +initialises the directory structure pointed at +.Fa dir . +All functions taking a +.Fa dir +argument must ensure that +this parameter points at a valid +.Fa isc_dir_t +structure. +.Pp +.Fn isc_dir_open +opens the directory named by +.Fa dirname . +.Pp +.Fn isc_dir_read +retrieves the next entry from the file descriptor associated with directory +.Fa dir . +The name of that entry and the length of its name are copied to +.Fa dir . +A successful initial call to +.Fn isc_dir_read +on a directory will populate the +.Fa isc_dir_t +with details of the first valid directory entry. +Subsequent calls fetch the next entries. +.Pp +The +.Fn isc_dir_close +function +closes the file descriptor associated with +.Fa dir . +.Pp +.Fn isc_dir_reset +repositions +.Fa dir +to the start of the directory. +.Pp +The name server's current directory is changed to +.Fa dirname +by +.Fn isc_dir_chdir . +.Pp +.Sh RETURN VALUES +Successful calls to +.Fn isc_dir_open , +.Fn isc_dir_read , +.Fn isc_dir_reset , +.Fn isc_dir_read +and +.Fn isc_dir_chdir +return +.Er ISC_R_SUCCESS . +.Fn isc_dir_read +returns +.Er ISC_R_NOMORE +when there are no more entries in the directory. +.Er ISC_R_UNEXPECTED +is returned if the name of the next directory entry is too big +to fit in the +.Fa isc_dir_t +structure. +If +.Fn isc_dir_chdir +fails, +.Er ISC_R_INVALIDFILE +is returned if +.Fa dirname +is not a directory, or +.Er ISC_R_NOPERM +if access permission is denied or +.Er ISC_R_IOERROR +if an I/O error occurs. +The WinNT version of +.Fn isc_dir_chdir +returns +.Er ISC_R_NOTIMPLEMENTED +when the operating system reports an error that cannot be defined by +either a return value of +.Er ISC_R_NOTFOUND +or +.Er ISC_R_UNEXPECTED . +An error of +.Er ISC_R_FAILURE +can be returned in the WinNT versions of +.Fn isc_dir_open +and +.Fn isc_dir_reset +.Sh SEE ALSO +.Xr opendir 3 , +.Xr readdir 3 , +.Xr closedir 3 , +.Xr rewinddir 3 , +.Xr chdir 2 diff --git a/doc/man/error.man b/doc/man/error.man new file mode 100644 index 0000000000..ed508d7e11 --- /dev/null +++ b/doc/man/error.man @@ -0,0 +1,90 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt error 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc__errno2result +.Nd map POSIX error codes to BIND9 error codes +.Sh SYNOPSIS +.Fd #include + +.Fd #include + +.Fd #include + +.Fd #include "errno2result.h" +.Ft isc_result_t +.Fn isc__errno2result "int posixerrno" +.Sh DESCRIPTION +.Fn isc__errno2result +maps the POSIX error code +.Fa posixerrno +to its equivalent BIND9 error code. +.Pp +.Sh RETURN VALUES +When +.Fa posixerrno +is set to the POSIX error codes +.Er ENOTDIR , +.Er ELOOP , +.Er EINVAL , +.Er ENAMETOOLONG , +and +.Er EBADF , +.Fn isc__errno2result +returns +.Er ISC_R_INVALIDFILE . +.Er ISC_R_FILENOTFOUND +is returned when +.Fa posixerrno +is set to +.Er ENOENT . +A retun value of +.Er ISC_R_NOPERM +is produced when the POSIX error code is +.Er EACCES . +If +.Fa posixerrno +is set to +.Er EIO +.Fn isc__errno2result +returns +.Er ISC_R_IOERROR +and if the error code is +.Er ENOMEM , +.Er ISC_R_NOMEMORY +is returned. +For all other values of +.Fa posixerrno , +.Fn isc__errno2result +returns +.Er ISC_R_UNEXPECTED . +.Sh SEE ALSO +.Xr errno 2 , +.Xr perror 3 +.Sh BUGS +Returning +.Er ISC_R_UNEXPECTED +for so many error codes is a little unhelpful. +It would be nice if +.Fn isc__errno2result +produced something more descriptive like the system's error string for +these error codes. diff --git a/doc/man/file.man b/doc/man/file.man new file mode 100644 index 0000000000..6d27a3ac82 --- /dev/null +++ b/doc/man/file.man @@ -0,0 +1,155 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt FILE 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm file_stats , +.Nm isc_file_getmodtime , +.Nm isc_file_settime , +.Nm isc_file_mktemplate , +.Nm isc_file_openunique , +.Nm isc_file_remove +.Nd BIND9 file operation functions +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include \*qerrno2result.h\*q +.Ft static isc_result_t +.Fn file_stats "const char *file" "struct stat *stats" +.Ft isc_result_t +.Fn isc_file_getmodtime "const char *file" "isc_time_t *time" +.Ft isc_result_t +.Fn isc_file_settime "const char *file" "isc_time_t *time" +.Ft isc_result_t +.Fn isc_file_mktemplate "const char *path" "char *buf" "size_t buflen" +.Ft isc_result_t +.Fn isc_file_openunique "char *templet" "FILE **fp" +.Ft isc_result_t +.Fn isc_file_remove "const char *filename" +.Sh DESCRIPTION +The BIND9 library provides these function calls to manipulate files. +.Pp +.Fn file_stats +performs a +.Fn stat +call on the filename +.Fa file +and stores the result in the +.Dv "struct stat" +.Fa stats . +.Pp +The modification date of filename +.Fa file +is obtained by a call to +.Fn isc_file_getmodtime . +.Fa time +is a pointer to an +.Dv isc_time_t +structure which contains the file's modification date. +.Pp +.Fn isc_file_settime +sets the access and modification times of the file named +.Fa file +to the value of the timestamp supplied in +.Fa time . +.Pp +Pathnames for temporary files are created with +.Fn isc_file_mktemplate . +It copies the pathname in +.Fa path +up to the last \*q/\*q character if any in +.Fa buf . +the 14-character string \*qtmp-XXXXXXXXXX\*q is then appended to that +buffer. +.Fa buflen +indicates the size of buffer +.Fa buf . +Calls to +.Fn isc_file_mktemplate +fail if the buffer is too small to hold for the newly-created pathname. +.Pp +.Fn isc_file_openunique +creates a unique file name with access permissions 0600 and opens the +file for reading and writing. +The name of the unique file is returned in +.Fa templet +and a pointer to a pointer to a +.Dv stdio stream +associated with the opened file is returned in +.Fa fp . +The file name template +.Fa templet +should be generated by calling +.Fn isc_file_mktemplate . +This ensures the last 10 characters of the template are the letter \*qX\*q +so that these can be overwritten by +.Fn mkstemp +to generate a unique file name. +.Pp +Files are deleted with +.Fn isc_file_remove . +It unlinks the file named +.Fa filename . +.Sh RETURN VALUES +Successful calls to these functions all return +.Er ISC_R_SUCCESS . +Apart from the exceptions listed below, failed calls return +a BIND9 error code by mapping the corresponding POSIX error code using\p +.Fn isc__errno2result . +.Fn file_stats , +.Fn isc_file_getmodtime +calls +.Fn file_stats +and returns whatever values can be returned by that function. +.Pp +.Fn isc_file_settime +will return +.Er ISC_R_RANGE +if the count of the number of seconds in +.Dv time +is too big to fit in a 32-bit quantity. +.Pp +An error of +.Ev ISC_R_NOSPACE +is returned by +.Fn isc_file_mktemplate +if the pathname overflows the allocated buffer. +.Sh SEE ALSO +.Xr perror 3 , +.Xr isc__errno2result 3 , +.Xr stat 2 , +.Xr isc_time_set 3 , +.Xr utimes 2 , +.Xr mkstemp 3 , +.Xr fdopen 3 , +.Xr unlink 2 diff --git a/doc/man/ipproto.man b/doc/man/ipproto.man new file mode 100644 index 0000000000..12b6eff989 --- /dev/null +++ b/doc/man/ipproto.man @@ -0,0 +1,98 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt IPPROTO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm try_proto , +.Nm initialize_action , +.Nm isc_net_probeipv4 , +.Nm isc_net_probeipv6 +.Nd protocol probe functions +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Ft static isc_result_t +.Fn try_proto "int domain" +.Ft static void +.Fn initialize_action +.Ft isc_result_t +.Fn isc_net_probeipv4 void +.Ft isc_result_t +.Fn isc_net_probeipv4 void +.Sh DESCRIPTION +.Fn isc_net_probeipv4 +and +.Fn isc_net_probeipv6 +check that the operating system support the IPv4 and IPv6 protocols +respectively. +They call +.Fn try_proto +which tries to create a socket of type +.Dv SOCK_STREAM +for the appropriate protocol family, +.Fa domain . +.Pp +.Fn initialize_action +sets the external variables +.Dv ipv4_result +and +.Dv ipv6_result +to +.Er ISC_R_SUCCESS +if the IPv4 and IPv6 protocols respectively are supported by the +operating system. +These variables can be tested by applications which need to perform +protocol-specific tasks. +.Sh RETURN VALUES +.Fn isc_net_probeipv4 +returns +.Er ISC_R_SUCCESS +if the IPv4 protocol is supported by the kernel and +.Fn isc_net_probeipv6 +returns +.Er ISC_R_SUCCESS +if the operating system supports IPv6. +.Fn try_proto +returns +.Fn ISC_R_NOTFOUND +if the chosen protocol family +.Fa domain +is not supported by the kernel. +An error message is printed on +.Dv stderr +and +.Er ISC_R_UNEXPECTED +returned if another error occurred when the attempt was made to create +the +.Dv SOCK_STREAM +socket. +.Sh SEE ALSO +.Xr socket 2 , +.Xr ip 4 , +.Xr ipv6 4 . diff --git a/doc/man/netif.man b/doc/man/netif.man new file mode 100644 index 0000000000..73163b0781 --- /dev/null +++ b/doc/man/netif.man @@ -0,0 +1,242 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt NETIF 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_interfaceiter_create , +.Nm internal_current , +.Nm internal_next , +.Nm internal_destroy , +.Nm get_addr , +.Nm isc_interfaceiter_current , +.Nm isc_interfaceiter_first , +.Nm isc_interfaceiter_next , +.Nm isc_interfaceiter_destroy +.Nd network interface management +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include +.Fd #ifdef HAVE_SYS_SOCKIO_H +.Fd #include /* Required for ifiter_ioctl.c. */ +.Fd #endif + +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include + +.Fd #include /* Must follow . */ + +.Ft isc_result_t +.Fn isc_interfaceiter_create "isc_mem_t *mctx" "isc_interfaceiter_t **iterp" +.Ft static isc_result_t +.Fn internal_current +.Ft static isc_result_t +.Fn internal_next +.Ft static void +.Fn internal_destroy +.Ft static void +.Fo get_addr +.Fa "unsigned int family" +.Fa "isc_netaddr_t *dst" +.Fa "struct sockaddr *src" +.Fc +.Ft isc_result_t +.Fo isc_interfaceiter_current +.Fa "isc_interfaceiter_t *iter" +.Fa "isc_interface_t *ifdata" +.Fc +.Ft isc_result_t +.Fn isc_interfaceiter_first "isc_interfaceiter_t *iter" +.Ft isc_result_t +.Fn isc_interfaceiter_next "isc_interfaceiter_t *iter" +.Ft void +.Fn isc_interfaceiter_destroy "isc_interfaceiter_t **iter" +.Sh DESCRIPTION +Details of the system's network interfaces can be retrieved with +.Fn isc_interfaceiter_create . +It uses +.Xr sysctl 3 +or an +.Dv SIOCGLIFCONF +.Xr ioctl 2 +to get the information from the kernel. +Configuration details of the system's network interfaces - IP addresses, network +mask, status, MAC address, etc. - is stored in a buffer which is +accessed through +.Fa iterp . +Memory is allocated from the memory context +.Fa mctx +to store this information. +The maximum buffer size that can be used to store the configuration +data of all the network interfaces is 1 Megabyte +This data buffer should be far more than enough for a system with a +sensible number of network interfaces. +The +.Dv isc_interfaceiter_t +structure is not accessed directly. +Information is\p +obtained using +.Fa isc_interfaceiter_current , +.Fa isc_interfaceiter_first +and +.Fa isc_interfaceiter_next +which use the internal functions +.Fa internal_current +and +.Fa internal_next . +.Pp +.Fn internal_current +gets information for the current network interface from +.Fa iter . +.Fn internal_current +sets +.Dv iter->current +to point at the information about the current interface. +.Fa internal_next +gets the next interface in the list created by +.Fn isc_interfaceiter_create . +Unlike +.Fn isc_interfaceiter_next , +calls to +.Fn internal_next +can position the +.Fa iter +pointers at an interface which will be ignored because it uses an +unsupported address family: a non-IP interface for example. +.Pp +.Fn internal_destroy +does nothing. +It serves as a stub for +.Xr isc_interfaceiter_destroy 3 . +.Pp +.Fn get_addr +extracts the network address part of the +.Dv sockaddr +struct referenced by +.Fa src +and copies it to +.Fa dst . +.Fa family +indicates the address family \*- +.Dv AF_INET +or +.Dv AF_INET6 . +The address family is given explicitly because the network address might +contain a netmask obtained by an +.Dv SIOCGIFNETMASK +.Xr ioctl 2 . +which will not assign a valid address family to +.Dv src->sa_family . +.Pp +.Fn isc_interfaceiter_current +copies the configuration details of +.Fa iter 's +current network interface to +.Fa ifdata . +.Pp +.Fn isc_interfaceiter_first +locates the first network interface in +.Fa iter +which has an address in a supported address family: i.e. an IPv4 or +IPv6 address. +.Fn isc_interfaceiter_next +find the next network interface in +.Fa iter 's +list that has an IPv4 or IPv6 address. +.Pp +The +.Dv isc_interfaceiter_t +structure referenced by +.Fa iterp +is discarded by calling +.Fn isc_interfaceiter_destroy . +Any memory associated with +.Fa iterp is freed. +.Sh RETURN VALUES +Successful calls to +.Fn isc_interfaceiter_create +return +.Er ISC_R_SUCCESS . +The function returns +.Er ISC_R_NOMEMORY +if it was unable to allocate enough memory for the list if network +interfaces. +.Er ISC_R_UNEXPECTED +is returned and an error message printed on +.Dv stderr +if it was not possible to obtain a list of network interfaces. +.Pp +.Fa internal_current +returns +.Er ISC_R_SUCCESS +on success. +If the current interface uses an unsupported address family or if some +operation on the interface fails, the function returns +.Er ISC_R_IGNORE . +.Pp +.Er ISC_R_NOMORE +is returned by +.Fn internal_next +when there are no more entries in the list of interfaces referenced +via +.Fa iter. +It returns +.Er ISC_R_SUCCESS +otherwise. +.Pp +.Fn isc_interfaceiter_current +always returns +.Er ISC_R_SUCCESS +if +.Fa iter +points to a valid +.Dv isc_interfaceiter_t +structure. +.Pp +.Fn isc_interfaceiter_first +and +.Fn isc_interfaceiter_next +return +.Er ISC_R_SUCCESS +on success or +.Er ISC_R_NOMORE +if there are no more network interfaces in +.Fa iter . +.Sh SEE ALSO +.Xr netintro 4, +.Xr sysctl 3 , +.Xr ioctl 2 , +.Xr isc_interfaceiter_current 3 , +.Xr isc_interfaceiter_first 3 , +.Xr isc_interfaceiter_next 3 , +.Xr isc_interfaceiter_destroy 3 , +.Xr ifconfig 8 . diff --git a/doc/man/socket.man b/doc/man/socket.man new file mode 100644 index 0000000000..a378984e3e --- /dev/null +++ b/doc/man/socket.man @@ -0,0 +1,221 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt XXXXXX 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +FUNCTION NAME/RETURN COUNT MISMATCH +.Nm select_poke , +.Nm select_readmsg , +.Nm make_nonblock , +.Nm process_cmsg , +.Nm dump_msg , +.Nm doio_recv , +.Nm doio_send , +.Nm destroy , +.Nm free_socket , +.Nm isc_socket_attach , +.Nm isc_socket_detach , +.Nm dispatch_recv , +.Nm dispatch_send , +.Nm dispatch_accept , +.Nm dispatch_connect , +.Nm internal_accept , +.Nm internal_recv , +.Nm internal_send , +.Nm watcher , +.Nm isc_socketmgr_create , +.Nm isc_socketmgr_destroy , +.Nm isc_socket_bind , +.Nm isc_socket_listen , +.Nm internal_connect , +.Nm isc_socket_getpeername , +.Nm isc_socket_getsockname , +.Nm isc_socket_cancel , +.Nm isc_socket_gettype , +.Nm isc_socket_isbound +.Nd XXX +.Sh SYNOPSIS +.Fd #include +.Fd +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fd +.Ft struct isc_socket { +.Fo select_poke +.Fa "isc_socketmgr_t *mgr" +.Fa "int msg" +.Fc +.Ft struct isc_socketmgr { +.Fo select_readmsg +.Fa "isc_socketmgr_t *mgr" +.Fc +.Ft static void +.Fo make_nonblock +.Fa "int fd" +.Fc +.Ft static void +.Fo process_cmsg +.Fa "isc_socket_t *sock" +.Fa "struct msghdr *msg" +.Fa "isc_socketevent_t *dev" +.Fc +.Ft static void +.Fo dump_msg +.Fa "struct msghdr *msg" +.Fc +.Ft static int +.Fo doio_recv +.Fa "isc_socket_t *sock" +.Fa "isc_socketevent_t *dev" +.Fc +.Ft static isc_result_t +.Fo doio_send +.Fa "isc_socket_t *sock" +.Fa "isc_socketevent_t *dev" +.Fc +.Ft static void +.Fo destroy +.Fa "isc_socket_t **sockp" +.Fc +.Ft static void +.Fo free_socket +.Fa "isc_socket_t **socketp" +.Fc +.Ft static void +.Fo isc_socket_attach +.Fa "isc_socket_t *sock" +.Fa "isc_socket_t **socketp" +.Fc +.Ft static void +.Fo isc_socket_detach +.Fa "isc_socket_t **socketp" +.Fc +.Ft static isc_socketevent_t * +.Fo dispatch_recv +.Fa "isc_socket_t *sock" +.Fc +.Ft static void +.Fo dispatch_send +.Fa "isc_socket_t *sock" +.Fc +.Ft static int +.Fo dispatch_accept +.Fa "isc_socket_t *sock" +.Fc +.Ft static int +.Fo dispatch_connect +.Fa "isc_socket_t *sock" +.Fc +.Ft static void +.Fo internal_accept +.Fa "isc_task_t *me" +.Fa "isc_event_t *ev" +.Fc +.Ft static isc_result_t +.Fo internal_recv +.Fa "isc_task_t *me" +.Fa "isc_event_t *ev" +.Fc +.Ft static void +.Fo internal_send +.Fa "isc_task_t *me" +.Fa "isc_event_t *ev" +.Fc +.Ft isc_result_t +.Fo watcher +.Fa "void *uap" +.Fc +.Ft void +.Fo isc_socketmgr_create +.Fa "isc_mem_t *mctx" +.Fa "isc_socketmgr_t **managerp" +.Fc +.Ft void +.Fo isc_socketmgr_destroy +.Fa "isc_socketmgr_t **managerp" +.Fc +.Ft static void +.Fo isc_socket_bind +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *sockaddr" +.Fc +.Ft static void +.Fo isc_socket_listen +.Fa "isc_socket_t *sock" +.Fa "unsigned int backlog" +.Fc +.Ft static void +.Fo internal_connect +.Fa "isc_task_t *me" +.Fa "isc_event_t *ev" +.Fc +.Ft static void +.Fo isc_socket_getpeername +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *addressp" +.Fc +.Ft static void +.Fo isc_socket_getsockname +.Fa "isc_socket_t *sock" +.Fa "isc_sockaddr_t *addressp" +.Fc +.Ft static void +.Fo isc_socket_cancel +.Fa "isc_socket_t *sock" +.Fa "isc_task_t *task" +.Fa "unsigned int how" +.Fc +.Ft static void +.Fo isc_socket_gettype +.Fa "isc_socket_t *sock" +.Fc +.Ft static void +.Fo isc_socket_isbound +.Fa "isc_socket_t *sock" +.Fc +.Sh DESCRIPTION +.Sh RETURN VALUES +.Sh SEE ALSO +.Sh BUGS diff --git a/doc/man/stdio.man b/doc/man/stdio.man new file mode 100644 index 0000000000..e01ad59da0 --- /dev/null +++ b/doc/man/stdio.man @@ -0,0 +1,179 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt STDIO 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_stdio_open , +.Nm isc_stdio_close , +.Nm isc_stdio_seek , +.Nm isc_stdio_read , +.Nm isc_stdio_write , +.Nm isc_stdio_flush , +.Nm isc_stdio_sync +.Nd BIND9 interface to stdio functions +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include + +.Fd #include + +.Fd #include \*qerrno2result.h\*q + +.Ft isc_result_t +.Fn isc_stdio_open "const char *filename" "const char *mode" "FILE **fp" +.Ft isc_result_t +.Fn isc_stdio_close "FILE *f" +.Ft isc_result_t +.Fn isc_stdio_seek "FILE *f" "long offset" "int whence" +.Ft isc_result_t +.Fo isc_stdio_read +.Fa "void *ptr" +.Fa "size_t size" +.Fa "size_t nmemb" +.Fa "FILE *f" +.Fa "size_t *nret" +.Fc +.Ft isc_result_t +.Fo isc_stdio_write +.Fa "void *ptr" +.Fa "size_t size" +.Fa "size_t nmemb" +.Fa "FILE *f" +.Fa "size_t *nret" +.Fc +.Ft isc_result_t +.Fn isc_stdio_flush "FILE *f" +.Ft isc_result_t +.Fn isc_stdio_sync "FILE *f" +.Sh DESCRIPTION +The BIND9 library uses the following routines for standard I/O +operations. +These functions call their equivalents in the operating system's stdio +library. +.Pp +.Fn isc_stdio_open +opens the file +.Fa filename +with access mode +.Fa mode . +The string +.Fa mode +should correspond to the +.Fa mode +parameter in +.Xr fopen 3 . +If the file open succeeds, +.Fa fp +contains a pointer to the pointer to the relevant stdio +.Dv FILE +structure. +Files get closed by calling +.Fn isc_stdio_close . +.Fa fp +should be a pointer to the +.DV FILE +structure that was returned by an earlier call to +.Fn isc_stdio_open . +.Pp +The file position indicator for a stdio stream is adjusted with +.Fn isc_stdio_seek . +.Fa f +is the +.Dv FILE +pointer and +.Fa offset +and +.Fa whence +have the usual meanings. +The new position is found by adding +.Fa offset +bytes to the position specified by +.Fa whence +which is set to the values +.Dv SEEK_SET , +.Dv SEEK_CUR , +or +.Dv SEEK_END . +These values indicate the new position is calculated relative to the start +of the file, the current position indicator, or end of file +respectively. +.Pp +Reading and writing on a stdio stream is performed using +.Fn isc_stdio_read +and +.Fn isc_stdio_write +respectively. +The function +.Fn isc_stdio_read +reads reads +.Fa nmemb +objects, each +.Fa size +bytes long, from the stream pointed to by +.Fa f . +The objects are stored at the location given by +.Fa ptr . +.Fa isc_stdio_write +writes +.Fa nmemb +objects, each +.Fa size +bytes long, from location +.Fa ptr +to the stream +.Fa f . +The number of objects written is returned via +.Fa nret . +If this is less than +.Fa nmemb , +some type of write error occurred. +.Pp +A +.Xr write 2 +of buffered data associated with the output +.Fa f +can be forced with +.Fn isc_stdio_flush . +This data can be committed to permanent storage by +.Fn isc_stdio_sync +which will invoke +.Xr fsync 2 . +.Sh RETURN VALUES +Successful calls to all these functions return +.Er ISC_R_SUCCESS . +If the calls fail, the error code returned by the operating system is +mapped to the appropriate BIND9 error code by calling +.Xr isc__errno2result 3 . +.Fn isc_stdio_read +returns +.Er ISC_R_EOF +at end of file. +.Sh SEE ALSO +.Xr stdio 3 , +.Xr fopen 3 , +.Xr fclose 3 , +.Xr fread 3 , +.Xr fwrite 3 , +.Xr fflush 3 , +.Xr fsync 2 , +.Xr isc__errno2result 3 . diff --git a/doc/man/stdtime.man b/doc/man/stdtime.man new file mode 100644 index 0000000000..659f5c85c0 --- /dev/null +++ b/doc/man/stdtime.man @@ -0,0 +1,60 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt STDTIME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm isc_stdtime_get +.Nd get the current date and time +.Sh SYNOPSIS +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include + +.Ft void +.Fn isc_stdtime_get "isc_stdtime_t *t" +.Sh DESCRIPTION +.Fn isc_stdtime_get +sets +.Fa t +to the number of seconds since the UNIX epoch, 00:00:00 UTC, January +1, 1970. +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr isc_time_now 3 +.Sh BUGS +A time synchronisation protocol such as NTP is needed to ensure that +the kernel's concept of the current time is accurate. +.Pp +At 03:14:08 GMT on Tue Jan 19 2038, the number of seconds since +the UNIX epoch will overflow a 32-bit signed integer. +This may cause unpredictable behaviour on systems which treat these +timestamps as 32-bit signed quantities. +.Dv isc_stdtime_t +is defined as a 32-bit unsigned quantity, which means +.Fn isc_stdtime_get +will be safe until some time in 2106. +Applications that +want maximum portability should not assume anything about the size +of a +.Dv isc_stdtime_t . diff --git a/doc/man/time.man b/doc/man/time.man new file mode 100644 index 0000000000..6ca64395ff --- /dev/null +++ b/doc/man/time.man @@ -0,0 +1,283 @@ +.\" +.\" 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.man,v 1.1 2000/06/01 03:19:06 jim Exp $ +.\" +.Dd Jun 30, 2000 +.Dt TIME 3 +.Os BIND9 9 +.ds vT BIND9 Programmer's Manual +.Sh NAME +.Nm time +.Nd time-related operations +.Sh SYNOPSIS +.Fd #include + +.Fd #include +.Fd #include +.Fd #include + +.Fd #include + +.Fd #include +.Fd #include +.Fd #include +.Ft void +.Fo "isc_interval_set" +.Fa "isc_interval_t *i" +.Fa "unsigned int seconds" +.Fa "unsigned int nanoseconds" +.Fc +.Ft isc_boolean_t +.Fn isc_interval_iszero "isc_interval_t *" +.Ft void +.Fo isc_time_set +.Fa "isc_time_t *t" +.Fa "unsigned int seconds" +.Fa "unsigned int nanoseconds" +.Fc +.Ft void +.Fn isc_time_settoepoch "isc_time_t *t" +.Ft isc_boolean_t +.Fn isc_time_isepoch "isc_time_t *t" +.Ft isc_result_t +.Fn isc_time_now "isc_time_t *t" +.Ft isc_result_t +.Fn isc_time_nowplusinterval "isc_time_t *t, isc_interval_t *i +.Ft int +.Fn isc_time_compare "isc_time_t *t1, isc_time_t *t2" +.Ft isc_result_t +.Fn isc_time_add "isc_time_t *t, isc_interval_t *i, isc_time_t *result" +.Ft isc_result_t +.Fn isc_time_subtract "isc_time_t *t, isc_interval_t *i, isc_time_t *result" +.Ft isc_uint64_t +.Fn isc_time_microdiff "isc_time_t *t1, isc_time_t *t2" +.Ft isc_uint32_t +.Fn isc_time_seconds "isc_time_t *t" +.Ft isc_result_t +.Fn isc_time_secondsastimet "isc_time_t *t, time_t *secondsp" +.Ft isc_uint32_t +.Fn isc_time_nanoseconds "isc_time_t *t" +.Sh DESCRIPTION +These functions are used by the name server for any time-related activities. +They operate on the system's struct +.Nm time_t +and two local data structures: +.Bd -literal -offset indent +struct isc_interval { + unsigned int seconds; + unsigned int nanoseconds; +}; + +typedef struct isc_interval isc_interval_t; +.Ed +.Bd -literal -offset indent +struct isc_time { + unsigned int seconds; + unsigned int nanoseconds; +}; + +typedef struct isc_time isc_time_t; +.Ed +The contents of these structures are private +and MUST NOT be accessed by callers directly. +Details have only been provided so that callers can avoid +dynamic allocation. +The elements of these structures should only be manipulated via the +following functions. +.Pp +The function +.Fn isc_interval_set +initialises the +.Nm isc_interval_t +pointed at by +.Fa *i . +The elements +.Nm seconds +and +.Nm +nanoseconds +are set to the values of +.Fa seconds +and +.Fa nanoseconds +respectively. +.Pp +.Fn isc_interval_iszero +returns +.Er ISC_TRUE +if +.Fa *i +is the zero interval. +This condition should hold when the desired amount of time until an +event associated with interval +.Fa *i +has elapsed. +.Pp +.Fn isc_time_settoepoch +sets +.Fa *t +to the time of the epoch. +On +.Ux +systems this is 0 hours, 0 minutes, 0 seconds, January 1, 1970 UTC. +.Pp +The function +.Fn isc_time_isepoch +returns +.Er ISC_TRUE +if the time in +.Fa *t +is equal to the epoch time: "time zero". +It returns +.Er ISC_FALSE +otherwise. +.Pp +The current absolute time of day is obtained from +.Fn isc_time_now . +On a successful call to this function, the structure pointed at by +.Fa *t +is set to the number of seconds and nanoseconds since the epoch. +.Pp +.Fn isc_time_nowplusinterval +sets +.Fa *t +to the current time plus the interval specified in +.Fa *i . +.Pp +.Fn isc_time_compare +compares the times referenced by +.Fa *t1 +and +.Fa *t2 . +It returns 0 if the two times are equal. +A value of 1 is returned when +.Fa *t1 +is greater than +.Fa *t2 . +If +.Fa *t1 +is less than +.Fa *t2 +.Fn isc_time_compare +returns -1. +.Pp +The function +.Fn isc_time_add +adds +.Fa *i +to +.Fn *t +and +.Fn *result . +The converse operation is performed by +.Fa isc_time_subtract . +It subtracts +.Fa *i +from +.Fa *t +and stores the result in +.Fa result . +.Pp +.Fn isc_time_microdiff +returns the number of difference in microseconds between +.Fa *t1 +and +.Fa *t2. +Zero is returned if the time represented by +.Fa *t1 +is less than that given by +.Fa t2 . +.Pp +.Fn isc_time_seconds +and +.Fn isc_time_nanoseconds +return the number of seconds and nanoseconds respectively +in the time indicated by +.Fa *t . +.Pp +The function +.Fn isc_time_secondsastimet +converts the time value represented by +.Fa *t +to the system's +.Nm time_t +struct pointed at by +.Fa *secondsp . +It takes great care to ensure that the number of seconds represented +by +.Nm t->seconds +can be represented by a +.Nm time_t . +This is not as straightforward as it might seem because a +.Nm time_t +might not be an integral type. +Implementations may treat this type as a signed or unsigned quantity +which potentially creates sign extension problems. +.Sh RETURN VALUES +.Fn isc_time_now +and +.Fn isc_time_nowplusinterval +return +.Er ISC_R_UNEXPECTED +if it cannot get the time of day or if the operating system returns +nonsense. +They return +.Er ISC_R_RANGE +if the number of seconds returned by the operating system is too big +to fit in a +.Nm "unsigned int" . +A result of +.Er ISC_R_SUCCESS +is returned on success. +.Pp +Calls to +.Fn isc_time_add , +.Fn isc_time_subtract +and +.Fn isc_time_secondsastimet +only return +.Er ISC_R_SUCCESS . +.ft B +So perhaps they should be void functions? - JR +.ft +.Sh SEE ALSO +.Xr gettimeofday 2 , +.Xr getitimer 2 , +.Xr ctime 3 +.Sh BUGS +Nanosecond- and microsecond resolution time values are notoriously +inaccurate on most +.Ux +systems because few, if any, of them have +hardware which provides that level of precision. +Consult the vendor's documentation. +The resolution of the real-time clock in most systems is typically +100Hz which means the finest granularity of time-related activity is +at most 0.01 seconds. +Scheduling latency can delay the processing of real-time events. +For most DNS activity such as decrementing TTLs or zone refreshes, +this loss of accuracy does not matter. +.Pp +The accuracy of absolute times returned by +.Fn isc_time_now +and +.Fn isc_time_nowplusinterval +depend on the reliability of the system's time of day clock. +This should be synchronised to UTC using an external time source using +a good timekeeping protocol such as NTP. +Pedants might want to worry about whether the absolute time includes +leap seconds or not.