1 /*
2  * Library to access the Apple File System (APFS) format
3  *
4  * Copyright (C) 2018-2021, Joachim Metz <joachim.metz@gmail.com>
5  *
6  * Refer to AUTHORS for acknowledgements.
7  *
8  * This program is free software: you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation, either version 3 of the License, or
11  * (at your option) any later version.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU Lesser General Public License
19  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
20  */
21 
22 #if !defined( _LIBFSAPFS_H )
23 #define _LIBFSAPFS_H
24 
25 #include <libfsapfs/codepage.h>
26 #include <libfsapfs/definitions.h>
27 #include <libfsapfs/error.h>
28 #include <libfsapfs/extern.h>
29 #include <libfsapfs/features.h>
30 #include <libfsapfs/types.h>
31 
32 #include <stdio.h>
33 
34 #if defined( LIBFSAPFS_HAVE_BFIO )
35 #include <libbfio.h>
36 #endif
37 
38 #if defined( __cplusplus )
39 extern "C" {
40 #endif
41 
42 /* -------------------------------------------------------------------------
43  * Support functions
44  * ------------------------------------------------------------------------- */
45 
46 /* Returns the library version
47  */
48 LIBFSAPFS_EXTERN \
49 const char *libfsapfs_get_version(
50              void );
51 
52 /* Returns the access flags for reading
53  */
54 LIBFSAPFS_EXTERN \
55 int libfsapfs_get_access_flags_read(
56      void );
57 
58 /* Retrieves the narrow system string codepage
59  * A value of 0 represents no codepage, UTF-8 encoding is used instead
60  * Returns 1 if successful or -1 on error
61  */
62 LIBFSAPFS_EXTERN \
63 int libfsapfs_get_codepage(
64      int *codepage,
65      libfsapfs_error_t **error );
66 
67 /* Sets the narrow system string codepage
68  * A value of 0 represents no codepage, UTF-8 encoding is used instead
69  * Returns 1 if successful or -1 on error
70  */
71 LIBFSAPFS_EXTERN \
72 int libfsapfs_set_codepage(
73      int codepage,
74      libfsapfs_error_t **error );
75 
76 /* Determines if a file contains an APFS container signature
77  * Returns 1 if true, 0 if not or -1 on error
78  */
79 LIBFSAPFS_EXTERN \
80 int libfsapfs_check_container_signature(
81      const char *filename,
82      libfsapfs_error_t **error );
83 
84 /* Determines if a file contains an APFS volume signature
85  * Returns 1 if true, 0 if not or -1 on error
86  */
87 LIBFSAPFS_EXTERN \
88 int libfsapfs_check_volume_signature(
89      const char *filename,
90      libfsapfs_error_t **error );
91 
92 #if defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE )
93 
94 /* Determines if a file contains an APFS container signature
95  * Returns 1 if true, 0 if not or -1 on error
96  */
97 LIBFSAPFS_EXTERN \
98 int libfsapfs_check_container_signature_wide(
99      const wchar_t *filename,
100      libfsapfs_error_t **error );
101 
102 /* Determines if a file contains an APFS volume signature
103  * Returns 1 if true, 0 if not or -1 on error
104  */
105 LIBFSAPFS_EXTERN \
106 int libfsapfs_check_volume_signature_wide(
107      const wchar_t *filename,
108      libfsapfs_error_t **error );
109 
110 #endif /* defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE ) */
111 
112 #if defined( LIBFSAPFS_HAVE_BFIO )
113 
114 /* Determines if a file contains an APFS container signature using a Basic File IO (bfio) handle
115  * Returns 1 if true, 0 if not or -1 on error
116  */
117 LIBFSAPFS_EXTERN \
118 int libfsapfs_check_container_signature_file_io_handle(
119      libbfio_handle_t *file_io_handle,
120      libfsapfs_error_t **error );
121 
122 /* Determines if a file contains an APFS volume signature using a Basic File IO (bfio) handle
123  * Returns 1 if true, 0 if not or -1 on error
124  */
125 LIBFSAPFS_EXTERN \
126 int libfsapfs_check_volume_signature_file_io_handle(
127      libbfio_handle_t *file_io_handle,
128      libfsapfs_error_t **error );
129 
130 #endif /* defined( LIBFSAPFS_HAVE_BFIO ) */
131 
132 /* -------------------------------------------------------------------------
133  * Notify functions
134  * ------------------------------------------------------------------------- */
135 
136 /* Sets the verbose notification
137  */
138 LIBFSAPFS_EXTERN \
139 void libfsapfs_notify_set_verbose(
140       int verbose );
141 
142 /* Sets the notification stream
143  * Returns 1 if successful or -1 on error
144  */
145 LIBFSAPFS_EXTERN \
146 int libfsapfs_notify_set_stream(
147      FILE *stream,
148      libfsapfs_error_t **error );
149 
150 /* Opens the notification stream using a filename
151  * The stream is opened in append mode
152  * Returns 1 if successful or -1 on error
153  */
154 LIBFSAPFS_EXTERN \
155 int libfsapfs_notify_stream_open(
156      const char *filename,
157      libfsapfs_error_t **error );
158 
159 /* Closes the notification stream if opened using a filename
160  * Returns 0 if successful or -1 on error
161  */
162 LIBFSAPFS_EXTERN \
163 int libfsapfs_notify_stream_close(
164      libfsapfs_error_t **error );
165 
166 /* -------------------------------------------------------------------------
167  * Error functions
168  * ------------------------------------------------------------------------- */
169 
170 /* Frees an error
171  */
172 LIBFSAPFS_EXTERN \
173 void libfsapfs_error_free(
174       libfsapfs_error_t **error );
175 
176 /* Prints a descriptive string of the error to the stream
177  * Returns the number of printed characters if successful or -1 on error
178  */
179 LIBFSAPFS_EXTERN \
180 int libfsapfs_error_fprint(
181      libfsapfs_error_t *error,
182      FILE *stream );
183 
184 /* Prints a descriptive string of the error to the string
185  * The end-of-string character is not included in the return value
186  * Returns the number of printed characters if successful or -1 on error
187  */
188 LIBFSAPFS_EXTERN \
189 int libfsapfs_error_sprint(
190      libfsapfs_error_t *error,
191      char *string,
192      size_t size );
193 
194 /* Prints a backtrace of the error to the stream
195  * Returns the number of printed characters if successful or -1 on error
196  */
197 LIBFSAPFS_EXTERN \
198 int libfsapfs_error_backtrace_fprint(
199      libfsapfs_error_t *error,
200      FILE *stream );
201 
202 /* Prints a backtrace of the error to the string
203  * The end-of-string character is not included in the return value
204  * Returns the number of printed characters if successful or -1 on error
205  */
206 LIBFSAPFS_EXTERN \
207 int libfsapfs_error_backtrace_sprint(
208      libfsapfs_error_t *error,
209      char *string,
210      size_t size );
211 
212 /* -------------------------------------------------------------------------
213  * Container functions
214  * ------------------------------------------------------------------------- */
215 
216 /* Creates a container
217  * Make sure the value container is referencing, is set to NULL
218  * Returns 1 if successful or -1 on error
219  */
220 LIBFSAPFS_EXTERN \
221 int libfsapfs_container_initialize(
222      libfsapfs_container_t **container,
223      libfsapfs_error_t **error );
224 
225 /* Frees a container
226  * Returns 1 if successful or -1 on error
227  */
228 LIBFSAPFS_EXTERN \
229 int libfsapfs_container_free(
230      libfsapfs_container_t **container,
231      libfsapfs_error_t **error );
232 
233 /* Signals the container to abort its current activity
234  * Returns 1 if successful or -1 on error
235  */
236 LIBFSAPFS_EXTERN \
237 int libfsapfs_container_signal_abort(
238      libfsapfs_container_t *container,
239      libfsapfs_error_t **error );
240 
241 /* Opens a container
242  * Returns 1 if successful or -1 on error
243  */
244 LIBFSAPFS_EXTERN \
245 int libfsapfs_container_open(
246      libfsapfs_container_t *container,
247      const char *filename,
248      int access_flags,
249      libfsapfs_error_t **error );
250 
251 #if defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE )
252 
253 /* Opens a container
254  * Returns 1 if successful or -1 on error
255  */
256 LIBFSAPFS_EXTERN \
257 int libfsapfs_container_open_wide(
258      libfsapfs_container_t *container,
259      const wchar_t *filename,
260      int access_flags,
261      libfsapfs_error_t **error );
262 
263 #endif /* defined( LIBFSAPFS_HAVE_WIDE_CHARACTER_TYPE ) */
264 
265 #if defined( LIBFSAPFS_HAVE_BFIO )
266 
267 /* Opens a container using a Basic File IO (bfio) handle
268  * Returns 1 if successful or -1 on error
269  */
270 LIBFSAPFS_EXTERN \
271 int libfsapfs_container_open_file_io_handle(
272      libfsapfs_container_t *container,
273      libbfio_handle_t *file_io_handle,
274      int access_flags,
275      libfsapfs_error_t **error );
276 
277 #endif /* defined( LIBFSAPFS_HAVE_BFIO ) */
278 
279 /* Closes a container
280  * Returns 0 if successful or -1 on error
281  */
282 LIBFSAPFS_EXTERN \
283 int libfsapfs_container_close(
284      libfsapfs_container_t *container,
285      libfsapfs_error_t **error );
286 
287 /* Retrieves the size
288  * Returns 1 if successful or -1 on error
289  */
290 LIBFSAPFS_EXTERN \
291 int libfsapfs_container_get_size(
292      libfsapfs_container_t *container,
293      size64_t *size,
294      libfsapfs_error_t **error );
295 
296 /* Retrieves the identifier
297  * The identifier is an UUID stored in big-endian and is 16 bytes of size
298  * Returns 1 if successful or -1 on error
299  */
300 LIBFSAPFS_EXTERN \
301 int libfsapfs_container_get_identifier(
302      libfsapfs_container_t *container,
303      uint8_t *uuid_data,
304      size_t uuid_data_size,
305      libfsapfs_error_t **error );
306 
307 /* Determines if the container is locked
308  * Returns 1 if locked, 0 if not or -1 on error
309  */
310 LIBFSAPFS_EXTERN \
311 int libfsapfs_container_is_locked(
312      libfsapfs_container_t *container,
313      libfsapfs_error_t **error );
314 
315 /* Retrieves the number of volumes
316  * Returns 1 if successful or -1 on error
317  */
318 LIBFSAPFS_EXTERN \
319 int libfsapfs_container_get_number_of_volumes(
320      libfsapfs_container_t *container,
321      int *number_of_volumes,
322      libfsapfs_error_t **error );
323 
324 /* Retrieves a specific of volume
325  * The volume reference must be freed after use with libfsapfs_volume_free
326  * Returns 1 if successful or -1 on error
327  */
328 LIBFSAPFS_EXTERN \
329 int libfsapfs_container_get_volume_by_index(
330      libfsapfs_container_t *container,
331      int volume_index,
332      libfsapfs_volume_t **volume,
333      libfsapfs_error_t **error );
334 
335 /* -------------------------------------------------------------------------
336  * Volume functions
337  * ------------------------------------------------------------------------- */
338 
339 /* Frees a volume
340  * Returns 1 if successful or -1 on error
341  */
342 LIBFSAPFS_EXTERN \
343 int libfsapfs_volume_free(
344      libfsapfs_volume_t **volume,
345      libfsapfs_error_t **error );
346 
347 /* Unlocks the volume
348  * Returns 1 if the volume is unlocked, 0 if not or -1 on error
349  */
350 LIBFSAPFS_EXTERN \
351 int libfsapfs_volume_unlock(
352      libfsapfs_volume_t *volume,
353      libfsapfs_error_t **error );
354 
355 /* Retrieves the feature flags
356  * Returns 1 if successful or -1 on error
357  */
358 LIBFSAPFS_EXTERN \
359 int libfsapfs_volume_get_features_flags(
360      libfsapfs_volume_t *volume,
361      uint64_t *compatible_features_flags,
362      uint64_t *incompatible_features_flags,
363      uint64_t *read_only_compatible_features_flags,
364      libfsapfs_error_t **error );
365 
366 /* Retrieves the size
367  * Returns 1 if successful or -1 on error
368  */
369 LIBFSAPFS_EXTERN \
370 int libfsapfs_volume_get_size(
371      libfsapfs_volume_t *volume,
372      size64_t *size,
373      libfsapfs_error_t **error );
374 
375 /* Retrieves the identifier
376  * The identifier is an UUID stored in big-endian and is 16 bytes of size
377  * Returns 1 if successful or -1 on error
378  */
379 LIBFSAPFS_EXTERN \
380 int libfsapfs_volume_get_identifier(
381      libfsapfs_volume_t *volume,
382      uint8_t *uuid_data,
383      size_t uuid_data_size,
384      libfsapfs_error_t **error );
385 
386 /* Retrieves the size of the UTF-8 encoded name
387  * The returned size includes the end of string character
388  * Returns 1 if successful or -1 on error
389  */
390 LIBFSAPFS_EXTERN \
391 int libfsapfs_volume_get_utf8_name_size(
392      libfsapfs_volume_t *volume,
393      size_t *utf8_string_size,
394      libfsapfs_error_t **error );
395 
396 /* Retrieves the UTF-8 encoded name
397  * The size should include the end of string character
398  * Returns 1 if successful or -1 on error
399  */
400 LIBFSAPFS_EXTERN \
401 int libfsapfs_volume_get_utf8_name(
402      libfsapfs_volume_t *volume,
403      uint8_t *utf8_string,
404      size_t utf8_string_size,
405      libfsapfs_error_t **error );
406 
407 /* Retrieves the size of the UTF-16 encoded name
408  * The returned size includes the end of string character
409  * Returns 1 if successful or -1 on error
410  */
411 LIBFSAPFS_EXTERN \
412 int libfsapfs_volume_get_utf16_name_size(
413      libfsapfs_volume_t *volume,
414      size_t *utf16_string_size,
415      libfsapfs_error_t **error );
416 
417 /* Retrieves the UTF-16 encoded name
418  * The size should include the end of string character
419  * Returns 1 if successful or -1 on error
420  */
421 LIBFSAPFS_EXTERN \
422 int libfsapfs_volume_get_utf16_name(
423      libfsapfs_volume_t *volume,
424      uint16_t *utf16_string,
425      size_t utf16_string_size,
426      libfsapfs_error_t **error );
427 
428 /* Determines if the volume is locked
429  * Returns 1 if locked, 0 if not or -1 on error
430  */
431 LIBFSAPFS_EXTERN \
432 int libfsapfs_volume_is_locked(
433      libfsapfs_volume_t *volume,
434      libfsapfs_error_t **error );
435 
436 /* Sets an UTF-8 formatted password
437  * This function needs to be used before one of the open or unlock functions
438  * Returns 1 if successful, 0 if password is invalid or -1 on error
439  */
440 LIBFSAPFS_EXTERN \
441 int libfsapfs_volume_set_utf8_password(
442      libfsapfs_volume_t *volume,
443      const uint8_t *utf8_string,
444      size_t utf8_string_length,
445      libfsapfs_error_t **error );
446 
447 /* Sets an UTF-16 formatted password
448  * This function needs to be used before one of the open or unlock functions
449  * Returns 1 if successful, 0 if password is invalid or -1 on error
450  */
451 LIBFSAPFS_EXTERN \
452 int libfsapfs_volume_set_utf16_password(
453      libfsapfs_volume_t *volume,
454      const uint16_t *utf16_string,
455      size_t utf16_string_length,
456      libfsapfs_error_t **error );
457 
458 /* Sets an UTF-8 formatted recovery password
459  * This function needs to be used before one of the open or unlock functions
460  * Returns 1 if successful, 0 if recovery password is invalid or -1 on error
461  */
462 LIBFSAPFS_EXTERN \
463 int libfsapfs_volume_set_utf8_recovery_password(
464      libfsapfs_volume_t *volume,
465      const uint8_t *utf8_string,
466      size_t utf8_string_length,
467      libfsapfs_error_t **error );
468 
469 /* Sets an UTF-16 formatted recovery password
470  * This function needs to be used before one of the open or unlock functions
471  * Returns 1 if successful, 0 if recovery password is invalid or -1 on error
472  */
473 LIBFSAPFS_EXTERN \
474 int libfsapfs_volume_set_utf16_recovery_password(
475      libfsapfs_volume_t *volume,
476      const uint16_t *utf16_string,
477      size_t utf16_string_length,
478      libfsapfs_error_t **error );
479 
480 /* Retrieves the next file entry identifier
481  * Returns 1 if successful or -1 on error
482  */
483 LIBFSAPFS_EXTERN \
484 int libfsapfs_volume_get_next_file_entry_identifier(
485      libfsapfs_volume_t *volume,
486      uint64_t *identifier,
487      libfsapfs_error_t **error );
488 
489 /* Retrieves the file entry for a specific identifier
490  * Returns 1 if successful, 0 if not available or -1 on error
491  */
492 LIBFSAPFS_EXTERN \
493 int libfsapfs_volume_get_file_entry_by_identifier(
494      libfsapfs_volume_t *volume,
495      uint64_t identifier,
496      libfsapfs_file_entry_t **file_entry,
497      libfsapfs_error_t **error );
498 
499 /* Retrieves the root directory file entry
500  * Returns 1 if successful or -1 on error
501  */
502 LIBFSAPFS_EXTERN \
503 int libfsapfs_volume_get_root_directory(
504      libfsapfs_volume_t *volume,
505      libfsapfs_file_entry_t **file_entry,
506      libfsapfs_error_t **error );
507 
508 /* Retrieves the file entry for an UTF-8 encoded path
509  * Returns 1 if successful, 0 if no such file entry or -1 on error
510  */
511 LIBFSAPFS_EXTERN \
512 int libfsapfs_volume_get_file_entry_by_utf8_path(
513      libfsapfs_volume_t *volume,
514      const uint8_t *utf8_string,
515      size_t utf8_string_length,
516      libfsapfs_file_entry_t **file_entry,
517      libfsapfs_error_t **error );
518 
519 /* Retrieves the file entry for an UTF-16 encoded path
520  * Returns 1 if successful, 0 if no such file entry or -1 on error
521  */
522 LIBFSAPFS_EXTERN \
523 int libfsapfs_volume_get_file_entry_by_utf16_path(
524      libfsapfs_volume_t *volume,
525      const uint16_t *utf16_string,
526      size_t utf16_string_length,
527      libfsapfs_file_entry_t **file_entry,
528      libfsapfs_error_t **error );
529 
530 /* Retrieves the number of snapshots
531  * Returns 1 if successful or -1 on error
532  */
533 LIBFSAPFS_EXTERN \
534 int libfsapfs_volume_get_number_of_snapshots(
535      libfsapfs_volume_t *volume,
536      int *number_of_snapshots,
537      libfsapfs_error_t **error );
538 
539 /* Retrieves a specific of snapshot
540  * The snapshot reference must be freed after use with libfsapfs_snapshot_free
541  * Returns 1 if successful or -1 on error
542  */
543 LIBFSAPFS_EXTERN \
544 int libfsapfs_volume_get_snapshot_by_index(
545      libfsapfs_volume_t *volume,
546      int snapshot_index,
547      libfsapfs_snapshot_t **snapshot,
548      libfsapfs_error_t **error );
549 
550 /* -------------------------------------------------------------------------
551  * Snapshot functions
552  * ------------------------------------------------------------------------- */
553 
554 /* Frees a snapshot
555  * Returns 1 if successful or -1 on error
556  */
557 LIBFSAPFS_EXTERN \
558 int libfsapfs_snapshot_free(
559      libfsapfs_snapshot_t **snapshot,
560      libfsapfs_error_t **error );
561 
562 /* Retrieves the size of the UTF-8 encoded name
563  * The returned size includes the end of string character
564  * Returns 1 if successful or -1 on error
565  */
566 LIBFSAPFS_EXTERN \
567 int libfsapfs_snapshot_get_utf8_name_size(
568      libfsapfs_snapshot_t *snapshot,
569      size_t *utf8_string_size,
570      libfsapfs_error_t **error );
571 
572 /* Retrieves the UTF-8 encoded name
573  * The size should include the end of string character
574  * Returns 1 if successful or -1 on error
575  */
576 LIBFSAPFS_EXTERN \
577 int libfsapfs_snapshot_get_utf8_name(
578      libfsapfs_snapshot_t *snapshot,
579      uint8_t *utf8_string,
580      size_t utf8_string_size,
581      libfsapfs_error_t **error );
582 
583 /* Retrieves the size of the UTF-16 encoded name
584  * The returned size includes the end of string character
585  * Returns 1 if successful or -1 on error
586  */
587 LIBFSAPFS_EXTERN \
588 int libfsapfs_snapshot_get_utf16_name_size(
589      libfsapfs_snapshot_t *snapshot,
590      size_t *utf16_string_size,
591      libfsapfs_error_t **error );
592 
593 /* Retrieves the UTF-16 encoded name
594  * The size should include the end of string character
595  * Returns 1 if successful or -1 on error
596  */
597 LIBFSAPFS_EXTERN \
598 int libfsapfs_snapshot_get_utf16_name(
599      libfsapfs_snapshot_t *snapshot,
600      uint16_t *utf16_string,
601      size_t utf16_string_size,
602      libfsapfs_error_t **error );
603 
604 /* -------------------------------------------------------------------------
605  * File entry functions
606  * ------------------------------------------------------------------------- */
607 
608 /* Frees a file entry
609  * Returns 1 if successful or -1 on error
610  */
611 LIBFSAPFS_EXTERN \
612 int libfsapfs_file_entry_free(
613      libfsapfs_file_entry_t **file_entry,
614      libfsapfs_error_t **error );
615 
616 /* Retrieves the identifier (or inode number)
617  * This value is retrieved from the inode
618  * Returns 1 if successful or -1 on error
619  */
620 LIBFSAPFS_EXTERN \
621 int libfsapfs_file_entry_get_identifier(
622      libfsapfs_file_entry_t *file_entry,
623      uint64_t *identifier,
624      libfsapfs_error_t **error );
625 
626 /* Retrieves the parent identifier (or inode number)
627  * This value is retrieved from the inode
628  * Returns 1 if successful or -1 on error
629  */
630 LIBFSAPFS_EXTERN \
631 int libfsapfs_file_entry_get_parent_identifier(
632      libfsapfs_file_entry_t *file_entry,
633      uint64_t *parent_identifier,
634      libfsapfs_error_t **error );
635 
636 /* Retrieves the parent file entry
637  * Returns 1 if successful, 0 if no such file entry or -1 on error
638  */
639 LIBFSAPFS_EXTERN \
640 int libfsapfs_file_entry_get_parent_file_entry(
641      libfsapfs_file_entry_t *file_entry,
642      libfsapfs_file_entry_t **parent_file_entry,
643      libfsapfs_error_t **error );
644 
645 /* Retrieves the creation date and time
646  * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
647  * This value is retrieved from the inode
648  * Returns 1 if successful or -1 on error
649  */
650 LIBFSAPFS_EXTERN \
651 int libfsapfs_file_entry_get_creation_time(
652      libfsapfs_file_entry_t *file_entry,
653      int64_t *posix_time,
654      libfsapfs_error_t **error );
655 
656 /* Retrieves the modification date and time
657  * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
658  * This value is retrieved from the inode
659  * Returns 1 if successful or -1 on error
660  */
661 LIBFSAPFS_EXTERN \
662 int libfsapfs_file_entry_get_modification_time(
663      libfsapfs_file_entry_t *file_entry,
664      int64_t *posix_time,
665      libfsapfs_error_t **error );
666 
667 /* Retrieves the access date and time
668  * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
669  * This value is retrieved from the inode
670  * Returns 1 if successful or -1 on error
671  */
672 LIBFSAPFS_EXTERN \
673 int libfsapfs_file_entry_get_access_time(
674      libfsapfs_file_entry_t *file_entry,
675      int64_t *posix_time,
676      libfsapfs_error_t **error );
677 
678 /* Retrieves the inode change date and time
679  * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
680  * This value is retrieved from the inode
681  * Returns 1 if successful or -1 on error
682  */
683 LIBFSAPFS_EXTERN \
684 int libfsapfs_file_entry_get_inode_change_time(
685      libfsapfs_file_entry_t *file_entry,
686      int64_t *posix_time,
687      libfsapfs_error_t **error );
688 
689 /* Retrieves the added date and time
690  * The timestamp is a signed 64-bit POSIX date and time value in number of nano seconds
691  * This value is retrieved from the directory record
692  * Returns 1 if successful, 0 if not available or -1 on error
693  */
694 LIBFSAPFS_EXTERN \
695 int libfsapfs_file_entry_get_added_time(
696      libfsapfs_file_entry_t *file_entry,
697      int64_t *posix_time,
698      libfsapfs_error_t **error );
699 
700 /* Retrieves the user identifier
701  * This value is retrieved from the inode
702  * Returns 1 if successful or -1 on error
703  */
704 LIBFSAPFS_EXTERN \
705 int libfsapfs_file_entry_get_owner_identifier(
706      libfsapfs_file_entry_t *file_entry,
707      uint32_t *owner_identifier,
708      libfsapfs_error_t **error );
709 
710 /* Retrieves the group identifier
711  * This value is retrieved from the inode
712  * Returns 1 if successful or -1 on error
713  */
714 LIBFSAPFS_EXTERN \
715 int libfsapfs_file_entry_get_group_identifier(
716      libfsapfs_file_entry_t *file_entry,
717      uint32_t *group_identifier,
718      libfsapfs_error_t **error );
719 
720 /* Retrieves the file mode
721  * This value is retrieved from the inode
722  * Returns 1 if successful or -1 on error
723  */
724 LIBFSAPFS_EXTERN \
725 int libfsapfs_file_entry_get_file_mode(
726      libfsapfs_file_entry_t *file_entry,
727      uint16_t *file_mode,
728      libfsapfs_error_t **error );
729 
730 /* Retrieves the size of the UTF-8 encoded name
731  * The returned size includes the end of string character
732  * Returns 1 if successful or -1 on error
733  */
734 LIBFSAPFS_EXTERN \
735 int libfsapfs_file_entry_get_utf8_name_size(
736      libfsapfs_file_entry_t *file_entry,
737      size_t *utf8_string_size,
738      libfsapfs_error_t **error );
739 
740 /* Retrieves the UTF-8 encoded name
741  * The size should include the end of string character
742  * This value is retrieved from the inode
743  * Returns 1 if successful or -1 on error
744  */
745 LIBFSAPFS_EXTERN \
746 int libfsapfs_file_entry_get_utf8_name(
747      libfsapfs_file_entry_t *file_entry,
748      uint8_t *utf8_string,
749      size_t utf8_string_size,
750      libfsapfs_error_t **error );
751 
752 /* Retrieves the size of the UTF-16 encoded name
753  * The returned size includes the end of string character
754  * This value is retrieved from the inode
755  * Returns 1 if successful or -1 on error
756  */
757 LIBFSAPFS_EXTERN \
758 int libfsapfs_file_entry_get_utf16_name_size(
759      libfsapfs_file_entry_t *file_entry,
760      size_t *utf16_string_size,
761      libfsapfs_error_t **error );
762 
763 /* Retrieves the UTF-16 encoded name
764  * The size should include the end of string character
765  * This value is retrieved from the inode
766  * Returns 1 if successful or -1 on error
767  */
768 LIBFSAPFS_EXTERN \
769 int libfsapfs_file_entry_get_utf16_name(
770      libfsapfs_file_entry_t *file_entry,
771      uint16_t *utf16_string,
772      size_t utf16_string_size,
773      libfsapfs_error_t **error );
774 
775 /* Retrieves the size of the UTF-8 encoded symbolic link target
776  * The size should include the end of string character
777  * This value is retrieved from the com.apple.fs.symlink extended attribute
778  * Returns 1 if successful, 0 if not available or -1 on error
779  */
780 LIBFSAPFS_EXTERN \
781 int libfsapfs_file_entry_get_utf8_symbolic_link_target_size(
782      libfsapfs_file_entry_t *file_entry,
783      size_t *utf8_string_size,
784      libfsapfs_error_t **error );
785 
786 /* Retrieves the UTF-8 encoded symbolic link target
787  * The size should include the end of string character
788  * This value is retrieved from the com.apple.fs.symlink extended attribute
789  * Returns 1 if successful, 0 if not available or -1 on error
790  */
791 LIBFSAPFS_EXTERN \
792 int libfsapfs_file_entry_get_utf8_symbolic_link_target(
793      libfsapfs_file_entry_t *file_entry,
794      uint8_t *utf8_string,
795      size_t utf8_string_size,
796      libfsapfs_error_t **error );
797 
798 /* Retrieves the size of the UTF-16 encoded symbolic link target
799  * The size should include the end of string character
800  * This value is retrieved from the com.apple.fs.symlink extended attribute
801  * Returns 1 if successful, 0 if not available or -1 on error
802  */
803 LIBFSAPFS_EXTERN \
804 int libfsapfs_file_entry_get_utf16_symbolic_link_target_size(
805      libfsapfs_file_entry_t *file_entry,
806      size_t *utf16_string_size,
807      libfsapfs_error_t **error );
808 
809 /* Retrieves the UTF-16 encoded symbolic link target
810  * The size should include the end of string character
811  * This value is retrieved from the com.apple.fs.symlink extended attribute
812  * Returns 1 if successful, 0 if not available or -1 on error
813  */
814 LIBFSAPFS_EXTERN \
815 int libfsapfs_file_entry_get_utf16_symbolic_link_target(
816      libfsapfs_file_entry_t *file_entry,
817      uint16_t *utf16_string,
818      size_t utf16_string_size,
819      libfsapfs_error_t **error );
820 
821 /* Retrieves the number of extended attributes
822  * Returns 1 if successful or -1 on error
823  */
824 LIBFSAPFS_EXTERN \
825 int libfsapfs_file_entry_get_number_of_extended_attributes(
826      libfsapfs_file_entry_t *file_entry,
827      int *number_of_extended_attributes,
828      libfsapfs_error_t **error );
829 
830 /* Retrieves the extended attribute for the specific index
831  * Returns 1 if successful or -1 on error
832  */
833 LIBFSAPFS_EXTERN \
834 int libfsapfs_file_entry_get_extended_attribute_by_index(
835      libfsapfs_file_entry_t *file_entry,
836      int extended_attribute_index,
837      libfsapfs_extended_attribute_t **extended_attribute,
838      libfsapfs_error_t **error );
839 
840 /* Determines if there is an extended attribute for an UTF-8 encoded name
841  * Returns 1 if available, 0 if not or -1 on error
842  */
843 LIBFSAPFS_EXTERN \
844 int libfsapfs_file_entry_has_extended_attribute_by_utf8_name(
845      libfsapfs_file_entry_t *file_entry,
846      const uint8_t *utf8_string,
847      size_t utf8_string_length,
848      libfsapfs_error_t **error );
849 
850 /* Determines if there is an extended attribute for an UTF-16 encoded name
851  * Returns 1 if available, 0 if not or -1 on error
852  */
853 LIBFSAPFS_EXTERN \
854 int libfsapfs_file_entry_has_extended_attribute_by_utf16_name(
855      libfsapfs_file_entry_t *file_entry,
856      const uint16_t *utf16_string,
857      size_t utf16_string_length,
858      libfsapfs_error_t **error );
859 
860 /* Retrieves the extended attribute for an UTF-8 encoded name
861  * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
862  */
863 LIBFSAPFS_EXTERN \
864 int libfsapfs_file_entry_get_extended_attribute_by_utf8_name(
865      libfsapfs_file_entry_t *file_entry,
866      const uint8_t *utf8_string,
867      size_t utf8_string_length,
868      libfsapfs_extended_attribute_t **extended_attribute,
869      libfsapfs_error_t **error );
870 
871 /* Retrieves the extended attribute for an UTF-16 encoded name
872  * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
873  */
874 LIBFSAPFS_EXTERN \
875 int libfsapfs_file_entry_get_extended_attribute_by_utf16_name(
876      libfsapfs_file_entry_t *file_entry,
877      const uint16_t *utf16_string,
878      size_t utf16_string_length,
879      libfsapfs_extended_attribute_t **extended_attribute,
880      libfsapfs_error_t **error );
881 
882 /* Retrieves the number of sub file entries
883  * Returns 1 if successful or -1 on error
884  */
885 LIBFSAPFS_EXTERN \
886 int libfsapfs_file_entry_get_number_of_sub_file_entries(
887      libfsapfs_file_entry_t *file_entry,
888      int *number_of_sub_file_entries,
889      libfsapfs_error_t **error );
890 
891 /* Retrieves the sub file entry for the specific index
892  * Returns 1 if successful or -1 on error
893  */
894 LIBFSAPFS_EXTERN \
895 int libfsapfs_file_entry_get_sub_file_entry_by_index(
896      libfsapfs_file_entry_t *file_entry,
897      int sub_file_entry_index,
898      libfsapfs_file_entry_t **sub_file_entry,
899      libfsapfs_error_t **error );
900 
901 /* Retrieves the sub file entry for an UTF-8 encoded name
902  * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
903  */
904 LIBFSAPFS_EXTERN \
905 int libfsapfs_file_entry_get_sub_file_entry_by_utf8_name(
906      libfsapfs_file_entry_t *file_entry,
907      const uint8_t *utf8_string,
908      size_t utf8_string_length,
909      libfsapfs_file_entry_t **sub_file_entry,
910      libfsapfs_error_t **error );
911 
912 /* Retrieves the sub file entry for an UTF-16 encoded name
913  * Returns 1 if successful, 0 if the file entry does not contain such value or -1 on error
914  */
915 LIBFSAPFS_EXTERN \
916 int libfsapfs_file_entry_get_sub_file_entry_by_utf16_name(
917      libfsapfs_file_entry_t *file_entry,
918      const uint16_t *utf16_string,
919      size_t utf16_string_length,
920      libfsapfs_file_entry_t **sub_file_entry,
921      libfsapfs_error_t **error );
922 
923 /* Reads data at the current offset
924  * Returns the number of bytes read or -1 on error
925  */
926 LIBFSAPFS_EXTERN \
927 ssize_t libfsapfs_file_entry_read_buffer(
928          libfsapfs_file_entry_t *file_entry,
929          void *buffer,
930          size_t buffer_size,
931          libfsapfs_error_t **error );
932 
933 /* Reads data at a specific offset
934  * Returns the number of bytes read or -1 on error
935  */
936 LIBFSAPFS_EXTERN \
937 ssize_t libfsapfs_file_entry_read_buffer_at_offset(
938          libfsapfs_file_entry_t *file_entry,
939          void *buffer,
940          size_t buffer_size,
941          off64_t offset,
942          libfsapfs_error_t **error );
943 
944 /* Seeks a certain offset
945  * Returns the offset if seek is successful or -1 on error
946  */
947 LIBFSAPFS_EXTERN \
948 off64_t libfsapfs_file_entry_seek_offset(
949          libfsapfs_file_entry_t *file_entry,
950          off64_t offset,
951          int whence,
952          libfsapfs_error_t **error );
953 
954 /* Retrieves the current offset
955  * Returns the offset if successful or -1 on error
956  */
957 LIBFSAPFS_EXTERN \
958 int libfsapfs_file_entry_get_offset(
959      libfsapfs_file_entry_t *file_entry,
960      off64_t *offset,
961      libfsapfs_error_t **error );
962 
963 /* Retrieves the size
964  * Returns 1 if successful or -1 on error
965  */
966 LIBFSAPFS_EXTERN \
967 int libfsapfs_file_entry_get_size(
968      libfsapfs_file_entry_t *file_entry,
969      size64_t *size,
970      libfsapfs_error_t **error );
971 
972 /* Retrieves the number of extents
973  * Returns 1 if successful or -1 on error
974  */
975 LIBFSAPFS_EXTERN \
976 int libfsapfs_file_entry_get_number_of_extents(
977      libfsapfs_file_entry_t *file_entry,
978      int *number_of_extents,
979      libfsapfs_error_t **error );
980 
981 /* Retrieves a specific extent
982  * Returns 1 if successful or -1 on error
983  */
984 LIBFSAPFS_EXTERN \
985 int libfsapfs_file_entry_get_extent_by_index(
986      libfsapfs_file_entry_t *file_entry,
987      int extent_index,
988      off64_t *extent_offset,
989      size64_t *extent_size,
990      uint32_t *extent_flags,
991      libfsapfs_error_t **error );
992 
993 /* -------------------------------------------------------------------------
994  * Extended attribute functions
995  * ------------------------------------------------------------------------- */
996 
997 /* Frees an extended attribute
998  * Returns 1 if successful or -1 on error
999  */
1000 LIBFSAPFS_EXTERN \
1001 int libfsapfs_extended_attribute_free(
1002      libfsapfs_extended_attribute_t **extended_attribute,
1003      libfsapfs_error_t **error );
1004 
1005 /* Retrieves the identifier
1006  * Returns 1 if successful or -1 on error
1007  */
1008 LIBFSAPFS_EXTERN \
1009 int libfsapfs_extended_attribute_get_identifier(
1010      libfsapfs_extended_attribute_t *extended_attribute,
1011      uint64_t *identifier,
1012      libfsapfs_error_t **error );
1013 
1014 /* Retrieves the size of the UTF-8 encoded name
1015  * The returned size includes the end of string character
1016  * Returns 1 if successful or -1 on error
1017  */
1018 LIBFSAPFS_EXTERN \
1019 int libfsapfs_extended_attribute_get_utf8_name_size(
1020      libfsapfs_extended_attribute_t *extended_attribute,
1021      size_t *utf8_string_size,
1022      libfsapfs_error_t **error );
1023 
1024 /* Retrieves the UTF-8 encoded name
1025  * The size should include the end of string character
1026  * Returns 1 if successful or -1 on error
1027  */
1028 LIBFSAPFS_EXTERN \
1029 int libfsapfs_extended_attribute_get_utf8_name(
1030      libfsapfs_extended_attribute_t *extended_attribute,
1031      uint8_t *utf8_string,
1032      size_t utf8_string_size,
1033      libfsapfs_error_t **error );
1034 
1035 /* Retrieves the size of the UTF-16 encoded name
1036  * The returned size includes the end of string character
1037  * Returns 1 if successful or -1 on error
1038  */
1039 LIBFSAPFS_EXTERN \
1040 int libfsapfs_extended_attribute_get_utf16_name_size(
1041      libfsapfs_extended_attribute_t *extended_attribute,
1042      size_t *utf16_string_size,
1043      libfsapfs_error_t **error );
1044 
1045 /* Retrieves the UTF-16 encoded name
1046  * The size should include the end of string character
1047  * Returns 1 if successful or -1 on error
1048  */
1049 LIBFSAPFS_EXTERN \
1050 int libfsapfs_extended_attribute_get_utf16_name(
1051      libfsapfs_extended_attribute_t *extended_attribute,
1052      uint16_t *utf16_string,
1053      size_t utf16_string_size,
1054      libfsapfs_error_t **error );
1055 
1056 /* Reads data at the current offset into a buffer
1057  * Returns the number of bytes read or -1 on error
1058  */
1059 LIBFSAPFS_EXTERN \
1060 ssize_t libfsapfs_extended_attribute_read_buffer(
1061          libfsapfs_extended_attribute_t *extended_attribute,
1062          void *buffer,
1063          size_t buffer_size,
1064          libfsapfs_error_t **error );
1065 
1066 /* Reads data at a specific offset
1067  * Returns the number of bytes read or -1 on error
1068  */
1069 LIBFSAPFS_EXTERN \
1070 ssize_t libfsapfs_extended_attribute_read_buffer_at_offset(
1071          libfsapfs_extended_attribute_t *extended_attribute,
1072          void *buffer,
1073          size_t buffer_size,
1074          off64_t offset,
1075          libfsapfs_error_t **error );
1076 
1077 /* Seeks a certain offset
1078  * Returns the offset if seek is successful or -1 on error
1079  */
1080 LIBFSAPFS_EXTERN \
1081 off64_t libfsapfs_extended_attribute_seek_offset(
1082          libfsapfs_extended_attribute_t *extended_attribute,
1083          off64_t offset,
1084          int whence,
1085          libfsapfs_error_t **error );
1086 
1087 /* Retrieves the current offset
1088  * Returns the offset if successful or -1 on error
1089  */
1090 LIBFSAPFS_EXTERN \
1091 int libfsapfs_extended_attribute_get_offset(
1092      libfsapfs_extended_attribute_t *extended_attribute,
1093      off64_t *offset,
1094      libfsapfs_error_t **error );
1095 
1096 /* Retrieves the size of the data stream object
1097  * Returns 1 if successful or -1 on error
1098  */
1099 LIBFSAPFS_EXTERN \
1100 int libfsapfs_extended_attribute_get_size(
1101      libfsapfs_extended_attribute_t *extended_attribute,
1102      size64_t *size,
1103      libfsapfs_error_t **error );
1104 
1105 #if defined( __cplusplus )
1106 }
1107 #endif
1108 
1109 #endif /* !defined( _LIBFSAPFS_H ) */
1110 
1111