Fix typo.
[kopensolaris-gnu/glibc.git] / manual / string.texi
1 @node String and Array Utilities, Character Set Handling, Character Handling, Top
2 @c %MENU% Utilities for copying and comparing strings and arrays
3 @chapter String and Array Utilities
4
5 Operations on strings (or arrays of characters) are an important part of
6 many programs.  The GNU C library provides an extensive set of string
7 utility functions, including functions for copying, concatenating,
8 comparing, and searching strings.  Many of these functions can also
9 operate on arbitrary regions of storage; for example, the @code{memcpy}
10 function can be used to copy the contents of any kind of array.
11
12 It's fairly common for beginning C programmers to ``reinvent the wheel''
13 by duplicating this functionality in their own code, but it pays to
14 become familiar with the library functions and to make use of them,
15 since this offers benefits in maintenance, efficiency, and portability.
16
17 For instance, you could easily compare one string to another in two
18 lines of C code, but if you use the built-in @code{strcmp} function,
19 you're less likely to make a mistake.  And, since these library
20 functions are typically highly optimized, your program may run faster
21 too.
22
23 @menu
24 * Representation of Strings::   Introduction to basic concepts.
25 * String/Array Conventions::    Whether to use a string function or an
26                                  arbitrary array function.
27 * String Length::               Determining the length of a string.
28 * Copying and Concatenation::   Functions to copy the contents of strings
29                                  and arrays.
30 * String/Array Comparison::     Functions for byte-wise and character-wise
31                                  comparison.
32 * Collation Functions::         Functions for collating strings.
33 * Search Functions::            Searching for a specific element or substring.
34 * Finding Tokens in a String::  Splitting a string into tokens by looking
35                                  for delimiters.
36 * strfry::                      Function for flash-cooking a string.
37 * Trivial Encryption::          Obscuring data.
38 * Encode Binary Data::          Encoding and Decoding of Binary Data.
39 * Argz and Envz Vectors::       Null-separated string vectors.
40 @end menu
41
42 @node Representation of Strings
43 @section Representation of Strings
44 @cindex string, representation of
45
46 This section is a quick summary of string concepts for beginning C
47 programmers.  It describes how character strings are represented in C
48 and some common pitfalls.  If you are already familiar with this
49 material, you can skip this section.
50
51 @cindex string
52 @cindex null character
53 A @dfn{string} is an array of @code{char} objects.  But string-valued
54 variables are usually declared to be pointers of type @code{char *}.
55 Such variables do not include space for the text of a string; that has
56 to be stored somewhere else---in an array variable, a string constant,
57 or dynamically allocated memory (@pxref{Memory Allocation}).  It's up to
58 you to store the address of the chosen memory space into the pointer
59 variable.  Alternatively you can store a @dfn{null pointer} in the
60 pointer variable.  The null pointer does not point anywhere, so
61 attempting to reference the string it points to gets an error.
62
63 By convention, a @dfn{null character}, @code{'\0'}, marks the end of a
64 string.  For example, in testing to see whether the @code{char *}
65 variable @var{p} points to a null character marking the end of a string,
66 you can write @code{!*@var{p}} or @code{*@var{p} == '\0'}.
67
68 A null character is quite different conceptually from a null pointer,
69 although both are represented by the integer @code{0}.
70
71 @cindex string literal
72 @dfn{String literals} appear in C program source as strings of
73 characters between double-quote characters (@samp{"}).  In @w{ISO C},
74 string literals can also be formed by @dfn{string concatenation}:
75 @code{"a" "b"} is the same as @code{"ab"}.  Modification of string
76 literals is not allowed by the GNU C compiler, because literals
77 are placed in read-only storage.
78
79 Character arrays that are declared @code{const} cannot be modified
80 either.  It's generally good style to declare non-modifiable string
81 pointers to be of type @code{const char *}, since this often allows the
82 C compiler to detect accidental modifications as well as providing some
83 amount of documentation about what your program intends to do with the
84 string.
85
86 The amount of memory allocated for the character array may extend past
87 the null character that normally marks the end of the string.  In this
88 document, the term @dfn{allocated size} is always used to refer to the
89 total amount of memory allocated for the string, while the term
90 @dfn{length} refers to the number of characters up to (but not
91 including) the terminating null character.
92 @cindex length of string
93 @cindex allocation size of string
94 @cindex size of string
95 @cindex string length
96 @cindex string allocation
97
98 A notorious source of program bugs is trying to put more characters in a
99 string than fit in its allocated size.  When writing code that extends
100 strings or moves characters into a pre-allocated array, you should be
101 very careful to keep track of the length of the text and make explicit
102 checks for overflowing the array.  Many of the library functions
103 @emph{do not} do this for you!  Remember also that you need to allocate
104 an extra byte to hold the null character that marks the end of the
105 string.
106
107 @node String/Array Conventions
108 @section String and Array Conventions
109
110 This chapter describes both functions that work on arbitrary arrays or
111 blocks of memory, and functions that are specific to null-terminated
112 arrays of characters.
113
114 Functions that operate on arbitrary blocks of memory have names
115 beginning with @samp{mem} (such as @code{memcpy}) and invariably take an
116 argument which specifies the size (in bytes) of the block of memory to
117 operate on.  The array arguments and return values for these functions
118 have type @code{void *}, and as a matter of style, the elements of these
119 arrays are referred to as ``bytes''.  You can pass any kind of pointer
120 to these functions, and the @code{sizeof} operator is useful in
121 computing the value for the size argument.
122
123 In contrast, functions that operate specifically on strings have names
124 beginning with @samp{str} (such as @code{strcpy}) and look for a null
125 character to terminate the string instead of requiring an explicit size
126 argument to be passed.  (Some of these functions accept a specified
127 maximum length, but they also check for premature termination with a
128 null character.)  The array arguments and return values for these
129 functions have type @code{char *}, and the array elements are referred
130 to as ``characters''.
131
132 In many cases, there are both @samp{mem} and @samp{str} versions of a
133 function.  The one that is more appropriate to use depends on the exact
134 situation.  When your program is manipulating arbitrary arrays or blocks of
135 storage, then you should always use the @samp{mem} functions.  On the
136 other hand, when you are manipulating null-terminated strings it is
137 usually more convenient to use the @samp{str} functions, unless you
138 already know the length of the string in advance.
139
140 @node String Length
141 @section String Length
142
143 You can get the length of a string using the @code{strlen} function.
144 This function is declared in the header file @file{string.h}.
145 @pindex string.h
146
147 @comment string.h
148 @comment ISO
149 @deftypefun size_t strlen (const char *@var{s})
150 The @code{strlen} function returns the length of the null-terminated
151 string @var{s}.  (In other words, it returns the offset of the terminating
152 null character within the array.)
153
154 For example,
155 @smallexample
156 strlen ("hello, world")
157     @result{} 12
158 @end smallexample
159
160 When applied to a character array, the @code{strlen} function returns
161 the length of the string stored there, not its allocated size.  You can
162 get the allocated size of the character array that holds a string using
163 the @code{sizeof} operator:
164
165 @smallexample
166 char string[32] = "hello, world";
167 sizeof (string)
168     @result{} 32
169 strlen (string)
170     @result{} 12
171 @end smallexample
172
173 But beware, this will not work unless @var{string} is the character
174 array itself, not a pointer to it.  For example:
175
176 @smallexample
177 char string[32] = "hello, world";
178 char *ptr = string;
179 sizeof (string)
180     @result{} 32
181 sizeof (ptr)
182     @result{} 4  /* @r{(on a machine with 4 byte pointers)} */
183 @end smallexample
184
185 This is an easy mistake to make when you are working with functions that
186 take string arguments; those arguments are always pointers, not arrays.
187
188 @end deftypefun
189
190 @comment string.h
191 @comment GNU
192 @deftypefun size_t strnlen (const char *@var{s}, size_t @var{maxlen})
193 The @code{strnlen} function returns the length of the null-terminated
194 string @var{s} is this length is smaller than @var{maxlen}.  Otherwise
195 it returns @var{maxlen}.  Therefore this function is equivalent to
196 @code{(strlen (@var{s}) < n ? strlen (@var{s}) : @var{maxlen})} but it
197 is more efficient.
198
199 @smallexample
200 char string[32] = "hello, world";
201 strnlen (string, 32)
202     @result{} 12
203 strnlen (string, 5)
204     @result{} 5
205 @end smallexample
206
207 This function is a GNU extension.
208 @end deftypefun
209
210 @node Copying and Concatenation
211 @section Copying and Concatenation
212
213 You can use the functions described in this section to copy the contents
214 of strings and arrays, or to append the contents of one string to
215 another.  These functions are declared in the header file
216 @file{string.h}.
217 @pindex string.h
218 @cindex copying strings and arrays
219 @cindex string copy functions
220 @cindex array copy functions
221 @cindex concatenating strings
222 @cindex string concatenation functions
223
224 A helpful way to remember the ordering of the arguments to the functions
225 in this section is that it corresponds to an assignment expression, with
226 the destination array specified to the left of the source array.  All
227 of these functions return the address of the destination array.
228
229 Most of these functions do not work properly if the source and
230 destination arrays overlap.  For example, if the beginning of the
231 destination array overlaps the end of the source array, the original
232 contents of that part of the source array may get overwritten before it
233 is copied.  Even worse, in the case of the string functions, the null
234 character marking the end of the string may be lost, and the copy
235 function might get stuck in a loop trashing all the memory allocated to
236 your program.
237
238 All functions that have problems copying between overlapping arrays are
239 explicitly identified in this manual.  In addition to functions in this
240 section, there are a few others like @code{sprintf} (@pxref{Formatted
241 Output Functions}) and @code{scanf} (@pxref{Formatted Input
242 Functions}).
243
244 @comment string.h
245 @comment ISO
246 @deftypefun {void *} memcpy (void *@var{to}, const void *@var{from}, size_t @var{size})
247 The @code{memcpy} function copies @var{size} bytes from the object
248 beginning at @var{from} into the object beginning at @var{to}.  The
249 behavior of this function is undefined if the two arrays @var{to} and
250 @var{from} overlap; use @code{memmove} instead if overlapping is possible.
251
252 The value returned by @code{memcpy} is the value of @var{to}.
253
254 Here is an example of how you might use @code{memcpy} to copy the
255 contents of an array:
256
257 @smallexample
258 struct foo *oldarray, *newarray;
259 int arraysize;
260 @dots{}
261 memcpy (new, old, arraysize * sizeof (struct foo));
262 @end smallexample
263 @end deftypefun
264
265 @comment string.h
266 @comment GNU
267 @deftypefun {void *} mempcpy (void *@var{to}, const void *@var{from}, size_t @var{size})
268 The @code{mempcpy} function is nearly identical to the @code{memcpy}
269 function.  It copies @var{size} bytes from the object beginning at
270 @code{from} into the object pointed to by @var{to}.  But instead of
271 returning the value of @var{to} it returns a pointer to the byte
272 following the last written byte in the object beginning at @var{to}.
273 I.e., the value is @code{((void *) ((char *) @var{to} + @var{size}))}.
274
275 This function is useful in situations where a number of objects shall be
276 copied to consecutive memory positions.
277
278 @smallexample
279 void *
280 combine (void *o1, size_t s1, void *o2, size_t s2)
281 @{
282   void *result = malloc (s1 + s2);
283   if (result != NULL)
284     mempcpy (mempcpy (result, o1, s1), o2, s2);
285   return result;
286 @}
287 @end smallexample
288
289 This function is a GNU extension.
290 @end deftypefun
291
292 @comment string.h
293 @comment ISO
294 @deftypefun {void *} memmove (void *@var{to}, const void *@var{from}, size_t @var{size})
295 @code{memmove} copies the @var{size} bytes at @var{from} into the
296 @var{size} bytes at @var{to}, even if those two blocks of space
297 overlap.  In the case of overlap, @code{memmove} is careful to copy the
298 original values of the bytes in the block at @var{from}, including those
299 bytes which also belong to the block at @var{to}.
300 @end deftypefun
301
302 @comment string.h
303 @comment SVID
304 @deftypefun {void *} memccpy (void *@var{to}, const void *@var{from}, int @var{c}, size_t @var{size})
305 This function copies no more than @var{size} bytes from @var{from} to
306 @var{to}, stopping if a byte matching @var{c} is found.  The return
307 value is a pointer into @var{to} one byte past where @var{c} was copied,
308 or a null pointer if no byte matching @var{c} appeared in the first
309 @var{size} bytes of @var{from}.
310 @end deftypefun
311
312 @comment string.h
313 @comment ISO
314 @deftypefun {void *} memset (void *@var{block}, int @var{c}, size_t @var{size})
315 This function copies the value of @var{c} (converted to an
316 @code{unsigned char}) into each of the first @var{size} bytes of the
317 object beginning at @var{block}.  It returns the value of @var{block}.
318 @end deftypefun
319
320 @comment string.h
321 @comment ISO
322 @deftypefun {char *} strcpy (char *@var{to}, const char *@var{from})
323 This copies characters from the string @var{from} (up to and including
324 the terminating null character) into the string @var{to}.  Like
325 @code{memcpy}, this function has undefined results if the strings
326 overlap.  The return value is the value of @var{to}.
327 @end deftypefun
328
329 @comment string.h
330 @comment ISO
331 @deftypefun {char *} strncpy (char *@var{to}, const char *@var{from}, size_t @var{size})
332 This function is similar to @code{strcpy} but always copies exactly
333 @var{size} characters into @var{to}.
334
335 If the length of @var{from} is more than @var{size}, then @code{strncpy}
336 copies just the first @var{size} characters.  Note that in this case
337 there is no null terminator written into @var{to}.
338
339 If the length of @var{from} is less than @var{size}, then @code{strncpy}
340 copies all of @var{from}, followed by enough null characters to add up
341 to @var{size} characters in all.  This behavior is rarely useful, but it
342 is specified by the @w{ISO C} standard.
343
344 The behavior of @code{strncpy} is undefined if the strings overlap.
345
346 Using @code{strncpy} as opposed to @code{strcpy} is a way to avoid bugs
347 relating to writing past the end of the allocated space for @var{to}.
348 However, it can also make your program much slower in one common case:
349 copying a string which is probably small into a potentially large buffer.
350 In this case, @var{size} may be large, and when it is, @code{strncpy} will
351 waste a considerable amount of time copying null characters.
352 @end deftypefun
353
354 @comment string.h
355 @comment SVID
356 @deftypefun {char *} strdup (const char *@var{s})
357 This function copies the null-terminated string @var{s} into a newly
358 allocated string.  The string is allocated using @code{malloc}; see
359 @ref{Unconstrained Allocation}.  If @code{malloc} cannot allocate space
360 for the new string, @code{strdup} returns a null pointer.  Otherwise it
361 returns a pointer to the new string.
362 @end deftypefun
363
364 @comment string.h
365 @comment GNU
366 @deftypefun {char *} strndup (const char *@var{s}, size_t @var{size})
367 This function is similar to @code{strdup} but always copies at most
368 @var{size} characters into the newly allocated string.
369
370 If the length of @var{s} is more than @var{size}, then @code{strndup}
371 copies just the first @var{size} characters and adds a closing null
372 terminator.  Otherwise all characters are copied and the string is
373 terminated.
374
375 This function is different to @code{strncpy} in that it always
376 terminates the destination string.
377
378 @code{strndup} is a GNU extension.
379 @end deftypefun
380
381 @comment string.h
382 @comment Unknown origin
383 @deftypefun {char *} stpcpy (char *@var{to}, const char *@var{from})
384 This function is like @code{strcpy}, except that it returns a pointer to
385 the end of the string @var{to} (that is, the address of the terminating
386 null character) rather than the beginning.
387
388 For example, this program uses @code{stpcpy} to concatenate @samp{foo}
389 and @samp{bar} to produce @samp{foobar}, which it then prints.
390
391 @smallexample
392 @include stpcpy.c.texi
393 @end smallexample
394
395 This function is not part of the ISO or POSIX standards, and is not
396 customary on Unix systems, but we did not invent it either.  Perhaps it
397 comes from MS-DOG.
398
399 Its behavior is undefined if the strings overlap.
400 @end deftypefun
401
402 @comment string.h
403 @comment GNU
404 @deftypefun {char *} stpncpy (char *@var{to}, const char *@var{from}, size_t @var{size})
405 This function is similar to @code{stpcpy} but copies always exactly
406 @var{size} characters into @var{to}.
407
408 If the length of @var{from} is more then @var{size}, then @code{stpncpy}
409 copies just the first @var{size} characters and returns a pointer to the
410 character directly following the one which was copied last.  Note that in
411 this case there is no null terminator written into @var{to}.
412
413 If the length of @var{from} is less than @var{size}, then @code{stpncpy}
414 copies all of @var{from}, followed by enough null characters to add up
415 to @var{size} characters in all.  This behaviour is rarely useful, but it
416 is implemented to be useful in contexts where this behaviour of the
417 @code{strncpy} is used.  @code{stpncpy} returns a pointer to the
418 @emph{first} written null character.
419
420 This function is not part of ISO or POSIX but was found useful while
421 developing the GNU C Library itself.
422
423 Its behaviour is undefined if the strings overlap.
424 @end deftypefun
425
426 @comment string.h
427 @comment GNU
428 @deftypefn {Macro} {char *} strdupa (const char *@var{s})
429 This macro is similar to @code{strdup} but allocates the new string
430 using @code{alloca} instead of @code{malloc} (@pxref{Variable Size
431 Automatic}).  This means of course the returned string has the same
432 limitations as any block of memory allocated using @code{alloca}.
433
434 For obvious reasons @code{strdupa} is implemented only as a macro;
435 you cannot get the address of this function.  Despite this limitation
436 it is a useful function.  The following code shows a situation where
437 using @code{malloc} would be a lot more expensive.
438
439 @smallexample
440 @include strdupa.c.texi
441 @end smallexample
442
443 Please note that calling @code{strtok} using @var{path} directly is
444 invalid.
445
446 This function is only available if GNU CC is used.
447 @end deftypefn
448
449 @comment string.h
450 @comment GNU
451 @deftypefn {Macro} {char *} strndupa (const char *@var{s}, size_t @var{size})
452 This function is similar to @code{strndup} but like @code{strdupa} it
453 allocates the new string using @code{alloca}
454 @pxref{Variable Size Automatic}.  The same advantages and limitations
455 of @code{strdupa} are valid for @code{strndupa}, too.
456
457 This function is implemented only as a macro, just like @code{strdupa}.
458
459 @code{strndupa} is only available if GNU CC is used.
460 @end deftypefn
461
462 @comment string.h
463 @comment ISO
464 @deftypefun {char *} strcat (char *@var{to}, const char *@var{from})
465 The @code{strcat} function is similar to @code{strcpy}, except that the
466 characters from @var{from} are concatenated or appended to the end of
467 @var{to}, instead of overwriting it.  That is, the first character from
468 @var{from} overwrites the null character marking the end of @var{to}.
469
470 An equivalent definition for @code{strcat} would be:
471
472 @smallexample
473 char *
474 strcat (char *to, const char *from)
475 @{
476   strcpy (to + strlen (to), from);
477   return to;
478 @}
479 @end smallexample
480
481 This function has undefined results if the strings overlap.
482 @end deftypefun
483
484 Programmers using the @code{strcat} function (or the following
485 @code{strncat} function for that matter) can easily be recognized as
486 lazy.  In almost all situations the lengths of the participating strings
487 are known.  Or at least, one could know them if one keeps track of the
488 results of the various function calls.  But then it is very inefficient
489 to use @code{strcat}.  A lot of time is wasted finding the end of the
490 destination string so that the actual copying can start.  This is a
491 common example:
492
493 @cindex __va_copy
494 @cindex va_copy
495 @smallexample
496 /* @r{This function concatenates arbitrarily many strings.  The last}
497    @r{parameter must be @code{NULL}.}  */
498 char *
499 concat (const char *str, ...)
500 @{
501   va_list ap, ap2;
502   size_t total = 1;
503   const char *s;
504   char *result;
505
506   va_start (ap, str);
507   /* @r{Actually @code{va_copy}, but this is the name more gcc versions}
508      @r{understand.}  */
509   __va_copy (ap2, ap);
510
511   /* @r{Determine how much space we need.}  */
512   for (s = str; s != NULL; s = va_arg (ap, const char *))
513     total += strlen (s);
514
515   va_end (ap);
516
517   result = (char *) malloc (total);
518   if (result != NULL)
519     @{
520       result[0] = '\0';
521
522       /* @r{Copy the strings.}  */
523       for (s = str; s != NULL; s = va_arg (ap2, const char *))
524         strcat (result, s);
525     @}
526
527   va_end (ap2);
528
529   return result;
530 @}
531 @end smallexample
532
533 This looks quite simple, especially the second loop where the strings
534 are actually copied.  But these innocent lines hide a major performance
535 penalty.  Just imagine that ten strings of 100 bytes each have to be
536 concatenated.  For the second string we search the already stored 100
537 bytes for the end of the string so that we can append the next string.
538 For all strings in total the comparisons necessary to find the end of
539 the intermediate results sums up to 5500!  If we combine the copying
540 with the search for the allocation we can write this function more
541 efficient:
542
543 @smallexample
544 char *
545 concat (const char *str, ...)
546 @{
547   va_list ap;
548   size_t allocated = 100;
549   char *result = (char *) malloc (allocated);
550   char *wp;
551
552   if (allocated != NULL)
553     @{
554       char *newp;
555
556       va_start (ap, atr);
557
558       wp = result;
559       for (s = str; s != NULL; s = va_arg (ap, const char *))
560         @{
561           size_t len = strlen (s);
562
563           /* @r{Resize the allocated memory if necessary.}  */
564           if (wp + len + 1 > result + allocated)
565             @{
566               allocated = (allocated + len) * 2;
567               newp = (char *) realloc (result, allocated);
568               if (newp == NULL)
569                 @{
570                   free (result);
571                   return NULL;
572                 @}
573               wp = newp + (wp - result);
574               result = newp;
575             @}
576
577           wp = mempcpy (wp, s, len);
578         @}
579
580       /* @r{Terminate the result string.}  */
581       *wp++ = '\0';
582
583       /* @r{Resize memory to the optimal size.}  */
584       newp = realloc (result, wp - result);
585       if (newp != NULL)
586         result = newp;
587
588       va_end (ap);
589     @}
590
591   return result;
592 @}
593 @end smallexample
594
595 With a bit more knowledge about the input strings one could fine-tune
596 the memory allocation.  The difference we are pointing to here is that
597 we don't use @code{strcat} anymore.  We always keep track of the length
598 of the current intermediate result so we can safe us the search for the
599 end of the string and use @code{mempcpy}.  Please note that we also
600 don't use @code{stpcpy} which might seem more natural since we handle
601 with strings.  But this is not necessary since we already know the
602 length of the string and therefore can use the faster memory copying
603 function.
604
605 Whenever a programmer feels the need to use @code{strcat} she or he
606 should think twice and look through the program whether the code cannot
607 be rewritten to take advantage of already calculated results.  Again: it
608 is almost always unnecessary to use @code{strcat}.
609
610 @comment string.h
611 @comment ISO
612 @deftypefun {char *} strncat (char *@var{to}, const char *@var{from}, size_t @var{size})
613 This function is like @code{strcat} except that not more than @var{size}
614 characters from @var{from} are appended to the end of @var{to}.  A
615 single null character is also always appended to @var{to}, so the total
616 allocated size of @var{to} must be at least @code{@var{size} + 1} bytes
617 longer than its initial length.
618
619 The @code{strncat} function could be implemented like this:
620
621 @smallexample
622 @group
623 char *
624 strncat (char *to, const char *from, size_t size)
625 @{
626   strncpy (to + strlen (to), from, size);
627   return to;
628 @}
629 @end group
630 @end smallexample
631
632 The behavior of @code{strncat} is undefined if the strings overlap.
633 @end deftypefun
634
635 Here is an example showing the use of @code{strncpy} and @code{strncat}.
636 Notice how, in the call to @code{strncat}, the @var{size} parameter
637 is computed to avoid overflowing the character array @code{buffer}.
638
639 @smallexample
640 @include strncat.c.texi
641 @end smallexample
642
643 @noindent
644 The output produced by this program looks like:
645
646 @smallexample
647 hello
648 hello, wo
649 @end smallexample
650
651 @comment string.h
652 @comment BSD
653 @deftypefun void bcopy (const void *@var{from}, void *@var{to}, size_t @var{size})
654 This is a partially obsolete alternative for @code{memmove}, derived from
655 BSD.  Note that it is not quite equivalent to @code{memmove}, because the
656 arguments are not in the same order and there is no return value.
657 @end deftypefun
658
659 @comment string.h
660 @comment BSD
661 @deftypefun void bzero (void *@var{block}, size_t @var{size})
662 This is a partially obsolete alternative for @code{memset}, derived from
663 BSD.  Note that it is not as general as @code{memset}, because the only
664 value it can store is zero.
665 @end deftypefun
666
667 @node String/Array Comparison
668 @section String/Array Comparison
669 @cindex comparing strings and arrays
670 @cindex string comparison functions
671 @cindex array comparison functions
672 @cindex predicates on strings
673 @cindex predicates on arrays
674
675 You can use the functions in this section to perform comparisons on the
676 contents of strings and arrays.  As well as checking for equality, these
677 functions can also be used as the ordering functions for sorting
678 operations.  @xref{Searching and Sorting}, for an example of this.
679
680 Unlike most comparison operations in C, the string comparison functions
681 return a nonzero value if the strings are @emph{not} equivalent rather
682 than if they are.  The sign of the value indicates the relative ordering
683 of the first characters in the strings that are not equivalent:  a
684 negative value indicates that the first string is ``less'' than the
685 second, while a positive value indicates that the first string is
686 ``greater''.
687
688 The most common use of these functions is to check only for equality.
689 This is canonically done with an expression like @w{@samp{! strcmp (s1, s2)}}.
690
691 All of these functions are declared in the header file @file{string.h}.
692 @pindex string.h
693
694 @comment string.h
695 @comment ISO
696 @deftypefun int memcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
697 The function @code{memcmp} compares the @var{size} bytes of memory
698 beginning at @var{a1} against the @var{size} bytes of memory beginning
699 at @var{a2}.  The value returned has the same sign as the difference
700 between the first differing pair of bytes (interpreted as @code{unsigned
701 char} objects, then promoted to @code{int}).
702
703 If the contents of the two blocks are equal, @code{memcmp} returns
704 @code{0}.
705 @end deftypefun
706
707 On arbitrary arrays, the @code{memcmp} function is mostly useful for
708 testing equality.  It usually isn't meaningful to do byte-wise ordering
709 comparisons on arrays of things other than bytes.  For example, a
710 byte-wise comparison on the bytes that make up floating-point numbers
711 isn't likely to tell you anything about the relationship between the
712 values of the floating-point numbers.
713
714 You should also be careful about using @code{memcmp} to compare objects
715 that can contain ``holes'', such as the padding inserted into structure
716 objects to enforce alignment requirements, extra space at the end of
717 unions, and extra characters at the ends of strings whose length is less
718 than their allocated size.  The contents of these ``holes'' are
719 indeterminate and may cause strange behavior when performing byte-wise
720 comparisons.  For more predictable results, perform an explicit
721 component-wise comparison.
722
723 For example, given a structure type definition like:
724
725 @smallexample
726 struct foo
727   @{
728     unsigned char tag;
729     union
730       @{
731         double f;
732         long i;
733         char *p;
734       @} value;
735   @};
736 @end smallexample
737
738 @noindent
739 you are better off writing a specialized comparison function to compare
740 @code{struct foo} objects instead of comparing them with @code{memcmp}.
741
742 @comment string.h
743 @comment ISO
744 @deftypefun int strcmp (const char *@var{s1}, const char *@var{s2})
745 The @code{strcmp} function compares the string @var{s1} against
746 @var{s2}, returning a value that has the same sign as the difference
747 between the first differing pair of characters (interpreted as
748 @code{unsigned char} objects, then promoted to @code{int}).
749
750 If the two strings are equal, @code{strcmp} returns @code{0}.
751
752 A consequence of the ordering used by @code{strcmp} is that if @var{s1}
753 is an initial substring of @var{s2}, then @var{s1} is considered to be
754 ``less than'' @var{s2}.
755 @end deftypefun
756
757 @comment string.h
758 @comment BSD
759 @deftypefun int strcasecmp (const char *@var{s1}, const char *@var{s2})
760 This function is like @code{strcmp}, except that differences in case are
761 ignored.  How uppercase and lowercase characters are related is
762 determined by the currently selected locale.  In the standard @code{"C"}
763 locale the characters @"A and @"a do not match but in a locale which
764 regards these characters as parts of the alphabet they do match.
765
766 @noindent
767 @code{strcasecmp} is derived from BSD.
768 @end deftypefun
769
770 @comment string.h
771 @comment BSD
772 @deftypefun int strncasecmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
773 This function is like @code{strncmp}, except that differences in case
774 are ignored.  Like @code{strcasecmp}, it is locale dependent how
775 uppercase and lowercase characters are related.
776
777 @noindent
778 @code{strncasecmp} is a GNU extension.
779 @end deftypefun
780
781 @comment string.h
782 @comment ISO
783 @deftypefun int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{size})
784 This function is the similar to @code{strcmp}, except that no more than
785 @var{size} characters are compared.  In other words, if the two strings are
786 the same in their first @var{size} characters, the return value is zero.
787 @end deftypefun
788
789 Here are some examples showing the use of @code{strcmp} and @code{strncmp}.
790 These examples assume the use of the ASCII character set.  (If some
791 other character set---say, EBCDIC---is used instead, then the glyphs
792 are associated with different numeric codes, and the return values
793 and ordering may differ.)
794
795 @smallexample
796 strcmp ("hello", "hello")
797     @result{} 0    /* @r{These two strings are the same.} */
798 strcmp ("hello", "Hello")
799     @result{} 32   /* @r{Comparisons are case-sensitive.} */
800 strcmp ("hello", "world")
801     @result{} -15  /* @r{The character @code{'h'} comes before @code{'w'}.} */
802 strcmp ("hello", "hello, world")
803     @result{} -44  /* @r{Comparing a null character against a comma.} */
804 strncmp ("hello", "hello, world", 5)
805     @result{} 0    /* @r{The initial 5 characters are the same.} */
806 strncmp ("hello, world", "hello, stupid world!!!", 5)
807     @result{} 0    /* @r{The initial 5 characters are the same.} */
808 @end smallexample
809
810 @comment string.h
811 @comment GNU
812 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
813 The @code{strverscmp} function compares the string @var{s1} against
814 @var{s2}, considering them as holding indices/version numbers.  Return
815 value follows the same conventions as found in the @code{strverscmp}
816 function.  In fact, if @var{s1} and @var{s2} contain no digits,
817 @code{strverscmp} behaves like @code{strcmp}.
818
819 Basically, we compare strings normally (character by character), until
820 we find a digit in each string - then we enter a special comparison
821 mode, where each sequence of digits is taken as a whole.  If we reach the
822 end of these two parts without noticing a difference, we return to the
823 standard comparison mode.  There are two types of numeric parts:
824 "integral" and "fractional" (those  begin with a '0'). The types
825 of the numeric parts affect the way we sort them:
826
827 @itemize @bullet
828 @item
829 integral/integral: we compare values as you would expect.
830
831 @item
832 fractional/integral: the fractional part is less than the integral one.
833 Again, no surprise.
834
835 @item
836 fractional/fractional: the things become a bit more complex.
837 If the common prefix contains only leading zeroes, the longest part is less
838 than the other one; else the comparison behaves normally.
839 @end itemize
840
841 @smallexample
842 strverscmp ("no digit", "no digit")
843     @result{} 0    /* @r{same behaviour as strcmp.} */
844 strverscmp ("item#99", "item#100")
845     @result{} <0   /* @r{same prefix, but 99 < 100.} */
846 strverscmp ("alpha1", "alpha001")
847     @result{} >0   /* @r{fractional part inferior to integral one.} */
848 strverscmp ("part1_f012", "part1_f01")
849     @result{} >0   /* @r{two fractional parts.} */
850 strverscmp ("foo.009", "foo.0")
851     @result{} <0   /* @r{idem, but with leading zeroes only.} */
852 @end smallexample
853
854 This function is especially useful when dealing with filename sorting,
855 because filenames frequently hold indices/version numbers.
856
857 @code{strverscmp} is a GNU extension.
858 @end deftypefun
859
860 @comment string.h
861 @comment BSD
862 @deftypefun int bcmp (const void *@var{a1}, const void *@var{a2}, size_t @var{size})
863 This is an obsolete alias for @code{memcmp}, derived from BSD.
864 @end deftypefun
865
866 @node Collation Functions
867 @section Collation Functions
868
869 @cindex collating strings
870 @cindex string collation functions
871
872 In some locales, the conventions for lexicographic ordering differ from
873 the strict numeric ordering of character codes.  For example, in Spanish
874 most glyphs with diacritical marks such as accents are not considered
875 distinct letters for the purposes of collation.  On the other hand, the
876 two-character sequence @samp{ll} is treated as a single letter that is
877 collated immediately after @samp{l}.
878
879 You can use the functions @code{strcoll} and @code{strxfrm} (declared in
880 the header file @file{string.h}) to compare strings using a collation
881 ordering appropriate for the current locale.  The locale used by these
882 functions in particular can be specified by setting the locale for the
883 @code{LC_COLLATE} category; see @ref{Locales}.
884 @pindex string.h
885
886 In the standard C locale, the collation sequence for @code{strcoll} is
887 the same as that for @code{strcmp}.
888
889 Effectively, the way these functions work is by applying a mapping to
890 transform the characters in a string to a byte sequence that represents
891 the string's position in the collating sequence of the current locale.
892 Comparing two such byte sequences in a simple fashion is equivalent to
893 comparing the strings with the locale's collating sequence.
894
895 The function @code{strcoll} performs this translation implicitly, in
896 order to do one comparison.  By contrast, @code{strxfrm} performs the
897 mapping explicitly.  If you are making multiple comparisons using the
898 same string or set of strings, it is likely to be more efficient to use
899 @code{strxfrm} to transform all the strings just once, and subsequently
900 compare the transformed strings with @code{strcmp}.
901
902 @comment string.h
903 @comment ISO
904 @deftypefun int strcoll (const char *@var{s1}, const char *@var{s2})
905 The @code{strcoll} function is similar to @code{strcmp} but uses the
906 collating sequence of the current locale for collation (the
907 @code{LC_COLLATE} locale).
908 @end deftypefun
909
910 Here is an example of sorting an array of strings, using @code{strcoll}
911 to compare them.  The actual sort algorithm is not written here; it
912 comes from @code{qsort} (@pxref{Array Sort Function}).  The job of the
913 code shown here is to say how to compare the strings while sorting them.
914 (Later on in this section, we will show a way to do this more
915 efficiently using @code{strxfrm}.)
916
917 @smallexample
918 /* @r{This is the comparison function used with @code{qsort}.} */
919
920 int
921 compare_elements (char **p1, char **p2)
922 @{
923   return strcoll (*p1, *p2);
924 @}
925
926 /* @r{This is the entry point---the function to sort}
927    @r{strings using the locale's collating sequence.} */
928
929 void
930 sort_strings (char **array, int nstrings)
931 @{
932   /* @r{Sort @code{temp_array} by comparing the strings.} */
933   qsort (array, nstrings,
934          sizeof (char *), compare_elements);
935 @}
936 @end smallexample
937
938 @cindex converting string to collation order
939 @comment string.h
940 @comment ISO
941 @deftypefun size_t strxfrm (char *@var{to}, const char *@var{from}, size_t @var{size})
942 The function @code{strxfrm} transforms @var{string} using the collation
943 transformation determined by the locale currently selected for
944 collation, and stores the transformed string in the array @var{to}.  Up
945 to @var{size} characters (including a terminating null character) are
946 stored.
947
948 The behavior is undefined if the strings @var{to} and @var{from}
949 overlap; see @ref{Copying and Concatenation}.
950
951 The return value is the length of the entire transformed string.  This
952 value is not affected by the value of @var{size}, but if it is greater
953 or equal than @var{size}, it means that the transformed string did not
954 entirely fit in the array @var{to}.  In this case, only as much of the
955 string as actually fits was stored.  To get the whole transformed
956 string, call @code{strxfrm} again with a bigger output array.
957
958 The transformed string may be longer than the original string, and it
959 may also be shorter.
960
961 If @var{size} is zero, no characters are stored in @var{to}.  In this
962 case, @code{strxfrm} simply returns the number of characters that would
963 be the length of the transformed string.  This is useful for determining
964 what size string to allocate.  It does not matter what @var{to} is if
965 @var{size} is zero; @var{to} may even be a null pointer.
966 @end deftypefun
967
968 Here is an example of how you can use @code{strxfrm} when
969 you plan to do many comparisons.  It does the same thing as the previous
970 example, but much faster, because it has to transform each string only
971 once, no matter how many times it is compared with other strings.  Even
972 the time needed to allocate and free storage is much less than the time
973 we save, when there are many strings.
974
975 @smallexample
976 struct sorter @{ char *input; char *transformed; @};
977
978 /* @r{This is the comparison function used with @code{qsort}}
979    @r{to sort an array of @code{struct sorter}.} */
980
981 int
982 compare_elements (struct sorter *p1, struct sorter *p2)
983 @{
984   return strcmp (p1->transformed, p2->transformed);
985 @}
986
987 /* @r{This is the entry point---the function to sort}
988    @r{strings using the locale's collating sequence.} */
989
990 void
991 sort_strings_fast (char **array, int nstrings)
992 @{
993   struct sorter temp_array[nstrings];
994   int i;
995
996   /* @r{Set up @code{temp_array}.  Each element contains}
997      @r{one input string and its transformed string.} */
998   for (i = 0; i < nstrings; i++)
999     @{
1000       size_t length = strlen (array[i]) * 2;
1001       char *transformed;
1002       size_t transformed_length;
1003
1004       temp_array[i].input = array[i];
1005
1006       /* @r{First try a buffer perhaps big enough.}  */
1007       transformed = (char *) xmalloc (length);
1008
1009       /* @r{Transform @code{array[i]}.}  */
1010       transformed_length = strxfrm (transformed, array[i], length);
1011
1012       /* @r{If the buffer was not large enough, resize it}
1013          @r{and try again.}  */
1014       if (transformed_length >= length)
1015         @{
1016           /* @r{Allocate the needed space. +1 for terminating}
1017              @r{@code{NUL} character.}  */
1018           transformed = (char *) xrealloc (transformed,
1019                                            transformed_length + 1);
1020
1021           /* @r{The return value is not interesting because we know}
1022              @r{how long the transformed string is.}  */
1023           (void) strxfrm (transformed, array[i],
1024                           transformed_length + 1);
1025         @}
1026
1027       temp_array[i].transformed = transformed;
1028     @}
1029
1030   /* @r{Sort @code{temp_array} by comparing transformed strings.} */
1031   qsort (temp_array, sizeof (struct sorter),
1032          nstrings, compare_elements);
1033
1034   /* @r{Put the elements back in the permanent array}
1035      @r{in their sorted order.} */
1036   for (i = 0; i < nstrings; i++)
1037     array[i] = temp_array[i].input;
1038
1039   /* @r{Free the strings we allocated.} */
1040   for (i = 0; i < nstrings; i++)
1041     free (temp_array[i].transformed);
1042 @}
1043 @end smallexample
1044
1045 @strong{Compatibility Note:}  The string collation functions are a new
1046 feature of @w{ISO C90}.  Older C dialects have no equivalent feature.
1047
1048 @node Search Functions
1049 @section Search Functions
1050
1051 This section describes library functions which perform various kinds
1052 of searching operations on strings and arrays.  These functions are
1053 declared in the header file @file{string.h}.
1054 @pindex string.h
1055 @cindex search functions (for strings)
1056 @cindex string search functions
1057
1058 @comment string.h
1059 @comment ISO
1060 @deftypefun {void *} memchr (const void *@var{block}, int @var{c}, size_t @var{size})
1061 This function finds the first occurrence of the byte @var{c} (converted
1062 to an @code{unsigned char}) in the initial @var{size} bytes of the
1063 object beginning at @var{block}.  The return value is a pointer to the
1064 located byte, or a null pointer if no match was found.
1065 @end deftypefun
1066
1067 @comment string.h
1068 @comment GNU
1069 @deftypefun {void *} memrchr (const void *@var{block}, int @var{c}, size_t @var{size})
1070 The function @code{memrchr} is like @code{memchr}, except that it searches
1071 backwards from the end of the block defined by @var{block} and @var{size}
1072 (instead of forwards from the front).
1073 @end deftypefun
1074
1075 @comment string.h
1076 @comment ISO
1077 @deftypefun {char *} strchr (const char *@var{string}, int @var{c})
1078 The @code{strchr} function finds the first occurrence of the character
1079 @var{c} (converted to a @code{char}) in the null-terminated string
1080 beginning at @var{string}.  The return value is a pointer to the located
1081 character, or a null pointer if no match was found.
1082
1083 For example,
1084 @smallexample
1085 strchr ("hello, world", 'l')
1086     @result{} "llo, world"
1087 strchr ("hello, world", '?')
1088     @result{} NULL
1089 @end smallexample
1090
1091 The terminating null character is considered to be part of the string,
1092 so you can use this function get a pointer to the end of a string by
1093 specifying a null character as the value of the @var{c} argument.
1094 @end deftypefun
1095
1096 @comment string.h
1097 @comment ???
1098 @deftypefun {char *} strchrnul (const char *@var{string}, int @var{c})
1099 @code{strchrnul} is the same as @code{strchr} except that if it does
1100 not find the character, it returns a pointer to string's terminating 
1101 null character rather than a null pointer.
1102 @end deftypefun
1103
1104 One useful, but unusual, use of the @code{strchr} 
1105 function is when one wants to have a pointer pointing to the NUL byte
1106 terminating a string.  This is often written in this way:
1107
1108 @smallexample
1109   s += strlen (s);
1110 @end smallexample
1111
1112 @noindent
1113 This is almost optimal but the addition operation duplicated a bit of
1114 the work already done in the @code{strlen} function.  A better solution
1115 is this:
1116
1117 @smallexample
1118   s = strchr (s, '\0');
1119 @end smallexample
1120
1121 There is no restriction on the second parameter of @code{strchr} so it
1122 could very well also be the NUL character.  Those readers thinking very
1123 hard about this might now point out that the @code{strchr} function is
1124 more expensive than the @code{strlen} function since we have two abort
1125 criteria.  This is right.  But in the GNU C library the implementation of
1126 @code{strchr} is optimized in a special way so that @code{strchr}
1127 actually is faster.
1128
1129 @comment string.h
1130 @comment ISO
1131 @deftypefun {char *} strrchr (const char *@var{string}, int @var{c})
1132 The function @code{strrchr} is like @code{strchr}, except that it searches
1133 backwards from the end of the string @var{string} (instead of forwards
1134 from the front).
1135
1136 For example,
1137 @smallexample
1138 strrchr ("hello, world", 'l')
1139     @result{} "ld"
1140 @end smallexample
1141 @end deftypefun
1142
1143 @comment string.h
1144 @comment ISO
1145 @deftypefun {char *} strstr (const char *@var{haystack}, const char *@var{needle})
1146 This is like @code{strchr}, except that it searches @var{haystack} for a
1147 substring @var{needle} rather than just a single character.  It
1148 returns a pointer into the string @var{haystack} that is the first
1149 character of the substring, or a null pointer if no match was found.  If
1150 @var{needle} is an empty string, the function returns @var{haystack}.
1151
1152 For example,
1153 @smallexample
1154 strstr ("hello, world", "l")
1155     @result{} "llo, world"
1156 strstr ("hello, world", "wo")
1157     @result{} "world"
1158 @end smallexample
1159 @end deftypefun
1160
1161
1162 @comment string.h
1163 @comment ???
1164 @deftypefun {char *} strcasestr (const char *@var{haystack}, const char *@var{needle})
1165 This is like @code{strstr}, except that it ignores case in searching for
1166 the substring.   Like @code{strcasecmp}, it is locale dependent how
1167 uppercase and lowercase characters are related.
1168
1169
1170 For example,
1171 @smallexample
1172 strstr ("hello, world", "L")
1173     @result{} "llo, world"
1174 strstr ("hello, World", "wo")
1175     @result{} "World"
1176 @end smallexample
1177 @end deftypefun
1178
1179
1180 @comment string.h
1181 @comment GNU
1182 @deftypefun {void *} memmem (const void *@var{haystack}, size_t @var{haystack-len},@*const void *@var{needle}, size_t @var{needle-len})
1183 This is like @code{strstr}, but @var{needle} and @var{haystack} are byte
1184 arrays rather than null-terminated strings.  @var{needle-len} is the
1185 length of @var{needle} and @var{haystack-len} is the length of
1186 @var{haystack}.@refill
1187
1188 This function is a GNU extension.
1189 @end deftypefun
1190
1191 @comment string.h
1192 @comment ISO
1193 @deftypefun size_t strspn (const char *@var{string}, const char *@var{skipset})
1194 The @code{strspn} (``string span'') function returns the length of the
1195 initial substring of @var{string} that consists entirely of characters that
1196 are members of the set specified by the string @var{skipset}.  The order
1197 of the characters in @var{skipset} is not important.
1198
1199 For example,
1200 @smallexample
1201 strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
1202     @result{} 5
1203 @end smallexample
1204 @end deftypefun
1205
1206 @comment string.h
1207 @comment ISO
1208 @deftypefun size_t strcspn (const char *@var{string}, const char *@var{stopset})
1209 The @code{strcspn} (``string complement span'') function returns the length
1210 of the initial substring of @var{string} that consists entirely of characters
1211 that are @emph{not} members of the set specified by the string @var{stopset}.
1212 (In other words, it returns the offset of the first character in @var{string}
1213 that is a member of the set @var{stopset}.)
1214
1215 For example,
1216 @smallexample
1217 strcspn ("hello, world", " \t\n,.;!?")
1218     @result{} 5
1219 @end smallexample
1220 @end deftypefun
1221
1222 @comment string.h
1223 @comment ISO
1224 @deftypefun {char *} strpbrk (const char *@var{string}, const char *@var{stopset})
1225 The @code{strpbrk} (``string pointer break'') function is related to
1226 @code{strcspn}, except that it returns a pointer to the first character
1227 in @var{string} that is a member of the set @var{stopset} instead of the
1228 length of the initial substring.  It returns a null pointer if no such
1229 character from @var{stopset} is found.
1230
1231 @c @group  Invalid outside the example.
1232 For example,
1233
1234 @smallexample
1235 strpbrk ("hello, world", " \t\n,.;!?")
1236     @result{} ", world"
1237 @end smallexample
1238 @c @end group
1239 @end deftypefun
1240
1241
1242 @subsection Compatibility String Search Functions
1243
1244 @comment string.h
1245 @comment BSD
1246 @deftypefun {char *} index (const char *@var{string}, int @var{c})
1247 @code{index} is another name for @code{strchr}; they are exactly the same.
1248 New code should always use @code{strchr} since this name is defined in
1249 @w{ISO C} while @code{index} is a BSD invention which never was available
1250 on @w{System V} derived systems.
1251 @end deftypefun
1252
1253 @comment string.h
1254 @comment BSD
1255 @deftypefun {char *} rindex (const char *@var{string}, int @var{c})
1256 @code{rindex} is another name for @code{strrchr}; they are exactly the same.
1257 New code should always use @code{strrchr} since this name is defined in
1258 @w{ISO C} while @code{rindex} is a BSD invention which never was available
1259 on @w{System V} derived systems.
1260 @end deftypefun
1261
1262 @node Finding Tokens in a String
1263 @section Finding Tokens in a String
1264
1265 @cindex tokenizing strings
1266 @cindex breaking a string into tokens
1267 @cindex parsing tokens from a string
1268 It's fairly common for programs to have a need to do some simple kinds
1269 of lexical analysis and parsing, such as splitting a command string up
1270 into tokens.  You can do this with the @code{strtok} function, declared
1271 in the header file @file{string.h}.
1272 @pindex string.h
1273
1274 @comment string.h
1275 @comment ISO
1276 @deftypefun {char *} strtok (char *@var{newstring}, const char *@var{delimiters})
1277 A string can be split into tokens by making a series of calls to the
1278 function @code{strtok}.
1279
1280 The string to be split up is passed as the @var{newstring} argument on
1281 the first call only.  The @code{strtok} function uses this to set up
1282 some internal state information.  Subsequent calls to get additional
1283 tokens from the same string are indicated by passing a null pointer as
1284 the @var{newstring} argument.  Calling @code{strtok} with another
1285 non-null @var{newstring} argument reinitializes the state information.
1286 It is guaranteed that no other library function ever calls @code{strtok}
1287 behind your back (which would mess up this internal state information).
1288
1289 The @var{delimiters} argument is a string that specifies a set of delimiters
1290 that may surround the token being extracted.  All the initial characters
1291 that are members of this set are discarded.  The first character that is
1292 @emph{not} a member of this set of delimiters marks the beginning of the
1293 next token.  The end of the token is found by looking for the next
1294 character that is a member of the delimiter set.  This character in the
1295 original string @var{newstring} is overwritten by a null character, and the
1296 pointer to the beginning of the token in @var{newstring} is returned.
1297
1298 On the next call to @code{strtok}, the searching begins at the next
1299 character beyond the one that marked the end of the previous token.
1300 Note that the set of delimiters @var{delimiters} do not have to be the
1301 same on every call in a series of calls to @code{strtok}.
1302
1303 If the end of the string @var{newstring} is reached, or if the remainder of
1304 string consists only of delimiter characters, @code{strtok} returns
1305 a null pointer.
1306 @end deftypefun
1307
1308 @strong{Warning:} Since @code{strtok} alters the string it is parsing,
1309 you should always copy the string to a temporary buffer before parsing
1310 it with @code{strtok}.  If you allow @code{strtok} to modify a string
1311 that came from another part of your program, you are asking for trouble;
1312 that string might be used for other purposes after @code{strtok} has
1313 modified it, and it would not have the expected value.
1314
1315 The string that you are operating on might even be a constant.  Then
1316 when @code{strtok} tries to modify it, your program will get a fatal
1317 signal for writing in read-only memory.  @xref{Program Error Signals}.
1318 Even if the operation of @code{strtok} would not require a modification
1319 of the string (e.g., if there is exactly one token) the string can (and
1320 in the GNU libc case will) be modified.
1321
1322 This is a special case of a general principle: if a part of a program
1323 does not have as its purpose the modification of a certain data
1324 structure, then it is error-prone to modify the data structure
1325 temporarily.
1326
1327 The function @code{strtok} is not reentrant.  @xref{Nonreentrancy}, for
1328 a discussion of where and why reentrancy is important.
1329
1330 Here is a simple example showing the use of @code{strtok}.
1331
1332 @comment Yes, this example has been tested.
1333 @smallexample
1334 #include <string.h>
1335 #include <stddef.h>
1336
1337 @dots{}
1338
1339 const char string[] = "words separated by spaces -- and, punctuation!";
1340 const char delimiters[] = " .,;:!-";
1341 char *token, *cp;
1342
1343 @dots{}
1344
1345 cp = strdupa (string);                /* Make writable copy.  */
1346 token = strtok (cp, delimiters);      /* token => "words" */
1347 token = strtok (NULL, delimiters);    /* token => "separated" */
1348 token = strtok (NULL, delimiters);    /* token => "by" */
1349 token = strtok (NULL, delimiters);    /* token => "spaces" */
1350 token = strtok (NULL, delimiters);    /* token => "and" */
1351 token = strtok (NULL, delimiters);    /* token => "punctuation" */
1352 token = strtok (NULL, delimiters);    /* token => NULL */
1353 @end smallexample
1354
1355 The GNU C library contains two more functions for tokenizing a string
1356 which overcome the limitation of non-reentrancy.
1357
1358 @comment string.h
1359 @comment POSIX
1360 @deftypefun {char *} strtok_r (char *@var{newstring}, const char *@var{delimiters}, char **@var{save_ptr})
1361 Just like @code{strtok}, this function splits the string into several
1362 tokens which can be accessed by successive calls to @code{strtok_r}.
1363 The difference is that the information about the next token is stored in
1364 the space pointed to by the third argument, @var{save_ptr}, which is a
1365 pointer to a string pointer.  Calling @code{strtok_r} with a null
1366 pointer for @var{newstring} and leaving @var{save_ptr} between the calls
1367 unchanged does the job without hindering reentrancy.
1368
1369 This function is defined in POSIX.1 and can be found on many systems
1370 which support multi-threading.
1371 @end deftypefun
1372
1373 @comment string.h
1374 @comment BSD
1375 @deftypefun {char *} strsep (char **@var{string_ptr}, const char *@var{delimiter})
1376 This function has a similar functionality as @code{strtok_r} with the
1377 @var{newstring} argument replaced by the @var{save_ptr} argument.  The
1378 initialization of the moving pointer has to be done by the user.
1379 Successive calls to @code{strsep} move the pointer along the tokens
1380 separated by @var{delimiter}, returning the address of the next token
1381 and updating @var{string_ptr} to point to the beginning of the next
1382 token.
1383
1384 One difference between @code{strsep} and @code{strtok_r} is that if the
1385 input string contains more than one character from @var{delimiter} in a
1386 row @code{strsep} returns an empty string for each pair of characters
1387 from @var{delimiter}.  This means that a program normally should test
1388 for @code{strsep} returning an empty string before processing it.
1389
1390 This function was introduced in 4.3BSD and therefore is widely available.
1391 @end deftypefun
1392
1393 Here is how the above example looks like when @code{strsep} is used.
1394
1395 @comment Yes, this example has been tested.
1396 @smallexample
1397 #include <string.h>
1398 #include <stddef.h>
1399
1400 @dots{}
1401
1402 const char string[] = "words separated by spaces -- and, punctuation!";
1403 const char delimiters[] = " .,;:!-";
1404 char *running;
1405 char *token;
1406
1407 @dots{}
1408
1409 running = strdupa (string);
1410 token = strsep (&running, delimiters);    /* token => "words" */
1411 token = strsep (&running, delimiters);    /* token => "separated" */
1412 token = strsep (&running, delimiters);    /* token => "by" */
1413 token = strsep (&running, delimiters);    /* token => "spaces" */
1414 token = strsep (&running, delimiters);    /* token => "" */
1415 token = strsep (&running, delimiters);    /* token => "" */
1416 token = strsep (&running, delimiters);    /* token => "" */
1417 token = strsep (&running, delimiters);    /* token => "and" */
1418 token = strsep (&running, delimiters);    /* token => "" */
1419 token = strsep (&running, delimiters);    /* token => "punctuation" */
1420 token = strsep (&running, delimiters);    /* token => "" */
1421 token = strsep (&running, delimiters);    /* token => NULL */
1422 @end smallexample
1423
1424
1425 @node strfry
1426 @section strfry
1427
1428 The function below addresses the perennial programming quandary: ``How do
1429 I take good data in string form and painlessly turn it into garbage?''
1430 This is actually a fairly simple task for C programmers who do not use
1431 the GNU C library string functions, but for programs based on the GNU C
1432 library, the @code{strfry} function is the preferred method for
1433 destroying string data.
1434
1435 The prototype for this function is in @file{string.h}.
1436
1437 @comment string.h
1438 @comment GNU
1439 @deftypefun {char *} strfry (char *@var{string}) 
1440
1441 @code{strfry} creates a pseudorandom anagram of a string, replacing the
1442 input with the anagram in place.  For each position in the string,
1443 @code{strfry} swaps it with a position in the string selected at random
1444 (from a uniform distribution).  The two positions may be the same.
1445
1446 The return value of @code{strfry} is always @var{string}.
1447
1448 @strong{Portability Note:}  This function is unique to the GNU C library.
1449
1450 @end deftypefun
1451
1452
1453 @node Trivial Encryption
1454 @section Trivial Encryption
1455 @cindex encryption
1456
1457
1458 The @code{memfrob} function converts an array of data to something
1459 unrecognizable and back again.  It is not encryption in its usual sense
1460 since it is easy for someone to convert the encrypted data back to clear
1461 text.  The transformation is analogous to Usenet's ``Rot13'' encryption
1462 method for obscuring offensive jokes from sensitive eyes and such.
1463 Unlike Rot13, @code{memfrob} works on arbitrary binary data, not just
1464 text.
1465 @cindex Rot13
1466
1467 For true encryption, @xref{Cryptographic Functions}.
1468
1469 This function is declared in @file{string.h}.
1470 @pindex string.h
1471
1472 @comment string.h
1473 @comment GNU
1474 @deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length})
1475
1476 @code{memfrob} transforms (frobnicates) each byte of the data structure
1477 at @var{mem}, which is @var{length} bytes long, by bitwise exclusive
1478 oring it with binary 00101010.  It does the transformation in place and
1479 its return value is always @var{mem}.
1480
1481 Note that @code{memfrob} a second time on the same data structure
1482 returns it to its original state.
1483
1484 This is a good function for hiding information from someone who doesn't
1485 want to see it or doesn't want to see it very much.  To really prevent
1486 people from retrieving the information, use stronger encryption such as
1487 that described in @xref{Cryptographic Functions}.
1488
1489 @strong{Portability Note:}  This function is unique to the GNU C library.
1490
1491 @end deftypefun
1492
1493 @node Encode Binary Data
1494 @section Encode Binary Data
1495
1496 To store or transfer binary data in environments which only support text
1497 one has to encode the binary data by mapping the input bytes to
1498 characters in the range allowed for storing or transfering.  SVID
1499 systems (and nowadays XPG compliant systems) provide minimal support for
1500 this task.
1501
1502 @comment stdlib.h
1503 @comment XPG
1504 @deftypefun {char *} l64a (long int @var{n})
1505 This function encodes a 32-bit input value using characters from the
1506 basic character set.  It returns a pointer to a 6 character buffer which
1507 contains an encoded version of @var{n}.  To encode a series of bytes the
1508 user must copy the returned string to a destination buffer.  It returns
1509 the empty string if @var{n} is zero, which is somewhat bizarre but
1510 mandated by the standard.@*
1511 @strong{Warning:} Since a static buffer is used this function should not
1512 be used in multi-threaded programs.  There is no thread-safe alternative
1513 to this function in the C library.@*
1514 @strong{Compatibility Note:} The XPG standard states that the return
1515 value of @code{l64a} is undefined if @var{n} is negative.  In the GNU
1516 implementation, @code{l64a} treats its argument as unsigned, so it will
1517 return a sensible encoding for any nonzero @var{n}; however, portable
1518 programs should not rely on this.
1519
1520 To encode a large buffer @code{l64a} must be called in a loop, once for
1521 each 32-bit word of the buffer.  For example, one could do something
1522 like this:
1523
1524 @smallexample
1525 char *
1526 encode (const void *buf, size_t len)
1527 @{
1528   /* @r{We know in advance how long the buffer has to be.} */
1529   unsigned char *in = (unsigned char *) buf;
1530   char *out = malloc (6 + ((len + 3) / 4) * 6 + 1);
1531   char *cp = out;
1532
1533   /* @r{Encode the length.} */
1534   /* @r{Using `htonl' is necessary so that the data can be}
1535      @r{decoded even on machines with different byte order.} */
1536
1537   cp = mempcpy (cp, l64a (htonl (len)), 6);
1538
1539   while (len > 3)
1540     @{
1541       unsigned long int n = *in++;
1542       n = (n << 8) | *in++;
1543       n = (n << 8) | *in++;
1544       n = (n << 8) | *in++;
1545       len -= 4;
1546       if (n)
1547         cp = mempcpy (cp, l64a (htonl (n)), 6);
1548       else
1549             /* @r{`l64a' returns the empty string for n==0, so we }
1550                @r{must generate its encoding (}"......"@r{) by hand.} */
1551         cp = stpcpy (cp, "......");
1552     @}
1553   if (len > 0)
1554     @{
1555       unsigned long int n = *in++;
1556       if (--len > 0)
1557         @{
1558           n = (n << 8) | *in++;
1559           if (--len > 0)
1560             n = (n << 8) | *in;
1561         @}
1562       memcpy (cp, l64a (htonl (n)), 6);
1563       cp += 6;
1564     @}
1565   *cp = '\0';
1566   return out;
1567 @}
1568 @end smallexample
1569
1570 It is strange that the library does not provide the complete
1571 functionality needed but so be it.
1572
1573 @end deftypefun
1574
1575 To decode data produced with @code{l64a} the following function should be
1576 used.
1577
1578 @comment stdlib.h
1579 @comment XPG
1580 @deftypefun {long int} a64l (const char *@var{string})
1581 The parameter @var{string} should contain a string which was produced by
1582 a call to @code{l64a}.  The function processes at least 6 characters of
1583 this string, and decodes the characters it finds according to the table
1584 below.  It stops decoding when it finds a character not in the table,
1585 rather like @code{atoi}; if you have a buffer which has been broken into
1586 lines, you must be careful to skip over the end-of-line characters.
1587
1588 The decoded number is returned as a @code{long int} value.
1589 @end deftypefun
1590
1591 The @code{l64a} and @code{a64l} functions use a base 64 encoding, in
1592 which each character of an encoded string represents six bits of an
1593 input word.  These symbols are used for the base 64 digits:
1594
1595 @multitable {xxxxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx} {xxx}
1596 @item              @tab 0 @tab 1 @tab 2 @tab 3 @tab 4 @tab 5 @tab 6 @tab 7
1597 @item       0      @tab @code{.} @tab @code{/} @tab @code{0} @tab @code{1}
1598                    @tab @code{2} @tab @code{3} @tab @code{4} @tab @code{5}
1599 @item       8      @tab @code{6} @tab @code{7} @tab @code{8} @tab @code{9}
1600                    @tab @code{A} @tab @code{B} @tab @code{C} @tab @code{D}
1601 @item       16     @tab @code{E} @tab @code{F} @tab @code{G} @tab @code{H}
1602                    @tab @code{I} @tab @code{J} @tab @code{K} @tab @code{L}
1603 @item       24     @tab @code{M} @tab @code{N} @tab @code{O} @tab @code{P}
1604                    @tab @code{Q} @tab @code{R} @tab @code{S} @tab @code{T}
1605 @item       32     @tab @code{U} @tab @code{V} @tab @code{W} @tab @code{X}
1606                    @tab @code{Y} @tab @code{Z} @tab @code{a} @tab @code{b}
1607 @item       40     @tab @code{c} @tab @code{d} @tab @code{e} @tab @code{f}
1608                    @tab @code{g} @tab @code{h} @tab @code{i} @tab @code{j}
1609 @item       48     @tab @code{k} @tab @code{l} @tab @code{m} @tab @code{n}
1610                    @tab @code{o} @tab @code{p} @tab @code{q} @tab @code{r}
1611 @item       56     @tab @code{s} @tab @code{t} @tab @code{u} @tab @code{v}
1612                    @tab @code{w} @tab @code{x} @tab @code{y} @tab @code{z}
1613 @end multitable
1614
1615 This encoding scheme is not standard.  There are some other encoding
1616 methods which are much more widely used (UU encoding, MIME encoding).
1617 Generally, it is better to use one of these encodings.
1618
1619 @node Argz and Envz Vectors
1620 @section Argz and Envz Vectors
1621
1622 @cindex argz vectors (string vectors)
1623 @cindex string vectors, null-character separated
1624 @cindex argument vectors, null-character separated
1625 @dfn{argz vectors} are vectors of strings in a contiguous block of
1626 memory, each element separated from its neighbors by null-characters
1627 (@code{'\0'}).
1628
1629 @cindex envz vectors (environment vectors)
1630 @cindex environment vectors, null-character separated
1631 @dfn{Envz vectors} are an extension of argz vectors where each element is a
1632 name-value pair, separated by a @code{'='} character (as in a Unix
1633 environment).
1634
1635 @menu
1636 * Argz Functions::              Operations on argz vectors.
1637 * Envz Functions::              Additional operations on environment vectors.
1638 @end menu
1639
1640 @node Argz Functions, Envz Functions, , Argz and Envz Vectors
1641 @subsection Argz Functions
1642
1643 Each argz vector is represented by a pointer to the first element, of
1644 type @code{char *}, and a size, of type @code{size_t}, both of which can
1645 be initialized to @code{0} to represent an empty argz vector.  All argz
1646 functions accept either a pointer and a size argument, or pointers to
1647 them, if they will be modified.
1648
1649 The argz functions use @code{malloc}/@code{realloc} to allocate/grow
1650 argz vectors, and so any argz vector creating using these functions may
1651 be freed by using @code{free}; conversely, any argz function that may
1652 grow a string expects that string to have been allocated using
1653 @code{malloc} (those argz functions that only examine their arguments or
1654 modify them in place will work on any sort of memory).
1655 @xref{Unconstrained Allocation}.
1656
1657 All argz functions that do memory allocation have a return type of
1658 @code{error_t}, and return @code{0} for success, and @code{ENOMEM} if an
1659 allocation error occurs.
1660
1661 @pindex argz.h
1662 These functions are declared in the standard include file @file{argz.h}.
1663
1664 @comment argz.h
1665 @comment GNU
1666 @deftypefun {error_t} argz_create (char *const @var{argv}[], char **@var{argz}, size_t *@var{argz_len})
1667 The @code{argz_create} function converts the Unix-style argument vector
1668 @var{argv} (a vector of pointers to normal C strings, terminated by
1669 @code{(char *)0}; @pxref{Program Arguments}) into an argz vector with
1670 the same elements, which is returned in @var{argz} and @var{argz_len}.
1671 @end deftypefun
1672
1673 @comment argz.h
1674 @comment GNU
1675 @deftypefun {error_t} argz_create_sep (const char *@var{string}, int @var{sep}, char **@var{argz}, size_t *@var{argz_len})
1676 The @code{argz_create_sep} function converts the null-terminated string
1677 @var{string} into an argz vector (returned in @var{argz} and
1678 @var{argz_len}) by splitting it into elements at every occurrence of the
1679 character @var{sep}.
1680 @end deftypefun
1681
1682 @comment argz.h
1683 @comment GNU
1684 @deftypefun {size_t} argz_count (const char *@var{argz}, size_t @var{arg_len})
1685 Returns the number of elements in the argz vector @var{argz} and
1686 @var{argz_len}.
1687 @end deftypefun
1688
1689 @comment argz.h
1690 @comment GNU
1691 @deftypefun {void} argz_extract (char *@var{argz}, size_t @var{argz_len}, char **@var{argv})
1692 The @code{argz_extract} function converts the argz vector @var{argz} and
1693 @var{argz_len} into a Unix-style argument vector stored in @var{argv},
1694 by putting pointers to every element in @var{argz} into successive
1695 positions in @var{argv}, followed by a terminator of @code{0}.
1696 @var{Argv} must be pre-allocated with enough space to hold all the
1697 elements in @var{argz} plus the terminating @code{(char *)0}
1698 (@code{(argz_count (@var{argz}, @var{argz_len}) + 1) * sizeof (char *)}
1699 bytes should be enough).  Note that the string pointers stored into
1700 @var{argv} point into @var{argz}---they are not copies---and so
1701 @var{argz} must be copied if it will be changed while @var{argv} is
1702 still active.  This function is useful for passing the elements in
1703 @var{argz} to an exec function (@pxref{Executing a File}).
1704 @end deftypefun
1705
1706 @comment argz.h
1707 @comment GNU
1708 @deftypefun {void} argz_stringify (char *@var{argz}, size_t @var{len}, int @var{sep})
1709 The @code{argz_stringify} converts @var{argz} into a normal string with
1710 the elements separated by the character @var{sep}, by replacing each
1711 @code{'\0'} inside @var{argz} (except the last one, which terminates the
1712 string) with @var{sep}.  This is handy for printing @var{argz} in a
1713 readable manner.
1714 @end deftypefun
1715
1716 @comment argz.h
1717 @comment GNU
1718 @deftypefun {error_t} argz_add (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str})
1719 The @code{argz_add} function adds the string @var{str} to the end of the
1720 argz vector @code{*@var{argz}}, and updates @code{*@var{argz}} and
1721 @code{*@var{argz_len}} accordingly.
1722 @end deftypefun
1723
1724 @comment argz.h
1725 @comment GNU
1726 @deftypefun {error_t} argz_add_sep (char **@var{argz}, size_t *@var{argz_len}, const char *@var{str}, int @var{delim})
1727 The @code{argz_add_sep} function is similar to @code{argz_add}, but
1728 @var{str} is split into separate elements in the result at occurrences of
1729 the character @var{delim}.  This is useful, for instance, for
1730 adding the components of a Unix search path to an argz vector, by using
1731 a value of @code{':'} for @var{delim}.
1732 @end deftypefun
1733
1734 @comment argz.h
1735 @comment GNU
1736 @deftypefun {error_t} argz_append (char **@var{argz}, size_t *@var{argz_len}, const char *@var{buf}, size_t @var{buf_len})
1737 The @code{argz_append} function appends @var{buf_len} bytes starting at
1738 @var{buf} to the argz vector @code{*@var{argz}}, reallocating
1739 @code{*@var{argz}} to accommodate it, and adding @var{buf_len} to
1740 @code{*@var{argz_len}}.
1741 @end deftypefun
1742
1743 @comment argz.h
1744 @comment GNU
1745 @deftypefun {error_t} argz_delete (char **@var{argz}, size_t *@var{argz_len}, char *@var{entry})
1746 If @var{entry} points to the beginning of one of the elements in the
1747 argz vector @code{*@var{argz}}, the @code{argz_delete} function will
1748 remove this entry and reallocate @code{*@var{argz}}, modifying
1749 @code{*@var{argz}} and @code{*@var{argz_len}} accordingly.  Note that as
1750 destructive argz functions usually reallocate their argz argument,
1751 pointers into argz vectors such as @var{entry} will then become invalid.
1752 @end deftypefun
1753
1754 @comment argz.h
1755 @comment GNU
1756 @deftypefun {error_t} argz_insert (char **@var{argz}, size_t *@var{argz_len}, char *@var{before}, const char *@var{entry})
1757 The @code{argz_insert} function inserts the string @var{entry} into the
1758 argz vector @code{*@var{argz}} at a point just before the existing
1759 element pointed to by @var{before}, reallocating @code{*@var{argz}} and
1760 updating @code{*@var{argz}} and @code{*@var{argz_len}}.  If @var{before}
1761 is @code{0}, @var{entry} is added to the end instead (as if by
1762 @code{argz_add}).  Since the first element is in fact the same as
1763 @code{*@var{argz}}, passing in @code{*@var{argz}} as the value of
1764 @var{before} will result in @var{entry} being inserted at the beginning.
1765 @end deftypefun
1766
1767 @comment argz.h
1768 @comment GNU
1769 @deftypefun {char *} argz_next (char *@var{argz}, size_t @var{argz_len}, const char *@var{entry})
1770 The @code{argz_next} function provides a convenient way of iterating
1771 over the elements in the argz vector @var{argz}.  It returns a pointer
1772 to the next element in @var{argz} after the element @var{entry}, or
1773 @code{0} if there are no elements following @var{entry}.  If @var{entry}
1774 is @code{0}, the first element of @var{argz} is returned.
1775
1776 This behavior suggests two styles of iteration:
1777
1778 @smallexample
1779     char *entry = 0;
1780     while ((entry = argz_next (@var{argz}, @var{argz_len}, entry)))
1781       @var{action};
1782 @end smallexample
1783
1784 (the double parentheses are necessary to make some C compilers shut up
1785 about what they consider a questionable @code{while}-test) and:
1786
1787 @smallexample
1788     char *entry;
1789     for (entry = @var{argz};
1790          entry;
1791          entry = argz_next (@var{argz}, @var{argz_len}, entry))
1792       @var{action};
1793 @end smallexample
1794
1795 Note that the latter depends on @var{argz} having a value of @code{0} if
1796 it is empty (rather than a pointer to an empty block of memory); this
1797 invariant is maintained for argz vectors created by the functions here.
1798 @end deftypefun
1799
1800 @comment argz.h
1801 @comment GNU
1802 @deftypefun error_t argz_replace (@w{char **@var{argz}, size_t *@var{argz_len}}, @w{const char *@var{str}, const char *@var{with}}, @w{unsigned *@var{replace_count}})
1803 Replace any occurrences of the string @var{str} in @var{argz} with
1804 @var{with}, reallocating @var{argz} as necessary.  If
1805 @var{replace_count} is non-zero, @code{*@var{replace_count}} will be
1806 incremented by number of replacements performed.
1807 @end deftypefun
1808
1809 @node Envz Functions, , Argz Functions, Argz and Envz Vectors
1810 @subsection Envz Functions
1811
1812 Envz vectors are just argz vectors with additional constraints on the form
1813 of each element; as such, argz functions can also be used on them, where it
1814 makes sense.
1815
1816 Each element in an envz vector is a name-value pair, separated by a @code{'='}
1817 character; if multiple @code{'='} characters are present in an element, those
1818 after the first are considered part of the value, and treated like all other
1819 non-@code{'\0'} characters.
1820
1821 If @emph{no} @code{'='} characters are present in an element, that element is
1822 considered the name of a ``null'' entry, as distinct from an entry with an
1823 empty value: @code{envz_get} will return @code{0} if given the name of null
1824 entry, whereas an entry with an empty value would result in a value of
1825 @code{""}; @code{envz_entry} will still find such entries, however.  Null
1826 entries can be removed with @code{envz_strip} function.
1827
1828 As with argz functions, envz functions that may allocate memory (and thus
1829 fail) have a return type of @code{error_t}, and return either @code{0} or
1830 @code{ENOMEM}.
1831
1832 @pindex envz.h
1833 These functions are declared in the standard include file @file{envz.h}.
1834
1835 @comment envz.h
1836 @comment GNU
1837 @deftypefun {char *} envz_entry (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name})
1838 The @code{envz_entry} function finds the entry in @var{envz} with the name
1839 @var{name}, and returns a pointer to the whole entry---that is, the argz
1840 element which begins with @var{name} followed by a @code{'='} character.  If
1841 there is no entry with that name, @code{0} is returned.
1842 @end deftypefun
1843
1844 @comment envz.h
1845 @comment GNU
1846 @deftypefun {char *} envz_get (const char *@var{envz}, size_t @var{envz_len}, const char *@var{name})
1847 The @code{envz_get} function finds the entry in @var{envz} with the name
1848 @var{name} (like @code{envz_entry}), and returns a pointer to the value
1849 portion of that entry (following the @code{'='}).  If there is no entry with
1850 that name (or only a null entry), @code{0} is returned.
1851 @end deftypefun
1852
1853 @comment envz.h
1854 @comment GNU
1855 @deftypefun {error_t} envz_add (char **@var{envz}, size_t *@var{envz_len}, const char *@var{name}, const char *@var{value})
1856 The @code{envz_add} function adds an entry to @code{*@var{envz}}
1857 (updating @code{*@var{envz}} and @code{*@var{envz_len}}) with the name
1858 @var{name}, and value @var{value}.  If an entry with the same name
1859 already exists in @var{envz}, it is removed first.  If @var{value} is
1860 @code{0}, then the new entry will the special null type of entry
1861 (mentioned above).
1862 @end deftypefun
1863
1864 @comment envz.h
1865 @comment GNU
1866 @deftypefun {error_t} envz_merge (char **@var{envz}, size_t *@var{envz_len}, const char *@var{envz2}, size_t @var{envz2_len}, int @var{override})
1867 The @code{envz_merge} function adds each entry in @var{envz2} to @var{envz},
1868 as if with @code{envz_add}, updating @code{*@var{envz}} and
1869 @code{*@var{envz_len}}.  If @var{override} is true, then values in @var{envz2}
1870 will supersede those with the same name in @var{envz}, otherwise not.
1871
1872 Null entries are treated just like other entries in this respect, so a null
1873 entry in @var{envz} can prevent an entry of the same name in @var{envz2} from
1874 being added to @var{envz}, if @var{override} is false.
1875 @end deftypefun
1876
1877 @comment envz.h
1878 @comment GNU
1879 @deftypefun {void} envz_strip (char **@var{envz}, size_t *@var{envz_len})
1880 The @code{envz_strip} function removes any null entries from @var{envz},
1881 updating @code{*@var{envz}} and @code{*@var{envz_len}}.
1882 @end deftypefun