mirror of
https://github.com/isc-projects/bind9.git
synced 2026-02-25 19:04:57 -05:00
179 lines
4.1 KiB
Groff
179 lines
4.1 KiB
Groff
.\"
|
|
.\" 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 .
|