VxWorks Reference Manual : Libraries
lstLib - doubly linked list subroutine library
lstInit( ) - initialize a list descriptor
lstAdd( ) - add a node to the end of a list
lstConcat( ) - concatenate two lists
lstCount( ) - report the number of nodes in a list
lstDelete( ) - delete a specified node from a list
lstExtract( ) - extract a sublist from a list
lstFirst( ) - find first node in list
lstGet( ) - delete and return the first node from a list
lstInsert( ) - insert a node in a list after a specified node
lstLast( ) - find the last node in a list
lstNext( ) - find the next node in a list
lstNth( ) - find the Nth node in a list
lstPrevious( ) - find the previous node in a list
lstNStep( ) - find a list node nStep steps away from a specified node
lstFind( ) - find a node in a list
lstFree( ) - free up a list
This subroutine library supports the creation and maintenance of a doubly linked list. The user supplies a list descriptor (type LIST) that will contain pointers to the first and last nodes in the list, and a count of the number of nodes in the list. The nodes in the list can be any user-defined structure, but they must reserve space for two pointers as their first elements. Both the forward and backward chains are terminated with a NULL pointer.
The linked-list library simply manipulates the linked-list data structures; no kernel functions are invoked. In particular, linked lists by themselves provide no task synchronization or mutual exclusion. If multiple tasks will access a single linked list, that list must be guarded with some mutual-exclusion mechanism (e.g., a mutual-exclusion semaphore).
--------- -------- -------- | head--------------->| next----------->| next--------- | | | | | | | | | ------- prev |<---------- prev | | | | | | | | | | | tail------ | | ... | ----->| ... | | | | | v | v |count=2| | ----- | ----- --------- | --- | --- | - | - | | ------------------------
----------- | head------------------ | | | | tail---------- | | | | v | count=0 | ----- ----- ----------- --- --- - -
lstLib.h
lstInit( ) - initialize a list descriptor
void lstInit ( LIST * pList /* ptr to list descriptor to be initialized */ )
This routine initializes a specified list to an empty list.
N/A
lstAdd( ) - add a node to the end of a list
void lstAdd ( LIST * pList, /* pointer to list descriptor */ NODE * pNode /* pointer to node to be added */ )
This routine adds a specified node to the end of a specified list.
N/A
lstConcat( ) - concatenate two lists
void lstConcat ( LIST * pDstList, /* destination list */ LIST * pAddList /* list to be added to dstList */ )
This routine concatenates the second list to the end of the first list. The second list is left empty. Either list (or both) can be empty at the beginning of the operation.
N/A
lstCount( ) - report the number of nodes in a list
int lstCount ( LIST * pList /* pointer to list descriptor */ )
This routine returns the number of nodes in a specified list.
The number of nodes in the list.
lstDelete( ) - delete a specified node from a list
void lstDelete ( LIST * pList, /* pointer to list descriptor */ NODE * pNode /* pointer to node to be deleted */ )
This routine deletes a specified node from a specified list.
N/A
lstExtract( ) - extract a sublist from a list
void lstExtract ( LIST * pSrcList, /* pointer to source list */ NODE * pStartNode, /* first node in sublist to be extracted */ NODE * pEndNode, /* last node in sublist to be extracted */ LIST * pDstList /* ptr to list where to put extracted list */ )
This routine extracts the sublist that starts with pStartNode and ends with pEndNode from a source list. It places the extracted list in pDstList.
N/A
lstFirst( ) - find first node in list
NODE *lstFirst ( LIST * pList /* pointer to list descriptor */ )
This routine finds the first node in a linked list.
A pointer to the first node in a list, or NULL if the list is empty.
lstGet( ) - delete and return the first node from a list
NODE *lstGet ( LIST * pList /* ptr to list from which to get node */ )
This routine gets the first node from a specified list, deletes the node from the list, and returns a pointer to the node gotten.
A pointer to the node gotten, or NULL if the list is empty.
lstInsert( ) - insert a node in a list after a specified node
void lstInsert ( LIST * pList, /* pointer to list descriptor */ NODE * pPrev, /* pointer to node after which to insert */ NODE * pNode /* pointer to node to be inserted */ )
This routine inserts a specified node in a specified list. The new node is placed following the list node pPrev. If pPrev is NULL, the node is inserted at the head of the list.
N/A
lstLast( ) - find the last node in a list
NODE *lstLast ( LIST * pList /* pointer to list descriptor */ )
This routine finds the last node in a list.
A pointer to the last node in the list, or NULL if the list is empty.
lstNext( ) - find the next node in a list
NODE *lstNext ( NODE * pNode /* ptr to node whose successor is to be found */ )
This routine locates the node immediately following a specified node.
A pointer to the next node in the list, or NULL if there is no next node.
lstNth( ) - find the Nth node in a list
NODE *lstNth ( LIST * pList, /* pointer to list descriptor */ int nodenum /* number of node to be found */ )
This routine returns a pointer to the node specified by a number nodenum where the first node in the list is numbered 1. Note that the search is optimized by searching forward from the beginning if the node is closer to the head, and searching back from the end if it is closer to the tail.
A pointer to the Nth node, or NULL if there is no Nth node.
lstPrevious( ) - find the previous node in a list
NODE *lstPrevious ( NODE * pNode /* ptr to node whose predecessor is to be found */ )
This routine locates the node immediately preceding the node pointed to by pNode.
A pointer to the previous node in the list, or NULL if there is no previous node.
lstNStep( ) - find a list node nStep steps away from a specified node
NODE *lstNStep ( NODE * pNode, /* the known node */ int nStep /* number of steps away to find */ )
This routine locates the node nStep steps away in either direction from a specified node. If nStep is positive, it steps toward the tail. If nStep is negative, it steps toward the head. If the number of steps is out of range, NULL is returned.
A pointer to the node nStep steps away, or NULL if the node is out of range.
lstFind( ) - find a node in a list
int lstFind ( LIST * pList, /* list in which to search */ NODE * pNode /* pointer to node to search for */ )
This routine returns the node number of a specified node (the first node is 1).
The node number, or ERROR if the node is not found.
lstFree( ) - free up a list
void lstFree ( LIST * pList /* list for which to free all nodes */ )
This routine turns any list into an empty list. It also frees up memory used for nodes.
N/A