LibreOffice: osl::File Class Reference

LibreOffice LibreOffice 7.4 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:

## 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] | ustrFileURL | The 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_None | on success
  E_INVAL | the format of the parameters was not valid
  E_BADF | Bad file
  E_INTR | function call was interrupted
  E_NOLINK | link has been severed
  E_NOSPC | no space left on device
  E_IO | on 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] | ustrSourceFileURL | Full qualified URL of the source file.
  [in] | ustrDestFileURL | Full qualified URL of the destination file. A directory is NOT a valid destination file!

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_NOMEM | not enough memory for allocating structures
  E_ACCES | permission denied
  E_PERM | operation not permitted
  E_NAMETOOLONG | file name too long
  E_NOENT | no such file or directory
  E_ISDIR | is a directory
  E_ROFS | read-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] | uPos | On success receives the current position of the file pointer.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_OVERFLOW | the 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] | rSize | Current size in bytes.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_OVERFLOW | the 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] | pIsEOF | Points to a variable that receives the end-of-file status.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_INTR | function call was interrupted
  E_IO | on I/O errors
  E_ISDIR | is a directory
  E_BADF | bad file
  E_FAULT | bad address
  E_AGAIN | operation would block
  E_NOLINK | link 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] | ustrSourceFileURL | Full qualified URL of the source file.
  [in] | ustrDestFileURL | Full qualified URL of the destination file. An existing directory is NOT a valid destination !

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_NOMEM | not enough memory for allocating structures
  E_ACCES | permission denied
  E_PERM | operation not permitted
  E_NAMETOOLONG | file name too long
  E_NOENT | no such file or directory
  E_ROFS | read-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] | uFlags | Specifies the open mode.

Return values

  E_None | on success
  E_NOMEM | not enough memory for allocating structures
  E_INVAL | the format of the parameters was not valid
  E_NAMETOOLONG | pathname was too long
  E_NOENT | no such file or directory
  E_ACCES | permission denied
  E_AGAIN | a write lock could not be established
  E_NOTDIR | not a directory
  E_NXIO | no such device or address
  E_NODEV | no such device
  E_ROFS | read-only file system
  E_TXTBSY | text file busy
  E_FAULT | bad address
  E_LOOP | too many symbolic links encountered
  E_NOSPC | no space left on device
  E_ISDIR | is a directory
  E_MFILE | too many open files used by the process
  E_NFILE | too many open files in the system
  E_DQUOT | quota exceeded
  E_EXIST | file exists
  E_INTR | function call was interrupted
  E_IO | on I/O errors
  E_MULTIHOP | multihop attempted
  E_NOLINK | link has been severed
  E_EOVERFLOW | value 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] | 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] | rBytesRead | On success the number of bytes which have actually been retrieved.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_INTR | function call was interrupted
  E_IO | on I/O errors
  E_ISDIR | is a directory
  E_BADF | bad file
  E_FAULT | bad address
  E_AGAIN | operation would block
  E_NOLINK | link 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] | aSeq | A reference to a rtl::ByteSequence that will hold the line read on success.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_INTR | function call was interrupted
  E_IO | on I/O errors
  E_ISDIR | is a directory
  E_BADF | bad file
  E_FAULT | bad address
  E_AGAIN | operation would block
  E_NOLINK | link 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] | ustrFileURL | Full qualified URL of the file to remove.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_NOMEM | not enough memory for allocating structures
  E_ACCES | permission denied
  E_PERM | operation not permitted
  E_NAMETOOLONG | file name too long
  E_NOENT | no such file or directory
  E_ISDIR | is a directory
  E_ROFS | read-only file system
  E_FAULT | bad address
  E_LOOP | too many symbolic links encountered
  E_IO | on I/O errors
  E_BUSY | device or resource busy
  E_INTR | function call was interrupted
  E_MULTIHOP | multihop attempted
  E_NOLINK | link has been severed
  E_TXTBSY | text 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] | ustrSourceFileURL | Full qualified URL of the source file.
  [in] | ustrDestFileURL | Full qualified URL of the destination file.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_NOMEM | not enough memory for allocating structures
  E_ACCES | permission denied
  E_PERM | operation not permitted
  E_NAMETOOLONG | file name too long
  E_NOENT | no such file
  E_ROFS | read-only file system
  E_BUSY | device 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] | ustrFileURL | The full qualified file URL.
  [in] | uAttributes | Attributes of the file to be set.

Returns

Return values

  E_None | on success
  E_INVAL | the 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] | uHow | Distance to move the internal position pointer (from uPos).
  [in] | uPos | Absolute position from the beginning of the file.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_OVERFLOW | the 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] | uSize | New size in bytes.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_OVERFLOW | the 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] | ustrFileURL | The full qualified URL of the file.
  [in] | rCreationTime | Creation time of the given file.
  [in] | rLastAccessTime | Time of the last access of the given file.
  [in] | rLastWriteTime | Time of the last modifying of the given file.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_NOENT | no 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_None | On success
  E_INVAL | The value of the input parameter is invalid
  E_BADF | The file is not open for writing
  E_IO | An I/O error occurred
  E_NOSPC | There is no enough space on the target device
  E_ROFS | The file is located on a read only file system
  E_TIMEDOUT | A 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] | pBuffer | Points to a buffer which contains the data.
  [in] | uBytesToWrite | Number of bytes which should be written.
  [out] | rBytesWritten | On success the number of bytes which have actually been written.

Return values

  E_None | on success
  E_INVAL | the format of the parameters was not valid
  E_FBIG | file too large
  E_DQUOT | quota exceeded
  E_AGAIN | operation would block
  E_BADF | bad file
  E_FAULT | bad address
  E_INTR | function call was interrupted
  E_IO | on I/O errors
  E_NOLCK | no record locks available
  E_NOLINK | link has been severed
  E_NOSPC | no space left on device
  E_NXIO | no 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:

- osl/file.hxx