contrib/bind-9.3/lib/isc/include/isc/file.h

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