mirror of
https://github.com/isc-projects/bind9.git
synced 2026-03-03 22:10:35 -05:00
40f53fa8d9
own CVS tree will help minimize CVS conflicts. Maybe not. Blame Graff for getting me to trim all trailing whitespace.
158 lines
4 KiB
Groff
158 lines
4 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 .
|