list.h File Reference

Functions to implement a list. More...

#include "errorcodes.h"
#include <stdlib.h>

Go to the source code of this file.

Data Structures
struct	list_node
	structure that is a single list node More...
struct	list
	structure to contain list information More...
Defines
#define	LIST_FOUND   1
	a macro for the found return value in a match function
#define	LIST_NOT_FOUND   0
	a macro for the not found return value in a match function
#define	LIST_FATAL   -1
	a macro for the fatal error return value in a match function
Typedefs
typedef list_node	list_node_t
	typedef for the list_node structure
typedef list	list_t
	typedef for the list structure
Functions
errorcode	list_init (list_t *list)
	initializes the list
errorcode	list_destroy (list_t *list, void(*func)(void *, void *), void *arg)
	deletes all entries from a list
errorcode	list_add (list_t *list, void *item)
	adds an item to the list
errorcode	list_find (list_t *list, int(*func)(void *, void *), void *arg, void **found_item)
	finds an item and returns a pointer to it through an argument. matches the item by a user specified function
errorcode	list_get (list_t *list, int index, void **item)
	gets the next item in the list after the index passed in
errorcode	list_remove (list_t *list, int(*func)(void *, void *), void *arg)
	removes an item from the list, matching the item by the user specified function
int	list_count (list_t *list)
	gets the number of items in the list
Variables
list_node	packed
	structure that is a single list node

---

Detailed Description

Functions to implement a list.

Author:

Daniel Ferullo (ferullo@cmu.edu)

Definition in file list.h.

---

Function Documentation

errorcode list_add (  list_t *  list, void *  item )

adds an item to the list Parameters: list  a pointer to the list to add the item to item  the item to add to the list Returns: SUCCESS, errorcode on failure Definition at line 134 of file list.c. References errorcode, list::head, list_node::item, list::last_get, list::last_get_num, list_node_t, list_t, list_node::next, and list::size. Referenced by connlist_add().

int list_count (  list_t *  list  )

gets the number of items in the list Parameters: list  a pointer to the list to get the item count from Returns: the number of items, neg on failure Definition at line 208 of file list.c. References list_t, and list::size. Referenced by connlist_count().

errorcode list_destroy (  list_t *  list, void(*)(void *, void *)  func, void *  arg )

deletes all entries from a list Use of the list functions after this function is called is undefined Parameters: list  a pointer to the list to destroy func  a function pointer to a user defined function that will clean up each item if cleanup is necessary. If no cleanup is needed, NULL can be supplied by the user. This function must be of the form void func(void*,void*) where the first argument is the current argument to cleanup, and the second is the user defined argument that is passed in as the third argument to this function. arg  the one argument allowed to the user defined cleanup function Returns: SUCCESS, errorcode on failure Definition at line 42 of file list.c. References errorcode, list::head, list_node::item, list_node_t, list_t, list_node::next, and safe_free().

errorcode list_find (  list_t *  list, int(*)(void *, void *)  func, void *  arg, void **  found_item )

finds an item and returns a pointer to it through an argument. matches the item by a user specified function The first item that matches will be returned Parameters: list  a pointer to the list to find in func  a function pointer to the function to match with to find the item to remove. Ths function must be of the form int func(void*,void*)) where it returns LIST_FOUND when the item is found, LIST_NOT_FOUND on not found and LIST_FATAL on "fatal error, stop looking". The first parameter to the function is the item in the list, and the second is an optional user defined argument (which is the third argument to this find function). arg  the optional func argument found_item  a pointer to a location to fill in the found item in. If the function returns error, this value is undefined. Returns: SUCCESS (item found) errorcode on failure/not find Definition at line 64 of file list.c. References errorcode, list::head, list_node::item, LIST_FATAL, LIST_FOUND, list_node_t, LIST_NOT_FOUND, list_t, and list_node::next. Referenced by connlist_find().

errorcode list_get (  list_t *  list, int  index, void **  item )

gets the next item in the list after the index passed in an index is a integer which indexes into the list like it is an array. So, an index of 0 is the first element. If the index is negative, or higher than the number of elements, an error is returned. Make no assumptions about what item should be located at a given location, only assume that if this function is called in succession without other list functions called in between then the entire list will be returned with no duplicates. Parameters: list  a pointer to the list to get an item from index  to an item to get item  a pointer to a pointer that will be filled in with the returned item upon success Returns: SUCCESS, errorcode on failure Definition at line 96 of file list.c. References errorcode, list::head, list_node::item, list::last_get, list::last_get_num, list_node_t, list_t, list_node::next, and list::size.

errorcode list_init (  list_t *  list  )

initializes the list Use of the list functions before this function is called is undefined Parameters: list  a pointer to the list the initalize Returns: SUCCESS, errorcode on failure Definition at line 29 of file list.c. References errorcode, list::head, list::last_get, list::last_get_num, list_t, and list::size. Referenced by connlist_init().

errorcode list_remove (  list_t *  list, int(*)(void *, void *)  func, void *  arg )

removes an item from the list, matching the item by the user specified function Only the first item that matches will be removed Parameters: list  a pointer to the list to remove from func  a function pointer to the function to match with to find the item to remove. This function must be of the form int func(void*,void*) where it return LIST_FOUND when the item is found, LIST_NOT_FOUND on not found, and LIST_FATAL on "fatal error, stop looking". The first parameter to the function is the item from the list, and the second is an optional user defined argument (this is the third argument to this remove function). arg  the optional func argument Returns: SUCCESS (removal or item not found), errorcode on failure Definition at line 160 of file list.c. References errorcode, list::head, list_node::item, list::last_get, list::last_get_num, LIST_FATAL, LIST_FOUND, list_node_t, LIST_NOT_FOUND, list_t, list_node::next, safe_free(), and list::size. Referenced by connlist_forget().

---