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_file.3,v 1.6 2001/01/09 21:47:44 bwelling Exp $
.Dd Jun 30, 2000 .Dt ISC_FILE 3 .Os BIND9 9 .Sh NAME .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 isc_result_t .Fo isc_file_getmodtime .Fa "const char *file" .Fa "isc_time_t *time" .Fc .Ft isc_result_t .Fo isc_file_settime .Fa "const char *file" .Fa "isc_time_t *time" .Fc .Ft isc_result_t .Fo isc_file_mktemplate .Fa "const char *path" .Fa "char *buf" .Fa "size_t buflen" .Fc .Ft isc_result_t .Fo isc_file_openunique .Fa "char *templet" .Fa "FILE **fp" .Fc .Ft isc_result_t .Fo isc_file_remove .Fa "const char *filename" .Fc .Sh DESCRIPTION The BIND9 library provides these function calls to manipulate files.
p 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.
p .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 .
p 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.
p .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.
p 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.
p .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.
p 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 .