3 * Copyright (c) International Business Machines Corp., 2000
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See
13 * the GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 * Functions: dlist_t CreateList
32 * int GetPreviousObject
35 * int BlindExtractObject
43 * BOOLEAN AtStartOfList
49 * int GoToSpecifiedItem
56 * BOOLEAN CheckListIntegrity
58 * Description: This module implements a simple, generic, doubly linked list.
59 * Data objects of any type can be placed into a linked list
60 * created by this module. Furthermore, data objects of different
61 * types may be placed into the same linked list.
63 * Notes: This linked list implementation makes use of the concept of the
64 * current item. In any non-empty list, one item in the list will
65 * be designated as the current item. When any of the following
66 * functions are called, they will operate upon the current item
67 * only: GetItem, ReplaceItem, DeleteItem, GetTag, NextItem,
68 * PreviousItem, GetObject, ExtractItem, and ExtractObject. The
69 * user of this module may set the current item through the use of
70 * the GoToStartOfList, GoToEndOfList, NextItem, PreviousItem,
71 * and GoToSpecifiedItem functions.
73 * Since a linked list created by this module may contain items
74 * of different types, the user will need a way to identify items
75 * of different types which may be in the same list. To allow users
76 * to do this, the concept of an item tag is used. When an item is
77 * added to the list, the user must enter an item tag. The item
78 * tag is merely some identifier that the user wishes to associate
79 * with the item being placed into the list. When used as intended,
80 * each type of data item will have a unique tag associated with it.
81 * This way, all data items of the same type will have the same tag
82 * while data items of different types will have different tags.
83 * Thus, by using the GetTag function, the user can get the item
84 * tag for the current item without having to get the item from the
85 * list. This allows the user to differentiate between items of
86 * different types which reside in the same list.
88 * This module is single threaded. If used in a multi-threaded
89 * environment, the user must implement appropriate access controls.
91 * When an item is inserted or appended to a list, this module
92 * allocates memory on the heap to hold the item and then copies
93 * the item to the memory that it allocated. This allows local
94 * variables to be safely inserted or appended to a list. However,
95 * it should be noted that under certain circumstances a copy of the
96 * entire data item will NOT be made. Specifically, if the data item
97 * is a structure or array containing pointers, then the data pointed
98 * to by the pointers will NOT be copied even though the structure or
99 * array is! This results from the fact that, when an item is being
100 * inserted or appended to a list, the user provides just an address
101 * and size. This module assumes that the item to inserted or append
102 * lies in a contiguous block of memory at the address provided by the
103 * user. This module has no way of knowing the structure of the data
104 * at the specified address, and therefore can not know about any
105 * embedded pointers which may lie within that block of memory.
107 * This module now employs the concept of a handle. A handle is a
108 * reference to a specific item in a list which allows that item to
109 * be made the current item in the list quickly. Example: If you
110 * use the GetHandle function to get a handle for the current item
111 * (lets call the item B1), then, regardless of where you are in the
112 * list (or any reodering of the items in the list), you can make item
113 * B1 the current item by passing its handle to the GoToSpecifiedItem
114 * function. Alternatively, you could operate directly on B1 using
115 * the other handle based functions, such as GetItem_By_Handle, for
116 * example. GetItem_By_Handle gets the item associated with the
117 * specified handle without changing which item in the list is the
118 * current item in the list.
120 * The functions of this module refer to user data as either items or
121 * objects. The difference between the two is simple, yet subtle. It
122 * deals with who is responsible for the memory used to hold the data.
123 * In the case of an item, this module is responsible for the memory
124 * used to hold the user data. In the case of an object, the user
125 * is responsible for the memory used to hold the data.
127 * What this means is that, for functions adding ITEMS to a list,
128 * this module will be responsible for allocating memory to hold
129 * the user data and then copying the user data into the memory
130 * that was allocated. For functions which return items, this
131 * module will COPY the user data from the LIST into a buffer
132 * specified by the user. For functions which add objects to a
133 * list, the user provides a pointer to a block of memory holding
134 * user data. This block of memory was allocated by the user, and
135 * becomes the "property" of this module once it has been added to
136 * a LIST. For functions which return objects, a pointer to the
137 * memory where the data is stored is returned. As long as an item/object
138 * is in a LIST, this module will be responsible for the memory that
139 * is used to store the data associated with that item. This means that
140 * users of this module should not call free on an object returned by this
141 * module as long as that object is still within a list.
148 #define DLISTHANDLER 1
150 #include <linux/types.h> /* will pull in platform specific data type info from linux/include/asm */
153 #ifndef BOOLEAN_DEFINED
154 #define BOOLEAN_DEFINED 1
155 typedef u_int8_t BOOLEAN;
158 typedef void * ADDRESS;
161 struct LinkNodeRecord
163 ADDRESS DataLocation; /* Where the data associated with this LinkNode is */
164 uint DataSize; /* The size of the data associated with this LinkNode. */
165 TAG DataTag; /* The item tag the user gave to the data. */
166 struct MasterListRecord * ControlNodeLocation; /* The control node of the list containing this item. */
167 struct LinkNodeRecord * NextLinkNode; /* The LinkNode of the next item in the list. */
168 struct LinkNodeRecord * PreviousLinkNode; /* The LinkNode of the item preceding this one in the list. */
171 typedef struct LinkNodeRecord LinkNode;
173 struct MasterListRecord
175 uint ItemCount; /* The number of items in the list. */
176 LinkNode * StartOfList; /* The address of the LinkNode of the first item in the list. */
177 LinkNode * EndOfList; /* The address of the LinkNode of the last item in the list. */
178 LinkNode * CurrentItem; /* The address of the LinkNode of the current item in the list. */
180 POOL NodePool; /* The pool of LinkNodes for this dlist_t. */
182 uint Verify; /* A field to contain the VerifyValue which marks this as a list created by this module. */
185 typedef struct MasterListRecord ControlNode;
188 typedef ControlNode * dlist_t;
199 typedef enum _Insertion_Modes {
206 /* Update the IS_DLIST_ERROR() macro below if you add, remove, or change */
209 #define DLIST_SUCCESS 0
210 #define DLIST_OUT_OF_MEMORY ENOMEM
212 #define DLIST_CORRUPTED 201
213 #define DLIST_BAD 202
214 #define DLIST_NOT_INITIALIZED 203
215 #define DLIST_EMPTY 204
216 #define DLIST_ITEM_SIZE_WRONG 205
217 #define DLIST_BAD_ITEM_POINTER 206
218 #define DLIST_ITEM_SIZE_ZERO 207
219 #define DLIST_ITEM_TAG_WRONG 208
220 #define DLIST_END_OF_LIST 209
221 #define DLIST_ALREADY_AT_START 210
222 #define DLIST_BAD_HANDLE 211
223 #define DLIST_INVALID_INSERTION_MODE 212
224 #define DLIST_OBJECT_NOT_FOUND 213
225 #define DLIST_OBJECT_ALREADY_IN_LIST 214
227 /* Macro to determine if an error code is a dlist error code. */
229 #define IS_DLIST_ERROR(rc) ((abs(rc) >= DLIST_CORRUPTED) && (abs(rc) <= DLIST_OBJECT_ALREADY_IN_LIST))
231 /* The following code is special. It is for use with the PruneList and ForEachItem functions. Basically, these functions
232 can be thought of as "searching" a list. They present each item in the list to a user supplied function which can then
233 operate on the items. If the user supplied function returns a non-zero error code, ForEachItem and PruneList abort and
234 return an error to the caller. This may be undesirable. If the user supplied function used with PruneList and ForEachItem
235 returns the code below, PruneList/ForEachItem will abort and return DLIST_SUCCESS. This allows PruneList and ForEachItem
236 to be used to search a list and terminate the search when the desired item is found without having to traverse the
237 remaining items in the list. */
239 #define DLIST_SEARCH_COMPLETE 0xFF
244 /*********************************************************************/
246 /* Function Name: CreateList */
248 /* Descriptive Name: This function allocates and initializes the */
249 /* data structures associated with a list and */
250 /* then returns a pointer to these structures. */
252 /* Input: uint InitialPoolSize - Each List gets a pool of */
253 /* link nodes. When items are */
254 /* added to the List, a link node*/
255 /* is removed from the pool. */
256 /* When an item is removed from */
257 /* the List, the link node used */
258 /* for that item is returned to */
259 /* the pool. InitialPoolSize is */
260 /* the number of link nodes to */
261 /* place in the pool when the */
262 /* pool is created. */
263 /* uint MaximumPoolSize - When the pool runs out of */
264 /* link nodes, new nodes are */
265 /* allocated by the pool. When */
266 /* these links start being */
267 /* returned to the pool, the pool*/
268 /* will grow. This parameter */
269 /* puts a limit on how big the */
270 /* pool may grow to. Once the */
271 /* pool reaches this size, any */
272 /* link nodes being returned to */
273 /* the pool will be deallocated. */
274 /* uint PoolIncrement - When the pool runs out of link*/
275 /* nodes and more are required, */
276 /* the pool will allocate one or */
277 /* more link nodes. This tells the*/
278 /* pool how many link nodes to */
279 /* allocate at one time. */
281 /* Output: If Success : The function return value will be non-NULL */
283 /* If Failure : The function return value will be NULL. */
285 /* Error Handling: The function will only fail if it can not */
286 /* allocate enough memory to create the new list */
287 /* and its associated pool of link nodes. */
289 /* Side Effects: None. */
293 /*********************************************************************/
294 dlist_t CreateList(uint InitialPoolSize,
295 uint MaximumPoolSize,
301 /*********************************************************************/
303 /* Function Name: CreateList */
305 /* Descriptive Name: This function allocates and initializes the */
306 /* data structures associated with a list and */
307 /* then returns a pointer to these structures. */
311 /* Output: If Success : The function return value will be non-NULL */
313 /* If Failure : The function return value will be NULL. */
315 /* Error Handling: The function will only fail if it can not */
316 /* allocate enough memory to create the new list. */
318 /* Side Effects: None. */
322 /*********************************************************************/
323 dlist_t CreateList( void );
328 /*********************************************************************/
330 /* Function Name: InsertItem */
332 /* Descriptive Name: This function inserts an item into a dlist_t.*/
333 /* The item can be placed either before or */
334 /* after the current item in the dlist_t. */
336 /* Input: dlist_t ListToAddTo : The list to which the */
337 /* data item is to be */
339 /* uint ItemSize : The size of the data item, in */
341 /* ADDRESS ItemLocation : The address of the data */
342 /* to append to the list */
343 /* TAG ItemTag : The item tag to associate with */
344 /* item being appended to the list */
345 /* ADDRESS TargetHandle : The item in ListToAddTo which */
346 /* is used to determine where */
347 /* the item being transferred will */
348 /* be placed. If this is NULL, */
349 /* then the current item in */
350 /* ListToAddTo will be used. */
351 /* Insertion_Modes InsertMode : This indicates where, */
352 /* relative to the item in */
353 /* ListToAddTo specified by */
354 /* Target_Handle, the item being */
355 /* inserted can be placed. */
356 /* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
357 /* into ListToAddTo becomes the */
358 /* current item in ListToAddTo. */
359 /* ADDRESS * Handle : The address of a variable to hold */
360 /* the handle for the item that was */
361 /* inserted into the list. */
363 /* Output: If all went well, the return value will be */
364 /* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
365 /* the new item. If errors were encountered, the . */
366 /* return value will be the error code and *Handle will */
369 /* Error Handling: This function will fail under the following */
371 /* ListToAddTo does not point to a valid */
374 /* ItemLocation is NULL */
375 /* The memory required to hold a copy of the */
376 /* item can not be allocated. */
377 /* The memory required to create a LINK NODE */
378 /* can not be allocated. */
379 /* TargetHandle is invalid or is for an item */
380 /* in another list. */
381 /* If this routine fails, an error code is returned*/
382 /* and any memory allocated by this function is */
385 /* Side Effects: None. */
387 /* Notes: The item to add is copied to the heap to */
388 /* avoid possible conflicts with the usage of */
389 /* local variables in functions which process */
390 /* dlist_ts. However, a pointer to a local variable */
391 /* should not be appended to the dlist_t. */
393 /* It is assumed that TargetHandle is valid, or is at least*/
394 /* the address of an accessible block of storage. If */
395 /* TargetHandle is invalid, or is not the address of an */
396 /* accessible block of storage, then a trap or exception */
399 /* It is assumed that if ItemLocation is not NULL, then */
400 /* it is a valid address that can be dereferenced. If */
401 /* this assumption is violated, an exception or trap may */
404 /*********************************************************************/
405 int InsertItem (dlist_t ListToAddTo,
407 ADDRESS ItemLocation,
409 ADDRESS TargetHandle,
410 Insertion_Modes Insert_Mode,
416 /*********************************************************************/
418 /* Function Name: InsertObject */
420 /* Descriptive Name: This function inserts an object into a */
421 /* dlist_t. The object can be inserted before */
422 /* or after the current item in the list. */
424 /* Input: dlist_t ListToAddTo : The list to which the */
425 /* data object is to be */
427 /* uint ItemSize : The size of the data item, in */
429 /* ADDRESS ItemLocation : The address of the data */
430 /* to append to the list */
431 /* TAG ItemTag : The item tag to associate with */
432 /* the item being appended to the */
434 /* ADDRESS TargetHandle : The item in ListToAddTo which */
435 /* is used to determine where */
436 /* the item being transferred will */
437 /* be placed. If this is NULL, */
438 /* then the current item in */
439 /* ListToAddTo will be used. */
440 /* Insertion_Modes Insert_Mode : This indicates where, */
441 /* relative to the item in */
442 /* ListToAddTo specified by */
443 /* Target_Handle, the item being */
444 /* inserted can be placed. */
445 /* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
446 /* into ListToAddTo becomes the */
447 /* current item in ListToAddTo. */
448 /* ADDRESS * Handle : The address of a variable to hold */
449 /* the handle for the item that was */
450 /* inserted into the list. */
452 /* Output: If all went well, the return value will be */
453 /* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
454 /* the new item. If errors were encountered, the . */
455 /* return value will be the error code and *Handle will */
458 /* Error Handling: This function will fail under the following */
460 /* ListToAddTo does not point to a valid */
463 /* ItemLocation is NULL */
464 /* The memory required for a LINK NODE can not */
466 /* TargetHandle is invalid or is for an item */
467 /* in another list. */
468 /* If this routine fails, an error code is returned*/
469 /* and any memory allocated by this function is */
472 /* Side Effects: None. */
474 /* Notes: The item to insert is NOT copied to the heap. Instead, */
475 /* the location of the item is stored in the list. This */
476 /* is the major difference between InsertObject and */
477 /* InsertItem. InsertItem allocates memory on the heap, */
478 /* copies the item to the memory it allocated, and stores */
479 /* the address of the memory it allocated in the list. */
480 /* InsertObject stores the address provided by the user. */
482 /* It is assumed that TargetHandle is valid, or is at least*/
483 /* the address of an accessible block of storage. If */
484 /* TargetHandle is invalid, or is not the address of an */
485 /* accessible block of storage, then a trap or exception */
488 /* It is assumed that if ItemLocation is not NULL, then */
489 /* it is a valid address that can be dereferenced. If */
490 /* this assumption is violated, an exception or trap may */
493 /*********************************************************************/
494 int InsertObject (dlist_t ListToAddTo,
496 ADDRESS ItemLocation,
498 ADDRESS TargetHandle,
499 Insertion_Modes Insert_Mode,
504 /*********************************************************************/
506 /* Function Name: ExclusiveInsertObject */
508 /* Descriptive Name: This function inserts an object into a */
509 /* dlist_t. The object can be inserted before */
510 /* or after the current item in the list. If */
511 /* object is already in the list, it is not */
514 /* Input: dlist_t ListToAddTo : The list to which the */
515 /* data object is to be */
517 /* uint ItemSize : The size of the data item, in */
519 /* ADDRESS ItemLocation : The address of the data */
520 /* to append to the list */
521 /* TAG ItemTag : The item tag to associate with */
522 /* the item being appended to the */
524 /* ADDRESS TargetHandle : The item in ListToAddTo which */
525 /* is used to determine where */
526 /* the item being transferred will */
527 /* be placed. If this is NULL, */
528 /* then the current item in */
529 /* ListToAddTo will be used. */
530 /* Insertion_Modes Insert_Mode : This indicates where, */
531 /* relative to the item in */
532 /* ListToAddTo specified by */
533 /* Target_Handle, the item being */
534 /* inserted can be placed. */
535 /* BOOLEAN MakeCurrent : If TRUE, the item being inserted */
536 /* into ListToAddTo becomes the */
537 /* current item in ListToAddTo. */
538 /* ADDRESS * Handle : The address of a variable to hold */
539 /* the handle for the item that was */
540 /* inserted into the list. */
542 /* Output: If all went well, the return value will be */
543 /* DLIST_SUCCESS and *Handle will contain the ADDRESS of */
544 /* the new item. If errors were encountered, the . */
545 /* return value will be the error code and *Handle will */
548 /* Error Handling: This function will fail under the following */
550 /* ListToAddTo does not point to a valid */
553 /* ItemLocation is NULL */
554 /* The memory required for a LINK NODE can not */
556 /* TargetHandle is invalid or is for an item */
557 /* in another list. */
558 /* If this routine fails, an error code is returned*/
559 /* and any memory allocated by this function is */
562 /* Side Effects: None. */
564 /* Notes: The item to insert is NOT copied to the heap. Instead, */
565 /* the location of the item is stored in the list. This */
566 /* is the major difference between InsertObject and */
567 /* InsertItem. InsertItem allocates memory on the heap, */
568 /* copies the item to the memory it allocated, and stores */
569 /* the address of the memory it allocated in the list. */
570 /* InsertObject stores the address provided by the user. */
572 /* It is assumed that TargetHandle is valid, or is at least*/
573 /* the address of an accessible block of storage. If */
574 /* TargetHandle is invalid, or is not the address of an */
575 /* accessible block of storage, then a trap or exception */
578 /* It is assumed that if ItemLocation is not NULL, then */
579 /* it is a valid address that can be dereferenced. If */
580 /* this assumption is violated, an exception or trap may */
583 /*********************************************************************/
584 int ExclusiveInsertObject (dlist_t ListToAddTo,
586 ADDRESS ItemLocation,
588 ADDRESS TargetHandle,
589 Insertion_Modes Insert_Mode,
594 /*********************************************************************/
596 /* Function Name: DeleteItem */
598 /* Descriptive Name: This function removes the specified item from*/
599 /* the list and optionally frees the memory */
600 /* associated with it. */
602 /* Input: dlist_t ListToDeleteFrom : The list whose current */
603 /* item is to be deleted. */
604 /* BOOLEAN FreeMemory : If TRUE, then the memory */
605 /* associated with the current */
606 /* item will be freed. If FALSE */
607 /* then the current item will be */
608 /* removed from the list but its */
609 /* memory will not be freed. */
610 /* ADDRESS Handle : The handle of the item to get. This */
611 /* handle must be of an item which resides*/
612 /* in ListToDeleteFrom, or NULL. If */
613 /* NULL is used, then the current item */
614 /* in ListToDeleteFrom will be deleted. */
616 /* Output: Return DLIST_SUCCESS if successful, else an error code.*/
618 /* Error Handling: This function will fail if ListToDeleteFrom is */
619 /* not a valid list, or if ListToDeleteFrom is */
620 /* empty, or if Handle is invalid. */
621 /* If this routine fails, an error code is */
624 /* Side Effects: None. */
626 /* Notes: Items in a list can be accessed in two ways: A copy of */
627 /* the item can be obtained using GetItem and its related */
628 /* calls, or a pointer to the item can be obtained using */
629 /* GetObject and its related calls. If you have a copy of */
630 /* the data and wish to remove the item from the list, set */
631 /* FreeMemory to TRUE. This will remove the item from the */
632 /* list and deallocate the memory used to hold it. If you */
633 /* have a pointer to the item in the list (from one of the */
634 /* GetObject style functions) and wish to remove the item */
635 /* from the list, set FreeMemory to FALSE. This removes */
636 /* the item from the list without freeing its memory, so */
637 /* that the pointer obtained with the GetObject style */
638 /* functions is still useable. */
640 /* It is assumed that Handle is valid, or is at least the */
641 /* address of an accessible block of storage. If Handle */
642 /* is invalid, or is not the address of an accessible block*/
643 /* of storage, then a trap or exception may occur. */
645 /* This function does not alter which item is the current */
646 /* item in the list, unless the handle specified belongs */
647 /* to the current item in the list, in which case this */
648 /* function behaves the same as DeleteItem. */
650 /*********************************************************************/
651 int DeleteItem (dlist_t ListToDeleteFrom,
656 /*********************************************************************/
658 /* Function Name: DeleteAllItems */
660 /* Descriptive Name: This function deletes all of the items in the*/
661 /* specified list and optionally frees the */
662 /* memory associated with each item deleted. */
664 /* Input: dlist_t ListToDeleteFrom : The list whose items */
665 /* are to be deleted. */
666 /* BOOLEAN FreeMemory : If TRUE, then the memory */
667 /* associated with each item in the*/
668 /* list will be freed. If FALSE */
669 /* then the each item will be */
670 /* removed from the list but its */
671 /* memory will not be freed. */
673 /* Output: Return DLIST_SUCCESS if successful, else an error code.*/
675 /* Error Handling: This function will fail if ListToDeleteFrom is */
676 /* not a valid list, or if ListToDeleteFrom is */
678 /* If this routine fails, an error code is */
681 /* Side Effects: None. */
683 /* Notes: Items in a list can be accessed in two ways: A copy of */
684 /* the item can be obtained using GetItem and its related */
685 /* calls, or a pointer to the item can be obtained using */
686 /* GetObject and its related calls. If you have a copy of */
687 /* the data and wish to remove the item from the list, set */
688 /* FreeMemory to TRUE. This will remove the item from the */
689 /* list and deallocate the memory used to hold it. If you */
690 /* have a pointer to the item in the list (from one of the */
691 /* GetObject style functions) and wish to remove the item */
692 /* from the list, set FreeMemory to FALSE. This removes */
693 /* the item from the list without freeing its memory, so */
694 /* that the pointer obtained with the GetObject style */
695 /* functions is still useable. */
697 /*********************************************************************/
698 int DeleteAllItems (dlist_t ListToDeleteFrom,
702 /*********************************************************************/
704 /* Function Name: DeleteObject */
706 /* Descriptive Name: This function removes the specified object */
709 /* Input: dlist_t ListToDeleteFrom : The list whose current */
710 /* item is to be deleted. */
711 /* ADDRESS Object : The address of the object to be removed*/
714 /* Output: Return DLIST_SUCCESS if successful, else an error code.*/
716 /* Error Handling: This function will fail if ListToDeleteFrom is */
717 /* not a valid list, or if ListToDeleteFrom is */
718 /* empty, or if Handle is invalid. */
719 /* If this routine fails, an error code is */
722 /* Side Effects: None. */
724 /* Notes: This function does not alter which item is the current */
725 /* item in the list, unless the handle specified belongs */
726 /* to the current item in the list, in which case this */
727 /* function behaves the same as DeleteItem. */
729 /*********************************************************************/
730 int DeleteObject (dlist_t ListToDeleteFrom,
734 /*********************************************************************/
736 /* Function Name: GetItem */
738 /* Descriptive Name: This function copies the specified item in */
739 /* the list to a buffer provided by the caller. */
741 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
742 /* is to be copied and returned*/
744 /* uint ItemSize : What the caller thinks the size of*/
745 /* the current item is. */
746 /* ADDRESS ItemLocation : This is the location of the */
747 /* buffer into which the current*/
748 /* item is to be copied. */
749 /* TAG ItemTag : What the caller thinks the item tag */
750 /* of the current item is. */
751 /* ADDRESS Handle : The handle of the item to get. This */
752 /* handle must be of an item which resides*/
753 /* in ListToGetItemFrom, or NULL. If */
754 /* NULL, then the current item in the list*/
756 /* BOOLEAN MakeCurrent : If TRUE, the item to get will */
757 /* become the current item in the */
760 /* Output: If Successful : */
761 /* Return DLIST_SUCCESS. */
762 /* The buffer at ItemLocation will contain a copy of */
763 /* the current item from ListToGetItemFrom. */
765 /* Return an error code. */
768 /* Error Handling: This function will fail under any of the */
769 /* following conditions: */
770 /* ListToGetItemFrom is not a valid list */
771 /* ItemSize does not match the size of the */
772 /* current item in the list */
773 /* ItemLocation is NULL */
774 /* ItemTag does not match the item tag */
775 /* of the current item in the list */
776 /* Handle is invalid, or is for an item */
777 /* which is not in ListToGetItemFrom */
778 /* If any of these conditions occur, an error code */
779 /* will be returned. */
781 /* Side Effects: None. */
783 /* Notes: It is assumed that if ItemLocation is not NULL, then */
784 /* it is a valid address that can be dereferenced. If */
785 /* this assumption is violated, an exception or trap may */
788 /* It is assumed that Handle is valid, or is at least the */
789 /* address of an accessible block of storage. If Handle */
790 /* is invalid, or is not the address of an accessible block*/
791 /* of storage, then a trap or exception may occur. */
792 /* NOTE: For this function, NULL is considered a valid */
793 /* handle corresponding to the current item in the */
796 /* This function does not alter which item is the current */
797 /* item in the list. */
799 /*********************************************************************/
800 int GetItem( dlist_t ListToGetItemFrom,
802 ADDRESS ItemLocation,
805 BOOLEAN MakeCurrent);
808 /*********************************************************************/
810 /* Function Name: GetNextItem */
812 /* Descriptive Name: This function advances the current item */
813 /* pointer and then copies the current item in */
814 /* the list to a buffer provided by the caller. */
816 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
817 /* is to be copied and returned*/
819 /* uint ItemSize : What the caller thinks the size of*/
820 /* the current item is. */
821 /* ADDRESS ItemLocation : This is the location of the */
822 /* buffer into which the current*/
823 /* item is to be copied. */
824 /* TAG ItemTag : What the caller thinks the item tag */
825 /* of the current item is. */
827 /* Output: If Successful : */
828 /* Return DLIST_SUCCESS. */
829 /* The buffer at ItemLocation will contain a copy of */
830 /* the current item from ListToGetItemFrom. */
832 /* Return an error code. */
833 /* The current item pointer will NOT be advanced. */
834 /* The current item in the list will be the same */
835 /* as before the call to this function. */
837 /* Error Handling: This function will fail under any of the */
838 /* following conditions: */
839 /* ListToGetItemFrom is not a valid list */
840 /* ItemSize does not match the size of the */
841 /* current item in the list */
842 /* ItemLocation is NULL */
843 /* ItemTag does not match the item tag */
844 /* of the current item in the list */
845 /* The current item in the list before this */
846 /* function is called is the last item */
847 /* item in the list. */
848 /* If any of these conditions occur, an error */
849 /* code will be returned. */
851 /* Side Effects: None. */
853 /* Notes: It is assumed that if ItemLocation is not NULL, then */
854 /* it is a valid address that can be dereferenced. If */
855 /* this assumption is violated, an exception or trap may */
858 /*********************************************************************/
859 int GetNextItem(dlist_t ListToGetItemFrom,
861 ADDRESS ItemLocation,
865 /*********************************************************************/
867 /* Function Name: GetPreviousItem */
869 /* Descriptive Name: This function makes the previous item in the */
870 /* list the current item in the list and then */
871 /* copies that item to a buffer provided by the */
874 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
875 /* is to be copied and returned*/
877 /* uint ItemSize : What the caller thinks the size of*/
878 /* the current item is. */
879 /* ADDRESS ItemLocation : This is the location of the */
880 /* buffer into which the current */
881 /* item is to be copied. */
882 /* TAG ItemTag : What the caller thinks the item tag */
883 /* of the current item is. */
885 /* Output: If Successful : */
886 /* Return DLIST_SUCCESS. */
887 /* The buffer at ItemLocation will contain a copy of */
888 /* the current item from ListToGetItemFrom. */
890 /* Return an error code. */
891 /* The current item pointer will NOT be advanced. */
892 /* The current item in the list will be the same */
893 /* as before the call to this function. */
895 /* Error Handling: This function will fail under any of the */
896 /* following conditions: */
897 /* ListToGetItemFrom is not a valid list */
898 /* ItemSize does not match the size of the */
899 /* current item in the list */
900 /* ItemLocation is NULL */
901 /* ItemTag does not match the item tag */
902 /* of the current item in the list */
903 /* The current item in the list before this */
904 /* function is called is the last item */
905 /* item in the list. */
906 /* If any of these conditions occur, an error */
907 /* code will be returned. */
909 /* Side Effects: None. */
911 /* Notes: It is assumed that if ItemLocation is not NULL, then */
912 /* it is a valid address that can be dereferenced. If */
913 /* this assumption is violated, an exception or trap may */
916 /*********************************************************************/
917 int GetPreviousItem(dlist_t ListToGetItemFrom,
919 ADDRESS ItemLocation,
923 /*********************************************************************/
925 /* Function Name: GetObject */
927 /* Descriptive Name: This function returns the address of the data*/
928 /* associated with the specified item in the */
931 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
932 /* is to have its address */
933 /* returned to the caller. */
934 /* uint ItemSize : What the caller thinks the size of*/
935 /* the current item is. */
936 /* TAG ItemTag : What the caller thinks the item tag */
937 /* of the current item is. */
938 /* ADDRESS Handle : The handle of the item to get. This */
939 /* handle must be of an item which resides*/
940 /* in ListToGetItemFrom, or NULL. If */
941 /* NULL, then the current item in the list*/
942 /* BOOLEAN MakeCurrent : If TRUE, the item to get will */
943 /* become the current item in the */
945 /* ADDRESS * Object : The address of a variable to hold */
946 /* the ADDRESS of data associated */
947 /* with the current item. */
949 /* Output: If Successful : */
950 /* Return DLIST_SUCCESS. */
951 /* *Object will be the address of the data */
952 /* associated with the current item in the list. */
954 /* Return an error code. */
955 /* *Object will be NULL. */
957 /* Error Handling: This function will fail under any of the */
958 /* following conditions: */
959 /* ListToGetItemFrom is not a valid list */
960 /* ItemSize does not match the size of the */
961 /* current item in the list */
962 /* ItemTag does not match the item tag */
963 /* of the current item in the list */
964 /* Handle is invalid, or is for an item */
965 /* which is not in ListToGetItemFrom */
966 /* If any of these conditions occur, an error code */
967 /* will be returned. */
969 /* Side Effects: None. */
971 /* Notes: The user should not free the memory associated with */
972 /* the address returned by this function as the object is */
973 /* still in the list. */
975 /* It is assumed that Handle is valid, or is at least the */
976 /* address of an accessible block of storage. If Handle */
977 /* is invalid, or is not the address of an accessible block*/
978 /* of storage, then a trap or exception may occur. */
979 /* NOTE: For this function, NULL is considered a valid */
980 /* handle designating the current item in the list. */
982 /* It is assumed that Object is a valid address. If not, */
983 /* an exception or trap may occur. */
985 /* This function does not alter which item is the current */
986 /* item in the list. */
988 /*********************************************************************/
989 int GetObject(dlist_t ListToGetItemFrom,
997 /*********************************************************************/
999 /* Function Name: BlindGetObject */
1001 /* Descriptive Name: This function returns the address of the data*/
1002 /* associated with the specified item in the */
1005 /* Input: dlist_t ListToGetItemFrom : The list whose current */
1006 /* item is to have its address */
1007 /* returned to the caller. */
1008 /* uint * ItemSize : The size of the current item */
1009 /* TAG * ItemTag : The tag of the current item */
1010 /* ADDRESS Handle : The handle of the item to get. This */
1011 /* handle must be of an item which resides*/
1012 /* in ListToGetItemFrom, or NULL. If */
1013 /* NULL, then the current item in the list*/
1014 /* BOOLEAN MakeCurrent : If TRUE, the item to get will */
1015 /* become the current item in the */
1017 /* ADDRESS * Object : The address of a variable to hold */
1018 /* the ADDRESS of data associated */
1019 /* with the current item. */
1021 /* Output: If Successful : */
1022 /* Return DLIST_SUCCESS. */
1023 /* *Object will be the address of the data */
1024 /* associated with the current item in the list. */
1026 /* Return an error code. */
1027 /* *Object will be NULL. */
1029 /* Error Handling: This function will fail under any of the */
1030 /* following conditions: */
1031 /* ListToGetItemFrom is not a valid list */
1032 /* ItemSize does not match the size of the */
1033 /* current item in the list */
1034 /* ItemTag does not match the item tag */
1035 /* of the current item in the list */
1036 /* Handle is invalid, or is for an item */
1037 /* which is not in ListToGetItemFrom */
1038 /* If any of these conditions occur, an error code */
1039 /* will be returned. */
1041 /* Side Effects: None. */
1043 /* Notes: The user should not free the memory associated with */
1044 /* the address returned by this function as the object is */
1045 /* still in the list. */
1047 /* It is assumed that Handle is valid, or is at least the */
1048 /* address of an accessible block of storage. If Handle */
1049 /* is invalid, or is not the address of an accessible block*/
1050 /* of storage, then a trap or exception may occur. */
1051 /* NOTE: For this function, NULL is considered a valid */
1052 /* handle designating the current item in the list. */
1054 /* It is assumed that Object is a valid address. If not, */
1055 /* an exception or trap may occur. */
1057 /* This function does not alter which item is the current */
1058 /* item in the list. */
1060 /*********************************************************************/
1061 int BlindGetObject(dlist_t ListToGetItemFrom,
1065 BOOLEAN MakeCurrent,
1069 /*********************************************************************/
1071 /* Function Name: GetNextObject */
1073 /* Descriptive Name: This function advances the current item */
1074 /* pointer and then returns the address of the */
1075 /* data associated with the current item in the */
1078 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
1079 /* is to be copied and returned*/
1080 /* to the caller. */
1081 /* uint ItemSize : What the caller thinks the size of*/
1082 /* the current item is. */
1083 /* TAG ItemTag : What the caller thinks the item tag */
1084 /* of the current item is. */
1085 /* ADDRESS * Object : The address of a variable to hold */
1086 /* the ADDRESS of data associated */
1087 /* with the next item. */
1089 /* Output: If Successful : */
1090 /* Return DLIST_SUCCESS. */
1091 /* *Object will be the address of the data */
1092 /* associated with the current item in the list. */
1094 /* Return an error code. */
1095 /* *Object will be NULL. */
1096 /* The current item pointer will NOT be advanced. */
1097 /* The current item in the list will be the same */
1098 /* as before the call to this function. */
1100 /* Error Handling: This function will fail under any of the */
1101 /* following conditions: */
1102 /* ListToGetItemFrom is not a valid list */
1103 /* ItemSize does not match the size of the */
1104 /* current item in the list */
1105 /* ItemTag does not match the item tag */
1106 /* of the current item in the list */
1107 /* The current item in the list before this */
1108 /* function is called is the last item */
1109 /* item in the list. */
1110 /* If any of these conditions occur, an error code */
1111 /* will be returned. */
1113 /* Side Effects: None. */
1115 /* Notes: The user should not free the memory associated with */
1116 /* the address returned by this function as the object is */
1117 /* still in the list. */
1119 /* It is assumed that Object is a valid address. If not, */
1120 /* an exception or trap may occur. */
1122 /*********************************************************************/
1123 int GetNextObject(dlist_t ListToGetItemFrom,
1129 /*********************************************************************/
1131 /* Function Name: GetPreviousObject */
1133 /* Descriptive Name: This function makes the previous item in the */
1134 /* list the current item and then returns the */
1135 /* address of the data associated with the */
1136 /* current item in the list. */
1138 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
1139 /* is to be copied and returned*/
1140 /* to the caller. */
1141 /* uint ItemSize : What the caller thinks the size of*/
1142 /* the current item is. */
1143 /* TAG ItemTag : What the caller thinks the item tag */
1144 /* of the current item is. */
1145 /* ADDRESS * Object : The address of a variable to hold */
1146 /* the ADDRESS of data associated */
1147 /* with the previous item. */
1149 /* Output: If Successful : */
1150 /* Return DLIST_SUCCESS. */
1151 /* *Object will be the address of the data */
1152 /* associated with the current item in the list. */
1154 /* Return an error code. */
1155 /* *Object will be NULL. */
1156 /* The current item pointer will NOT be advanced. */
1157 /* The current item in the list will be the same */
1158 /* as before the call to this function. */
1160 /* Error Handling: This function will fail under any of the */
1161 /* following conditions: */
1162 /* ListToGetItemFrom is not a valid list */
1163 /* ItemSize does not match the size of the */
1164 /* current item in the list */
1165 /* ItemTag does not match the item tag */
1166 /* of the current item in the list */
1167 /* The current item in the list before this */
1168 /* function is called is the last item */
1169 /* item in the list. */
1170 /* If any of these conditions occur, an error code */
1171 /* will be returned. */
1173 /* Side Effects: None. */
1175 /* Notes: The user should not free the memory associated with */
1176 /* the address returned by this function as the object is */
1177 /* still in the list. */
1179 /* It is assumed that Object is a valid address. If not, */
1180 /* an exception or trap may occur. */
1182 /*********************************************************************/
1183 int GetPreviousObject(dlist_t ListToGetItemFrom,
1189 /*********************************************************************/
1191 /* Function Name: ExtractItem */
1193 /* Descriptive Name: This function copies the specified item in */
1194 /* the list to a buffer provided by the caller */
1195 /* and removes the item from the list. */
1197 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
1198 /* is to be copied and returned*/
1199 /* to the caller. */
1200 /* uint ItemSize : What the caller thinks the size of*/
1201 /* the current item is. */
1202 /* ADDRESS ItemLocation : This is the location of the */
1203 /* buffer into which the current*/
1204 /* item is to be copied. */
1205 /* TAG ItemTag : What the caller thinks the item tag */
1206 /* of the current item is. */
1207 /* ADDRESS Handle : The handle of the item to get. This */
1208 /* handle must be of an item which resides*/
1209 /* in ListToGetItemFrom, or NULL. If */
1210 /* NULL, then the current item in the list*/
1213 /* Output: If Successful : */
1214 /* Return DLIST_SUCCESS. */
1215 /* The buffer at ItemLocation will contain a copy of */
1216 /* the current item from ListToGetItemFrom. */
1217 /* The item will have been removed from the list and */
1218 /* its memory deallocated. */
1220 /* Return an error code. */
1222 /* Error Handling: This function will fail under any of the */
1223 /* following conditions: */
1224 /* ListToGetItemFrom is not a valid list */
1225 /* ItemSize does not match the size of the */
1226 /* current item in the list */
1227 /* ItemLocation is NULL */
1228 /* ItemTag does not match the item tag */
1229 /* of the current item in the list */
1230 /* Handle is invalid, or is for an item */
1231 /* which is not in ListToGetItemFrom */
1232 /* If any of these conditions occur, *Error will */
1233 /* contain a non-zero error code. */
1235 /* Side Effects: None. */
1237 /* Notes: It is assumed that if ItemLocation is not NULL, then */
1238 /* it is a valid address that can be dereferenced. If */
1239 /* these assumptions are violated, an exception or trap */
1242 /* It is assumed that Handle is valid, or is at least the */
1243 /* address of an accessible block of storage. If Handle */
1244 /* is invalid, or is not the address of an accessible block*/
1245 /* of storage, then a trap or exception may occur. */
1246 /* NOTE: For this function, NULL is considered a valid */
1247 /* handle which refers to the current item in the */
1250 /* This function does not alter which item is the current */
1251 /* item in the list, unless the handle specified belongs */
1252 /* to the current item in the list, in which case the */
1253 /* item following the current item becomes the current */
1254 /* item in the list. If there is no item following the */
1255 /* current item in the list, then the item preceding the */
1256 /* current item will become the current item in the list. */
1258 /*********************************************************************/
1259 int ExtractItem(dlist_t ListToGetItemFrom,
1261 ADDRESS ItemLocation,
1266 /*********************************************************************/
1268 /* Function Name: ExtractObject */
1270 /* Descriptive Name: This function returns the address of the data*/
1271 /* associated with the specified item in the */
1272 /* list and then removes that item from the list*/
1274 /* Input: dlist_t ListToGetItemFrom : The list whose current item */
1275 /* is to be copied and returned*/
1276 /* to the caller. */
1277 /* uint ItemSize : What the caller thinks the size of*/
1278 /* the current item is. */
1279 /* TAG ItemTag : What the caller thinks the item tag */
1280 /* of the current item is. */
1281 /* ADDRESS Handle : The handle of the item to get. This */
1282 /* handle must be of an item which resides*/
1283 /* in ListToGetItemFrom, or NULL. If */
1284 /* NULL, then the current item in the */
1285 /* list will be used. */
1286 /* ADDRESS * Object : The address of a variable to hold */
1287 /* the ADDRESS of data associated */
1288 /* with the current item. */
1290 /* Output: If Successful : */
1291 /* Return DLIST_SUCCESS. */
1292 /* *Object will be the address of the data */
1293 /* associated with the current item in the list. */
1295 /* Return an error code. */
1296 /* *Object will be NULL. */
1298 /* Error Handling: This function will fail under any of the */
1299 /* following conditions: */
1300 /* ListToGetItemFrom is not a valid list */
1301 /* ItemSize does not match the size of the */
1302 /* current item in the list */
1303 /* ItemTag does not match the item tag */
1304 /* of the current item in the list */
1305 /* Handle is invalid, or is for an item */
1306 /* which is not in ListToGetItemFrom */
1307 /* If any of these conditions occur, an error code */
1308 /* will be returned. */
1310 /* Side Effects: None. */
1312 /* Notes: The user is responsible for the memory associated with */
1313 /* the address returned by this function since this */
1314 /* function removes that object from the list. This means */
1315 /* that, when the user is through with the object, they */
1316 /* should free it. */
1318 /* It is assumed that Handle is valid, or is at least the */
1319 /* address of an accessible block of storage. If Handle */
1320 /* is invalid, or is not the address of an accessible block*/
1321 /* of storage, then a trap or exception may occur. */
1322 /* NOTE: For this function, NULL is considered a valid */
1323 /* handle which refers to the current item in the */
1326 /* It is assumed that Object is a valid address. If not, */
1327 /* an exception or trap may occur. */
1329 /* This function does not alter which item is the current */
1330 /* item in the list, unless the handle specified belongs */
1331 /* to the current item in the list, in which case the */
1332 /* item following the current item becomes the current */
1333 /* item in the list. If there is no item following the */
1334 /* current item in the list, then the item preceding the */
1335 /* current item will become the current item in the list. */
1337 /*********************************************************************/
1338 int ExtractObject(dlist_t ListToGetItemFrom,
1345 /*********************************************************************/
1347 /* Function Name: BlindExtractObject */
1349 /* Descriptive Name: This function returns the address of the data*/
1350 /* associated with the specified item in the */
1351 /* list and then removes that item from the list*/
1353 /* Input: dlist_t ListToGetItemFrom : The list whose current */
1354 /* item is to be copied and */
1355 /* returned to the caller. */
1356 /* uint * ItemSize : The size of the current item */
1357 /* TAG * ItemTag : The tag of the current item */
1358 /* ADDRESS Handle : The handle of the item to get. This */
1359 /* handle must be of an item which resides*/
1360 /* in ListToGetItemFrom, or NULL. If */
1361 /* NULL, then the current item in the */
1362 /* list will be used. */
1363 /* ADDRESS * Object : The address of a variable to hold */
1364 /* the ADDRESS of data associated */
1365 /* with the current item. */
1367 /* Output: If Successful : */
1368 /* Return DLIST_SUCCESS. */
1369 /* *Object will be the address of the data */
1370 /* associated with the current item in the list. */
1372 /* Return an error code. */
1373 /* *Object will be NULL. */
1375 /* Error Handling: This function will fail under any of the */
1376 /* following conditions: */
1377 /* ListToGetItemFrom is not a valid list */
1378 /* ItemSize does not match the size of the */
1379 /* current item in the list */
1380 /* ItemTag does not match the item tag */
1381 /* of the current item in the list */
1382 /* Handle is invalid, or is for an item */
1383 /* which is not in ListToGetItemFrom */
1384 /* If any of these conditions occur, an error code */
1385 /* will be returned. */
1387 /* Side Effects: None. */
1389 /* Notes: The user is responsible for the memory associated with */
1390 /* the address returned by this function since this */
1391 /* function removes that object from the list. This means */
1392 /* that, when the user is through with the object, they */
1393 /* should free it. */
1395 /* It is assumed that Handle is valid, or is at least the */
1396 /* address of an accessible block of storage. If Handle */
1397 /* is invalid, or is not the address of an accessible block*/
1398 /* of storage, then a trap or exception may occur. */
1399 /* NOTE: For this function, NULL is considered a valid */
1400 /* handle which refers to the current item in the */
1403 /* It is assumed that Object is a valid address. If not, */
1404 /* an exception or trap may occur. */
1406 /* This function does not alter which item is the current */
1407 /* item in the list, unless the handle specified belongs */
1408 /* to the current item in the list, in which case the */
1409 /* item following the current item becomes the current */
1410 /* item in the list. If there is no item following the */
1411 /* current item in the list, then the item preceding the */
1412 /* current item will become the current item in the list. */
1414 /*********************************************************************/
1415 int BlindExtractObject(dlist_t ListToGetItemFrom,
1422 /*********************************************************************/
1424 /* Function Name: ReplaceItem */
1426 /* Descriptive Name: This function replaces the specified item in */
1427 /* the list with the one provided as its */
1430 /* Input: dlist_t ListToReplaceItemIn : The list whose current item*/
1431 /* is to be replaced */
1432 /* uint ItemSize : The size, in bytes, of the */
1433 /* replacement item */
1434 /* ADDRESS ItemLocation : The address of the replacement */
1436 /* TAG ItemTag : The item tag that the user wishes to */
1437 /* associate with the replacement item */
1438 /* ADDRESS Handle : The handle of the item to get. This */
1439 /* handle must be of an item which resides */
1440 /* in ListToGetItemFrom, or NULL. If NULL */
1441 /* then the current item in the list will */
1443 /* BOOLEAN MakeCurrent : If TRUE, the item to get will */
1444 /* become the current item in the */
1447 /* Output: If Successful then return DLIST_SUCCESS. */
1448 /* If Unsuccessful, then return an error code. */
1450 /* Error Handling: This function will fail under the following */
1452 /* ListToReplaceItemIn is empty */
1454 /* ItemLocation is NULL */
1455 /* The memory required can not be allocated. */
1456 /* Handle is invalid, or is for an item */
1457 /* which is not in ListToGetItemFrom */
1458 /* If any of these conditions occurs, an error */
1459 /* code will be returned. */
1461 /* Side Effects: None. */
1463 /* Notes: It is assumed that if ItemLocation is not NULL, then */
1464 /* it is a valid address that can be dereferenced. If */
1465 /* these assumptions are violated, an exception or trap */
1468 /* It is assumed that Handle is valid, or is at least the */
1469 /* address of an accessible block of storage. If Handle */
1470 /* is invalid, or is not the address of an accessible block*/
1471 /* of storage, then a trap or exception may occur. */
1472 /* NOTE: For this function, NULL is a valid handle which */
1473 /* refers to the current item in the list. */
1475 /* This function does not alter which item is the current */
1476 /* item in the list. */
1478 /*********************************************************************/
1479 int ReplaceItem(dlist_t ListToReplaceItemIn,
1481 ADDRESS ItemLocation,
1484 BOOLEAN MakeCurrent);
1487 /*********************************************************************/
1489 /* Function Name: ReplaceObject */
1491 /* Descriptive Name: This function replaces the specified object */
1492 /* in the list with the one provided as its */
1495 /* Input: dlist_t ListToReplaceItemIn : The list whose current */
1496 /* object is to be replaced */
1497 /* uint ItemSize : The size, in bytes, of the */
1498 /* replacement object */
1499 /* ADDRESS ItemLocation : The address of the replacement */
1501 /* TAG ItemTag : The item tag that the user wishes to */
1502 /* associate with the replacement item */
1503 /* ADDRESS Handle : The handle of the item to get. This */
1504 /* handle must be of an item which resides */
1505 /* in ListToGetItemFrom, or NULL. If NULL */
1506 /* then the current item in the list will */
1508 /* BOOLEAN MakeCurrent : If TRUE, the item to get will */
1509 /* become the current item in the */
1511 /* ADDRESS * Object : The address of a variable to hold */
1512 /* the ADDRESS of the object that */
1515 /* Output: If Successful then return DLIST_SUCCESS and the */
1516 /* *Object will contain the address of the object that */
1518 /* If Unsuccessful, then return an error code and */
1519 /* *Object will be NULL. */
1521 /* Error Handling: This function will fail under the following */
1523 /* ListToReplaceItemIn is empty */
1525 /* ItemLocation is NULL */
1526 /* The memory required can not be allocated. */
1527 /* Handle is invalid, or is for an item */
1528 /* which is not in ListToGetItemFrom */
1529 /* If any of these conditions occurs, an error */
1530 /* code will be returned. */
1532 /* Side Effects: None. */
1534 /* Notes: The user is responsible for the memory associated with */
1535 /* the object returned by this function as that object is */
1536 /* removed from the list. This means that, when the user */
1537 /* is through with the object returned by this function, */
1538 /* they should free it. */
1540 /* It is assumed that if ItemLocation is not NULL, then */
1541 /* it is a valid address that can be dereferenced. If */
1542 /* these assumptions are violated, an exception or trap */
1545 /* It is assumed that Handle is valid, or is at least the */
1546 /* address of an accessible block of storage. If Handle */
1547 /* is invalid, or is not the address of an accessible block*/
1548 /* of storage, then a trap or exception may occur. */
1549 /* NOTE: For this function, NULL is a valid handle for the */
1550 /* current item in the list. */
1552 /* It is assumed that Object is a valid address. If not, */
1553 /* an exception or trap may occur. */
1555 /* This function does not alter which item is the current */
1556 /* item in the list. */
1558 /*********************************************************************/
1559 int ReplaceObject(dlist_t ListToReplaceItemIn,
1560 uint * ItemSize, /* On input - size of new object. On return = size of old object. */
1561 ADDRESS ItemLocation,
1562 TAG * ItemTag, /* On input - TAG of new object. On return = TAG of old object. */
1564 BOOLEAN MakeCurrent,
1568 /*********************************************************************/
1570 /* Function Name: GetTag */
1572 /* Descriptive Name: This function returns the item tag associated*/
1573 /* with the current item in the list. */
1575 /* Input: dlist_t ListToGetTagFrom : The list from which the item */
1576 /* tag of the current item is to*/
1578 /* ADDRESS Handle : The handle of the item whose TAG and */
1579 /* size we are to get. This handle must */
1580 /* be of an item which resides in */
1581 /* in ListToGetTagFrom, or NULL. If NULL */
1582 /* then the current item in the list will */
1584 /* uint * ItemSize : The size, in bytes, of the */
1585 /* current item in the list. */
1586 /* TAG * Tag : The address of a variable to hold */
1587 /* the returned tag. */
1589 /* Output: If successful, the function returns DLIST_SUCCESS. */
1590 /* *ItemSize contains the size of the item. *Tag */
1591 /* contains the tag. */
1592 /* If unsuccessful, an error code is returned. */
1594 /* Error Handling: This function will fail if ListToGetTagFrom is */
1595 /* not a valid list or is an empty list. In either*/
1596 /* of these cases, an error code is returned. */
1598 /* Side Effects: None. */
1600 /*********************************************************************/
1601 int GetTag(dlist_t ListToGetTagFrom,
1607 /*********************************************************************/
1609 /* Function Name: GetHandle */
1611 /* Descriptive Name: This function returns a handle for the */
1612 /* current item in the list. This handle is */
1613 /* then associated with that item regardless of */
1614 /* its position in the list. This handle can be*/
1615 /* used to make its associated item the current */
1616 /* item in the list. */
1618 /* Input: dlist_t ListToGetHandleFrom : The list from which a */
1619 /* handle is needed. */
1620 /* ADDRESS * Handle : The address of a variable to hold */
1623 /* Output: If successful, the function returns DLIST_SUCCESS and */
1624 /* *Handle is set to the handle for the current item */
1625 /* in ListToGetHandleFrom. */
1626 /* If unsuccessful, an error code is returned and *Handle */
1629 /* Error Handling: This function will fail if ListToGetHandleFrom */
1630 /* is not a valid list or is an empty list. In */
1631 /* either of these cases, an error code is */
1634 /* Side Effects: None. */
1636 /* Notes: The handle returned is a pointer to the LinkNode of the */
1637 /* current item in the list. This allows the item to move */
1638 /* around in the list without losing its associated handle.*/
1639 /* However, if the item is deleted from the list, then the */
1640 /* handle is invalid and its use could result in a trap. */
1642 /*********************************************************************/
1643 int GetHandle (dlist_t ListToGetHandleFrom,
1648 /*********************************************************************/
1650 /* Function Name: GetListSize */
1652 /* Descriptive Name: This function returns the number of items in */
1655 /* Input: dlist_t ListToGetSizeOf : The list whose size we wish to*/
1657 /* uint * Size : The address of a variable to hold */
1658 /* the size of the list. */
1660 /* Output: If successful, the function returns DLIST_SUCCESS and */
1661 /* *Size contains the a count of the number of items */
1663 /* If unsuccessful, an error code is returned and *Size */
1666 /* Error Handling: This function will fail if ListToGetSizeOf is */
1667 /* not a valid list. If this happens, then an */
1668 /* error code is returned. . */
1670 /* Side Effects: None. */
1672 /* Notes: It is assumed that Size contains a valid address. If */
1673 /* this assumption is violated, an exception or trap */
1676 /*********************************************************************/
1677 int GetListSize(dlist_t ListToGetSizeOf,
1681 /*********************************************************************/
1683 /* Function Name: ListEmpty */
1685 /* Descriptive Name: This function returns TRUE if the */
1686 /* specified list is empty, otherwise it returns*/
1689 /* Input: dlist_t ListToCheck : The list to check to see if it*/
1692 /* Output: If successful, the function returns TRUE if the */
1693 /* number of items in the list is 0, otherwise it */
1694 /* returns FALSE. */
1695 /* If unsuccessful, the function returns TRUE. */
1697 /* Error Handling: This function will return TRUE if ListToCheck */
1698 /* is not a valid list. */
1700 /* Side Effects: None. */
1702 /*********************************************************************/
1703 BOOLEAN ListEmpty(dlist_t ListToCheck);
1706 /*********************************************************************/
1708 /* Function Name: AtEndOfList */
1710 /* Descriptive Name: This function returns TRUE if the */
1711 /* current item in the list is the last item */
1712 /* in the list. Returns FALSE otherwise. */
1714 /* Input: dlist_t ListToCheck : The list to check. */
1716 /* Output: If successful, the function returns TRUE if the */
1717 /* current item in the list is the last item in the */
1718 /* list. If it is not the last item in the list, */
1719 /* FALSE is returned. */
1720 /* If unsuccessful, the function returns FALSE. */
1722 /* Error Handling: This function will return FALSE ListToCheck is */
1723 /* not a valid list. */
1725 /* Side Effects: None. */
1727 /*********************************************************************/
1728 BOOLEAN AtEndOfList(dlist_t ListToCheck);
1731 /*********************************************************************/
1733 /* Function Name: AtStartOfList */
1735 /* Descriptive Name: This function returns TRUE if the */
1736 /* current item in the list is the first item */
1737 /* in the list. Returns FALSE otherwise. */
1739 /* Input: dlist_t ListToCheck : The list to check. */
1741 /* Output: If successful, the function returns TRUE if the */
1742 /* current item in the list is the first item in the */
1743 /* list. If it is not the first item in the list, */
1744 /* FALSE is returned. */
1745 /* If unsuccessful, the function returns FALSE */
1747 /* Error Handling: This function will return FALSE if ListToCheck */
1748 /* is not a valid list. */
1750 /* Side Effects: None. */
1752 /*********************************************************************/
1753 BOOLEAN AtStartOfList(dlist_t ListToCheck);
1756 /*********************************************************************/
1758 /* Function Name: DestroyList */
1760 /* Descriptive Name: This function releases the memory associated */
1761 /* with the internal data structures of a */
1762 /* dlist_t. Once a dlist_t has been destroyed */
1763 /* by this function, it must be reinitialized */
1764 /* before it can be used again. */
1766 /* Input: dlist_t ListToDestroy : The list to be eliminated */
1768 /* BOOLEAN FreeItemMemory : If TRUE, all items in the list */
1769 /* will be freed. If FALSE, all */
1770 /* items in the list are not */
1771 /* freed, only the list structures*/
1772 /* associated with them are. */
1774 /* Output: If successful, return DLIST_SUCCESS */
1775 /* If unsuccessful, return an error code. */
1777 /* Error Handling: This function will fail if ListToDestroy is not */
1778 /* a valid list. If this happens, then an error */
1779 /* code is returned. */
1781 /* Side Effects: None. */
1783 /* Notes: If FreeItemMemory is TRUE, then this function will try */
1784 /* to delete any items which may be in the list. However, */
1785 /* since this function has no way of knowing the internal */
1786 /* structure of an item, items which contain embedded */
1787 /* pointers will not be entirely freed. This can lead to */
1788 /* memory leaks. The programmer should ensure that any */
1789 /* list passed to this function when the FreeItemMemory */
1790 /* parameter is TRUE is empty or does not contain any */
1791 /* items with embedded pointers. */
1793 /*********************************************************************/
1794 int DestroyList(dlist_t * ListToDestroy,
1795 BOOLEAN FreeItemMemory);
1798 /*********************************************************************/
1800 /* Function Name: NextItem */
1802 /* Descriptive Name: This function makes the next item in the list*/
1803 /* the current item in the list (i.e. it */
1804 /* advances the current item pointer). */
1806 /* Input: dlist_t ListToAdvance : The list whose current item */
1807 /* pointer is to be advanced */
1809 /* Output: If successful, return DLIST_SUCCESS. */
1810 /* If unsuccessful, return error code. */
1812 /* Error Handling: This function will fail under the following */
1814 /* ListToAdvance is not a valid list */
1815 /* ListToAdvance is empty */
1816 /* The current item is the last item in the */
1818 /* If any of these conditions occurs, then an */
1819 /* error code is returned. */
1821 /* Side Effects: None. */
1823 /*********************************************************************/
1824 int NextItem(dlist_t ListToAdvance);
1827 /*********************************************************************/
1829 /* Function Name: PreviousItem */
1831 /* Descriptive Name: This function makes the previous item in the */
1832 /* list the current item in the list. */
1834 /* Input: dlist_t ListToChange : The list whose current item */
1835 /* pointer is to be changed */
1837 /* Output: If successful, return DLIST_SUCCESS. */
1838 /* If unsuccessful, return an error code. */
1840 /* Error Handling: This function will fail under the following */
1842 /* ListToChange is not a valid list */
1843 /* ListToChange is empty */
1844 /* The current item is the first item in the */
1846 /* If any of these conditions occurs, then return */
1847 /* an error code. */
1849 /* Side Effects: None. */
1851 /*********************************************************************/
1852 int PreviousItem(dlist_t ListToChange);
1855 /*********************************************************************/
1857 /* Function Name: GoToStartOfList */
1859 /* Descriptive Name: This function makes the first item in the */
1860 /* list the current item in the list. */
1862 /* Input: dlist_t ListToReset : The list whose current item */
1863 /* is to be set to the first */
1864 /* item in the list */
1866 /* Output: If successful, return DLIST_SUCCESS. */
1867 /* If unsuccessful, return an error code */
1869 /* Error Handling: This function will fail if ListToAdvance is not */
1870 /* a valid list. If this occurs, then an error */
1871 /* code is returned. */
1873 /* Side Effects: None. */
1875 /*********************************************************************/
1876 int GoToStartOfList(dlist_t ListToReset);
1879 /*********************************************************************/
1881 /* Function Name: GoToEndOfList */
1883 /* Descriptive Name: This function makes the last item in the */
1884 /* list the current item in the list. */
1886 /* Input: dlist_t ListToSet : The list whose current item */
1887 /* is to be set to the last item */
1890 /* Output: If successful, return DLIST_SUCCESS. */
1891 /* If unsuccessful, return an error code */
1893 /* Error Handling: This function will fail if ListToAdvance is not */
1894 /* a valid list. If this occurs, then an error */
1895 /* code is returned. */
1897 /* Side Effects: None. */
1899 /*********************************************************************/
1900 int GoToEndOfList(dlist_t ListToSet);
1903 /*********************************************************************/
1905 /* Function Name: GoToSpecifiedItem */
1907 /* Descriptive Name: This function makes the item associated with */
1908 /* Handle the current item in the list. */
1910 /* Input: dlist_t ListToReposition: The list whose current item */
1911 /* is to be set to the item */
1912 /* associated with Handle. */
1913 /* ADDRESS Handle : A handle obtained by using the */
1914 /* GetHandle function. This handle */
1915 /* identifies a unique item in the list. */
1917 /* Output: If successful, return DLIST_SUCCESS. */
1918 /* If unsuccessful, return an error code */
1920 /* Error Handling: This function will fail if ListToAdvance is not */
1921 /* a valid list. If this occurs, then an error */
1922 /* code is returned. */
1924 /* Side Effects: None. */
1926 /* Notes: It is assumed that Handle is a valid handle and that */
1927 /* the item associated with Handle is still in the list. */
1928 /* If these conditions are not met, an exception or trap */
1931 /*********************************************************************/
1932 int GoToSpecifiedItem(dlist_t ListToReposition,
1936 /*********************************************************************/
1938 /* Function Name: SortList */
1940 /* Descriptive Name: This function sorts the contents of a list. */
1941 /* The sorting algorithm used is a stable sort */
1942 /* whose performance is not dependent upon the */
1943 /* initial order of the items in the list. */
1945 /* Input: dlist_t ListToSort : The dlist_t that is to be sorted. */
1947 /* int (*Compare) ( ... ) */
1949 /* This is a pointer to a function that can compare any */
1950 /* two items in the list. It should return -1 if */
1951 /* Object1 is less than Object2, 0 if Object1 is equal */
1952 /* to Object2, and 1 if Object1 is greater than Object2.*/
1953 /* This function will be called during the sort whenever*/
1954 /* the sorting algorithm needs to compare two objects. */
1956 /* The Compare function takes the following parameters: */
1958 /* ADDRESS Object1 : The address of the data for the */
1959 /* first object to be compared. */
1960 /* TAG Object1Tag : The user assigned TAG value for the */
1961 /* first object to be compared. */
1962 /* ADDRESS Object2 : The address of the data for the */
1963 /* second object to be compared. */
1964 /* TAG Object2Tag : The user assigned TAG value for the */
1965 /* second object to be compared. */
1966 /* uint * Error : The address of a variable to hold the */
1967 /* error return value. */
1969 /* If this function ever sets *Error to a non-zero value*/
1970 /* the sort will terminate and the error code will be */
1971 /* returned to the caller of the SortList function. */
1974 /* Output: If successful, this function will return DLIST_SUCCESS */
1975 /* and ListToSort will have been sorted. */
1976 /* If unsuccessful, an error code will be returned. */
1977 /* The order of the items in ListToSort is undefined */
1978 /* and may have changed. */
1980 /* Error Handling: This function will terminate if *Compare sets */
1981 /* *Error to a non-zero value, or if ListToSort */
1982 /* is invalid. If this function does terminate in */
1983 /* the middle of a sort, the order of the items in */
1984 /* ListToSort may be different than it was before */
1985 /* the function was called. */
1987 /* Side Effects: None. */
1989 /* Notes: This function works by breaking the list into sublists */
1990 /* and merging the sublists back into one list. The size */
1991 /* of the sublists starts at 1, and with each pass, the */
1992 /* of the sublists is doubled. The sort ends when the size*/
1993 /* of a sublist is greater than the size of the original */
1996 /*********************************************************************/
1997 int SortList(dlist_t ListToSort,
1998 int (*Compare) (ADDRESS Object1,
2005 /*********************************************************************/
2007 /* Function Name: ForEachItem */
2009 /* Descriptive Name: This function passes a pointer to each item */
2010 /* in a list to a user provided function for */
2011 /* processing by the user provided function. */
2013 /* Input: dlist_t ListToProcess : The dlist_t whose items are to */
2014 /* be processed by the user */
2015 /* provided function. */
2017 /* int (*ProcessItem) (...) */
2019 /* This is a pointer to the user provided function. */
2020 /* This user provided function takes the following */
2023 /* ADDRESS Object : A pointer to an item in */
2024 /* ListToProcess. */
2025 /* TAG Object1Tag : The user assigned TAG value for */
2026 /* the item pointed to by Object. */
2027 /* ADDRESS Parameter : The address of a block of */
2028 /* memory containing any */
2029 /* parameters that the user */
2030 /* wishes to have passed to this*/
2033 /* ADDRESS Parameters : This field is passed through to */
2034 /* *ProcessItem. This function does */
2035 /* not even look at the contents of */
2036 /* this field. This field is here to */
2037 /* provide the user a way to pass */
2038 /* additional data to *ProcessItem */
2039 /* that *ProcessItem may need to */
2040 /* function correctly. */
2042 /* Output: If successful, return DLIST_SUCCESS. */
2043 /* If unsuccessful, return an error code. */
2045 /* Error Handling: This function aborts immediately when an error */
2046 /* is detected, and any remaining items in the list*/
2047 /* will not be processed. */
2049 /* Side Effects: None. */
2051 /* Notes: This function allows the user to access all of the items */
2052 /* in a list and perform an operation on them. The */
2053 /* operation performed must not free any items in the list, */
2054 /* or perform any list operations on the list being */
2057 /* As an example of when this would be useful, consider a */
2058 /* a list of graphic objects (rectangles, triangles, circles*/
2059 /* etc.) which comprise a drawing. To draw the picture */
2060 /* that these graphic objects represent, one could build a */
2061 /* loop which gets and draws each item. Another way to */
2062 /* do this would be to build a drawing function which can */
2063 /* draw any of the graphic objects, and then use that */
2064 /* function as the ProcessItem function in a call to */
2067 /* If the ProcessItem function returns an error code */
2068 /* other than DLIST_SUCCESS, then ForEachItem will terminate*/
2069 /* and return an error to whoever called it. The single */
2070 /* exception to this is if ProcessItem returns */
2071 /* DLIST_SEARCH_COMPLETE, in which case ForEachItem */
2072 /* terminates and returns DLIST_SUCCESS. This is */
2073 /* useful for using ForEachItem to search a list and then */
2074 /* terminating the search once the desired item is found. */
2076 /* A word about the Parameters parameter. This parameter */
2077 /* is passed through to *ProcessItem and is never looked at */
2078 /* by this function. This means that the user can put any */
2079 /* value they desire into Parameters as long as it is the */
2080 /* same size (in bytes) as Parameters. The intended use of */
2081 /* Parameters is to allow the user to pass information to */
2082 /* *ProcessItem that *ProcessItem may need. Either way, */
2083 /* how Parameters is used is literally up to the user. */
2085 /*********************************************************************/
2086 int ForEachItem(dlist_t ListToProcess,
2087 int (*ProcessItem) (ADDRESS Object,
2090 ADDRESS ObjectHandle,
2091 ADDRESS Parameters),
2096 /*********************************************************************/
2098 /* Function Name: PruneList */
2100 /* Descriptive Name: This function allows the caller to examine */
2101 /* each item in a list and optionally delete */
2102 /* it from the list. */
2104 /* Input: dlist_t ListToProcess : The dlist_t to be pruned. */
2106 /* BOOLEAN (*KillItem) (...) */
2108 /* This is a pointer to a user provided function. */
2109 /* This user provided function takes the following */
2112 /* ADDRESS Object : A pointer to an item in */
2113 /* ListToProcess. */
2114 /* TAG Object1Tag : The user assigned TAG value for */
2115 /* the item pointed to by Object. */
2116 /* ADDRESS Parameter : The address of a block of */
2117 /* memory containing any */
2118 /* parameters that the user */
2119 /* wishes to have passed to this*/
2121 /* BOOLEAN * FreeMemory : The address of a BOOLEAN */
2122 /* variable which this */
2123 /* function will set to */
2124 /* either TRUE or FALSE. */
2125 /* If the function return */
2126 /* value is TRUE, then the */
2127 /* value in *FreeMemory will */
2128 /* be examined. If it is */
2129 /* TRUE, then PruneList will */
2130 /* free the memory associated*/
2131 /* with the item being */
2132 /* deleted. If *FreeMemory */
2133 /* is FALSE, then the item */
2134 /* being removed from the */
2135 /* dlist_t will not be freed,*/
2136 /* and it is up to the user */
2137 /* to ensure that this memory*/
2138 /* is handled properly. */
2139 /* uint * Error : The address of a variable to*/
2140 /* hold the error return value.*/
2142 /* ADDRESS Parameters : This field is passed through to */
2143 /* *KillItem. This function does */
2144 /* not even look at the contents of */
2145 /* this field. This field is here to */
2146 /* provide the user a way to pass */
2147 /* additional data to *ProcessItem */
2148 /* that *ProcessItem may need to */
2149 /* function correctly. */
2152 /* Output: If successful, return DLIST_SUCCESS. */
2153 /* If unsuccessful, return an error code. */
2155 /* Error Handling: This function aborts immediately when an error */
2156 /* is detected, and any remaining items in the list*/
2157 /* will not be processed. */
2159 /* Side Effects: None. */
2161 /* Notes: This function allows the user to access all of the items */
2162 /* in a list, perform an operation on them, and then */
2163 /* optionally delete ("remove") them from the dlist_t. The */
2164 /* operation performed must not free any items in the list, */
2165 /* or perform any list operations on the list being */
2168 /* If the KillItem function sets *Error to something other */
2169 /* than DLIST_SUCCESS, then PruneList will terminate and */
2170 /* return an error to whoever called it. The single */
2171 /* exception to this is if KillItem sets *Error to */
2172 /* DLIST_SEARCH_COMPLETE, in which case KillItem */
2173 /* terminates and sets *Error to DLIST_SUCCESS. This is */
2174 /* useful for using KillItem to search a list and then */
2175 /* terminating the search once the desired item is found. */
2177 /* A word about the Parameters parameter. This parameter */
2178 /* is passed through to *ProcessItem and is never looked at */
2179 /* by this function. This means that the user can put any */
2180 /* value they desire into Parameters as long as it is the */
2181 /* same size (in bytes) as Parameters. The intended use of */
2182 /* Parameters is to allow the user to pass information to */
2183 /* *ProcessItem that *ProcessItem may need. Either way, */
2184 /* how Parameters is used is literally up to the user. */
2186 /*********************************************************************/
2187 int PruneList(dlist_t ListToProcess,
2188 BOOLEAN (*KillItem) (ADDRESS Object,
2191 ADDRESS ObjectHandle,
2193 BOOLEAN * FreeMemory,
2195 ADDRESS Parameters);
2197 /*********************************************************************/
2199 /* Function Name: AppendList */
2201 /* Descriptive Name: Removes the items in SourceList and appends */
2202 /* them to TargetList. */
2204 /* Input: dlist_t TargetList : The dlist_t which is to have the */
2205 /* items from SourceList appended to */
2207 /* dlist_t SourceList : The dlist_t whose items are to be */
2208 /* removed and appended to TargetList.*/
2210 /* Output: If successful, return DLIST_SUCCESS. */
2211 /* SourceList will be empty, and TargetList will contain*/
2212 /* all of its original items and all of the items that */
2213 /* were in SourceList. */
2214 /* If unsuccessful, return an error code. SourceList and */
2215 /* TargetList will be unmodified. */
2217 /* Error Handling: This function will abort immediately upon */
2218 /* detection of an error. All errors that can be */
2219 /* detected are detected before the contents of */
2220 /* SourceList are appended to TargetList, so if an*/
2221 /* error is detected and the function aborts, */
2222 /* SourceList and TargetList are unaltered. */
2224 /* Side Effects: None. */
2228 /*********************************************************************/
2229 int AppendList(dlist_t TargetList,
2230 dlist_t SourceList);
2233 /*********************************************************************/
2235 /* Function Name: TransferItem */
2237 /* Descriptive Name: Removes an item in SourceList and places in */
2240 /* Input: dlist_t SourceList : The dlist_t containing the item */
2241 /* which is to be transferred. */
2242 /* ADDRESS SourceHandle : The handle of the item in */
2243 /* SourceList which is to be */
2244 /* transferred to another dlist_t. */
2245 /* If this is NULL, then the */
2246 /* current item in SourceList will */
2248 /* dlist_t TargetList : The dlist_t which is to receive the*/
2249 /* item being transferred. */
2250 /* ADDRESS TargetHandle : The item in TargetList which */
2251 /* is used to determine where */
2252 /* the item being transferred will */
2253 /* be placed. If this is NULL, */
2254 /* then the current item in */
2255 /* TargetList will be used. */
2256 /* Insertion_Modes TransferMode : This indicates where, */
2257 /* relative to the item in */
2258 /* TargetList specified by */
2259 /* Target_Handle, the item being */
2260 /* transferred can be placed. */
2261 /* BOOLEAN MakeCurrent : If TRUE, the item transferred to */
2262 /* TargetList becomes the current */
2263 /* item in TargetList. */
2265 /* Output: If successful, return DLIST_SUCCESS, SourceList will be */
2266 /* empty, and TargetList will contain all of its */
2267 /* original items and all of the items that were in */
2269 /* If unsuccessful, an error code will be returned and */
2270 /* SourceList and TargetList will be unmodified. */
2272 /* Error Handling: This function will abort immediately upon */
2273 /* detection of an error. All errors that can be */
2274 /* detected are detected before the contents of */
2275 /* SourceList are appended to TargetList, so if an*/
2276 /* error is detected and the function aborts, */
2277 /* SourceList and TargetList are unaltered. */
2279 /* Side Effects: None. */
2283 /*********************************************************************/
2284 int TransferItem(dlist_t SourceList,
2285 ADDRESS SourceHandle,
2287 ADDRESS TargetHandle,
2288 Insertion_Modes TransferMode,
2289 BOOLEAN MakeCurrent);
2292 /*********************************************************************/
2294 /* Function Name: CopyList */
2296 /* Descriptive Name: Copies the items in SourceList to the */
2299 /* Input: dlist_t TargetList : The dlist_t which is to have the */
2300 /* items from SourceList copied to it.*/
2301 /* dlist_t SourceList : The dlist_t whose items are to be */
2302 /* copied to TargetList. */
2304 /* Output: If successful, return DLIST_SUCCESS. */
2305 /* SourceList will be unchanged and TargetList will */
2306 /* contain all of its original items and all of the */
2307 /* items that were in SourceList. */
2308 /* If unsuccessful, return an error code. SourceList and */
2309 /* TargetList will be unmodified. */
2311 /* Error Handling: This function will abort immediately upon */
2312 /* detection of an error. All errors that can be */
2313 /* detected are detected before the contents of */
2314 /* SourceList are appended to TargetList, so if an*/
2315 /* error is detected and the function aborts, */
2316 /* SourceList and TargetList are unaltered. */
2318 /* Side Effects: None. */
2322 /*********************************************************************/
2323 int CopyList(dlist_t TargetList,
2325 Insertion_Modes Insert_Mode);
2328 /*********************************************************************/
2330 /* Function Name: CheckListIntegrity */
2332 /* Descriptive Name: Checks the integrity of a dlist_t. All link */
2333 /* nodes in the list are checked, as are all */
2334 /* fields in the list control block. */
2336 /* Input: dlist_t ListToCheck - The list whose integrity is to be */
2339 /* Output: The function return value will be TRUE if all of the */
2340 /* elements in the dlist_t are correct. If this function */
2341 /* returns FALSE, then the dlist_t being checked has been */
2344 /* Error Handling: If this function encounters an error in a */
2345 /* dlist_t, it will return FALSE. */
2347 /* Side Effects: None. */
2351 /*********************************************************************/
2352 BOOLEAN CheckListIntegrity(dlist_t ListToCheck);
git://git.whamcloud.com / tools / e2fsprogs.git / blob