*** /dev/null Wed May 1 11:45:38 2024
--- - Wed May 1 11:47:39 2024
***************
*** 0 ****
--- 1,399 ----
+ ##
+ ## OSSP al - Assembly Lists
+ ## Copyright (c) 2002 Michael van Elst <mlelstv@dev.de.cw.net>
+ ## Copyright (c) 2002 The OSSP Project <http://www.ossp.org/>
+ ## Copyright (c) 2002 Cable & Wireless Deutschland <http://www.cw.com/de/>
+ ##
+ ## This file is part of OSSP al, an abstract datatype of a data buffer
+ ## that can assemble, move and truncate data but avoids actual copying.
+ ##
+ ## Permission to use, copy, modify, and distribute this software for
+ ## any purpose with or without fee is hereby granted, provided that
+ ## the above copyright notice and this permission notice appear in all
+ ## copies.
+ ##
+ ## THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+ ## WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+ ## MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+ ## IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+ ## CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ ## SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ ## LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+ ## USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ ## ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ ## OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+ ## OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+ ## SUCH DAMAGE.
+ ##
+ ## al.pod: assembly lists library manual page
+ ##
+
+ =pod
+
+ =head1 NAME
+
+ B<OSSP al> - Assembly Lists
+
+ =head1 VERSION
+
+ B<OSSP al AL_VERSION_STR>
+
+ =head1 SYNOPSIS
+
+ =over 4
+
+ =item B<Abstract Data Types>:
+
+ al_rc_t,
+ al_t,
+ al_tx_t,
+ al_td_t,
+ al_chunk_t.
+
+ =item B<Assembly List Operations>:
+
+ al_create,
+ al_destroy,
+ al_append_bytes,
+ al_prepend_bytes,
+ al_attach_buffer,
+ al_splice,
+ al_bytes.
+
+ =item B<Traversal Operations>:
+
+ al_txalloc,
+ al_txfree,
+ al_traverse,
+ al_traverse_next,
+ al_traverse_cb.
+
+ =item B<Convenience Operations>:
+
+ al_flatten,
+ al_copy.
+
+ =item B<Chunk Operations>:
+
+ al_chunk_len,
+ al_chunk_span,
+ al_chunk_ptr.
+
+ =item B<Error Handling>:
+
+ al_error.
+
+ =back
+
+ =head1 DESCRIPTION
+
+ B<OSSP al> defines an abstract type of a data buffer that can
+ assemble, move and truncate data but avoids actual copying.
+
+ It provides the following key features:
+
+ =over 4
+
+ =back
+
+ =head1 DATA TYPES
+
+ B<OSSP al> uses five data types in its API:
+
+ =over 4
+
+ =item B<al_rc_t> (Return Code Type)
+
+ This is an exported enumerated integer type with the following possible
+ values:
+
+ AL_OK Everything Ok
+ AL_ERR_ARG Invalid Argument
+ AL_ERR_MEM Not Enough Memory
+ AL_ERR_EOF End Of Communication
+ AL_ERR_INT Internal Error
+
+ =item B<al_t> (Assembly List Type)
+
+ This is an opaque data type representing a data buffer.
+ Only pointers to this abstract data type are used in the API.
+
+ =item B<al_tx_t> (Traversal Context Type)
+
+ This is an opaque data type representing a the state of a buffer
+ traversal operation. Only pointers to this abstract data type are
+ used in the API.
+
+ =item B<al_td_t> (Traversal Direction Type)
+
+ This is an exported enumerated integer type with the following possible
+ values:
+
+ AL_FORWARD traverse list from beginning to end
+ AL_BACKWARD traverse list from end to beginning
+
+ =item B<al_chunk_t> (Chunk Type)
+
+ This is an opaque data type representing a chunk of a buffer during
+ a traversal operation. Only pointers to this abstract data type are
+ used in the API. The B<al_chunk_t> type is used to generate a pointer
+ and byte count to access the data in the buffer.
+
+ =back
+
+ =head1 FUNCTIONS
+
+ B<OSSP al> provides a bunch of API functions, all modelled after the
+ same prototype: "C<al_rc_t> C<al_>I<name>C<(al_>[C<chunk>]C<_t *,>
+ ...C<)>". This means every function returns C<al_rc_t> to indicate its
+ success (C<AL_OK>) or failure (C<AL_ERR_XXX>) by returning a return code
+ (the corresponding describing text can be determined by passing this
+ return code to C<al_error>). Each function name starts with the common
+ prefix C<al_> and receives a C<al_t> (or C<al_chunk_t>) object on which
+ it operates as its first argument.
+
+ =head2 Assembly List Operations
+
+ =over 4
+
+ =item al_rc_t B<al_create>(al_t **I<alp>);
+
+ Create an assembly list abstraction object.
+ The object is stored in I<alp> on success.
+
+ Example: C<al_t *al; sa_create(&al);>
+
+ =item al_rc_t B<al_destroy>(al_t *I<al>);
+
+ Destroy an assembly list abstraction object.
+ The object I<al> is invalid after this call succeeded.
+
+ Example: C<al_destroy(al);>
+
+ =item al_rc_t B<al_append_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>);
+
+ Append I<n> bytes from a storage array at I<src> to the assembly list, the
+ bytes are copied, memory is allocated as necessary.
+
+ Example: C<al_append_bytes(al, "Goodbye cruel world\n", 20);>
+
+ =item al_rc_t B<al_prepend_bytes>(al_t *I<al>, const char *I<src>, size_t I<n>);
+
+ Prepend I<n> bytes from a storage array at I<src> to the assembly list, the
+ bytes are copied, memory is allocated as necessary.
+
+ Example: C<al_prepend_bytes(al, "Hello world\n", 12);>
+
+ =item al_rc_t B<al_attach_buffer>(al_t *I<al>, char *I<p>, size_t I<n>);
+
+ Attach the storage array starting at I<p> with size <n> at the end of
+ the assembly list. Its content will become part of the assembly list
+ and is subject to assembly list operations. The storage array must stay
+ in scope for the whole life time of the assembly list, there is no way
+ to detach it from the assembly list.
+
+ Example: C<char store[] = "foo\n"; al_attach_buffer(al, store, sizeof(store));>
+
+ =item al_rc_t B<al_splice>(al_t *I<al>, size_t I<off>, size_t I<n>, al_t *I<nal>, al_t *I<tal>);
+
+ This is the general data move operation modelled after the perl operator
+ B<splice>.
+
+ I<off> and I<n> are byte counts that define a span of bytes within the
+ source assembly list I<al>. These bytes are moved to the target list
+ I<tal> while the content of the new list I<nal> is moved to the source
+ to replace the selected span.
+
+ There are two deviations from the perl operator to avoid copying:
+
+ The move to the target list I<tal> appends the data to its end.
+ The move from the new list I<nal> removes the data from its origin.
+
+ The target list I<tal> may be B<NULL>, the data bytes that would
+ be moved to the target are then discard. This avoids creation
+ and destruction of a dummy target.
+
+ The new list I<nal> may be B<NULL>, then nothing is inserted into
+ the source. This avoids creation and destruction of an empty list.
+
+ Examples:
+
+ al_t *source;
+ al_t *insertion;
+ al_t *buffer;
+
+ al_create(&source);
+ al_create(&insertion);
+ al_create(&buffer);
+
+ al_append_bytes(source, "Hello world\n", 12);
+ al_append_bytes(insertion, "Goodbye cruel", 13);
+
+ al_splice(source, 0, 5, insertion, buffer);
+
+ The buffer now holds the string "Hello".
+ The source now holds the string "Goodbye cruel world\n".
+ The insertion is now empty.
+
+ al_append_bytes(insertion, "brave", 5);
+ al_splice(source, 8, 5, insertion, NULL);
+
+ The source now holds the string "Goodbye brave world\n".
+ The insertion is now empty.
+
+ al_append_bytes(insertion, "B", 1);
+ al_splice(source, 0, 8, NULL, buffer);
+ al_splice(source, 0, 1, insertion, NULL);
+ al_append_bytes(insertion, "\n", 1);
+ al_splice(buffer, al_bytes(buffer)-1, 1, insertion, NULL),
+
+ The source now holds the string "Brave world\n".
+ The buffer now holds the string "HelloGoodbye\n".
+ The insertion is empty.
+
+ =item size_t B<al_bytes>(const al_t *I<al>);
+
+ Returns the number of bytes stored in the assembly list.
+
+ Example: C<al_t *al; size_t count; count = al_bytes(al);>
+
+ =back
+
+ =head2 Traversal Operations
+
+ =over 4
+
+ =item al_rc_t B<al_txalloc>(al_t *I<al>, al_tx_t **txp);
+
+ Allocate a traversal context.
+
+ Example: C<al_tx_t *tx; al_txalloc(&tx);>
+
+ =item al_rc_t B<al_free>(al_t *I<al>, al_tx_t *tx);
+
+ Free a traversal context.
+
+ Example: C<al_tx_t *tx; al_txfree(tx);>
+
+ =item al_rc_t B<al_traverse>(al_t *I<al>, size_t I<off>, size_t I<n>, al_td_t I<dir>, al_tx_t *I<tx>);
+
+ Start traversing the assembly list I<al> beginning at byte offset I<off>
+ for up to I<n> bytes in direction I<dir>. The state of the traversal is
+ stored in the supplied context I<tx>.
+
+ This function fails when the offset is outside the assembly list bounds.
+
+ =item al_rc_t B<al_traverse_next>(al_t *I<al>, al_tx_t *I<tx>, al_chunk_t **I<alcp>);
+
+ Complete a traversal step on the assembly list I<al> using the initialized
+ context I<tx>. In each step a chunk descriptor is filled and stored in
+ I<alcp>. All bytes of the chunk are guaranteed to be stored in a flat
+ array and can be accessed through the chunk operations described below.
+
+ The function returns AL_ERR_EOF when it passes the end (or beginning
+ in case of backward traversal) of the list.
+
+ =item al_rc_t B<al_traverse_cb>(al_t *I<al>, size_t I<off>, size_t I<n>, al_td_t I<dir>, al_rc_t (*I<cb>)(al_chunk_t *, void *), void *u);
+
+ B<al_traverse_cb> is a wrapper function that does a full list traversal in
+ a single call. In every step a chunk descriptor is passed to the callback
+ function I<cb> together with a user supplied pointer I<u>. When the
+ callback function returns anything but AL_OK the traversal is aborted
+ and B<al_traverse_cb> returns with that result code.
+
+ =back
+
+ =head2 Convenience Operations
+
+ =over 4
+
+ =item al_rc_t B<al_flatten>(al_t *I<al>, size_t I<off>, size_t I<n>, char *I<dst>, size_t *I<lenp>);
+
+ I<off> and I<n> are byte counts that define a span of bytes with the
+ assembly list I<al>. These bytes are copied to the storage array I<dst>
+ which must be sized appropriately.
+ I<off> must be a valid offset, I<n> must be positive but may exceed
+ the size of the assembly list.
+ The actual number of bytes that is copied to the destination is stored
+ in I<lenp>.
+
+ Example:
+
+ al_t *al;
+ char buffer[42];
+ size_t actual;
+
+ al_flatten(al, 500, 42, buffer, &actual);
+
+ =item al_rc_t B<al_copy>(al_t *I<al>, size_t I<off>, size_t I<n>, al_t *I<tal);
+
+ I<off> and I<n> are byte counts that define a span of bytes within the
+ assembly list I<al>. These bytes are appended to the target list I<tal>,
+ memory is allocated as necessary.
+ I<off> must be a valid offset, I<n> must be positive but may exceed
+ the size of the assembly list.
+
+ Example:
+
+ al_t *al;
+ al_t *tal;
+
+ al_create(&tal);
+ al_flatten(al, 500, 42, tal);
+
+ =back
+
+ =head2 Chunk Operations
+
+ =over 4
+
+ =item size_t B<al_chunk_len>(al_chunk_t *I<alc>);
+
+ Returns the number of bytes in a chunk.
+
+ =item size_t B<al_chunk_span>(al_chunk_t *I<alc>, size_t I<off>, size_t I<n>);
+
+ I<off> and I<n> are byte counts that define a span of bytes.
+ B<al_chunk_span> returns the number of bytes that are stored in the chunk.
+ I<off> must be a valid offset, I<n> must be positive but may exceed
+ the size of the chunk.
+
+ =item char *B<al_chunk_ptr>(al_chunk_t *I<alc>, size_t I<off>);
+
+ Returns the pointer to the byte at offset I<off> within the chunk I<alc>.
+ I<off> must be positive and must not exceed the size of the chunk.
+ Since all bytes of the chunk are guaranteed to be stored in a flat
+ array the pointer can be used to reference every byte within the chunk.
+
+ Example:
+
+ al_chunk_t *alc;
+ char *start, *end;
+
+ start = al_chunk_ptr(alc, 0);
+ end = start + al_chunk_len(alc) - 1;
+
+ =back
+
+ =head2 Error Handling
+
+ =over 4
+
+ =item const char *B<al_error>(al_rc_t I<rv>);
+
+ =back
+
+ =head1 SEE ALSO
+
+ =head1 HISTORY
+
+ B<OSSP al> was invented in October 2002 by Michael van Elst
+ E<lt>mlelstv@dev.de.cw.netE<gt> for use inside the OSSP project.
+
+ =head1 AUTHORS
+
+ Michael van Elst
+ mlelstv@dev.de.cw.net
+
+ =cut
+
|
