LibreOffice
LibreOffice 24.2 SDK C/C++ API Reference
Public Member Functions | Static Public Member Functions | Friends | List of all members
osl::File Class Reference

The file class object provides access to file contents and attributes. More...

#include <file.hxx>

Inheritance diagram for osl::File:
osl::FileBase

Public Member Functions

 File (const ::rtl::OUString &ustrFileURL)
 Constructor. More...
 
 ~File ()
 Destructor. More...
 
rtl::OUString getURL () const
 Obtain the URL. More...
 
RC open (sal_uInt32 uFlags)
 Open a regular file. More...
 
RC close ()
 Close an open file. More...
 
SAL_WARN_UNUSED_RESULT RC setPos (sal_uInt32 uHow, sal_Int64 uPos)
 Set the internal position pointer of an open file. More...
 
RC getPos (sal_uInt64 &uPos)
 Retrieve the current position of the internal pointer of an open file. More...
 
RC isEndOfFile (sal_Bool *pIsEOF)
 Test if the end of a file is reached. More...
 
RC setSize (sal_uInt64 uSize)
 Set the file size of an open file. More...
 
RC getSize (sal_uInt64 &rSize)
 Get the file size of an open file. More...
 
RC read (void *pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 &rBytesRead)
 Read a number of bytes from a file. More...
 
RC write (const void *pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 &rBytesWritten)
 Write a number of bytes to a file. More...
 
RC readLine (::rtl::ByteSequence &aSeq)
 Read a line from a file. More...
 
RC sync () const
 Synchronize the memory representation of a file with that on the physical medium. More...
 

Static Public Member Functions

static RC copy (const ::rtl::OUString &ustrSourceFileURL, const ::rtl::OUString &ustrDestFileURL)
 Copy a file to a new destination. More...
 
static RC move (const ::rtl::OUString &ustrSourceFileURL, const ::rtl::OUString &ustrDestFileURL)
 Move a file or directory to a new destination or renames it. More...
 
static RC replace (const ::rtl::OUString &ustrSourceFileURL, const ::rtl::OUString &ustrDestFileURL)
 Move a file to a new destination or rename it, taking old file's identity (if exists). More...
 
static RC remove (const ::rtl::OUString &ustrFileURL)
 Remove a regular file. More...
 
static RC setAttributes (const ::rtl::OUString &ustrFileURL, sal_uInt64 uAttributes)
 Set file attributes. More...
 
static RC setTime (const ::rtl::OUString &ustrFileURL, const TimeValue &rCreationTime, const TimeValue &rLastAccessTime, const TimeValue &rLastWriteTime)
 Set the file time. More...
 
- Static Public Member Functions inherited from osl::FileBase
static RC getCanonicalName (const ::rtl::OUString &ustrRequestedURL, ::rtl::OUString &ustrValidURL)
 Determine a valid unused canonical name for a requested name. More...
 
static RC getAbsoluteFileURL (const ::rtl::OUString &ustrBaseDirectoryURL, const ::rtl::OUString &ustrRelativeFileURL, ::rtl::OUString &ustrAbsoluteFileURL)
 Convert a path relative to a given directory into an full qualified file URL. More...
 
static RC getSystemPathFromFileURL (const ::rtl::OUString &ustrFileURL, ::rtl::OUString &ustrSystemPath)
 Convert a file URL into a system dependent path. More...
 
static RC getFileURLFromSystemPath (const ::rtl::OUString &ustrSystemPath, ::rtl::OUString &ustrFileURL)
 Convert a system dependent path into a file URL. More...
 
static RC searchFileURL (const ::rtl::OUString &ustrFileName, const ::rtl::OUString &ustrSearchPath, ::rtl::OUString &ustrFileURL)
 Search a full qualified system path or a file URL. More...
 
static RC getTempDirURL (::rtl::OUString &ustrTempDirURL)
 Retrieves the file URL of the system's temporary directory path. More...
 
static RC createTempFile (::rtl::OUString *pustrDirectoryURL, oslFileHandle *pHandle, ::rtl::OUString *pustrTempFileURL)
 Creates a temporary file in the directory provided by the caller or the directory returned by getTempDirURL. More...
 

Friends

class DirectoryItem
 

Additional Inherited Members

- Public Types inherited from osl::FileBase
enum  RC {
  E_None = osl_File_E_None, E_PERM = osl_File_E_PERM, E_NOENT = osl_File_E_NOENT, E_SRCH = osl_File_E_SRCH,
  E_INTR = osl_File_E_INTR, E_IO = osl_File_E_IO, E_NXIO = osl_File_E_NXIO, E_2BIG = osl_File_E_2BIG,
  E_NOEXEC = osl_File_E_NOEXEC, E_BADF = osl_File_E_BADF, E_CHILD = osl_File_E_CHILD, E_AGAIN = osl_File_E_AGAIN,
  E_NOMEM = osl_File_E_NOMEM, E_ACCES = osl_File_E_ACCES, E_FAULT = osl_File_E_FAULT, E_BUSY = osl_File_E_BUSY,
  E_EXIST = osl_File_E_EXIST, E_XDEV = osl_File_E_XDEV, E_NODEV = osl_File_E_NODEV, E_NOTDIR = osl_File_E_NOTDIR,
  E_ISDIR = osl_File_E_ISDIR, E_INVAL = osl_File_E_INVAL, E_NFILE = osl_File_E_NFILE, E_MFILE = osl_File_E_MFILE,
  E_NOTTY = osl_File_E_NOTTY, E_FBIG = osl_File_E_FBIG, E_NOSPC = osl_File_E_NOSPC, E_SPIPE = osl_File_E_SPIPE,
  E_ROFS = osl_File_E_ROFS, E_MLINK = osl_File_E_MLINK, E_PIPE = osl_File_E_PIPE, E_DOM = osl_File_E_DOM,
  E_RANGE = osl_File_E_RANGE, E_DEADLK = osl_File_E_DEADLK, E_NAMETOOLONG = osl_File_E_NAMETOOLONG, E_NOLCK = osl_File_E_NOLCK,
  E_NOSYS = osl_File_E_NOSYS, E_NOTEMPTY = osl_File_E_NOTEMPTY, E_LOOP = osl_File_E_LOOP, E_ILSEQ = osl_File_E_ILSEQ,
  E_NOLINK = osl_File_E_NOLINK, E_MULTIHOP = osl_File_E_MULTIHOP, E_USERS = osl_File_E_USERS, E_OVERFLOW = osl_File_E_OVERFLOW,
  E_NOTREADY = osl_File_E_NOTREADY, E_invalidError = osl_File_E_invalidError, E_TIMEDOUT = osl_File_E_TIMEDOUT, E_NETWORK = osl_File_E_NETWORK
}
 

Detailed Description

The file class object provides access to file contents and attributes.

See also
Directory
DirectoryItem

Constructor & Destructor Documentation

◆ File()

osl::File::File ( const ::rtl::OUString ustrFileURL)
inline

Constructor.

Parameters
[in]ustrFileURLThe full qualified URL of the file. Relative paths are not allowed.

◆ ~File()

osl::File::~File ( )
inline

Destructor.

Member Function Documentation

◆ close()

RC osl::File::close ( )
inline

Close an open file.

Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_BADFBad file
E_INTRfunction call was interrupted
E_NOLINKlink has been severed
E_NOSPCno space left on device
E_IOon I/O errors
See also
open()

◆ copy()

static RC osl::File::copy ( const ::rtl::OUString ustrSourceFileURL,
const ::rtl::OUString ustrDestFileURL 
)
inlinestatic

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]ustrSourceFileURLFull qualified URL of the source file.
[in]ustrDestFileURLFull qualified URL of the destination file. A directory is NOT a valid destination file!
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_NOMEMnot enough memory for allocating structures
E_ACCESpermission denied
E_PERMoperation not permitted
E_NAMETOOLONGfile name too long
E_NOENTno such file or directory
E_ISDIRis a directory
E_ROFSread-only file system
See also
move()
remove()

◆ getPos()

RC osl::File::getPos ( sal_uInt64 &  uPos)
inline

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

Parameters
[out]uPosOn success receives the current position of the file pointer.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_OVERFLOWthe resulting file offset would be a value which cannot be represented correctly for regular files
See also
open()
setPos()
read()
write()

◆ getSize()

RC osl::File::getSize ( sal_uInt64 &  rSize)
inline

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
[out]rSizeCurrent size in bytes.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_OVERFLOWthe resulting file offset would be a value which cannot be represented correctly for regular files
See also
open()
setPos()
getSize()
setSize()
getStatus()

◆ getURL()

rtl::OUString osl::File::getURL ( ) const
inline

Obtain the URL.

Returns
the URL with which this File instance was created.
Since
LibreOffice 4.1

◆ isEndOfFile()

RC osl::File::isEndOfFile ( sal_Bool pIsEOF)
inline

Test if the end of a file is reached.

Parameters
[out]pIsEOFPoints to a variable that receives the end-of-file status.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_INTRfunction call was interrupted
E_IOon I/O errors
E_ISDIRis a directory
E_BADFbad file
E_FAULTbad address
E_AGAINoperation would block
E_NOLINKlink has been severed
See also
open()
read()
readLine()
setPos()

◆ move()

static RC osl::File::move ( const ::rtl::OUString ustrSourceFileURL,
const ::rtl::OUString ustrDestFileURL 
)
inlinestatic

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]ustrSourceFileURLFull qualified URL of the source file.
[in]ustrDestFileURLFull qualified URL of the destination file. An existing directory is NOT a valid destination !
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_NOMEMnot enough memory for allocating structures
E_ACCESpermission denied
E_PERMoperation not permitted
E_NAMETOOLONGfile name too long
E_NOENTno such file or directory
E_ROFSread-only file system
See also
copy()

◆ open()

RC osl::File::open ( sal_uInt32  uFlags)
inline

Open a regular file.

Open a file. Only regular files can be opened.

Parameters
[in]uFlagsSpecifies the open mode.
Return values
E_Noneon success
E_NOMEMnot enough memory for allocating structures
E_INVALthe format of the parameters was not valid
E_NAMETOOLONGpathname was too long
E_NOENTno such file or directory
E_ACCESpermission denied
E_AGAINa write lock could not be established
E_NOTDIRnot a directory
E_NXIOno such device or address
E_NODEVno such device
E_ROFSread-only file system
E_TXTBSYtext file busy
E_FAULTbad address
E_LOOPtoo many symbolic links encountered
E_NOSPCno space left on device
E_ISDIRis a directory
E_MFILEtoo many open files used by the process
E_NFILEtoo many open files in the system
E_DQUOTquota exceeded
E_EXISTfile exists
E_INTRfunction call was interrupted
E_IOon I/O errors
E_MULTIHOPmultihop attempted
E_NOLINKlink has been severed
E_EOVERFLOWvalue too large for defined data type
See also
close()
setPos()
getPos()
read()
write()
getSize()
setSize()

◆ read()

RC osl::File::read ( void *  pBuffer,
sal_uInt64  uBytesRequested,
sal_uInt64 &  rBytesRead 
)
inline

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
[out]pBufferPoints to a buffer which receives data. The buffer must be large enough to hold uBytesRequested bytes.
[in]uBytesRequestedNumber of bytes which should be retrieved.
[out]rBytesReadOn success the number of bytes which have actually been retrieved.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_INTRfunction call was interrupted
E_IOon I/O errors
E_ISDIRis a directory
E_BADFbad file
E_FAULTbad address
E_AGAINoperation would block
E_NOLINKlink has been severed
See also
open()
write()
readLine()
setPos()

◆ readLine()

RC osl::File::readLine ( ::rtl::ByteSequence aSeq)
inline

Read a line from a file.

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

Parameters
[in,out]aSeqA reference to a rtl::ByteSequence that will hold the line read on success.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_INTRfunction call was interrupted
E_IOon I/O errors
E_ISDIRis a directory
E_BADFbad file
E_FAULTbad address
E_AGAINoperation would block
E_NOLINKlink has been severed
See also
open()
read()
write()
setPos()

◆ remove()

static RC osl::File::remove ( const ::rtl::OUString ustrFileURL)
inlinestatic

Remove a regular file.

Parameters
[in]ustrFileURLFull qualified URL of the file to remove.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_NOMEMnot enough memory for allocating structures
E_ACCESpermission denied
E_PERMoperation not permitted
E_NAMETOOLONGfile name too long
E_NOENTno such file or directory
E_ISDIRis a directory
E_ROFSread-only file system
E_FAULTbad address
E_LOOPtoo many symbolic links encountered
E_IOon I/O errors
E_BUSYdevice or resource busy
E_INTRfunction call was interrupted
E_MULTIHOPmultihop attempted
E_NOLINKlink has been severed
E_TXTBSYtext file busy
See also
open()

◆ replace()

static RC osl::File::replace ( const ::rtl::OUString ustrSourceFileURL,
const ::rtl::OUString ustrDestFileURL 
)
inlinestatic

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 move().

Parameters
[in]ustrSourceFileURLFull qualified URL of the source file.
[in]ustrDestFileURLFull qualified URL of the destination file.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_NOMEMnot enough memory for allocating structures
E_ACCESpermission denied
E_PERMoperation not permitted
E_NAMETOOLONGfile name too long
E_NOENTno such file
E_ROFSread-only file system
E_BUSYdevice or resource busy
See also
move()
Since
LibreOffice 6.2

◆ setAttributes()

static RC osl::File::setAttributes ( const ::rtl::OUString ustrFileURL,
sal_uInt64  uAttributes 
)
inlinestatic

Set file attributes.

Parameters
[in]ustrFileURLThe full qualified file URL.
[in]uAttributesAttributes of the file to be set.
Returns
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
See also
FileStatus

◆ setPos()

SAL_WARN_UNUSED_RESULT RC osl::File::setPos ( sal_uInt32  uHow,
sal_Int64  uPos 
)
inline

Set the internal position pointer of an open file.

Parameters
[in]uHowDistance to move the internal position pointer (from uPos).
[in]uPosAbsolute position from the beginning of the file.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_OVERFLOWthe resulting file offset would be a value which cannot be represented correctly for regular files
See also
open()
getPos()

◆ setSize()

RC osl::File::setSize ( sal_uInt64  uSize)
inline

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]uSizeNew size in bytes.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_OVERFLOWthe resulting file offset would be a value which cannot be represented correctly for regular files
See also
open()
setPos()
getStatus()

◆ setTime()

static RC osl::File::setTime ( const ::rtl::OUString ustrFileURL,
const TimeValue rCreationTime,
const TimeValue rLastAccessTime,
const TimeValue rLastWriteTime 
)
inlinestatic

Set the file time.

Parameters
[in]ustrFileURLThe full qualified URL of the file.
[in]rCreationTimeCreation time of the given file.
[in]rLastAccessTimeTime of the last access of the given file.
[in]rLastWriteTimeTime of the last modifying of the given file.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_NOENTno such file or directory not found
See also
FileStatus

◆ sync()

RC osl::File::sync ( ) const
inline

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.

Return values
E_NoneOn success
E_INVALThe value of the input parameter is invalid
E_BADFThe file is not open for writing
E_IOAn I/O error occurred
E_NOSPCThere is no enough space on the target device
E_ROFSThe file is located on a read only file system
E_TIMEDOUTA remote connection timed out. This may happen when a file is on a remote location
See also
osl_syncFile()
open()
write()

◆ write()

RC osl::File::write ( const void *  pBuffer,
sal_uInt64  uBytesToWrite,
sal_uInt64 &  rBytesWritten 
)
inline

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]pBufferPoints to a buffer which contains the data.
[in]uBytesToWriteNumber of bytes which should be written.
[out]rBytesWrittenOn success the number of bytes which have actually been written.
Return values
E_Noneon success
E_INVALthe format of the parameters was not valid
E_FBIGfile too large
E_DQUOTquota exceeded
E_AGAINoperation would block
E_BADFbad file
E_FAULTbad address
E_INTRfunction call was interrupted
E_IOon I/O errors
E_NOLCKno record locks available
E_NOLINKlink has been severed
E_NOSPCno space left on device
E_NXIOno such device or address
See also
open()
read()
setPos()

Friends And Related Function Documentation

◆ DirectoryItem

friend class DirectoryItem
friend

The documentation for this class was generated from the following file: