LibreOffice
LibreOffice 5.3 SDK C/C++ API Reference
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
Classes | Macros | Typedefs | Enumerations | Functions
file.h File Reference

Main goals and usage hints. More...

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

Go to the source code of this file.

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   0x00000001L
 
#define osl_Volume_Attribute_Remote   0x00000002L
 
#define osl_Volume_Attribute_CompactDisc   0x00000004L
 
#define osl_Volume_Attribute_FixedDisk   0x00000008L
 
#define osl_Volume_Attribute_RAMDisk   0x00000010L
 
#define osl_Volume_Attribute_FloppyDisk   0x00000020L
 
#define osl_Volume_Attribute_Case_Is_Preserved   0x00000040L
 
#define osl_Volume_Attribute_Case_Sensitive   0x00000080L
 
#define osl_VolumeInfo_Mask_Attributes   0x00000001L
 
#define osl_VolumeInfo_Mask_TotalSpace   0x00000002L
 
#define osl_VolumeInfo_Mask_UsedSpace   0x00000004L
 
#define osl_VolumeInfo_Mask_FreeSpace   0x00000008L
 
#define osl_VolumeInfo_Mask_MaxNameLength   0x00000010L
 
#define osl_VolumeInfo_Mask_MaxPathLength   0x00000020L
 
#define osl_VolumeInfo_Mask_FileSystemName   0x00000040L
 
#define osl_VolumeInfo_Mask_DeviceHandle   0x00000080L
 
#define osl_VolumeInfo_Mask_FileSystemCaseHandling   0x00000100L
 
#define osl_File_OpenFlag_Read   0x00000001L
 
#define osl_File_OpenFlag_Write   0x00000002L
 
#define osl_File_OpenFlag_Create   0x00000004L
 
#define osl_File_OpenFlag_NoLock   0x00000008L
 
#define osl_Pos_Absolut   1
 
#define osl_Pos_Current   2
 
#define osl_Pos_End   3
 
#define osl_File_MapFlag_RandomAccess   ((sal_uInt32)(0x1))
 Map flags. 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
 
typedef void * oslVolumeDeviceHandle
 
typedef struct _oslVolumeInfo oslVolumeInfo
 
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_DLLPUBLIC oslFileError osl_setFilePos (oslFileHandle Handle, sal_uInt32 uHow, sal_Int64 uPos) SAL_WARN_UNUSED_RESULT
 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)
 Searche 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...
 

Detailed Description

Main goals and usage hints.

The main intentention of this interface is to provide an universal portable and high performance access to file system issues on any operating system.

There are a few main goals:

1.The path specifications always has to be absolut. 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.

2.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

3.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.

  1. Obtaining information about files or volumes is controlled by a bitmask which specifies which fields are of interest. Due to performance issues 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 he uses this additional information or not. But he 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 (f.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 an 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

#define osl_File_Attribute_Executable   0x00000010
#define osl_File_Attribute_GrpExe   0x00000080
#define osl_File_Attribute_GrpRead   0x00000040
#define osl_File_Attribute_GrpWrite   0x00000020
#define osl_File_Attribute_Hidden   0x00000002
#define osl_File_Attribute_OthExe   0x00002000
#define osl_File_Attribute_OthRead   0x00001000
#define osl_File_Attribute_OthWrite   0x00000800
#define osl_File_Attribute_OwnExe   0x00000400
#define osl_File_Attribute_OwnRead   0x00000200
#define osl_File_Attribute_OwnWrite   0x00000100
#define osl_File_Attribute_ReadOnly   0x00000001
#define osl_File_MapFlag_RandomAccess   ((sal_uInt32)(0x1))

Map flags.

Since
UDK 3.2.10
#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).

Since
UDK 3.2.12
#define osl_File_OpenFlag_Create   0x00000004L
#define osl_File_OpenFlag_NoLock   0x00000008L
#define osl_File_OpenFlag_Read   0x00000001L
#define osl_File_OpenFlag_Write   0x00000002L
#define osl_FileStatus_Mask_AccessTime   0x00000020
#define osl_FileStatus_Mask_All   0x7FFFFFFF
#define osl_FileStatus_Mask_Attributes   0x00000002
#define osl_FileStatus_Mask_CreationTime   0x00000010
#define osl_FileStatus_Mask_FileName   0x00000100
#define osl_FileStatus_Mask_FileSize   0x00000080
#define osl_FileStatus_Mask_FileURL   0x00000200
#define osl_FileStatus_Mask_LinkTargetURL   0x00000400
#define osl_FileStatus_Mask_ModifyTime   0x00000040
#define osl_FileStatus_Mask_Type   0x00000001
#define osl_FileStatus_Mask_Validate   0x80000000
#define osl_Pos_Absolut   1
#define osl_Pos_Current   2
#define osl_Pos_End   3
#define osl_Volume_Attribute_Case_Is_Preserved   0x00000040L
#define osl_Volume_Attribute_Case_Sensitive   0x00000080L
#define osl_Volume_Attribute_CompactDisc   0x00000004L
#define osl_Volume_Attribute_FixedDisk   0x00000008L
#define osl_Volume_Attribute_FloppyDisk   0x00000020L
#define osl_Volume_Attribute_RAMDisk   0x00000010L
#define osl_Volume_Attribute_Remote   0x00000002L
#define osl_Volume_Attribute_Removeable   0x00000001L
#define osl_VolumeInfo_Mask_Attributes   0x00000001L
#define osl_VolumeInfo_Mask_DeviceHandle   0x00000080L
#define osl_VolumeInfo_Mask_FileSystemCaseHandling   0x00000100L
#define osl_VolumeInfo_Mask_FileSystemName   0x00000040L
#define osl_VolumeInfo_Mask_FreeSpace   0x00000008L
#define osl_VolumeInfo_Mask_MaxNameLength   0x00000010L
#define osl_VolumeInfo_Mask_MaxPathLength   0x00000020L
#define osl_VolumeInfo_Mask_TotalSpace   0x00000002L
#define osl_VolumeInfo_Mask_UsedSpace   0x00000004L

Typedef Documentation

typedef sal_uInt32( * oslCalcTextWidthFunc)(rtl_uString *ustrText)

Function pointer representing the function called back from osl_abbreviateSystemPath.

Parameters
ustrText[in] 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()
typedef void* oslDirectory
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
typedef void* oslDirectoryItem
typedef void* oslFileHandle
typedef struct _oslFileStatus oslFileStatus
typedef void* oslVolumeDeviceHandle
typedef struct _oslVolumeInfo oslVolumeInfo

Enumeration Type Documentation

Enumerator
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 
Enumerator
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 

Function Documentation

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

Abbreviate a system notation path.

Parameters
ustrSystemPath[in] The full system path to abbreviate
pustrCompacted[out] Receives the compacted system path on output
pCalcWidth[in] Function ptr that calculates the width of a string. Can be zero.
uMaxWidth[in] Maximum width allowed that is retunrned from pCalcWidth. If pCalcWidth is zero the character count is assumed as width.
Returns
osl_File_E_None on success
See Also
oslCalcTextWidthFunc
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
Item[in] A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
Returns
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()
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
Handle[in] An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
Returns
osl_File_E_None on success
Todo:
specify all error codes that may be returned
See Also
osl_getVolumeInformation()
SAL_DLLPUBLIC oslFileError osl_closeDirectory ( oslDirectory  Directory)

Release a directory handle.

Parameters
Directory[in] A handle received by a call to osl_openDirectory().
Returns
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()
SAL_DLLPUBLIC oslFileError osl_closeFile ( oslFileHandle  Handle)

Close an open file.

Parameters
Handle[in] Handle to a file received by a previous call to osl_openFile().
Returns
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()
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
pustrSourceFileURL[in] Full qualified URL of the source file.
pustrDestFileURL[in] Full qualified URL of the destination file. A directory is NOT a valid destination file!
Returns
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()
SAL_DLLPUBLIC oslFileError osl_createDirectory ( rtl_uString *  pustrDirectoryURL)

Create a directory.

Parameters
pustrDirectoryURL[in] Full qualified URL of the directory to create.
Returns
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()
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.

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.
Returns
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
SAL_DLLPUBLIC oslFileError osl_createDirectoryWithFlags ( rtl_uString *  url,
sal_uInt32  flags 
)

Create a directory, passing flags.

Parameters
urlFile URL of the directory to create.
flagsA 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
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
pustrDirectoryURL[in] 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.
pHandle[out] 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.
ppustrTempFileURL[out] 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.
Returns
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()
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
pustrBaseDirectoryURL[in] Base directory URL to which the relative path is related to.
pustrRelativeFileURL[in] An 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.
ppustrAbsoluteFileURL[out] On success it receives the full qualified absolute file URL.
Returns
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()
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
pustrRequestedURL[in] Requested name of a file or directory.
ppustrValidURL[out] On success receives a name which is unused and valid on the actual Operating System and File System.
Returns
osl_File_E_None on success
osl_File_E_INVAL the format of the parameters was not valid
See Also
osl_getFileStatus()
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
pustrFileURL[in] An absolute file URL.
pItem[out] 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().
Returns
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()
SAL_DLLPUBLIC oslFileError osl_getFilePos ( oslFileHandle  Handle,
sal_uInt64 *  pPos 
)

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

Parameters
Handle[in] Handle to a file received by a previous call to osl_openFile().
pPos[out] On success receives the current position of the file pointer.
Returns
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()
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
Handle[in] Handle to a file received by a previous call to osl_openFile().
pSize[out] Current size in bytes.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_getFileStatus ( oslDirectoryItem  Item,
oslFileStatus pStatus,
sal_uInt32  uFieldMask 
)

Retrieve information about a single file or directory.

Parameters
Item[in] A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
pStatus[in|out] 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.
uFieldMask[in] Specifies which fields of the structure pointed to by pStatus are of interest to the caller.
Returns
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
SAL_DLLPUBLIC oslFileError osl_getFileURLFromSystemPath ( rtl_uString *  pustrSystemPath,
rtl_uString **  ppustrFileURL 
)

Convert a system dependent path into a file URL.

Parameters
pustrSystemPath[in] A System dependent path of a file or directory.
ppustrFileURL[out] On success it receives the file URL.
Returns
osl_File_E_None on success
osl_File_E_INVAL the format of the parameters was not valid
See Also
osl_getSystemPathFromFileURL()
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
Directory[in] A directory handle received from a previous call to osl_openDirectory().
pItem[out] 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().
uHint[in] 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.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_getSystemPathFromFileURL ( rtl_uString *  pustrFileURL,
rtl_uString **  ppustrSystemPath 
)

Convert a file URL into a system dependent path.

Parameters
pustrFileURL[in] A File URL.
ppustrSystemPath[out] On success it receives the system path.
Returns
osl_File_E_None on success osl_File_E_INVAL the format of the parameters was not valid
See Also
osl_getFileURLFromSystemPath()
SAL_DLLPUBLIC oslFileError osl_getTempDirURL ( rtl_uString **  pustrTempDirURL)

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

Parameters
[out]pustrTempDirURLOn success receives the URL of system's temporary directory path.
Returns
osl_File_E_None on success osl_File_E_NOENT no such file or directory not found
SAL_DLLPUBLIC oslFileError osl_getVolumeDeviceMountPath ( oslVolumeDeviceHandle  Handle,
rtl_uString **  ppustrDirectoryURL 
)

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

Parameters
Handle[in] An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
ppustrDirectoryURL[out] Receives the full qualified URL where the device is mounted to.
Returns
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()
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
pustrDirectoryURL[in] Full qualified URL of the volume
pInfo[out] On success it receives information about the volume.
uFieldMask[in] Specifies which members of the structure should be filled
Returns
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
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
pItemA[in] A directory handle to compare with another handle
pItemB[in] A directory handle to compare with pItemA
Returns
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
SAL_DLLPUBLIC oslFileError osl_isEndOfFile ( oslFileHandle  Handle,
sal_Bool pIsEOF 
)

Test if the end of a file is reached.

Parameters
Handle[in] Handle to a file received by a previous call to osl_openFile().
pIsEOF[out] Points to a variable that receives the end-of-file status.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_mapFile ( oslFileHandle  Handle,
void **  ppAddr,
sal_uInt64  uLength,
sal_uInt64  uOffset,
sal_uInt32  uFlags 
)

Map a shared file into memory.

Don't know what the "shared" is supposed to mean there? Also, obviously this API can be used to map part of a file into memory, and different parts can be mapped separately even.

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.

Since
UDK 3.2.10
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
pustrSourceFileURL[in] Full qualified URL of the source file.
pustrDestFileURL[in] Full qualified URL of the destination file. An existing directory is NOT a valid destination !
Returns
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()
SAL_DLLPUBLIC oslFileError osl_openDirectory ( rtl_uString *  pustrDirectoryURL,
oslDirectory pDirectory 
)

Open a directory for enumerating its contents.

Parameters
pustrDirectoryURL[in] The full qualified URL of the directory.
pDirectory[out] 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().
Returns
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 an 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()
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 openend.

Parameters
pustrFileURL[in] The full qualified URL of the file to open.
pHandle[out] On success it receives a handle to the open file.
uFlags[in] 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.

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

Since
UDK 3.2.10
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
Handle[in] Handle to a file received by a previous call to osl_openFile().
ppSequence[in/out] A pointer pointer to a sal_Sequence that will hold the line read on success.
Returns
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()
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
Item[in] A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
Returns
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()
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
Handle[in] An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
Returns
osl_File_E_None on success
Todo:
specify all error codes that may be returned
See Also
osl_acquireVolumeDeviceHandle()
osl_getVolumeInformation()
SAL_DLLPUBLIC oslFileError osl_removeDirectory ( rtl_uString *  pustrDirectoryURL)

Remove an empty directory.

Parameters
pustrDirectoryURL[in] Full qualified URL of the directory.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_removeFile ( rtl_uString *  pustrFileURL)

Remove a regular file.

Parameters
pustrFileURL[in] Full qualified URL of the file to remove.
Returns
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_LOOP too many symbolic links encountered
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()
SAL_DLLPUBLIC oslFileError osl_searchFileURL ( rtl_uString *  pustrFileName,
rtl_uString *  pustrSearchPath,
rtl_uString **  ppustrFileURL 
)

Searche a full qualified system path or a file URL.

Parameters
pustrFileName[in] A system dependent path, a file URL, a file or relative directory.
pustrSearchPath[in] 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.
ppustrFileURL[out] On success it receives the full qualified file URL.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_setFileAttributes ( rtl_uString *  pustrFileURL,
sal_uInt64  uAttributes 
)

Set file attributes.

Parameters
pustrFileURL[in] The full qualified file URL.
uAttributes[in] Attributes of the file to be set.
Returns
osl_File_E_None on success
osl_File_E_INVAL the format of the parameters was not valid
See Also
osl_getFileStatus()
SAL_DLLPUBLIC oslFileError osl_setFilePos ( oslFileHandle  Handle,
sal_uInt32  uHow,
sal_Int64  uPos 
)

Set the internal position pointer of an open file.

Parameters
Handle[in] Handle to a file received by a previous call to osl_openFile().
uHow[in] Distance to move the internal position pointer (from uPos).
uPos[in] Absolute position from the beginning of the file.
Returns
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_getFilePos()
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
Handle[in] Handle to a file received by a previous call to osl_openFile().
uSize[in] New size in bytes.
Returns
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()
SAL_DLLPUBLIC oslFileError osl_setFileTime ( rtl_uString *  pustrFileURL,
const TimeValue aCreationTime,
const TimeValue aLastAccessTime,
const TimeValue aLastWriteTime 
)

Set the file time.

Parameters
pustrFileURL[in] The full qualified URL of the file.
aCreationTime[in] Creation time of the given file.
aLastAccessTime[in] Time of the last access of the given file.
aLastWriteTime[in] Time of the last modifying of the given file.
Returns
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()
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().
Returns
osl_File_E_None
On success
osl_File_E_INVAL
The value of the input parameter is invalid

In addition to these error codes others may occur as well, for instance:


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()
SAL_DLLPUBLIC oslFileError osl_unmapFile ( void *  pAddr,
sal_uInt64  uLength 
)

Unmap a shared file from memory.

Ditto here, why do we need to mention "shared"?

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
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
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
Handle[in] Handle to a file received by a previous call to osl_openFile().
pBuffer[in] Points to a buffer which contains the data.
uBytesToWrite[in] Number of bytes which should be written.
pBytesWritten[out] On success the number of bytes which have actually been written.
Returns
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 errosr
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()
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.

Since
UDK 3.2.10