bind/doc/man/file.man

.\"
.\" 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