blob: e3e0f03d9a2ffefcc70d161ef8a7ba9a4052d6ec [file] [log] [blame]
/*
* Copyright (C) Tildeslash Ltd. All rights reserved.
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU Affero General Public License version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU Affero General Public License for more details.
*
* You should have received a copy of the GNU Affero General Public License
* along with this program. If not, see <http://www.gnu.org/licenses/>.
*
* In addition, as a special exception, the copyright holders give
* permission to link the code of portions of this program with the
* OpenSSL library under certain conditions as described in each
* individual source file, and distribute linked combinations
* including the two.
*
* You must obey the GNU Affero General Public License in all respects
* for all of the code used other than OpenSSL.
*/
#ifndef FILE_INCLUDED
#define FILE_INCLUDED
#include <sys/types.h>
/**
* A set of low-level class methods for operating on a file.
*
* @see http://www.mmonit.com/
* @file
*/
/**
* The system-dependent filename separator character. On UNIX systems
* the value of this char is '/' on Win32 systems it is '\'.
*/
extern const char SEPARATOR_CHAR;
/**
* The separator character, provided as a string for convenience. This
* string contains a single character, namely SEPARATOR_CHAR.
*/
extern const char *SEPARATOR;
/**
* The system-dependent path-separator character. This character is
* used to separate filenames in a sequence of files given as a path
* list. On UNIX systems, this character is ':' on Win32 systems it is ';'.
*/
extern const char PATH_SEPARATOR_CHAR;
/**
* The system-dependent path-separator character, provided as a string
* for convenience. This string contains a single character, namely
* PATH_SEPARATOR_CHAR.
*/
extern const char *PATH_SEPARATOR;
/**
* Open <code>file</code> and return its file descriptor. The file is
* opened in non-blocking mode, meaning that read and write operations
* will not block. Clients can pass the descriptor to an Input- and/or
* an OutputStream for reading/writing to the file. The mode parameter
* is used to specify the access requested for the file. The mode may
* be one of
* <ol>
* <li>"r" Open for reading. The stream is positioned at the beginning
* of the file</li>
* <li>"w" Open for writing. If the file does not exist it will be
* created, if it exist it is truncated to length 0. The stream is
* positioned at the beginning of the file</li>
* <li>"r+" Open for reading and writing. The stream is positioned
* at the beginning of the file</li>
* <li>"w+" Open for reading and writing. If the file does not exist it
* will be created, if it exist it is truncated to length 0. The stream is
* positioned at the beginning of the file</li>
* <li>"a" Open for writing at the end of the file (appending). If the
* file does not exist it will be created. The stream is positioned at
* the end of the file</li>
* <li>"a+" Open for reading and writing. If the file does not exist it
* will be created. The stream is positioned at the end of the file</li>
*</ol>
* @param file An absolute file path
* @param mode the file access mode
* @return A file descriptor or -1 if the file cannot be opened. Use
* System_getLastError() to get a description of the error that occurred
*/
int File_open(const char *file, const char *mode);
/**
* Close the file descriptor <code>fd</code>
* @param fd An open file descriptor
* @return true on success or false if an error occurred.
*/
int File_close(int fd);
/**
* Move the <code>read</code> position in the file to the beginning
* of input.
* @param fd An open file descriptor
* @return true if success otherwise false and errno is set accordingly
*/
int File_rewind(int fd);
/**
* Returns the last modified time stamp for the given <code>file</code>.
* A file's mtime is changed by a file write operation
* @param file An absolute file path
* @return the last modified time stamp or -1 if the file was not found.
*/
time_t File_mtime(const char *file);
/**
* Returns the time when the <code>file</code> status was last changed.
* A file ctime is changed by a file write, chmod, chown, rename, etc.
* @param file An absolute file path
* @return the last changed time stamp or -1 if the file was not found
*/
time_t File_ctime(const char *file);
/**
* Returns the time when <code>file</code> data was last accessed.
* A file atime is changed by a file read operation
* @param file An absolute file path
* @return the last accessed time stamp or -1 if the file was not found.
*/
time_t File_atime(const char *file);
/**
* Check if this is a regular <code>file</code>.
* @param file An absolute file path
* @return true if file exist and is a regular file, otherwise false
*/
int File_isFile(const char *file);
/**
* Check if <code>file</code> is a directory
* @param file An absolute file path
* @return true if file exist and is a directory, otherwise false
*/
int File_isDirectory(const char *file);
/**
* Check if the <code>file</code> exist
* @param file An absolute file path
* @return true if file exist otherwise false
*/
int File_exist(const char *file);
/**
* Returns the file type. The returned char is one of
* <ul>
* <li>r - regular file</li>
* <li>d - directory</li>
* <li>c - char special</li>
* <li>b - block special</li>
* <li>l - symbolic link</li>
* <li>p - fifo or socket</li>
* <li>s - socket</li>
* <li>? - file does not exist</li>
* </ul>
* @param file An absolute file path
* @return The file type
*/
char File_type(const char *file);
/**
* Returns the <code>file</code> size in bytes
* @param file An absolute file path
* @return The file size or -1 if it does not exist
*/
off_t File_size(const char *file);
/**
* Changes permission bits on the <code>file</code> to the bit pattern
* represented by <code>perm</code>. On POSIX systems, see chmod(1) for
* details. Example, <code>File_chmod(file, 0644);</code> sets read and
* write permission for the File owner and read-only permission for others.
* @param file An absolute file path
* @param perm An octal number specifying a permission bit pattern.
* @return true if success otherwise false if for instance the File does
* not exist in the file system.
*/
int File_chmod(const char *file, mode_t perm);
/**
* Returns the permission bit pattern for the <code>file</code>. See also
* File_chmod().
* @param file An absolute file path
* @return An octal number specifying the permission set for this file
* or -1 if the file does not exist
*/
mode_t File_mod(const char *file);
/**
* Returns the current umask value for this process. Umask values are
* subtracted from the default permissions. Files and directories
* are created with default permission set to 0666 and 0777 respectively.
*
* Simply put, the umask value is a set of permission bits to turn back off
* a file creation mode. When a file or directory is created, the permission
* bits specified are <i>anded</i> with the complement of the umask value to
* determine the actual bits that will be set. For instance, when a file is
* created with File_open() the permission for the new file is set
* according to
* <pre>
* 0666 & ~File_umask(). If File_umask() is 022 then; 0666 & ~022 = 0644
* </pre>
* If a new directory is created with Dir_mkdir() then permission is set
* according to,
* <pre>
* 0777 & ~File_umask(). If File_umask() is 022 then; 0777 & ~022 = 0755
* </pre>
* Here is a ruby on-liner to play with, to see how umask modifies default
* permissions
* <pre>
* ruby -e 'printf("%#o\n", (0666 & ~0022))'
* </pre>
* See also http://en.wikipedia.org/wiki/Umask and umask(2) on Unix
* @return An octal number representing the umask value for this process
*/
mode_t File_umask(void);
/**
* Set the umask value for this process. The default value is 022, unless
* changed by the user. See also File_umask()
* @param mask The new umask value, as a 3 digit octal number, e.g. 007
* @return The old umask value for this process
*/
mode_t File_setUmask(mode_t mask);
/**
* Check if the <code>file</code> is readable for the real user id (uid) of
* this process
* @param file An absolute path
* @return true if the file is readable, otherwise false
*/
int File_isReadable(const char *file);
/**
* Check if the <code>file</code> is writable for the real user id (uid) of
* this process
* @param file An absolute path
* @return true if the file is writable, otherwise false
*/
int File_isWritable(const char *file);
/**
* Check if the <code>file</code> is executable for the real user id (uid) of
* this process
* @param file An absolute path
* @return true if the file is executable, otherwise false
*/
int File_isExecutable(const char *file);
/**
* Delete <code>file</code> from the filesystem
* @param file An absolute path
* @return true if success otherwise false
*/
int File_delete(const char *file);
/**
* Renames the given <code>file</code> to the new <code>name</code>
* Both <code>file</code> and <code>name</code> should contain a full path.
* @param file The name of the file to be renamed
* @param name The new name for the file.
* @return true if success otherwise false
*/
int File_rename(const char *file, const char *name);
/**
* Returns only the filename with leading directory components
* removed. This function does not modify the path string.
* @param path A file path string
* @return A pointer to the base name in path
*/
const char *File_basename(const char *path);
/**
* Strip the filename and return only the path, including the last path
* separator. The path parameter is modified so if you need to preserve
* the path string, copy the string before it is passed to this function.
* If no file separator can be found in the given path the following string
* is returned "." meaning the current directory.
* @param path A file path string
* @return The dir name from the path
*/
char *File_dirname(char *path);
/**
* Returns only the file extension from the <code>path</code>. This
* function does not modify the path string. For instance given
* the file path: <code>zild/webapps/ROOT/hello.html</code> this method
* returns a pointer to the sub-string <code>html</code>. If the
* <code>path</code> string does not contain an extension this
* method returns NULL.
* @param path A file path string
* @return A pointer to the file extension in the <code>path</code>
* string or NULL if no extension is found.
*/
const char *File_extension(const char *path);
/**
* If path is a directory, remove the last SEPARATOR char if any.
* Example:
* <pre>
* File_removeTrailingSeparator("/tmp/") -> "/tmp"
* File_removeTrailingSeparator("/tmp") -> "/tmp"
* File_removeTrailingSeparator(".monitrc") -> ".monitrc"
* </pre>
* @param path A file path string
* @return A pointer to the path string
*/
char *File_removeTrailingSeparator(char *path);
/**
* Returns the canonicalized absolute pathname of the <code>path</code>
* parameter. The <code>resolved</code> buffer must have size equal to
* PATH_MAX
* @param path The file path to normalize
* @param resolved The buffer to write the real path too
* @return A pointer to the resolved buffer or NULL if an error occured
*/
char *File_getRealPath(const char *path, char *resolved);
#endif