file.h revision 38b50b57eccaf810ff91b91e518226d676bd021b
/** Sharing mode: deny read. */ /** Sharing mode: deny write. */ /** Sharing mode: deny read and write. */ /** Sharing mode: deny all. */ /** Sharing mode: do NOT deny delete (NT). * @remark This might not be implemented on all platforms, * and will be defaulted & ignored on those. /** Sharing mode mask. */ /** Action: Open an existing file (the default action). */ /** Action: Create a new file or open an existing one. */ /** Action: Create a new a file. */ /** Action: Create a new file or replace an existing one. */ /** Turns off indexing of files on Windows hosts, *CREATE* only. * @remark This might not be implemented on all platforms, * and will be ignored on those. * @remark This will not truncate files opened for read-only. * @remark The trunction doesn't have to be atomically, so anyone * else opening the file may be racing us. The caller is * responsible for not causing this race. */ /** Make the handle inheritable on RTProcessCreate(/exec). */ /** Open file in non-blocking mode - non-portable. * @remark This flag may not be supported on all platforms, in which * case it's considered an invalid parameter. /** Write through directly to disk. Workaround to avoid iSCSI * initiator deadlocks on Windows hosts. * @remark This might not be implemented on all platforms, * and will be ignored on those. /** Mask of all valid flags. * @remark This doesn't validate the access mode properly. * Force the use of open flags for all files opened after the setting is * changed. The caller is responsible for not causing races with RTFileOpen(). * @returns iprt status code. * @param fOpenForAccess Access mode to which the set/mask settings apply. * @param fSet Open flags to be forced set. * @param fMask Open flags to be masked out. * @returns iprt status code. * @param pFile Where to store the handle to the opened file. * @param pszFilename Path to the file which is to be opened. (UTF-8) * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines. * Close a file opened by RTFileOpen(). * @returns iprt status code. * @param File The file handle to close. * @returns iprt status code. * @param pszFilename Path to the file which is to be deleted. (UTF-8) * @todo This is a RTPath api! /** Seek from the start of the file. */ /** Seek from the current file position. */ /** Seek from the end of the file. */ * Changes the read & write position in a file. * @returns iprt status code. * @param File Handle to the file. * @param offSeek Offset to seek. * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines. * @param poffActual Where to store the new file position. * Read bytes from a file. * @returns iprt status code. * @param File Handle to the file. * @param pvBuf Where to put the bytes we read. * @param cbToRead How much to read. * @param *pcbRead How much we actually read . * If NULL an error will be returned for a partial read. * Read bytes from a file at a given offset. * This function may modify the file position. * @returns iprt status code. * @param File Handle to the file. * @param off Where to read. * @param pvBuf Where to put the bytes we read. * @param cbToRead How much to read. * @param *pcbRead How much we actually read . * If NULL an error will be returned for a partial read. * @returns iprt status code. * @param File Handle to the file. * @param pvBuf What to write. * @param cbToWrite How much to write. * @param *pcbWritten How much we actually wrote. * If NULL an error will be returned for a partial write. * Write bytes to a file at a given offset. * This function may modify the file position. * @returns iprt status code. * @param File Handle to the file. * @param off Where to write. * @param pvBuf What to write. * @param cbToWrite How much to write. * @param *pcbWritten How much we actually wrote. * If NULL an error will be returned for a partial write. * Flushes the buffers for the specified file. * @returns iprt status code. * @param File Handle to the file. * Set the size of the file. * @returns iprt status code. * @param File Handle to the file. * @param cbSize The new file size. * Query the size of the file. * @returns iprt status code. * @param File Handle to the file. * @param pcbSize Where to store the filesize. * Determine the maximum file size. * @returns The max size of the file. * -1 on failure, the file position is undefined. * @param File Handle to the file. * @see RTFileGetMaxSizeEx. * Determine the maximum file size. * @returns IPRT status code. * @param File Handle to the file. * @param pcbMax Where to store the max file size. * Determine the maximum file size depending on the file system the file is stored on. * @returns The max size of the file. * @param File Handle to the file. * Gets the current file position. * @returns ~0UUL on failure. * @param File Handle to the file. * Checks if the supplied handle is valid. * @returns true if valid. * @returns false if invalid. * @param File The file handle * @returns VERR_ALREADY_EXISTS if the destination file exists. * @returns VBox Status code. * @param pszSrc The path to the source file. * @param pszDst The path to the destination file. * This file will be created. * Copies a file given the handles to both files. * @returns VBox Status code. * @param FileSrc The source file. The file position is unaltered. * @param FileDst The destination file. * On successful returns the file position is at the end of the file. * On failures the file position and size is undefined. /** Flags for RTFileCopyEx(). /** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */ * @returns VERR_ALREADY_EXISTS if the destination file exists. * @returns VBox Status code. * @param pszSrc The path to the source file. * @param pszDst The path to the destination file. * This file will be created. * @param fFlags Flags (RTFILECOPY_*). * @param pfnProgress Pointer to callback function for reporting progress. * @param pvUser User argument to pass to pfnProgress along with the completion precentage. * Copies a file given the handles to both files and * provide progress callbacks. * @returns IPRT status code. * @param FileSrc The source file. The file position is unaltered. * @param FileDst The destination file. * On successful returns the file position is at the end of the file. * On failures the file position and size is undefined. * @param pfnProgress Pointer to callback function for reporting progress. * @param pvUser User argument to pass to pfnProgress along with the completion precentage. * Identical to RTPathRename except that it will ensure that the source is not a directory. * @returns IPRT status code. * @returns VERR_ALREADY_EXISTS if the destination file exists. * @param pszSrc The path to the source file. * @param pszDst The path to the destination file. * This file will be created. * @param fRename See RTPathRename. /** @name RTFileMove flags (bit masks). /** Replace destination file if present. */ * RTFileMove differs from RTFileRename in that it works across volumes. * @returns IPRT status code. * @returns VERR_ALREADY_EXISTS if the destination file exists. * @param pszSrc The path to the source file. * @param pszDst The path to the destination file. * This file will be created. * @param fMove A combination of the RTFILEMOVE_* flags. /** @page pg_rt_filelock RT File locking API description * File locking general rules: * Region to lock or unlock can be located beyond the end of file, this can be used for * Read (or Shared) locks can be acquired held by an unlimited number of processes at the * same time, but a Write (or Exclusive) lock can only be acquired by one process, and * cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until * there are no processes holding any Write locks. To acquire a Write lock, a process must * wait until there are no processes holding either kind of lock. * By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock * can't be acquired due to conflict with other locks, however they can be called in wait mode. * Differences in implementation: * Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system. * I.e. when file region is locked in Read mode, any write in it will fail; in case of Write * lock - region can be readed and writed only by lock's owner. * Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the * operation system. Also see comments to RTFileChangeLock API call. * Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes * may use locks to coordonate access to a file between themselves, but programs are also free * to ignore locks and access the file in any way they choose to. /** @name Lock flags (bit masks). /** Read access, can be shared with others. */ /** Write access, one at a time. */ /** Don't wait for other locks to be released. */ /** Wait till conflicting locks have been released. */ * Locks a region of file for read (shared) or write (exclusive) access. * @returns iprt status code. * @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired. * @param File Handle to the file. * @param fLock Lock method and flags, see RTFILE_LOCK_* defines. * @param offLock Offset of lock start. * @param cbLock Length of region to lock, may overlap the end of file. * Changes a lock type from read to write or from write to read. * The region to type change must correspond exactly to an existing locked region. * If change can't be done due to locking conflict and non-blocking mode is used, error is * returned and lock keeps its state (see next warning). * WARNING: win32 implementation of this call is not atomic, it transforms to a pair of * calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be * lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't * be acquired, and old lock (previous state) can't be acquired back too. This situation * may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or * in race condition with the current call. * In this very bad case special error code VERR_FILE_LOCK_LOST will be returned. * @returns iprt status code. * @returns VERR_FILE_NOT_LOCKED if region was not locked. * @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type. * @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :( * @param File Handle to the file. * @param fLock Lock method and flags, see RTFILE_LOCK_* defines. * @param offLock Offset of lock start. * @param cbLock Length of region to lock, may overlap the end of file. * Unlocks previously locked region of file. * The region to unlock must correspond exactly to an existing locked region. * @returns iprt status code. * @returns VERR_FILE_NOT_LOCKED if region was not locked. * @param File Handle to the file. * @param offLock Offset of lock start. * @param cbLock Length of region to unlock, may overlap the end of file. * Query information about an open file. * @returns iprt status code. * @param File Handle to the file. * @param pObjInfo Object information structure to be filled on successful return. * @param enmAdditionalAttribs Which set of additional attributes to request. * Use RTFSOBJATTRADD_NOTHING if this doesn't matter. * Changes one or more of the timestamps associated of file system object. * @returns iprt status code. * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS. * @param File Handle to the file. * @param pAccessTime Pointer to the new access time. NULL if not to be changed. * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed. * @param pChangeTime Pointer to the new change time. NULL if not to be changed. * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed. * @remark The file system might not implement all these time attributes, * the API will ignore the ones which aren't supported. * @remark The file system might not implement the time resolution * employed by this interface, the time will be chopped to fit. * @remark The file system may update the change time even if it's * @remark POSIX can only set Access & Modification and will always set both. * Gets one or more of the timestamps associated of file system object. * @returns iprt status code. * @param File Handle to the file. * @param pAccessTime Where to store the access time. NULL is ok. * @param pModificationTime Where to store the modifcation time. NULL is ok. * @param pChangeTime Where to store the change time. NULL is ok. * @param pBirthTime Where to store the time of birth. NULL is ok. * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes(). * Changes the mode flags of an open file. * The API requires at least one of the mode flag sets (Unix/Dos) to * be set. The type is ignored. * @returns iprt status code. * @param File Handle to the file. * @param fMode The new file mode, see @ref grp_rt_fs for details. * Gets the mode flags of an open file. * @returns iprt status code. * @param File Handle to the file. * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details. * @remark This is wrapper around RTFileQueryInfo() * and exists to complement RTFileSetMode(). * Changes the owner and/or group of an open file. * @returns iprt status code. * @param File Handle to the file. * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged. * @param gid The new group id. Use -1 (or ~0) to leave this unchanged. * Gets the owner and/or group of an open file. * @returns iprt status code. * @param File Handle to the file. * @param pUid Where to store the owner user id. NULL is ok. * @param pGid Where to store the group id. NULL is ok. * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner(). * Executes an IOCTL on a file descriptor. * This function is currently only available in L4 and posix environments. * Attemps at calling it from code shared with any other platforms will break things! * The rational for defining this API is to simplify L4 porting of audio drivers, * and to remove some of the assumptions on RTFILE being a file descriptor on * platforms using the posix file implementation. * @returns iprt status code. * @param File Handle to the file. * @param iRequest IOCTL request to carry out. * @param pvData IOCTL data. * @param cbData Size of the IOCTL data. * @param piRet Return value of the IOCTL request.