Import bind 9.5.2 vendor sources.
[dragonfly.git] / contrib / bind-9.5.2 / lib / isc / include / isc / file.h
1 /*
2  * Copyright (C) 2004-2007, 2009  Internet Systems Consortium, Inc. ("ISC")
3  * Copyright (C) 2000, 2001  Internet Software Consortium.
4  *
5  * Permission to use, copy, modify, and/or distribute this software for any
6  * purpose with or without fee is hereby granted, provided that the above
7  * copyright notice and this permission notice appear in all copies.
8  *
9  * THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
10  * REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
11  * AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
12  * INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
13  * LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
14  * OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
15  * PERFORMANCE OF THIS SOFTWARE.
16  */
17
18 /* $Id: file.h,v 1.33.128.2 2009/01/19 23:47:03 tbox Exp $ */
19
20 #ifndef ISC_FILE_H
21 #define ISC_FILE_H 1
22
23 /*! \file isc/file.h */
24
25 #include <stdio.h>
26
27 #include <isc/lang.h>
28 #include <isc/types.h>
29
30 ISC_LANG_BEGINDECLS
31
32 isc_result_t
33 isc_file_settime(const char *file, isc_time_t *time);
34
35 isc_result_t
36 isc_file_getmodtime(const char *file, isc_time_t *time);
37 /*!<
38  * \brief Get the time of last modification of a file.
39  *
40  * Notes:
41  *\li   The time that is set is relative to the (OS-specific) epoch, as are
42  *      all isc_time_t structures.
43  *
44  * Requires:
45  *\li   file != NULL.
46  *\li   time != NULL.
47  *
48  * Ensures:
49  *\li   If the file could not be accessed, 'time' is unchanged.
50  *
51  * Returns:
52  *\li   #ISC_R_SUCCESS
53  *              Success.
54  *\li   #ISC_R_NOTFOUND
55  *              No such file exists.
56  *\li   #ISC_R_INVALIDFILE
57  *              The path specified was not usable by the operating system.
58  *\li   #ISC_R_NOPERM
59  *              The file's metainformation could not be retrieved because
60  *              permission was denied to some part of the file's path.
61  *\li   #ISC_R_EIO
62  *              Hardware error interacting with the filesystem.
63  *\li   #ISC_R_UNEXPECTED
64  *              Something totally unexpected happened.
65  *
66  */
67
68 isc_result_t
69 isc_file_mktemplate(const char *path, char *buf, size_t buflen);
70 /*!<
71  * \brief Generate a template string suitable for use with isc_file_openunique().
72  *
73  * Notes:
74  *\li   This function is intended to make creating temporary files
75  *      portable between different operating systems.
76  *
77  *\li   The path is prepended to an implementation-defined string and
78  *      placed into buf.  The string has no path characters in it,
79  *      and its maximum length is 14 characters plus a NUL.  Thus
80  *      buflen should be at least strlen(path) + 15 characters or
81  *      an error will be returned.
82  *
83  * Requires:
84  *\li   buf != NULL.
85  *
86  * Ensures:
87  *\li   If result == #ISC_R_SUCCESS:
88  *              buf contains a string suitable for use as the template argument
89  *              to isc_file_openunique().
90  *
91  *\li   If result != #ISC_R_SUCCESS:
92  *              buf is unchanged.
93  *
94  * Returns:
95  *\li   #ISC_R_SUCCESS  Success.
96  *\li   #ISC_R_NOSPACE  buflen indicates buf is too small for the catenation
97  *                              of the path with the internal template string.
98  */
99
100
101 isc_result_t
102 isc_file_openunique(char *templet, FILE **fp);
103 /*!<
104  * \brief Create and open a file with a unique name based on 'templet'.
105  *
106  * Notes:
107  *\li   'template' is a reserved work in C++.  If you want to complain
108  *      about the spelling of 'templet', first look it up in the
109  *      Merriam-Webster English dictionary. (http://www.m-w.com/)
110  *
111  *\li   This function works by using the template to generate file names.
112  *      The template must be a writable string, as it is modified in place.
113  *      Trailing X characters in the file name (full file name on Unix,
114  *      basename on Win32 -- eg, tmp-XXXXXX vs XXXXXX.tmp, respectively)
115  *      are replaced with ASCII characters until a non-existent filename
116  *      is found.  If the template does not include pathname information,
117  *      the files in the working directory of the program are searched.
118  *
119  *\li   isc_file_mktemplate is a good, portable way to get a template.
120  *
121  * Requires:
122  *\li   'fp' is non-NULL and '*fp' is NULL.
123  *
124  *\li   'template' is non-NULL, and of a form suitable for use by
125  *      the system as described above.
126  *
127  * Ensures:
128  *\li   If result is #ISC_R_SUCCESS:
129  *              *fp points to an stream opening in stdio's "w+" mode.
130  *
131  *\li   If result is not #ISC_R_SUCCESS:
132  *              *fp is NULL.
133  *
134  *              No file is open.  Even if one was created (but unable
135  *              to be reopened as a stdio FILE pointer) then it has been
136  *              removed.
137  *
138  *\li   This function does *not* ensure that the template string has not been
139  *      modified, even if the operation was unsuccessful.
140  *
141  * Returns:
142  *\li   #ISC_R_SUCCESS
143  *              Success.
144  *\li   #ISC_R_EXISTS
145  *              No file with a unique name could be created based on the
146  *              template.
147  *\li   #ISC_R_INVALIDFILE
148  *              The path specified was not usable by the operating system.
149  *\li   #ISC_R_NOPERM
150  *              The file could not be created because permission was denied
151  *              to some part of the file's path.
152  *\li   #ISC_R_IOERROR
153  *              Hardware error interacting with the filesystem.
154  *\li   #ISC_R_UNEXPECTED
155  *              Something totally unexpected happened.
156  */
157
158 isc_result_t
159 isc_file_remove(const char *filename);
160 /*!<
161  * \brief Remove the file named by 'filename'.
162  */
163
164 isc_result_t
165 isc_file_rename(const char *oldname, const char *newname);
166 /*!<
167  * \brief Rename the file 'oldname' to 'newname'.
168  */
169
170 isc_boolean_t
171 isc_file_exists(const char *pathname);
172 /*!<
173  * \brief Return #ISC_TRUE if the calling process can tell that the given file exists.
174  * Will not return true if the calling process has insufficient privileges
175  * to search the entire path.
176  */
177
178 isc_boolean_t
179 isc_file_isabsolute(const char *filename);
180 /*!<
181  * \brief Return #ISC_TRUE if the given file name is absolute.
182  */
183
184 isc_boolean_t
185 isc_file_iscurrentdir(const char *filename);
186 /*!<
187  * \brief Return #ISC_TRUE if the given file name is the current directory (".").
188  */
189
190 isc_boolean_t
191 isc_file_ischdiridempotent(const char *filename);
192 /*%<
193  * Return #ISC_TRUE if calling chdir(filename) multiple times will give
194  * the same result as calling it once.
195  */
196
197 const char *
198 isc_file_basename(const char *filename);
199 /*%<
200  * Return the final component of the path in the file name.
201  */
202
203 isc_result_t
204 isc_file_progname(const char *filename, char *buf, size_t buflen);
205 /*!<
206  * \brief Given an operating system specific file name "filename"
207  * referring to a program, return the canonical program name.
208  *
209  *
210  * Any directory prefix or executable file name extension (if
211  * used on the OS in case) is stripped.  On systems where program
212  * names are case insensitive, the name is canonicalized to all
213  * lower case.  The name is written to 'buf', an array of 'buflen'
214  * chars, and null terminated.
215  *
216  * Returns:
217  *\li   #ISC_R_SUCCESS
218  *\li   #ISC_R_NOSPACE  The name did not fit in 'buf'.
219  */
220
221 isc_result_t
222 isc_file_template(const char *path, const char *templet, char *buf,
223                   size_t buflen);
224 /*%<
225  * Create an OS specific template using 'path' to define the directory
226  * 'templet' to describe the filename and store the result in 'buf'
227  * such that path can be renamed to buf atomically.
228  */
229
230 isc_result_t
231 isc_file_renameunique(const char *file, char *templet);
232 /*%<
233  * Rename 'file' using 'templet' as a template for the new file name.
234  */
235
236 isc_result_t
237 isc_file_absolutepath(const char *filename, char *path, size_t pathlen);
238 /*%<
239  * Given a file name, return the fully qualified path to the file.
240  */
241
242 /*
243  * XXX We should also have a isc_file_writeeopen() function
244  * for safely open a file in a publicly writable directory
245  * (see write_open() in BIND 8's ns_config.c).
246  */
247
248 isc_result_t
249 isc_file_truncate(const char *filename, isc_offset_t size);
250 /*%<
251  * Truncate/extend the file specified to 'size' bytes.
252  */
253
254 ISC_LANG_ENDDECLS
255
256 #endif /* ISC_FILE_H */