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
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.
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.
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
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
30 * String/Array Comparison:: Functions for byte-wise and character-wise
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
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.
42 @node Representation of Strings
43 @section Representation of Strings
44 @cindex string, representation of
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.
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.
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'}.
68 A null character is quite different conceptually from a null pointer,
69 although both are represented by the integer @code{0}.
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.
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
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
96 @cindex string allocation
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
107 @node String/Array Conventions
108 @section String and Array Conventions
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.
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.
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''.
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.
141 @section String Length
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}.
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.)
156 strlen ("hello, world")
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:
166 char string[32] = "hello, world";
173 But beware, this will not work unless @var{string} is the character
174 array itself, not a pointer to it. For example:
177 char string[32] = "hello, world";
182 @result{} 4 /* @r{(on a machine with 4 byte pointers)} */
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.
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
200 char string[32] = "hello, world";
207 This function is a GNU extension.
210 @node Copying and Concatenation
211 @section Copying and Concatenation
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
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
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.
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
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
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.
252 The value returned by @code{memcpy} is the value of @var{to}.
254 Here is an example of how you might use @code{memcpy} to copy the
255 contents of an array:
258 struct foo *oldarray, *newarray;
261 memcpy (new, old, arraysize * sizeof (struct foo));
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}))}.
275 This function is useful in situations where a number of objects shall be
276 copied to consecutive memory positions.
280 combine (void *o1, size_t s1, void *o2, size_t s2)
282 void *result = malloc (s1 + s2);
284 mempcpy (mempcpy (result, o1, s1), o2, s2);
289 This function is a GNU extension.
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}.
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}.
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}.
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}.
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}.
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}.
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.
344 The behavior of @code{strncpy} is undefined if the strings overlap.
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.
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.
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.
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
375 This function is different to @code{strncpy} in that it always
376 terminates the destination string.
378 @code{strndup} is a GNU extension.
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.
388 For example, this program uses @code{stpcpy} to concatenate @samp{foo}
389 and @samp{bar} to produce @samp{foobar}, which it then prints.
392 @include stpcpy.c.texi
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
399 Its behavior is undefined if the strings overlap.
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}.
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}.
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.
420 This function is not part of ISO or POSIX but was found useful while
421 developing the GNU C Library itself.
423 Its behaviour is undefined if the strings overlap.
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}.
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.
440 @include strdupa.c.texi
443 Please note that calling @code{strtok} using @var{path} directly is
446 This function is only available if GNU CC is used.
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.
457 This function is implemented only as a macro, just like @code{strdupa}.
459 @code{strndupa} is only available if GNU CC is used.
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}.
470 An equivalent definition for @code{strcat} would be:
474 strcat (char *to, const char *from)
476 strcpy (to + strlen (to), from);
481 This function has undefined results if the strings overlap.
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
496 /* @r{This function concatenates arbitrarily many strings. The last}
497 @r{parameter must be @code{NULL}.} */
499 concat (const char *str, ...)
507 /* @r{Actually @code{va_copy}, but this is the name more gcc versions}
511 /* @r{Determine how much space we need.} */
512 for (s = str; s != NULL; s = va_arg (ap, const char *))
517 result = (char *) malloc (total);
522 /* @r{Copy the strings.} */
523 for (s = str; s != NULL; s = va_arg (ap2, const char *))
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
545 concat (const char *str, ...)
548 size_t allocated = 100;
549 char *result = (char *) malloc (allocated);
552 if (allocated != NULL)
559 for (s = str; s != NULL; s = va_arg (ap, const char *))
561 size_t len = strlen (s);
563 /* @r{Resize the allocated memory if necessary.} */
564 if (wp + len + 1 > result + allocated)
566 allocated = (allocated + len) * 2;
567 newp = (char *) realloc (result, allocated);
573 wp = newp + (wp - result);
577 wp = mempcpy (wp, s, len);
580 /* @r{Terminate the result string.} */
583 /* @r{Resize memory to the optimal size.} */
584 newp = realloc (result, wp - result);
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
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}.
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.
619 The @code{strncat} function could be implemented like this:
624 strncat (char *to, const char *from, size_t size)
626 strncpy (to + strlen (to), from, size);
632 The behavior of @code{strncat} is undefined if the strings overlap.
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}.
640 @include strncat.c.texi
644 The output produced by this program looks like:
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.
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.
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
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.
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
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)}}.
691 All of these functions are declared in the header file @file{string.h}.
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}).
703 If the contents of the two blocks are equal, @code{memcmp} returns
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.
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.
723 For example, given a structure type definition like:
739 you are better off writing a specialized comparison function to compare
740 @code{struct foo} objects instead of comparing them with @code{memcmp}.
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}).
750 If the two strings are equal, @code{strcmp} returns @code{0}.
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}.
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.
767 @code{strcasecmp} is derived from 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.
778 @code{strncasecmp} is a GNU extension.
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.
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.)
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.} */
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}.
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:
829 integral/integral: we compare values as you would expect.
832 fractional/integral: the fractional part is less than the integral one.
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.
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.} */
854 This function is especially useful when dealing with filename sorting,
855 because filenames frequently hold indices/version numbers.
857 @code{strverscmp} is a GNU extension.
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.
866 @node Collation Functions
867 @section Collation Functions
869 @cindex collating strings
870 @cindex string collation functions
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}.
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}.
886 In the standard C locale, the collation sequence for @code{strcoll} is
887 the same as that for @code{strcmp}.
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.
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}.
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).
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}.)
918 /* @r{This is the comparison function used with @code{qsort}.} */
921 compare_elements (char **p1, char **p2)
923 return strcoll (*p1, *p2);
926 /* @r{This is the entry point---the function to sort}
927 @r{strings using the locale's collating sequence.} */
930 sort_strings (char **array, int nstrings)
932 /* @r{Sort @code{temp_array} by comparing the strings.} */
933 qsort (array, nstrings,
934 sizeof (char *), compare_elements);
938 @cindex converting string to collation order
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
948 The behavior is undefined if the strings @var{to} and @var{from}
949 overlap; see @ref{Copying and Concatenation}.
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.
958 The transformed string may be longer than the original string, and it
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.
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.
976 struct sorter @{ char *input; char *transformed; @};
978 /* @r{This is the comparison function used with @code{qsort}}
979 @r{to sort an array of @code{struct sorter}.} */
982 compare_elements (struct sorter *p1, struct sorter *p2)
984 return strcmp (p1->transformed, p2->transformed);
987 /* @r{This is the entry point---the function to sort}
988 @r{strings using the locale's collating sequence.} */
991 sort_strings_fast (char **array, int nstrings)
993 struct sorter temp_array[nstrings];
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++)
1000 size_t length = strlen (array[i]) * 2;
1002 size_t transformed_length;
1004 temp_array[i].input = array[i];
1006 /* @r{First try a buffer perhaps big enough.} */
1007 transformed = (char *) xmalloc (length);
1009 /* @r{Transform @code{array[i]}.} */
1010 transformed_length = strxfrm (transformed, array[i], length);
1012 /* @r{If the buffer was not large enough, resize it}
1013 @r{and try again.} */
1014 if (transformed_length >= length)
1016 /* @r{Allocate the needed space. +1 for terminating}
1017 @r{@code{NUL} character.} */
1018 transformed = (char *) xrealloc (transformed,
1019 transformed_length + 1);
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);
1027 temp_array[i].transformed = transformed;
1030 /* @r{Sort @code{temp_array} by comparing transformed strings.} */
1031 qsort (temp_array, sizeof (struct sorter),
1032 nstrings, compare_elements);
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;
1039 /* @r{Free the strings we allocated.} */
1040 for (i = 0; i < nstrings; i++)
1041 free (temp_array[i].transformed);
1045 @strong{Compatibility Note:} The string collation functions are a new
1046 feature of @w{ISO C90}. Older C dialects have no equivalent feature.
1048 @node Search Functions
1049 @section Search Functions
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}.
1055 @cindex search functions (for strings)
1056 @cindex string search functions
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.
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).
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.
1085 strchr ("hello, world", 'l')
1086 @result{} "llo, world"
1087 strchr ("hello, world", '?')
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.
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.
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:
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
1118 s = strchr (s, '\0');
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}
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
1138 strrchr ("hello, world", 'l')
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}.
1154 strstr ("hello, world", "l")
1155 @result{} "llo, world"
1156 strstr ("hello, world", "wo")
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.
1172 strstr ("hello, world", "L")
1173 @result{} "llo, world"
1174 strstr ("hello, World", "wo")
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
1188 This function is a GNU extension.
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.
1201 strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
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}.)
1217 strcspn ("hello, world", " \t\n,.;!?")
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.
1231 @c @group Invalid outside the example.
1235 strpbrk ("hello, world", " \t\n,.;!?")
1242 @subsection Compatibility String Search Functions
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.
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.
1262 @node Finding Tokens in a String
1263 @section Finding Tokens in a String
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}.
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}.
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).
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.
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}.
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
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.
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.
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
1327 The function @code{strtok} is not reentrant. @xref{Nonreentrancy}, for
1328 a discussion of where and why reentrancy is important.
1330 Here is a simple example showing the use of @code{strtok}.
1332 @comment Yes, this example has been tested.
1339 const char string[] = "words separated by spaces -- and, punctuation!";
1340 const char delimiters[] = " .,;:!-";
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 */
1355 The GNU C library contains two more functions for tokenizing a string
1356 which overcome the limitation of non-reentrancy.
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.
1369 This function is defined in POSIX.1 and can be found on many systems
1370 which support multi-threading.
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
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.
1390 This function was introduced in 4.3BSD and therefore is widely available.
1393 Here is how the above example looks like when @code{strsep} is used.
1395 @comment Yes, this example has been tested.
1402 const char string[] = "words separated by spaces -- and, punctuation!";
1403 const char delimiters[] = " .,;:!-";
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 */
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.
1435 The prototype for this function is in @file{string.h}.
1439 @deftypefun {char *} strfry (char *@var{string})
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.
1446 The return value of @code{strfry} is always @var{string}.
1448 @strong{Portability Note:} This function is unique to the GNU C library.
1453 @node Trivial Encryption
1454 @section Trivial Encryption
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
1467 For true encryption, @xref{Cryptographic Functions}.
1469 This function is declared in @file{string.h}.
1474 @deftypefun {void *} memfrob (void *@var{mem}, size_t @var{length})
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}.
1481 Note that @code{memfrob} a second time on the same data structure
1482 returns it to its original state.
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}.
1489 @strong{Portability Note:} This function is unique to the GNU C library.
1493 @node Encode Binary Data
1494 @section Encode Binary Data
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
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.
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
1526 encode (const void *buf, size_t len)
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);
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.} */
1537 cp = mempcpy (cp, l64a (htonl (len)), 6);
1541 unsigned long int n = *in++;
1542 n = (n << 8) | *in++;
1543 n = (n << 8) | *in++;
1544 n = (n << 8) | *in++;
1547 cp = mempcpy (cp, l64a (htonl (n)), 6);
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, "......");
1555 unsigned long int n = *in++;
1558 n = (n << 8) | *in++;
1562 memcpy (cp, l64a (htonl (n)), 6);
1570 It is strange that the library does not provide the complete
1571 functionality needed but so be it.
1575 To decode data produced with @code{l64a} the following function should be
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.
1588 The decoded number is returned as a @code{long int} value.
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:
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}
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.
1619 @node Argz and Envz Vectors
1620 @section Argz and Envz Vectors
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
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
1636 * Argz Functions:: Operations on argz vectors.
1637 * Envz Functions:: Additional operations on environment vectors.
1640 @node Argz Functions, Envz Functions, , Argz and Envz Vectors
1641 @subsection Argz Functions
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.
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}.
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.
1662 These functions are declared in the standard include file @file{argz.h}.
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}.
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}.
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
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}).
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
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.
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}.
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}}.
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.
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.
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.
1776 This behavior suggests two styles of iteration:
1780 while ((entry = argz_next (@var{argz}, @var{argz_len}, entry)))
1784 (the double parentheses are necessary to make some C compilers shut up
1785 about what they consider a questionable @code{while}-test) and:
1789 for (entry = @var{argz};
1791 entry = argz_next (@var{argz}, @var{argz_len}, entry))
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.
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.
1809 @node Envz Functions, , Argz Functions, Argz and Envz Vectors
1810 @subsection Envz Functions
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
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.
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.
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
1833 These functions are declared in the standard include file @file{envz.h}.
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.
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.
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
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.
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.
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}}.