source: vbox/trunk/include/iprt/file.h@ 23305

/** @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 <iprt/cdefs.h>
#include <iprt/types.h>
#ifdef IN_RING3
# include <iprt/fs.h>
#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. Furthermore FILE_APPEND_DATA
 *          is disabled. To write beyond the size of file use RTFileSetSize prior
 *          writing the data to the file.
 *
 *          This flag does not work on Solaris if the target filesystem is ZFS. RTFileOpen will return an
 *          error with that configuration. When used with UFS the same alginment restrictions
 *          apply like Linux and Windows.
 *
 * @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