"Fossies" - the Fresh Open Source Software Archive

Member "monit-5.28.0/libmonit/src/io/File.h" (28 Mar 2021, 11886 Bytes) of package /linux/privat/monit-5.28.0.tar.gz:


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 and the latest Fossies "Diffs" side-by-side code changes report: 5.27.2_vs_5.28.0.

    1 /*
    2  * Copyright (C) Tildeslash Ltd. All rights reserved.
    3  *
    4  * This program is free software: you can redistribute it and/or modify
    5  * it under the terms of the GNU Affero General Public License version 3.
    6  *
    7  * This program is distributed in the hope that it will be useful,
    8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
    9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   10  * GNU Affero General Public License for more details.
   11  *
   12  * You should have received a copy of the GNU Affero General Public License
   13  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
   14  *
   15  * In addition, as a special exception, the copyright holders give
   16  * permission to link the code of portions of this program with the
   17  * OpenSSL library under certain conditions as described in each
   18  * individual source file, and distribute linked combinations
   19  * including the two.
   20  *
   21  * You must obey the GNU Affero General Public License in all respects
   22  * for all of the code used other than OpenSSL.  
   23  */
   24 
   25 
   26 #ifndef FILE_INCLUDED
   27 #define FILE_INCLUDED
   28 #include <sys/types.h>
   29 
   30 
   31 /**
   32  * A set of low-level class methods for operating on a file.
   33  * 
   34  * @author http://www.tildeslash.com/
   35  * @see http://www.mmonit.com/
   36  * @file
   37  */
   38 
   39 
   40 /**
   41  * The system-dependent filename separator character. On UNIX systems
   42  * the value of this char is '/' on Win32 systems it is '\'.
   43  */
   44 extern const char SEPARATOR_CHAR;
   45 
   46 /**
   47  * The separator character, provided as a string for convenience. This
   48  * string contains a single character, namely SEPARATOR_CHAR.
   49  */
   50 extern const char *SEPARATOR;
   51 
   52 /**
   53  * The system-dependent path-separator character. This character is
   54  * used to separate filenames in a sequence of files given as a path
   55  * list. On UNIX systems, this character is ':' on Win32 systems it is ';'.
   56  */
   57 extern const char PATH_SEPARATOR_CHAR;
   58 
   59 /**
   60  * The system-dependent path-separator character, provided as a string
   61  * for convenience. This string contains a single character, namely
   62  * PATH_SEPARATOR_CHAR.
   63  */
   64 extern const char *PATH_SEPARATOR;
   65 
   66 
   67 /**
   68  * Open <code>file</code> and return its file descriptor. The file is 
   69  * opened in non-blocking mode, meaning that read and write operations
   70  * will not block. Clients can pass the descriptor to an Input- and/or 
   71  * an OutputStream for reading/writing to the file. The mode parameter
   72  * is used to specify the access requested for the file. The mode may 
   73  * be one of
   74  * <ol>
   75  * <li>"r" Open for reading. The stream is positioned at the beginning 
   76  * of the file</li>
   77  * <li>"w" Open for writing. If the file does not exist it will be
   78  * created, if it exist it is truncated to length 0. The stream is 
   79  * positioned at the beginning of the file</li>
   80  * <li>"r+" Open for reading and writing. The stream is positioned 
   81  * at the beginning of the file</li>
   82  * <li>"w+" Open for reading and writing. If the file does not exist it 
   83  * will be created, if it exist it is truncated to length 0. The stream is 
   84  * positioned at the beginning of the file</li>
   85  * <li>"a" Open for writing at the end of the file (appending). If the
   86  * file does not exist it will be created. The stream is positioned at
   87  * the end of the file</li>
   88  * <li>"a+" Open for reading and writing. If the file does not exist it 
   89  * will be created. The stream is positioned at the end of the file</li>
   90  *</ol>
   91  * @param file An absolute  file path
   92  * @param mode the file access mode
   93  * @return A file descriptor or -1 if the file cannot be opened. Use 
   94  * System_getLastError() to get a description of the error that occurred
   95  */
   96 int File_open(const char *file, const char *mode);
   97 
   98 
   99 /**
  100  * Close the file descriptor <code>fd</code>
  101  * @param fd An open file descriptor
  102  * @return true on success or false if an error occurred.
  103  */
  104 bool File_close(int fd);
  105 
  106 
  107 /**
  108  * Move the <code>read</code> position in the file to the beginning
  109  * of input.
  110  * @param fd An open file descriptor
  111  * @return true if success otherwise false and errno is set accordingly
  112  */
  113 bool File_rewind(int fd);
  114 
  115 
  116 /**
  117  * Returns the last modified time stamp for the given <code>file</code>. 
  118  * A file's mtime is changed by a file write operation
  119  * @param file An absolute file path
  120  * @return the last modified time stamp or -1 if the file was not found.
  121  */
  122 time_t File_mtime(const char *file);
  123 
  124 
  125 /**
  126  * Returns the time when the <code>file</code> status was last changed. 
  127  * A file ctime is changed by a file write, chmod, chown, rename, etc.
  128  * @param file An absolute file path
  129  * @return the last changed time stamp or -1 if the file was not found 
  130  */
  131 time_t File_ctime(const char *file);
  132 
  133 
  134 /**
  135  * Returns the time when <code>file</code> data was last accessed. 
  136  * A file atime is changed by a file read operation
  137  * @param file An absolute file path
  138  * @return the last accessed time stamp or -1 if the file was not found.
  139  */
  140 time_t File_atime(const char *file);
  141 
  142 
  143 /**
  144  * Check if this is a regular <code>file</code>.
  145  * @param file An absolute file path
  146  * @return true if file exist and is a regular file, otherwise false
  147  */
  148 bool File_isFile(const char *file);
  149 
  150 
  151 /**
  152  * Returns true if <code>file</code> is a Unix Domain socket
  153  * @param file An absolute file path
  154  * @return true if file is a socket file, otherwise false
  155  */
  156 bool File_isSocket(const char *file);
  157 
  158         
  159 /**
  160  * Check if <code>file</code> is a directory
  161  * @param file An absolute file path
  162  * @return true if file exist and is a directory, otherwise false
  163  */
  164 bool File_isDirectory(const char *file);
  165 
  166 
  167 /**
  168  * Check if the <code>file</code> exist
  169  * @param file An absolute file path
  170  * @return true if file exist otherwise false
  171  */
  172 bool File_exist(const char *file);
  173 
  174 
  175 /**
  176  * Returns the file type. The returned char is one of
  177  * <ul>
  178  * <li>r - regular file</li>
  179  * <li>d - directory</li>
  180  * <li>c - char special</li>
  181  * <li>b - block special</li>
  182  * <li>l - symbolic link</li>
  183  * <li>p - fifo or socket</li>
  184  * <li>s - socket</li>
  185  * <li>? - file does not exist</li>
  186  * </ul>
  187  * @param file An absolute file path
  188  * @return The file type
  189  */
  190 char File_type(const char *file);
  191 
  192 
  193 /**
  194  * Returns the <code>file</code> size in bytes
  195  * @param file An absolute file path
  196  * @return The file size or -1 if it does not exist
  197  */
  198 off_t File_size(const char *file);
  199 
  200 
  201 /**
  202  * Changes permission bits on the <code>file</code> to the bit pattern 
  203  * represented by <code>perm</code>. On POSIX systems, see chmod(1) for 
  204  * details. Example, <code>File_chmod(file, 0644);</code> sets read and 
  205  * write permission for the File owner and read-only permission for others.
  206  * @param file An absolute file path
  207  * @param perm An octal number specifying a permission bit pattern.
  208  * @return true if success otherwise false if for instance the File does
  209  * not exist in the file system.
  210  */
  211 bool File_chmod(const char *file, mode_t perm);
  212 
  213 
  214 /**
  215  * Returns the permission bit pattern for the <code>file</code>. See also
  216  * File_chmod().
  217  * @param file An absolute file path
  218  * @return An octal number specifying the permission set for this file
  219  * or -1 if the file does not exist 
  220  */
  221 int File_mod(const char *file);
  222 
  223 
  224 /**
  225  * Returns the current umask value for this process. Umask values are 
  226  * subtracted from the default permissions. Files and directories 
  227  * are created with default permission set to 0666 and 0777 respectively.
  228  * 
  229  * Simply put, the umask value is a set of permission bits to turn back off 
  230  * a file creation mode. When a file or directory is created, the permission
  231  * bits specified are <i>anded</i> with the complement of the umask value to
  232  * determine the actual bits that will be set. For instance, when a file is 
  233  * created with File_open() the permission for the new file is set 
  234  * according to
  235  * <pre>
  236  * 0666 & ~File_umask(). If File_umask() is 022 then; 0666 & ~022 = 0644
  237  * </pre>
  238  * If a new directory is created with Dir_mkdir() then permission is set
  239  * according to,
  240  * <pre>
  241  * 0777 & ~File_umask(). If File_umask() is 022 then; 0777 & ~022 = 0755
  242  * </pre>
  243  * Here is a ruby on-liner to play with, to see how umask modifies default
  244  * permissions
  245  * <pre>
  246  * ruby -e 'printf("%#o\n", (0666 & ~0022))' 
  247  * </pre>
  248  * See also http://en.wikipedia.org/wiki/Umask and umask(2) on Unix
  249  * @return An octal number representing the umask value for this process
  250  */
  251 int File_umask(void);
  252 
  253 
  254 /**
  255  * Set the umask value for this process. The default value is 022, unless
  256  * changed by the user. See also File_umask()
  257  * @param mask The new umask value, as a 3 digit octal number, e.g. 007
  258  * @return The old umask value for this process
  259  */
  260 mode_t File_setUmask(mode_t mask);
  261 
  262 
  263 /**
  264  * Check if the <code>file</code> is readable for the real user id (uid) of 
  265  * this process
  266  * @param file An absolute path
  267  * @return true if the file is readable, otherwise false
  268  */
  269 bool File_isReadable(const char *file);
  270 
  271 
  272 /**
  273  * Check if the <code>file</code> is writable for the real user id (uid) of 
  274  * this process
  275  * @param file An absolute path
  276  * @return true if the file is writable, otherwise false
  277  */
  278 bool File_isWritable(const char *file);
  279 
  280 
  281 /**
  282  * Check if the <code>file</code> is executable for the real user id (uid) of 
  283  * this process
  284  * @param file An absolute path
  285  * @return true if the file is executable, otherwise false
  286  */
  287 bool File_isExecutable(const char *file);
  288 
  289 
  290 /**
  291  * Delete <code>file</code> from the filesystem
  292  * @param file An absolute path
  293  * @return true if success otherwise false
  294  */
  295 bool File_delete(const char *file);
  296 
  297 
  298 /**
  299  * Renames the given <code>file</code> to the new <code>name</code>
  300  * Both <code>file</code> and <code>name</code> should contain a full path.
  301  * @param file The name of the file to be renamed
  302  * @param name The new name for the file. 
  303  * @return true if success otherwise false
  304  */
  305 bool File_rename(const char *file, const char *name);
  306 
  307 
  308 /**
  309  * Returns only the filename with leading directory components
  310  * removed. This function does not modify the path string.
  311  * @param path A file path string
  312  * @return A pointer to the base name in path
  313  */
  314 const char *File_basename(const char *path);
  315 
  316 
  317 /**
  318  * Strip the filename and return only the path, including the last path
  319  * separator. The path parameter is modified so if you need to preserve 
  320  * the path string, copy the string before it is passed to this function. 
  321  * If no file separator can be found in the given path the following string
  322  * is returned "." meaning the current directory.
  323  * @param path A file path string
  324  * @return The dir name from the path
  325  */
  326 char *File_dirname(char *path);
  327 
  328 
  329 /**
  330  * Returns only the file extension from the <code>path</code>. This
  331  * function does not modify the path string. For instance given
  332  * the file path: <code>zild/webapps/ROOT/hello.html</code> this method 
  333  * returns a pointer to the sub-string <code>html</code>. If the 
  334  * <code>path</code> string does not contain an extension this 
  335  * method returns NULL.
  336  * @param path A file path string
  337  * @return A pointer to the file extension in the <code>path</code>
  338  * string or NULL if no extension is found.
  339  */
  340 const char *File_extension(const char *path);
  341 
  342 
  343 /**
  344  * If path is a directory, remove the last SEPARATOR char if any.
  345  * Example:
  346  * <pre>
  347  * File_removeTrailingSeparator("/tmp/")    -> "/tmp"
  348  * File_removeTrailingSeparator("/tmp")     -> "/tmp"
  349  * File_removeTrailingSeparator(".monitrc") -> ".monitrc"
  350  * </pre>
  351  * @param path A file path string
  352  * @return A pointer to the path string
  353  */
  354 char *File_removeTrailingSeparator(char *path);
  355 
  356 
  357 /**
  358  * Returns the canonicalized absolute pathname of the <code>path</code>
  359  * parameter. The <code>resolved</code> buffer must have size equal to
  360  * PATH_MAX
  361  * @param path The file path to normalize
  362  * @param resolved The buffer to write the real path too
  363  * @return A pointer to the resolved buffer or NULL if an error occurred
  364  */
  365 char *File_getRealPath(const char *path, char *resolved);
  366 
  367 
  368 #endif