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