← Back to branch summary

~ubuntu-branches/ubuntu/utopic/gridengine/utopic

« back to all changes in this revision

Viewing changes to doc/htmlman/htmlman3/lListFuncs.html

  • Committer: Bazaar Package Importer
  • Author(s): Mark Hymers
  • Date: 2008-06-25 22:36:13 UTC
  • Revision ID: james.westby@ubuntu.com-20080625223613-tvd9xlhuoct9kyhm
Tags: upstream-6.2~beta2
Import upstream version 6.2~beta2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/htmlman/htmlman3/lListFuncs.html
 
1
<HTML>
 
2
<BODY BGCOLOR=white>
 
3
<PRE>
 
4
<!-- Manpage converted by man2html 3.0.1 -->
 
5
NAME
 
6
     lCreateList,  lFreeList,  lCopyList,  lAddList,  lPSortList,
 
7
     lDumpList,  lUndumpList, lWriteList, lWriteListTo, lGetList-
 
8
     Name, lGetListDescr, lGetNumberOfElem
 
9
 
 
10
     generic list manipulation and information functions
 
11
 
 
12
SYNOPSIS
 
13
     #include "cull.h"
 
14
 
 
15
     lList* lCreateList( char *listname, lDescr *descriptor );
 
16
 
 
17
     lList* lCreateElemList( char *listname, lDescr  *descriptor,
 
18
     int n );
 
19
 
 
20
     lList* lFreeList( lList *list );
 
21
 
 
22
     lList* lCopyList( char *listname, lList *list );
 
23
 
 
24
     void lAddList( lList *list1, lList *list2 );
 
25
 
 
26
     int lPSortList( lList *list, char *orderstring, ... );
 
27
 
 
28
     int lDumpList( FILE *file, lList *list, int indent );
 
29
 
 
30
     lList* lUndumpList(
 
31
          FILE *file,
 
32
          char *newname,
 
33
          lDescr *descriptor
 
34
     );
 
35
 
 
36
     void lWriteList( lList *list );
 
37
 
 
38
     void lWriteListTo( lList *list, FILE *fp );
 
39
 
 
40
     char* lGetListName( lList *list );
 
41
 
 
42
     lDescr* lGetListDescr( lList *list );
 
43
 
 
44
     int lGetNumberOfElem( lList *list );
 
45
 
 
46
     int lGetNumberOfRemainingElem( lListElem *elem );
 
47
 
 
48
DESCRIPTION
 
49
     lCreateList
 
50
          gets the new name of the list to  be  created  and  its
 
51
          descriptor  which  enumerates  the  fields (name,type),
 
52
          that a list element will contain.  The memory  for  the
 
53
          list  is dynamically created and a pointer to the newly
 
54
          created list is returned.  If one of the  arguments  is
 
55
          NULL or if the descriptor contains no fields the return
 
56
          value of <I>lCreateList</I> is NULL. This is also true for any
 
57
          error  that  might  occur.  The list must be freed with
 
58
          <I>lFreeList</I> when the list is no longer used (all  associ-
 
59
          ated sub-lists and strings are also freed).
 
60
 
 
61
     lCreateElemList
 
62
          gets the new name of the list to  be  created  and  its
 
63
          descriptor  which  enumerates  the  fields (name,type),
 
64
          that a list element will contain.  The  third  argument
 
65
          specifies the number of elements that shall be created.
 
66
          The memory for the list is dynamically  created  and  a
 
67
          pointer  to the newly created list is returned.  If one
 
68
          of the arguments is NULL, if the descriptor contains no
 
69
          fields  or  if creation of all requested elements fails
 
70
          the return value of <I>lCreateElemList</I> is  NULL.  This  is
 
71
          also  true  for  any  error that might occur.  The list
 
72
          must be freed with <I>lFreeList</I> when the list is no longer
 
73
          used  (all  associated  sub-lists  and strings are also
 
74
          freed).
 
75
 
 
76
     lFreeList
 
77
          gets as argument a pointer to a generic  list.  If  the
 
78
          list  pointer is NULL the function simply returns, oth-
 
79
          erwise the list, all its sub-lists and its strings  are
 
80
          freed.
 
81
 
 
82
     lCopyList
 
83
          copies an existing generic list with all its sub-lists.
 
84
          The  required memory is allocated by <I>lCopyList</I> and must
 
85
          be released via <I>lFreeList</I> if  the  copied  list  is  no
 
86
          longer  used.   The  first argument to lCopyList is the
 
87
          name of the copied list,  the  second  argument  is  an
 
88
          existing  list.   In  case  of success a pointer to the
 
89
          copied list is returned. Otherwise the return value  is
 
90
          NULL.
 
91
 
 
92
     lAddList
 
93
          concatenates two generic lists. The first  argument  is
 
94
          the  list which is expanded. The second argument is the
 
95
          list that is added to the first list.  The  descriptors
 
96
          of  both  lists  have  to be equal. After appending the
 
97
          elements of the second list  to  the  first  list,  the
 
98
          second list gets destroyed.
 
99
 
 
100
     lPSortList
 
101
          sorts a given list corresponding to a given sort order.
 
102
          The  first  argument  is the generic list to be sorted,
 
103
          the second argument is the sort order  string  and  the
 
104
          following  variable  argument list specifies the fields
 
105
          which act as sorting keys.  lPSortList  returns  -1  in
 
106
          case of error, 0 otherwise.
 
107
          The sort order string has the following syntax:
 
108
 
 
109
               sort order string = %I{+|-} [%I{+|-}...]
 
110
 
 
111
          %I  stands  for  the   field   and   +/-   stands   for
 
112
          ascending/descending sorting order
 
113
          for every percent sign there is one 'fieldname' in  the
 
114
          variable argument list, %I stands for the field and +/-
 
115
          stands for ascending/descending sorting order.
 
116
 
 
117
          The following example may show the usage:
 
118
 
 
119
               lPSortList( list, "%I+ %I-", field1, field2 );
 
120
 
 
121
     lDumpList
 
122
          writes a generic list and all its sub-lists to a  file.
 
123
          The  first argument is a FILE pointer, the second argu-
 
124
          ment is a generic list pointer and the  third  argument
 
125
          is the number of indentation units for the lines in the
 
126
          list file (for better readability).
 
127
 
 
128
     lUndumpList
 
129
          read a dumped list and all its sub-lists  from  a  dump
 
130
          file.   The  first  argument is the FILE pointer of the
 
131
          dump file. The second argument is the program  internal
 
132
          name of the read in list or the name of the list in the
 
133
          dump file if NULL is specified. The third  argument  is
 
134
          the  descriptor  of the new list or the list descriptor
 
135
          stored in the dump file if NULL is  specified.  If  the
 
136
          new  list  descriptor  is a subset of the descriptor in
 
137
          the dump file the obsolete fields  are  skipped  and  a
 
138
          warning  message  is  displayed.  If  additional fields
 
139
          occur in the new descriptor they remain unchanged (i.e.
 
140
          they  keep  their creation time value).  If <I>lUndumpList</I>
 
141
          is successful, a generic list is created and  the  list
 
142
          pointer  is  returned.  Otherwise  the  return value is
 
143
          NULL.
 
144
 
 
145
     lWriteList
 
146
          writes a generic list and all its sub-lists if Monitor-
 
147
          ing  Level  CULL_LAYER is set to info. The generic list
 
148
          pointer is the only  function  argument.  If  the  list
 
149
          pointer  is  NULL  the  function displays a warning and
 
150
          returns.
 
151
 
 
152
     lWriteListTo
 
153
          writes a generic list and  all  its  sub-lists  to  the
 
154
          stream  connected  with fp. The generic list pointer is
 
155
          the first function argument. The second argument is the
 
156
          file pointer. If the file pointer is NULL, the function
 
157
          behaves as "lWriteList".
 
158
 
 
159
     lGetListName
 
160
          returns the name of the specified generic list. If  the
 
161
          function  argument  is NULL, the string 'No List speci-
 
162
          fied' is returned.
 
163
 
 
164
     lGetListDescr
 
165
          returns the list descriptor of the  specified  list  or
 
166
          NULL if a NULL if the argument is NULL.
 
167
 
 
168
     lGetNumberOfElem
 
169
          gets the number of list elements actually contained  in
 
170
          the generic list specified as function argument. If the
 
171
          generic list pointer  is  NULL,  -1  is  returned,  the
 
172
          number of list elements is returned otherwise.
 
173
 
 
174
     lGetNumberOfRemainingElem
 
175
          returns the number of list elements  contained  in  the
 
176
          remainder of a generic list after a specified list ele-
 
177
          ment.
 
178
 
 
179
RETURN VALUES
 
180
     In case of error the return value is -1 or NULL, otherwise 0
 
181
     or a valid pointer to the corresponding struct is returned.
 
182
 
 
183
ERRORS
 
184
     The following errors may occur. The affected  functions  are
 
185
     listed in parentheses.
 
186
 
 
187
     LENOLISTNAME
 
188
          No list name specified. (<I>lCreateList</I>)
 
189
 
 
190
     LEDESCRNULL
 
191
          List descriptor is NULL. (<I>lCreateList</I>)
 
192
 
 
193
     LEMALLOC
 
194
          <B><A HREF="../htmlman3/Malloc.html">Malloc(3)</A></B> failed. (<I>lCreateList</I>, <I>lUndumpList</I>)
 
195
 
 
196
     LESTRDUP
 
197
          <B><A HREF="../htmlman3/Strdup.html">Strdup(3)</A></B> failed. (<I>lCreateList</I>)
 
198
 
 
199
     LECOUNTDESCR
 
200
          Counting the descriptor  length  failed.  (<I>lCreateList</I>,
 
201
          <I>lAddList</I>, <I>lUndumpList</I>)
 
202
 
 
203
     LELISTNULL
 
204
          List pointer is NULL. (<I>lFreeList</I>, <I>lCopyList</I>,  <I>lAddList</I>,
 
205
          <I>lPSortList</I>,  <I>lWriteList</I>,  <I>lGetListName</I>,  <I>lGetListDescr</I>,
 
206
          <I>lGetNumberOfElem</I>, <I>lDumpList</I>)
 
207
 
 
208
     LECREATELIST
 
209
          Creation of a new list failed. (<I>lCopyList</I>,  <I>lPSortList</I>,
 
210
          <I>lUndumpList</I>)
 
211
 
 
212
     LEAPPENDELEM
 
213
          <I>lAppendElem</I> function failed. (<I>lCopyList</I>, <I>lAddList</I>, <I>lUn-</I>
 
214
          <I>dumpList</I>)
 
215
 
 
216
     LEDIFFDESCR
 
217
          Unequal descriptors specified. (<I>lAddList</I>)
 
218
 
 
219
     LEDECHAINELEM
 
220
          <I>lDechainElem</I> failed. (<I>lAddList</I>, <I>lPSortList</I>)
 
221
 
 
222
     LENOFORMATSTR
 
223
          No format string specified. (<I>lPSortList</I>)
 
224
 
 
225
     LEPARSESORTORD
 
226
          Parsing the sort order format string  failed.  (<I>lPSort-</I>
 
227
          <I>List</I>)
 
228
 
 
229
     LEGETNROFELEM
 
230
          Getting number of list elements failed. (<I>lPSortList</I>)
 
231
 
 
232
     LEFILENULL
 
233
          File pointer to dump file is NULL. (<I>lDumpList</I>,  <I>lUndum-</I>
 
234
          <I>pList</I>)
 
235
 
 
236
     LESYNTAX
 
237
          A syntax error occurred. (<I>lUndumpList</I>)
 
238
 
 
239
     LEFIELDREAD
 
240
          Reading a field value failed. (<I>lUndumpList</I>)
 
241
 
 
242
     LEFGETDESCR
 
243
          <I>lUndumpDescr</I> failed. (<I>lUndumpList</I>)
 
244
 
 
245
     LEUNDUMPELEM
 
246
          <I>lUndumpElem</I> failed. (<I>lUndumpList</I>)
 
247
 
 
248
     LECREATEELEM
 
249
          <I>lCreateElem</I> failed. (<I>lUndumpList</I>)
 
250
 
 
251
     LECOPYSWITCH
 
252
          Copying list element fields failed. (<I>lUndumpList</I>)
 
253
 
 
254
SEE ALSO
 
255
     <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B>, <B><A HREF="../htmlman3/list_intro.html">list_intro(3)</A></B>.
 
256
 
 
257
COPYRIGHT
 
258
     See <B><A HREF="../htmlman1/sge_intro.html">sge_intro(1)</A></B> for a full statement of rights and  permis-
 
259
     sions.
 
260
 
 
261
 
 
262
 
 
263
 
 
264
 
 
265
</PRE>
 
266
<HR>
 
267
<ADDRESS>
 
268
Man(1) output converted with
 
269
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
 
270
</ADDRESS>
 
271
</BODY>
 
272
</HTML>