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