Ignore:
Timestamp:
Jul 8, 2014, 12:15:12 AM (8 years ago)
Author:
jordan
Message:

(trunk, libT) #4160 'foreign character support' -- merge mike.dld's 4160-03a-file.platch, which introduces tr_sys_file_*() portability wrappers

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/libtransmission/file.h

    r14314 r14321  
    2929 */
    3030
     31#ifndef _WIN32
     32 /** @brief Platform-specific file descriptor type. */
     33 typedef int tr_sys_file_t;
     34 /** @brief Platform-specific invalid file descriptor constant. */
     35 #define TR_BAD_SYS_FILE (-1)
     36#else
     37 typedef HANDLE tr_sys_file_t;
     38 #define TR_BAD_SYS_FILE INVALID_HANDLE_VALUE
     39#endif
     40
    3141typedef enum
    3242{
     43  TR_STD_SYS_FILE_IN,
     44  TR_STD_SYS_FILE_OUT,
     45  TR_STD_SYS_FILE_ERR
     46}
     47tr_std_sys_file_t;
     48
     49typedef enum
     50{
     51  TR_SYS_FILE_READ       = 1 << 0,
     52  TR_SYS_FILE_WRITE      = 1 << 1,
     53  TR_SYS_FILE_CREATE     = 1 << 2,
     54  TR_SYS_FILE_CREATE_NEW = 1 << 3,
     55  TR_SYS_FILE_APPEND     = 1 << 4,
     56  TR_SYS_FILE_TRUNCATE   = 1 << 5,
     57  TR_SYS_FILE_SEQUENTIAL = 1 << 6
     58}
     59tr_sys_file_open_flags_t;
     60
     61typedef enum
     62{
     63  TR_SEEK_SET,
     64  TR_SEEK_CUR,
     65  TR_SEEK_END
     66}
     67tr_seek_origin_t;
     68
     69typedef enum
     70{
    3371    TR_SYS_PATH_NO_FOLLOW = 1 << 0
    3472}
    3573tr_sys_path_get_info_flags_t;
     74
     75typedef enum
     76{
     77    TR_SYS_FILE_PREALLOC_SPARSE = 1 << 0
     78}
     79tr_sys_file_preallocate_flags_t;
    3680
    3781typedef enum
     
    56100 * Following functions accept paths in UTF-8 encoding and convert them to native
    57101 * encoding internally if needed.
     102 * Descriptors returned (@ref tr_sys_file_t) may have different type depending
     103 * on platform and should generally not be passed to native functions, but to
     104 * wrapper functions instead.
    58105 *
    59106 * @{
     
    184231                                             tr_error          ** error);
    185232
     233/* File-related wrappers */
     234
     235/**
     236 * @brief Get handle to one of standard I/O files.
     237 *
     238 * @param[in]  std_file Standard file identifier.
     239 * @param[out] error    Pointer to error object. Optional, pass `NULL` if you
     240 *                      are not interested in error details.
     241 *
     242 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
     243 *         `error` set accordingly). DO NOT pass this descriptor to
     244 *         @ref tr_sys_file_close (unless you know what you are doing).
     245 */
     246tr_sys_file_t   tr_sys_file_get_std         (tr_std_sys_file_t    std_file,
     247                                             tr_error          ** error);
     248
     249/**
     250 * @brief Portability wrapper for `open ()`.
     251 *
     252 * @param[in]  path        Path to file.
     253 * @param[in]  flags       Combination of @ref tr_sys_file_open_flags_t values.
     254 * @param[in]  permissions Permissions to create file with (in case
     255                           @ref TR_SYS_FILE_CREATE is used). Not used on Windows.
     256 * @param[out] error       Pointer to error object. Optional, pass `NULL` if you
     257 *                         are not interested in error details.
     258 *
     259 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
     260 *         `error` set accordingly).
     261 */
     262tr_sys_file_t   tr_sys_file_open            (const char         * path,
     263                                             int                  flags,
     264                                             int                  permissions,
     265                                             tr_error          ** error);
     266
     267/**
     268 * @brief Portability wrapper for `mkstemp ()`.
     269 *
     270 * @param[in,out] path_template Template path to file. Should end with at least
     271 *                              six 'X' characters. Upon success, trailing 'X'
     272 *                              characters are replaced with actual random
     273 *                              characters used to form a unique path to
     274 *                              temporary file.
     275 * @param[out]    error         Pointer to error object. Optional, pass `NULL`
     276 *                              if you are not interested in error details.
     277 *
     278 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
     279 *         `error` set accordingly).
     280 */
     281tr_sys_file_t   tr_sys_file_open_temp       (char               * path_template,
     282                                             tr_error          ** error);
     283
     284/**
     285 * @brief Portability wrapper for `close ()`.
     286 *
     287 * @param[in]  handle Valid file descriptor.
     288 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     289 *                    not interested in error details.
     290 *
     291 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     292 */
     293bool            tr_sys_file_close           (tr_sys_file_t        handle,
     294                                             tr_error          ** error);
     295
     296/**
     297 * @brief Portability wrapper for `fstat ()`.
     298 *
     299 * @param[in]  handle Valid file descriptor.
     300 * @param[out] info   Result buffer.
     301 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     302 *                    not interested in error details.
     303 *
     304 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     305 */
     306bool            tr_sys_file_get_info        (tr_sys_file_t        handle,
     307                                             tr_sys_path_info   * info,
     308                                             tr_error          ** error);
     309
     310/**
     311 * @brief Portability wrapper for `lseek ()`.
     312 *
     313 * @param[in]  handle     Valid file descriptor.
     314 * @param[in]  offset     Relative file offset in bytes to seek to.
     315 * @param[in]  origin     Offset origin.
     316 * @param[out] new_offset New offset in bytes from beginning of file. Optional,
     317 *                        pass `NULL` if you are not interested.
     318 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
     319 *                        are not interested in error details.
     320 *
     321 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     322 */
     323bool            tr_sys_file_seek            (tr_sys_file_t        handle,
     324                                             int64_t              offset,
     325                                             tr_seek_origin_t     origin,
     326                                             uint64_t           * new_offset,
     327                                             tr_error          ** error);
     328
     329/**
     330 * @brief Portability wrapper for `read ()`.
     331 *
     332 * @param[in]  handle     Valid file descriptor.
     333 * @param[out] buffer     Buffer to store read data to.
     334 * @param[in]  size       Number of bytes to read.
     335 * @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
     336 *                        if you are not interested.
     337 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
     338 *                        are not interested in error details.
     339 *
     340 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     341 */
     342bool            tr_sys_file_read            (tr_sys_file_t        handle,
     343                                             void               * buffer,
     344                                             uint64_t             size,
     345                                             uint64_t           * bytes_read,
     346                                             tr_error          ** error);
     347
     348/**
     349 * @brief Like `pread ()`, except that the position is undefined afterwards.
     350 *        Not thread-safe.
     351 *
     352 * @param[in]  handle     Valid file descriptor.
     353 * @param[out] buffer     Buffer to store read data to.
     354 * @param[in]  size       Number of bytes to read.
     355 * @param[in]  offset     File offset in bytes to start reading from.
     356 * @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
     357 *                        if you are not interested.
     358 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
     359 *                        are not interested in error details.
     360 *
     361 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     362 */
     363bool            tr_sys_file_read_at         (tr_sys_file_t        handle,
     364                                             void               * buffer,
     365                                             uint64_t             size,
     366                                             uint64_t             offset,
     367                                             uint64_t           * bytes_read,
     368                                             tr_error          ** error);
     369
     370/**
     371 * @brief Portability wrapper for `write ()`.
     372 *
     373 * @param[in]  handle        Valid file descriptor.
     374 * @param[in]  buffer        Buffer to get data being written from.
     375 * @param[in]  size          Number of bytes to write.
     376 * @param[out] bytes_written Number of bytes actually written. Optional, pass
     377 *                           `NULL` if you are not interested.
     378 * @param[out] error         Pointer to error object. Optional, pass `NULL` if
     379 *                           you are not interested in error details.
     380 *
     381 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     382 */
     383bool            tr_sys_file_write           (tr_sys_file_t        handle,
     384                                             const void         * buffer,
     385                                             uint64_t             size,
     386                                             uint64_t           * bytes_written,
     387                                             tr_error          ** error);
     388
     389/**
     390 * @brief Like `pwrite ()`, except that the position is undefined afterwards.
     391 *        Not thread-safe.
     392 *
     393 * @param[in]  handle        Valid file descriptor.
     394 * @param[in]  buffer        Buffer to get data being written from.
     395 * @param[in]  size          Number of bytes to write.
     396 * @param[in]  offset        File offset in bytes to start writing from.
     397 * @param[out] bytes_written Number of bytes actually written. Optional, pass
     398 *                           `NULL` if you are not interested.
     399 * @param[out] error         Pointer to error object. Optional, pass `NULL` if you
     400 *                           are not interested in error details.
     401 *
     402 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     403 */
     404bool            tr_sys_file_write_at        (tr_sys_file_t        handle,
     405                                             const void         * buffer,
     406                                             uint64_t             size,
     407                                             uint64_t             offset,
     408                                             uint64_t           * bytes_written,
     409                                             tr_error          ** error);
     410
     411/**
     412 * @brief Portability wrapper for `fsync ()`.
     413 *
     414 * @param[in]  handle Valid file descriptor.
     415 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     416 *                    not interested in error details.
     417 *
     418 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     419 */
     420bool            tr_sys_file_flush           (tr_sys_file_t        handle,
     421                                             tr_error          ** error);
     422
     423/**
     424 * @brief Portability wrapper for `ftruncate ()`.
     425 *
     426 * @param[in]  handle Valid file descriptor.
     427 * @param[in]  size   Number of bytes to truncate (or extend) file to.
     428 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     429 *                    not interested in error details.
     430 *
     431 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     432 */
     433bool            tr_sys_file_truncate        (tr_sys_file_t        handle,
     434                                             uint64_t             size,
     435                                             tr_error          ** error);
     436
     437/**
     438 * @brief Tell system to prefetch some part of file which is to be read soon.
     439 *
     440 * @param[in]  handle Valid file descriptor.
     441 * @param[in]  offset Offset in file to prefetch from.
     442 * @param[in]  size   Number of bytes to prefetch.
     443 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     444 *                    not interested in error details.
     445 *
     446 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     447 */
     448bool            tr_sys_file_prefetch        (tr_sys_file_t        handle,
     449                                             uint64_t             offset,
     450                                             uint64_t             size,
     451                                             tr_error          ** error);
     452
     453/**
     454 * @brief Preallocate file to specified size in full or sparse mode.
     455 *
     456 * @param[in]  handle Valid file descriptor.
     457 * @param[in]  size   Number of bytes to preallocate file to.
     458 * @param[in]  flags  Combination of @ref tr_sys_file_preallocate_flags_t values.
     459 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     460 *                    not interested in error details.
     461 *
     462 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     463 */
     464bool            tr_sys_file_preallocate     (tr_sys_file_t        handle,
     465                                             uint64_t             size,
     466                                             int                  flags,
     467                                             tr_error          ** error);
     468
     469/**
     470 * @brief Portability wrapper for `mmap ()` for files.
     471 *
     472 * @param[in]  handle Valid file descriptor.
     473 * @param[in]  offset Offset in file to map from.
     474 * @param[in]  size   Number of bytes to map.
     475 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
     476 *                    not interested in error details.
     477 *
     478 * @return Pointer to mapped file data on success, `NULL` otherwise (with
     479 *         `error` set accordingly).
     480 */
     481void          * tr_sys_file_map_for_reading (tr_sys_file_t        handle,
     482                                             uint64_t             offset,
     483                                             uint64_t             size,
     484                                             tr_error          ** error);
     485
     486/**
     487 * @brief Portability wrapper for `munmap ()` for files.
     488 *
     489 * @param[in]  address Pointer to mapped file data.
     490 * @param[in]  size    Size of mapped data in bytes.
     491 * @param[out] error   Pointer to error object. Optional, pass `NULL` if you are
     492 *                     not interested in error details.
     493 *
     494 * @return `True` on success, `false` otherwise (with `error` set accordingly).
     495 */
     496bool            tr_sys_file_unmap           (const void         * address,
     497                                             uint64_t             size,
     498                                             tr_error          ** error);
     499
    186500/** @} */
    187501/** @} */
Note: See TracChangeset for help on using the changeset viewer.