source: trunk/libtransmission/file.h

Last change on this file was 14724, checked in by jordan, 5 years ago

use '#pragma once' instead of #ifndef..#define..#endif guards

  • Property svn:keywords set to Date Rev Author Id
File size: 27.5 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: file.h 14724 2016-03-29 16:37:21Z mikedld $
8 */
9
10#pragma once
11
12#include <inttypes.h>
13#include <time.h>
14
15#ifdef _WIN32
16 #include <windows.h>
17#endif
18
19#ifdef __cplusplus
20extern "C" {
21#endif
22
23struct tr_error;
24
25/**
26 * @addtogroup file_io File IO
27 * @{
28 */
29
30#ifndef _WIN32
31 /** @brief Platform-specific file descriptor type. */
32 typedef int tr_sys_file_t;
33 /** @brief Platform-specific invalid file descriptor constant. */
34 #define TR_BAD_SYS_FILE (-1)
35 /** @brief Platform-specific directory descriptor type. */
36 typedef void * tr_sys_dir_t;
37 /** @brief Platform-specific end-of-line sequence. */
38 #define TR_NATIVE_EOL_STR "\n"
39 /** @brief Platform-specific end-of-line sequence length. */
40 #define TR_NATIVE_EOL_STR_SIZE 1
41#else
42 typedef HANDLE tr_sys_file_t;
43 #define TR_BAD_SYS_FILE INVALID_HANDLE_VALUE
44 typedef struct tr_sys_dir_win32 * tr_sys_dir_t;
45 #define TR_NATIVE_EOL_STR "\r\n"
46 #define TR_NATIVE_EOL_STR_SIZE 2
47#endif
48
49/** @brief Platform-specific invalid directory descriptor constant. */
50#define TR_BAD_SYS_DIR ((tr_sys_dir_t)NULL)
51
52typedef enum
53{
54  TR_STD_SYS_FILE_IN,
55  TR_STD_SYS_FILE_OUT,
56  TR_STD_SYS_FILE_ERR
57}
58tr_std_sys_file_t;
59
60typedef enum
61{
62  TR_SYS_FILE_READ       = 1 << 0,
63  TR_SYS_FILE_WRITE      = 1 << 1,
64  TR_SYS_FILE_CREATE     = 1 << 2,
65  TR_SYS_FILE_CREATE_NEW = 1 << 3,
66  TR_SYS_FILE_APPEND     = 1 << 4,
67  TR_SYS_FILE_TRUNCATE   = 1 << 5,
68  TR_SYS_FILE_SEQUENTIAL = 1 << 6
69}
70tr_sys_file_open_flags_t;
71
72typedef enum
73{
74  TR_SEEK_SET,
75  TR_SEEK_CUR,
76  TR_SEEK_END
77}
78tr_seek_origin_t;
79
80typedef enum
81{
82    TR_SYS_PATH_NO_FOLLOW = 1 << 0
83}
84tr_sys_path_get_info_flags_t;
85
86typedef enum
87{
88    TR_SYS_FILE_PREALLOC_SPARSE = 1 << 0
89}
90tr_sys_file_preallocate_flags_t;
91
92typedef enum
93{
94    TR_SYS_DIR_CREATE_PARENTS = 1 << 0
95}
96tr_sys_dir_create_flags_t;
97
98typedef enum
99{
100  TR_SYS_PATH_IS_FILE,
101  TR_SYS_PATH_IS_DIRECTORY,
102  TR_SYS_PATH_IS_OTHER
103}
104tr_sys_path_type_t;
105
106typedef struct tr_sys_path_info
107{
108  tr_sys_path_type_t type;
109  uint64_t           size;
110  time_t             last_modified_at;
111}
112tr_sys_path_info;
113
114/**
115 * @name Platform-specific wrapper functions
116 *
117 * Following functions accept paths in UTF-8 encoding and convert them to native
118 * encoding internally if needed.
119 * Descriptors returned (@ref tr_sys_file_t and @ref tr_sys_dir_t) may have
120 * different type depending on platform and should generally not be passed to
121 * native functions, but to wrapper functions instead.
122 *
123 * @{
124 */
125
126/* Path-related wrappers */
127
128/**
129 * @brief Portability wrapper for `stat ()`.
130 *
131 * @param[in]  path  Path to file or directory.
132 * @param[in]  flags Combination of @ref tr_sys_path_get_info_flags_t values.
133 * @param[out] info  Result buffer.
134 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
135 *                   not interested in error details.
136 *
137 * @return `True` on success, `false` otherwise (with `error` set accordingly).
138 */
139bool            tr_sys_path_get_info        (const char         * path,
140                                             int                  flags,
141                                             tr_sys_path_info   * info,
142                                             struct tr_error   ** error);
143
144/**
145 * @brief Portability wrapper for `access ()`.
146 *
147 * @param[in]  path  Path to file or directory.
148 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
149 *                   not interested in error details.
150 *
151 * @return `True` if path exists, `false` otherwise. Note that `false` will also
152 *         be returned in case of error; if you need to distinguish the two,
153 *         check if `error` is `NULL` afterwards.
154 */
155bool            tr_sys_path_exists          (const char         * path,
156                                             struct tr_error   ** error);
157
158/**
159 * @brief Check whether path is relative.
160 *
161 * This function only analyzes the string, so no error reporting is needed.
162 *
163 * @param[in] path Path to file or directory.
164 *
165 * @return `True` if path is relative, `false` otherwise
166 */
167bool            tr_sys_path_is_relative     (const char         * path);
168
169/**
170 * @brief Test to see if the two filenames point to the same file.
171 *
172 * @param[in]  path1  Path to first file or directory.
173 * @param[in]  path2  Path to second file or directory.
174 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
175 *                   not interested in error details.
176 *
177 * @return `True` if two paths point to the same file or directory, `false`
178 *         otherwise. Note that `false` will also be returned in case of error;
179 *         if you need to distinguish the two, check if `error` is `NULL`
180 *         afterwards.
181 */
182bool            tr_sys_path_is_same         (const char         * path1,
183                                             const char         * path2,
184                                             struct tr_error   ** error);
185
186/**
187 * @brief Portability wrapper for `realpath ()`.
188 *
189 * @param[in]  path  Path to file or directory.
190 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
191 *                   not interested in error details.
192 *
193 * @return Pointer to newly allocated buffer containing full path (with symbolic
194 *         links, `.` and `..` resolved) on success (use @ref tr_free to free it
195 *         when no longer needed), `NULL` otherwise (with `error` set
196 *         accordingly).
197 */
198char          * tr_sys_path_resolve         (const char         * path,
199                                             struct tr_error   ** error);
200
201/**
202 * @brief Portability wrapper for `basename ()`.
203 *
204 * @param[in]  path  Path to file or directory.
205 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
206 *                   not interested in error details.
207 *
208 * @return Pointer to newly allocated buffer containing base name (last path
209 *         component; parent path removed) on success (use @ref tr_free to free
210 *         it when no longer needed), `NULL` otherwise (with `error` set
211 *         accordingly).
212 */
213char          * tr_sys_path_basename        (const char         * path,
214                                             struct tr_error   ** error);
215
216/**
217 * @brief Portability wrapper for `dirname ()`.
218 *
219 * @param[in]  path  Path to file or directory.
220 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
221 *                   not interested in error details.
222 *
223 * @return Pointer to newly allocated buffer containing directory (parent path;
224 *         last path component removed) on success (use @ref tr_free to free it
225 *         when no longer needed), `NULL` otherwise (with `error` set
226 *         accordingly).
227 */
228char          * tr_sys_path_dirname         (const char         * path,
229                                             struct tr_error   ** error);
230
231/**
232 * @brief Portability wrapper for `rename ()`.
233 *
234 * @param[in]  src_path Path to source file or directory.
235 * @param[in]  dst_path Path to destination file or directory.
236 * @param[out] error    Pointer to error object. Optional, pass `NULL` if you
237 *                      are not interested in error details.
238 *
239 * @return `True` on success, `false` otherwise (with `error` set accordingly).
240 *         Rename will generally only succeed if both source and destination are
241 *         on the same partition.
242 */
243bool            tr_sys_path_rename          (const char         * src_path,
244                                             const char         * dst_path,
245                                             struct tr_error   ** error);
246
247/**
248 * @brief Portability wrapper for `remove ()`.
249 *
250 * @param[in]  path  Path to file or directory.
251 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
252 *                   not interested in error details.
253 *
254 * @return `True` on success, `false` otherwise (with `error` set accordingly).
255 *         Directory removal will only succeed if it is empty (contains no other
256 *         files and directories).
257 */
258bool            tr_sys_path_remove          (const char         * path,
259                                             struct tr_error   ** error);
260
261/* File-related wrappers */
262
263/**
264 * @brief Get handle to one of standard I/O files.
265 *
266 * @param[in]  std_file Standard file identifier.
267 * @param[out] error    Pointer to error object. Optional, pass `NULL` if you
268 *                      are not interested in error details.
269 *
270 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
271 *         `error` set accordingly). DO NOT pass this descriptor to
272 *         @ref tr_sys_file_close (unless you know what you are doing).
273 */
274tr_sys_file_t   tr_sys_file_get_std         (tr_std_sys_file_t    std_file,
275                                             struct tr_error   ** error);
276
277/**
278 * @brief Portability wrapper for `open ()`.
279 *
280 * @param[in]  path        Path to file.
281 * @param[in]  flags       Combination of @ref tr_sys_file_open_flags_t values.
282 * @param[in]  permissions Permissions to create file with (in case
283                           @ref TR_SYS_FILE_CREATE is used). Not used on Windows.
284 * @param[out] error       Pointer to error object. Optional, pass `NULL` if you
285 *                         are not interested in error details.
286 *
287 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
288 *         `error` set accordingly).
289 */
290tr_sys_file_t   tr_sys_file_open            (const char         * path,
291                                             int                  flags,
292                                             int                  permissions,
293                                             struct tr_error   ** error);
294
295/**
296 * @brief Portability wrapper for `mkstemp ()`.
297 *
298 * @param[in,out] path_template Template path to file. Should end with at least
299 *                              six 'X' characters. Upon success, trailing 'X'
300 *                              characters are replaced with actual random
301 *                              characters used to form a unique path to
302 *                              temporary file.
303 * @param[out]    error         Pointer to error object. Optional, pass `NULL`
304 *                              if you are not interested in error details.
305 *
306 * @return Opened file descriptor on success, `TR_BAD_SYS_FILE` otherwise (with
307 *         `error` set accordingly).
308 */
309tr_sys_file_t   tr_sys_file_open_temp       (char               * path_template,
310                                             struct tr_error   ** error);
311
312/**
313 * @brief Portability wrapper for `close ()`.
314 *
315 * @param[in]  handle Valid file descriptor.
316 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
317 *                    not interested in error details.
318 *
319 * @return `True` on success, `false` otherwise (with `error` set accordingly).
320 */
321bool            tr_sys_file_close           (tr_sys_file_t        handle,
322                                             struct tr_error   ** error);
323
324/**
325 * @brief Portability wrapper for `fstat ()`.
326 *
327 * @param[in]  handle Valid file descriptor.
328 * @param[out] info   Result buffer.
329 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
330 *                    not interested in error details.
331 *
332 * @return `True` on success, `false` otherwise (with `error` set accordingly).
333 */
334bool            tr_sys_file_get_info        (tr_sys_file_t        handle,
335                                             tr_sys_path_info   * info,
336                                             struct tr_error   ** error);
337
338/**
339 * @brief Portability wrapper for `lseek ()`.
340 *
341 * @param[in]  handle     Valid file descriptor.
342 * @param[in]  offset     Relative file offset in bytes to seek to.
343 * @param[in]  origin     Offset origin.
344 * @param[out] new_offset New offset in bytes from beginning of file. Optional,
345 *                        pass `NULL` if you are not interested.
346 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
347 *                        are not interested in error details.
348 *
349 * @return `True` on success, `false` otherwise (with `error` set accordingly).
350 */
351bool            tr_sys_file_seek            (tr_sys_file_t        handle,
352                                             int64_t              offset,
353                                             tr_seek_origin_t     origin,
354                                             uint64_t           * new_offset,
355                                             struct tr_error   ** error);
356
357/**
358 * @brief Portability wrapper for `read ()`.
359 *
360 * @param[in]  handle     Valid file descriptor.
361 * @param[out] buffer     Buffer to store read data to.
362 * @param[in]  size       Number of bytes to read.
363 * @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
364 *                        if you are not interested.
365 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
366 *                        are not interested in error details.
367 *
368 * @return `True` on success, `false` otherwise (with `error` set accordingly).
369 */
370bool            tr_sys_file_read            (tr_sys_file_t        handle,
371                                             void               * buffer,
372                                             uint64_t             size,
373                                             uint64_t           * bytes_read,
374                                             struct tr_error   ** error);
375
376/**
377 * @brief Like `pread ()`, except that the position is undefined afterwards.
378 *        Not thread-safe.
379 *
380 * @param[in]  handle     Valid file descriptor.
381 * @param[out] buffer     Buffer to store read data to.
382 * @param[in]  size       Number of bytes to read.
383 * @param[in]  offset     File offset in bytes to start reading from.
384 * @param[out] bytes_read Number of bytes actually read. Optional, pass `NULL`
385 *                        if you are not interested.
386 * @param[out] error      Pointer to error object. Optional, pass `NULL` if you
387 *                        are not interested in error details.
388 *
389 * @return `True` on success, `false` otherwise (with `error` set accordingly).
390 */
391bool            tr_sys_file_read_at         (tr_sys_file_t        handle,
392                                             void               * buffer,
393                                             uint64_t             size,
394                                             uint64_t             offset,
395                                             uint64_t           * bytes_read,
396                                             struct tr_error   ** error);
397
398/**
399 * @brief Portability wrapper for `write ()`.
400 *
401 * @param[in]  handle        Valid file descriptor.
402 * @param[in]  buffer        Buffer to get data being written from.
403 * @param[in]  size          Number of bytes to write.
404 * @param[out] bytes_written Number of bytes actually written. Optional, pass
405 *                           `NULL` if you are not interested.
406 * @param[out] error         Pointer to error object. Optional, pass `NULL` if
407 *                           you are not interested in error details.
408 *
409 * @return `True` on success, `false` otherwise (with `error` set accordingly).
410 */
411bool            tr_sys_file_write           (tr_sys_file_t        handle,
412                                             const void         * buffer,
413                                             uint64_t             size,
414                                             uint64_t           * bytes_written,
415                                             struct tr_error   ** error);
416
417/**
418 * @brief Like `pwrite ()`, except that the position is undefined afterwards.
419 *        Not thread-safe.
420 *
421 * @param[in]  handle        Valid file descriptor.
422 * @param[in]  buffer        Buffer to get data being written from.
423 * @param[in]  size          Number of bytes to write.
424 * @param[in]  offset        File offset in bytes to start writing from.
425 * @param[out] bytes_written Number of bytes actually written. Optional, pass
426 *                           `NULL` if you are not interested.
427 * @param[out] error         Pointer to error object. Optional, pass `NULL` if you
428 *                           are not interested in error details.
429 *
430 * @return `True` on success, `false` otherwise (with `error` set accordingly).
431 */
432bool            tr_sys_file_write_at        (tr_sys_file_t        handle,
433                                             const void         * buffer,
434                                             uint64_t             size,
435                                             uint64_t             offset,
436                                             uint64_t           * bytes_written,
437                                             struct tr_error   ** error);
438
439/**
440 * @brief Portability wrapper for `fsync ()`.
441 *
442 * @param[in]  handle Valid file descriptor.
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_flush           (tr_sys_file_t        handle,
449                                             struct tr_error   ** error);
450
451/**
452 * @brief Portability wrapper for `ftruncate ()`.
453 *
454 * @param[in]  handle Valid file descriptor.
455 * @param[in]  size   Number of bytes to truncate (or extend) file to.
456 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
457 *                    not interested in error details.
458 *
459 * @return `True` on success, `false` otherwise (with `error` set accordingly).
460 */
461bool            tr_sys_file_truncate        (tr_sys_file_t        handle,
462                                             uint64_t             size,
463                                             struct tr_error   ** error);
464
465/**
466 * @brief Tell system to prefetch some part of file which is to be read soon.
467 *
468 * @param[in]  handle Valid file descriptor.
469 * @param[in]  offset Offset in file to prefetch from.
470 * @param[in]  size   Number of bytes to prefetch.
471 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
472 *                    not interested in error details.
473 *
474 * @return `True` on success, `false` otherwise (with `error` set accordingly).
475 */
476bool            tr_sys_file_prefetch        (tr_sys_file_t        handle,
477                                             uint64_t             offset,
478                                             uint64_t             size,
479                                             struct tr_error   ** error);
480
481/**
482 * @brief Preallocate file to specified size in full or sparse mode.
483 *
484 * @param[in]  handle Valid file descriptor.
485 * @param[in]  size   Number of bytes to preallocate file to.
486 * @param[in]  flags  Combination of @ref tr_sys_file_preallocate_flags_t values.
487 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
488 *                    not interested in error details.
489 *
490 * @return `True` on success, `false` otherwise (with `error` set accordingly).
491 */
492bool            tr_sys_file_preallocate     (tr_sys_file_t        handle,
493                                             uint64_t             size,
494                                             int                  flags,
495                                             struct tr_error   ** error);
496
497/**
498 * @brief Portability wrapper for `mmap ()` for files.
499 *
500 * @param[in]  handle Valid file descriptor.
501 * @param[in]  offset Offset in file to map from.
502 * @param[in]  size   Number of bytes to map.
503 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
504 *                    not interested in error details.
505 *
506 * @return Pointer to mapped file data on success, `NULL` otherwise (with
507 *         `error` set accordingly).
508 */
509void          * tr_sys_file_map_for_reading (tr_sys_file_t        handle,
510                                             uint64_t             offset,
511                                             uint64_t             size,
512                                             struct tr_error   ** error);
513
514/**
515 * @brief Portability wrapper for `munmap ()` for files.
516 *
517 * @param[in]  address Pointer to mapped file data.
518 * @param[in]  size    Size of mapped data in bytes.
519 * @param[out] error   Pointer to error object. Optional, pass `NULL` if you are
520 *                     not interested in error details.
521 *
522 * @return `True` on success, `false` otherwise (with `error` set accordingly).
523 */
524bool            tr_sys_file_unmap           (const void         * address,
525                                             uint64_t             size,
526                                             struct tr_error   ** error);
527
528/* File-related wrappers (utility) */
529
530/**
531 * @brief Portability wrapper for `fgets ()`, removing EOL internally.
532 *
533 * Special care should be taken when reading from one of standard input streams
534 * (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
535 *
536 * Reading from other streams (files, pipes) also leaves data untouched, so it
537 * should already be in UTF-8 encoding, or whichever else you expect.
538 *
539 * @param[in]  handle      Valid file descriptor.
540 * @param[out] buffer      Buffer to store read zero-terminated string to.
541 * @param[in]  buffer_size Buffer size in bytes, taking '\0' character into
542 *                         account.
543 * @param[out] error       Pointer to error object. Optional, pass `NULL` if you
544 *                         are not interested in error details.
545 *
546 * @return `True` on success, `false` otherwise (with `error` set accordingly).
547 *         Note that `false` will also be returned in case of end of file; if
548 *         you need to distinguish the two, check if `error` is `NULL`
549 *         afterwards.
550 */
551bool            tr_sys_file_read_line       (tr_sys_file_t        handle,
552                                             char               * buffer,
553                                             size_t               buffer_size,
554                                             struct tr_error   ** error);
555
556/**
557 * @brief Portability wrapper for `fputs ()`, appending EOL internally.
558 *
559 * Special care should be taken when writing to one of standard output streams
560 * (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
561 *
562 * Writing to other streams (files, pipes) also leaves data untouched, so it
563 * should already be in UTF-8 encoding, or whichever else you expect.
564 *
565 * @param[in]  handle Valid file descriptor.
566 * @param[in]  buffer Zero-terminated string to write.
567 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
568 *                    not interested in error details.
569 *
570 * @return `True` on success, `false` otherwise (with `error` set accordingly).
571 */
572bool            tr_sys_file_write_line      (tr_sys_file_t        handle,
573                                             const char         * buffer,
574                                             struct tr_error   ** error);
575
576/**
577 * @brief Portability wrapper for `fprintf ()`.
578 *
579 * Special care should be taken when writing to one of standard output streams
580 * (@ref tr_std_sys_file_t) since no UTF-8 conversion is currently being made.
581 *
582 * Writing to other streams (files, pipes) also leaves data untouched, so it
583 * should already be in UTF-8 encoding, or whichever else you expect.
584 *
585 * @param[in]  handle Valid file descriptor.
586 * @param[in]  format String format to write.
587 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
588 *                    not interested in error details.
589 * @param[in]  ...    Format arguments.
590 *
591 * @return `True` on success, `false` otherwise (with `error` set accordingly).
592 */
593bool            tr_sys_file_write_fmt       (tr_sys_file_t        handle,
594                                             const char         * format,
595                                             struct tr_error   ** error,
596                                                                  ...);
597
598/* Directory-related wrappers */
599
600/**
601 * @brief Portability wrapper for `getcwd ()`.
602 *
603 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
604 *                   not interested in error details.
605 *
606 * @return Pointer to newly allocated buffer containing path to current
607 *         directory (use @ref tr_free to free it when no longer needed) on
608 *         success, `NULL` otherwise (with `error` set accordingly).
609 */
610char          * tr_sys_dir_get_current      (struct tr_error   ** error);
611
612/**
613 * @brief Like `mkdir ()`, but makes parent directories if needed.
614 *
615 * @param[in]  path        Path to directory.
616 * @param[in]  flags       Combination of @ref tr_sys_dir_create_flags_t values.
617 * @param[in]  permissions Permissions to create directory with. Not used on
618                           Windows.
619 * @param[out] error       Pointer to error object. Optional, pass `NULL` if you
620 *                         are not interested in error details.
621 *
622 * @return `True` on success, `false` otherwise (with `error` set accordingly).
623 */
624bool            tr_sys_dir_create           (const char         * path,
625                                             int                  flags,
626                                             int                  permissions,
627                                             struct tr_error   ** error);
628
629/**
630 * @brief Portability wrapper for `mkdtemp ()`.
631 *
632 * @param[in,out] path_template Template path to directory. Should end with at
633 *                              least six 'X' characters. Upon success, trailing
634 *                              'X' characters are replaced with actual random
635 *                              characters used to form a unique path to
636 *                              temporary directory.
637 * @param[out]    error         Pointer to error object. Optional, pass `NULL`
638 *                              if you are not interested in error details.
639 *
640 * @return `True` on success, `false` otherwise (with `error` set accordingly).
641 */
642bool            tr_sys_dir_create_temp      (char               * path_template,
643                                             struct tr_error   ** error);
644
645/**
646 * @brief Portability wrapper for `opendir ()`.
647 *
648 * @param[in]  path  Path to directory.
649 * @param[out] error Pointer to error object. Optional, pass `NULL` if you are
650 *                   not interested in error details.
651 *
652 * @return Opened directory descriptor on success, `TR_BAD_SYS_DIR` otherwise
653 *         (with `error` set accordingly).
654 */
655tr_sys_dir_t    tr_sys_dir_open             (const char         * path,
656                                             struct tr_error   ** error);
657
658/**
659 * @brief Portability wrapper for `readdir ()`.
660 *
661 * @param[in]  handle Valid directory descriptor.
662 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
663 *                    not interested in error details.
664 *
665 * @return Pointer to next directory entry name (stored internally, DO NOT pass
666 *         it to @ref tr_free) on success, `NULL` otherwise (with `error` set
667 *         accordingly). Note that `NULL` will also be returned in case of end
668 *         of directory; if you need to distinguish the two, check if `error`
669 *         is `NULL` afterwards.
670 */
671const char    * tr_sys_dir_read_name        (tr_sys_dir_t         handle,
672                                             struct tr_error   ** error);
673
674/**
675 * @brief Portability wrapper for `closedir ()`.
676 *
677 * @param[in]  handle Valid directory descriptor.
678 * @param[out] error  Pointer to error object. Optional, pass `NULL` if you are
679 *                    not interested in error details.
680 *
681 * @return `True` on success, `false` otherwise (with `error` set accordingly).
682 */
683bool            tr_sys_dir_close            (tr_sys_dir_t         handle,
684                                             struct tr_error   ** error);
685
686/** @} */
687/** @} */
688
689#ifdef __cplusplus
690}
691#endif
692
Note: See TracBrowser for help on using the repository browser.