file.h revision b1832549d0212157df12ef3337ef904d2d932143
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * IPRT - File I/O.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Copyright (C) 2006-2007 Sun Microsystems, Inc.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This file is part of VirtualBox Open Source Edition (OSE), as
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * available from http://www.virtualbox.org. This file is free software;
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * you can redistribute it and/or modify it under the terms of the GNU
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * General Public License (GPL) as published by the Free Software
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Foundation, in version 2 as it comes in the "COPYING" file of the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The contents of this file may alternatively be used under the terms
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * of the Common Development and Distribution License Version 1.0
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * VirtualBox OSE distribution, in which case the provisions of the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * CDDL are applicable instead of those of the GPL.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * You may elect to license modified versions of this file under the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * terms and conditions of either the GPL or the CDDL or both.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Clara, CA 95054 USA or visit http://www.sun.com if you need
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * additional information or have any questions.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @defgroup grp_rt_fileio RTFile - File I/O
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @ingroup grp_rt
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Platform specific text line break.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#if defined(RT_OS_OS2) || defined(RT_OS_WINDOWS)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @name Open flags
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Open the file with read access. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Open the file with write access. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Open the file with read & write access. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** The file access mask.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark The value 0 is invalid. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: deny none (the default mode). */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: deny read. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: deny write. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: deny read and write. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: deny all. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILE_O_DENY_ALL RTFILE_O_DENY_READWRITE
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode: do NOT deny delete (NT).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This might not be implemented on all platforms,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will be defaulted & ignored on those.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Sharing mode mask. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Action: Open an existing file (the default action). */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Action: Create a new file or open an existing one. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Action: Create a new a file. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Action: Create a new file or replace an existing one. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Action mask. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Turns off indexing of files on Windows hosts, *CREATE* only.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This might not be implemented on all platforms,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will be ignored on those.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILE_O_NOT_CONTENT_INDEXED 0x00000800
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Truncate the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This will not truncate files opened for read-only.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark The trunction doesn't have to be atomically, so anyone
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * else opening the file may be racing us. The caller is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * responsible for not causing this race. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Make the handle inheritable on RTProcessCreate(/exec). */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Open file in non-blocking mode - non-portable.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This flag may not be supported on all platforms, in which
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * case it's considered an invalid parameter.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Write through directly to disk. Workaround to avoid iSCSI
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * initiator deadlocks on Windows hosts.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This might not be implemented on all platforms,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will be ignored on those.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** File attributes access, *CREATE* only.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This might not be implemented on all platforms,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will be ignored on those.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Attributes can be read if the file is being opened
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * with read access, and can be written with write access.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILE_O_ACCESS_ATTR_DEFAULT 0x00000000
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Attributes can be read. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Attributes can be written. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Attributes can be both read & written. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILE_O_ACCESS_ATTR_READWRITE 0x00030000
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** The file attributes access mask. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Unix file mode mask for use when creating files. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** The number of bits to shift to get the file mode mask.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * To extract it: (fFlags & RTFILE_O_CREATE_MODE_MASK) >> RTFILE_O_CREATE_MODE_SHIFT.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Open file for async I/O
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This flag may not be needed on all platforms,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will be ignored on those.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Mask of all valid flags.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This doesn't validate the access mode properly.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Force the use of open flags for all files opened after the setting is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * changed. The caller is responsible for not causing races with RTFileOpen().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fOpenForAccess Access mode to which the set/mask settings apply.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fSet Open flags to be forced set.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fMask Open flags to be masked out.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Open a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pFile Where to store the handle to the opened file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszFilename Path to the file which is to be opened. (UTF-8)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Close a file opened by RTFileOpen().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File The file handle to close.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Creates an IPRT file handle from a native one.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pFile Where to store the IPRT file handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param uNative The native handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileFromNative(PRTFILE pFile, RTHCINTPTR uNative);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the native handle for an IPRT file handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @return The native handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @params File The IPRT file handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(RTHCINTPTR) RTFileToNative(RTFILE File);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Delete a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszFilename Path to the file which is to be deleted. (UTF-8)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @todo This is a RTPath api!
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileDelete(const char *pszFilename);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @name Seek flags.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Seek from the start of the file. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Seek from the current file position. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Seek from the end of the file. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @internal */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @internal */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Changes the read & write position in a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param offSeek Offset to seek.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param poffActual Where to store the new file position.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * NULL is allowed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Read bytes from a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf Where to put the bytes we read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbToRead How much to read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param *pcbRead How much we actually read .
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If NULL an error will be returned for a partial read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Read bytes from a file at a given offset.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This function may modify the file position.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off Where to read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf Where to put the bytes we read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbToRead How much to read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param *pcbRead How much we actually read .
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If NULL an error will be returned for a partial read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Write bytes to a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf What to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbToWrite How much to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param *pcbWritten How much we actually wrote.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If NULL an error will be returned for a partial write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Write bytes to a file at a given offset.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This function may modify the file position.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off Where to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf What to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbToWrite How much to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param *pcbWritten How much we actually wrote.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If NULL an error will be returned for a partial write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Flushes the buffers for the specified file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Set the size of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbSize The new file size.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Query the size of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbSize Where to store the filesize.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Determine the maximum file size.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns The max size of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * -1 on failure, the file position is undefined.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @see RTFileGetMaxSizeEx.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Determine the maximum file size.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbMax Where to store the max file size.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @see RTFileGetMaxSize.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileGetMaxSizeEx(RTFILE File, PRTFOFF pcbMax);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Determine the maximum file size depending on the file system the file is stored on.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns The max size of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * -1 on failure.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(RTFOFF) RTFileGetMaxSize(RTFILE File);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the current file position.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns File offset.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns ~0UUL on failure.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Checks if the supplied handle is valid.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns true if valid.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns false if invalid.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File The file handle
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Copies a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_ALREADY_EXISTS if the destination file exists.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VBox Status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszSrc The path to the source file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszDst The path to the destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This file will be created.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Copies a file given the handles to both files.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VBox Status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param FileSrc The source file. The file position is unaltered.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param FileDst The destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * On successful returns the file position is at the end of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * On failures the file position and size is undefined.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Flags for RTFileCopyEx().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE RT_BIT(0)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Do not use RTFILE_O_DENY_WRITE on the target file. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILECOPY_FLAGS_NO_DST_DENY_WRITE RT_BIT(1)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Do not use RTFILE_O_DENY_WRITE on either of the two files. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILECOPY_FLAGS_NO_DENY_WRITE ( RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE | RTFILECOPY_FLAGS_NO_DST_DENY_WRITE )
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#define RTFILECOPY_FLAGS_MASK UINT32_C(0x00000003)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Copies a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_ALREADY_EXISTS if the destination file exists.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VBox Status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszSrc The path to the source file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszDst The path to the destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This file will be created.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fFlags Flags (RTFILECOPY_*).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pfnProgress Pointer to callback function for reporting progress.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Copies a file given the handles to both files and
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * provide progress callbacks.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param FileSrc The source file. The file position is unaltered.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param FileDst The destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * On successful returns the file position is at the end of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * On failures the file position and size is undefined.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pfnProgress Pointer to callback function for reporting progress.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Renames a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Identical to RTPathRename except that it will ensure that the source is not a directory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_ALREADY_EXISTS if the destination file exists.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszSrc The path to the source file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszDst The path to the destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This file will be created.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fRename See RTPathRename.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @name RTFileMove flags (bit masks).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Replace destination file if present. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Moves a file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileMove differs from RTFileRename in that it works across volumes.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_ALREADY_EXISTS if the destination file exists.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszSrc The path to the source file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszDst The path to the destination file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This file will be created.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fMove A combination of the RTFILEMOVE_* flags.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @page pg_rt_filelock RT File locking API description
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * File locking general rules:
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Region to lock or unlock can be located beyond the end of file, this can be used for
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * growing files.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Read (or Shared) locks can be acquired held by an unlimited number of processes at the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * same time, but a Write (or Exclusive) lock can only be acquired by one process, and
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * there are no processes holding any Write locks. To acquire a Write lock, a process must
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * wait until there are no processes holding either kind of lock.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * can't be acquired due to conflict with other locks, however they can be called in wait mode.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Differences in implementation:
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * I.e. when file region is locked in Read mode, any write in it will fail; in case of Write
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * lock - region can be readed and writed only by lock's owner.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * operation system. Also see comments to RTFileChangeLock API call.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * may use locks to coordinate access to a file between themselves, but programs are also free
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to ignore locks and access the file in any way they choose to.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Additional reading:
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * http://unixhelp.ed.ac.uk/CGI/man-cgi?fcntl+2
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @name Lock flags (bit masks).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Read access, can be shared with others. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Write access, one at a time. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Don't wait for other locks to be released. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Wait till conflicting locks have been released. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Valid flags mask */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Locks a region of file for read (shared) or write (exclusive) access.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param offLock Offset of lock start.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbLock Length of region to lock, may overlap the end of file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Changes a lock type from read to write or from write to read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The region to type change must correspond exactly to an existing locked region.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If change can't be done due to locking conflict and non-blocking mode is used, error is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * returned and lock keeps its state (see next warning).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * WARNING: win32 implementation of this call is not atomic, it transforms to a pair of
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * be acquired, and old lock (previous state) can't be acquired back too. This situation
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * in race condition with the current call.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * In this very bad case special error code VERR_FILE_LOCK_LOST will be returned.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_FILE_NOT_LOCKED if region was not locked.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :(
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param offLock Offset of lock start.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbLock Length of region to lock, may overlap the end of file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Unlocks previously locked region of file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The region to unlock must correspond exactly to an existing locked region.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_FILE_NOT_LOCKED if region was not locked.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param offLock Offset of lock start.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbLock Length of region to unlock, may overlap the end of file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Query information about an open file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pObjInfo Object information structure to be filled on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param enmAdditionalAttribs Which set of additional attributes to request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Changes one or more of the timestamps associated of file system object.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pAccessTime Pointer to the new access time. NULL if not to be changed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark The file system might not implement all these time attributes,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * the API will ignore the ones which aren't supported.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark The file system might not implement the time resolution
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * employed by this interface, the time will be chopped to fit.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark The file system may update the change time even if it's
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * not specified.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark POSIX can only set Access & Modification and will always set both.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets one or more of the timestamps associated of file system object.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pAccessTime Where to store the access time. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pModificationTime Where to store the modifcation time. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pChangeTime Where to store the change time. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pBirthTime Where to store the time of birth. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper PRTTIMESPEC pChangeTime, PRTTIMESPEC pBirthTime);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Changes the mode flags of an open file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The API requires at least one of the mode flag sets (Unix/Dos) to
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * be set. The type is ignored.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fMode The new file mode, see @ref grp_rt_fs for details.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the mode flags of an open file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This is wrapper around RTFileQueryInfo()
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and exists to complement RTFileSetMode().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Changes the owner and/or group of an open file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the owner and/or group of an open file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pUid Where to store the owner user id. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pGid Where to store the group id. NULL is ok.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Executes an IOCTL on a file descriptor.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This function is currently only available in L4 and posix environments.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Attemps at calling it from code shared with any other platforms will break things!
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The rational for defining this API is to simplify L4 porting of audio drivers,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and to remove some of the assumptions on RTFILE being a file descriptor on
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * platforms using the posix file implementation.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns iprt status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File Handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param iRequest IOCTL request to carry out.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvData IOCTL data.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbData Size of the IOCTL data.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param piRet Return value of the IOCTL request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Reads the file into memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The caller must free the memory using RTFileReadAllFree().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszFilename The name of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param ppvFile Where to store the pointer to the memory on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbFile Where to store the size of the file on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks Note that this function may be implemented using memory mapping, which means
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * that the file may remain open until RTFileReadAllFree() is called. It also
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * means that the return memory may reflect the state of the file when it's
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * accessed instead of when this call was done. So, in short, don't use this
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * API for volatile files, then rather use the extended variant with a
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * yet-to-be-defined.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileReadAll(const char *pszFilename, void **ppvFile, size_t *pcbFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Reads the file into memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The caller must free the memory using RTFileReadAllFree().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pszFilename The name of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off The offset to start reading at.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to read to the end of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fFlags Flags for the future, must be 0.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param ppvFile Where to store the pointer to the memory on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbFile Where to store the size of the file on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks See the remarks for RTFileReadAll.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileReadAllEx(const char *pszFilename, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Reads the file into memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The caller must free the memory using RTFileReadAllFree().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File The handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param ppvFile Where to store the pointer to the memory on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbFile Where to store the size of the file on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks See the remarks for RTFileReadAll.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileReadAllByHandle(RTFILE File, void **ppvFile, size_t *pcbFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Reads the file into memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The caller must free the memory using RTFileReadAllFree().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param File The handle to the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off The offset to start reading at.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to read to the end of the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param fFlags Flags for the future, must be 0.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param ppvFile Where to store the pointer to the memory on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbFile Where to store the size of the file on successful return.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks See the remarks for RTFileReadAll.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileReadAllByHandleEx(RTFILE File, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Frees the memory returned by one of the RTFileReadAll(), RTFileReadAllEx(),
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileReadAllByHandle() and RTFileReadAllByHandleEx() functions.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvFile Pointer to the memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbFile The size of the memory.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(void) RTFileReadAllFree(void *pvFile, size_t cbFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** @page pg_rt_asyncio RT File async I/O API
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * File operations are usually blocking the calling thread until
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * they completed making it impossible to let the thread do anything
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * else inbetween.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The RT File async I/O API provides an easy and efficient way to
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * access files asynchronously using the native facilities provided
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * by each operating system.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * There are two objects used in this API.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The first object is the request. A request contains every information
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * needed two complete the file operation successfully like the start offset
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and pointer to the source or destination buffer.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Requests are created with RTFileAioReqCreate() and destroyed with
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioReqDestroy().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Because creating a request may require allocating various operating
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * system dependent ressources and may be quite expensive it is possible
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to use a request more than once to save CPU cycles.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * A request is constructed with either RTFileAioReqPrepareRead()
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * which will set up a request to read from the given file or
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioReqPrepareWrite() which will write to a given file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The second object is the context. A file is associated with a context
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and requests for this file may complete only on the context the file
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * was associated with and not on the context given in RTFileAioCtxSubmit()
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * (see below for further information).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioCtxWait() is used to wait for completion of requests which were
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * associated with the context. While waiting for requests the thread can not
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * respond to global state changes. Thatswhy the API provides a way to let
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioCtxWait() return immediately no matter how many requests
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * have finished through RTFileAioCtxWakeup(). The return code is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * VERR_INTERRUPTED to let the thread know that he got interrupted.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The API is a thin wrapper around the specific host OS APIs and therefore
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * relies on the thread safety of the underlying API.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The interesting functions with regards to thread safety are RTFileAioCtxSubmit()
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and RTFileAioCtxWait(). RTFileAioCtxWait() must not be called from different
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * threads at the same time with the same context handle. The same applies to
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioCtxSubmit(). However it is possible to submit new requests from a different
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * thread while waiting for completed requests on another thread with RTFileAioCtxWait().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Differences in implementation:
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Because the host APIs are quite different on every OS and every API has other limitations
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * there are some things to consider to make the code as portable as possible.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The first restriction at the moment is that every buffer has to be aligned to a 512 byte boundary.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This limitation comes from the Linux io_* interface. To use the interface the file
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * must be opened with O_DIRECT. This flag disables the kernel cache too which may
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * degrade performance but is unfortunately the only way to make asynchronous
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * I/O work till today (if O_DIRECT is omitted io_submit will revert to sychronous behavior
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * and will return when the requests finished and when they are queued).
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * It is mostly used by DBMS which do theire own caching.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Furthermore there is no filesystem independent way to discover the restrictions at least
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * for the 2.4 kernel series. Since 2.6 the 512 byte boundary seems to be used by all
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * file systems. So Linus comment about this flag is comprehensible but Linux
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * lacks an alternative at the moment.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The next limitation applies only to Windows. Reqeusts are not assoicated with the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * I/O context they are associated with but with the file the request is for.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * The file needs to be associated with exactly one I/O completion port and requests
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * for this file will only arrive at that context after they completed and not on
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * the context the request was submitted.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * To associate a file with a specific context RTFileAioCtxAssociateWithFile() is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * used. It is only implemented on Windows and does nothing on the other platforms.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If the file needs to be associated with different context for some reason
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * the file must be closed first. After it was opened again the new context
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * can be associated with the other context.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * This can't be done by the API because there is no way to retrieve the flags
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * the file was opened with.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Creates an async I/O request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param phReq Where to store the request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phReq);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Destroys an async I/O request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(void) RTFileAioReqDestroy(RTFILEAIOREQ hReq);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Prepares an async read request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hFile The file to read from.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off The offset to start reading at.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf Where to store the read bits.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbRead Number of bytes to read.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvUser Opaque user data associated with this request which
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * can be retrieved with RTFileAioReqGetUser().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Prepares an async write request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hFile The file to write to.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param off The offset to start writing at.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvBuf Where to store the written bits.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cbRead Number of bytes to write.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvUser Opaque user data associated with this request which
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * can be retrieved with RTFileAioReqGetUser().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hReq, RTFILE hFile, RTFOFF off,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Prepares an async flush of all cached data associated with a file handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hFile The file to flush.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pvUser Opaque user data associated with this request which
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * can be retrieved with RTFileAioReqGetUser().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks May also flush other caches on some platforms.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ hReq, RTFILE hFile, void *pvUser);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the opaque user data associated with the given request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns Opaque user data.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval NULL if the request hasn't been prepared yet.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hReq);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Cancels a pending request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VINF_SUCCESS If the request was canceled.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_FILE_AIO_IN_PROGRESS If the request could not be canceled because it is already processed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_FILE_AIO_COMPLETED If the request could not be canceled because it already completed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request to cancel.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hReq);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Gets the status of a completed request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns The IPRT status code of the given request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_FILE_AIO_IN_PROGRESS if the request isn't yet completed.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hReq The request handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcbTransferred Where to store the number of bytes transfered.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Optional since it is not relevant for all kinds of
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hReq, size_t *pcbTransfered);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Creates an async I/O context.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @todo briefly explain what an async context is here or in the page
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param phAioCtx Where to store the async I/O context handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cAioReqsMax How many async I/O requests the context should be capable
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to handle. Pass RTFILEAIO_UNLIMITED_REQS if the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * context should support an unlimited number of
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxCreate(PRTFILEAIOCTX phAioCtx, uint32_t cAioReqsMax);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper/** Unlimited number of requests.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Used with RTFileAioCtxCreate and RTFileAioCtxGetMaxReqCount. */
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Destroys an async I/O context.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The async I/O context handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioCtx);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Get the maximum number of requests one aio context can handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns Maximum number of tasks the context can handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFILEAIO_UNLIMITED_REQS if there is no limit.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The async I/O context handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * If NIL_RTAIOCONTEXT is passed the maximum value
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * which can be passed to RTFileAioCtxCreate()
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * is returned.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(uint32_t) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioCtx);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Associates a file with a async I/O context.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Requests for this file will arrive at the completion port
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * associated with the file.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The async I/O context handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hFile The file handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxAssociateWithFile(RTFILEAIOCTX hAioCtx, RTFILE hFile);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Submits a set of requests to an async I/O context for processing.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The async I/O context handle.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pahReqs Pointer to an array of request handles.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cReqs The number of entries in the array.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcReqs Where to store the number of requests
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * successfully submitted before an error
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * occured. If VINF_SUCCESS is returned
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * the value equals cReqs. This value is always
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks @a cReqs uses the type size_t while it really is a uint32_t, this is
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * to avoid annoying warnings when using RT_ELEMENTS and similar
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioCtx, PRTFILEAIOREQ pahReqs, size_t cReqs, size_t *pcReqs);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Waits for request completion.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Only one thread at a time may call this API on a context.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_INVALID_POINTER If pcReqs or/and pahReqs are invalid.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_INVALID_HANDLE If hAioCtx is invalid.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_OUT_OF_RANGE If cMinReqs is larger than cReqs.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_INVALID_PARAMETER If cReqs is 0.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_TIMEOUT If cMinReqs didn't complete before the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * timeout expired.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_INTERRUPTED If the completion context was interrupted
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * by RTFileAioCtxWakeup().
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @retval VERR_FILE_AIO_NO_REQUEST If there are no pending request.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The async I/O context handle to wait and get
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * completed requests from.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cMinReqs The minimum number of requests which have to
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * complete before this function returns.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cMillisTimeout The number of milliseconds to wait before returning
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * VERR_TIMEOUT. Use RT_INDEFINITE_WAIT to wait
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pahReqs Pointer to an array where the handles of the
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * completed requests will be stored on success.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param cReqs The number of entries @a pahReqs can hold.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param pcReqs Where to store the number of returned (complete)
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * requests. This will always be set.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks The wait will be resume if interrupted by a signal. An
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RTFileAioCtxWaitNoResume variant can be added later if it becomes
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @remarks @a cMinReqs and @a cReqs use the type size_t while they really are
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * uint32_t's, this is to avoid annoying warnings when using
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * RT_ELEMENTS and similar macros.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxWait(RTFILEAIOCTX hAioCtx, size_t cMinReqs, unsigned cMillisTimeout,
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper PRTFILEAIOREQ pahReqs, size_t cReqs, uint32_t *pcReqs);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * Forces any RTFileAioCtxWait() call on another thread to return immediately.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @returns IPRT status code.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper * @param hAioCtx The handle of the async I/O context to wakeup.
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de ReeperRTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioCtx);
9772159fcd47ec75c7451e49baf2165fecb1f271Mark de Reeper#endif /* IN_RING3 */