mirror of
https://github.com/isc-projects/bind9.git
synced 2026-02-26 03:11:56 -05:00
40f53fa8d9
own CVS tree will help minimize CVS conflicts. Maybe not. Blame Graff for getting me to trim all trailing whitespace.
192 lines
4.1 KiB
Groff
192 lines
4.1 KiB
Groff
.\" Copyright (C) 2000 Internet Software Consortium.
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
|
|
.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
|
|
.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
|
|
.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
|
|
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
|
|
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
|
|
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" $Id: isc_stdio.3,v 1.3 2000/08/01 01:19:58 tale Exp $
|
|
.\"
|
|
.Dd Jun 30, 2000
|
|
.Dt ISC_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
|
|
.Fo isc_stdio_open
|
|
.Fa "const char *filename"
|
|
.Fa "const char *mode"
|
|
.Fa "FILE **fp"
|
|
.Fc
|
|
.Ft isc_result_t
|
|
.Fo isc_stdio_close
|
|
.Fa "FILE *f"
|
|
.Fc
|
|
.Ft isc_result_t
|
|
.Fo isc_stdio_seek
|
|
.Fa "FILE *f"
|
|
.Fa "long offset"
|
|
.Fa "int whence"
|
|
.Fc
|
|
.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
|
|
.Fo isc_stdio_flush
|
|
.Fa "FILE *f"
|
|
.Fc
|
|
.Ft isc_result_t
|
|
.Fo isc_stdio_sync
|
|
.Fa "FILE *f"
|
|
.Fc
|
|
.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 .
|