file.h revision 258945
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.332.2 2009/01/18 23:47:41 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 30ISC_LANG_BEGINDECLS 31 32isc_result_t 33isc_file_settime(const char *file, isc_time_t *time); 34 35isc_result_t 36isc_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 68isc_result_t 69isc_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 101isc_result_t 102isc_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 158isc_result_t 159isc_file_remove(const char *filename); 160/*!< 161 * \brief Remove the file named by 'filename'. 162 */ 163 164isc_result_t 165isc_file_rename(const char *oldname, const char *newname); 166/*!< 167 * \brief Rename the file 'oldname' to 'newname'. 168 */ 169 170isc_boolean_t 171isc_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 178isc_boolean_t 179isc_file_isabsolute(const char *filename); 180/*!< 181 * \brief Return #ISC_TRUE if the given file name is absolute. 182 */ 183 184isc_boolean_t 185isc_file_iscurrentdir(const char *filename); 186/*!< 187 * \brief Return #ISC_TRUE if the given file name is the current directory ("."). 188 */ 189 190isc_boolean_t 191isc_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 197const char * 198isc_file_basename(const char *filename); 199/*%< 200 * Return the final component of the path in the file name. 201 */ 202 203isc_result_t 204isc_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 221isc_result_t 222isc_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 230isc_result_t 231isc_file_renameunique(const char *file, char *templet); 232/*%< 233 * Rename 'file' using 'templet' as a template for the new file name. 234 */ 235 236isc_result_t 237isc_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 248isc_result_t 249isc_file_truncate(const char *filename, isc_offset_t size); 250/*%< 251 * Truncate/extend the file specified to 'size' bytes. 252 */ 253 254ISC_LANG_ENDDECLS 255 256#endif /* ISC_FILE_H */ 257