diff options
Diffstat (limited to 'archivers/libarchive/files/doc/text/libarchive_internals.3.txt')
| -rw-r--r-- | archivers/libarchive/files/doc/text/libarchive_internals.3.txt | 70 |
1 files changed, 35 insertions, 35 deletions
diff --git a/archivers/libarchive/files/doc/text/libarchive_internals.3.txt b/archivers/libarchive/files/doc/text/libarchive_internals.3.txt index 8f92851adb6..7b7fb35dd92 100644 --- a/archivers/libarchive/files/doc/text/libarchive_internals.3.txt +++ b/archivers/libarchive/files/doc/text/libarchive_internals.3.txt @@ -1,23 +1,23 @@ -LIBARCHIVE(3) NetBSD Library Functions Manual LIBARCHIVE(3) +LIBARCHIVE_INTERNALS(3) BSD Library Functions Manual LIBARCHIVE_INTERNALS(3) NAME - libarchive_internals -- description of libarchive internal interfaces + libarchive_internals — description of libarchive internal interfaces OVERVIEW The libarchive library provides a flexible interface for reading and writing streaming archive files such as tar and cpio. Internally, it - follows a modular layered design that should make it easy to add new ar- + follows a modular layered design that should make it easy to add new ar‐ chive and compression formats. GENERAL ARCHITECTURE Externally, libarchive exposes most operations through an opaque, object- - style interface. The archive_entry(1) objects store information about a + style interface. The archive_entry(3) objects store information about a single filesystem object. The rest of the library provides facilities to - write archive_entry(1) objects to archive files, read them from archive + write archive_entry(3) objects to archive files, read them from archive files, and write them to disk. (There are plans to add a facility to - read archive_entry(1) objects from disk as well.) + read archive_entry(3) objects from disk as well.) - The read and write APIs each have four layers: a public API layer, a for- + The read and write APIs each have four layers: a public API layer, a for‐ mat layer that understands the archive file format, a compression layer, and an I/O layer. The I/O layer is completely exposed to clients who can replace it entirely with their own functions. @@ -29,24 +29,24 @@ GENERAL ARCHITECTURE READ ARCHITECTURE From the outside, clients use the archive_read(3) API to manipulate an - archive object to read entries and bodies from an archive stream. Inter- + archive object to read entries and bodies from an archive stream. Inter‐ nally, the archive object is cast to an archive_read object, which holds all read-specific data. The API has four layers: The lowest layer is the - I/O layer. This layer can be overridden by clients, but most clients use + I/O layer. This layer can be overridden by clients, but most clients use the packaged I/O callbacks provided, for example, by - archive_read_open_memory(3), and archive_read_open_fd(3). The compres- + archive_read_open_memory(3), and archive_read_open_fd(3). The compres‐ sion layer calls the I/O layer to read bytes and decompresses them for the format layer. The format layer unpacks a stream of uncompressed bytes and creates archive_entry objects from the incoming data. The API layer tracks overall state (for example, it prevents clients from reading data before reading a header) and invokes the format and compression layer operations through registered function pointers. In particular, - the API layer drives the format-detection process: When opening the ar- + the API layer drives the format-detection process: When opening the ar‐ chive, it reads an initial block of data and offers it to each registered compression handler. The one with the highest bid is initialized with the first block. Similarly, the format handlers are polled to see which - handler is the best for each archive. (Prior to 2.4.0, the format bid- - ders were invoked for each entry, but this design hindered error recov- + handler is the best for each archive. (Prior to 2.4.0, the format bid‐ + ders were invoked for each entry, but this design hindered error recov‐ ery.) I/O Layer and Client Callbacks @@ -55,13 +55,13 @@ READ ARCHITECTURE The client read callback is expected to provide a block of data on each call. A zero-length return does indicate end of file, but otherwise - blocks may be as small as one byte or as large as the entire file. In + blocks may be as small as one byte or as large as the entire file. In particular, blocks may be of different sizes. The client skip callback returns the number of bytes actually skipped, - which may be much smaller than the skip requested. The only requirement + which may be much smaller than the skip requested. The only requirement is that the skip not be larger. In particular, clients are allowed to - return zero for any skip that they don't want to handle. The skip call- + return zero for any skip that they don't want to handle. The skip call‐ back must never be invoked with a negative value. Keep in mind that not all clients are reading from disk: clients reading @@ -73,10 +73,10 @@ READ ARCHITECTURE Decompresssion Layer The decompression layer not only handles decompression, it also buffers - data so that the format handlers see a much nicer I/O model. The decom- + data so that the format handlers see a much nicer I/O model. The decom‐ pression API is a two stage peek/consume model. A read_ahead request specifies a minimum read amount; the decompression layer must provide a - pointer to at least that much data. If more data is immediately avail- + pointer to at least that much data. If more data is immediately avail‐ able, it should return more: the format layer handles bulk data reads by asking for a minimum of one byte and then copying as much data as is available. @@ -92,16 +92,16 @@ READ ARCHITECTURE A decompression handler has a specific lifecycle: Registration/Configuration - When the client invokes the public support function, the decom- + When the client invokes the public support function, the decom‐ pression handler invokes the internal __archive_read_register_compression() function to provide bid and initialization functions. This function returns NULL on error or - else a pointer to a struct decompressor_t. This structure con- - tains a void * config slot that can be used for storing any cus- + else a pointer to a struct decompressor_t. This structure con‐ + tains a void * config slot that can be used for storing any cus‐ tomization information. Bid The bid function is invoked with a pointer and size of a block of data. The decompressor can access its config data through the - decompressor element of the archive_read object. The bid func- + decompressor element of the archive_read object. The bid func‐ tion is otherwise stateless. In particular, it must not perform any I/O operations. @@ -148,7 +148,7 @@ READ ARCHITECTURE The header read is usually the most complex part of any format. There are a few strategies worth mentioning: For formats such as tar or cpio, reading and parsing the header is straightforward - since headers alternate with data. For formats that store all + since headers alternate with data. For formats that store all header data at the beginning of the file, the first header read request may have to read all headers into memory and store that data, sorted by the location of the file data. Subsequent header @@ -158,11 +158,11 @@ READ ARCHITECTURE The read data interface supports sparse files; this requires that each call return a block of data specifying the file offset and size. This may require you to carefully track the location so - that you can return accurate file offsets for each read. Remem- + that you can return accurate file offsets for each read. Remem‐ ber that the decompressor will return as much data as it has. Generally, you will want to request one byte, examine the return value to see how much data is available, and possibly trim that - to the amount you can use. You should invoke consume for each + to the amount you can use. You should invoke consume for each block just before you return it. Skip All Data The skip data call should skip over all file data and trailing @@ -170,7 +170,7 @@ READ ARCHITECTURE before each header read. It is also called in response to the client calling the public data_skip() function. Cleanup - On cleanup, the format should release all of its allocated mem- + On cleanup, the format should release all of its allocated mem‐ ory. API Layer @@ -179,7 +179,7 @@ READ ARCHITECTURE WRITE ARCHITECTURE The write API has a similar set of four layers: an API layer, a format layer, a compression layer, and an I/O layer. The registration here is - much simpler because only one format and one compression can be regis- + much simpler because only one format and one compression can be regis‐ tered at a time. I/O Layer and Client Callbacks @@ -200,9 +200,9 @@ WRITE_DISK ARCHITECTURE not layered internally. GENERAL SERVICES - The archive_read, archive_write, and archive_write_disk objects all con- + The archive_read, archive_write, and archive_write_disk objects all con‐ tain an initial archive object which provides common support for a set of - standard services. (Recall that ANSI/ISO C90 guarantees that you can + standard services. (Recall that ANSI/ISO C90 guarantees that you can cast freely between a pointer to a structure and a pointer to the first element of that structure.) The archive object has a magic value that indicates which API this object is associated with, slots for storing @@ -212,7 +212,7 @@ MISCELLANEOUS NOTES Connecting existing archiving libraries into libarchive is generally quite difficult. In particular, many existing libraries strongly assume that you are reading from a file; they seek forwards and backwards as - necessary to locate various pieces of information. In contrast, + necessary to locate various pieces of information. In contrast, libarchive never seeks backwards in its input, which sometimes requires very different approaches. @@ -220,9 +220,9 @@ MISCELLANEOUS NOTES most ISO9660 readers. The libarchive support utilizes a work-queue design that keeps a list of known entries sorted by their location in the input. Whenever libarchive's ISO9660 implementation is asked for the - next header, checks this list to find the next item on the disk. Direc- + next header, checks this list to find the next item on the disk. Direc‐ tories are parsed when they are encountered and new items are added to - the list. This design relies heavily on the ISO9660 image being opti- + the list. This design relies heavily on the ISO9660 image being opti‐ mized so that directories always occur earlier on the disk than the files they describe. @@ -235,8 +235,8 @@ MISCELLANEOUS NOTES program. SEE ALSO - archive(3), archive_entry(3), archive_read(3), archive_write(3), - archive_write_disk(3) + archive_entry(3), archive_read(3), archive_write(3), + archive_write_disk(3) libarchive(3), HISTORY The libarchive library first appeared in FreeBSD 5.3. @@ -244,4 +244,4 @@ HISTORY AUTHORS The libarchive library was written by Tim Kientzle <kientzle@acm.org>. -NetBSD 5.0 April 16, 2007 NetBSD 5.0 +BSD January 26, 2011 BSD |