source: trunk/libtransmission/file.h @ 14332

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

(trunk, libT) #4160: apply mike.dld's patch: 4160-05a-file-fmt.patch

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