"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/isc/include/isc/file.h" (4 Sep 2020, 11668 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "file.h" see the Fossies "Dox" file reference documentation.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #ifndef ISC_FILE_H
   13 #define ISC_FILE_H 1
   14 
   15 /*! \file isc/file.h */
   16 
   17 #include <stdbool.h>
   18 #include <stdio.h>
   19 
   20 #include <isc/lang.h>
   21 #include <isc/stat.h>
   22 #include <isc/types.h>
   23 
   24 ISC_LANG_BEGINDECLS
   25 
   26 isc_result_t
   27 isc_file_settime(const char *file, isc_time_t *time);
   28 
   29 isc_result_t
   30 isc_file_mode(const char *file, mode_t *modep);
   31 
   32 isc_result_t
   33 isc_file_getmodtime(const char *file, isc_time_t *time);
   34 /*!<
   35  * \brief Get the time of last modification of a file.
   36  *
   37  * Notes:
   38  *\li   The time that is set is relative to the (OS-specific) epoch, as are
   39  *  all isc_time_t structures.
   40  *
   41  * Requires:
   42  *\li   file != NULL.
   43  *\li   time != NULL.
   44  *
   45  * Ensures:
   46  *\li   If the file could not be accessed, 'time' is unchanged.
   47  *
   48  * Returns:
   49  *\li   #ISC_R_SUCCESS
   50  *      Success.
   51  *\li   #ISC_R_NOTFOUND
   52  *      No such file exists.
   53  *\li   #ISC_R_INVALIDFILE
   54  *      The path specified was not usable by the operating system.
   55  *\li   #ISC_R_NOPERM
   56  *      The file's metainformation could not be retrieved because
   57  *      permission was denied to some part of the file's path.
   58  *\li   #ISC_R_IOERROR
   59  *      Hardware error interacting with the filesystem.
   60  *\li   #ISC_R_UNEXPECTED
   61  *      Something totally unexpected happened.
   62  *
   63  */
   64 
   65 isc_result_t
   66 isc_file_mktemplate(const char *path, char *buf, size_t buflen);
   67 /*!<
   68  * \brief Generate a template string suitable for use with
   69  * isc_file_openunique().
   70  *
   71  * Notes:
   72  *\li   This function is intended to make creating temporary files
   73  *  portable between different operating systems.
   74  *
   75  *\li   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  *\li   buf != NULL.
   83  *
   84  * Ensures:
   85  *\li   If result == #ISC_R_SUCCESS:
   86  *      buf contains a string suitable for use as the template argument
   87  *      to isc_file_openunique().
   88  *
   89  *\li   If result != #ISC_R_SUCCESS:
   90  *      buf is unchanged.
   91  *
   92  * Returns:
   93  *\li   #ISC_R_SUCCESS  Success.
   94  *\li   #ISC_R_NOSPACE  buflen indicates buf is too small for the catenation
   95  *              of the path with the internal template string.
   96  */
   97 
   98 isc_result_t
   99 isc_file_openunique(char *templet, FILE **fp);
  100 isc_result_t
  101 isc_file_openuniqueprivate(char *templet, FILE **fp);
  102 isc_result_t
  103 isc_file_openuniquemode(char *templet, int mode, FILE **fp);
  104 isc_result_t
  105 isc_file_bopenunique(char *templet, FILE **fp);
  106 isc_result_t
  107 isc_file_bopenuniqueprivate(char *templet, FILE **fp);
  108 isc_result_t
  109 isc_file_bopenuniquemode(char *templet, int mode, FILE **fp);
  110 /*!<
  111  * \brief Create and open a file with a unique name based on 'templet'.
  112  *  isc_file_bopen*() open the file in binary mode in Windows.
  113  *  isc_file_open*() open the file in text mode in Windows.
  114  *
  115  * Notes:
  116  *\li   'template' is a reserved work in C++.  If you want to complain
  117  *  about the spelling of 'templet', first look it up in the
  118  *  Merriam-Webster English dictionary. (http://www.m-w.com/)
  119  *
  120  *\li   This function works by using the template to generate file names.
  121  *  The template must be a writable string, as it is modified in place.
  122  *  Trailing X characters in the file name (full file name on Unix,
  123  *  basename on Win32 -- eg, tmp-XXXXXX vs XXXXXX.tmp, respectively)
  124  *  are replaced with ASCII characters until a non-existent filename
  125  *  is found.  If the template does not include pathname information,
  126  *  the files in the working directory of the program are searched.
  127  *
  128  *\li   isc_file_mktemplate is a good, portable way to get a template.
  129  *
  130  * Requires:
  131  *\li   'fp' is non-NULL and '*fp' is NULL.
  132  *
  133  *\li   'template' is non-NULL, and of a form suitable for use by
  134  *  the system as described above.
  135  *
  136  * Ensures:
  137  *\li   If result is #ISC_R_SUCCESS:
  138  *      *fp points to an stream opening in stdio's "w+" mode.
  139  *
  140  *\li   If result is not #ISC_R_SUCCESS:
  141  *      *fp is NULL.
  142  *
  143  *      No file is open.  Even if one was created (but unable
  144  *      to be reopened as a stdio FILE pointer) then it has been
  145  *      removed.
  146  *
  147  *\li   This function does *not* ensure that the template string has not been
  148  *  modified, even if the operation was unsuccessful.
  149  *
  150  * Returns:
  151  *\li   #ISC_R_SUCCESS
  152  *      Success.
  153  *\li   #ISC_R_EXISTS
  154  *      No file with a unique name could be created based on the
  155  *      template.
  156  *\li   #ISC_R_INVALIDFILE
  157  *      The path specified was not usable by the operating system.
  158  *\li   #ISC_R_NOPERM
  159  *      The file could not be created because permission was denied
  160  *      to some part of the file's path.
  161  *\li   #ISC_R_IOERROR
  162  *      Hardware error interacting with the filesystem.
  163  *\li   #ISC_R_UNEXPECTED
  164  *      Something totally unexpected happened.
  165  */
  166 
  167 isc_result_t
  168 isc_file_remove(const char *filename);
  169 /*!<
  170  * \brief Remove the file named by 'filename'.
  171  */
  172 
  173 isc_result_t
  174 isc_file_rename(const char *oldname, const char *newname);
  175 /*!<
  176  * \brief Rename the file 'oldname' to 'newname'.
  177  */
  178 
  179 bool
  180 isc_file_exists(const char *pathname);
  181 /*!<
  182  * \brief Return #true if the calling process can tell that the given file
  183  * exists. Will not return true if the calling process has insufficient
  184  * privileges to search the entire path.
  185  */
  186 
  187 bool
  188 isc_file_isabsolute(const char *filename);
  189 /*!<
  190  * \brief Return #true if the given file name is absolute.
  191  */
  192 
  193 isc_result_t
  194 isc_file_isplainfile(const char *name);
  195 
  196 isc_result_t
  197 isc_file_isplainfilefd(int fd);
  198 /*!<
  199  * \brief Check that the file is a plain file
  200  *
  201  * Returns:
  202  *\li   #ISC_R_SUCCESS
  203  *      Success. The file is a plain file.
  204  *\li   #ISC_R_INVALIDFILE
  205  *      The path specified was not usable by the operating system.
  206  *\li   #ISC_R_FILENOTFOUND
  207  *      The file does not exist. This return code comes from
  208  *      errno=ENOENT when stat returns -1. This code is mentioned
  209  *      here, because in logconf.c, it is the one rcode that is
  210  *      permitted in addition to ISC_R_SUCCESS. This is done since
  211  *      the next call in logconf.c is to isc_stdio_open(), which
  212  *      will create the file if it can.
  213  *\li   other ISC_R_* errors translated from errno
  214  *      These occur when stat returns -1 and an errno.
  215  */
  216 
  217 isc_result_t
  218 isc_file_isdirectory(const char *name);
  219 /*!<
  220  * \brief Check that 'name' exists and is a directory.
  221  *
  222  * Returns:
  223  *\li   #ISC_R_SUCCESS
  224  *      Success, file is a directory.
  225  *\li   #ISC_R_INVALIDFILE
  226  *      File is not a directory.
  227  *\li   #ISC_R_FILENOTFOUND
  228  *      File does not exist.
  229  *\li   other ISC_R_* errors translated from errno
  230  *      These occur when stat returns -1 and an errno.
  231  */
  232 
  233 bool
  234 isc_file_iscurrentdir(const char *filename);
  235 /*!<
  236  * \brief Return #true if the given file name is the current directory (".").
  237  */
  238 
  239 bool
  240 isc_file_ischdiridempotent(const char *filename);
  241 /*%<
  242  * Return #true if calling chdir(filename) multiple times will give
  243  * the same result as calling it once.
  244  */
  245 
  246 const char *
  247 isc_file_basename(const char *filename);
  248 /*%<
  249  * Return the final component of the path in the file name.
  250  */
  251 
  252 isc_result_t
  253 isc_file_progname(const char *filename, char *buf, size_t buflen);
  254 /*!<
  255  * \brief Given an operating system specific file name "filename"
  256  * referring to a program, return the canonical program name.
  257  *
  258  * Any directory prefix or executable file name extension (if
  259  * used on the OS in case) is stripped.  On systems where program
  260  * names are case insensitive, the name is canonicalized to all
  261  * lower case.  The name is written to 'buf', an array of 'buflen'
  262  * chars, and null terminated.
  263  *
  264  * Returns:
  265  *\li   #ISC_R_SUCCESS
  266  *\li   #ISC_R_NOSPACE  The name did not fit in 'buf'.
  267  */
  268 
  269 isc_result_t
  270 isc_file_template(const char *path, const char *templet, char *buf,
  271           size_t buflen);
  272 /*%<
  273  * Create an OS specific template using 'path' to define the directory
  274  * 'templet' to describe the filename and store the result in 'buf'
  275  * such that path can be renamed to buf atomically.
  276  */
  277 
  278 isc_result_t
  279 isc_file_renameunique(const char *file, char *templet);
  280 /*%<
  281  * Rename 'file' using 'templet' as a template for the new file name.
  282  */
  283 
  284 isc_result_t
  285 isc_file_absolutepath(const char *filename, char *path, size_t pathlen);
  286 /*%<
  287  * Given a file name, return the fully qualified path to the file.
  288  */
  289 
  290 /*
  291  * XXX We should also have a isc_file_writeeopen() function
  292  * for safely open a file in a publicly writable directory
  293  * (see write_open() in BIND 8's ns_config.c).
  294  */
  295 
  296 isc_result_t
  297 isc_file_truncate(const char *filename, isc_offset_t size);
  298 /*%<
  299  * Truncate/extend the file specified to 'size' bytes.
  300  */
  301 
  302 isc_result_t
  303 isc_file_safecreate(const char *filename, FILE **fp);
  304 /*%<
  305  * Open 'filename' for writing, truncating if necessary.  Ensure that
  306  * if it existed it was a normal file.  If creating the file, ensure
  307  * that only the owner can read/write it.
  308  */
  309 
  310 isc_result_t
  311 isc_file_splitpath(isc_mem_t *mctx, const char *path, char **dirname,
  312            char const **basename);
  313 /*%<
  314  * Split a path into dirname and basename.  If 'path' contains no slash
  315  * (or, on windows, backslash), then '*dirname' is set to ".".
  316  *
  317  * Allocates memory for '*dirname', which can be freed with isc_mem_free().
  318  *
  319  * Returns:
  320  * - ISC_R_SUCCESS on success
  321  * - ISC_R_INVALIDFILE if 'path' is empty or ends with '/'
  322  * - ISC_R_NOMEMORY if unable to allocate memory
  323  */
  324 
  325 isc_result_t
  326 isc_file_getsize(const char *file, off_t *size);
  327 /*%<
  328  * Return the size of the file (stored in the parameter pointed
  329  * to by 'size') in bytes.
  330  *
  331  * Returns:
  332  * - ISC_R_SUCCESS on success
  333  */
  334 
  335 isc_result_t
  336 isc_file_getsizefd(int fd, off_t *size);
  337 /*%<
  338  * Return the size of the file (stored in the parameter pointed
  339  * to by 'size') in bytes.
  340  *
  341  * Returns:
  342  * - ISC_R_SUCCESS on success
  343  */
  344 
  345 void *
  346 isc_file_mmap(void *addr, size_t len, int prot, int flags, int fd,
  347           off_t offset);
  348 /*%<
  349  * Portable front-end to mmap().  If mmap() is not defined on this
  350  * platform, then we simulate it by calling malloc() and read().
  351  * (In this event, the addr, prot, and flags parameters are ignored).
  352  */
  353 
  354 int
  355 isc_file_munmap(void *addr, size_t len);
  356 /*%<
  357  * Portable front-end to munmap().  If munmap() is not defined on
  358  * this platform, then we simply free the memory.
  359  */
  360 
  361 isc_result_t
  362 isc_file_sanitize(const char *dir, const char *base, const char *ext,
  363           char *path, size_t length);
  364 /*%<
  365  * Generate a sanitized filename, such as for MKEYS or NZF files.
  366  *
  367  * Historically, MKEYS and NZF files used SHA256 hashes of the view
  368  * name for the filename; this was to deal with the possibility of
  369  * forbidden characters such as "/" being in a view name, and to
  370  * avoid problems with case-insensitive file systems.
  371  *
  372  * Given a basename 'base' and an extension 'ext', this function checks
  373  * for the existence of file using the old-style name format in directory
  374  * 'dir'. If found, it returns the path to that file.  If there is no
  375  * file already in place, a new pathname is generated; if the basename
  376  * contains any excluded characters, then a truncated SHA256 hash is
  377  * used, otherwise the basename is used.  The path name is copied
  378  * into 'path', which must point to a buffer of at least 'length'
  379  * bytes.
  380  *
  381  * Requires:
  382  * - base != NULL
  383  * - path != NULL
  384  *
  385  * Returns:
  386  * - ISC_R_SUCCESS on success
  387  * - ISC_R_NOSPACE if the resulting path would be longer than 'length'
  388  */
  389 
  390 bool
  391 isc_file_isdirwritable(const char *path);
  392 /*%<
  393  *  Return true if the path is a directory and is writable
  394  */
  395 
  396 ISC_LANG_ENDDECLS
  397 
  398 #endif /* ISC_FILE_H */