include/osl/file.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
   2 /*
   3  * This file is part of the LibreOffice project.
   4  *
   5  * This Source Code Form is subject to the terms of the Mozilla Public
   6  * License, v. 2.0. If a copy of the MPL was not distributed with this
   7  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   8  *
   9  * This file incorporates work covered by the following license notice:
  10  *
  11  *   Licensed to the Apache Software Foundation (ASF) under one or more
  12  *   contributor license agreements. See the NOTICE file distributed
  13  *   with this work for additional information regarding copyright
  14  *   ownership. The ASF licenses this file to you under the Apache
  15  *   License, Version 2.0 (the "License"); you may not use this file
  16  *   except in compliance with the License. You may obtain a copy of
  17  *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
  18  */
  19
  20 /*
  21  * This file is part of LibreOffice published API.
  22  */
  23
  24 #ifndef INCLUDED_OSL_FILE_H
  25 #define INCLUDED_OSL_FILE_H
  26
  27 #include "sal/config.h"
  28
  29 #include "osl/time.h"
  30 #include "rtl/ustring.h"
  31 #include "sal/saldllapi.h"
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /** @file
  38
  39 Main goals and usage hints
  40
  41 The main intention of this interface is to provide a universal portable and
  42 high performance access to file system functionality on any operating
  43 system.
  44
  45 There are a few main goals:
  46
  47 1. The path specifications always has to be absolute. Any usage of relative
  48 path specifications is forbidden. Exceptions are osl_getSystemPathFromFileURL,
  49 osl_getFileURLFromSystemPath and osl_getAbsoluteFileURL. Most operating
  50 systems provide a "Current Directory" per process. This is the reason why
  51 relative path specifications can cause problems in multithreading
  52 environments.
  53
  54 2. Proprietary notations of file paths are not supported. Every path notation
  55 must the file URL specification. File URLs must be encoded in UTF8 and after
  56 that escaped. Although the URL parameter is a unicode string, the must
  57 contain only ASCII characters.
  58
  59 3. The caller cannot get any information whether a file system is case
  60 sensitive, case preserving or not. The operating system implementation
  61 itself should determine if it can map case-insensitive paths. The case
  62 correct notation of a filename or file path is part of the "File Info". This
  63 case correct name can be used as a unique key if necessary.
  64
  65 4. Obtaining information about files or volumes is controlled by a bitmask
  66 which specifies which fields are of interest. Due to performance reasons it
  67 is not recommended to obtain information which is not needed.  But if the
  68 operating system provides more information anyway the implementation can set
  69 more fields on output as were requested. It is in the responsibility of the
  70 caller to decide if they use this additional information or not. But they
  71 should do so to prevent further unnecessary calls if the information is
  72 already there.
  73
  74 The input bitmask supports a flag osl_FileStatus_Mask_Validate which can be
  75 used to force retrieving uncached validated information. Setting this flag
  76 when calling osl_getFileStatus in combination with no other flag is a synonym
  77 for a "FileExists". This should only be done when processing a single file
  78 (i.e. before opening) and NEVER during enumeration of directory contents on
  79 any step of information processing. This would change the runtime behaviour
  80 from O(n) to O(n*n/2) on nearly every file system.  On Windows NT reading the
  81 contents of a directory with 7000 entries and getting full information about
  82 every file only takes 0.6 seconds. Specifying the flag
  83 osl_FileStatus_Mask_Validate for each entry will increase the time to 180
  84 seconds (!!!).
  85
  86 */
  87
  88 /* Error codes according to errno */
  89 typedef enum {
  90     osl_File_E_None,            /*!< on success                                                  */
  91     osl_File_E_PERM,            /*!< operation not permitted                                     */
  92     osl_File_E_NOENT,           /*!< no such file or directory                                   */
  93     osl_File_E_SRCH,            /*!< no process matches the PID                                  */
  94     osl_File_E_INTR,            /*!< function call was interrupted                               */
  95     osl_File_E_IO,              /*!< I/O error occurred                                          */
  96     osl_File_E_NXIO,            /*!< no such device or address                                   */
  97     osl_File_E_2BIG,            /*!< argument list too long                                      */
  98     osl_File_E_NOEXEC,          /*!< invalid executable file format                              */
  99     osl_File_E_BADF,            /*!< bad file descriptor                                         */
 100     osl_File_E_CHILD,           /*!< there are no child processes                                */
 101     osl_File_E_AGAIN,           /*!< resource temp unavailable, try again later                  */
 102     osl_File_E_NOMEM,           /*!< no memory available                                         */
 103     osl_File_E_ACCES,           /*!< file permissions do not allow operation                     */
 104     osl_File_E_FAULT,           /*!< bad address; an invalid pointer detected                    */
 105     osl_File_E_BUSY,            /*!< resource busy                                               */
 106     osl_File_E_EXIST,           /*!< file exists where should only be created                    */
 107     osl_File_E_XDEV,            /*!< improper link across file systems detected                  */
 108     osl_File_E_NODEV,           /*!< wrong device type specified                                 */
 109     osl_File_E_NOTDIR,          /*!< file isn't a directory where one is needed                  */
 110     osl_File_E_ISDIR,           /*!< file is a directory, invalid operation                      */
 111     osl_File_E_INVAL,           /*!< invalid argument to library function                        */
 112     osl_File_E_NFILE,           /*!< too many distinct file openings                             */
 113     osl_File_E_MFILE,           /*!< process has too many distinct files open                    */
 114     osl_File_E_NOTTY,           /*!< inappropriate I/O control operation                         */
 115     osl_File_E_FBIG,            /*!< file too large                                              */
 116     osl_File_E_NOSPC,           /*!< no space left on device, write failed                       */
 117     osl_File_E_SPIPE,           /*!< invalid seek operation (such as on pipe)                    */
 118     osl_File_E_ROFS,            /*!< illegal modification to read-only filesystem                */
 119     osl_File_E_MLINK,           /*!< too many links to file                                      */
 120     osl_File_E_PIPE,            /*!< broken pipe; no process reading from other end of pipe      */
 121     osl_File_E_DOM,             /*!< domain error (mathematical error)                           */
 122     osl_File_E_RANGE,           /*!< range error (mathematical error)                            */
 123     osl_File_E_DEADLK,          /*!< deadlock avoided                                            */
 124     osl_File_E_NAMETOOLONG,     /*!< filename too long                                           */
 125     osl_File_E_NOLCK,           /*!< no locks available                                          */
 126     osl_File_E_NOSYS,           /*!< function not implemented                                    */
 127     osl_File_E_NOTEMPTY,        /*!< directory not empty                                         */
 128     osl_File_E_LOOP,            /*!< too many levels of symbolic links found during name lookup  */
 129     osl_File_E_ILSEQ,           /*!< invalid or incomplete byte sequence of multibyte char found */
 130     osl_File_E_NOLINK,          /*!< link has been severed                                       */
 131     osl_File_E_MULTIHOP,        /*!< remote resource is not directly available                   */
 132     osl_File_E_USERS,           /*!< file quote system is confused as there are too many users   */
 133     osl_File_E_OVERFLOW,        /*!< value too large for defined data type                       */
 134     osl_File_E_NOTREADY,        /*!< device not ready                                            */
 135     osl_File_E_invalidError,    /*!< unmapped error: always last entry in enum!                  */
 136     osl_File_E_TIMEDOUT,        /*!< socket operation timed out                                  */
 137     osl_File_E_NETWORK,         /*!< unexpected network error occurred (Windows) - could be a
 138                                      user session was deleted, or an unexpected network error
 139                                      occurred                                                    */
 140     osl_File_E_FORCE_EQUAL_SIZE = SAL_MAX_ENUM
 141 } oslFileError;
 142
 143 typedef void *oslDirectory;
 144 typedef void *oslDirectoryItem;
 145
 146 /** Open a directory for enumerating its contents.
 147
 148     @param[in]  pustrDirectoryURL
 149     The full qualified URL of the directory.
 150
 151     @param[out]  pDirectory
 152     On success it receives a handle used for subsequent calls by osl_getNextDirectoryItem().
 153     The handle has to be released by a call to osl_closeDirectory().
 154
 155     @retval osl_File_E_None on success
 156     @retval osl_File_E_INVAL the format of the parameters was not valid
 157     @retval osl_File_E_NOENT the specified path doesn't exist
 158     @retval osl_File_E_NOTDIR the specified path is not a directory
 159     @retval osl_File_E_NOMEM not enough memory for allocating structures
 160     @retval osl_File_E_ACCES permission denied
 161     @retval osl_File_E_MFILE too many open files used by the process
 162     @retval osl_File_E_NFILE too many open files in the system
 163     @retval osl_File_E_NAMETOOLONG File name too long
 164     @retval osl_File_E_LOOP Too many symbolic links encountered
 165
 166     @see osl_getNextDirectoryItem()
 167     @see osl_closeDirectory()
 168 */
 169 SAL_DLLPUBLIC oslFileError SAL_CALL osl_openDirectory(
 170         rtl_uString *pustrDirectoryURL, oslDirectory *pDirectory);
 171
 172 /** Retrieve the next item of a previously opened directory.
 173
 174     Retrieves the next item of a previously opened directory.
 175     All handles have an initial refcount of 1.
 176
 177     @param[in]  Directory
 178     A directory handle received from a previous call to osl_openDirectory().
 179
 180     @param[out]  pItem
 181     On success it receives a handle that can be used for subsequent calls to osl_getFileStatus().
 182     The handle has to be released by a call to osl_releaseDirectoryItem().
 183
 184     @param[in]  uHint
 185     With this parameter the caller can tell the implementation that (s)he
 186     is going to call this function uHint times afterwards. This enables the implementation to
 187     get the information for more than one file and cache it until the next calls.
 188
 189     @retval osl_File_E_None on success
 190     @retval osl_File_E_INVAL the format of the parameters was not valid
 191     @retval osl_File_E_NOMEM not enough memory for allocating structures
 192     @retval osl_File_E_NOENT no more entries in this directory
 193     @retval osl_File_E_BADF invalid oslDirectory parameter
 194     @retval osl_File_E_OVERFLOW the value too large for defined data type
 195
 196     @see osl_releaseDirectoryItem()
 197     @see osl_acquireDirectoryItem()
 198     @see osl_getDirectoryItem()
 199     @see osl_getFileStatus()
 200 */
 201 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getNextDirectoryItem(
 202     oslDirectory Directory,
 203     oslDirectoryItem *pItem,
 204     sal_uInt32   uHint
 205     );
 206
 207 /** Release a directory handle.
 208
 209     @param[in] Directory
 210     A handle received by a call to osl_openDirectory().
 211
 212     @retval osl_File_E_None on success
 213     @retval osl_File_E_INVAL the format of the parameters was not valid
 214     @retval osl_File_E_NOMEM not enough memory for allocating structures
 215     @retval osl_File_E_BADF invalid oslDirectory parameter
 216     @retval osl_File_E_INTR the function call was interrupted
 217
 218     @see osl_openDirectory()
 219 */
 220 SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeDirectory(
 221         oslDirectory Directory);
 222
 223 /** Retrieve a single directory item.
 224
 225     Retrieves a single directory item. The returned handle has an initial refcount of 1.
 226     Due to performance issues it is not recommended to use this function while
 227     enumerating the contents of a directory. In this case use osl_getNextDirectoryItem() instead.
 228
 229     @param[in] pustrFileURL
 230     An absolute file URL.
 231
 232     @param[out] pItem
 233     On success it receives a handle which can be used for subsequent calls to osl_getFileStatus().
 234     The handle has to be released by a call to osl_releaseDirectoryItem().
 235
 236     @retval osl_File_E_None on success
 237     @retval osl_File_E_INVAL the format of the parameters was not valid
 238     @retval osl_File_E_NOMEM not enough memory for allocating structures
 239     @retval osl_File_E_ACCES permission denied
 240     @retval osl_File_E_MFILE too many open files used by the process
 241     @retval osl_File_E_NFILE too many open files in the system
 242     @retval osl_File_E_NOENT no such file or directory
 243     @retval osl_File_E_LOOP too many symbolic links encountered
 244     @retval osl_File_E_NAMETOOLONG the file name is too long
 245     @retval osl_File_E_NOTDIR a component of the path prefix of path is not a directory
 246     @retval osl_File_E_IO on I/O errors
 247     @retval osl_File_E_MULTIHOP multihop attempted
 248     @retval osl_File_E_NOLINK link has been severed
 249     @retval osl_File_E_FAULT bad address
 250     @retval osl_File_E_INTR the function call was interrupted
 251
 252     @see osl_releaseDirectoryItem()
 253     @see osl_acquireDirectoryItem()
 254     @see osl_getFileStatus()
 255     @see osl_getNextDirectoryItem()
 256 */
 257 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getDirectoryItem(
 258     rtl_uString *pustrFileURL,
 259     oslDirectoryItem *pItem
 260     );
 261
 262 /** Increase the refcount of a directory item handle.
 263
 264     The caller responsible for releasing the directory item handle using osl_releaseDirectoryItem().
 265
 266     @param[in]  Item
 267     A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
 268
 269     @retval osl_File_E_None on success
 270     @retval osl_File_E_NOMEM not enough memory for allocating structures
 271     @retval osl_File_E_INVAL the format of the parameters was not valid
 272
 273     @see osl_getDirectoryItem()
 274     @see osl_getNextDirectoryItem()
 275     @see osl_releaseDirectoryItem()
 276 */
 277 SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireDirectoryItem(
 278         oslDirectoryItem Item );
 279
 280
 281 /** Decrease the refcount of a directory item handle.
 282
 283     Decreases the refcount of a directory item handle.
 284     If the refcount reaches 0 the data associated with
 285     this directory item handle will be released.
 286
 287     @param[in]  Item
 288     A handle received by a call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
 289
 290     @retval osl_File_E_None on success
 291     @retval osl_File_E_NOMEM not enough memory for allocating structures
 292     @retval osl_File_E_INVAL the format of the parameters was not valid
 293
 294     @see osl_getDirectoryItem()
 295     @see osl_getNextDirectoryItem()
 296     @see osl_acquireDirectoryItem()
 297 */
 298 SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseDirectoryItem(
 299         oslDirectoryItem Item );
 300
 301 /** Determine if two directory items point the same underlying file
 302
 303     The comparison is done first by URL, and then by resolving links to
 304     find the target, and finally by comparing inodes on unix.
 305
 306     @param[in]  pItemA
 307     A directory handle to compare with another handle
 308
 309     @param[in]  pItemB
 310     A directory handle to compare with pItemA
 311
 312     @retval sal_True if the items point to an identical resource
 313     @retval sal_False if the items point to a different resource, or a fatal error occurred
 314
 315     @see osl_getDirectoryItem()
 316
 317     @since LibreOffice 3.6
 318 */
 319 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_identicalDirectoryItem(
 320                                         oslDirectoryItem pItemA,
 321                                         oslDirectoryItem pItemB );
 322
 323 /**
 324    @defgroup filetype File types
 325
 326    @{
 327  */
 328 typedef enum {
 329     osl_File_Type_Directory,        /*< directory               */
 330     osl_File_Type_Volume,           /*< volume (e.g. C:, A:)    */
 331     osl_File_Type_Regular,          /*< regular file            */
 332     osl_File_Type_Fifo,             /*< named pipe              */
 333     osl_File_Type_Socket,           /*< socket                  */
 334     osl_File_Type_Link,             /*< file link               */
 335     osl_File_Type_Special,          /*< special device file     */
 336     osl_File_Type_Unknown           /*< unknown file type       */
 337 } oslFileType;
 338 /** @} */
 339
 340 /**
 341    @defgroup fileattrs File attributes
 342
 343    @{
 344  */
 345 #define osl_File_Attribute_ReadOnly             0x00000001
 346 #define osl_File_Attribute_Hidden               0x00000002
 347 #define osl_File_Attribute_Executable           0x00000010
 348 #define osl_File_Attribute_GrpWrite             0x00000020
 349 #define osl_File_Attribute_GrpRead              0x00000040
 350 #define osl_File_Attribute_GrpExe               0x00000080
 351 #define osl_File_Attribute_OwnWrite             0x00000100
 352 #define osl_File_Attribute_OwnRead              0x00000200
 353 #define osl_File_Attribute_OwnExe               0x00000400
 354 #define osl_File_Attribute_OthWrite             0x00000800
 355 #define osl_File_Attribute_OthRead              0x00001000
 356 #define osl_File_Attribute_OthExe               0x00002000
 357 /** @} */
 358
 359 /**
 360    @defgroup filestatus Flags specifying which fields to retrieve by osl_getFileStatus
 361
 362    @{
 363  */
 364 #define osl_FileStatus_Mask_Type                0x00000001
 365 #define osl_FileStatus_Mask_Attributes          0x00000002
 366 #define osl_FileStatus_Mask_CreationTime        0x00000010
 367 #define osl_FileStatus_Mask_AccessTime          0x00000020
 368 #define osl_FileStatus_Mask_ModifyTime          0x00000040
 369 #define osl_FileStatus_Mask_FileSize            0x00000080
 370 #define osl_FileStatus_Mask_FileName            0x00000100
 371 #define osl_FileStatus_Mask_FileURL             0x00000200
 372 #define osl_FileStatus_Mask_LinkTargetURL       0x00000400
 373 #define osl_FileStatus_Mask_All                 0x7FFFFFFF
 374 #define osl_FileStatus_Mask_Validate            0x80000000
 375 /** @} */
 376
 377 /** Structure containing information about files and directories
 378
 379     @see    osl_getFileStatus()
 380     @see    oslFileType
 381 */
 382 typedef struct _oslFileStatus {
 383 /** Must be initialized with the size in bytes of the structure before passing it to any function */
 384     sal_uInt32      uStructSize;
 385 /** Determines which members of the structure contain valid data */
 386     sal_uInt32      uValidFields;
 387 /** The type of the file (file, directory, volume). */
 388     oslFileType eType;
 389 /** File attributes */
 390     sal_uInt64  uAttributes;
 391 /** First creation time in nanoseconds since 1/1/1970. Can be the last modify time depending on
 392     platform or file system. */
 393     TimeValue   aCreationTime;
 394 /** Last access time in nanoseconds since 1/1/1970. Can be the last modify time depending on
 395     platform or file system. */
 396     TimeValue   aAccessTime;
 397 /** Last modify time in nanoseconds since 1/1/1970. */
 398     TimeValue   aModifyTime;
 399 /** Size in bytes of the file. Zero for directories and volumes. */
 400     sal_uInt64  uFileSize;
 401 /** Case correct name of the file. Should be set to zero before calling osl_getFileStatus
 402     and released after usage. */
 403     rtl_uString *ustrFileName;
 404 /** Full URL of the file. Should be set to zero before calling osl_getFileStatus
 405     and released after usage. */
 406     rtl_uString *ustrFileURL;
 407 /** Full URL of the target file if the file itself is a link.
 408     Should be set to zero before calling osl_getFileStatus
 409     and released after usage. */
 410     rtl_uString *ustrLinkTargetURL;
 411 } oslFileStatus;
 412
 413 /** Retrieve information about a single file or directory.
 414
 415     @param[in]  Item
 416     A handle received by a previous call to osl_getDirectoryItem() or osl_getNextDirectoryItem().
 417
 418     @param[in,out] pStatus
 419     Points to a structure which receives the information of the file or directory
 420     represented by the handle Item. The member uStructSize has to be initialized to
 421     sizeof(oslFileStatus) before calling this function.
 422
 423     @param[in]  uFieldMask
 424     Specifies which fields of the structure pointed to by pStatus are of interest to the caller.
 425
 426     @retval osl_File_E_None on success
 427     @retval osl_File_E_NOMEM not enough memory for allocating structures
 428     @retval osl_File_E_INVAL the format of the parameters was not valid
 429     @retval osl_File_E_LOOP too many symbolic links encountered
 430     @retval osl_File_E_ACCES permission denied
 431     @retval osl_File_E_NOENT no such file or directory
 432     @retval osl_File_E_NAMETOOLONG file name too long
 433     @retval osl_File_E_BADF invalid oslDirectoryItem parameter
 434     @retval osl_File_E_FAULT bad address
 435     @retval osl_File_E_OVERFLOW value too large for defined data type
 436     @retval osl_File_E_INTR function call was interrupted
 437     @retval osl_File_E_NOLINK link has been severed
 438     @retval osl_File_E_MULTIHOP components of path require hopping to multiple
 439         remote machines and the file system does not allow it
 440     @retval osl_File_E_MFILE too many open files used by the process
 441     @retval osl_File_E_NFILE too many open files in the system
 442     @retval osl_File_E_NOSPC no space left on device
 443     @retval osl_File_E_NXIO no such device or address
 444     @retval osl_File_E_IO on I/O errors
 445     @retval osl_File_E_NOSYS function not implemented
 446
 447     @see osl_getDirectoryItem()
 448     @see osl_getNextDirectoryItem()
 449     @see oslFileStatus
 450 */
 451 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileStatus(
 452         oslDirectoryItem Item, oslFileStatus *pStatus, sal_uInt32 uFieldMask );
 453
 454 typedef void *oslVolumeDeviceHandle;
 455
 456 /** Release a volume device handle.
 457
 458     Releases the given oslVolumeDeviceHandle which was acquired by a call to
 459     osl_getVolumeInformation() or osl_acquireVolumeDeviceHandle().
 460
 461     @param[in] Handle
 462     An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
 463
 464     @retval
 465     osl_File_E_None on success
 466
 467     @todo
 468     specify all error codes that may be returned
 469
 470     @see osl_acquireVolumeDeviceHandle()
 471     @see osl_getVolumeInformation()
 472 */
 473 SAL_DLLPUBLIC oslFileError SAL_CALL osl_releaseVolumeDeviceHandle(
 474         oslVolumeDeviceHandle Handle );
 475
 476 /** Acquire a volume device handle.
 477
 478     Acquires the given oslVolumeDeviceHandle which was acquired by a call to
 479     osl_getVolumeInformation(). The caller is responsible for releasing the
 480     acquired handle by calling osl_releaseVolumeDeviceHandle().
 481
 482     @param[in] Handle
 483     An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
 484
 485     @retval
 486     osl_File_E_None on success
 487
 488     @todo
 489     specify all error codes that may be returned
 490
 491     @see osl_getVolumeInformation()
 492 */
 493 SAL_DLLPUBLIC oslFileError SAL_CALL osl_acquireVolumeDeviceHandle(
 494         oslVolumeDeviceHandle Handle );
 495
 496 /** Get the full qualified URL where a device is mounted to.
 497
 498     @param[in] Handle
 499     An oslVolumeDeviceHandle received by a call to osl_getVolumeInformation().
 500
 501     @param[out] ppustrDirectoryURL
 502     Receives the full qualified URL where the device is mounted to.
 503
 504     @retval osl_File_E_None on success
 505     @retval osl_File_E_NOMEM not enough memory for allocating structures
 506     @retval osl_File_E_INVAL the format of the parameters was not valid
 507     @retval osl_File_E_ACCES permission denied
 508     @retval osl_File_E_NXIO  no such device or address
 509     @retval osl_File_E_NODEV no such device
 510     @retval osl_File_E_NOENT no such file or directory
 511     @retval osl_File_E_FAULT bad address
 512     @retval osl_FilE_E_INTR function call was interrupted
 513     @retval osl_File_E_IO on I/O errors
 514     @retval osl_File_E_MULTIHOP multihop attempted
 515     @retval osl_File_E_NOLINK link has been severed
 516     @retval osl_File_E_EOVERFLOW value too large for defined data type
 517
 518     @see    osl_getVolumeInformation()
 519 */
 520 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeDeviceMountPath(
 521         oslVolumeDeviceHandle Handle, rtl_uString **ppustrDirectoryURL);
 522
 523 /**
 524    @defgroup volattrs Volume attributes
 525
 526    @{
 527  */
 528 #define osl_Volume_Attribute_Removeable            0x00000001
 529 #define osl_Volume_Attribute_Remote                0x00000002
 530 #define osl_Volume_Attribute_CompactDisc           0x00000004
 531 #define osl_Volume_Attribute_FixedDisk             0x00000008
 532 #define osl_Volume_Attribute_RAMDisk               0x00000010
 533 #define osl_Volume_Attribute_FloppyDisk            0x00000020
 534
 535 #define osl_Volume_Attribute_Case_Is_Preserved     0x00000040
 536 #define osl_Volume_Attribute_Case_Sensitive        0x00000080
 537
 538 /** @} */
 539
 540 /**
 541     @defgroup volinfoflags Flags specifying which fields to retrieve by osl_getVolumeInfo
 542
 543     @{
 544  */
 545
 546 #define osl_VolumeInfo_Mask_Attributes             0x00000001
 547 #define osl_VolumeInfo_Mask_TotalSpace             0x00000002
 548 #define osl_VolumeInfo_Mask_UsedSpace              0x00000004
 549 #define osl_VolumeInfo_Mask_FreeSpace              0x00000008
 550 #define osl_VolumeInfo_Mask_MaxNameLength          0x00000010
 551 #define osl_VolumeInfo_Mask_MaxPathLength          0x00000020
 552 #define osl_VolumeInfo_Mask_FileSystemName         0x00000040
 553 #define osl_VolumeInfo_Mask_DeviceHandle           0x00000080
 554 #define osl_VolumeInfo_Mask_FileSystemCaseHandling 0x00000100
 555
 556 /** @} */
 557
 558 /** Structure containing information about volumes
 559
 560     @see    osl_getVolumeInformation()
 561     @see    oslFileType
 562 */
 563
 564 typedef struct _oslVolumeInfo {
 565 /** Must be initialized with the size in bytes of the structure before
 566     passing it to any function */
 567     sal_uInt32      uStructSize;
 568 /** Determines which members of the structure contain valid data */
 569     sal_uInt32      uValidFields;
 570 /** Attributes of the volume (remote and/or removable) */
 571     sal_uInt32      uAttributes;
 572 /** Total available space on the volume for the current process/user */
 573     sal_uInt64      uTotalSpace;
 574 /** Used space on the volume for the current process/user */
 575     sal_uInt64      uUsedSpace;
 576 /** Free space on the volume for the current process/user */
 577     sal_uInt64      uFreeSpace;
 578 /** Maximum length of file name of a single item */
 579     sal_uInt32      uMaxNameLength;
 580 /** Maximum length of a full qualified path in system notation */
 581     sal_uInt32      uMaxPathLength;
 582 /** Points to a string that receives the name of the file system type. String
 583     should be set to zero before calling osl_getVolumeInformation and released
 584     after usage. */
 585     rtl_uString     *ustrFileSystemName;
 586 /** Pointer to handle the receives underlying device. Handle should be set to
 587     zero before calling osl_getVolumeInformation */
 588     oslVolumeDeviceHandle   *pDeviceHandle;
 589 } oslVolumeInfo;
 590
 591 /** Retrieve information about a volume.
 592
 593     Retrieves information about a volume. A volume can either be a mount point, a network
 594     resource or a drive depending on Operating System and File System. Before calling this
 595     function osl_getFileStatus() should be called to determine if the type is
 596     osl_file_Type_Volume.
 597
 598     @param[in] pustrDirectoryURL
 599     Full qualified URL of the volume
 600
 601     @param[out] pInfo
 602     On success it receives information about the volume.
 603
 604     @param[in] uFieldMask
 605     Specifies which members of the structure should be filled
 606
 607     @retval osl_File_E_None on success
 608     @retval osl_File_E_NOMEM not enough memory for allocating structures
 609     @retval osl_File_E_INVAL the format of the parameters was not valid
 610     @retval osl_File_E_NOTDIR not a directory
 611     @retval osl_File_E_NAMETOOLONG file name too long
 612     @retval osl_File_E_NOENT no such file or directory
 613     @retval osl_File_E_ACCES permission denied
 614     @retval osl_File_E_LOOP too many symbolic links encountered
 615     @retval ols_File_E_FAULT Bad address
 616     @retval osl_File_E_IO on I/O errors
 617     @retval osl_File_E_NOSYS function not implemented
 618     @retval osl_File_E_MULTIHOP multihop attempted
 619     @retval osl_File_E_NOLINK link has been severed
 620     @retval osl_File_E_INTR function call was interrupted
 621
 622     @see    osl_getFileStatus()
 623     @see    oslVolumeInfo
 624 */
 625 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getVolumeInformation(
 626     rtl_uString *pustrDirectoryURL,
 627     oslVolumeInfo *pInfo,
 628     sal_uInt32 uFieldMask );
 629
 630 typedef void *oslFileHandle;
 631
 632 /* Open flags */
 633
 634 #define osl_File_OpenFlag_Read      0x00000001
 635 #define osl_File_OpenFlag_Write     0x00000002
 636 #define osl_File_OpenFlag_Create    0x00000004
 637 #define osl_File_OpenFlag_NoLock    0x00000008
 638 /* larger bit-fields reserved for internal use cf. detail/file.h */
 639
 640 /** Open a regular file.
 641
 642     Open a file. Only regular files can be opened.
 643
 644     @param[in] pustrFileURL
 645     The full qualified URL of the file to open.
 646
 647     @param[out] pHandle
 648     On success it receives a handle to the open file.
 649
 650     @param[in] uFlags
 651     Specifies the open mode.
 652
 653     On Android, if the file path is below the /assets folder, the file
 654     exists only as a hopefully uncompressed element inside the app
 655     package (.apk), which has been mapped into memory as a whole by
 656     the LibreOffice Android bootstrapping code. So files "opened" from
 657     there aren't actually files in the OS sense.
 658
 659     @retval osl_File_E_None on success
 660     @retval osl_File_E_NOMEM not enough memory for allocating structures
 661     @retval osl_File_E_INVAL the format of the parameters was not valid
 662     @retval osl_File_E_NAMETOOLONG pathname was too long
 663     @retval osl_File_E_NOENT no such file or directory
 664     @retval osl_File_E_ACCES permission denied
 665     @retval osl_File_E_AGAIN a write lock could not be established
 666     @retval osl_File_E_NOTDIR not a directory
 667     @retval osl_File_E_NXIO no such device or address
 668     @retval osl_File_E_NODEV no such device
 669     @retval osl_File_E_ROFS read-only file system
 670     @retval osl_File_E_TXTBSY text file busy
 671     @retval osl_File_E_FAULT bad address
 672     @retval osl_File_E_LOOP too many symbolic links encountered
 673     @retval osl_File_E_NOSPC no space left on device
 674     @retval osl_File_E_ISDIR is a directory
 675     @retval osl_File_E_MFILE too many open files used by the process
 676     @retval osl_File_E_NFILE too many open files in the system
 677     @retval osl_File_E_DQUOT quota exceeded
 678     @retval osl_File_E_EXIST file exists
 679     @retval osl_FilE_E_INTR function call was interrupted
 680     @retval osl_File_E_IO on I/O errors
 681     @retval osl_File_E_MULTIHOP multihop attempted
 682     @retval osl_File_E_NOLINK link has been severed
 683     @retval osl_File_E_EOVERFLOW value too large for defined data type
 684
 685     @see osl_closeFile()
 686     @see osl_setFilePos()
 687     @see osl_getFilePos()
 688     @see osl_readFile()
 689     @see osl_writeFile()
 690     @see osl_setFileSize()
 691     @see osl_getFileSize()
 692 */
 693 SAL_DLLPUBLIC oslFileError SAL_CALL osl_openFile(
 694         rtl_uString *pustrFileURL, oslFileHandle *pHandle, sal_uInt32 uFlags );
 695
 696 #define osl_Pos_Absolut 1
 697 #define osl_Pos_Current 2
 698 #define osl_Pos_End     3
 699
 700 /** Set the internal position pointer of an open file.
 701
 702     @param[in] Handle
 703     Handle to a file received by a previous call to osl_openFile().
 704
 705     @param[in] uHow
 706     How to calculate the offset - osl_Pos_Absolut means start at the
 707     beginning of the file, osl_Pos_Current means offset from the current
 708     seek position and osl_Pos_End means the offset will be negative and
 709     the position will be calculated backwards from the end of the file by
 710     the offset provided.
 711
 712     @param[in] uPos
 713     Seek offset, depending on uHow. If uHow is osl_Pos_End then the value must be negative.
 714
 715     @retval osl_File_E_None on success
 716     @retval osl_File_E_INVAL the format of the parameters was not valid
 717         (e.g. if uHow is osl_Pos_End then must be negative)
 718     @retval osl_File_E_OVERFLOW the resulting file offset would be a
 719         value which cannot be represented correctly for regular files
 720
 721     @see    osl_openFile()
 722     @see    osl_getFilePos()
 723 */
 724 SAL_WARN_UNUSED_RESULT SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFilePos(
 725         oslFileHandle Handle, sal_uInt32 uHow, sal_Int64 uPos );
 726
 727 /** Retrieve the current position of the internal pointer of an open file.
 728
 729     @param[in] Handle
 730     Handle to a file received by a previous call to osl_openFile().
 731
 732     @param[out] pPos
 733     On success receives the current position of the file pointer.
 734
 735     @retval osl_File_E_None on success
 736     @retval osl_File_E_INVAL the format of the parameters was not valid
 737     @retval osl_File_E_OVERFLOW the resulting file offset would be a value
 738         which cannot be represented correctly for regular files
 739
 740     @see osl_openFile()
 741     @see osl_setFilePos()
 742     @see osl_readFile()
 743     @see osl_writeFile()
 744 */
 745 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFilePos(
 746         oslFileHandle Handle, sal_uInt64 *pPos );
 747
 748 /** Set the file size of an open file.
 749
 750     Sets the file size of an open file. The file can be truncated or enlarged by the function.
 751     The position of the file pointer is not affeced by this function.
 752
 753     @param[in] Handle
 754     Handle to a file received by a previous call to osl_openFile().
 755
 756     @param[in] uSize
 757     New size in bytes.
 758
 759     @retval osl_File_E_None on success
 760     @retval osl_File_E_INVAL the format of the parameters was not valid
 761     @retval osl_File_E_OVERFLOW the resulting file offset would be a value
 762         which cannot be represented correctly for regular files
 763
 764     @see osl_openFile()
 765     @see osl_setFilePos()
 766     @see osl_getFileStatus()
 767     @see osl_getFileSize()
 768 */
 769 SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileSize(
 770         oslFileHandle Handle, sal_uInt64 uSize );
 771
 772 /** Get the file size of an open file.
 773
 774     Gets the file size of an open file.
 775     The position of the file pointer is not affeced by this function.
 776
 777     @param[in] Handle
 778     Handle to a file received by a previous call to osl_openFile().
 779
 780     @param[out] pSize
 781     Current size in bytes.
 782
 783     @retval osl_File_E_None on success
 784     @retval osl_File_E_INVAL the format of the parameters was not valid
 785     @retval osl_File_E_OVERFLOW the resulting file offset would be a value
 786         which cannot be represented correctly for regular files
 787
 788     @see osl_openFile()
 789     @see osl_setFilePos()
 790     @see osl_getFileStatus()
 791 */
 792 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileSize(
 793         oslFileHandle Handle, sal_uInt64 *pSize );
 794
 795 /** Indicate that the file can be accessed randomly (i.e. there is no sequential
 796     reading). Basically it means that the first byte of every page in the
 797     file-mapping will be read.
 798
 799     @since UDK 3.2.10
 800  */
 801 #define osl_File_MapFlag_RandomAccess ((sal_uInt32)(0x1))
 802
 803 /** Map flag denoting that the mapped address space will be accessed by the
 804     process soon (and it is advantageous for the operating system to already
 805     start paging in the data).
 806
 807     @attention As this assumes that madvise() with the WILLREAD flag is
 808     asynchronous (which is I'm afraid an incorrect assumption), Linux systems
 809     will ignore this flag.
 810
 811     @since UDK 3.2.12
 812 */
 813 #define osl_File_MapFlag_WillNeed ((sal_uInt32)(0x2))
 814
 815 /** Map a shared file into memory.
 816
 817     Files can be mapped into memory to allow multiple processes to use
 818     this memory-mapped file to share data.
 819
 820     On Android, if the Handle refers to a file that is actually inside
 821     the app package (.apk zip archive), no new mapping is created,
 822     just a pointer to the file inside the already mapped .apk is
 823     returned.
 824
 825     @param[in] Handle       Handle of the file to be mapped.
 826     @param[in,out] ppAddr   Memory address of the mapped file
 827     @param[in] uLength      Amount to map of the file from the offset
 828     @param[in] uOffset      Offset into the file to map
 829     @param[in] uFlags       osl_File_MapFlag_RandomAccess or
 830                             osl_File_MapFlag_WillNeed
 831
 832     @retval osl_File_E_None on success
 833     @retval osl_File_E_INVAL invalid file handle, on Unix systems also
 834                 can mean that the address, length of the file or the
 835                 file offset are too large or not aligned on a page
 836                 boundary; on Linux can also mean after Linux 2.6.12
 837                 that the length was set to 0 (illogical).
 838     @retval osl_File_E_OVERFLOW requested mapping size too large,
 839                 or the file offset was too large
 840     @retval osl_File_E_ACCES file descriptor to non-regular file, or
 841                 file descriptor not open for reading, or the file
 842                 descriptor is not open in read/write mode
 843     @retval osl_File_E_AGAIN file has been locked, or too much memory
 844                 has been locked
 845     @retval osl_File_E_NODEV underlying filesystem of specified file
 846                 does not support memory mapping
 847     @retval osl_File_E_TXTBSY on Linux means that writing to the mapped
 848                 file is denied, but the file descriptor points to a file
 849                 open for writing
 850     @retval osl_File_E_NOMEM process's maximum number of mappings have
 851                 been exceeded
 852
 853     @since UDK 3.2.10
 854 */
 855 SAL_DLLPUBLIC oslFileError SAL_CALL osl_mapFile (
 856   oslFileHandle Handle,
 857   void**        ppAddr,
 858   sal_uInt64    uLength,
 859   sal_uInt64    uOffset,
 860   sal_uInt32    uFlags
 861 );
 862
 863
 864 #ifndef ANDROID
 865
 866 /** Unmap a shared file from memory.
 867
 868     This function just won't work on Android in general where for
 869     (uncompressed) files inside the .apk, per SDK conventions in the
 870     /assets folder, osl_mapFile() returns a pointer to the file inside
 871     the already by LibreOffice Android-specific bootstrapping code
 872     mmapped .apk archive. We can't go and randomly munmap part of the
 873     .apk archive. So this function is not present on Android.
 874
 875     @since UDK 3.2.10
 876 */
 877 SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapFile (
 878   void*      pAddr,
 879   sal_uInt64 uLength
 880 );
 881
 882 #endif
 883
 884 /** Unmap a file segment from memory.
 885
 886     Like osl_unmapFile(), but takes also the oslFileHandle argument
 887     passed to osl_mapFile() when creating this mapping.
 888
 889     On Android, for files below /assets, i.e. located inside the app
 890     archive (.apk), this won't actually unmap anything; all the .apk
 891     stays mapped.
 892
 893     @since UDK 3.6
 894 */
 895 SAL_DLLPUBLIC oslFileError SAL_CALL osl_unmapMappedFile (
 896   oslFileHandle Handle,
 897   void*      pAddr,
 898   sal_uInt64 uLength
 899 );
 900
 901 /** Read a number of bytes from a file.
 902
 903     Reads a number of bytes from a file. The internal file pointer is
 904     increased by the number of bytes read.
 905
 906     @param[in] Handle
 907     Handle to a file received by a previous call to osl_openFile().
 908
 909     @param[out] pBuffer
 910     Points to a buffer which receives data. The buffer must be large enough
 911     to hold uBytesRequested bytes.
 912
 913     @param[in] uBytesRequested
 914     Number of bytes which should be retrieved.
 915
 916     @param[out] pBytesRead
 917     On success the number of bytes which have actually been retrieved.
 918
 919     @retval osl_File_E_None on success
 920     @retval osl_File_E_INVAL the format of the parameters was not valid
 921     @retval osl_File_E_INTR function call was interrupted
 922     @retval osl_File_E_IO on I/O errors
 923     @retval osl_File_E_ISDIR is a directory
 924     @retval osl_File_E_BADF bad file
 925     @retval osl_File_E_FAULT bad address
 926     @retval osl_File_E_AGAIN operation would block
 927     @retval osl_File_E_NOLINK link has been severed
 928
 929     @see osl_openFile()
 930     @see osl_writeFile()
 931     @see osl_readLine()
 932     @see osl_setFilePos()
 933 */
 934 SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFile(
 935         oslFileHandle Handle, void *pBuffer, sal_uInt64 uBytesRequested, sal_uInt64 *pBytesRead );
 936
 937 /** Test if the end of a file is reached.
 938
 939     @param[in] Handle
 940     Handle to a file received by a previous call to osl_openFile().
 941
 942     @param[out] pIsEOF
 943     Points to a variable that receives the end-of-file status.
 944
 945     @retval osl_File_E_None on success
 946     @retval osl_File_E_INVAL the format of the parameters was not valid
 947     @retval osl_File_E_INTR function call was interrupted
 948     @retval osl_File_E_IO on I/O errors
 949     @retval osl_File_E_ISDIR is a directory
 950     @retval osl_File_E_BADF bad file
 951     @retval osl_File_E_FAULT bad address
 952     @retval osl_File_E_AGAIN operation would block
 953     @retval osl_File_E_NOLINK link has been severed
 954
 955     @see osl_openFile()
 956     @see osl_readFile()
 957     @see osl_readLine()
 958     @see osl_setFilePos()
 959 */
 960 SAL_DLLPUBLIC oslFileError SAL_CALL osl_isEndOfFile(
 961         oslFileHandle Handle, sal_Bool *pIsEOF );
 962
 963 /** Resets the list of paths and associated permissions for osl
 964
 965     @param[in] pustrFileURLs
 966     Contains a ':' delimited list of control strings and paths.
 967     Control segments are a short path that refers to the following
 968     segments and contain either:
 969
 970     r: read-only paths follow (the default)
 971     w: read & write paths follow
 972     x: executable paths follow
 973
 974     Any real paths (ie. having resolved all symlinks)
 975     accessed outside of these paths will cause an
 976     osl_File_E_ACCESS error in the relevant method calls.
 977
 978     This method is Unix specific.
 979
 980     @see osl_isForbiddenPath
 981
 982     @since LibreOffice 7.7
 983 */
 984 SAL_DLLPUBLIC void SAL_CALL osl_setAllowedPaths(
 985     rtl_uString *pustrFileURLs
 986     );
 987
 988 /**
 989    Determine if the passed in path is not contained inside
 990    the allowed paths, or if no allowed paths are set it
 991    will not forbid any access.
 992
 993    @param[in] pustrFileURL
 994    A URL (or path) that we want to check if it is forbidden
 995    to access.
 996
 997    @param[in] nFlags
 998    Flags to determine what type of access is requested,
 999    osl_File_OpenFlag_Read | Write, or 0x80 for 'execute'.
1000
1001    This method is Unix specific.
1002
1003    @see osl_setAllowedPaths
1004
1005    @since LibreOffice 7.7
1006  */
1007 SAL_DLLPUBLIC sal_Bool SAL_CALL osl_isForbiddenPath(
1008     rtl_uString *pustrFileURL, int nFlags
1009     );
1010
1011 /** Write a number of bytes to a file.
1012
1013     Writes a number of bytes to a file.
1014     The internal file pointer is increased by the number of bytes read.
1015
1016     @param[in] Handle
1017     Handle to a file received by a previous call to osl_openFile().
1018
1019     @param[in] pBuffer
1020     Points to a buffer which contains the data.
1021
1022     @param[in] uBytesToWrite
1023     Number of bytes which should be written.
1024
1025     @param[out] pBytesWritten
1026     On success the number of bytes which have actually been written.
1027
1028     @retval osl_File_E_None on success
1029     @retval osl_File_E_INVAL the format of the parameters was not valid
1030     @retval osl_File_E_FBIG file too large
1031     @retval osl_File_E_DQUOT quota exceeded
1032     @retval osl_File_E_AGAIN operation would block
1033     @retval osl_File_E_BADF bad file
1034     @retval osl_File_E_FAULT bad address
1035     @retval osl_File_E_INTR function call was interrupted
1036     @retval osl_File_E_IO on I/O errors
1037     @retval osl_File_E_NOLCK no record locks available
1038     @retval osl_File_E_NOLINK link has been severed
1039     @retval osl_File_E_NOSPC no space left on device
1040     @retval osl_File_E_NXIO no such device or address
1041
1042     @see osl_openFile()
1043     @see osl_readFile()
1044     @see osl_setFilePos()
1045 */
1046 SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFile(
1047         oslFileHandle Handle, const void *pBuffer, sal_uInt64 uBytesToWrite, sal_uInt64 *pBytesWritten );
1048
1049 /** Read a number of bytes from a specified offset in a file.
1050
1051     The current position of the internal file pointer may or may not be changed.
1052
1053     @param[in] Handle
1054     Handle to a file received by a previous call to osl_openFile().
1055
1056     @param[in] uOffset
1057     Offset position from start of file where read starts
1058
1059     @param[out] pBuffer
1060     Points to a buffer which receives data. The buffer must be large enough
1061     to hold uBytesRequested bytes.
1062
1063     @param[in] uBytesRequested
1064     Number of bytes which should be retrieved.
1065
1066     @param[out] pBytesRead
1067     On success the number of bytes which have actually been retrieved.
1068
1069     @retval osl_File_E_None on success
1070     @retval osl_File_E_INVAL the format of the parameters was not valid
1071     @retval osl_File_E_INTR function call was interrupted
1072     @retval osl_File_E_IO on I/O errors
1073     @retval osl_File_E_ISDIR is a directory
1074     @retval osl_File_E_BADF bad file
1075     @retval osl_File_E_FAULT bad address
1076     @retval osl_File_E_AGAIN operation would block
1077     @retval osl_File_E_NOLINK link has been severed
1078     @since UDK 3.2.10
1079  */
1080 SAL_DLLPUBLIC oslFileError SAL_CALL osl_readFileAt(
1081   oslFileHandle Handle,
1082   sal_uInt64    uOffset,
1083   void*         pBuffer,
1084   sal_uInt64    uBytesRequested,
1085   sal_uInt64*   pBytesRead
1086 );
1087
1088 /** Write a number of bytes to a specified offset in a file.
1089
1090     The current position of the internal file pointer may or may not be changed.
1091
1092     @param[in] Handle
1093     Handle to a file received by a previous call to osl_openFile().
1094
1095     @param[in] uOffset
1096     Position of file to write into.
1097
1098     @param[in] pBuffer
1099     Points to a buffer which contains the data.
1100
1101     @param[in] uBytesToWrite
1102     Number of bytes which should be written.
1103
1104     @param[out] pBytesWritten
1105     On success the number of bytes which have actually been written.
1106
1107     @retval osl_File_E_None on success
1108     @retval osl_File_E_INVAL the format of the parameters was not valid
1109     @retval osl_File_E_FBIG file too large
1110     @retval osl_File_E_DQUOT quota exceeded
1111     @retval osl_File_E_AGAIN operation would block
1112     @retval osl_File_E_BADF bad file
1113     @retval osl_File_E_FAULT bad address
1114     @retval osl_File_E_INTR function call was interrupted
1115     @retval osl_File_E_IO on I/O errors
1116     @retval osl_File_E_NOLCK no record locks available
1117     @retval osl_File_E_NOLINK link has been severed
1118     @retval osl_File_E_NOSPC no space left on device
1119     @retval osl_File_E_NXIO no such device or address
1120     @since UDK 3.2.10
1121 */
1122 SAL_DLLPUBLIC oslFileError SAL_CALL osl_writeFileAt(
1123   oslFileHandle Handle,
1124   sal_uInt64    uOffset,
1125   const void*   pBuffer,
1126   sal_uInt64    uBytesToWrite,
1127   sal_uInt64*   pBytesWritten
1128 );
1129
1130 /** Read a line from a file.
1131
1132     Reads a line from a file. The new line delimiter is NOT returned!
1133
1134     @param[in] Handle
1135     Handle to a file received by a previous call to osl_openFile().
1136
1137     @param[in,out] ppSequence
1138     A pointer pointer to a sal_Sequence that will hold the line read on success.
1139
1140     @retval osl_File_E_None on success
1141     @retval osl_File_E_INVAL the format of the parameters was not valid
1142     @retval osl_File_E_INTR function call was interrupted
1143     @retval osl_File_E_IO on I/O errors
1144     @retval osl_File_E_ISDIR is a directory
1145     @retval osl_File_E_BADF bad file
1146     @retval osl_File_E_FAULT bad address
1147     @retval osl_File_E_AGAIN operation would block
1148     @retval osl_File_E_NOLINK link has been severed
1149
1150     @see osl_openFile()
1151     @see osl_readFile()
1152     @see osl_writeFile()
1153     @see osl_setFilePos()
1154 */
1155 SAL_DLLPUBLIC oslFileError SAL_CALL osl_readLine(
1156         oslFileHandle Handle, sal_Sequence** ppSequence );
1157
1158 /** Synchronize the memory representation of a file with that on the physical medium.
1159
1160      The function ensures that all modified data and attributes of the file associated with
1161      the given file handle have been written to the physical medium.
1162      In case the hard disk has a write cache enabled, the data may not really be on
1163      permanent storage when osl_syncFile returns.
1164
1165       @param Handle
1166       [in] Handle to a file received by a previous call to osl_openFile().
1167
1168       @retval osl_File_E_None On success
1169       @retval osl_File_E_INVAL The value of the input parameter is invalid
1170       @retval osl_File_E_BADF The file associated with the given file handle is not open for writing
1171       @retval osl_File_E_IO An I/O error occurred
1172       @retval osl_File_E_NOSPC There is no enough space on the target device
1173       @retval osl_File_E_ROFS The file associated with the given file handle is located on a read only file system
1174       @retval osl_File_E_TIMEDOUT A remote connection timed out. This may happen when a file is on a remote location
1175
1176       @see osl_openFile()
1177       @see osl_writeFile()
1178 */
1179 SAL_DLLPUBLIC oslFileError SAL_CALL osl_syncFile( oslFileHandle Handle );
1180
1181 /** Close an open file.
1182
1183     @param[in] Handle
1184     Handle to a file received by a previous call to osl_openFile().
1185
1186     @retval osl_File_E_None on success
1187     @retval osl_File_E_INVAL the format of the parameters was not valid
1188     @retval osl_File_E_BADF Bad file
1189     @retval osl_File_E_INTR function call was interrupted
1190     @retval osl_File_E_NOLINK link has been severed
1191     @retval osl_File_E_NOSPC no space left on device
1192     @retval osl_File_E_IO on I/O errors
1193
1194     @see osl_openFile()
1195 */
1196 SAL_DLLPUBLIC oslFileError SAL_CALL osl_closeFile( oslFileHandle Handle );
1197
1198 /** Create a directory.
1199
1200     @param[in] pustrDirectoryURL
1201     Full qualified URL of the directory to create.
1202
1203     @retval osl_File_E_None on success
1204     @retval osl_File_E_INVAL the format of the parameters was not valid
1205     @retval osl_File_E_NOMEM not enough memory for allocating structures
1206     @retval osl_File_E_EXIST file exists
1207     @retval osl_File_E_ACCES permission denied
1208     @retval osl_File_E_NAMETOOLONG file name too long
1209     @retval osl_File_E_NOENT no such file or directory
1210     @retval osl_File_E_NOTDIR not a directory
1211     @retval osl_File_E_ROFS read-only file system
1212     @retval osl_File_E_NOSPC no space left on device
1213     @retval osl_File_E_DQUOT quota exceeded
1214     @retval osl_File_E_LOOP too many symbolic links encountered
1215     @retval osl_File_E_FAULT bad address
1216     @retval osl_FileE_IO on I/O errors
1217     @retval osl_File_E_MLINK too many links
1218     @retval osl_File_E_MULTIHOP multihop attempted
1219     @retval osl_File_E_NOLINK link has been severed
1220
1221     @see osl_removeDirectory()
1222 */
1223 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectory( rtl_uString* pustrDirectoryURL );
1224
1225 /** Create a directory, passing flags.
1226
1227     @param url
1228     File URL of the directory to create.
1229
1230     @param flags
1231     A combination of the same osl_File_OpenFlag_*s used by osl_openFile,
1232     except that osl_File_OpenFlag_Create is implied and ignored.  Support for
1233     the various flags can differ across operating systems.
1234
1235     @see osl_createDirectory()
1236
1237     @since LibreOffice 4.3
1238 */
1239 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryWithFlags(
1240     rtl_uString * url, sal_uInt32 flags);
1241
1242 /** Remove an empty directory.
1243
1244     @param[in] pustrDirectoryURL
1245     Full qualified URL of the directory.
1246
1247     @retval osl_File_E_None on success
1248     @retval osl_File_E_INVAL the format of the parameters was not valid
1249     @retval osl_File_E_NOMEM not enough memory for allocating structures
1250     @retval osl_File_E_PERM operation not permitted
1251     @retval osl_File_E_ACCES permission denied
1252     @retval osl_File_E_NOENT no such file or directory
1253     @retval osl_File_E_NOTDIR not a directory
1254     @retval osl_File_E_NOTEMPTY directory not empty
1255     @retval osl_File_E_FAULT bad address
1256     @retval osl_File_E_NAMETOOLONG file name too long
1257     @retval osl_File_E_BUSY device or resource busy
1258     @retval osl_File_E_ROFS read-only file system
1259     @retval osl_File_E_LOOP too many symbolic links encountered
1260     @retval osl_File_E_EXIST file exists
1261     @retval osl_File_E_IO on I/O errors
1262     @retval osl_File_E_MULTIHOP multihop attempted
1263     @retval osl_File_E_NOLINK link has been severed
1264
1265     @see osl_createDirectory()
1266 */
1267 SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeDirectory( rtl_uString* pustrDirectoryURL );
1268
1269 /** Function pointer representing a function that will be called by osl_createDirectoryPath
1270     if a directory has been created.
1271
1272     To avoid unpredictable results the callee must not access the directory whose
1273     creation is just notified.
1274
1275     @param pData
1276     [in] User specified data given in osl_createDirectoryPath.
1277
1278     @param aDirectoryUrl
1279     [in] The absolute file URL of the directory that was just created by
1280     osl_createDirectoryPath.
1281
1282     @see osl_createDirectoryPath
1283 */
1284 typedef void (SAL_CALL *oslDirectoryCreationCallbackFunc)(void* pData, rtl_uString* aDirectoryUrl);
1285
1286 /** Create a directory path.
1287
1288     The osl_createDirectoryPath function creates a specified directory path.
1289     All nonexisting sub directories will be created.
1290
1291     @attention PLEASE NOTE You cannot rely on getting the error code
1292     osl_File_E_EXIST for existing directories. Programming against this error
1293     code is in general a strong indication of a wrong usage of osl_createDirectoryPath.
1294
1295     @param aDirectoryUrl
1296     [in] The absolute file URL of the directory path to create.
1297     A relative file URL will not be accepted.
1298
1299     @param aDirectoryCreationCallbackFunc
1300     [in] Pointer to a function that will be called synchronously
1301     for each sub directory that was created. The value of this
1302     parameter may be NULL, in this case notifications will not be
1303     sent.
1304
1305     @param pData
1306     [in] User specified data to be passed to the directory creation
1307     callback function. The value of this parameter may be arbitrary
1308     and will not be interpreted by osl_createDirectoryPath.
1309
1310     @retval osl_File_E_None On success
1311     @retval osl_File_E_INVAL The format of the parameters was not valid
1312     @retval osl_File_E_ACCES Permission denied
1313     @retval osl_File_E_EXIST The final node of the specified directory path already exist
1314     @retval osl_File_E_NAMETOOLONG The name of the specified directory path exceeds the maximum allowed length
1315     @retval osl_File_E_NOTDIR A component of the specified directory path already exist as file in any part of the directory path
1316     @retval osl_File_E_ROFS Read-only file system
1317     @retval osl_File_E_NOSPC No space left on device
1318     @retval osl_File_E_DQUOT Quota exceeded
1319     @retval osl_File_E_FAULT Bad address
1320     @retval osl_File_E_IO I/O error
1321     @retval osl_File_E_LOOP Too many symbolic links encountered
1322     @retval osl_File_E_NOLINK Link has been severed
1323     @retval osl_File_E_invalidError An unknown error occurred
1324
1325     @see oslDirectoryCreationFunc
1326     @see oslFileError
1327     @see osl_createDirectory
1328 */
1329 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createDirectoryPath(
1330     rtl_uString* aDirectoryUrl,
1331     oslDirectoryCreationCallbackFunc aDirectoryCreationCallbackFunc,
1332     void* pData);
1333
1334 /** Remove a regular file.
1335
1336     @param[in] pustrFileURL
1337     Full qualified URL of the file to remove.
1338
1339     @retval osl_File_E_None on success
1340     @retval osl_File_E_INVAL the format of the parameters was not valid
1341     @retval osl_File_E_NOMEM not enough memory for allocating structures
1342     @retval osl_File_E_ACCES permission denied
1343     @retval osl_File_E_PERM operation not permitted
1344     @retval osl_File_E_NAMETOOLONG file name too long
1345     @retval osl_File_E_NOENT no such file or directory
1346     @retval osl_File_E_ISDIR is a directory
1347     @retval osl_File_E_ROFS read-only file system
1348     @retval osl_File_E_FAULT bad address
1349     @retval osl_File_E_LOOP too many symbolic links encountered
1350     @retval osl_File_E_IO on I/O errors
1351     @retval osl_File_E_BUSY device or resource busy
1352     @retval osl_File_E_INTR function call was interrupted
1353     @retval osl_File_E_MULTIHOP multihop attempted
1354     @retval osl_File_E_NOLINK link has been severed
1355     @retval osl_File_E_TXTBSY text file busy
1356
1357     @see osl_openFile()
1358 */
1359 SAL_DLLPUBLIC oslFileError SAL_CALL osl_removeFile(
1360         rtl_uString* pustrFileURL );
1361
1362 /** Copy a file to a new destination.
1363
1364     Copies a file to a new destination. Copies only files not directories.
1365     No assumptions should be made about preserving attributes or file time.
1366
1367     @param[in] pustrSourceFileURL
1368     Full qualified URL of the source file.
1369
1370     @param[in] pustrDestFileURL
1371     Full qualified URL of the destination file. A directory is NOT a valid destination file!
1372
1373     @retval osl_File_E_None on success
1374     @retval osl_File_E_INVAL the format of the parameters was not valid
1375     @retval osl_File_E_NOMEM not enough memory for allocating structures
1376     @retval osl_File_E_ACCES permission denied
1377     @retval osl_File_E_PERM operation not permitted
1378     @retval osl_File_E_NAMETOOLONG file name too long
1379     @retval osl_File_E_NOENT no such file or directory
1380     @retval osl_File_E_ISDIR is a directory
1381     @retval osl_File_E_ROFS read-only file system
1382     @retval osl_File_E_BUSY if the implementation internally requires resources that are
1383         (temporarily) unavailable (added with LibreOffice 4.4)
1384
1385     @see    osl_moveFile()
1386     @see    osl_removeFile()
1387 */
1388 SAL_DLLPUBLIC oslFileError SAL_CALL osl_copyFile(
1389         rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );
1390
1391 /** Move a file or directory to a new destination or renames it.
1392
1393     Moves a file or directory to a new destination or renames it.
1394     File time and attributes are preserved.
1395
1396     @param[in] pustrSourceFileURL
1397     Full qualified URL of the source file.
1398
1399     @param[in] pustrDestFileURL
1400     Full qualified URL of the destination file. An existing directory is NOT a valid destination !
1401
1402     @retval osl_File_E_None on success
1403     @retval osl_File_E_INVAL the format of the parameters was not valid
1404     @retval osl_File_E_NOMEM not enough memory for allocating structures
1405     @retval osl_File_E_ACCES permission denied
1406     @retval osl_File_E_PERM operation not permitted
1407     @retval osl_File_E_NAMETOOLONG file name too long
1408     @retval osl_File_E_NOENT no such file or directory
1409     @retval osl_File_E_ROFS read-only file system
1410     @retval osl_File_E_BUSY if the implementation internally requires resources that are
1411         (temporarily) unavailable (added with LibreOffice 4.4)
1412
1413     @see osl_copyFile()
1414 */
1415 SAL_DLLPUBLIC oslFileError SAL_CALL osl_moveFile(
1416         rtl_uString* pustrSourceFileURL, rtl_uString *pustrDestFileURL );
1417
1418 /** Determine a valid unused canonical name for a requested name.
1419
1420     Determines a valid unused canonical name for a requested name.
1421     Depending on the Operating System and the File System the illegal characters are replaced by valid ones.
1422     If a file or directory with the requested name already exists a new name is generated following
1423     the common rules on the actual Operating System and File System.
1424
1425     @param[in] pustrRequestedURL
1426     Requested name of a file or directory.
1427
1428     @param[out] ppustrValidURL
1429     On success receives a name which is unused and valid on the actual Operating System and
1430     File System.
1431
1432     @retval osl_File_E_None on success
1433     @retval osl_File_E_INVAL the format of the parameters was not valid
1434
1435     @see osl_getFileStatus()
1436 */
1437 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getCanonicalName(
1438         rtl_uString *pustrRequestedURL, rtl_uString **ppustrValidURL);
1439
1440 /** Convert a path relative to a given directory into an full qualified file URL.
1441
1442     Convert a path relative to a given directory into an full qualified file URL.
1443     The function resolves symbolic links if possible and path ellipses, so on success
1444     the resulting absolute path is fully resolved.
1445
1446     @param[in] pustrBaseDirectoryURL
1447     Base directory URL to which the relative path is related to.
1448
1449     @param[in] pustrRelativeFileURL
1450     A URL of a file or directory relative to the directory path specified by pustrBaseDirectoryURL
1451     or an absolute path.
1452     If pustrRelativeFileURL denotes an absolute path pustrBaseDirectoryURL will be ignored.
1453
1454     @param[out] ppustrAbsoluteFileURL
1455     On success it receives the full qualified absolute file URL.
1456
1457     @retval osl_File_E_None on success
1458     @retval osl_File_E_INVAL the format of the parameters was not valid
1459     @retval osl_File_E_NOMEM not enough memory for allocating structures
1460     @retval osl_File_E_NOTDIR not a directory
1461     @retval osl_File_E_ACCES permission denied
1462     @retval osl_File_E_NOENT no such file or directory
1463     @retval osl_File_E_NAMETOOLONG file name too long
1464     @retval osl_File_E_OVERFLOW value too large for defined data type
1465     @retval osl_File_E_FAULT bad address
1466     @retval osl_File_E_INTR function call was interrupted
1467     @retval osl_File_E_LOOP too many symbolic links encountered
1468     @retval osl_File_E_MULTIHOP multihop attempted
1469     @retval osl_File_E_NOLINK link has been severed
1470
1471     @see    osl_getFileStatus()
1472 */
1473 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getAbsoluteFileURL(
1474     rtl_uString* pustrBaseDirectoryURL,
1475     rtl_uString *pustrRelativeFileURL,
1476     rtl_uString **ppustrAbsoluteFileURL );
1477
1478 /** Convert a system dependent path into a file URL.
1479
1480     @param[in] pustrSystemPath
1481     A System dependent path of a file or directory.
1482
1483     @param[out] ppustrFileURL
1484     On success it receives the file URL.
1485
1486     @retval osl_File_E_None on success
1487     @retval osl_File_E_INVAL the format of the parameters was not valid
1488
1489     @see osl_getSystemPathFromFileURL()
1490 */
1491 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getFileURLFromSystemPath(
1492         rtl_uString *pustrSystemPath, rtl_uString **ppustrFileURL);
1493
1494 /** Search a full qualified system path or a file URL.
1495
1496     @param[in] pustrFileName
1497     A system dependent path, a file URL, a file or relative directory.
1498
1499     @param[in] pustrSearchPath
1500     @parblock
1501         A list of system paths, in which a given file has to be searched. The Notation of a path
1502         list is system dependent, e.g. on UNIX system "/usr/bin:/bin" and on Windows "C:\BIN;C:\BATCH".
1503         These paths are only for the search of a file or a relative path, otherwise it will be ignored.
1504         If pustrSearchPath is NULL or while using the search path the search failed, the function
1505         searches for a matching file in all system directories and in the directories listed in the PATH
1506         environment variable.
1507
1508         The value of an environment variable should be used (e.g.
1509         LD_LIBRARY_PATH) if the caller is not aware of the Operating System and so doesn't know which
1510         path list delimiter to use.
1511     @endparblock
1512
1513     @param[out] ppustrFileURL
1514     On success it receives the full qualified file URL.
1515
1516     @retval osl_File_E_None on success
1517     @retval osl_File_E_INVAL the format of the parameters was not valid
1518     @retval osl_File_E_NOTDIR not a directory
1519     @retval osl_File_E_NOENT no such file or directory not found
1520
1521     @see osl_getFileURLFromSystemPath()
1522     @see osl_getSystemPathFromFileURL()
1523 */
1524 SAL_DLLPUBLIC oslFileError SAL_CALL osl_searchFileURL(
1525         rtl_uString *pustrFileName, rtl_uString *pustrSearchPath, rtl_uString **ppustrFileURL );
1526
1527 /** Convert a file URL into a system dependent path.
1528
1529     @param[in] pustrFileURL
1530     A File URL.
1531
1532     @param[out] ppustrSystemPath
1533     On success it receives the system path.
1534
1535     @retval osl_File_E_None on success
1536     @retval osl_File_E_INVAL the format of the parameters was not valid
1537
1538     @see osl_getFileURLFromSystemPath()
1539 */
1540 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getSystemPathFromFileURL(
1541         rtl_uString *pustrFileURL, rtl_uString **ppustrSystemPath);
1542
1543 /** Function pointer representing the function called back from osl_abbreviateSystemPath
1544
1545     @param[in] ustrText
1546     Text to calculate the width for
1547
1548     @return
1549     The width of the text specified by ustrText, e.g. it can return the width in pixel
1550     or the width in character count.
1551
1552     @see osl_abbreviateSystemPath()
1553 */
1554 typedef sal_uInt32 (SAL_CALL *oslCalcTextWidthFunc)( rtl_uString *ustrText );
1555
1556 /** Abbreviate a system notation path.
1557
1558     @param[in] ustrSystemPath
1559     The full system path to abbreviate
1560
1561     @param[out] pustrCompacted
1562     Receives the compacted system path on output
1563
1564     @param[in] pCalcWidth
1565     Function ptr that calculates the width of a string. Can be zero.
1566
1567     @param[in] uMaxWidth
1568     Maximum width allowed that is returned from pCalcWidth.
1569     If pCalcWidth is zero the character count is assumed as width.
1570
1571     @retval osl_File_E_None on success
1572
1573     @see    oslCalcTextWidthFunc
1574 */
1575 SAL_DLLPUBLIC oslFileError SAL_CALL osl_abbreviateSystemPath(
1576     rtl_uString *ustrSystemPath,
1577     rtl_uString **pustrCompacted,
1578     sal_uInt32 uMaxWidth,
1579     oslCalcTextWidthFunc pCalcWidth );
1580
1581 /** Set file attributes.
1582
1583     @param[in] pustrFileURL
1584     The full qualified file URL.
1585
1586     @param[in] uAttributes
1587     Attributes of the file to be set.
1588
1589     @retval osl_File_E_None on success
1590     @retval osl_File_E_INVAL the format of the parameters was not valid
1591
1592     @see osl_getFileStatus()
1593 */
1594 SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileAttributes(
1595         rtl_uString *pustrFileURL, sal_uInt64 uAttributes );
1596
1597 /** Set the file time.
1598
1599     @param[in] pustrFileURL
1600     The full qualified URL of the file.
1601
1602     @param[in] aCreationTime
1603     Creation time of the given file.
1604
1605     @param[in] aLastAccessTime
1606     Time of the last access of the given file.
1607
1608     @param[in] aLastWriteTime
1609     Time of the last modifying of the given file.
1610
1611     @retval osl_File_E_None on success
1612     @retval osl_File_E_INVAL the format of the parameters was not valid
1613     @retval osl_File_E_NOENT no such file or directory not found
1614
1615     @see osl_getFileStatus()
1616 */
1617 SAL_DLLPUBLIC oslFileError SAL_CALL osl_setFileTime(
1618     rtl_uString *pustrFileURL,
1619     const TimeValue *aCreationTime,
1620     const TimeValue *aLastAccessTime,
1621     const TimeValue *aLastWriteTime);
1622
1623 /** Retrieves the file URL of the system's temporary directory path
1624
1625     @param[out] pustrTempDirURL
1626     On success receives the URL of system's temporary directory path.
1627
1628     @retval osl_File_E_None on success
1629     @retval osl_File_E_NOENT no such file or directory not found
1630 */
1631 SAL_DLLPUBLIC oslFileError SAL_CALL osl_getTempDirURL(
1632         rtl_uString **pustrTempDirURL );
1633
1634 /** Creates a temporary file in the directory provided by the caller or the
1635     directory returned by osl_getTempDirURL.
1636
1637     Creates a temporary file in the directory provided by the caller or the
1638     directory returned by osl_getTempDirURL.
1639     Under UNIX Operating Systems the file will be created with read and write
1640     access for the user exclusively.
1641     If the caller requests only a handle to the open file but not the name of
1642     it, the file will be automatically removed on close else the caller is
1643     responsible for removing the file on success.
1644
1645     Description of the different pHandle, ppustrTempFileURL parameter combinations.
1646     pHandle is 0 and ppustrTempDirURL is 0 - this combination is invalid
1647     pHandle is not 0 and ppustrTempDirURL is 0 - a handle to the open file
1648     will be returned on success and the file will be automatically removed on close.
1649     pHandle is 0 and ppustrTempDirURL is not 0 - the name of the file will be returned,
1650     the caller is responsible for opening, closing and removing the file.
1651     pHandle is not 0 and ppustrTempDirURL is not 0 - a handle to the open file as well as
1652     the file name will be returned, the caller is responsible for closing and removing
1653     the file.
1654
1655     @param[in]  pustrDirectoryURL
1656     Specifies the full qualified URL where the temporary file should be created.
1657     If pustrDirectoryURL is 0 the path returned by osl_getTempDirURL will be used.
1658
1659     @param[out]  pHandle
1660     On success receives a handle to the open file. If pHandle is 0 the file will
1661     be closed on return, in this case ppustrTempFileURL must not be 0.
1662
1663     @param[out]  ppustrTempFileURL
1664     On success receives the full qualified URL of the temporary file.
1665     If ppustrTempFileURL is 0 the file will be automatically removed on close,
1666     in this case pHandle must not be 0.
1667     If ppustrTempFileURL is not 0 the caller receives the name of the created
1668     file and is responsible for removing the file, in this case
1669     *ppustrTempFileURL must be 0 or must point to a valid rtl_uString.
1670
1671     @retval osl_File_E_None   on success
1672     @retval osl_File_E_INVAL  the format of the parameter is invalid
1673     @retval osl_File_E_NOMEM  not enough memory for allocating structures
1674     @retval osl_File_E_ACCES  Permission denied
1675     @retval osl_File_E_NOENT  No such file or directory
1676     @retval osl_File_E_NOTDIR Not a directory
1677     @retval osl_File_E_ROFS   Read-only file system
1678     @retval osl_File_E_NOSPC  No space left on device
1679     @retval osl_File_E_DQUOT  Quota exceeded
1680
1681     @see    osl_getTempDirURL()
1682 */
1683 SAL_DLLPUBLIC oslFileError SAL_CALL osl_createTempFile(
1684     rtl_uString*   pustrDirectoryURL,
1685     oslFileHandle* pHandle,
1686     rtl_uString**  ppustrTempFileURL);
1687
1688 /** Move a file to a new destination or rename it, taking old file's identity (if exists).
1689
1690     Moves or renames a file, replacing an existing file if exist. If the old file existed,
1691     moved file's metadata, e.g. creation time (on FSes which keep files' creation time) or
1692     ACLs, are set to old one's (to keep the old file's identity) - currently this is only
1693     implemented fully on Windows; on other platforms, this is mostly equivalent to osl_moveFile.
1694
1695     @param[in] pustrSourceFileURL
1696     Full qualified URL of the source file.
1697
1698     @param[in] pustrDestFileURL
1699     Full qualified URL of the destination file.
1700
1701     @retval osl_File_E_None on success
1702     @retval osl_File_E_INVAL the format of the parameters was not valid
1703     @retval osl_File_E_NOMEM not enough memory for allocating structures
1704     @retval osl_File_E_ACCES permission denied
1705     @retval osl_File_E_PERM operation not permitted
1706     @retval osl_File_E_NAMETOOLONG file name too long
1707     @retval osl_File_E_NOENT no such file
1708     @retval osl_File_E_ROFS read-only file system
1709     @retval osl_File_E_BUSY if the implementation internally requires resources that are
1710         (temporarily) unavailable
1711
1712     @see osl_moveFile()
1713
1714     @since LibreOffice 6.2
1715 */
1716 SAL_DLLPUBLIC oslFileError SAL_CALL osl_replaceFile(rtl_uString* pustrSourceFileURL,
1717                                                     rtl_uString* pustrDestFileURL);
1718
1719 #ifdef __cplusplus
1720 }
1721 #endif
1722
1723 #endif // INCLUDED_OSL_FILE_H
1724
1725 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */