file.h revision b319118f2fe592c196d185bf00adfac6086443b8
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * IPRT - File I/O.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Copyright (C) 2006-2007 Sun Microsystems, Inc.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This file is part of VirtualBox Open Source Edition (OSE), as
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * available from http://www.virtualbox.org. This file is free software;
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * you can redistribute it and/or modify it under the terms of the GNU
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * General Public License (GPL) as published by the Free Software
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Foundation, in version 2 as it comes in the "COPYING" file of the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The contents of this file may alternatively be used under the terms
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * of the Common Development and Distribution License Version 1.0
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * VirtualBox OSE distribution, in which case the provisions of the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * CDDL are applicable instead of those of the GPL.
f4e76ddf09a338dc23da0904866290ac36274a5bNattuvetty Bhavyan * You may elect to license modified versions of this file under the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * terms and conditions of either the GPL or the CDDL or both.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Clara, CA 95054 USA or visit http://www.sun.com if you need
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * additional information or have any questions.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @defgroup grp_rt_fileio RTFile - File I/O
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @ingroup grp_rt
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Platform specific text line break.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @deprecated Use text I/O streams and '\\n'. See iprt/stream.h. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @name Open flags
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Open the file with read access. */
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan/** Open the file with write access. */
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan/** Open the file with read & write access. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** The file access mask.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark The value 0 is invalid. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode: deny none (the default mode). */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode: deny read. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode: deny write. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode: deny read and write. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode: deny all. */
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan/** Sharing mode: do NOT deny delete (NT).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This might not be implemented on all platforms,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and will be defaulted & ignored on those.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Sharing mode mask. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Action: Open an existing file (the default action). */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Action: Create a new file or open an existing one. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Action: Create a new a file. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Action: Create a new file or replace an existing one. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Action mask. */
70c284ca5360ed73476d9e94223d4905dd80b1adPeter Cudhea - Sun Microsystems - Burlington, MA United States#define RTFILE_O_ACTION_MASK 0x00000300
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Turns off indexing of files on Windows hosts, *CREATE* only.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This might not be implemented on all platforms,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and will be ignored on those.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Truncate the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This will not truncate files opened for read-only.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark The trunction doesn't have to be atomically, so anyone
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * else opening the file may be racing us. The caller is
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * responsible for not causing this race. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Make the handle inheritable on RTProcessCreate(/exec). */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Open file in non-blocking mode - non-portable.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This flag may not be supported on all platforms, in which
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * case it's considered an invalid parameter.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Write through directly to disk. Workaround to avoid iSCSI
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * initiator deadlocks on Windows hosts.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This might not be implemented on all platforms,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and will be ignored on those.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** File attributes access, *CREATE* only.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This might not be implemented on all platforms,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and will be ignored on those.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Attributes can be read if the file is being opened
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * with read access, and can be written with write access.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Attributes can be read. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Attributes can be written. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Attributes can be both read & written. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** The file attributes access mask. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Unix file mode mask for use when creating files. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** The number of bits to shift to get the file mode mask.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * To extract it: (fFlags & RTFILE_O_CREATE_MODE_MASK) >> RTFILE_O_CREATE_MODE_SHIFT.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Open file for async I/O
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This flag may not be needed on all platforms,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and will be ignored on those.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Mask of all valid flags.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This doesn't validate the access mode properly.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Force the use of open flags for all files opened after the setting is
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * changed. The caller is responsible for not causing races with RTFileOpen().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fOpenForAccess Access mode to which the set/mask settings apply.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fSet Open flags to be forced set.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fMask Open flags to be masked out.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSetForceFlags(unsigned fOpenForAccess, unsigned fSet, unsigned fMask);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Open a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pFile Where to store the handle to the opened file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszFilename Path to the file which is to be opened. (UTF-8)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fOpen Open flags, i.e a combination of the RTFILE_O_* defines.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileOpen(PRTFILE pFile, const char *pszFilename, unsigned fOpen);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Close a file opened by RTFileOpen().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The file handle to close.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Creates an IPRT file handle from a native one.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pFile Where to store the IPRT file handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param uNative The native handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileFromNative(PRTFILE pFile, RTHCINTPTR uNative);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Gets the native handle for an IPRT file handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @return The native handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @params File The IPRT file handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Delete a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszFilename Path to the file which is to be deleted. (UTF-8)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @todo This is a RTPath api!
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileDelete(const char *pszFilename);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @name Seek flags.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Seek from the start of the file. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Seek from the current file position. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Seek from the end of the file. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @internal */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @internal */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Changes the read & write position in a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param offSeek Offset to seek.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param uMethod Seek method, i.e. one of the RTFILE_SEEK_* defines.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param poffActual Where to store the new file position.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * NULL is allowed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSeek(RTFILE File, int64_t offSeek, unsigned uMethod, uint64_t *poffActual);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Read bytes from a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvBuf Where to put the bytes we read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbToRead How much to read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param *pcbRead How much we actually read .
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If NULL an error will be returned for a partial read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileRead(RTFILE File, void *pvBuf, size_t cbToRead, size_t *pcbRead);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Read bytes from a file at a given offset.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This function may modify the file position.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param off Where to read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvBuf Where to put the bytes we read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbToRead How much to read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param *pcbRead How much we actually read .
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If NULL an error will be returned for a partial read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileReadAt(RTFILE File, RTFOFF off, void *pvBuf, size_t cbToRead, size_t *pcbRead);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Write bytes to a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvBuf What to write.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbToWrite How much to write.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param *pcbWritten How much we actually wrote.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If NULL an error will be returned for a partial write.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileWrite(RTFILE File, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * Write bytes to a file at a given offset.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * This function may modify the file position.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @returns iprt status code.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param File Handle to the file.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param off Where to write.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param pvBuf What to write.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param cbToWrite How much to write.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param *pcbWritten How much we actually wrote.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * If NULL an error will be returned for a partial write.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty BhavyanRTR3DECL(int) RTFileWriteAt(RTFILE File, RTFOFF off, const void *pvBuf, size_t cbToWrite, size_t *pcbWritten);
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * Flushes the buffers for the specified file.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Set the size of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbSize The new file size.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSetSize(RTFILE File, uint64_t cbSize);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Query the size of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
7145ae3ec9b6b40ec13b508a7bb1718ce67f4588Nattuvetty Bhavyan * @param pcbSize Where to store the filesize.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileGetSize(RTFILE File, uint64_t *pcbSize);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Determine the maximum file size.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns The max size of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * -1 on failure, the file position is undefined.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @see RTFileGetMaxSizeEx.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Determine the maximum file size.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbMax Where to store the max file size.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @see RTFileGetMaxSize.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileGetMaxSizeEx(RTFILE File, PRTFOFF pcbMax);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Determine the maximum file size depending on the file system the file is stored on.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns The max size of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * -1 on failure.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Gets the current file position.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns File offset.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns ~0UUL on failure.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Checks if the supplied handle is valid.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns true if valid.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns false if invalid.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param File The file handle
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTR3DECL(bool) RTFileIsValid(RTFILE File);
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * Copies a file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns VERR_ALREADY_EXISTS if the destination file exists.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns VBox Status code.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param pszSrc The path to the source file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param pszDst The path to the destination file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * This file will be created.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTDECL(int) RTFileCopy(const char *pszSrc, const char *pszDst);
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * Copies a file given the handles to both files.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns VBox Status code.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param FileSrc The source file. The file position is unaltered.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param FileDst The destination file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * On successful returns the file position is at the end of the file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * On failures the file position and size is undefined.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTDECL(int) RTFileCopyByHandles(RTFILE FileSrc, RTFILE FileDst);
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan/** Flags for RTFileCopyEx().
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan/** Do not use RTFILE_O_DENY_WRITE on the source file to allow for copying files opened for writing. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE RT_BIT(0)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Do not use RTFILE_O_DENY_WRITE on the target file. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define RTFILECOPY_FLAGS_NO_DST_DENY_WRITE RT_BIT(1)
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Do not use RTFILE_O_DENY_WRITE on either of the two files. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#define RTFILECOPY_FLAGS_NO_DENY_WRITE ( RTFILECOPY_FLAGS_NO_SRC_DENY_WRITE | RTFILECOPY_FLAGS_NO_DST_DENY_WRITE )
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Copies a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_ALREADY_EXISTS if the destination file exists.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VBox Status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszSrc The path to the source file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszDst The path to the destination file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This file will be created.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fFlags Flags (RTFILECOPY_*).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pfnProgress Pointer to callback function for reporting progress.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTDECL(int) RTFileCopyEx(const char *pszSrc, const char *pszDst, uint32_t fFlags, PFNRTPROGRESS pfnProgress, void *pvUser);
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * Copies a file given the handles to both files and
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * provide progress callbacks.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns IPRT status code.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param FileSrc The source file. The file position is unaltered.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param FileDst The destination file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * On successful returns the file position is at the end of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * On failures the file position and size is undefined.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pfnProgress Pointer to callback function for reporting progress.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvUser User argument to pass to pfnProgress along with the completion precentage.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileCopyByHandlesEx(RTFILE FileSrc, RTFILE FileDst, PFNRTPROGRESS pfnProgress, void *pvUser);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Renames a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Identical to RTPathRename except that it will ensure that the source is not a directory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_ALREADY_EXISTS if the destination file exists.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszSrc The path to the source file.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param pszDst The path to the destination file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This file will be created.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fRename See RTPathRename.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileRename(const char *pszSrc, const char *pszDst, unsigned fRename);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @name RTFileMove flags (bit masks).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Replace destination file if present. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Moves a file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * RTFileMove differs from RTFileRename in that it works across volumes.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_ALREADY_EXISTS if the destination file exists.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszSrc The path to the source file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszDst The path to the destination file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This file will be created.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fMove A combination of the RTFILEMOVE_* flags.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTDECL(int) RTFileMove(const char *pszSrc, const char *pszDst, unsigned fMove);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @page pg_rt_filelock RT File locking API description
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * File locking general rules:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Region to lock or unlock can be located beyond the end of file, this can be used for
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * growing files.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Read (or Shared) locks can be acquired held by an unlimited number of processes at the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * same time, but a Write (or Exclusive) lock can only be acquired by one process, and
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * cannot coexist with a Shared lock. To acquire a Read lock, a process must wait until
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * there are no processes holding any Write locks. To acquire a Write lock, a process must
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * wait until there are no processes holding either kind of lock.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * By default, RTFileLock and RTFileChangeLock calls returns error immediately if the lock
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * can't be acquired due to conflict with other locks, however they can be called in wait mode.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Differences in implementation:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Win32, OS/2: Locking is mandatory, since locks are enforced by the operating system.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * I.e. when file region is locked in Read mode, any write in it will fail; in case of Write
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * lock - region can be readed and writed only by lock's owner.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Win32: File size change (RTFileSetSize) is not controlled by locking at all (!) in the
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * operation system. Also see comments to RTFileChangeLock API call.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Linux/Posix: By default locks in Unixes are advisory. This means that cooperating processes
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may use locks to coordinate access to a file between themselves, but programs are also free
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * to ignore locks and access the file in any way they choose to.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Additional reading:
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * http://msdn.microsoft.com/library/default.asp?url=/library/en-us/fileio/fs/lockfileex.asp
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @name Lock flags (bit masks).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Read access, can be shared with others. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Write access, one at a time. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Don't wait for other locks to be released. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Wait till conflicting locks have been released. */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** Valid flags mask */
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Locks a region of file for read (shared) or write (exclusive) access.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_FILE_LOCK_VIOLATION if lock can't be acquired.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param offLock Offset of lock start.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbLock Length of region to lock, may overlap the end of file.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTR3DECL(int) RTFileLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * Changes a lock type from read to write or from write to read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The region to type change must correspond exactly to an existing locked region.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If change can't be done due to locking conflict and non-blocking mode is used, error is
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * returned and lock keeps its state (see next warning).
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * WARNING: win32 implementation of this call is not atomic, it transforms to a pair of
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * calls RTFileUnlock and RTFileLock. Potentially the previously acquired lock can be
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * lost, i.e. function is called in non-blocking mode, previous lock is freed, new lock can't
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * be acquired, and old lock (previous state) can't be acquired back too. This situation
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * may occurs _only_ if the other process is acquiring a _write_ lock in blocking mode or
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * in race condition with the current call.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * In this very bad case special error code VERR_FILE_LOCK_LOST will be returned.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_FILE_NOT_LOCKED if region was not locked.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_FILE_LOCK_VIOLATION if lock type can't be changed, lock remains its type.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_FILE_LOCK_LOST if lock was lost, we haven't this lock anymore :(
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fLock Lock method and flags, see RTFILE_LOCK_* defines.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param offLock Offset of lock start.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbLock Length of region to lock, may overlap the end of file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileChangeLock(RTFILE File, unsigned fLock, int64_t offLock, uint64_t cbLock);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Unlocks previously locked region of file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The region to unlock must correspond exactly to an existing locked region.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns VERR_FILE_NOT_LOCKED if region was not locked.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param offLock Offset of lock start.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbLock Length of region to unlock, may overlap the end of file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileUnlock(RTFILE File, int64_t offLock, uint64_t cbLock);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Query information about an open file.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @returns iprt status code.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param File Handle to the file.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param pObjInfo Object information structure to be filled on successful return.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param enmAdditionalAttribs Which set of additional attributes to request.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * Use RTFSOBJATTRADD_NOTHING if this doesn't matter.
450396635f70344c58b6b1e4db38cf17ff34445cJohn ForteRTR3DECL(int) RTFileQueryInfo(RTFILE File, PRTFSOBJINFO pObjInfo, RTFSOBJATTRADD enmAdditionalAttribs);
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * Changes one or more of the timestamps associated of file system object.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @returns iprt status code.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @returns VERR_NOT_SUPPORTED is returned if the operation isn't supported by the OS.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param File Handle to the file.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param pAccessTime Pointer to the new access time. NULL if not to be changed.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param pModificationTime Pointer to the new modifcation time. NULL if not to be changed.
450396635f70344c58b6b1e4db38cf17ff34445cJohn Forte * @param pChangeTime Pointer to the new change time. NULL if not to be changed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pBirthTime Pointer to the new time of birth. NULL if not to be changed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark The file system might not implement all these time attributes,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * the API will ignore the ones which aren't supported.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark The file system might not implement the time resolution
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * employed by this interface, the time will be chopped to fit.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark The file system may update the change time even if it's
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * not specified.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark POSIX can only set Access & Modification and will always set both.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSetTimes(RTFILE File, PCRTTIMESPEC pAccessTime, PCRTTIMESPEC pModificationTime,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto PCRTTIMESPEC pChangeTime, PCRTTIMESPEC pBirthTime);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Gets one or more of the timestamps associated of file system object.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pAccessTime Where to store the access time. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pModificationTime Where to store the modifcation time. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pChangeTime Where to store the change time. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pBirthTime Where to store the time of birth. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileSetTimes().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileGetTimes(RTFILE File, PRTTIMESPEC pAccessTime, PRTTIMESPEC pModificationTime,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Changes the mode flags of an open file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The API requires at least one of the mode flag sets (Unix/Dos) to
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * be set. The type is ignored.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fMode The new file mode, see @ref grp_rt_fs for details.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSetMode(RTFILE File, RTFMODE fMode);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Gets the mode flags of an open file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pfMode Where to store the file mode, see @ref grp_rt_fs for details.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This is wrapper around RTFileQueryInfo()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and exists to complement RTFileSetMode().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileGetMode(RTFILE File, uint32_t *pfMode);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Changes the owner and/or group of an open file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param uid The new file owner user id. Use -1 (or ~0) to leave this unchanged.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param gid The new group id. Use -1 (or ~0) to leave this unchanged.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileSetOwner(RTFILE File, uint32_t uid, uint32_t gid);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Gets the owner and/or group of an open file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pUid Where to store the owner user id. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pGid Where to store the group id. NULL is ok.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remark This is wrapper around RTFileQueryInfo() and exists to complement RTFileGetOwner().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileGetOwner(RTFILE File, uint32_t *pUid, uint32_t *pGid);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Executes an IOCTL on a file descriptor.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * This function is currently only available in L4 and posix environments.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Attemps at calling it from code shared with any other platforms will break things!
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The rational for defining this API is to simplify L4 porting of audio drivers,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * and to remove some of the assumptions on RTFILE being a file descriptor on
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * platforms using the posix file implementation.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns iprt status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File Handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param iRequest IOCTL request to carry out.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvData IOCTL data.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbData Size of the IOCTL data.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param piRet Return value of the IOCTL request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTR3DECL(int) RTFileIoCtl(RTFILE File, int iRequest, void *pvData, unsigned cbData, int *piRet);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Reads the file into memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The caller must free the memory using RTFileReadAllFree().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszFilename The name of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param ppvFile Where to store the pointer to the memory on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbFile Where to store the size of the file on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remarks Note that this function may be implemented using memory mapping, which means
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * that the file may remain open until RTFileReadAllFree() is called. It also
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * means that the return memory may reflect the state of the file when it's
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * accessed instead of when this call was done. So, in short, don't use this
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * API for volatile files, then rather use the extended variant with a
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * yet-to-be-defined.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileReadAll(const char *pszFilename, void **ppvFile, size_t *pcbFile);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Reads the file into memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The caller must free the memory using RTFileReadAllFree().
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pszFilename The name of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param off The offset to start reading at.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * to read to the end of the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param fFlags Flags for the future, must be 0.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param ppvFile Where to store the pointer to the memory on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbFile Where to store the size of the file on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remarks See the remarks for RTFileReadAll.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileReadAllEx(const char *pszFilename, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Reads the file into memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The caller must free the memory using RTFileReadAllFree().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param ppvFile Where to store the pointer to the memory on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbFile Where to store the size of the file on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remarks See the remarks for RTFileReadAll.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileReadAllByHandle(RTFILE File, void **ppvFile, size_t *pcbFile);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Reads the file into memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * The caller must free the memory using RTFileReadAllFree().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The handle to the file.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param off The offset to start reading at.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbMax The maximum number of bytes to read into memory. Specify RTFOFF_MAX
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * to read to the end of the file.
f4e76ddf09a338dc23da0904866290ac36274a5bNattuvetty Bhavyan * @param fFlags Flags for the future, must be 0.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param ppvFile Where to store the pointer to the memory on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbFile Where to store the size of the file on successful return.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @remarks See the remarks for RTFileReadAll.
716c180559045549271833327182dc6a266134f1Nattuvetty BhavyanRTDECL(int) RTFileReadAllByHandleEx(RTFILE File, RTFOFF off, RTFOFF cbMax, uint32_t fFlags, void **ppvFile, size_t *pcbFile);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Frees the memory returned by one of the RTFileReadAll(), RTFileReadAllEx(),
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * RTFileReadAllByHandle() and RTFileReadAllByHandleEx() functions.
716c180559045549271833327182dc6a266134f1Nattuvetty Bhavyan * @param pvFile Pointer to the memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbFile The size of the memory.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(void) RTFileReadAllFree(void *pvFile, size_t cbFile);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto/** @page pg_rt_asyncio RT File async I/O API
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @todo Write something
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Create a async I/O request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param phRequest Where to store the request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqCreate(PRTFILEAIOREQ phRequest);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Destroy a async I/O request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns nothing
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(void) RTFileAioReqDestroy(RTFILEAIOREQ hRequest);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Prepare a read task for a async request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The file to read from.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param off The offset to start reading at.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvBuf Where to store the read bits.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbRead Number of bytes to read.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvUser Opaque user data associated with this request which
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * can be retrieved with RTFileAsyncRequestGetUser()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqPrepareRead(RTFILEAIOREQ hRequest, RTFILE File,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Prepare a write task for a async request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The file to write to.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param off The offset to start writing at.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvBuf Where to store the written bits.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cbRead Number of bytes to write.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvUser Opaque user data associated with this request which
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * can be retrieved with RTFileAsyncRequestGetUser()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqPrepareWrite(RTFILEAIOREQ hRequest, RTFILE File,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Prepare a async flush of all cached data associated with a file handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param File The file to flush.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pvUser Opaque user data associated with this request which
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * can be retrieved with RTFileAsyncRequestGetUser()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqPrepareFlush(RTFILEAIOREQ Request, RTFILE File, void *pvUser);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Get the opaque user data associated with the given request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns Opaque user data.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval NULL if there is no user data associated with the given request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(void *) RTFileAioReqGetUser(RTFILEAIOREQ hRequest);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Cancels a pending request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VINF_SUCCESS If the request was canceled.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_FILE_AIO_IN_PROGRESS If the request could not be canceled because it is already processed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_FILE_AIO_COMPLETED If the request could not be canceled because it already completed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request to cancel.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqCancel(RTFILEAIOREQ hRequest);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Get the status of a completed request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns The IPRT status code of the given request.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hRequest The request handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcbTransferred Where to store the number of bytes transfered.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioReqGetRC(RTFILEAIOREQ hRequest, size_t *pcbTransfered);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Create an async I/O context.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param phAioContext Where to store the aio context handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cAioReqsMax How many async I/O requests the context should be capable
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * to handle. -1 means that the context should support an
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * unlimited number of requests.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxCreate(RTFILEAIOCTX phAioContext, int cAioReqsMax);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Destroy an async I/O context.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hAioContext The aio context handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxDestroy(RTFILEAIOCTX hAioContext);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Get the maximum number of requests one aio context can handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns Maximum number of tasks the context can handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * -1 if there is no limit.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hAioContext The aio context handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * If NIL_RTAIOCONTEXT is passed the maximum value
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * which can be passed to RTFileAsyncIoContextCreate()
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * is returned.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxGetMaxReqCount(RTFILEAIOCTX hAioContext);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Submit an array of requests to an aio context for processing.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hAioContext The context handle.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param aRequests Array of requests to submit.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cRequests Number of requests in the array.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxSubmit(RTFILEAIOCTX hAioContext, RTFILEAIOREQ aRequests[], unsigned cRequests);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Wait for request completion.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_NUMBER_TOO_BIG If cMinRequests or cMaxRequests exceeds limit.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_TIMEOUT If the timeout value expired before at least cMinRequests requests finished.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_INTERRUPTED If the completion context was interrupted with RTFileAsyncIoContextWakeup().
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @retval VERR_FILE_AIO_NO_REQUEST If there is no pending request to wait for completion.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hAioContext The aio context handle to get completed requests from.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cMinRequests The minimum number of requests which have to complete until this function returns.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param apRequestsCompleted Where to store the completed tasks.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cMaxRequests The maximum number of requests the array can hold.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param pcRequestsCompleted Where to store the number of requests completed.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param cMillisTimeout Maximum number of millisceonds to wait before returning.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Use RT_INDEFINITE_WAIT to wait forever.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxWaitForCompletion(RTFILEAIOCTX hAioContext, int cMinRequests,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto RTFILEAIOREQ apRequestsCompleted[], int cMaxRequests,
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto int *pcRequestsCompleted, unsigned cMillisTimeout);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * Let's return RTFileAsyncIoContextWaitForCompletion() immediateley.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @returns IPRT status code.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto * @param hAioContext The context handle to wakeup.
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szetoRTDECL(int) RTFileAioCtxWakeup(RTFILEAIOCTX hAioContext);
8fe960854f0d52e2e8a80ba68e8621a5ac6a866dtim szeto#endif /* IN_RING3 */