libfsxfs(3)

📦
this version · 2 versions
, in debian trixie, opensuse-leap 16.0, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 libfsxfs(3) 💖

okay so bestie, sit down, hydrate, because this is the manual page from the Library Functions Manual for libfsxfs — and no, you're not getting out of it, this library is a whole main character. It lives in section 3 of your man pages, and it is obsessed with one thing: the X File System (XFS) format. 🦋

Fair warning before we dive in: this page is LONG long. Like, longer than your screen time report. We're doing it in parts so nobody passes out. Part 1 is right here. Let's go. ✨

🌸 NAME 🌸

libfsxfs.h — Library to support the X File System (XFS) format

periodt. that's the whole identity. that's the name. 💅

✨ SYNOPSIS ✨

first thing first, you gotta invite the library in:

#include <libfsxfs.h>

and then… it's functions. SO many functions. grouped into little squads, which honestly is giving "friend group at lunch" and I respect it deeply. 🎀

💫 Support functions 💫

the little housekeeping besties — the ones that tell you what build you're on and how this whole thing is configured:

const char *
libfsxfs_get_version(void);

int
libfsxfs_get_access_flags_read(void);

int
libfsxfs_get_codepage(int *codepage, libfsxfs_error_t **error);

int
libfsxfs_set_codepage(int codepage, libfsxfs_error_t **error);

int
libfsxfs_check_volume_signature(const char *filename,
    libfsxfs_error_t **error);

now. some of these support girls only show up if the library was built a certain way, so listen up:

Available when compiled with wide character string support:

int
libfsxfs_check_volume_signature_wide(const wchar_t *filename,
    libfsxfs_error_t **error);

Available when compiled with libbfio support:

int
libfsxfs_check_volume_signature_file_io_handle(libbfio_handle_t *file_io_handle,
    libfsxfs_error_t **error);
not me saying "available when compiled with…" like that's not the most build-config-dependent sentence ever. iykyk. if your build didn't include those, those functions literally are not there. no cap. 🙈

📣 Notify functions 📣

these are the ones that keep you in the loop — how loud the library is, where it's yapping to, and opening/closing that stream. very "who's in the group chat and who's muted" energy:

void
libfsxfs_notify_set_verbose(int verbose);

int
libfsxfs_notify_set_stream(FILE *stream, libfsxfs_error_t **error);

int
libfsxfs_notify_stream_open(const char *filename,
    libfsxfs_error_t **error);

int
libfsxfs_notify_stream_close(libfsxfs_error_t **error);

😭 Error functions 😭

the ✨emotional support✨ squad. errors get freed, printed, sprinted into a string, and yes — there's a whole backtrace situation, because sometimes you need to know how you ended up here:

void
libfsxfs_error_free(libfsxfs_error_t **error);

int
libfsxfs_error_fprint(libfsxfs_error_t *error, FILE *stream);

int
libfsxfs_error_sprint(libfsxfs_error_t *error, char *string,
    size_t size);

int
libfsxfs_error_backtrace_fprint(libfsxfs_error_t *error, FILE *stream);

int
libfsxfs_error_backtrace_sprint(libfsxfs_error_t *error, char *string,
    size_t size);

🌀 Volume functions 🌀

okay THIS is the group. the volume girlies. init, free, abort the whole operation mid-way (iconic of her), open, close, read the format version, pull the label in utf8 or utf16, grab the root directory, hunt down file entries by inode or by path… it's a lot and every single one is here, no skipping:

int
libfsxfs_volume_initialize(libfsxfs_volume_t **volume,
    libfsxfs_error_t **error);

int
libfsxfs_volume_free(libfsxfs_volume_t **volume,
    libfsxfs_error_t **error);

int
libfsxfs_volume_signal_abort(libfsxfs_volume_t *volume,
    libfsxfs_error_t **error);

int
libfsxfs_volume_open(libfsxfs_volume_t *volume, const char *filename,
    int access_flags, libfsxfs_error_t **error);

int
libfsxfs_volume_close(libfsxfs_volume_t *volume,
    libfsxfs_error_t **error);

int
libfsxfs_volume_get_format_version(libfsxfs_volume_t *volume,
    uint8_t *format_version, libfsxfs_error_t **error);

int
libfsxfs_volume_get_utf8_label_size(libfsxfs_volume_t *volume,
    size_t *utf8_string_size, libfsxfs_error_t **error);

int
libfsxfs_volume_get_utf8_label(libfsxfs_volume_t *volume,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_volume_get_utf16_label_size(libfsxfs_volume_t *volume,
    size_t *utf16_string_size, libfsxfs_error_t **error);

int
libfsxfs_volume_get_utf16_label(libfsxfs_volume_t *volume,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_volume_get_root_directory(libfsxfs_volume_t *volume,
    libfsxfs_file_entry_t **file_entry, libfsxfs_error_t **error);

int
libfsxfs_volume_get_file_entry_by_inode(libfsxfs_volume_t *volume,
    uint64_t inode_number, libfsxfs_file_entry_t **file_entry,
    libfsxfs_error_t **error);

int
libfsxfs_volume_get_file_entry_by_utf8_path(libfsxfs_volume_t *volume,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfsxfs_file_entry_t **file_entry, libfsxfs_error_t **error);

int
libfsxfs_volume_get_file_entry_by_utf16_path(libfsxfs_volume_t *volume,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfsxfs_file_entry_t **file_entry, libfsxfs_error_t **error);

and the conditional ones again, because yes, they get their own moment too:

Available when compiled with wide character string support:

int
libfsxfs_volume_open_wide(libfsxfs_volume_t *volume,
    const wchar_t *filename, int access_flags,
    libfsxfs_error_t **error);

Available when compiled with libbfio support:

int
libfsxfs_volume_open_file_io_handle(libfsxfs_volume_t *volume,
    libbfio_handle_t *file_io_handle, int access_flags,
    libfsxfs_error_t **error);

🦋 File entry functions 🦋

this is the big one. the group chat with 47 people in it. everything you could possibly want to know about a file entry, laid out and ready: inode number, times (creation, modification, access, inode change — she's thorough), file mode, link count, owner, group, device identifier, device numbers in major/minor form, names in utf8 and utf16 and their sizes, symbolic link targets in utf8 and utf16 with sizes, extended attributes by count and index and by utf8/utf16 name, sub file entries by count, index, or utf8/utf16 name, plus read, read-at-offset, seek, offset, size, extent count and extent-by-index. literally all of it:

int
libfsxfs_file_entry_free(libfsxfs_file_entry_t **file_entry,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_inode_number(libfsxfs_file_entry_t *file_entry,
    uint64_t *inode_number, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_creation_time(libfsxfs_file_entry_t *file_entry,
    int64_t *posix_time, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_modification_time(libfsxfs_file_entry_t *file_entry,
    int64_t *posix_time, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_access_time(libfsxfs_file_entry_t *file_entry,
    int64_t *posix_time, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_inode_change_time(libfsxfs_file_entry_t *file_entry,
    int64_t *posix_time, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_file_mode(libfsxfs_file_entry_t *file_entry,
    uint16_t *file_mode, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_number_of_links(libfsxfs_file_entry_t *file_entry,
    uint32_t *number_of_links, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_owner_identifier(libfsxfs_file_entry_t *file_entry,
    uint32_t *owner_identifier, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_group_identifier(libfsxfs_file_entry_t *file_entry,
    uint32_t *group_identifier, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_device_identifier(libfsxfs_file_entry_t *file_entry,
    uint32_t *device_identifier, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_device_number(libfsxfs_file_entry_t *file_entry,
    uint32_t *major_device_number, uint32_t *minor_device_number,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf8_name_size(libfsxfs_file_entry_t *file_entry,
    size_t *utf8_string_size, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf8_name(libfsxfs_file_entry_t *file_entry,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf16_name_size(libfsxfs_file_entry_t *file_entry,
    size_t *utf16_string_size, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf16_name(libfsxfs_file_entry_t *file_entry,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf8_symbolic_link_target_size(libfsxfs_file_entry_t *file_entry,
    size_t *utf8_string_size, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf8_symbolic_link_target(libfsxfs_file_entry_t *file_entry,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf16_symbolic_link_target_size(libfsxfs_file_entry_t *file_entry,
    size_t *utf16_string_size, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_utf16_symbolic_link_target(libfsxfs_file_entry_t *file_entry,
    uint16_t *utf16_string, size_t utf16_string_size,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_number_of_extended_attributes(libfsxfs_file_entry_t *file_entry,
    int *number_of_extended_attributes, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_extended_attribute_by_index(libfsxfs_file_entry_t *file_entry,
    int extended_attribute_index,
    libfsxfs_extended_attribute_t **extended_attribute,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_has_extended_attribute_by_utf8_name(libfsxfs_file_entry_t *file_entry,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_has_extended_attribute_by_utf16_name(libfsxfs_file_entry_t *file_entry,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_extended_attribute_by_utf8_name(libfsxfs_file_entry_t *file_entry,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfsxfs_extended_attribute_t **extended_attribute,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_extended_attribute_by_utf16_name(libfsxfs_file_entry_t *file_entry,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfsxfs_extended_attribute_t **extended_attribute,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_number_of_sub_file_entries(libfsxfs_file_entry_t *file_entry,
    int *number_of_sub_entries, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_sub_file_entry_by_index(libfsxfs_file_entry_t *file_entry,
    int sub_file_entry_index, libfsxfs_file_entry_t **sub_file_entry,
    libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_sub_file_entry_by_utf8_name(libfsxfs_file_entry_t *file_entry,
    const uint8_t *utf8_string, size_t utf8_string_length,
    libfsxfs_file_entry_t **sub_file_entry, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_sub_file_entry_by_utf16_name(libfsxfs_file_entry_t *file_entry,
    const uint16_t *utf16_string, size_t utf16_string_length,
    libfsxfs_file_entry_t **sub_file_entry, libfsxfs_error_t **error);

ssize_t
libfsxfs_file_entry_read_buffer(libfsxfs_file_entry_t *file_entry,
    void *buffer, size_t buffer_size, libfsxfs_error_t **error);

ssize_t
libfsxfs_file_entry_read_buffer_at_offset(libfsxfs_file_entry_t *file_entry,
    void *buffer, size_t buffer_size, off64_t offset,
    libfsxfs_error_t **error);

off64_t
libfsxfs_file_entry_seek_offset(libfsxfs_file_entry_t *file_entry,
    off64_t offset, int whence, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_offset(libfsxfs_file_entry_t *file_entry,
    off64_t *offset, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_size(libfsxfs_file_entry_t *file_entry,
    size64_t *size, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_number_of_extents(libfsxfs_file_entry_t *file_entry,
    int *number_of_extents, libfsxfs_error_t **error);

int
libfsxfs_file_entry_get_extent_by_index(libfsxfs_file_entry_t *file_entry,
    int extent_index, off64_t *extent_offset, size64_t *extent_size,
    uint32_t *extent_flags, libfsxfs_error_t **error);
take a breath. drink water. she's worth it. 🫶

🎀 Extended attribute functions 🎀

and finally for part 1, the extended attribute squad — free her, get her utf8 name size, get her utf8 name:

int
libfsxfs_extended_attribute_free(libfsxfs_extended_attribute_t **extended_attribute,
    libfsxfs_error_t **error);

int
libfsxfs_extended_attribute_get_utf8_name_size(libfsxfs_extended_attribute_t *extended_attribute,
    size_t *utf8_string_size, libfsxfs_error_t **error);

int
libfsxfs_extended_attribute_get_utf8_name(libfsxfs_extended_attribute_t *extended_attribute,
    uint8_t *utf8_string, size_t utf8_string_size,
    libfsxfs_error_t **error);

okay bestie, that's the SYNOPSIS and we are NOT done — there's more of this page and we're getting to it. don't go anywhere. 💜

       int
       libfsxfs_extended_attribute_get_utf16_name_size(libfsxfs_extended_attribute_t *extended_attribute,
           size_t *utf16_string_size, libfsxfs_error_t **error);

       int
       libfsxfs_extended_attribute_get_utf16_name(libfsxfs_extended_attribute_t *extended_attribute,
           uint16_t *utf16_string, size_t utf16_string_size,
           libfsxfs_error_t **error);

       ssize_t
       libfsxfs_extended_attribute_read_buffer(libfsxfs_extended_attribute_t *extended_attribute,
           void *buffer, size_t buffer_size, libfsxfs_error_t **error);

       ssize_t
       libfsxfs_extended_attribute_read_buffer_at_offset(libfsxfs_extended_attribute_t *extended_attribute,
           void *buffer, size_t buffer_size, off64_t offset,
           libfsxfs_error_t **error);

       off64_t
       libfsxfs_extended_attribute_seek_offset(libfsxfs_extended_attribute_t *extended_attribute,
           off64_t offset, int whence, libfsxfs_error_t **error);

       int
       libfsxfs_extended_attribute_get_offset(libfsxfs_extended_attribute_t *extended_attribute,
           off64_t *offset, libfsxfs_error_t **error);

       int
       libfsxfs_extended_attribute_get_size(libfsxfs_extended_attribute_t *extended_attribute,
           size64_t *size, libfsxfs_error_t **error);

       int
       libfsxfs_extended_attribute_get_number_of_extents(libfsxfs_extended_attribute_t *extended_attribute,
           int *number_of_extents, libfsxfs_error_t **error);

       int
       libfsxfs_extended_attribute_get_extent_by_index(libfsxfs_extended_attribute_t *extended_attribute,
           int extent_index, off64_t *extent_offset, size64_t *extent_size,
           uint32_t *extent_flags, libfsxfs_error_t **error);

✨ DESCRIPTION ✨

Okay so the libfsxfs_get_version() function is used to retrieve the library version. That's literally its entire job, bestie. Giving main character energy for version numbers. 💅

🎀 RETURN VALUES 🎀

Most of the functions return NULL or -1 on error, dependent on the return type. For the actual return values see libfsxfs.h. So like, check the header, babe. It's all in there. 📖

🌈 ENVIRONMENT 🌈

None. Zero. Nada. The environment is not the moment here, bestie. 💀

🦋 FILES 🦋

None. No files. Nothing to see. Move along. ✨

💖 NOTES 💖

  • libfsxfs can be compiled with wide character support (wchar_t). So like, it's possible, and it's lowkey iconic. 🌸
  • To compile libfsxfs with wide character support use: ./configure --enable-wide-character-type=yes or define: _UNICODE or UNICODE during compilation. Pick your fighter, bestie. 💅
  • LIBFSXFS_WIDE_CHARACTER_TYPE in libfsxfs/features.h can be used to determine if libfsxfs was compiled with wide character support. Vibe check your build. 👑

😭 BUGS 😭

Please report bugs of any kind on the project issue tracker: https://github.com/libyal/libfsxfs/issues — don't be shy, they want to know. No cap. 🫶

👑 AUTHOR 👑

These man pages are generated from libfsxfs.h. That's the source of truth, periodt. 💯

Copyright (C) 2020-2024, Joachim Metz <joachim.metz@gmail.com>. This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

So like, it's free, but no promises. Read the fine print, bestie. 💜

🌟 SEE ALSO 🌟

the libfsxfs.h include file — that's it. That's the only see also. And honestly? Iconic. 🎀

This page is from libfsxfs, dated August 29, 2022, and it's the libfsxfs(3) man page. Bye bestie! 💖✨🦋

📦 where this page comes from