home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / isc / file.h < prev    next >
Encoding:
C/C++ Source or Header  |  2008-09-17  |  7.4 KB  |  257 lines
  1. /*
  2.  * Copyright (C) 2004, 2005  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.27.18.2 2005/04/29 00:16:54 marka Exp $ */
  19.  
  20. #ifndef ISC_FILE_H
  21. #define ISC_FILE_H 1
  22.  
  23. /*! \file */
  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 modication 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 */
  257.