Back to index

glibc  2.9
string.h
Go to the documentation of this file.
00001 /* Copyright (C) 1991-1993, 1995-2004, 2007 Free Software Foundation, Inc.
00002    This file is part of the GNU C Library.
00003 
00004    The GNU C Library is free software; you can redistribute it and/or
00005    modify it under the terms of the GNU Lesser General Public
00006    License as published by the Free Software Foundation; either
00007    version 2.1 of the License, or (at your option) any later version.
00008 
00009    The GNU C Library is distributed in the hope that it will be useful,
00010    but WITHOUT ANY WARRANTY; without even the implied warranty of
00011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012    Lesser General Public License for more details.
00013 
00014    You should have received a copy of the GNU Lesser General Public
00015    License along with the GNU C Library; if not, write to the Free
00016    Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
00017    02111-1307 USA.  */
00018 
00019 /*
00020  *     ISO C99 Standard: 7.21 String handling    <string.h>
00021  */
00022 
00023 #ifndef       _STRING_H
00024 #define       _STRING_H     1
00025 
00026 #include <features.h>
00027 
00028 __BEGIN_DECLS
00029 
00030 /* Get size_t and NULL from <stddef.h>.  */
00031 #define       __need_size_t
00032 #define       __need_NULL
00033 #include <stddef.h>
00034 
00035 
00036 __BEGIN_NAMESPACE_STD
00037 /* Copy N bytes of SRC to DEST.  */
00038 extern void *memcpy (void *__restrict __dest,
00039                    __const void *__restrict __src, size_t __n)
00040      __THROW __nonnull ((1, 2));
00041 /* Copy N bytes of SRC to DEST, guaranteeing
00042    correct behavior for overlapping strings.  */
00043 extern void *memmove (void *__dest, __const void *__src, size_t __n)
00044      __THROW __nonnull ((1, 2));
00045 __END_NAMESPACE_STD
00046 
00047 /* Copy no more than N bytes of SRC to DEST, stopping when C is found.
00048    Return the position in DEST one byte past where C was copied,
00049    or NULL if C was not found in the first N bytes of SRC.  */
00050 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN
00051 extern void *memccpy (void *__restrict __dest, __const void *__restrict __src,
00052                     int __c, size_t __n)
00053      __THROW __nonnull ((1, 2));
00054 #endif /* SVID.  */
00055 
00056 
00057 __BEGIN_NAMESPACE_STD
00058 /* Set N bytes of S to C.  */
00059 extern void *memset (void *__s, int __c, size_t __n) __THROW __nonnull ((1));
00060 
00061 /* Compare N bytes of S1 and S2.  */
00062 extern int memcmp (__const void *__s1, __const void *__s2, size_t __n)
00063      __THROW __attribute_pure__ __nonnull ((1, 2));
00064 
00065 /* Search N bytes of S for C.  */
00066 extern void *memchr (__const void *__s, int __c, size_t __n)
00067       __THROW __attribute_pure__ __nonnull ((1));
00068 __END_NAMESPACE_STD
00069 
00070 #ifdef __USE_GNU
00071 /* Search in S for C.  This is similar to `memchr' but there is no
00072    length limit.  */
00073 extern void *rawmemchr (__const void *__s, int __c)
00074      __THROW __attribute_pure__ __nonnull ((1));
00075 
00076 /* Search N bytes of S for the final occurrence of C.  */
00077 extern void *memrchr (__const void *__s, int __c, size_t __n)
00078       __THROW __attribute_pure__ __nonnull ((1));
00079 #endif
00080 
00081 
00082 __BEGIN_NAMESPACE_STD
00083 /* Copy SRC to DEST.  */
00084 extern char *strcpy (char *__restrict __dest, __const char *__restrict __src)
00085      __THROW __nonnull ((1, 2));
00086 /* Copy no more than N characters of SRC to DEST.  */
00087 extern char *strncpy (char *__restrict __dest,
00088                     __const char *__restrict __src, size_t __n)
00089      __THROW __nonnull ((1, 2));
00090 
00091 /* Append SRC onto DEST.  */
00092 extern char *strcat (char *__restrict __dest, __const char *__restrict __src)
00093      __THROW __nonnull ((1, 2));
00094 /* Append no more than N characters from SRC onto DEST.  */
00095 extern char *strncat (char *__restrict __dest, __const char *__restrict __src,
00096                     size_t __n) __THROW __nonnull ((1, 2));
00097 
00098 /* Compare S1 and S2.  */
00099 extern int strcmp (__const char *__s1, __const char *__s2)
00100      __THROW __attribute_pure__ __nonnull ((1, 2));
00101 /* Compare N characters of S1 and S2.  */
00102 extern int strncmp (__const char *__s1, __const char *__s2, size_t __n)
00103      __THROW __attribute_pure__ __nonnull ((1, 2));
00104 
00105 /* Compare the collated forms of S1 and S2.  */
00106 extern int strcoll (__const char *__s1, __const char *__s2)
00107      __THROW __attribute_pure__ __nonnull ((1, 2));
00108 /* Put a transformation of SRC into no more than N bytes of DEST.  */
00109 extern size_t strxfrm (char *__restrict __dest,
00110                      __const char *__restrict __src, size_t __n)
00111      __THROW __nonnull ((2));
00112 __END_NAMESPACE_STD
00113 
00114 #ifdef __USE_GNU
00115 /* The following functions are equivalent to the both above but they
00116    take the locale they use for the collation as an extra argument.
00117    This is not standardsized but something like will come.  */
00118 # include <xlocale.h>
00119 
00120 /* Compare the collated forms of S1 and S2 using rules from L.  */
00121 extern int strcoll_l (__const char *__s1, __const char *__s2, __locale_t __l)
00122      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
00123 /* Put a transformation of SRC into no more than N bytes of DEST.  */
00124 extern size_t strxfrm_l (char *__dest, __const char *__src, size_t __n,
00125                       __locale_t __l) __THROW __nonnull ((2, 4));
00126 #endif
00127 
00128 #if defined __USE_SVID || defined __USE_BSD || defined __USE_XOPEN_EXTENDED
00129 /* Duplicate S, returning an identical malloc'd string.  */
00130 extern char *strdup (__const char *__s)
00131      __THROW __attribute_malloc__ __nonnull ((1));
00132 #endif
00133 
00134 /* Return a malloc'd copy of at most N bytes of STRING.  The
00135    resultant string is terminated even if no null terminator
00136    appears before STRING[N].  */
00137 #if defined __USE_GNU
00138 extern char *strndup (__const char *__string, size_t __n)
00139      __THROW __attribute_malloc__ __nonnull ((1));
00140 #endif
00141 
00142 #if defined __USE_GNU && defined __GNUC__
00143 /* Duplicate S, returning an identical alloca'd string.  */
00144 # define strdupa(s)                                                  \
00145   (__extension__                                                     \
00146     ({                                                               \
00147       __const char *__old = (s);                                     \
00148       size_t __len = strlen (__old) + 1;                             \
00149       char *__new = (char *) __builtin_alloca (__len);                      \
00150       (char *) memcpy (__new, __old, __len);                                \
00151     }))
00152 
00153 /* Return an alloca'd copy of at most N bytes of string.  */
00154 # define strndupa(s, n)                                                     \
00155   (__extension__                                                     \
00156     ({                                                               \
00157       __const char *__old = (s);                                     \
00158       size_t __len = strnlen (__old, (n));                                  \
00159       char *__new = (char *) __builtin_alloca (__len + 1);                  \
00160       __new[__len] = '\0';                                           \
00161       (char *) memcpy (__new, __old, __len);                                \
00162     }))
00163 #endif
00164 
00165 __BEGIN_NAMESPACE_STD
00166 /* Find the first occurrence of C in S.  */
00167 extern char *strchr (__const char *__s, int __c)
00168      __THROW __attribute_pure__ __nonnull ((1));
00169 /* Find the last occurrence of C in S.  */
00170 extern char *strrchr (__const char *__s, int __c)
00171      __THROW __attribute_pure__ __nonnull ((1));
00172 __END_NAMESPACE_STD
00173 
00174 #ifdef __USE_GNU
00175 /* This function is similar to `strchr'.  But it returns a pointer to
00176    the closing NUL byte in case C is not found in S.  */
00177 extern char *strchrnul (__const char *__s, int __c)
00178      __THROW __attribute_pure__ __nonnull ((1));
00179 #endif
00180 
00181 __BEGIN_NAMESPACE_STD
00182 /* Return the length of the initial segment of S which
00183    consists entirely of characters not in REJECT.  */
00184 extern size_t strcspn (__const char *__s, __const char *__reject)
00185      __THROW __attribute_pure__ __nonnull ((1, 2));
00186 /* Return the length of the initial segment of S which
00187    consists entirely of characters in ACCEPT.  */
00188 extern size_t strspn (__const char *__s, __const char *__accept)
00189      __THROW __attribute_pure__ __nonnull ((1, 2));
00190 /* Find the first occurrence in S of any character in ACCEPT.  */
00191 extern char *strpbrk (__const char *__s, __const char *__accept)
00192      __THROW __attribute_pure__ __nonnull ((1, 2));
00193 /* Find the first occurrence of NEEDLE in HAYSTACK.  */
00194 extern char *strstr (__const char *__haystack, __const char *__needle)
00195      __THROW __attribute_pure__ __nonnull ((1, 2));
00196 
00197 
00198 /* Divide S into tokens separated by characters in DELIM.  */
00199 extern char *strtok (char *__restrict __s, __const char *__restrict __delim)
00200      __THROW __nonnull ((2));
00201 __END_NAMESPACE_STD
00202 
00203 /* Divide S into tokens separated by characters in DELIM.  Information
00204    passed between calls are stored in SAVE_PTR.  */
00205 extern char *__strtok_r (char *__restrict __s,
00206                       __const char *__restrict __delim,
00207                       char **__restrict __save_ptr)
00208      __THROW __nonnull ((2, 3));
00209 #if defined __USE_POSIX || defined __USE_MISC
00210 extern char *strtok_r (char *__restrict __s, __const char *__restrict __delim,
00211                      char **__restrict __save_ptr)
00212      __THROW __nonnull ((2, 3));
00213 #endif
00214 
00215 #ifdef __USE_GNU
00216 /* Similar to `strstr' but this function ignores the case of both strings.  */
00217 extern char *strcasestr (__const char *__haystack, __const char *__needle)
00218      __THROW __attribute_pure__ __nonnull ((1, 2));
00219 #endif
00220 
00221 #ifdef __USE_GNU
00222 /* Find the first occurrence of NEEDLE in HAYSTACK.
00223    NEEDLE is NEEDLELEN bytes long;
00224    HAYSTACK is HAYSTACKLEN bytes long.  */
00225 extern void *memmem (__const void *__haystack, size_t __haystacklen,
00226                    __const void *__needle, size_t __needlelen)
00227      __THROW __attribute_pure__ __nonnull ((1, 3));
00228 
00229 /* Copy N bytes of SRC to DEST, return pointer to bytes after the
00230    last written byte.  */
00231 extern void *__mempcpy (void *__restrict __dest,
00232                      __const void *__restrict __src, size_t __n)
00233      __THROW __nonnull ((1, 2));
00234 extern void *mempcpy (void *__restrict __dest,
00235                     __const void *__restrict __src, size_t __n)
00236      __THROW __nonnull ((1, 2));
00237 #endif
00238 
00239 
00240 __BEGIN_NAMESPACE_STD
00241 /* Return the length of S.  */
00242 extern size_t strlen (__const char *__s)
00243      __THROW __attribute_pure__ __nonnull ((1));
00244 __END_NAMESPACE_STD
00245 
00246 #ifdef __USE_GNU
00247 /* Find the length of STRING, but scan at most MAXLEN characters.
00248    If no '\0' terminator is found in that many characters, return MAXLEN.  */
00249 extern size_t strnlen (__const char *__string, size_t __maxlen)
00250      __THROW __attribute_pure__ __nonnull ((1));
00251 #endif
00252 
00253 
00254 __BEGIN_NAMESPACE_STD
00255 /* Return a string describing the meaning of the `errno' code in ERRNUM.  */
00256 extern char *strerror (int __errnum) __THROW;
00257 __END_NAMESPACE_STD
00258 #if defined __USE_XOPEN2K || defined __USE_MISC
00259 /* Reentrant version of `strerror'.
00260    There are 2 flavors of `strerror_r', GNU which returns the string
00261    and may or may not use the supplied temporary buffer and POSIX one
00262    which fills the string into the buffer.
00263    To use the POSIX version, -D_XOPEN_SOURCE=600 or -D_POSIX_C_SOURCE=200112L
00264    without -D_GNU_SOURCE is needed, otherwise the GNU version is
00265    preferred.  */
00266 # if defined __USE_XOPEN2K && !defined __USE_GNU
00267 /* Fill BUF with a string describing the meaning of the `errno' code in
00268    ERRNUM.  */
00269 #  ifdef __REDIRECT_NTH
00270 extern int __REDIRECT_NTH (strerror_r,
00271                         (int __errnum, char *__buf, size_t __buflen),
00272                         __xpg_strerror_r) __nonnull ((2));
00273 #  else
00274 extern int __xpg_strerror_r (int __errnum, char *__buf, size_t __buflen)
00275      __THROW __nonnull ((2));
00276 #   define strerror_r __xpg_strerror_r
00277 #  endif
00278 # else
00279 /* If a temporary buffer is required, at most BUFLEN bytes of BUF will be
00280    used.  */
00281 extern char *strerror_r (int __errnum, char *__buf, size_t __buflen)
00282      __THROW __nonnull ((2));
00283 # endif
00284 #endif
00285 
00286 #ifdef __USE_GNU
00287 /* Translate error number to string according to the locale L.  */
00288 extern char *strerror_l (int __errnum, __locale_t __l) __THROW;
00289 #endif
00290 
00291 
00292 /* We define this function always since `bzero' is sometimes needed when
00293    the namespace rules does not allow this.  */
00294 extern void __bzero (void *__s, size_t __n) __THROW __nonnull ((1));
00295 
00296 #ifdef __USE_BSD
00297 /* Copy N bytes of SRC to DEST (like memmove, but args reversed).  */
00298 extern void bcopy (__const void *__src, void *__dest, size_t __n)
00299      __THROW __nonnull ((1, 2));
00300 
00301 /* Set N bytes of S to 0.  */
00302 extern void bzero (void *__s, size_t __n) __THROW __nonnull ((1));
00303 
00304 /* Compare N bytes of S1 and S2 (same as memcmp).  */
00305 extern int bcmp (__const void *__s1, __const void *__s2, size_t __n)
00306      __THROW __attribute_pure__ __nonnull ((1, 2));
00307 
00308 /* Find the first occurrence of C in S (same as strchr).  */
00309 extern char *index (__const char *__s, int __c)
00310      __THROW __attribute_pure__ __nonnull ((1));
00311 
00312 /* Find the last occurrence of C in S (same as strrchr).  */
00313 extern char *rindex (__const char *__s, int __c)
00314      __THROW __attribute_pure__ __nonnull ((1));
00315 
00316 /* Return the position of the first bit set in I, or 0 if none are set.
00317    The least-significant bit is position 1, the most-significant 32.  */
00318 extern int ffs (int __i) __THROW __attribute__ ((__const__));
00319 
00320 /* The following two functions are non-standard but necessary for non-32 bit
00321    platforms.  */
00322 # ifdef       __USE_GNU
00323 extern int ffsl (long int __l) __THROW __attribute__ ((__const__));
00324 #  ifdef __GNUC__
00325 __extension__ extern int ffsll (long long int __ll)
00326      __THROW __attribute__ ((__const__));
00327 #  endif
00328 # endif
00329 
00330 /* Compare S1 and S2, ignoring case.  */
00331 extern int strcasecmp (__const char *__s1, __const char *__s2)
00332      __THROW __attribute_pure__ __nonnull ((1, 2));
00333 
00334 /* Compare no more than N chars of S1 and S2, ignoring case.  */
00335 extern int strncasecmp (__const char *__s1, __const char *__s2, size_t __n)
00336      __THROW __attribute_pure__ __nonnull ((1, 2));
00337 #endif /* Use BSD.  */
00338 
00339 #ifdef __USE_GNU
00340 /* Again versions of a few functions which use the given locale instead
00341    of the global one.  */
00342 extern int strcasecmp_l (__const char *__s1, __const char *__s2,
00343                       __locale_t __loc)
00344      __THROW __attribute_pure__ __nonnull ((1, 2, 3));
00345 
00346 extern int strncasecmp_l (__const char *__s1, __const char *__s2,
00347                        size_t __n, __locale_t __loc)
00348      __THROW __attribute_pure__ __nonnull ((1, 2, 4));
00349 #endif
00350 
00351 #ifdef __USE_BSD
00352 /* Return the next DELIM-delimited token from *STRINGP,
00353    terminating it with a '\0', and update *STRINGP to point past it.  */
00354 extern char *strsep (char **__restrict __stringp,
00355                    __const char *__restrict __delim)
00356      __THROW __nonnull ((1, 2));
00357 #endif
00358 
00359 #ifdef __USE_GNU
00360 /* Compare S1 and S2 as strings holding name & indices/version numbers.  */
00361 extern int strverscmp (__const char *__s1, __const char *__s2)
00362      __THROW __attribute_pure__ __nonnull ((1, 2));
00363 
00364 /* Return a string describing the meaning of the signal number in SIG.  */
00365 extern char *strsignal (int __sig) __THROW;
00366 
00367 /* Copy SRC to DEST, returning the address of the terminating '\0' in DEST.  */
00368 extern char *__stpcpy (char *__restrict __dest, __const char *__restrict __src)
00369      __THROW __nonnull ((1, 2));
00370 extern char *stpcpy (char *__restrict __dest, __const char *__restrict __src)
00371      __THROW __nonnull ((1, 2));
00372 
00373 /* Copy no more than N characters of SRC to DEST, returning the address of
00374    the last character written into DEST.  */
00375 extern char *__stpncpy (char *__restrict __dest,
00376                      __const char *__restrict __src, size_t __n)
00377      __THROW __nonnull ((1, 2));
00378 extern char *stpncpy (char *__restrict __dest,
00379                     __const char *__restrict __src, size_t __n)
00380      __THROW __nonnull ((1, 2));
00381 
00382 /* Sautee STRING briskly.  */
00383 extern char *strfry (char *__string) __THROW __nonnull ((1));
00384 
00385 /* Frobnicate N bytes of S.  */
00386 extern void *memfrob (void *__s, size_t __n) __THROW __nonnull ((1));
00387 
00388 # ifndef basename
00389 /* Return the file name within directory of FILENAME.  We don't
00390    declare the function if the `basename' macro is available (defined
00391    in <libgen.h>) which makes the XPG version of this function
00392    available.  */
00393 extern char *basename (__const char *__filename) __THROW __nonnull ((1));
00394 # endif
00395 #endif
00396 
00397 
00398 #if defined __GNUC__ && __GNUC__ >= 2
00399 # if defined __OPTIMIZE__ && !defined __OPTIMIZE_SIZE__ \
00400      && !defined __NO_INLINE__ && !defined __cplusplus
00401 /* When using GNU CC we provide some optimized versions of selected
00402    functions from this header.  There are two kinds of optimizations:
00403 
00404    - machine-dependent optimizations, most probably using inline
00405      assembler code; these might be quite expensive since the code
00406      size can increase significantly.
00407      These optimizations are not used unless the symbol
00408        __USE_STRING_INLINES
00409      is defined before including this header.
00410 
00411    - machine-independent optimizations which do not increase the
00412      code size significantly and which optimize mainly situations
00413      where one or more arguments are compile-time constants.
00414      These optimizations are used always when the compiler is
00415      taught to optimize.
00416 
00417    One can inhibit all optimizations by defining __NO_STRING_INLINES.  */
00418 
00419 /* Get the machine-dependent optimizations (if any).  */
00420 #  include <bits/string.h>
00421 
00422 /* These are generic optimizations which do not add too much inline code.  */
00423 #  include <bits/string2.h>
00424 # endif
00425 
00426 # if __USE_FORTIFY_LEVEL > 0 && defined __extern_always_inline
00427 /* Functions with security checks.  */
00428 #  include <bits/string3.h>
00429 # endif
00430 #endif
00431 
00432 __END_DECLS
00433 
00434 #endif /* string.h  */