/** @file * IPRT - File I/O. */ /* * Copyright (C) 2006-2007 Sun Microsystems, Inc. * * This file is part of VirtualBox Open Source Edition (OSE), as * available from http://www.virtualbox.org. This file is free software; * you can redistribute it and/or modify it under the terms of the GNU * General Public License (GPL) as published by the Free Software * Foundation, in version 2 as it comes in the "COPYING" file of the * VirtualBox OSE distribution. VirtualBox OSE is distributed in the * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind. * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the * VirtualBox OSE distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. * * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa * Clara, CA 95054 USA or visit http://www.sun.com if you need * additional information or have any questions. */ #ifndef ___iprt_file_h #define ___iprt_file_h #include #include #ifdef IN_RING3 # include #endif RT_C_DECLS_BEGIN /** @defgroup grp_rt_fileio RTFile - File I/O * @ingroup grp_rt * @{ */ /** Platform specific text line break. * @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */ #if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS) # define RTFILE_LINEFEED "\r\n" #else # define RTFILE_LINEFEED "\n" #endif #ifdef IN_RING3 /** * Checks if the specified file name exists and is a regular file. * * Symbolic links will be resolved. * * @returns true if it's a regular file, false if it isn't. * @param pszPath The path to the file. * * @sa RTDirExists, RTPathExists, RTSymlinkExists. */ RTDECL(bool) RTFileExists(const char *pszPath); /** @name Open flags * @{ */ /** Open the file with read access. */ #define RTFILE_O_READ 0x00000001 /** Open the file with write access. */ #define RTFILE_O_WRITE 0x00000002 /** Open the file with read & write access. */ #define RTFILE_O_READWRITE 0x00000003 /** The file access mask. * @remarks The value 0 is invalid. */ #define RTFILE_O_ACCESS_MASK 0x00000003 /** Open file in APPEND mode, so all writes to the file handle will * append data at the end of the file. * @remarks It is ignored if write access is not requested, that is * RTFILE_O_WRITE is not set. */ #define RTFILE_O_APPEND 0x00000004 /* 0x00000008 is unused atm. */ /** Sharing mode: deny none (the default mode). */ #define RTFILE_O_DENY_NONE 0x00000000 /** Sharing mode: deny read. */ #define RTFILE_O_DENY_READ 0x00000010 /** Sharing mode: deny write. */ #define RTFILE_O_DENY_WRITE 0x00000020 /** Sharing mode: deny read and write. */ #define RTFILE_O_DENY_READWRITE 0x00000030 /** Sharing mode: deny all. */ #define RTFILE_O_DENY_ALL RTFILE_O_DENY_READWRITE /** Sharing mode: do NOT deny delete (NT). * @remarks This might not be implemented on all platforms, and will be * defaulted & ignored on those. */ #define RTFILE_O_DENY_NOT_DELETE 0x00000040 /** Sharing mode mask. */ #define RTFILE_O_DENY_MASK 0x00000070 /** Action: Open an existing file (the default action). */ #define RTFILE_O_OPEN 0x00000000 /** Action: Create a new file or open an existing one. */ #define RTFILE_O_OPEN_CREATE 0x00000100 /** Action: Create a new a file. */ #define RTFILE_O_CREATE 0x00000200 /** Action: Create a new file or replace an existing one. */ #define RTFILE_O_CREATE_REPLACE 0x00000300 /** Action mask. */ #define RTFILE_O_ACTION_MASK 0x00000300 /*0x00000400 and 0x00000800 are unused atm. */ /** Turns off indexing of files on Windows hosts, *CREATE* only. * @remarks Window only. */ #define RTFILE_O_NOT_CONTENT_INDEXED 0x00000800 /** Truncate the file. * @remarks This will not truncate files opened for read-only. * @remarks 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. */ #define RTFILE_O_TRUNCATE 0x00001000 /** Make the handle inheritable on RTProcessCreate(/exec). */ #define RTFILE_O_INHERIT 0x00002000 /** Open file in non-blocking mode - non-portable. * @remarks This flag may not be supported on all platforms, in which case it's * considered an invalid parameter. */ #define RTFILE_O_NON_BLOCK 0x00004000 /** Write through directly to disk. Workaround to avoid iSCSI * initiator deadlocks on Windows hosts. * @remarks This might not be implemented on all platforms, and will be ignored * on those. */ #define RTFILE_O_WRITE_THROUGH 0x00008000 /** Attribute access: Attributes can be read if the file is being opened with * read access, and can be written with write access. */ #define RTFILE_O_ACCESS_ATTR_DEFAULT 0x00000000 /** Attribute access: Attributes can be read. * @remarks Windows only. */ #define RTFILE_O_ACCESS_ATTR_READ 0x00010000 /** Attribute access: Attributes can be written. * @remarks Windows only. */ #define RTFILE_O_ACCESS_ATTR_WRITE 0x00020000 /** Attribute access: Attributes can be both read & written. * @remarks Windows only. */ #define RTFILE_O_ACCESS_ATTR_READWRITE 0x00030000 /** Attribute access: The file attributes access mask. * @remarks Windows only. */ #define RTFILE_O_ACCESS_ATTR_MASK 0x00030000 /** Open file for async I/O * @remarks This flag may not be needed on all platforms, and will be ignored on * those. */ #define RTFILE_O_ASYNC_IO 0x00040000 /** Disables caching. * * Useful when using very big files which might bring the host I/O scheduler to * its knees during high I/O load. * * @remarks This flag might impose restrictions * on the buffer alignment, start offset and/or transfer size. * * On Linux the buffer needs to be aligned to the 512 sector * boundary. * * On Windows the FILE_FLAG_NO_BUFFERING is used (see * http://msdn.microsoft.com/en-us/library/cc644950(VS.85).aspx ). * The buffer address, the transfer size and offset needs to be * aligned to the sector size of the volume. * * @remarks This might not be implemented on all platforms, * and will be ignored on those. */ #define RTFILE_O_NO_CACHE 0x00080000 /** Unix file mode mask for use when creating files. */ #define RTFILE_O_CREATE_MODE_MASK 0x1ff00000 /** The number of bits to shift to get the file mode mask. * To extract it: (fFlags & RTFILE_O_CREATE_MODE_MASK) >> RTFILE_O_CREATE_MODE_SHIFT. */ #define RTFILE_O_CREATE_MODE_SHIFT 20 /*0x20000000, 0x40000000 and 0x80000000 are unused atm. */ /** Mask of all valid flags. * @remark This doesn't validate the access mode properly. */ #define RTFILE_O_VALID_MASK 0x1ffFFB77 /** @} */ /** * 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. */ RTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask); /** * Open a file. * * @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. */ RTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen); /** * Close a file opened by RTFileOpen(). * * @returns iprt status code. * @param File The file handle to close. */ RTR3DECL(int) RTFileClose(RTFILE File); /** * Creates an IPRT file handle from a native one. * * @returns IPRT status code. * @param pFile Where to store the IPRT file handle. * @param uNative The native handle. */ RTR3DECL(int) RTFileFromNative(PRTFILE pFile, RTHCINTPTR uNative); /** * Gets the native handle for an IPRT file handle. * * @return The native handle. * @params File The IPRT file handle. */ RTR3DECL(RTHCINTPTR) RTFileToNative(RTFILE File); /** * Delete a file. * * @returns iprt status code. * @param pszFilename Path to the file which is to be deleted. (UTF-8) * @todo This is a RTPath api! */ RTR3DECL(int) RTFileDelete(const char *pszFilename); /** @name Seek flags. * @{ */ /** Seek from the start of the file. */ #define RTFILE_SEEK_BEGIN 0x00 /** Seek from the current file position. */ #define RTFILE_SEEK_CURRENT 0x01 /** Seek from the end of the file. */ #define RTFILE_SEEK_END 0x02 /** @internal */ #define RTFILE_SEEK_FIRST RTFILE_SEEK_BEGIN /** @internal */ #define RTFILE_SEEK_LAST RTFILE_SEEK_END /** @} */ /** * 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. * NULL is allowed. */ RTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual); /** * 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. */ RTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead); /** * 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. */ RTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead); /** * Write bytes to a file. * * @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. */ RTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten); /** * 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. */ RTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten); /** * Flushes the buffers for the specified file. * * @returns iprt status code. * @param File Handle to the file. */ RTR3DECL(int) RTFileFlush(RTFILE File); /** * Set the size of the file. * * @returns iprt status code. * @param File Handle to the file. * @param cbSize The new file size. */ RTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize); /** * Query the size of the file. * * @returns iprt status code. * @param File Handle to the file. * @param pcbSize Where to store the filesize. */ RTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize); /** * 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. */ RTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File); /** * Determine the maximum file size. * * @returns IPRT status code. * @param File Handle to the file. * @param pcbMax Where to store the max file size. * @see RTFileGetMaxSize. */ RTR3DECL(int) RTFileGetMaxSizeEx(RTFILE File, PRTFOFF pcbMax); /** * Determine the maximum file size depending on the file system the file is stored on. * * @returns The max size of the file. * -1 on failure. * @param File Handle to the file. */ RTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File); /** * Gets the current file position. * * @returns File offset. * @returns ~0UUL on failure. * @param File Handle to the file. */ RTDECL(uint64_t) RTFileTell(RTFILE File); /** * Checks if the supplied handle is valid. * * @returns true if valid. * @returns false if invalid. * @param File The file handle */ RTR3DECL(bool) RTFileIsValid(RTFILE File); /** * Copies a file. * * @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. */ RTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst); /** * 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. */ RTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst); /** Flags for RTFileCopyEx(). * @{ */ /** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */ #define RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE RT_BIT(0) /** Do not use RTFILE_O_DENY_WRITE on the target file. */ #define RTFILECOPY_FLAGS_NO_DST_DENY_WRITE RT_BIT(1) /** Do not use RTFILE_O_DENY_WRITE on either of the two files. */ #define RTFILECOPY_FLAGS_NO_DENY_WRITE ( RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE | RTFILECOPY_FLAGS_NO_DST_DENY_WRITE ) /** */ #define RTFILECOPY_FLAGS_MASK UINT32_C(0x00000003) /** @} */ /** * Copies a file. * * @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. */ RTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser); /** * 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. */ RTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser); /** * Renames a file. * * 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. */ RTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename); /** @name RTFileMove flags (bit masks). * @{ */ /** Replace destination file if present. */ #define RTFILEMOVE_FLAGS_REPLACE 0x1 /** @} */ /** * Moves a file. * * 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. */ RTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove); /** @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 * growing files. * 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 coordinate access to a file between themselves, but programs are also free * to ignore locks and access the file in any way they choose to. * * Additional reading: * http://en.wikipedia.org/wiki/File_locking * http://unixhelp.ed.ac.uk/CGI/man-cgi?fcntl+2 * http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp */ /** @name Lock flags (bit masks). * @{ */ /** Read access, can be shared with others. */ #define RTFILE_LOCK_READ 0x00 /** Write access, one at a time. */ #define RTFILE_LOCK_WRITE 0x01 /** Don't wait for other locks to be released. */ #define RTFILE_LOCK_IMMEDIATELY 0x00 /** Wait till conflicting locks have been released. */ #define RTFILE_LOCK_WAIT 0x02 /** Valid flags mask */ #define RTFILE_LOCK_MASK 0x03 /** @} */ /** * 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. */ RTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock); /** * 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. */ RTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock); /** * 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. */ RTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock); /** * 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. */ RTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs); /** * 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 * not specified. * * @remark POSIX can only set Access & Modification and will always set both. */ RTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime, PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime); /** * 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(). */ RTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime, PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime); /** * 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. */ RTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode); /** * 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(). */ RTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode); /** * 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. */ RTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid); /** * 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(). */ RTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid); /** * 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. */ RTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet); /** * Reads the file into memory. * * The caller must free the memory using RTFileReadAllFree(). * * @returns IPRT status code. * @param pszFilename The name of the file. * @param ppvFile Where to store the pointer to the memory on successful return. * @param pcbFile Where to store the size of the returned memory. * * @remarks Note that this function may be implemented using memory mapping, which means * that the file may remain open until RTFileReadAllFree() is called. It also * means that the return memory may reflect the state of the file when it's * accessed instead of when this call was done. So, in short, don't use this * API for volatile files, then rather use the extended variant with a * yet-to-be-defined. */ RTDECL(int) RTFileReadAll(const char *pszFilename, void **ppvFile, size_t *pcbFile); /** * Reads the file into memory. * * The caller must free the memory using RTFileReadAllFree(). * * @returns IPRT status code. * @param pszFilename The name of the file. * @param off The offset to start reading at. * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX * to read to the end of the file. * @param fFlags See RTFILE_RDALL_*. * @param ppvFile Where to store the pointer to the memory on successful return. * @param pcbFile Where to store the size of the returned memory. * * @remarks See the remarks for RTFileReadAll. */ RTDECL(int) RTFileReadAllEx(const char *pszFilename, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile); /** * Reads the file into memory. * * The caller must free the memory using RTFileReadAllFree(). * * @returns IPRT status code. * @param File The handle to the file. * @param ppvFile Where to store the pointer to the memory on successful return. * @param pcbFile Where to store the size of the returned memory. * * @remarks See the remarks for RTFileReadAll. */ RTDECL(int) RTFileReadAllByHandle(RTFILE File, void **ppvFile, size_t *pcbFile); /** * Reads the file into memory. * * The caller must free the memory using RTFileReadAllFree(). * * @returns IPRT status code. * @param File The handle to the file. * @param off The offset to start reading at. * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX * to read to the end of the file. * @param fFlags See RTFILE_RDALL_*. * @param ppvFile Where to store the pointer to the memory on successful return. * @param pcbFile Where to store the size of the returned memory. * * @remarks See the remarks for RTFileReadAll. */ RTDECL(int) RTFileReadAllByHandleEx(RTFILE File, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile); /** * Frees the memory returned by one of the RTFileReadAll(), RTFileReadAllEx(), * RTFileReadAllByHandle() and RTFileReadAllByHandleEx() functions. * * @param pvFile Pointer to the memory. * @param cbFile The size of the memory. */ RTDECL(void) RTFileReadAllFree(void *pvFile, size_t cbFile); /** @name RTFileReadAllEx and RTFileReadAllHandleEx flags * The open flags are ignored by RTFileReadAllHandleEx. * @{ */ #define RTFILE_RDALL_O_DENY_NONE RTFILE_O_DENY_NONE #define RTFILE_RDALL_O_DENY_READ RTFILE_O_DENY_READ #define RTFILE_RDALL_O_DENY_WRITE RTFILE_O_DENY_WRITE #define RTFILE_RDALL_O_DENY_READWRITE RTFILE_O_DENY_READWRITE #define RTFILE_RDALL_O_DENY_ALL RTFILE_O_DENY_ALL #define RTFILE_RDALL_O_DENY_NOT_DELETE RTFILE_O_DENY_NOT_DELETE #define RTFILE_RDALL_O_DENY_MASK RTFILE_O_DENY_MASK /** Mask of valid flags. */ #define RTFILE_RDALL_VALID_MASK RTFILE_RDALL_O_DENY_MASK /** @} */ /** @page pg_rt_asyncio RT File async I/O API * * File operations are usually blocking the calling thread until * they completed making it impossible to let the thread do anything * else inbetween. * The RT File async I/O API provides an easy and efficient way to * access files asynchronously using the native facilities provided * by each operating system. * * @section sec_rt_asyncio_objects Objects * * There are two objects used in this API. * The first object is the request. A request contains every information * needed two complete the file operation successfully like the start offset * and pointer to the source or destination buffer. * Requests are created with RTFileAioReqCreate() and destroyed with * RTFileAioReqDestroy(). * Because creating a request may require allocating various operating * system dependent ressources and may be quite expensive it is possible * to use a request more than once to save CPU cycles. * A request is constructed with either RTFileAioReqPrepareRead() * which will set up a request to read from the given file or * RTFileAioReqPrepareWrite() which will write to a given file. * * The second object is the context. A file is associated with a context * and requests for this file may complete only on the context the file * was associated with and not on the context given in RTFileAioCtxSubmit() * (see below for further information). * RTFileAioCtxWait() is used to wait for completion of requests which were * associated with the context. While waiting for requests the thread can not * respond to global state changes. Thatswhy the API provides a way to let * RTFileAioCtxWait() return immediately no matter how many requests * have finished through RTFileAioCtxWakeup(). The return code is * VERR_INTERRUPTED to let the thread know that he got interrupted. * * @section sec_rt_asyncio_request_states Request states * * Created: * After a request was created with RTFileAioReqCreate() it is in the same state * like it just completed successfully. RTFileAioReqGetRC() will return VINF_SUCCESS * and a transfer size of 0. RTFileAioReqGetUser() will return NULL. The request can be * destroyed RTFileAioReqDestroy(). It is also allowed to prepare a the request * for a data transfer with the RTFileAioReqPrepare* methods. * Calling any other method like RTFileAioCtxSubmit() will return VERR_FILE_AIO_NOT_PREPARED * and RTFileAioReqCancel() returns VERR_FILE_AIO_NOT_SUBMITTED. * * Prepared: * A request will enter this state if one of the RTFileAioReqPrepare* methods * is called. In this state you can still destroy and retrieve the user data * associated with the request but trying to cancel the request or getting * the result of the operation will return VERR_FILE_AIO_NOT_SUBMITTED. * * Submitted: * A prepared request can be submitted with RTFileAioCtxSubmit(). If the operation * succeeds it is not allowed to touch the request or free any ressources until * it completed through RTFileAioCtxWait(). The only allowed method is RTFileAioReqCancel() * which tries to cancel the request. The request will go into the completed state * and RTFileAioReqGetRC() will return VERR_FILE_AIO_CANCELED. * If the request completes not matter if successfully or with an error it will * switch into the completed state. RTFileReqDestroy() fails if the given request * is in this state. * * Completed: * The request will be in this state after it completed and returned through * RTFileAioCtxWait(). RTFileAioReqGetRC() returns the final result code * and the number of bytes transfered. * The request can be used for new data transfers. * * @section sec_rt_asyncio_threading Threading * * The API is a thin wrapper around the specific host OS APIs and therefore * relies on the thread safety of the underlying API. * The interesting functions with regards to thread safety are RTFileAioCtxSubmit() * and RTFileAioCtxWait(). RTFileAioCtxWait() must not be called from different * threads at the same time with the same context handle. The same applies to * RTFileAioCtxSubmit(). However it is possible to submit new requests from a different * thread while waiting for completed requests on another thread with RTFileAioCtxWait(). * * @section sec_rt_asyncio_implementations Differences in implementation * * Because the host APIs are quite different on every OS and every API has other limitations * there are some things to consider to make the code as portable as possible. * * The first restriction at the moment is that every buffer has to be aligned to a 512 byte boundary. * This limitation comes from the Linux io_* interface. To use the interface the file * must be opened with O_DIRECT. This flag disables the kernel cache too which may * degrade performance but is unfortunately the only way to make asynchronous * I/O work till today (if O_DIRECT is omitted io_submit will revert to sychronous behavior * and will return when the requests finished and when they are queued). * It is mostly used by DBMS which do theire own caching. * Furthermore there is no filesystem independent way to discover the restrictions at least * for the 2.4 kernel series. Since 2.6 the 512 byte boundary seems to be used by all * file systems. So Linus comment about this flag is comprehensible but Linux * lacks an alternative at the moment. * * The next limitation applies only to Windows. Requests are not associated with the * I/O context they are associated with but with the file the request is for. * The file needs to be associated with exactly one I/O completion port and requests * for this file will only arrive at that context after they completed and not on * the context the request was submitted. * To associate a file with a specific context RTFileAioCtxAssociateWithFile() is * used. It is only implemented on Windows and does nothing on the other platforms. * If the file needs to be associated with different context for some reason * the file must be closed first. After it was opened again the new context * can be associated with the other context. * This can't be done by the API because there is no way to retrieve the flags * the file was opened with. */ /** * Global limits for the AIO API. */ typedef struct RTFILEAIOLIMITS { /** Global number of simultaneous outstanding requests allowed. * RTFILEAIO_UNLIMITED_REQS means no limit. */ uint32_t cReqsOutstandingMax; /** The alignment data buffers need to have. * 0 means no alignment restrictions. */ uint32_t cbBufferAlignment; } RTFILEAIOLIMITS; /** A pointer to a AIO limits structure. */ typedef RTFILEAIOLIMITS *PRTFILEAIOLIMITS; /** * Returns the global limits for the AIO API. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the host does not support the async I/O API. * * @param pAioLimits Where to store the global limit information. */ RTDECL(int) RTFileAioGetLimits(PRTFILEAIOLIMITS pAioLimits); /** * Creates an async I/O request handle. * * @returns IPRT status code. * @param phReq Where to store the request handle. */ RTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phReq); /** * Destroys an async I/O request handle. * * @returns IPRT status code. * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress. * * @param hReq The request handle. */ RTDECL(int) RTFileAioReqDestroy(RTFILEAIOREQ hReq); /** * Prepares an async read request. * * @returns IPRT status code. * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress. * * @param hReq The request handle. * @param hFile The file to read from. * @param off The offset to start reading at. * @param pvBuf Where to store the read bits. * @param cbRead Number of bytes to read. * @param pvUser Opaque user data associated with this request which * can be retrieved with RTFileAioReqGetUser(). */ RTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off, void *pvBuf, size_t cbRead, void *pvUser); /** * Prepares an async write request. * * @returns IPRT status code. * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress. * * @param hReq The request handle. * @param hFile The file to write to. * @param off The offset to start writing at. * @param pvBuf Where to store the written bits. * @param cbRead Number of bytes to write. * @param pvUser Opaque user data associated with this request which * can be retrieved with RTFileAioReqGetUser(). */ RTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off, void *pvBuf, size_t cbWrite, void *pvUser); /** * Prepares an async flush of all cached data associated with a file handle. * * @returns IPRT status code. * @retval VERR_FILE_AIO_IN_PROGRESS if the request is still in progress. * * @param hReq The request handle. * @param hFile The file to flush. * @param pvUser Opaque user data associated with this request which * can be retrieved with RTFileAioReqGetUser(). * * @remarks May also flush other caches on some platforms. */ RTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ hReq, RTFILE hFile, void *pvUser); /** * Gets the opaque user data associated with the given request. * * @returns Opaque user data. * @retval NULL if the request hasn't been prepared yet. * * @param hReq The request handle. */ RTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hReq); /** * Cancels a pending request. * * @returns IPRT status code. * @retval VINF_SUCCESS If the request was canceled. * @retval VERR_FILE_AIO_NOT_SUBMITTED If the request wasn't submitted yet. * @retval VERR_FILE_AIO_IN_PROGRESS If the request could not be canceled because it is already processed. * @retval VERR_FILE_AIO_COMPLETED If the request could not be canceled because it already completed. * * @param hReq The request to cancel. */ RTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hReq); /** * Gets the status of a completed request. * * @returns The IPRT status code of the given request. * @retval VERR_FILE_AIO_NOT_SUBMITTED if the request wasn't submitted yet. * @retval VERR_FILE_AIO_CANCELED if the request was canceled. * @retval VERR_FILE_AIO_IN_PROGRESS if the request isn't yet completed. * * @param hReq The request handle. * @param pcbTransferred Where to store the number of bytes transfered. * Optional since it is not relevant for all kinds of * requests. */ RTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hReq, size_t *pcbTransfered); /** * Creates an async I/O context. * * @todo briefly explain what an async context is here or in the page * above. * * @returns IPRT status code. * @param phAioCtx Where to store the async I/O context handle. * @param cAioReqsMax How many async I/O requests the context should be capable * to handle. Pass RTFILEAIO_UNLIMITED_REQS if the * context should support an unlimited number of * requests. */ RTDECL(int) RTFileAioCtxCreate(PRTFILEAIOCTX phAioCtx, uint32_t cAioReqsMax); /** Unlimited number of requests. * Used with RTFileAioCtxCreate and RTFileAioCtxGetMaxReqCount. */ #define RTFILEAIO_UNLIMITED_REQS UINT32_MAX /** * Destroys an async I/O context. * * @returns IPRT status code. * @param hAioCtx The async I/O context handle. */ RTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioCtx); /** * Get the maximum number of requests one aio context can handle. * * @returns Maximum number of tasks the context can handle. * RTFILEAIO_UNLIMITED_REQS if there is no limit. * * @param hAioCtx The async I/O context handle. * If NIL_RTAIOCONTEXT is passed the maximum value * which can be passed to RTFileAioCtxCreate() * is returned. */ RTDECL(uint32_t) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioCtx); /** * Associates a file with a async I/O context. * Requests for this file will arrive at the completion port * associated with the file. * * @returns IPRT status code. * * @param hAioCtx The async I/O context handle. * @param hFile The file handle. */ RTDECL(int) RTFileAioCtxAssociateWithFile(RTFILEAIOCTX hAioCtx, RTFILE hFile); /** * Submits a set of requests to an async I/O context for processing. * * @returns IPRT status code. * @returns VERR_FILE_AIO_INSUFFICIENT_RESSOURCES if the maximum number of * simultaneous outstanding requests would be exceeded. * * @param hAioCtx The async I/O context handle. * @param pahReqs Pointer to an array of request handles. * @param cReqs The number of entries in the array. * * @remarks It is possible that some requests could be submitted successfully * even if the method returns an error code. In that case RTFileAioReqGetRC() * can be used to determine the status of a request. * If it returns VERR_FILE_AIO_IN_PROGRESS it was submitted successfully. * Any other error code may indicate why the request failed. * VERR_FILE_AIO_NOT_SUBMITTED indicates that a request wasn't submitted * probably because the previous request encountered an error. * * @remarks @a cReqs uses the type size_t while it really is a uint32_t, this is * to avoid annoying warnings when using RT_ELEMENTS and similar * macros. */ RTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioCtx, PRTFILEAIOREQ pahReqs, size_t cReqs); /** * Waits for request completion. * * Only one thread at a time may call this API on a context. * * @returns IPRT status code. * @retval VERR_INVALID_POINTER If pcReqs or/and pahReqs are invalid. * @retval VERR_INVALID_HANDLE If hAioCtx is invalid. * @retval VERR_OUT_OF_RANGE If cMinReqs is larger than cReqs. * @retval VERR_INVALID_PARAMETER If cReqs is 0. * @retval VERR_TIMEOUT If cMinReqs didn't complete before the * timeout expired. * @retval VERR_INTERRUPTED If the completion context was interrupted * by RTFileAioCtxWakeup(). * @retval VERR_FILE_AIO_NO_REQUEST If there are no pending request. * * @param hAioCtx The async I/O context handle to wait and get * completed requests from. * @param cMinReqs The minimum number of requests which have to * complete before this function returns. * @param cMillisTimeout The number of milliseconds to wait before returning * VERR_TIMEOUT. Use RT_INDEFINITE_WAIT to wait * forever. * @param pahReqs Pointer to an array where the handles of the * completed requests will be stored on success. * @param cReqs The number of entries @a pahReqs can hold. * @param pcReqs Where to store the number of returned (complete) * requests. This will always be set. * * @remarks The wait will be resume if interrupted by a signal. An * RTFileAioCtxWaitNoResume variant can be added later if it becomes * necessary. * * @remarks @a cMinReqs and @a cReqs use the type size_t while they really are * uint32_t's, this is to avoid annoying warnings when using * RT_ELEMENTS and similar macros. */ RTDECL(int) RTFileAioCtxWait(RTFILEAIOCTX hAioCtx, size_t cMinReqs, unsigned cMillisTimeout, PRTFILEAIOREQ pahReqs, size_t cReqs, uint32_t *pcReqs); /** * Forces any RTFileAioCtxWait() call on another thread to return immediately. * * @returns IPRT status code. * * @param hAioCtx The handle of the async I/O context to wakeup. */ RTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioCtx); #endif /* IN_RING3 */ /** @} */ RT_C_DECLS_END #endif