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: stdio.man,v 1.2 2000/06/22 00:52:14 tale Exp $
.Dd Jun 30, 2000 .Dt STDIO 3 .Os BIND9 9 .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.
p .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 .
p 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.
p 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.
p 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 .