Change in porting tactics: OS/2's EMX porting layer doesn't allow multiple
[privoxy.git] / list.c
1 const char list_rcs[] = "$Id: list.c,v 1.11 2001/10/23 21:21:03 jongfoster Exp $";
2 /*********************************************************************
3  *
4  * File        :  $Source: /cvsroot/ijbswa/current/list.c,v $
5  *
6  * Purpose     :  Declares functions to handle lists.
7  *                Functions declared include:
8  *                   `destroy_list', `enlist' and `list_to_text'
9  *
10  * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
11  *                IJBSWA team.  http://ijbswa.sourceforge.net
12  *
13  *                Based on the Internet Junkbuster originally written
14  *                by and Copyright (C) 1997 Anonymous Coders and
15  *                Junkbusters Corporation.  http://www.junkbusters.com
16  *
17  *                This program is free software; you can redistribute it
18  *                and/or modify it under the terms of the GNU General
19  *                Public License as published by the Free Software
20  *                Foundation; either version 2 of the License, or (at
21  *                your option) any later version.
22  *
23  *                This program is distributed in the hope that it will
24  *                be useful, but WITHOUT ANY WARRANTY; without even the
25  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
26  *                PARTICULAR PURPOSE.  See the GNU General Public
27  *                License for more details.
28  *
29  *                The GNU General Public License should be included with
30  *                this file.  If not, you can view it at
31  *                http://www.gnu.org/copyleft/gpl.html
32  *                or write to the Free Software Foundation, Inc., 59
33  *                Temple Place - Suite 330, Boston, MA  02111-1307, USA.
34  *
35  * Revisions   :
36  *    $Log: list.c,v $
37  *    Revision 1.11  2001/10/23 21:21:03  jongfoster
38  *    New error handling - error codes are now jb_errs, not ints.
39  *    Changed the way map() handles out-of-memory, to dramatically
40  *    reduce the amount of error-checking clutter needed.
41  *
42  *    Revision 1.10  2001/09/16 17:30:24  jongfoster
43  *    Fixing a compiler warning.
44  *
45  *    Revision 1.9  2001/09/16 13:20:29  jongfoster
46  *    Rewrite of list library.  Now has seperate header and list_entry
47  *    structures.  Also added a large sprinking of assert()s to the list
48  *    code.
49  *
50  *    Revision 1.8  2001/08/07 14:00:20  oes
51  *    Fixed comment
52  *
53  *    Revision 1.7  2001/08/05 16:06:20  jongfoster
54  *    Modifiying "struct map" so that there are now separate header and
55  *    "map_entry" structures.  This means that functions which modify a
56  *    map no longer need to return a pointer to the modified map.
57  *    Also, it no longer reverses the order of the entries (which may be
58  *    important with some advanced template substitutions).
59  *
60  *    Revision 1.6  2001/07/31 14:44:51  oes
61  *    list_to_text() now appends empty line at end
62  *
63  *    Revision 1.5  2001/06/29 21:45:41  oes
64  *    Indentation, CRLF->LF, Tab-> Space
65  *
66  *    Revision 1.4  2001/06/29 13:30:22  oes
67  *    - Added Convenience function enlist_unique_header(),
68  *      which takes the Header name and value as separate
69  *      arguments and thus saves the pain of sprintf()ing
70  *      and determining the Header name length to enlist_unique
71  *    - Improved comments
72  *    - Removed logentry from cancelled commit
73  *
74  *    Revision 1.3  2001/06/03 19:12:24  oes
75  *    functions for new struct map, extended enlist_unique
76  *
77  *    Revision 1.2  2001/06/01 18:49:17  jongfoster
78  *    Replaced "list_share" with "list" - the tiny memory gain was not
79  *    worth the extra complexity.
80  *
81  *    Revision 1.1  2001/05/31 21:11:53  jongfoster
82  *    - Moved linked list support to new "list.c" file.
83  *      Structure definitions are still in project.h,
84  *      function prototypes are now in "list.h".
85  *    - Added support for "struct list_share", which is identical
86  *      to "struct list" except it saves memory by not duplicating
87  *      the strings.  Obviously, this only works if there is some
88  *      other way of managing the memory used by the strings.
89  *      (These list_share lists are used for lists which last
90  *      for only 1 request, and where all the list entries are
91  *      just coming directly from entries in the actionsfile.)
92  *      Note that you still need to destroy list_share lists
93  *      properly to free the nodes - it's only the strings
94  *      which are shared.
95  *
96  *
97  *********************************************************************/
98 \f
99
100 #include "config.h"
101
102 #ifndef _WIN32
103 /* FIXME: The following headers are not needed for Win32.  Are they
104  * needed on other platforms?
105  */
106 #include <stdio.h>
107 #include <sys/types.h>
108 #include <stdlib.h>
109 #include <ctype.h>
110 #endif
111 #include <string.h>
112
113 #if !defined(_WIN32) && !defined(__OS2__)
114 #include <unistd.h>
115 #endif
116
117 #include <assert.h>
118
119 #include "project.h"
120 #include "list.h"
121 #include "miscutil.h"
122
123 const char list_h_rcs[] = LIST_H_VERSION;
124
125
126 static int list_is_valid (const struct list *the_list);
127
128
129 /*********************************************************************
130  *
131  * Function    :  list_init
132  *
133  * Description :  Create a new, empty list in user-allocated memory.
134  *                Caller should allocate a "struct list" variable,
135  *                then pass it to this function.
136  *                (Implementation note:  Rather than calling this
137  *                function, you can also just memset the memory to
138  *                zero, e.g. if you have a larger structure you
139  *                want to initialize quickly.  However, that isn't
140  *                really good design.)
141  *
142  * Parameters  :
143  *          1  :  the_list = pointer to list
144  *
145  * Returns     :  N/A
146  *
147  *********************************************************************/
148 void init_list(struct list *the_list)
149 {
150    memset(the_list, '\0', sizeof(*the_list));
151 }
152
153
154 /*********************************************************************
155  *
156  * Function    :  destroy_list
157  *
158  * Description :  Destroy a string list (opposite of list_init).
159  *                On return, the memory used by the list entries has
160  *                been freed, but not the memory used by the_list
161  *                itself.  You should not re-use the_list without
162  *                calling list_init().
163  *
164  *                (Implementation note:  You *can* reuse the_list
165  *                without calling list_init(), but please don't.
166  *                If you want to remove all entries from a list
167  *                and still have a usable list, then use
168  *                list_remove_all().)
169  *
170  * Parameters  :
171  *          1  :  the_list = pointer to list
172  *
173  * Returns     :  N/A
174  *
175  *********************************************************************/
176 void destroy_list (struct list *the_list)
177 {
178    struct list_entry *cur_entry, *next_entry;
179
180    assert(the_list);
181
182    for (cur_entry = the_list->first; cur_entry ; cur_entry = next_entry)
183    {
184       next_entry = cur_entry->next;
185       freez(cur_entry->str);
186       free(cur_entry);
187    }
188
189    the_list->first = NULL;
190    the_list->last = NULL;
191 }
192
193
194 /*********************************************************************
195  *
196  * Function    :  list_is_valid
197  *
198  * Description :  Check that a string list is valid.  The intended
199  *                usage is "assert(list_is_valid(the_list))".
200  *                Currently this checks that "the_list->last"
201  *                is correct, and that the list dosn't contain
202  *                circular references.  It is likely to crash if
203  *                it's passed complete garbage.
204  *
205  * Parameters  :
206  *          1  :  the_list = pointer to list.  Must be non-null.
207  *
208  * Returns     :  1 if list is valid, 0 otherwise.
209  *
210  *********************************************************************/
211 static int list_is_valid (const struct list *the_list)
212 {
213    /*
214     * If you don't want this check, just change the line below
215     * from "#if 1" to "#if 0".
216     */
217 #if 1
218    const struct list_entry *cur_entry;
219    const struct list_entry *last_entry = NULL;
220    int length = 0;
221
222    assert(the_list);
223
224    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
225    {
226       last_entry = cur_entry;
227
228       if (cur_entry->str)
229       {
230          /*
231           * Just check that this string can be accessed - i.e. it's a valid
232           * pointer.
233           */
234          strlen(cur_entry->str);
235       }
236
237       /*
238        * Check for looping back to first
239        */
240       if ((length != 0) && (cur_entry == the_list->first))
241       {
242          return 0;
243       }
244
245       /*
246        * Arbitrarily limit length to prevent infinite loops.
247        */
248       if (++length > 1000)
249       {
250          return 0;
251       }
252
253       /*
254        * Check this isn't marked as the last entry, unless of course it's
255        * *really* the last entry.
256        */
257       if ((the_list->last == cur_entry) && (cur_entry->next != NULL))
258       {
259          /* This is the last entry, but there's data after it !!?? */
260          return 0;
261       }
262    }
263
264    return (the_list->last == last_entry);
265 #else
266    return 1;
267 #endif
268 }
269
270 /*********************************************************************
271  *
272  * Function    :  enlist
273  *
274  * Description :  Append a string into a specified string list.
275  *
276  * Parameters  :
277  *          1  :  the_list = pointer to list
278  *          2  :  str = string to add to the list (maybe NULL)
279  *
280  * Returns     :  JB_ERR_OK on success
281  *                JB_ERR_MEMORY on out-of-memory error.
282  *                On error, the_list will be unchanged.
283  *
284  *********************************************************************/
285 jb_err enlist(struct list *the_list, const char *str)
286 {
287    struct list_entry *cur;
288
289    assert(the_list);
290    assert(list_is_valid(the_list));
291
292    if (NULL == (cur = (struct list_entry *)zalloc(sizeof(*cur))))
293    {
294       return JB_ERR_MEMORY;
295    }
296
297    if (str)
298    {
299       if (NULL == (cur->str = strdup(str)))
300       {
301          free(cur);
302          return JB_ERR_MEMORY;
303       }
304    }
305    /* else { cur->str = NULL; }  - implied by zalloc */
306
307    /* cur->next = NULL;  - implied by zalloc */
308
309    if (the_list->last)
310    {
311       the_list->last->next = cur;
312       the_list->last = cur;
313    }
314    else
315    {
316       the_list->first = cur;
317       the_list->last = cur;
318    }
319
320    assert(list_is_valid(the_list));
321    return JB_ERR_OK;
322 }
323
324
325 /*********************************************************************
326  *
327  * Function    :  enlist_first
328  *
329  * Description :  Append a string as first element into a specified
330  *                string list.
331  *
332  * Parameters  :
333  *          1  :  the_list = pointer to list
334  *          2  :  str = string to add to the list (maybe NULL)
335  *
336  * Returns     :  JB_ERR_OK on success
337  *                JB_ERR_MEMORY on out-of-memory error.
338  *                On error, the_list will be unchanged.
339  *
340  *********************************************************************/
341 jb_err enlist_first(struct list *the_list, const char *str)
342 {
343    struct list_entry *cur;
344
345    assert(the_list);
346    assert(list_is_valid(the_list));
347
348    if (NULL == (cur = (struct list_entry *)zalloc(sizeof(*cur))))
349    {
350       return JB_ERR_MEMORY;
351    }
352
353    if (str)
354    {
355       if (NULL == (cur->str = strdup(str)))
356       {
357          free(cur);
358          return JB_ERR_MEMORY;
359       }
360    }
361    /* else { cur->str = NULL; }  - implied by zalloc */
362
363    cur->next = the_list->first;
364
365    the_list->first = cur;
366    if (the_list->last == NULL)
367    {
368       the_list->last = cur;
369    }
370
371    assert(list_is_valid(the_list));
372    return JB_ERR_OK;
373 }
374
375
376 /*********************************************************************
377  *
378  * Function    :  enlist_unique
379  *
380  * Description :  Append a string into a specified string list,
381  *                if & only if it's not there already.
382  *                If the num_significant_chars argument is nonzero,
383  *                only compare up to the nth character.
384  *
385  * Parameters  :
386  *          1  :  the_list = pointer to list
387  *          2  :  str = string to add to the list
388  *          3  :  num_significant_chars = number of chars to use
389  *                for uniqueness test, or 0 to require an exact match.
390  *
391  * Returns     :  JB_ERR_OK on success
392  *                JB_ERR_MEMORY on out-of-memory error.
393  *                On error, the_list will be unchanged.
394  *                "Success" does not indicate whether or not the
395  *                item was already in the list.
396  *
397  *********************************************************************/
398 jb_err enlist_unique(struct list *the_list, const char *str,
399                      int num_significant_chars)
400 {
401    struct list_entry *cur_entry;
402
403    assert(the_list);
404    assert(list_is_valid(the_list));
405    assert(str);
406    assert(num_significant_chars >= 0);
407    assert((size_t)num_significant_chars <= strlen(str));
408
409    if (num_significant_chars > 0)
410    {
411       for (cur_entry = the_list->first; cur_entry != NULL; cur_entry = cur_entry->next)
412       {
413          if ( (cur_entry->str != NULL)
414            && (0 == strncmp(str, cur_entry->str, num_significant_chars)))
415          {
416             /* Already there */
417             return JB_ERR_OK;
418          }
419       }
420    }
421    else
422    {
423       /* Test whole string */
424       for (cur_entry = the_list->first; cur_entry != NULL; cur_entry = cur_entry->next)
425       {
426          if ( (cur_entry->str != NULL) && (0 == strcmp(str, cur_entry->str)))
427          {
428             /* Already there */
429             return JB_ERR_OK;
430          }
431       }
432    }
433
434    return enlist(the_list, str);
435 }
436
437
438 /*********************************************************************
439  *
440  * Function    :  enlist_unique_header
441  *
442  * Description :  Make a HTTP header from the two strings name and value,
443  *                and append the result into a specified string list,
444  *                if & only if there isn't already a header with that name.
445  *
446  * Parameters  :
447  *          1  :  the_list = pointer to list
448  *          2  :  name = HTTP header name (e.g. "Content-type")
449  *          3  :  value = HTTP header value (e.g. "text/html")
450  *
451  * Returns     :  JB_ERR_OK on success
452  *                JB_ERR_MEMORY on out-of-memory error.
453  *                On error, the_list will be unchanged.
454  *                "Success" does not indicate whether or not the
455  *                header was already in the list.
456  *
457  *********************************************************************/
458 jb_err enlist_unique_header(struct list *the_list, const char *name,
459                             const char *value)
460 {
461    int length;
462    jb_err result;
463    char *str;
464
465    assert(the_list);
466    assert(list_is_valid(the_list));
467    assert(name);
468    assert(value);
469
470    length = strlen(name) + 2;
471    if (NULL == (str = (char *)malloc(length + strlen(value) + 1)))
472    {
473       return JB_ERR_MEMORY;
474    }
475    strcpy(str, name);
476    str[length - 2] = ':';
477    str[length - 1] = ' ';
478    strcpy(str + length, value);
479
480    result = enlist_unique(the_list, str, length);
481
482    free(str);
483
484    assert(list_is_valid(the_list));
485
486    return result;
487 }
488
489
490 /*********************************************************************
491  *
492  * Function    :  list_remove_all
493  *
494  * Description :  Remove all entries from a list.  On return, the_list
495  *                is a valid, empty list.  Note that this is similar
496  *                to destroy_list(), but the difference is that this
497  *                function guarantees that the list structure is still
498  *                valid after the call.
499  *
500  * Parameters  :
501  *          1  :  the_list = pointer to list
502  *
503  * Returns     :  N/A
504  *
505  *********************************************************************/
506 void list_remove_all(struct list *the_list)
507 {
508    struct list_entry *cur_entry;
509    struct list_entry *next_entry;
510
511    assert(the_list);
512    assert(list_is_valid(the_list));
513
514    for (cur_entry = the_list->first; cur_entry ; cur_entry = next_entry)
515    {
516       next_entry = cur_entry->next;
517       freez(cur_entry->str);
518       free(cur_entry);
519    }
520
521    the_list->first = the_list->last = NULL;
522
523    assert(list_is_valid(the_list));
524 }
525
526
527 /*********************************************************************
528  *
529  * Function    :  list_to_text
530  *
531  * Description :  "Flatten" a string list into 1 long \r\n delimited string,
532  *                adding an empty line at the end.  NULL entries are ignored.
533  *                This function does not change the_list.
534  *
535  * Parameters  :
536  *          1  :  the_list = pointer to list
537  *
538  * Returns     :  NULL on malloc error, else new long string.
539  *                Caller must free() it.
540  *
541  *********************************************************************/
542 char *list_to_text(const struct list *the_list)
543 {
544    struct list_entry *cur_entry;
545    char *ret = NULL;
546    char *s;
547    int size = 2;
548
549    assert(the_list);
550    assert(list_is_valid(the_list));
551
552    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
553    {
554       if (cur_entry->str)
555       {
556          size += strlen(cur_entry->str) + 2;
557       }
558    }
559
560    if ((ret = (char *)malloc(size + 1)) == NULL)
561    {
562       return NULL;
563    }
564
565    ret[size] = '\0';
566
567    s = ret;
568
569    for (cur_entry = the_list->first; cur_entry ; cur_entry = cur_entry->next)
570    {
571       if (cur_entry->str)
572       {
573          strcpy(s, cur_entry->str);
574          s += strlen(s);
575          *s++ = '\r'; *s++ = '\n';
576       }
577    }
578    *s++ = '\r'; *s++ = '\n';
579
580    return ret;
581 }
582
583
584 /*********************************************************************
585  *
586  * Function    :  list_remove_item
587  *
588  * Description :  Remove a string from a specified string list.
589  *
590  * Parameters  :
591  *          1  :  the_list = pointer to list
592  *          2  :  str = string to remove from the list - non-NULL
593  *
594  * Returns     :  Number of times it was removed.
595  *
596  *********************************************************************/
597 int list_remove_item(struct list *the_list, const char *str)
598 {
599    struct list_entry *prev = NULL;
600    struct list_entry *cur;
601    struct list_entry *next;
602    int count = 0;
603
604    assert(the_list);
605    assert(list_is_valid(the_list));
606    assert(str);
607
608    cur = the_list->first;
609
610    while (cur != NULL)
611    {
612       next = cur->next;
613
614       if ((cur->str != NULL) && (0 == strcmp(str, cur->str)))
615       {
616          count++;
617
618          if (prev != NULL)
619          {
620             prev->next = next;
621          }
622          else
623          {
624             the_list->first = next;
625          }
626          free((char *)cur->str);
627          free(cur);
628       }
629       else
630       {
631          prev = cur;
632       }
633       cur = next;
634    }
635
636    the_list->last = prev;
637
638    assert(list_is_valid(the_list));
639
640    return count;
641 }
642
643
644 /*********************************************************************
645  *
646  * Function    :  list_remove_list
647  *
648  * Description :  Remove all strings in one list from another list.
649  *                This is currently a brute-force algorithm
650  *                (it compares every pair of strings).
651  *
652  * Parameters  :
653  *          1  :  dest = list to change
654  *          2  :  src = list of strings to remove
655  *
656  * Returns     :  Total number of strings removed.
657  *
658  *********************************************************************/
659 int list_remove_list(struct list *dest, const struct list *src)
660 {
661    struct list_entry *cur;
662    int count = 0;
663
664    assert(src);
665    assert(dest);
666    assert(list_is_valid(src));
667    assert(list_is_valid(dest));
668
669    for (cur = src->first; cur != NULL; cur = cur->next)
670    {
671       if (cur->str != NULL)
672       {
673          count += list_remove_item(dest, cur->str);
674       }
675    }
676
677    assert(list_is_valid(src));
678    assert(list_is_valid(dest));
679
680    return count;
681 }
682
683
684 /*********************************************************************
685  *
686  * Function    :  list_duplicate
687  *
688  * Description :  Copy a string list
689  *
690  * Parameters  :
691  *          1  :  dest = Destination list.  Must be a valid list.
692  *                       All existing entries will be removed.
693  *          1  :  src = pointer to source list for copy.
694  *
695  * Returns     :  JB_ERR_OK on success
696  *                JB_ERR_MEMORY on out-of-memory error.
697  *                On error, dest will be empty.
698  *
699  *********************************************************************/
700 jb_err list_duplicate(struct list *dest, const struct list *src)
701 {
702    struct list_entry * cur_src;
703    struct list_entry * cur_dest;
704
705    assert(src);
706    assert(dest);
707    assert(list_is_valid(src));
708    assert(list_is_valid(dest));
709
710    list_remove_all(dest);
711
712    /* Need to process first entry specially so we can set dest->first */
713    cur_src = src->first;
714    if (cur_src)
715    {
716       cur_dest = dest->first = (struct list_entry *)zalloc(sizeof(*cur_dest));
717       if (cur_dest == NULL)
718       {
719          destroy_list(dest);
720
721          assert(list_is_valid(src));
722          assert(list_is_valid(dest));
723
724          return JB_ERR_MEMORY;
725       }
726
727       if (cur_src->str)
728       {
729          cur_dest->str = strdup(cur_src->str);
730          if (cur_dest->str == NULL)
731          {
732             destroy_list(dest);
733
734             assert(list_is_valid(src));
735             assert(list_is_valid(dest));
736
737             return JB_ERR_MEMORY;
738          }
739       }
740       /* else { cur_dest->str = NULL; }  - implied by zalloc */
741
742       /* Now process the rest */
743       for (cur_src = cur_src->next; cur_src; cur_src = cur_src->next)
744       {
745          cur_dest = cur_dest->next = (struct list_entry *)zalloc(sizeof(*cur_dest));
746          if (cur_dest == NULL)
747          {
748             destroy_list(dest);
749
750             assert(list_is_valid(src));
751             assert(list_is_valid(dest));
752
753             return JB_ERR_MEMORY;
754          }
755          if (cur_src->str)
756          {
757             cur_dest->str = strdup(cur_src->str);
758             if (cur_dest->str == NULL)
759             {
760                destroy_list(dest);
761
762                assert(list_is_valid(src));
763                assert(list_is_valid(dest));
764
765                return JB_ERR_MEMORY;
766             }
767          }
768          /* else { cur_dest->str = NULL; }  - implied by zalloc */
769       }
770
771       dest->last = cur_dest;
772    }
773
774    assert(list_is_valid(src));
775    assert(list_is_valid(dest));
776
777    return JB_ERR_OK;
778 }
779
780
781 /*********************************************************************
782  *
783  * Function    :  list_append_list_unique
784  *
785  * Description :  Append a string list to another list.
786  *                Duplicate items are not added.
787  *
788  * Parameters  :
789  *          1  :  dest = pointer to destination list for merge.
790  *          2  :  src = pointer to source for merge.
791  *
792  * Returns     :  JB_ERR_OK on success
793  *                JB_ERR_MEMORY on out-of-memory error.
794  *                On error, some (but not all) of src might have
795  *                been copied into dest.
796  *
797  *********************************************************************/
798 jb_err list_append_list_unique(struct list *dest, const struct list *src)
799 {
800    struct list_entry * cur;
801
802    assert(src);
803    assert(dest);
804    assert(list_is_valid(src));
805    assert(list_is_valid(dest));
806
807    for (cur = src->first; cur; cur = cur->next)
808    {
809       if (cur->str)
810       {
811          if (enlist_unique(dest, cur->str, 0))
812          {
813             assert(list_is_valid(src));
814             assert(list_is_valid(dest));
815
816             return JB_ERR_MEMORY;
817          }
818       }
819    }
820
821    assert(list_is_valid(src));
822    assert(list_is_valid(dest));
823
824    return JB_ERR_OK;
825 }
826
827
828 /*********************************************************************
829  *
830  * Function    :  list_is_empty
831  *
832  * Description :  Test whether a list is empty.  Does not change the list.
833  *
834  * Parameters  :
835  *          1  :  the_list = pointer to list to test.
836  *
837  * Returns     :  Nonzero iff the list contains no entries.
838  *
839  *********************************************************************/
840 int list_is_empty(const struct list *the_list)
841 {
842    assert(the_list);
843    assert(list_is_valid(the_list));
844
845    return (the_list->first == NULL);
846 }
847
848
849 /*********************************************************************
850  *
851  * Function    :  new_map
852  *
853  * Description :  Create a new, empty map.
854  *
855  * Parameters  :  N/A
856  *
857  * Returns     :  A new, empty map, or NULL if out of memory.
858  *
859  *********************************************************************/
860 struct map *new_map(void)
861 {
862    return (struct map *) zalloc(sizeof(struct map));
863 }
864
865
866 /*********************************************************************
867  *
868  * Function    :  free_map
869  *
870  * Description :  Free the memory occupied by a map and its
871  *                depandant strings
872  *
873  * Parameters  :
874  *          1  :  the_map = map to be freed.  May be NULL.
875  *
876  * Returns     :  N/A
877  *
878  *********************************************************************/
879 void free_map(struct map *the_map)
880 {
881    struct map_entry *cur_entry;
882    struct map_entry *next_entry;
883
884    if (the_map == NULL)
885    {
886       return;
887    }
888
889    for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = next_entry)
890    {
891       freez(cur_entry->name);
892       freez(cur_entry->value);
893
894       next_entry = cur_entry->next;
895       free(cur_entry);
896    }
897
898    the_map->first = the_map->last = NULL;
899
900    free(the_map);
901 }
902
903
904 /*********************************************************************
905  *
906  * Function    :  map
907  *
908  * Description :  Add a mapping from given name to given value to a
909  *                given map.
910  *
911  *                Note: Since all strings will be free()d in free_map()
912  *                      later, set the copy flags for constants or
913  *                      strings that will be independantly free()d.
914  *
915  *                Note2: This function allows NULL parameters - it
916  *                       returns JB_ERR_MEMORY in that case.
917  *
918  *                Note3: If this function returns JB_ERR_MEMORY,
919  *                       it will free(name) unless you specify
920  *                       name_needs_copying, and similarly it will
921  *                       free(value) unless you specify
922  *                       value_needs_copying.
923  *
924  *                Due to Note2 and Note3 above, the following code
925  *                is legal, and will never crash or leak memory even
926  *                if the system runs out of memory:
927  *
928  *                    err = map(mymap, "xyz", 1, html_encode(somestring), 0);
929  *
930  *                err will be set to JB_ERR_MEMORY if either call runs
931  *                out-of-memory.  Without these features, you would
932  *                need to check the return value of html_encode in the
933  *                above example for NULL, which (at least) doubles the
934  *                amount of error-checking code needed.
935  *
936  * Parameters  :
937  *          1  :  the_map = map to add to
938  *          2  :  name = name to add
939  *          3  :  name_needs_copying = flag set if a copy of name should be used
940  *          4  :  value = value to add
941  *          5  :  value_needs_copying = flag set if a copy of value should be used
942  *
943  * Returns     :  JB_ERR_OK on success
944  *                JB_ERR_MEMORY on out-of-memory error.
945  *
946  *********************************************************************/
947 jb_err map(struct map *the_map,
948            const char *name, int name_needs_copying,
949            const char *value, int value_needs_copying)
950 {
951    struct map_entry *new_entry;
952
953    assert(the_map);
954
955    if ( (NULL == value)
956      || (NULL == name)
957      || (NULL == (new_entry = zalloc(sizeof(*new_entry)))) )
958    {
959       if ((name != NULL) && (!name_needs_copying))
960       {
961           free((char *)name);
962       }
963       if ((value != NULL) && (!value_needs_copying))
964       {
965           free((char *)value);
966       }
967       return JB_ERR_MEMORY;
968    }
969
970    if (name_needs_copying)
971    {
972       if (NULL == (name = strdup(name)))
973       {
974          free(new_entry);
975          if (!value_needs_copying)
976          {
977              free((char *)value);
978          }
979          return JB_ERR_MEMORY;
980       }
981    }
982
983    if (value_needs_copying)
984    {
985       if (NULL == (value = strdup(value)))
986       {
987          free((char *)name);
988          free(new_entry);
989          return JB_ERR_MEMORY;
990       }
991    }
992
993    new_entry->name = name;
994    new_entry->value = value;
995    /* new_entry->next = NULL;  - implied by zalloc */
996
997    if (the_map->last)
998    {
999       the_map->last->next = new_entry;
1000       the_map->last = new_entry;
1001    }
1002    else
1003    {
1004       the_map->first = new_entry;
1005       the_map->last = new_entry;
1006    }
1007
1008    return JB_ERR_OK;
1009 }
1010
1011
1012 /*********************************************************************
1013  *
1014  * Function    :  lookup
1015  *
1016  * Description :  Look up an item with a given name in a map, and
1017  *                return its value
1018  *
1019  * Parameters  :
1020  *          1  :  the_map = map to look in
1021  *          2  :  name = name parameter to look for
1022  *
1023  * Returns     :  the value if found, else the empty string.
1024  *                Return value is alloced as part of the map, so
1025  *                it is freed when the map is destroyed.  Caller
1026  *                must not free or modify it.
1027  *
1028  *********************************************************************/
1029 const char *lookup(const struct map *the_map, const char *name)
1030 {
1031    const struct map_entry *cur_entry;
1032
1033    assert(the_map);
1034    assert(name);
1035
1036    for (cur_entry = the_map->first; cur_entry != NULL; cur_entry = cur_entry->next)
1037    {
1038       if (!strcmp(name, cur_entry->name))
1039       {
1040          return cur_entry->value;
1041       }
1042    }
1043    return "";
1044 }
1045
1046
1047 /*
1048   Local Variables:
1049   tab-width: 3
1050   end:
1051 */