Main goals and usage hints. More...

#include "sal/config.h"
#include "osl/time.h"
#include "rtl/ustring.h"
#include "sal/saldllapi.h"

Classes
struct	_oslFileStatus
	Structure containing information about files and directories. More...

struct	_oslVolumeInfo
	Structure containing information about volumes. More...

Macros
#define	osl_File_Attribute_ReadOnly 0x00000001

#define	osl_File_Attribute_Hidden 0x00000002

#define	osl_File_Attribute_Executable 0x00000010

#define	osl_File_Attribute_GrpWrite 0x00000020

#define	osl_File_Attribute_GrpRead 0x00000040

#define	osl_File_Attribute_GrpExe 0x00000080

#define	osl_File_Attribute_OwnWrite 0x00000100

#define	osl_File_Attribute_OwnRead 0x00000200

#define	osl_File_Attribute_OwnExe 0x00000400

#define	osl_File_Attribute_OthWrite 0x00000800

#define	osl_File_Attribute_OthRead 0x00001000

#define	osl_File_Attribute_OthExe 0x00002000

#define	osl_FileStatus_Mask_Type 0x00000001

#define	osl_FileStatus_Mask_Attributes 0x00000002

#define	osl_FileStatus_Mask_CreationTime 0x00000010

#define	osl_FileStatus_Mask_AccessTime 0x00000020

#define	osl_FileStatus_Mask_ModifyTime 0x00000040

#define	osl_FileStatus_Mask_FileSize 0x00000080

#define	osl_FileStatus_Mask_FileName 0x00000100

#define	osl_FileStatus_Mask_FileURL 0x00000200

#define	osl_FileStatus_Mask_LinkTargetURL 0x00000400

#define	osl_FileStatus_Mask_All 0x7FFFFFFF

#define	osl_FileStatus_Mask_Validate 0x80000000

#define	osl_Volume_Attribute_Removeable 0x00000001

#define	osl_Volume_Attribute_Remote 0x00000002

#define	osl_Volume_Attribute_CompactDisc 0x00000004

#define	osl_Volume_Attribute_FixedDisk 0x00000008

#define	osl_Volume_Attribute_RAMDisk 0x00000010

#define	osl_Volume_Attribute_FloppyDisk 0x00000020

#define	osl_Volume_Attribute_Case_Is_Preserved 0x00000040

#define	osl_Volume_Attribute_Case_Sensitive 0x00000080

#define	osl_VolumeInfo_Mask_Attributes 0x00000001

#define	osl_VolumeInfo_Mask_TotalSpace 0x00000002

#define	osl_VolumeInfo_Mask_UsedSpace 0x00000004

#define	osl_VolumeInfo_Mask_FreeSpace 0x00000008

#define	osl_VolumeInfo_Mask_MaxNameLength 0x00000010

#define	osl_VolumeInfo_Mask_MaxPathLength 0x00000020

#define	osl_VolumeInfo_Mask_FileSystemName 0x00000040

#define	osl_VolumeInfo_Mask_DeviceHandle 0x00000080

#define	osl_VolumeInfo_Mask_FileSystemCaseHandling 0x00000100

#define	osl_File_OpenFlag_Read 0x00000001

#define	osl_File_OpenFlag_Write 0x00000002

#define	osl_File_OpenFlag_Create 0x00000004

#define	osl_File_OpenFlag_NoLock 0x00000008

#define	osl_Pos_Absolut 1

#define	osl_Pos_Current 2

#define	osl_Pos_End 3

#define	osl_File_MapFlag_RandomAccess ((sal_uInt32)(0x1))
	Indicate that the file can be accessed randomly (i.e. More...

#define	osl_File_MapFlag_WillNeed ((sal_uInt32)(0x2))
	Map flag denoting that the mapped address space will be accessed by the process soon (and it is advantageous for the operating system to already start paging in the data). More...

Typedefs
typedef void *	oslDirectory

typedef void *	oslDirectoryItem

typedef struct _oslFileStatus	oslFileStatus
	Structure containing information about files and directories. More...

typedef void *	oslVolumeDeviceHandle

typedef struct _oslVolumeInfo	oslVolumeInfo
	Structure containing information about volumes. More...

typedef void *	oslFileHandle

typedef void(*	oslDirectoryCreationCallbackFunc) (void pData, rtl_uString aDirectoryUrl)
	Function pointer representing a function that will be called by osl_createDirectoryPath if a directory has been created. More...

typedef sal_uInt32(*	oslCalcTextWidthFunc) (rtl_uString *ustrText)
	Function pointer representing the function called back from osl_abbreviateSystemPath. More...

Enumerations
enum	oslFileError { osl_File_E_None , osl_File_E_PERM , osl_File_E_NOENT , osl_File_E_SRCH , osl_File_E_INTR , osl_File_E_IO , osl_File_E_NXIO , osl_File_E_2BIG , osl_File_E_NOEXEC , osl_File_E_BADF , osl_File_E_CHILD , osl_File_E_AGAIN , osl_File_E_NOMEM , osl_File_E_ACCES , osl_File_E_FAULT , osl_File_E_BUSY , osl_File_E_EXIST , osl_File_E_XDEV , osl_File_E_NODEV , osl_File_E_NOTDIR , osl_File_E_ISDIR , osl_File_E_INVAL , osl_File_E_NFILE , osl_File_E_MFILE , osl_File_E_NOTTY , osl_File_E_FBIG , osl_File_E_NOSPC , osl_File_E_SPIPE , osl_File_E_ROFS , osl_File_E_MLINK , osl_File_E_PIPE , osl_File_E_DOM , osl_File_E_RANGE , osl_File_E_DEADLK , osl_File_E_NAMETOOLONG , osl_File_E_NOLCK , osl_File_E_NOSYS , osl_File_E_NOTEMPTY , osl_File_E_LOOP , osl_File_E_ILSEQ , osl_File_E_NOLINK , osl_File_E_MULTIHOP , osl_File_E_USERS , osl_File_E_OVERFLOW , osl_File_E_NOTREADY , osl_File_E_invalidError , osl_File_E_TIMEDOUT , osl_File_E_NETWORK , osl_File_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM }

enum	oslFileType { osl_File_Type_Directory , osl_File_Type_Volume , osl_File_Type_Regular , osl_File_Type_Fifo , osl_File_Type_Socket , osl_File_Type_Link , osl_File_Type_Special , osl_File_Type_Unknown }

Functions
SAL_DLLPUBLIC oslFileError	osl_openDirectory (rtl_uString pustrDirectoryURL, oslDirectory pDirectory)
	Open a directory for enumerating its contents. More...

SAL_DLLPUBLIC oslFileError	osl_getNextDirectoryItem (oslDirectory Directory, oslDirectoryItem *pItem, sal_uInt32 uHint)
	Retrieve the next item of a previously opened directory. More...

SAL_DLLPUBLIC oslFileError	osl_closeDirectory (oslDirectory Directory)
	Release a directory handle. More...

SAL_DLLPUBLIC oslFileError	osl_getDirectoryItem (rtl_uString pustrFileURL, oslDirectoryItem pItem)
	Retrieve a single directory item. More...

SAL_DLLPUBLIC oslFileError	osl_acquireDirectoryItem (oslDirectoryItem Item)
	Increase the refcount of a directory item handle. More...

SAL_DLLPUBLIC oslFileError	osl_releaseDirectoryItem (oslDirectoryItem Item)
	Decrease the refcount of a directory item handle. More...

SAL_DLLPUBLIC sal_Bool	osl_identicalDirectoryItem (oslDirectoryItem pItemA, oslDirectoryItem pItemB)
	Determine if two directory items point the same underlying file. More...

SAL_DLLPUBLIC oslFileError	osl_getFileStatus (oslDirectoryItem Item, oslFileStatus *pStatus, sal_uInt32 uFieldMask)
	Retrieve information about a single file or directory. More...

SAL_DLLPUBLIC oslFileError	osl_releaseVolumeDeviceHandle (oslVolumeDeviceHandle Handle)
	Release a volume device handle. More...

SAL_DLLPUBLIC oslFileError	osl_acquireVolumeDeviceHandle (oslVolumeDeviceHandle Handle)
	Acquire a volume device handle. More...

SAL_DLLPUBLIC oslFileError	osl_getVolumeDeviceMountPath (oslVolumeDeviceHandle Handle, rtl_uString **ppustrDirectoryURL)
	Get the full qualified URL where a device is mounted to. More...

SAL_DLLPUBLIC oslFileError	osl_getVolumeInformation (rtl_uString pustrDirectoryURL, oslVolumeInfo pInfo, sal_uInt32 uFieldMask)
	Retrieve information about a volume. More...

SAL_DLLPUBLIC oslFileError	osl_openFile (rtl_uString pustrFileURL, oslFileHandle pHandle, sal_uInt32 uFlags)
	Open a regular file. More...

SAL_WARN_UNUSED_RESULT SAL_DLLPUBLIC oslFileError	osl_setFilePos (oslFileHandle Handle, sal_uInt32 uHow, sal_Int64 uPos)
	Set the internal position pointer of an open file. More...

SAL_DLLPUBLIC oslFileError	osl_getFilePos (oslFileHandle Handle, sal_uInt64 *pPos)
	Retrieve the current position of the internal pointer of an open file. More...

SAL_DLLPUBLIC oslFileError	osl_setFileSize (oslFileHandle Handle, sal_uInt64 uSize)
	Set the file size of an open file. More...

SAL_DLLPUBLIC oslFileError	osl_getFileSize (oslFileHandle Handle, sal_uInt64 *pSize)
	Get the file size of an open file. More...

SAL_DLLPUBLIC oslFileError	osl_mapFile (oslFileHandle Handle, void **ppAddr, sal_uInt64 uLength, sal_uInt64 uOffset, sal_uInt32 uFlags)
	Map a shared file into memory. More...

SAL_DLLPUBLIC oslFileError	osl_unmapFile (void *pAddr, sal_uInt64 uLength)
	Unmap a shared file from memory. More...

SAL_DLLPUBLIC oslFileError	osl_unmapMappedFile (oslFileHandle Handle, void *pAddr, sal_uInt64 uLength)
	Unmap a file segment from memory. More...

SAL_DLLPUBLIC oslFileError	osl_readFile (oslFileHandle Handle, void pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 pBytesRead)
	Read a number of bytes from a file. More...

SAL_DLLPUBLIC oslFileError	osl_isEndOfFile (oslFileHandle Handle, sal_Bool *pIsEOF)
	Test if the end of a file is reached. More...

SAL_DLLPUBLIC oslFileError	osl_writeFile (oslFileHandle Handle, const void pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 pBytesWritten)
	Write a number of bytes to a file. More...

SAL_DLLPUBLIC oslFileError	osl_readFileAt (oslFileHandle Handle, sal_uInt64 uOffset, void pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 pBytesRead)
	Read a number of bytes from a specified offset in a file. More...

SAL_DLLPUBLIC oslFileError	osl_writeFileAt (oslFileHandle Handle, sal_uInt64 uOffset, const void pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 pBytesWritten)
	Write a number of bytes to a specified offset in a file. More...

SAL_DLLPUBLIC oslFileError	osl_readLine (oslFileHandle Handle, sal_Sequence **ppSequence)
	Read a line from a file. More...

SAL_DLLPUBLIC oslFileError	osl_syncFile (oslFileHandle Handle)
	Synchronize the memory representation of a file with that on the physical medium. More...

SAL_DLLPUBLIC oslFileError	osl_closeFile (oslFileHandle Handle)
	Close an open file. More...

SAL_DLLPUBLIC oslFileError	osl_createDirectory (rtl_uString *pustrDirectoryURL)
	Create a directory. More...

SAL_DLLPUBLIC oslFileError	osl_createDirectoryWithFlags (rtl_uString *url, sal_uInt32 flags)
	Create a directory, passing flags. More...

SAL_DLLPUBLIC oslFileError	osl_removeDirectory (rtl_uString *pustrDirectoryURL)
	Remove an empty directory. More...

SAL_DLLPUBLIC oslFileError	osl_createDirectoryPath (rtl_uString aDirectoryUrl, oslDirectoryCreationCallbackFunc aDirectoryCreationCallbackFunc, void pData)
	Create a directory path. More...

SAL_DLLPUBLIC oslFileError	osl_removeFile (rtl_uString *pustrFileURL)
	Remove a regular file. More...

SAL_DLLPUBLIC oslFileError	osl_copyFile (rtl_uString pustrSourceFileURL, rtl_uString pustrDestFileURL)
	Copy a file to a new destination. More...

SAL_DLLPUBLIC oslFileError	osl_moveFile (rtl_uString pustrSourceFileURL, rtl_uString pustrDestFileURL)
	Move a file or directory to a new destination or renames it. More...

SAL_DLLPUBLIC oslFileError	osl_getCanonicalName (rtl_uString pustrRequestedURL, rtl_uString *ppustrValidURL)
	Determine a valid unused canonical name for a requested name. More...

SAL_DLLPUBLIC oslFileError	osl_getAbsoluteFileURL (rtl_uString pustrBaseDirectoryURL, rtl_uString pustrRelativeFileURL, rtl_uString **ppustrAbsoluteFileURL)
	Convert a path relative to a given directory into an full qualified file URL. More...

SAL_DLLPUBLIC oslFileError	osl_getFileURLFromSystemPath (rtl_uString pustrSystemPath, rtl_uString *ppustrFileURL)
	Convert a system dependent path into a file URL. More...

SAL_DLLPUBLIC oslFileError	osl_searchFileURL (rtl_uString pustrFileName, rtl_uString pustrSearchPath, rtl_uString **ppustrFileURL)
	Search a full qualified system path or a file URL. More...

SAL_DLLPUBLIC oslFileError	osl_getSystemPathFromFileURL (rtl_uString pustrFileURL, rtl_uString *ppustrSystemPath)
	Convert a file URL into a system dependent path. More...

SAL_DLLPUBLIC oslFileError	osl_abbreviateSystemPath (rtl_uString ustrSystemPath, rtl_uString *pustrCompacted, sal_uInt32 uMaxWidth, oslCalcTextWidthFunc pCalcWidth)
	Abbreviate a system notation path. More...

SAL_DLLPUBLIC oslFileError	osl_setFileAttributes (rtl_uString *pustrFileURL, sal_uInt64 uAttributes)
	Set file attributes. More...

SAL_DLLPUBLIC oslFileError	osl_setFileTime (rtl_uString pustrFileURL, const TimeValue aCreationTime, const TimeValue aLastAccessTime, const TimeValue aLastWriteTime)
	Set the file time. More...

SAL_DLLPUBLIC oslFileError	osl_getTempDirURL (rtl_uString **pustrTempDirURL)
	Retrieves the file URL of the system's temporary directory path. More...

SAL_DLLPUBLIC oslFileError	osl_createTempFile (rtl_uString pustrDirectoryURL, oslFileHandle pHandle, rtl_uString **ppustrTempFileURL)
	Creates a temporary file in the directory provided by the caller or the directory returned by osl_getTempDirURL. More...

SAL_DLLPUBLIC oslFileError	osl_replaceFile (rtl_uString pustrSourceFileURL, rtl_uString pustrDestFileURL)
	Move a file to a new destination or rename it, taking old file's identity (if exists). More...

Detailed Description

Main goals and usage hints.

The main intention of this interface is to provide a universal portable and high performance access to file system functionality on any operating system.

There are a few main goals:

The path specifications always has to be absolute. Any usage of relative path specifications is forbidden. Exceptions are osl_getSystemPathFromFileURL, osl_getFileURLFromSystemPath and osl_getAbsoluteFileURL. Most operating systems provide a "Current Directory" per process. This is the reason why relative path specifications can cause problems in multithreading environments.
Proprietary notations of file paths are not supported. Every path notation must the file URL specification. File URLs must be encoded in UTF8 and after that escaped. Although the URL parameter is a unicode string, the must contain only ASCII characters.
The caller cannot get any information whether a file system is case sensitive, case preserving or not. The operating system implementation itself should determine if it can map case-insensitive paths. The case correct notation of a filename or file path is part of the "File Info". This case correct name can be used as a unique key if necessary.
Obtaining information about files or volumes is controlled by a bitmask which specifies which fields are of interest. Due to performance reasons it is not recommended to obtain information which is not needed. But if the operating system provides more information anyway the implementation can set more fields on output as were requested. It is in the responsibility of the caller to decide if they use this additional information or not. But they should do so to prevent further unnecessary calls if the information is already there.

The input bitmask supports a flag osl_FileStatus_Mask_Validate which can be used to force retrieving uncached validated information. Setting this flag when calling osl_getFileStatus in combination with no other flag is a synonym for a "FileExists". This should only be done when processing a single file (i.e. before opening) and NEVER during enumeration of directory contents on any step of information processing. This would change the runtime behaviour from O(n) to O(n*n/2) on nearly every file system. On Windows NT reading the contents of a directory with 7000 entries and getting full information about every file only takes 0.6 seconds. Specifying the flag osl_FileStatus_Mask_Validate for each entry will increase the time to 180 seconds (!!!).

Macro Definition Documentation

◆ osl_File_MapFlag_RandomAccess

#define osl_File_MapFlag_RandomAccess ((sal_uInt32)(0x1))

Indicate that the file can be accessed randomly (i.e.

there is no sequential reading). Basically it means that the first byte of every page in the file-mapping will be read.

Since: UDK 3.2.10

◆ osl_File_MapFlag_WillNeed

#define osl_File_MapFlag_WillNeed ((sal_uInt32)(0x2))

Map flag denoting that the mapped address space will be accessed by the process soon (and it is advantageous for the operating system to already start paging in the data).

Attention: As this assumes that madvise() with the WILLREAD flag is asynchronous (which is I'm afraid an incorrect assumption), Linux systems will ignore this flag.

Since: UDK 3.2.12

◆ osl_File_OpenFlag_Create

#define osl_File_OpenFlag_Create 0x00000004

◆ osl_File_OpenFlag_NoLock

#define osl_File_OpenFlag_NoLock 0x00000008

◆ osl_File_OpenFlag_Read

#define osl_File_OpenFlag_Read 0x00000001

◆ osl_File_OpenFlag_Write

#define osl_File_OpenFlag_Write 0x00000002

◆ osl_Pos_Absolut

#define osl_Pos_Absolut 1

◆ osl_Pos_Current

#define osl_Pos_Current 2

◆ osl_Pos_End

#define osl_Pos_End 3

Typedef Documentation

◆ oslCalcTextWidthFunc

typedef sal_uInt32( * oslCalcTextWidthFunc) (rtl_uString *ustrText)

Function pointer representing the function called back from osl_abbreviateSystemPath.

Parameters

[in] ustrText Text to calculate the width for

Returns: The width of the text specified by ustrText, e.g. it can return the width in pixel or the width in character count.

See also: osl_abbreviateSystemPath()

◆ oslDirectory

typedef void* oslDirectory

◆ oslDirectoryCreationCallbackFunc

typedef void( * oslDirectoryCreationCallbackFunc) (void *pData, rtl_uString *aDirectoryUrl)

Function pointer representing a function that will be called by osl_createDirectoryPath if a directory has been created.

To avoid unpredictable results the callee must not access the directory whose creation is just notified.

Parameters

pData	[in] User specified data given in osl_createDirectoryPath.
aDirectoryUrl	[in] The absolute file URL of the directory that was just created by osl_createDirectoryPath.

See also: osl_createDirectoryPath

◆ oslDirectoryItem

typedef void* oslDirectoryItem

◆ oslFileHandle

typedef void* oslFileHandle

◆ oslFileStatus

typedef struct _oslFileStatus oslFileStatus

Structure containing information about files and directories.

See also: osl_getFileStatus(); oslFileType

◆ oslVolumeDeviceHandle

typedef void* oslVolumeDeviceHandle

◆ oslVolumeInfo

typedef struct _oslVolumeInfo oslVolumeInfo

Structure containing information about volumes.

See also: osl_getVolumeInformation(); oslFileType

Enumeration Type Documentation

◆ oslFileError

enum oslFileError

Enumerator
osl_File_E_None	on success
osl_File_E_PERM	operation not permitted
osl_File_E_NOENT	no such file or directory
osl_File_E_SRCH	no process matches the PID
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	I/O error occurred
osl_File_E_NXIO	no such device or address
osl_File_E_2BIG	argument list too long
osl_File_E_NOEXEC	invalid executable file format
osl_File_E_BADF	bad file descriptor
osl_File_E_CHILD	there are no child processes
osl_File_E_AGAIN	resource temp unavailable, try again later
osl_File_E_NOMEM	no memory available
osl_File_E_ACCES	file permissions do not allow operation
osl_File_E_FAULT	bad address; an invalid pointer detected
osl_File_E_BUSY	resource busy
osl_File_E_EXIST	file exists where should only be created
osl_File_E_XDEV	improper link across file systems detected
osl_File_E_NODEV	wrong device type specified
osl_File_E_NOTDIR	file isn't a directory where one is needed
osl_File_E_ISDIR	file is a directory, invalid operation
osl_File_E_INVAL	invalid argument to library function
osl_File_E_NFILE	too many distinct file openings
osl_File_E_MFILE	process has too many distinct files open
osl_File_E_NOTTY	inappropriate I/O control operation
osl_File_E_FBIG	file too large
osl_File_E_NOSPC	no space left on device, write failed
osl_File_E_SPIPE	invalid seek operation (such as on pipe)
osl_File_E_ROFS	illegal modification to read-only filesystem
osl_File_E_MLINK	too many links to file
osl_File_E_PIPE	broken pipe; no process reading from other end of pipe
osl_File_E_DOM	domain error (mathematical error)
osl_File_E_RANGE	range error (mathematical error)
osl_File_E_DEADLK	deadlock avoided
osl_File_E_NAMETOOLONG	filename too long
osl_File_E_NOLCK	no locks available
osl_File_E_NOSYS	function not implemented
osl_File_E_NOTEMPTY	directory not empty
osl_File_E_LOOP	too many levels of symbolic links found during name lookup
osl_File_E_ILSEQ	invalid or incomplete byte sequence of multibyte char found
osl_File_E_NOLINK	link has been severed
osl_File_E_MULTIHOP	remote resource is not directly available
osl_File_E_USERS	file quote system is confused as there are too many users
osl_File_E_OVERFLOW	value too large for defined data type
osl_File_E_NOTREADY	device not ready
osl_File_E_invalidError	unmapped error: always last entry in enum!
osl_File_E_TIMEDOUT	socket operation timed out
osl_File_E_NETWORK	unexpected network error occurred (Windows) - could be a user session was deleted, or an unexpected network error occurred
osl_File_E_FORCE_EQUAL_SIZE

Function Documentation

◆ osl_abbreviateSystemPath()

SAL_DLLPUBLIC oslFileError osl_abbreviateSystemPath	(	rtl_uString *	ustrSystemPath,
		rtl_uString **	pustrCompacted,
		sal_uInt32	uMaxWidth,
		oslCalcTextWidthFunc	pCalcWidth
	)

Abbreviate a system notation path.

Parameters

[in]	ustrSystemPath	The full system path to abbreviate
[out]	pustrCompacted	Receives the compacted system path on output
[in]	pCalcWidth	Function ptr that calculates the width of a string. Can be zero.
[in]	uMaxWidth	Maximum width allowed that is returned from pCalcWidth. If pCalcWidth is zero the character count is assumed as width.

Return values

osl_File_E_None on success

See also: oslCalcTextWidthFunc

◆ osl_acquireDirectoryItem()

SAL_DLLPUBLIC oslFileError osl_acquireDirectoryItem ( oslDirectoryItem Item )

Increase the refcount of a directory item handle.

The caller responsible for releasing the directory item handle using osl_releaseDirectoryItem().

Parameters

[in] Item A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getDirectoryItem(); osl_getNextDirectoryItem(); osl_releaseDirectoryItem()

◆ osl_acquireVolumeDeviceHandle()

SAL_DLLPUBLIC oslFileError osl_acquireVolumeDeviceHandle ( oslVolumeDeviceHandle Handle )

Acquire a volume device handle.

Acquires the given oslVolumeDeviceHandle which was acquired by a call to osl_getVolumeInformation(). The caller is responsible for releasing the acquired handle by calling osl_releaseVolumeDeviceHandle().

Parameters

[in] Handle An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().

Return values

osl_File_E_None on success

Todo:: specify all error codes that may be returned

See also: osl_getVolumeInformation()

◆ osl_closeDirectory()

SAL_DLLPUBLIC oslFileError osl_closeDirectory ( oslDirectory Directory )

Release a directory handle.

Parameters

[in] Directory A handle received by a call to osl_openDirectory().

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_BADF	invalid oslDirectory parameter
osl_File_E_INTR	the function call was interrupted

See also: osl_openDirectory()

◆ osl_closeFile()

SAL_DLLPUBLIC oslFileError osl_closeFile ( oslFileHandle Handle )

Close an open file.

Parameters

[in] Handle Handle to a file received by a previous call to osl_openFile().

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_BADF	Bad file
osl_File_E_INTR	function call was interrupted
osl_File_E_NOLINK	link has been severed
osl_File_E_NOSPC	no space left on device
osl_File_E_IO	on I/O errors

See also: osl_openFile()

◆ osl_copyFile()

SAL_DLLPUBLIC oslFileError osl_copyFile	(	rtl_uString *	pustrSourceFileURL,
		rtl_uString *	pustrDestFileURL
	)

Copy a file to a new destination.

Copies a file to a new destination. Copies only files not directories. No assumptions should be made about preserving attributes or file time.

Parameters

[in]	pustrSourceFileURL	Full qualified URL of the source file.
[in]	pustrDestFileURL	Full qualified URL of the destination file. A directory is NOT a valid destination file!

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_PERM	operation not permitted
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file or directory
osl_File_E_ISDIR	is a directory
osl_File_E_ROFS	read-only file system
osl_File_E_BUSY	if the implementation internally requires resources that are (temporarily) unavailable (added with LibreOffice 4.4)

See also: osl_moveFile(); osl_removeFile()

◆ osl_createDirectory()

SAL_DLLPUBLIC oslFileError osl_createDirectory ( rtl_uString * pustrDirectoryURL )

Create a directory.

Parameters

[in] pustrDirectoryURL Full qualified URL of the directory to create.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_EXIST	file exists
osl_File_E_ACCES	permission denied
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file or directory
osl_File_E_NOTDIR	not a directory
osl_File_E_ROFS	read-only file system
osl_File_E_NOSPC	no space left on device
osl_File_E_DQUOT	quota exceeded
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_FAULT	bad address
osl_FileE_IO	on I/O errors
osl_File_E_MLINK	too many links
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed

See also: osl_removeDirectory()

◆ osl_createDirectoryPath()

SAL_DLLPUBLIC oslFileError osl_createDirectoryPath	(	rtl_uString *	aDirectoryUrl,
		oslDirectoryCreationCallbackFunc	aDirectoryCreationCallbackFunc,
		void *	pData
	)

Create a directory path.

The osl_createDirectoryPath function creates a specified directory path. All nonexisting sub directories will be created.

Attention: PLEASE NOTE You cannot rely on getting the error code osl_File_E_EXIST for existing directories. Programming against this error code is in general a strong indication of a wrong usage of osl_createDirectoryPath.

Parameters

aDirectoryUrl	[in] The absolute file URL of the directory path to create. A relative file URL will not be accepted.
aDirectoryCreationCallbackFunc	[in] Pointer to a function that will be called synchronously for each sub directory that was created. The value of this parameter may be NULL, in this case notifications will not be sent.
pData	[in] User specified data to be passed to the directory creation callback function. The value of this parameter may be arbitrary and will not be interpreted by osl_createDirectoryPath.

Return values

osl_File_E_None	On success
osl_File_E_INVAL	The format of the parameters was not valid
osl_File_E_ACCES	Permission denied
osl_File_E_EXIST	The final node of the specified directory path already exist
osl_File_E_NAMETOOLONG	The name of the specified directory path exceeds the maximum allowed length
osl_File_E_NOTDIR	A component of the specified directory path already exist as file in any part of the directory path
osl_File_E_ROFS	Read-only file system
osl_File_E_NOSPC	No space left on device
osl_File_E_DQUOT	Quota exceeded
osl_File_E_FAULT	Bad address
osl_File_E_IO	I/O error
osl_File_E_LOOP	Too many symbolic links encountered
osl_File_E_NOLINK	Link has been severed
osl_File_E_invalidError	An unknown error occurred

See also: oslDirectoryCreationFunc; oslFileError; osl_createDirectory

◆ osl_createDirectoryWithFlags()

SAL_DLLPUBLIC oslFileError osl_createDirectoryWithFlags	(	rtl_uString *	url,
		sal_uInt32	flags
	)

Create a directory, passing flags.

Parameters

url	File URL of the directory to create.
flags	A combination of the same osl_File_OpenFlag_*s used by osl_openFile, except that osl_File_OpenFlag_Create is implied and ignored. Support for the various flags can differ across operating systems.

See also: osl_createDirectory()

Since: LibreOffice 4.3

◆ osl_createTempFile()

SAL_DLLPUBLIC oslFileError osl_createTempFile	(	rtl_uString *	pustrDirectoryURL,
		oslFileHandle *	pHandle,
		rtl_uString **	ppustrTempFileURL
	)

Creates a temporary file in the directory provided by the caller or the directory returned by osl_getTempDirURL.

Creates a temporary file in the directory provided by the caller or the directory returned by osl_getTempDirURL. Under UNIX Operating Systems the file will be created with read and write access for the user exclusively. If the caller requests only a handle to the open file but not the name of it, the file will be automatically removed on close else the caller is responsible for removing the file on success.

Description of the different pHandle, ppustrTempFileURL parameter combinations. pHandle is 0 and ppustrTempDirURL is 0 - this combination is invalid pHandle is not 0 and ppustrTempDirURL is 0 - a handle to the open file will be returned on success and the file will be automatically removed on close. pHandle is 0 and ppustrTempDirURL is not 0 - the name of the file will be returned, the caller is responsible for opening, closing and removing the file. pHandle is not 0 and ppustrTempDirURL is not 0 - a handle to the open file as well as the file name will be returned, the caller is responsible for closing and removing the file.

Parameters

[in]	pustrDirectoryURL	Specifies the full qualified URL where the temporary file should be created. If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used.
[out]	pHandle	On success receives a handle to the open file. If pHandle is 0 the file will be closed on return, in this case ppustrTempFileURL must not be 0.
[out]	ppustrTempFileURL	On success receives the full qualified URL of the temporary file. If ppustrTempFileURL is 0 the file will be automatically removed on close, in this case pHandle must not be 0. If ppustrTempFileURL is not 0 the caller receives the name of the created file and is responsible for removing the file, in this case ppustrTempFileURL must be 0 or must point to a valid rtl_uString.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameter is invalid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	Permission denied
osl_File_E_NOENT	No such file or directory
osl_File_E_NOTDIR	Not a directory
osl_File_E_ROFS	Read-only file system
osl_File_E_NOSPC	No space left on device
osl_File_E_DQUOT	Quota exceeded

See also: osl_getTempDirURL()

◆ osl_getAbsoluteFileURL()

SAL_DLLPUBLIC oslFileError osl_getAbsoluteFileURL	(	rtl_uString *	pustrBaseDirectoryURL,
		rtl_uString *	pustrRelativeFileURL,
		rtl_uString **	ppustrAbsoluteFileURL
	)

Convert a path relative to a given directory into an full qualified file URL.

Convert a path relative to a given directory into an full qualified file URL. The function resolves symbolic links if possible and path ellipses, so on success the resulting absolute path is fully resolved.

Parameters

[in]	pustrBaseDirectoryURL	Base directory URL to which the relative path is related to.
[in]	pustrRelativeFileURL	A URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL or an absolute path. If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored.
[out]	ppustrAbsoluteFileURL	On success it receives the full qualified absolute file URL.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_NOTDIR	not a directory
osl_File_E_ACCES	permission denied
osl_File_E_NOENT	no such file or directory
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_OVERFLOW	value too large for defined data type
osl_File_E_FAULT	bad address
osl_File_E_INTR	function call was interrupted
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed

See also: osl_getFileStatus()

◆ osl_getCanonicalName()

SAL_DLLPUBLIC oslFileError osl_getCanonicalName	(	rtl_uString *	pustrRequestedURL,
		rtl_uString **	ppustrValidURL
	)

Determine a valid unused canonical name for a requested name.

Determines a valid unused canonical name for a requested name. Depending on the Operating System and the File System the illegal characters are replaced by valid ones. If a file or directory with the requested name already exists a new name is generated following the common rules on the actual Operating System and File System.

Parameters

[in]	pustrRequestedURL	Requested name of a file or directory.
[out]	ppustrValidURL	On success receives a name which is unused and valid on the actual Operating System and File System.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getFileStatus()

◆ osl_getDirectoryItem()

SAL_DLLPUBLIC oslFileError osl_getDirectoryItem	(	rtl_uString *	pustrFileURL,
		oslDirectoryItem *	pItem
	)

Retrieve a single directory item.

Retrieves a single directory item. The returned handle has an initial refcount of 1. Due to performance issues it is not recommended to use this function while enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead.

Parameters

[in]	pustrFileURL	An absolute file URL.
[out]	pItem	On success it receives a handle which can be used for subsequent calls to osl_getFileStatus(). The handle has to be released by a call to osl_releaseDirectoryItem().

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_MFILE	too many open files used by the process
osl_File_E_NFILE	too many open files in the system
osl_File_E_NOENT	no such file or directory
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_NAMETOOLONG	the file name is too long
osl_File_E_NOTDIR	a component of the path prefix of path is not a directory
osl_File_E_IO	on I/O errors
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed
osl_File_E_FAULT	bad address
osl_File_E_INTR	the function call was interrupted

See also: osl_releaseDirectoryItem(); osl_acquireDirectoryItem(); osl_getFileStatus(); osl_getNextDirectoryItem()

◆ osl_getFilePos()

SAL_DLLPUBLIC oslFileError osl_getFilePos	(	oslFileHandle	Handle,
		sal_uInt64 *	pPos
	)

Retrieve the current position of the internal pointer of an open file.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[out]	pPos	On success receives the current position of the file pointer.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_OVERFLOW	the resulting file offset would be a value which cannot be represented correctly for regular files

See also: osl_openFile(); osl_setFilePos(); osl_readFile(); osl_writeFile()

◆ osl_getFileSize()

SAL_DLLPUBLIC oslFileError osl_getFileSize	(	oslFileHandle	Handle,
		sal_uInt64 *	pSize
	)

Get the file size of an open file.

Gets the file size of an open file. The position of the file pointer is not affeced by this function.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[out]	pSize	Current size in bytes.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_OVERFLOW	the resulting file offset would be a value which cannot be represented correctly for regular files

See also: osl_openFile(); osl_setFilePos(); osl_getFileStatus()

◆ osl_getFileStatus()

SAL_DLLPUBLIC oslFileError osl_getFileStatus	(	oslDirectoryItem	Item,
		oslFileStatus *	pStatus,
		sal_uInt32	uFieldMask
	)

Retrieve information about a single file or directory.

Parameters

[in]	Item	A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
[in,out]	pStatus	Points to a structure which receives the information of the file or directory represented by the handle Item. The member uStructSize has to be initialized to sizeof(oslFileStatus) before calling this function.
[in]	uFieldMask	Specifies which fields of the structure pointed to by pStatus are of interest to the caller.

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_ACCES	permission denied
osl_File_E_NOENT	no such file or directory
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_BADF	invalid oslDirectoryItem parameter
osl_File_E_FAULT	bad address
osl_File_E_OVERFLOW	value too large for defined data type
osl_File_E_INTR	function call was interrupted
osl_File_E_NOLINK	link has been severed
osl_File_E_MULTIHOP	components of path require hopping to multiple remote machines and the file system does not allow it
osl_File_E_MFILE	too many open files used by the process
osl_File_E_NFILE	too many open files in the system
osl_File_E_NOSPC	no space left on device
osl_File_E_NXIO	no such device or address
osl_File_E_IO	on I/O errors
osl_File_E_NOSYS	function not implemented

See also: osl_getDirectoryItem(); osl_getNextDirectoryItem(); oslFileStatus

◆ osl_getFileURLFromSystemPath()

SAL_DLLPUBLIC oslFileError osl_getFileURLFromSystemPath	(	rtl_uString *	pustrSystemPath,
		rtl_uString **	ppustrFileURL
	)

Convert a system dependent path into a file URL.

Parameters

[in]	pustrSystemPath	A System dependent path of a file or directory.
[out]	ppustrFileURL	On success it receives the file URL.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getSystemPathFromFileURL()

◆ osl_getNextDirectoryItem()

SAL_DLLPUBLIC oslFileError osl_getNextDirectoryItem	(	oslDirectory	Directory,
		oslDirectoryItem *	pItem,
		sal_uInt32	uHint
	)

Retrieve the next item of a previously opened directory.

Retrieves the next item of a previously opened directory. All handles have an initial refcount of 1.

Parameters

[in]	Directory	A directory handle received from a previous call to osl_openDirectory().
[out]	pItem	On success it receives a handle that can be used for subsequent calls to osl_getFileStatus(). The handle has to be released by a call to osl_releaseDirectoryItem().
[in]	uHint	With this parameter the caller can tell the implementation that (s)he is going to call this function uHint times afterwards. This enables the implementation to get the information for more than one file and cache it until the next calls.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_NOENT	no more entries in this directory
osl_File_E_BADF	invalid oslDirectory parameter
osl_File_E_OVERFLOW	the value too large for defined data type

See also: osl_releaseDirectoryItem(); osl_acquireDirectoryItem(); osl_getDirectoryItem(); osl_getFileStatus()

◆ osl_getSystemPathFromFileURL()

SAL_DLLPUBLIC oslFileError osl_getSystemPathFromFileURL	(	rtl_uString *	pustrFileURL,
		rtl_uString **	ppustrSystemPath
	)

Convert a file URL into a system dependent path.

Parameters

[in]	pustrFileURL	A File URL.
[out]	ppustrSystemPath	On success it receives the system path.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getFileURLFromSystemPath()

◆ osl_getTempDirURL()

SAL_DLLPUBLIC oslFileError osl_getTempDirURL ( rtl_uString ** pustrTempDirURL )

Retrieves the file URL of the system's temporary directory path.

Parameters

[out] pustrTempDirURL On success receives the URL of system's temporary directory path.

Return values

osl_File_E_None	on success
osl_File_E_NOENT	no such file or directory not found

◆ osl_getVolumeDeviceMountPath()

SAL_DLLPUBLIC oslFileError osl_getVolumeDeviceMountPath	(	oslVolumeDeviceHandle	Handle,
		rtl_uString **	ppustrDirectoryURL
	)

Get the full qualified URL where a device is mounted to.

Parameters

[in]	Handle	An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
[out]	ppustrDirectoryURL	Receives the full qualified URL where the device is mounted to.

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_ACCES	permission denied
osl_File_E_NXIO	no such device or address
osl_File_E_NODEV	no such device
osl_File_E_NOENT	no such file or directory
osl_File_E_FAULT	bad address
osl_FilE_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed
osl_File_E_EOVERFLOW	value too large for defined data type

See also: osl_getVolumeInformation()

◆ osl_getVolumeInformation()

SAL_DLLPUBLIC oslFileError osl_getVolumeInformation	(	rtl_uString *	pustrDirectoryURL,
		oslVolumeInfo *	pInfo,
		sal_uInt32	uFieldMask
	)

Retrieve information about a volume.

Retrieves information about a volume. A volume can either be a mount point, a network resource or a drive depending on Operating System and File System. Before calling this function osl_getFileStatus() should be called to determine if the type is osl_file_Type_Volume.

Parameters

[in]	pustrDirectoryURL	Full qualified URL of the volume
[out]	pInfo	On success it receives information about the volume.
[in]	uFieldMask	Specifies which members of the structure should be filled

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOTDIR	not a directory
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file or directory
osl_File_E_ACCES	permission denied
osl_File_E_LOOP	too many symbolic links encountered
ols_File_E_FAULT	Bad address
osl_File_E_IO	on I/O errors
osl_File_E_NOSYS	function not implemented
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed
osl_File_E_INTR	function call was interrupted

See also: osl_getFileStatus(); oslVolumeInfo

◆ osl_identicalDirectoryItem()

SAL_DLLPUBLIC sal_Bool osl_identicalDirectoryItem	(	oslDirectoryItem	pItemA,
		oslDirectoryItem	pItemB
	)

Determine if two directory items point the same underlying file.

The comparison is done first by URL, and then by resolving links to find the target, and finally by comparing inodes on unix.

Parameters

[in]	pItemA	A directory handle to compare with another handle
[in]	pItemB	A directory handle to compare with pItemA

Return values

sal_True	if the items point to an identical resource
sal_False	if the items point to a different resource, or a fatal error occurred

See also: osl_getDirectoryItem()

Since: LibreOffice 3.6

◆ osl_isEndOfFile()

SAL_DLLPUBLIC oslFileError osl_isEndOfFile	(	oslFileHandle	Handle,
		sal_Bool *	pIsEOF
	)

Test if the end of a file is reached.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[out]	pIsEOF	Points to a variable that receives the end-of-file status.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_ISDIR	is a directory
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_AGAIN	operation would block
osl_File_E_NOLINK	link has been severed

See also: osl_openFile(); osl_readFile(); osl_readLine(); osl_setFilePos()

◆ osl_mapFile()

SAL_DLLPUBLIC oslFileError osl_mapFile	(	oslFileHandle	Handle,
		void **	ppAddr,
		sal_uInt64	uLength,
		sal_uInt64	uOffset,
		sal_uInt32	uFlags
	)

Map a shared file into memory.

Files can be mapped into memory to allow multiple processes to use this memory-mapped file to share data.

On Android, if the Handle refers to a file that is actually inside the app package (.apk zip archive), no new mapping is created, just a pointer to the file inside the already mapped .apk is returned.

Parameters

[in]	Handle	Handle of the file to be mapped.
[in,out]	ppAddr	Memory address of the mapped file
[in]	uLength	Amount to map of the file from the offset
[in]	uOffset	Offset into the file to map
[in]	uFlags	osl_File_MapFlag_RandomAccess or osl_File_MapFlag_WillNeed

Return values

osl_File_E_None	on success
osl_File_E_INVAL	invalid file handle, on Unix systems also can mean that the address, length of the file or the file offset are too large or not aligned on a page boundary; on Linux can also mean after Linux 2.6.12 that the length was set to 0 (illogical).
osl_File_E_OVERFLOW	requested mapping size too large, or the file offset was too large
osl_File_E_ACCES	file descriptor to non-regular file, or file descriptor not open for reading, or the file descriptor is not open in read/write mode
osl_File_E_AGAIN	file has been locked, or too much memory has been locked
osl_File_E_NODEV	underlying filesystem of specified file does not support memory mapping
osl_File_E_TXTBSY	on Linux means that writing to the mapped file is denied, but the file descriptor points to a file open for writing
osl_File_E_NOMEM	process's maximum number of mappings have been exceeded

Since: UDK 3.2.10

◆ osl_moveFile()

SAL_DLLPUBLIC oslFileError osl_moveFile	(	rtl_uString *	pustrSourceFileURL,
		rtl_uString *	pustrDestFileURL
	)

Move a file or directory to a new destination or renames it.

Moves a file or directory to a new destination or renames it. File time and attributes are preserved.

Parameters

[in]	pustrSourceFileURL	Full qualified URL of the source file.
[in]	pustrDestFileURL	Full qualified URL of the destination file. An existing directory is NOT a valid destination !

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_PERM	operation not permitted
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file or directory
osl_File_E_ROFS	read-only file system
osl_File_E_BUSY	if the implementation internally requires resources that are (temporarily) unavailable (added with LibreOffice 4.4)

See also: osl_copyFile()

◆ osl_openDirectory()

SAL_DLLPUBLIC oslFileError osl_openDirectory	(	rtl_uString *	pustrDirectoryURL,
		oslDirectory *	pDirectory
	)

Open a directory for enumerating its contents.

Parameters

[in]	pustrDirectoryURL	The full qualified URL of the directory.
[out]	pDirectory	On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem(). The handle has to be released by a call to osl_closeDirectory().

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOENT	the specified path doesn't exist
osl_File_E_NOTDIR	the specified path is not a directory
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_MFILE	too many open files used by the process
osl_File_E_NFILE	too many open files in the system
osl_File_E_NAMETOOLONG	File name too long
osl_File_E_LOOP	Too many symbolic links encountered

See also: osl_getNextDirectoryItem(); osl_closeDirectory()

◆ osl_openFile()

SAL_DLLPUBLIC oslFileError osl_openFile	(	rtl_uString *	pustrFileURL,
		oslFileHandle *	pHandle,
		sal_uInt32	uFlags
	)

Open a regular file.

Open a file. Only regular files can be opened.

Parameters

[in]	pustrFileURL	The full qualified URL of the file to open.
[out]	pHandle	On success it receives a handle to the open file.
[in]	uFlags	Specifies the open mode.

On Android, if the file path is below the /assets folder, the file exists only as a hopefully uncompressed element inside the app package (.apk), which has been mapped into memory as a whole by the LibreOffice Android bootstrapping code. So files "opened" from there aren't actually files in the OS sense.

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NAMETOOLONG	pathname was too long
osl_File_E_NOENT	no such file or directory
osl_File_E_ACCES	permission denied
osl_File_E_AGAIN	a write lock could not be established
osl_File_E_NOTDIR	not a directory
osl_File_E_NXIO	no such device or address
osl_File_E_NODEV	no such device
osl_File_E_ROFS	read-only file system
osl_File_E_TXTBSY	text file busy
osl_File_E_FAULT	bad address
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_NOSPC	no space left on device
osl_File_E_ISDIR	is a directory
osl_File_E_MFILE	too many open files used by the process
osl_File_E_NFILE	too many open files in the system
osl_File_E_DQUOT	quota exceeded
osl_File_E_EXIST	file exists
osl_FilE_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed
osl_File_E_EOVERFLOW	value too large for defined data type

See also: osl_closeFile(); osl_setFilePos(); osl_getFilePos(); osl_readFile(); osl_writeFile(); osl_setFileSize(); osl_getFileSize()

◆ osl_readFile()

SAL_DLLPUBLIC oslFileError osl_readFile	(	oslFileHandle	Handle,
		void *	pBuffer,
		sal_uInt64	uBytesRequested,
		sal_uInt64 *	pBytesRead
	)

Read a number of bytes from a file.

Reads a number of bytes from a file. The internal file pointer is increased by the number of bytes read.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[out]	pBuffer	Points to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes.
[in]	uBytesRequested	Number of bytes which should be retrieved.
[out]	pBytesRead	On success the number of bytes which have actually been retrieved.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_ISDIR	is a directory
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_AGAIN	operation would block
osl_File_E_NOLINK	link has been severed

See also: osl_openFile(); osl_writeFile(); osl_readLine(); osl_setFilePos()

◆ osl_readFileAt()

SAL_DLLPUBLIC oslFileError osl_readFileAt	(	oslFileHandle	Handle,
		sal_uInt64	uOffset,
		void *	pBuffer,
		sal_uInt64	uBytesRequested,
		sal_uInt64 *	pBytesRead
	)

Read a number of bytes from a specified offset in a file.

The current position of the internal file pointer may or may not be changed.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in]	uOffset	Offset position from start of file where read starts
[out]	pBuffer	Points to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes.
[in]	uBytesRequested	Number of bytes which should be retrieved.
[out]	pBytesRead	On success the number of bytes which have actually been retrieved.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_ISDIR	is a directory
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_AGAIN	operation would block
osl_File_E_NOLINK	link has been severed

Since: UDK 3.2.10

◆ osl_readLine()

SAL_DLLPUBLIC oslFileError osl_readLine	(	oslFileHandle	Handle,
		sal_Sequence **	ppSequence
	)

Read a line from a file.

Reads a line from a file. The new line delimiter is NOT returned!

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in,out]	ppSequence	A pointer pointer to a sal_Sequence that will hold the line read on success.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_ISDIR	is a directory
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_AGAIN	operation would block
osl_File_E_NOLINK	link has been severed

See also: osl_openFile(); osl_readFile(); osl_writeFile(); osl_setFilePos()

◆ osl_releaseDirectoryItem()

SAL_DLLPUBLIC oslFileError osl_releaseDirectoryItem ( oslDirectoryItem Item )

Decrease the refcount of a directory item handle.

Decreases the refcount of a directory item handle. If the refcount reaches 0 the data associated with this directory item handle will be released.

Parameters

[in] Item A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().

Return values

osl_File_E_None	on success
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getDirectoryItem(); osl_getNextDirectoryItem(); osl_acquireDirectoryItem()

◆ osl_releaseVolumeDeviceHandle()

SAL_DLLPUBLIC oslFileError osl_releaseVolumeDeviceHandle ( oslVolumeDeviceHandle Handle )

Release a volume device handle.

Releases the given oslVolumeDeviceHandle which was acquired by a call to osl_getVolumeInformation() or osl_acquireVolumeDeviceHandle().

Parameters

[in] Handle An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().

Return values

osl_File_E_None on success

Todo:: specify all error codes that may be returned

See also: osl_acquireVolumeDeviceHandle(); osl_getVolumeInformation()

◆ osl_removeDirectory()

SAL_DLLPUBLIC oslFileError osl_removeDirectory ( rtl_uString * pustrDirectoryURL )

Remove an empty directory.

Parameters

[in] pustrDirectoryURL Full qualified URL of the directory.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_PERM	operation not permitted
osl_File_E_ACCES	permission denied
osl_File_E_NOENT	no such file or directory
osl_File_E_NOTDIR	not a directory
osl_File_E_NOTEMPTY	directory not empty
osl_File_E_FAULT	bad address
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_BUSY	device or resource busy
osl_File_E_ROFS	read-only file system
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_EXIST	file exists
osl_File_E_IO	on I/O errors
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed

See also: osl_createDirectory()

◆ osl_removeFile()

SAL_DLLPUBLIC oslFileError osl_removeFile ( rtl_uString * pustrFileURL )

Remove a regular file.

Parameters

[in] pustrFileURL Full qualified URL of the file to remove.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_PERM	operation not permitted
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file or directory
osl_File_E_ISDIR	is a directory
osl_File_E_ROFS	read-only file system
osl_File_E_FAULT	bad address
osl_File_E_LOOP	too many symbolic links encountered
osl_File_E_IO	on I/O errors
osl_File_E_BUSY	device or resource busy
osl_File_E_INTR	function call was interrupted
osl_File_E_MULTIHOP	multihop attempted
osl_File_E_NOLINK	link has been severed
osl_File_E_TXTBSY	text file busy

See also: osl_openFile()

◆ osl_replaceFile()

SAL_DLLPUBLIC oslFileError osl_replaceFile	(	rtl_uString *	pustrSourceFileURL,
		rtl_uString *	pustrDestFileURL
	)

Move a file to a new destination or rename it, taking old file's identity (if exists).

Moves or renames a file, replacing an existing file if exist. If the old file existed, moved file's metadata, e.g. creation time (on FSes which keep files' creation time) or ACLs, are set to old one's (to keep the old file's identity) - currently this is only implemented fully on Windows; on other platforms, this is mostly equivalent to osl_moveFile.

Parameters

[in]	pustrSourceFileURL	Full qualified URL of the source file.
[in]	pustrDestFileURL	Full qualified URL of the destination file.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOMEM	not enough memory for allocating structures
osl_File_E_ACCES	permission denied
osl_File_E_PERM	operation not permitted
osl_File_E_NAMETOOLONG	file name too long
osl_File_E_NOENT	no such file
osl_File_E_ROFS	read-only file system
osl_File_E_BUSY	if the implementation internally requires resources that are (temporarily) unavailable

See also: osl_moveFile()

Since: LibreOffice 6.2

◆ osl_searchFileURL()

SAL_DLLPUBLIC oslFileError osl_searchFileURL	(	rtl_uString *	pustrFileName,
		rtl_uString *	pustrSearchPath,
		rtl_uString **	ppustrFileURL
	)

Search a full qualified system path or a file URL.

Parameters

[in] pustrFileName A system dependent path, a file URL, a file or relative directory.

[in]

pustrSearchPath

A list of system paths, in which a given file has to be searched. The Notation of a path list is system dependent, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH". These paths are only for the search of a file or a relative path, otherwise it will be ignored. If pustrSearchPath is NULL or while using the search path the search failed, the function searches for a matching file in all system directories and in the directories listed in the PATH environment variable.

The value of an environment variable should be used (e.g. LD_LIBRARY_PATH) if the caller is not aware of the Operating System and so doesn't know which path list delimiter to use.

Parameters

[out] ppustrFileURL On success it receives the full qualified file URL.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOTDIR	not a directory
osl_File_E_NOENT	no such file or directory not found

See also: osl_getFileURLFromSystemPath(); osl_getSystemPathFromFileURL()

◆ osl_setFileAttributes()

SAL_DLLPUBLIC oslFileError osl_setFileAttributes	(	rtl_uString *	pustrFileURL,
		sal_uInt64	uAttributes
	)

Set file attributes.

Parameters

[in]	pustrFileURL	The full qualified file URL.
[in]	uAttributes	Attributes of the file to be set.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid

See also: osl_getFileStatus()

◆ osl_setFilePos()

SAL_WARN_UNUSED_RESULT SAL_DLLPUBLIC oslFileError osl_setFilePos	(	oslFileHandle	Handle,
		sal_uInt32	uHow,
		sal_Int64	uPos
	)

Set the internal position pointer of an open file.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in]	uHow	How to calculate the offset - osl_Pos_Absolut means start at the beginning of the file, osl_Pos_Current means offset from the current seek position and osl_Pos_End means the offset will be negative and the position will be calculated backwards from the end of the file by the offset provided.
[in]	uPos	Seek offset, depending on uHow. If uHow is osl_Pos_End then the value must be negative.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid (e.g. if uHow is osl_Pos_End then must be negative)
osl_File_E_OVERFLOW	the resulting file offset would be a value which cannot be represented correctly for regular files

See also: osl_openFile(); osl_getFilePos()

◆ osl_setFileSize()

SAL_DLLPUBLIC oslFileError osl_setFileSize	(	oslFileHandle	Handle,
		sal_uInt64	uSize
	)

Set the file size of an open file.

Sets the file size of an open file. The file can be truncated or enlarged by the function. The position of the file pointer is not affeced by this function.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in]	uSize	New size in bytes.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_OVERFLOW	the resulting file offset would be a value which cannot be represented correctly for regular files

See also: osl_openFile(); osl_setFilePos(); osl_getFileStatus(); osl_getFileSize()

◆ osl_setFileTime()

SAL_DLLPUBLIC oslFileError osl_setFileTime	(	rtl_uString *	pustrFileURL,
		const TimeValue *	aCreationTime,
		const TimeValue *	aLastAccessTime,
		const TimeValue *	aLastWriteTime
	)

Set the file time.

Parameters

[in]	pustrFileURL	The full qualified URL of the file.
[in]	aCreationTime	Creation time of the given file.
[in]	aLastAccessTime	Time of the last access of the given file.
[in]	aLastWriteTime	Time of the last modifying of the given file.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_NOENT	no such file or directory not found

See also: osl_getFileStatus()

◆ osl_syncFile()

SAL_DLLPUBLIC oslFileError osl_syncFile ( oslFileHandle Handle )

Synchronize the memory representation of a file with that on the physical medium.

The function ensures that all modified data and attributes of the file associated with the given file handle have been written to the physical medium. In case the hard disk has a write cache enabled, the data may not really be on permanent storage when osl_syncFile returns.

Parameters

Handle [in] Handle to a file received by a previous call to osl_openFile().

Return values

osl_File_E_None	On success
osl_File_E_INVAL	The value of the input parameter is invalid
osl_File_E_BADF	The file associated with the given file handle is not open for writing
osl_File_E_IO	An I/O error occurred
osl_File_E_NOSPC	There is no enough space on the target device
osl_File_E_ROFS	The file associated with the given file handle is located on a read only file system
osl_File_E_TIMEDOUT	A remote connection timed out. This may happen when a file is on a remote location

See also: osl_openFile(); osl_writeFile()

◆ osl_unmapFile()

SAL_DLLPUBLIC oslFileError osl_unmapFile	(	void *	pAddr,
		sal_uInt64	uLength
	)

Unmap a shared file from memory.

This function just won't work on Android in general where for (uncompressed) files inside the .apk, per SDK conventions in the /assets folder, osl_mapFile() returns a pointer to the file inside the already by LibreOffice Android-specific bootstrapping code mmapped .apk archive. We can't go and randomly munmap part of the .apk archive. So this function is not present on Android.

Since: UDK 3.2.10

◆ osl_unmapMappedFile()

SAL_DLLPUBLIC oslFileError osl_unmapMappedFile	(	oslFileHandle	Handle,
		void *	pAddr,
		sal_uInt64	uLength
	)

Unmap a file segment from memory.

Like osl_unmapFile(), but takes also the oslFileHandle argument passed to osl_mapFile() when creating this mapping.

On Android, for files below /assets, i.e. located inside the app archive (.apk), this won't actually unmap anything; all the .apk stays mapped.

Since: UDK 3.6

◆ osl_writeFile()

SAL_DLLPUBLIC oslFileError osl_writeFile	(	oslFileHandle	Handle,
		const void *	pBuffer,
		sal_uInt64	uBytesToWrite,
		sal_uInt64 *	pBytesWritten
	)

Write a number of bytes to a file.

Writes a number of bytes to a file. The internal file pointer is increased by the number of bytes read.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in]	pBuffer	Points to a buffer which contains the data.
[in]	uBytesToWrite	Number of bytes which should be written.
[out]	pBytesWritten	On success the number of bytes which have actually been written.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_FBIG	file too large
osl_File_E_DQUOT	quota exceeded
osl_File_E_AGAIN	operation would block
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_NOLCK	no record locks available
osl_File_E_NOLINK	link has been severed
osl_File_E_NOSPC	no space left on device
osl_File_E_NXIO	no such device or address

See also: osl_openFile(); osl_readFile(); osl_setFilePos()

◆ osl_writeFileAt()

SAL_DLLPUBLIC oslFileError osl_writeFileAt	(	oslFileHandle	Handle,
		sal_uInt64	uOffset,
		const void *	pBuffer,
		sal_uInt64	uBytesToWrite,
		sal_uInt64 *	pBytesWritten
	)

Write a number of bytes to a specified offset in a file.

The current position of the internal file pointer may or may not be changed.

Parameters

[in]	Handle	Handle to a file received by a previous call to osl_openFile().
[in]	uOffset	Position of file to write into.
[in]	pBuffer	Points to a buffer which contains the data.
[in]	uBytesToWrite	Number of bytes which should be written.
[out]	pBytesWritten	On success the number of bytes which have actually been written.

Return values

osl_File_E_None	on success
osl_File_E_INVAL	the format of the parameters was not valid
osl_File_E_FBIG	file too large
osl_File_E_DQUOT	quota exceeded
osl_File_E_AGAIN	operation would block
osl_File_E_BADF	bad file
osl_File_E_FAULT	bad address
osl_File_E_INTR	function call was interrupted
osl_File_E_IO	on I/O errors
osl_File_E_NOLCK	no record locks available
osl_File_E_NOLINK	link has been severed
osl_File_E_NOSPC	no space left on device
osl_File_E_NXIO	no such device or address

Since: UDK 3.2.10

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ osl_File_MapFlag_RandomAccess

◆ osl_File_MapFlag_WillNeed

◆ osl_File_OpenFlag_Create

◆ osl_File_OpenFlag_NoLock

◆ osl_File_OpenFlag_Read

◆ osl_File_OpenFlag_Write

◆ osl_Pos_Absolut

◆ osl_Pos_Current

◆ osl_Pos_End

Typedef Documentation

◆ oslCalcTextWidthFunc

◆ oslDirectory

◆ oslDirectoryCreationCallbackFunc

◆ oslDirectoryItem

◆ oslFileHandle

◆ oslFileStatus

◆ oslVolumeDeviceHandle

◆ oslVolumeInfo

Enumeration Type Documentation

◆ oslFileError

Function Documentation

◆ osl_abbreviateSystemPath()

◆ osl_acquireDirectoryItem()

◆ osl_acquireVolumeDeviceHandle()

◆ osl_closeDirectory()

◆ osl_closeFile()

◆ osl_copyFile()

◆ osl_createDirectory()

◆ osl_createDirectoryPath()

◆ osl_createDirectoryWithFlags()

◆ osl_createTempFile()

◆ osl_getAbsoluteFileURL()

◆ osl_getCanonicalName()

◆ osl_getDirectoryItem()

◆ osl_getFilePos()

◆ osl_getFileSize()

◆ osl_getFileStatus()

◆ osl_getFileURLFromSystemPath()

◆ osl_getNextDirectoryItem()

◆ osl_getSystemPathFromFileURL()

◆ osl_getTempDirURL()

◆ osl_getVolumeDeviceMountPath()

◆ osl_getVolumeInformation()

◆ osl_identicalDirectoryItem()

◆ osl_isEndOfFile()

◆ osl_mapFile()

◆ osl_moveFile()

◆ osl_openDirectory()

◆ osl_openFile()

◆ osl_readFile()

◆ osl_readFileAt()

◆ osl_readLine()

◆ osl_releaseDirectoryItem()

◆ osl_releaseVolumeDeviceHandle()

◆ osl_removeDirectory()

◆ osl_removeFile()

◆ osl_replaceFile()

◆ osl_searchFileURL()

◆ osl_setFileAttributes()

◆ osl_setFilePos()

◆ osl_setFileSize()

◆ osl_setFileTime()

◆ osl_syncFile()

◆ osl_unmapFile()

◆ osl_unmapMappedFile()

◆ osl_writeFile()

◆ osl_writeFileAt()