source: trunk/libtransmission/file.h @ 14321

Last change on this file since 14321 was 14321, checked in by jordan, 8 years ago

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

File size: 19.6 KB
Line 
1/*
2 * This file Copyright (C) 2013-2014 Mnemosyne LLC
3 *
4 * It may be used under the GNU GPL versions 2 or 3
5 * or any future license endorsed by Mnemosyne LLC.
6 *
7 * $Id$
8 */
9
10#ifndef TR_FILE_H
11#define TR_FILE_H
12
13#include <inttypes.h>
14#include <time.h>
15
16#ifdef WIN32
17 #include <windows.h>
18#endif
19
20#include "error.h"
21
22#ifdef __cplusplus
23extern "C" {
24#endif
25
26/**
27 * @addtogroup file_io File IO
28 * @{
29 */
30
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
41typedef enum
42{
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{
71    TR_SYS_PATH_NO_FOLLOW = 1 << 0
72}
73tr_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;
80
81typedef enum
82{
83  TR_SYS_PATH_IS_FILE,
84  TR_SYS_PATH_IS_DIRECTORY,
85  TR_SYS_PATH_IS_OTHER
86}
87tr_sys_path_type_t;
88
89typedef struct tr_sys_path_info
90{
91  tr_sys_path_type_t type;
92  uint64_t           size;
93  time_t             last_modified_at;
94}
95tr_sys_path_info;
96
97/**
98 * @name Platform-specific wrapper functions
99 *
100 * Following functions accept paths in UTF-8 encoding and convert them to native
101 * 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.
105 *
106 * @{
107 */
108
109/* Path-related wrappers */
110
111/**
112 * @brief Portability wrapper for `stat ()`.
113 *
114 * @param[in]  path  Path to file or directory.
115 * @param[in]  flags Combination of @ref tr_sys_path_get_info_flags_t values.
116 * @param[out] info  Result buffer.
117 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
118 *                   not interested in error details.
119 *
120 * @return `True` on success, `false` otherwise (with `error` set accordingly).
121 */
122bool            tr_sys_path_get_info        (const char         * path,
123                                             int                  flags,
124                                             tr_sys_path_info   * info,
125                                             tr_error          ** error);
126
127/**
128 * @brief Portability wrapper for `access ()`.
129 *
130 * @param[in]  path  Path to file or directory.
131 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
132 *                   not interested in error details.
133 *
134 * @return `True` if path exists, `false` otherwise. Note that `false` will also
135 *         be returned in case of error; if you need to distinguish the two,
136 *         check if `error` is `NULL` afterwards.
137 */
138bool            tr_sys_path_exists          (const char         * path,
139                                             tr_error          ** error);
140
141/**
142 * @brief Test to see if the two filenames point to the same file.
143 *
144 * @param[in]  path1  Path to first file or directory.
145 * @param[in]  path2  Path to second file or directory.
146 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
147 *                   not interested in error details.
148 *
149 * @return `True` if two paths point to the same file or directory, `false`
150 *         otherwise. Note that `false` will also be returned in case of error;
151 *         if you need to distinguish the two, check if `error` is `NULL`
152 *         afterwards.
153 */
154bool            tr_sys_path_is_same         (const char         * path1,
155                                             const char         * path2,
156                                             tr_error          ** error);
157
158/**
159 * @brief Portability wrapper for `realpath ()`.
160 *
161 * @param[in]  path  Path to file or directory.
162 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
163 *                   not interested in error details.
164 *
165 * @return Pointer to newly allocated buffer containing full path (with symbolic
166 *         links, `.` and `..` resolved) on success (use @ref tr_free to free it
167 *         when no longer needed), `NULL` otherwise (with `error` set
168 *         accordingly).
169 */
170char          * tr_sys_path_resolve         (const char         * path,
171                                             tr_error          ** error);
172
173/**
174 * @brief Portability wrapper for `basename ()`.
175 *
176 * @param[in]  path  Path to file or directory.
177 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
178 *                   not interested in error details.
179 *
180 * @return Pointer to newly allocated buffer containing base name (last path
181 *         component; parent path removed) on success (use @ref tr_free to free
182 *         it when no longer needed), `NULL` otherwise (with `error` set
183 *         accordingly).
184 */
185char          * tr_sys_path_basename        (const char         * path,
186                                             tr_error          ** error);
187
188/**
189 * @brief Portability wrapper for `dirname ()`.
190 *
191 * @param[in]  path  Path to file or directory.
192 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
193 *                   not interested in error details.
194 *
195 * @return Pointer to newly allocated buffer containing directory (parent path;
196 *         last path component removed) on success (use @ref tr_free to free it
197 *         when no longer needed), `NULL` otherwise (with `error` set
198 *         accordingly).
199 */
200char          * tr_sys_path_dirname         (const char         * path,
201                                             tr_error          ** error);
202
203/**
204 * @brief Portability wrapper for `rename ()`.
205 *
206 * @param[in]  src_path Path to source file or directory.
207 * @param[in]  dst_path Path to destination file or directory.
208 * @param[out] error    Pointer to error object. Optional, pass `NULL` if you
209 *                      are not interested in error details.
210 *
211 * @return `True` on success, `false` otherwise (with `error` set accordingly).
212 *         Rename will generally only succeed if both source and destination are
213 *         on the same partition.
214 */
215bool            tr_sys_path_rename          (const char         * src_path,
216                                             const char         * dst_path,
217                                             tr_error          ** error);
218
219/**
220 * @brief Portability wrapper for `remove ()`.
221 *
222 * @param[in]  path  Path to file or directory.
223 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
224 *                   not interested in error details.
225 *
226 * @return `True` on success, `false` otherwise (with `error` set accordingly).
227 *         Directory removal will only succeed if it is empty (contains no other
228 *         files and directories).
229 */
230bool            tr_sys_path_remove          (const char         * path,
231                                             tr_error          ** error);
232
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
500/** @} */
501/** @} */
502
503#ifdef __cplusplus
504}
505#endif
506
507#endif
Note: See TracBrowser for help on using the repository browser.