Archive.Nif (Archive v0.3.0)

Proceed With Caution

The Archive.Nif module contains the functions that directly interact with libarchive. It is generally discouraged to interact with this library directly. If you find you need functionality not supported in the higher-level APIs, consider opening an issue first if the feature would be generally applicable or desireable.

Archive.Nif provides direct Elixir bindings to the libarchive C API. Most of the functions in this module are 1-to-1 mappings to the C API equivalent functions.

These functions work directly with references, rather than Archive or Archive.Entry structs.

As long as you use the ArchiveReaderResource and ArchiveEntryResource reference types, they will be managed and garbage-collected by this module once created.

Most functions in this module may raise ErlangError on failure. You should invoke most of these functions using Archive.Nif.safe_call/2 to catch the errors and return them as :ok or an {:error, reason} tuple

libarchive APIs

libarchive distinguishes the following APIs:

archive_read

Reading an Archive

Although Archive's high-level API takes care of all of the resource management for you, it can still be useful to understand how it works:

  1. Create new archive reader object
  2. Update any global reader properties as appropriate. These properties determine supported compressions, formats, etc.
  3. Open the archive
  4. Repeatedly call archive_read_next_header to get information about successive archive entries. Call archive_read_data to extract data for entries of interest.
  5. Cleanup archive reader object

archive-write

Creating an Archive

To create an archive:

  1. Ask archive_write_new for an archive writer object.
  2. Set any global properties. In particular, you should set the compression and format to use.
  3. Call archive_write_open to open the file (most people will use archive_write_open_file or archive_write_open_fd, which provide convenient canned I/O callbacks for you).
  4. For each entry:
    • construct an appropriate struct archive_entry structure
    • archive_write_header to write the header
    • archive_write_data to write the entry data
  5. archive_write_close to close the output
  6. archive_write_free to cleanup the writer and release resources

archive_write_disk

Writing to Disk

To create objects on disk:

  1. Ask archive_write_disk_new for a new archive_write_disk object.
  2. Set any global properties. In particular, you probably want to set the options.
  3. For each entry:
    • construct an appropriate struct archive_entry structure
    • archive_write_header to create the file/dir/etc on disk
    • archive_write_data to write the entry data
  4. archive_write_free to cleanup the writer and release resources s In particular, you can use this in conjunction with archive_read() to pull entries out of an archive and create them on disk.

It also has archive_read_extract functions that combine reading with writing to disk.

Summary

Functions

Functions

Link to this function

archive_bzlib_version()

@spec archive_bzlib_version() :: binary()
Link to this function

archive_clear_error(arg1)

@spec archive_clear_error(term()) :: :ok
Link to this function

archive_compression(arg1)

@spec archive_compression(reference()) :: -2_147_483_648..2_147_483_647
Link to this function

archive_compression_name(arg1)

@spec archive_compression_name(reference()) :: binary()
Link to this function

archive_entry_clear(arg1)

@spec archive_entry_clear(reference()) :: :ok
Link to this function

archive_entry_copy_stat(arg1, arg2)

@spec archive_entry_copy_stat(
  reference(),
  %{
    atime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    atime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    ctime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    ctime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    devmajor: -2_147_483_648..2_147_483_647,
    devminor: -2_147_483_648..2_147_483_647,
    gid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    inode: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    kind:
      :unknown
      | :unix_domain_socket
      | :sym_link
      | :named_pipe
      | :file
      | :directory
      | :character_device
      | :block_device
      | 49152
      | 40960
      | 32768
      | 24576
      | 16384
      | 8192
      | 4096
      | 0,
    mode: 0..65535,
    mtime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    mtime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    nlinks: 0..4_294_967_295,
    size: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
    uid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807
  }
  | [
      atime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      atime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      ctime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      ctime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      devmajor: -2_147_483_648..2_147_483_647,
      devminor: -2_147_483_648..2_147_483_647,
      gid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      inode: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      kind:
        :unknown
        | :unix_domain_socket
        | :sym_link
        | :named_pipe
        | :file
        | :directory
        | :character_device
        | :block_device
        | 49152
        | 40960
        | 32768
        | 24576
        | 16384
        | 8192
        | 4096
        | 0,
      mode: 0..65535,
      mtime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      mtime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      nlinks: 0..4_294_967_295,
      size: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
      uid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807
    ]
) :: :ok
Link to this function

archive_entry_new()

@spec archive_entry_new() :: reference()
Link to this function

archive_entry_pathname(arg1)

@spec archive_entry_pathname(reference()) :: binary()
Link to this function

archive_entry_set_pathname(arg1, arg2)

@spec archive_entry_set_pathname(reference(), [byte()] | binary() | nil) :: :ok
Link to this function

archive_entry_size(arg1)

@spec archive_entry_size(reference()) ::
  -9_223_372_036_854_775_808..9_223_372_036_854_775_807
Link to this function

archive_entry_stat(arg1)

@spec archive_entry_stat(reference()) :: %{
  atime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  atime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  ctime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  ctime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  devmajor: -2_147_483_648..2_147_483_647,
  devminor: -2_147_483_648..2_147_483_647,
  gid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  inode: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  kind:
    :unknown
    | :unix_domain_socket
    | :sym_link
    | :named_pipe
    | :file
    | :directory
    | :character_device
    | :block_device,
  mode: 0..65535,
  mtime_nsec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  mtime_sec: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  nlinks: 0..4_294_967_295,
  size: -9_223_372_036_854_775_808..9_223_372_036_854_775_807,
  uid: -9_223_372_036_854_775_808..9_223_372_036_854_775_807
}
Link to this function

archive_error_string(arg1)

@spec archive_error_string(term()) :: binary()
Link to this function

archive_file_count(arg1)

@spec archive_file_count(reference()) :: -2_147_483_648..2_147_483_647
Link to this function

archive_format(arg1)

@spec archive_format(reference()) :: -2_147_483_648..2_147_483_647
Link to this function

archive_format_name(arg1)

@spec archive_format_name(reference()) :: binary()
Link to this function

archive_liblz4_version()

@spec archive_liblz4_version() :: binary()
Link to this function

archive_liblzma_version()

@spec archive_liblzma_version() :: binary()
Link to this function

archive_libzstd_version()

@spec archive_libzstd_version() :: binary()
Link to this function

archive_read_close(arg1)

@spec archive_read_close(reference()) :: :ok
Link to this function

archive_read_data(arg1, arg2)

@spec archive_read_data(reference(), 0..18_446_744_073_709_551_615) :: term()
Link to this function

archive_read_extract(arg1, arg2, arg3)

@spec archive_read_extract(reference(), reference(), -2_147_483_648..2_147_483_647) ::
  :ok
Link to this function

archive_read_format_capabilities(arg1)

@spec archive_read_format_capabilities(reference()) :: -2_147_483_648..2_147_483_647
Link to this function

archive_read_new()

@spec archive_read_new() :: reference()
Link to this function

archive_read_next_header(arg1, arg2)

@spec archive_read_next_header(reference(), reference()) :: :ok
Link to this function

archive_read_open_filename(arg1, arg2, arg3)

@spec archive_read_open_filename(
  reference(),
  [byte()] | binary(),
  0..18_446_744_073_709_551_615
) :: :ok
Link to this function

archive_read_open_memory(arg1, arg2)

@spec archive_read_open_memory(reference(), [byte()] | binary()) :: :ok
Link to this function

archive_read_refresh(arg1)

@spec archive_read_refresh(reference()) :: :ok
Link to this function

archive_read_support_compression_all(arg1)

@spec archive_read_support_compression_all(reference()) :: :ok
Link to this function

archive_read_support_filter_all(arg1)

@spec archive_read_support_filter_all(reference()) :: :ok
Link to this function

archive_read_support_filter_by_code(arg1, arg2)

@spec archive_read_support_filter_by_code(reference(), -2_147_483_648..2_147_483_647) ::
  :ok
Link to this function

archive_read_support_format_all(arg1)

@spec archive_read_support_format_all(reference()) :: :ok
Link to this function

archive_read_support_format_by_code(arg1, arg2)

@spec archive_read_support_format_by_code(reference(), -2_147_483_648..2_147_483_647) ::
  :ok
Link to this function

archive_read_support_format_raw(arg1)

@spec archive_read_support_format_raw(reference()) :: :ok
Link to this function

archive_version_details()

@spec archive_version_details() :: binary()
Link to this function

archive_version_string()

@spec archive_version_string() :: binary()
Link to this function

archive_write_add_filter(arg1, arg2)

@spec archive_write_add_filter(reference(), -2_147_483_648..2_147_483_647) :: :ok
Link to this function

archive_write_close(arg1)

@spec archive_write_close(reference()) :: :ok
Link to this function

archive_write_header(arg1, arg2)

@spec archive_write_header(reference(), reference()) :: :ok
Link to this function

archive_write_new()

@spec archive_write_new() :: reference()
Link to this function

archive_write_open_filename(arg1, arg2)

@spec archive_write_open_filename(reference(), [byte()] | binary()) :: :ok
Link to this function

archive_write_refresh(arg1)

@spec archive_write_refresh(reference()) :: :ok
Link to this function

archive_write_set_format(arg1, arg2)

@spec archive_write_set_format(reference(), -2_147_483_648..2_147_483_647) :: :ok
Link to this function

archive_zlib_version()

@spec archive_zlib_version() :: binary()
Link to this function

archiveFilterToAtom(arg1)

@spec archiveFilterToAtom(-2_147_483_648..2_147_483_647) ::
  :zstd
  | :xz
  | :uu
  | :rpm
  | :program
  | :none
  | :lzop
  | :lzma
  | :lzip
  | :lz4
  | :lrzip
  | :gzip
  | :grzip
  | :compress
  | :bzip2
Link to this function

archiveFilterToInt(arg1)

@spec archiveFilterToInt(
  :zstd
  | :xz
  | :uu
  | :rpm
  | :program
  | :none
  | :lzop
  | :lzma
  | :lzip
  | :lz4
  | :lrzip
  | :gzip
  | :grzip
  | :compress
  | :bzip2
  | 0..14
) :: -2_147_483_648..2_147_483_647
Link to this function

archiveFormatToAtom(arg1)

@spec archiveFormatToAtom(-2_147_483_648..2_147_483_647) ::
  :zip
  | :xar
  | :warc
  | :tar_ustar
  | :tar_pax_restricted
  | :tar_pax_interchange
  | :tar_gnutar
  | :tar
  | :shar_dump
  | :shar_base
  | :shar
  | :sevenz
  | :raw
  | :rar_v5
  | :rar
  | :mtree
  | :lha
  | :iso9660_rockridge
  | :iso9660
  | :empty
  | :cpio_svr4_nocrc
  | :cpio_svr4_crc
  | :cpio_pwb
  | :cpio_posix
  | :cpio_bin_le
  | :cpio_bin_be
  | :cpio_afio_large
  | :cpio
  | :cab
  | :ar_gnu
  | :ar_bsd
  | :ar
Link to this function

archiveFormatToInt(arg1)

@spec archiveFormatToInt(
  :zip
  | :xar
  | :warc
  | :tar_ustar
  | :tar_pax_restricted
  | :tar_pax_interchange
  | :tar_gnutar
  | :tar
  | :shar_dump
  | :shar_base
  | :shar
  | :sevenz
  | :raw
  | :rar_v5
  | :rar
  | :mtree
  | :lha
  | :iso9660_rockridge
  | :iso9660
  | :empty
  | :cpio_svr4_nocrc
  | :cpio_svr4_crc
  | :cpio_pwb
  | :cpio_posix
  | :cpio_bin_le
  | :cpio_bin_be
  | :cpio_afio_large
  | :cpio
  | :cab
  | :ar_gnu
  | :ar_bsd
  | :ar
  | 1_048_576
  | 983_040
  | 917_504
  | 851_968
  | 786_432
  | 720_896
  | 655_360
  | 589_824
  | 524_288
  | 458_752..458_754
  | 393_216
  | 327_680
  | 262_144..262_145
  | 196_608..196_612
  | 131_072..131_074
  | 65536..65543
) :: -2_147_483_648..2_147_483_647
Link to this macro

call(func)

(macro)
Link to this macro

call(func, ref)

(macro)
Link to this function

extractFlagToInt(arg1)

@spec extractFlagToInt(
  :xattr
  | :unlink
  | :time
  | :sparse
  | :secure_symlinks
  | :secure_nodotdot
  | :secure_noabsolutepaths
  | :safe_writes
  | :perm
  | :owner
  | :no_overwrite_newer
  | :no_overwrite
  | :no_hfs_compression
  | :no_autodir
  | :mac_metadata
  | :hfs_compression_forced
  | :fflags
  | :clear_nochange_fflags
  | :acl
  | 262_144
  | 131_072
  | 65536
  | 32768
  | 16384
  | 8192
  | 4096
  | 2048
  | 1024
  | 512
  | 256
  | 128
  | 64
  | 32
  | 16
  | 8
  | 4
  | 1..2
) :: -2_147_483_648..2_147_483_647
Link to this function

file_stat_to_zig_map(stat)

Link to this function

get_error_string(ref)

Link to this function

getExtractInfo()

@spec getExtractInfo() :: [
  %{
    default_doc: binary(),
    flag:
      :xattr
      | :unlink
      | :time
      | :sparse
      | :secure_symlinks
      | :secure_nodotdot
      | :secure_noabsolutepaths
      | :safe_writes
      | :perm
      | :owner
      | :no_overwrite_newer
      | :no_overwrite
      | :no_hfs_compression
      | :no_autodir
      | :mac_metadata
      | :hfs_compression_forced
      | :fflags
      | :clear_nochange_fflags
      | :acl
  }
]
Link to this function

isSubFormatOf(arg1, arg2)

@spec isSubFormatOf(
  :zip
  | :xar
  | :warc
  | :tar_ustar
  | :tar_pax_restricted
  | :tar_pax_interchange
  | :tar_gnutar
  | :tar
  | :shar_dump
  | :shar_base
  | :shar
  | :sevenz
  | :raw
  | :rar_v5
  | :rar
  | :mtree
  | :lha
  | :iso9660_rockridge
  | :iso9660
  | :empty
  | :cpio_svr4_nocrc
  | :cpio_svr4_crc
  | :cpio_pwb
  | :cpio_posix
  | :cpio_bin_le
  | :cpio_bin_be
  | :cpio_afio_large
  | :cpio
  | :cab
  | :ar_gnu
  | :ar_bsd
  | :ar
  | 1_048_576
  | 983_040
  | 917_504
  | 851_968
  | 786_432
  | 720_896
  | 655_360
  | 589_824
  | 524_288
  | 458_752..458_754
  | 393_216
  | 327_680
  | 262_144..262_145
  | 196_608..196_612
  | 131_072..131_074
  | 65536..65543,
  :zip
  | :xar
  | :warc
  | :tar_ustar
  | :tar_pax_restricted
  | :tar_pax_interchange
  | :tar_gnutar
  | :tar
  | :shar_dump
  | :shar_base
  | :shar
  | :sevenz
  | :raw
  | :rar_v5
  | :rar
  | :mtree
  | :lha
  | :iso9660_rockridge
  | :iso9660
  | :empty
  | :cpio_svr4_nocrc
  | :cpio_svr4_crc
  | :cpio_pwb
  | :cpio_posix
  | :cpio_bin_le
  | :cpio_bin_be
  | :cpio_afio_large
  | :cpio
  | :cab
  | :ar_gnu
  | :ar_bsd
  | :ar
  | 1_048_576
  | 983_040
  | 917_504
  | 851_968
  | 786_432
  | 720_896
  | 655_360
  | 589_824
  | 524_288
  | 458_752..458_754
  | 393_216
  | 327_680
  | 262_144..262_145
  | 196_608..196_612
  | 131_072..131_074
  | 65536..65543
) :: boolean()
Link to this function

list_all(atom1, atom2)

Link to this function

listReadableFilters()

@spec listReadableFilters() :: [binary()]
Link to this function

listReadableFormats()

@spec listReadableFormats() :: [binary()]
Link to this function

listWritableFilters()

@spec listWritableFilters() :: [binary()]
Link to this function

listWritableFormats()

@spec listWritableFormats() :: [binary()]
Link to this function

safe_call(fun, ref \\ nil)