mirror of
https://gitlab.isc.org/isc-projects/bind9
synced 2025-08-31 22:45:39 +00:00
Import of PRM
This commit is contained in:
Jim Reid
234
doc/man/app.man
Normal file
234
doc/man/app.man
Normal file
@@ -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 <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
|
||||
71
doc/man/ctoman
Executable file
71
doc/man/ctoman
Executable file
@@ -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"
|
||||
|
||||
}
|
||||
155
doc/man/dir.man
Normal file
155
doc/man/dir.man
Normal file
@@ -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 <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
|
||||
90
doc/man/error.man
Normal file
90
doc/man/error.man
Normal file
@@ -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 <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.
|
||||
155
doc/man/file.man
Normal file
155
doc/man/file.man
Normal file
@@ -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 <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
|
||||
98
doc/man/ipproto.man
Normal file
98
doc/man/ipproto.man
Normal file
@@ -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 <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 .
|
||||
242
doc/man/netif.man
Normal file
242
doc/man/netif.man
Normal file
@@ -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 <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 .
|
||||
221
doc/man/socket.man
Normal file
221
doc/man/socket.man
Normal file
@@ -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 <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
|
||||
179
doc/man/stdio.man
Normal file
179
doc/man/stdio.man
Normal file
@@ -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 <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 .
|
||||
60
doc/man/stdtime.man
Normal file
60
doc/man/stdtime.man
Normal file
@@ -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 <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 .
|
||||
283
doc/man/time.man
Normal file
283
doc/man/time.man
Normal file
@@ -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 <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.
|
||||
Reference in New Issue
Block a user