alenlist_ops(D3X)

NAME
      alenlist_ops:  alenlist_append, alenlist_clear, alenlist_create,
     alenlist_cursor_create, alenlist_cursor_destroy, alenlist_cursor_init,
     alenlist_cursor_offset, alenlist_destroy, alenlist_get, alenlist_size,
     kvaddr_to_alenlist, uvaddr_to_alenlist, buf_to_alenlist - operations on
     address/length lists

SYNOPSIS
     #include <sys/types.h>
     #include <sys/alenlist.h>
     #include <sys/ddi.h>

     alenlist_t
     alenlist_create(unsigned flags);

     void
     alenlist_clear(alenlist_t plist);

     void
     alenlist_destroy(alenlist_t plist);

     int
     alenlist_size(alenlist_t plist);

     alenlist_cursor_t
     alenlist_cursor_create(alenlist_t plist, unsigned flags);

     void
     alenlist_cursor_destroy(alenlist_cursor_t ocursor);

     int
     alenlist_get(alenlist_t plist,
               alenlist_cursor_t icursor,
               size_t maxlength,
               alenaddr_t *paddr,
               size_t *plength,
               unsigned flags);

     int
     alenlist_cursor_init(alenlist_t plist,
               size_t offset,
               alenlist_cursor_t icursor);

     size_t
     alenlist_cursor_offset(alenlist_t plist, alenlist_cursor_t icursor);

     int
     alenlist_append(alenlist_t plist,
               alenaddr_t address,
               size_t length,
               unsigned flags);
     alenlist_t
     kvaddr_to_alenlist(alenlist_t plist,
               caddr_t kvaddr,
               size_t length,
               unsigned flags);

     alenlist_t
     uvaddr_to_alenlist( alenlist_t plist,
               uvaddr_t uvaddr,
               size_t length,
               unsigned flags);

     alenlist_t
     buf_to_alenlist(alenlist_t plist,
               struct buf *buf,
               unsigned flags);

   Arguments
     address     An address in some address space.

     buf         Address of a buf struct.

     flags       A Boolean combination of the flags declared in
                 sys/alenlist.h.

     icursor     A handle to an existing cursor, or NULL to indicate the
                 implicit cursor in plist.

     kvaddr      A valid address in kernel virtual memory.

     length      The length related to an address.

     maxlength   The maximum length allowed in the returned address/length
                 pair, or 0 to indicate no maximum applies.

     ocursor     A handle to an existing cursor, the target of the operation.

     offset      An initial byte offset for icursor, usually 0.

     paddr       A pointer to a variable to receive the address from an
                 address/length pair.

     plength     A pointer to a variable to receive the length from an
                 address/length pair.

     plist       A handle to an existing alenlist.

     uvaddr      A valid address in user virtual memory for the in-context
                 process.

DESCRIPTION
     For an overview of address/length lists (alenlists) see alenlist(D4X).

   Allocation and Release
     Create an empty list using alenlist_create().  The AL_NOSLEEP flag
     ensures that the caller will not sleep waiting for memory.  If memory
     cannot be allocated, NULL is returned.  The returned list has no pairs in
     it, and its implicit cursor is initialized to point to the start of the
     (empty) list.

     The functions kvaddr_to_alenlist(), uvaddr_to_alenlist(), and
     buf_to_alenlist(), when the plist argument is NULL, allocate a new
     alenlist and return it.  However, these functions do not honor
     AL_NOSLEEP, either when creating a list or when getting memory to extend
     an existing list.  If it is important not to sleep, preallocate the list.

     Empty a list by applying alenlist_clear().  The implicit cursor is reset
     to the start of the (empty) list.

     Release a list using alenlist_destroy().  This lets the system know that
     the specified List is no longer in use.

     Create a cursor by calling alenlist_cursor_create().  Pass AL_NOSLEEP to
     avoid sleeping on memory allocation.  When a cursor cannot be created,
     NULL is returned.  The new cursor is associated with plist and is
     initialized to point to the head of that list.  More than one cursor can
     point to a given list.

     Use alenlist_cursor_destroy() to tell the system the cursor is no longer
     needed.  The cursor must not be used after this call is made.

   Reading a List
     Use the alenlist_get() function to retrieve pairs from the list.  An
     address/length pair from plist is stored based on paddr and plength.  The
     pair to retrieve is established by a cursor, either icursor or the
     implicit cursor in plist when icursor is NULL.  The cursor used is
     updated by the length returned, provided the AL_LEAVE_CURSOR flag is not
     used.

     It is not necessary to read out exactly the pairs that were added to the
     list.  When maxlength is nonzero, it establishes the maximum length
     retrieved.  When maxlength is also an integral power of 2, the returned
     length is further constrained so that the returned address and length do
     not cross a maxlength boundary.  For example, when maxlength is 512, the
     address/length values returned are such that the next pair returned will
     begin on a 512-boundary.

     Returns ALENLIST_SUCCESS or ALENLIST_FAILURE.  The normal cause for
     failure is that the list is exhausted.

     Call alenlist_cursor_init() to initialize a cursor to a specified offset
     (usually 0).  If cursorp is NULL, the implicit internal cursor of plist
     is initialized.

     To retrieve the current byte offset of a cursor, call
     alenlist_cursor_offset().  When icursor is NULL, the offset of the
     implicit cursor in plist is returned.

     Call alenlist_size() to determine the number of address/length pairs in
     the list.

   Loading a List
     The basic operation to add an address/length pair to a list is
     alenlist_append().  The list is expanded if necessary.  Use the
     AL_NOSLEEP flag to prevent sleeping on memory allocation that might be
     necessary to resize the list.  Use AL_NOCOMPACT to prevent the added pair
     from being merged into a logically-adjacent preceding pair.  Returns
     ALENLIST_SUCCESS or ALENLIST_FAILURE.

     To build an alenlist that describes a buffer in kernel virtual memory,
     call kvaddr_to_alenlist().  The specified kernel virtual address is
     converted into a list of physical address/length pairs and the pairs are
     appended to an alenlist.  A handle to the alenlist is returned.  When
     plist is NULL, a new list is created, and this list is returned.

     To build an alenlist that describes a buffer in user virtual memory, call
     uvaddr_to_alenlist().  The specified user virtual address for the
     specified length is converted into a list of physical address/length
     pairs and the pairs are appended to an alenlist.  A handle to the
     alenlist is returned.  When plist is NULL, a new list is created, and
     this list is returned.

     To build an alenlist that describes a buffer mapped by a buf structure,
     call buf_to_alenlist().  The memory described by the buf is converted
     into a list of physical address/length pairs and the pairs are appended
     to an alenlist.  A handle to the alenlist is returned.  When plist is
     NULL, a new list is created, and this list is returned.

SEE ALSO
     alenlist(D4X), IRIX Device Driver Programmer's Guide