40f53fa8d9
own CVS tree will help minimize CVS conflicts. Maybe not. Blame Graff for getting me to trim all trailing whitespace.
159 lines
4.0 KiB
Groff
159 lines
4.0 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_file.3,v 1.4 2000/08/01 01:19:12 tale Exp $
|
|
.\"
|
|
.Dd Jun 30, 2000
|
|
.Dt ISC_FILE 3
|
|
.Os BIND9 9
|
|
.ds vT BIND9 Programmer's Manual
|
|
.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.
|
|
.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 .
|