listhash/list_new.3.in

   1 .TH @LISTHASH_PREFIX@_list_new 3 "Jan 2000" "University of Illinois" "C Library Calls"
   2 \" @configure_input@
   3 .SH NAME
   4 @LISTHASH_PREFIX@_list_new, @LISTHASH_PREFIX@_list_free, @LISTHASH_PREFIX@_list_next,
   5 @LISTHASH_PREFIX@_list_prev, @LISTHASH_PREFIX@_list_add, @LISTHASH_PREFIX@_list_del,
   6 @LISTHASH_PREFIX@_list_search, @LISTHASH_PREFIX@_list_dup, @LISTHASH_PREFIX@_list_merge,
   7 @LISTHASH_PREFIX@_list_add_str \- linked list routines
   8 .SH SYNOPSIS
   9 .B #include <@LISTHASH_PREFIX@.h>
  10 .P
  11 .BI "@LISTHASH_PREFIX@_list_t *@LISTHASH_PREFIX@_list_new(int " flags ","
  12 .BI "int (*" cmpfunc ")());"
  13 .br
  14 .BI "void @LISTHASH_PREFIX@_list_free(@LISTHASH_PREFIX@_list_t *" l ", void (*" freefunc ")());"
  15 .br
  16 .BI "int @LISTHASH_PREFIX@_list_add_str(@LISTHASH_PREFIX@_list_t *" l ", char *" str ","
  17 .BI "char *" delim ");"
  18 .br
  19 .BI "int @LISTHASH_PREFIX@_list_add(@LISTHASH_PREFIX@_list_t *" l ", void *" data ");"
  20 .br
  21 .BI "void @LISTHASH_PREFIX@_list_del(@LISTHASH_PREFIX@_list_t *" l ", @LISTHASH_PREFIX@_node_t **" n ");"
  22 .br
  23 .BI "int @LISTHASH_PREFIX@_list_search(@LISTHASH_PREFIX@_list_t *" l ", @LISTHASH_PREFIX@_node_t **" n ","
  24 .BI "void *" data ", int (*" matchfunc ")());"
  25 .br
  26 .BI "int @LISTHASH_PREFIX@_list_next(@LISTHASH_PREFIX@_list_t *" l ", @LISTHASH_PREFIX@_node_t **" n ");"
  27 .br
  28 .BI "int @LISTHASH_PREFIX@_list_prev(@LISTHASH_PREFIX@_list_t *" l ", @LISTHASH_PREFIX@_node_t **" n ");"
  29 .br
  30 .BI "@LISTHASH_PREFIX@_list_t *@LISTHASH_PREFIX@_list_dup(@LISTHASH_PREFIX@_list_t *" l ");"
  31 .br
  32 .BI "@LISTHASH_PREFIX@_list_t *@LISTHASH_PREFIX@_list_merge(int (*" cmpfunc ")(), int " flags ","
  33 .BI "@LISTHASH_PREFIX@_list_t *" list1 ", @LISTHASH_PREFIX@_list_t *" list2 ");"
  34 .SH DESCRIPTION
  35 The \fB@LISTHASH_PREFIX@_list_new\fP() function creates a new list.  The \fIflags\fP
  36 argument must be one of the following values:
  37 .IP \fBLIST_USERFUNC\fP
  38 The \fIcmpfunc\fP argument points to a user-supplied function which
  39 determines the ordering of the list.
  40 .IP \fBLIST_STACK\fP
  41 Use the list as a stack.  New elements are added to the front of the list.
  42 .IP \fBLIST_QUEUE\fP
  43 Use the list as a queue.  New elements are added to the end of the list.
  44 .PP
  45 The \fB@LISTHASH_PREFIX@_list_free\fP() function deallocates all memory associated
  46 with the list \fIl\fP.  If \fIfreefunc\fP is not \fINULL\fP, it is called
  47 to free memory associated with each node in the list.
  48
  49 The \fB@LISTHASH_PREFIX@_list_add\fP() function adds the element pointed to by
  50 \fIdata\fP to the list \fIl\fP.  The position of the new element will
  51 be determined by the flags passed to \fB@LISTHASH_PREFIX@_list_new\fP() when the
  52 list was created.
  53
  54 The \fB@LISTHASH_PREFIX@_list_add_str\fP() function tokenizes the string \fIstr\fP
  55 using the delimiter characters in the string \fIdelim\fP.  The resulting
  56 tokens are added to list \fIl\fP using \fB@LISTHASH_PREFIX@_list_add\fP().
  57
  58 The \fB@LISTHASH_PREFIX@_list_search\fP() function searches for an element which
  59 matches \fIdata\fP using the matching function \fImatchfunc\fP.  If
  60 \fImatchfunc\fP is \fINULL\fP, a default matching function designed for
  61 ASCII strings is used.  Searching begins from the node pointed to by
  62 \fIn\fP.
  63
  64 The \fB@LISTHASH_PREFIX@_list_del\fP() function removes the entry pointed to by
  65 \fIn\fP from the list pointed to by \fIl\fP.
  66
  67 The \fB@LISTHASH_PREFIX@_list_dup\fP() function creates a copy of the list \fIl\fP
  68 using dynamically allocated memory.
  69
  70 The \fB@LISTHASH_PREFIX@_list_merge\fP() function creates a new
  71 list with \fIflags\fP and \fIcmpfunc\fP, in the same way as
  72 \fB@LISTHASH_PREFIX@_list_new\fP().  It then adds all elements from \fIlist1\fP
  73 and \fIlist2\fP using \fB@LISTHASH_PREFIX@_list_add\fP().
  74 .SH RETURN VALUE
  75 The \fB@LISTHASH_PREFIX@_list_new\fP(), \fB@LISTHASH_PREFIX@_list_dup\fP(), and
  76 \fB@LISTHASH_PREFIX@_list_merge\fP() functions return a pointer to the new list
  77 structure, or \fINULL\fP on error.
  78
  79 The \fB@LISTHASH_PREFIX@_list_next\fP(), \fB@LISTHASH_PREFIX@_list_prev\fP(), and
  80 \fB@LISTHASH_PREFIX@_list_search\fP() functions return 1 when valid data is
  81 returned, or 0 otherwise.
  82
  83 The \fB@LISTHASH_PREFIX@_list_add\fP() and \fB@LISTHASH_PREFIX@_list_add_str\fP() functions
  84 return 0 on success, or \-1 on error.
  85 .SH SEE ALSO
  86 .BR @LISTHASH_PREFIX@_hash_new (3)