OSX/libsecurity_asn1/lib/plstr.h

   1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /*
   3  * The contents of this file are subject to the Mozilla Public
   4  * License Version 1.1 (the "License"); you may not use this file
   5  * except in compliance with the License. You may obtain a copy of
   6  * the License at http://www.mozilla.org/MPL/
   7  *
   8  * Software distributed under the License is distributed on an "AS
   9  * IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or
  10  * implied. See the License for the specific language governing
  11  * rights and limitations under the License.
  12  *
  13  * The Original Code is the Netscape Portable Runtime (NSPR).
  14  *
  15  * The Initial Developer of the Original Code is Netscape
  16  * Communications Corporation.  Portions created by Netscape are
  17  * Copyright (C) 1998-2000 Netscape Communications Corporation.  All
  18  * Rights Reserved.
  19  *
  20  * Contributor(s):
  21  *   Roland Mainz <roland mainz@informatik.med.uni-giessen.de>
  22  *
  23  * Alternatively, the contents of this file may be used under the
  24  * terms of the GNU General Public License Version 2 or later (the
  25  * "GPL"), in which case the provisions of the GPL are applicable
  26  * instead of those above.  If you wish to allow use of your
  27  * version of this file only under the terms of the GPL and not to
  28  * allow others to use your version of this file under the MPL,
  29  * indicate your decision by deleting the provisions above and
  30  * replace them with the notice and other provisions required by
  31  * the GPL.  If you do not delete the provisions above, a recipient
  32  * may use your version of this file under either the MPL or the
  33  * GPL.
  34  */
  35
  36 #ifndef _plstr_h
  37 #define _plstr_h
  38
  39 /*
  40  * plstr.h
  41  *
  42  * This header file exports the API to the NSPR portable library or string-
  43  * handling functions.
  44  *
  45  * This API was not designed as an "optimal" or "ideal" string library; it
  46  * was based on the good ol' unix string.3 functions, and was written to
  47  *
  48  *  1) replace the libc functions, for cross-platform consistancy,
  49  *  2) complete the API on platforms lacking common functions (e.g.,
  50  *     strcase*), and
  51  *  3) to implement some obvious "closure" functions that I've seen
  52  *     people hacking around in our code.
  53  *
  54  * Point number three largely means that most functions have an "strn"
  55  * limited-length version, and all comparison routines have a non-case-
  56  * sensitive version available.
  57  */
  58
  59 #include <security_asn1/prtypes.h>
  60
  61 PR_BEGIN_EXTERN_C
  62 /*
  63  * PL_strlen
  64  *
  65  * Returns the length of the provided string, not including the trailing '\0'.
  66  */
  67
  68 PR_EXTERN(PRUint32)
  69 PL_strlen(const char *str);
  70
  71 /*
  72  * PL_strnlen
  73  *
  74  * Returns the length of the provided string, not including the trailing '\0',
  75  * up to the indicated maximum.  The string will not be examined beyond the
  76  * maximum; if no terminating '\0' is found, the maximum will be returned.
  77  */
  78
  79 PR_EXTERN(PRUint32)
  80 PL_strnlen(const char *str, PRUint32 max);
  81
  82 /*
  83  * PL_strcpy
  84  *
  85  * Copies the source string, up to and including the trailing '\0', into the
  86  * destination buffer.  It does not (can not) verify that the destination
  87  * buffer is large enough.  It returns the "dest" argument.
  88  */
  89
  90 PR_EXTERN(char *)
  91 PL_strcpy(char *dest, const char *src);
  92
  93 /*
  94  * PL_strncpy
  95  *
  96  * Copies the source string into the destination buffer, up to and including
  97  * the trailing '\0' or up to and including the max'th character, whichever
  98  * comes first.  It does not (can not) verify that the destination buffer is
  99  * large enough.  If the source string is longer than the maximum length,
 100  * the result will *not* be null-terminated (JLRU).
 101  */
 102
 103 PR_EXTERN(char *)
 104 PL_strncpy(char *dest, const char *src, PRUint32 max);
 105
 106 /*
 107  * PL_strncpyz
 108  *
 109  * Copies the source string into the destination buffer, up to and including
 110  * the trailing '\0' or up but not including the max'th character, whichever
 111  * comes first.  It does not (can not) verify that the destination buffer is
 112  * large enough.  The destination string is always terminated with a '\0',
 113  * unlike the traditional libc implementation.  It returns the "dest" argument.
 114  *
 115  * NOTE: If you call this with a source "abcdefg" and a max of 5, the
 116  * destination will end up with "abcd\0" (i.e., it's strlen length will be 4)!
 117  *
 118  * This means you can do this:
 119  *
 120  *     char buffer[ SOME_SIZE ];
 121  *     PL_strncpyz(buffer, src, sizeof(buffer));
 122  *
 123  * and the result will be properly terminated.
 124  */
 125
 126 PR_EXTERN(char *)
 127 PL_strncpyz(char *dest, const char *src, PRUint32 max);
 128
 129 /*
 130  * PL_strdup
 131  *
 132  * Returns a pointer to a malloc'd extent of memory containing a duplicate
 133  * of the argument string.  The size of the allocated extent is one greater
 134  * than the length of the argument string, because of the terminator.  A
 135  * null argument, like a zero-length argument, will result in a pointer to
 136  * a one-byte extent containing the null value.  This routine returns null
 137  * upon malloc failure.
 138  */
 139
 140 PR_EXTERN(char *)
 141 PL_strdup(const char *s);
 142
 143 /*
 144  * PL_strfree
 145  *
 146  * Free memory allocated by PL_strdup
 147  */
 148
 149 PR_EXTERN(void)
 150 PL_strfree(char *s);
 151
 152 /*
 153  * PL_strndup
 154  *
 155  * Returns a pointer to a malloc'd extent of memory containing a duplicate
 156  * of the argument string, up to the maximum specified.  If the argument
 157  * string has a length greater than the value of the specified maximum, the
 158  * return value will be a pointer to an extent of memory of length one
 159  * greater than the maximum specified.  A null string, a zero-length string,
 160  * or a zero maximum will all result in a pointer to a one-byte extent
 161  * containing the null value.  This routine returns null upon malloc failure.
 162  */
 163
 164 PR_EXTERN(char *)
 165 PL_strndup(const char *s, PRUint32 max);
 166
 167 /*
 168  * PL_strcat
 169  *
 170  * Appends a copy of the string pointed to by the second argument to the
 171  * end of the string pointed to by the first.  The destination buffer is
 172  * not (can not be) checked for sufficient size.  A null destination
 173  * argument returns null; otherwise, the first argument is returned.
 174  */
 175
 176 PR_EXTERN(char *)
 177 PL_strcat(char *dst, const char *src);
 178
 179 /*
 180  * PL_strncat
 181  *
 182  * Appends a copy of the string pointed to by the second argument, up to
 183  * the maximum size specified, to the end of the string pointed to by the
 184  * first.  The destination buffer is not (can not be) checked for sufficient
 185  * size.  A null destination argument returns null; otherwise, the first
 186  * argument is returned.  If the maximum size limits the copy, then the
 187  * result will *not* be null-terminated (JLRU).  A null destination
 188  * returns null; otherwise, the destination argument is returned.
 189  */
 190
 191 PR_EXTERN(char *)
 192 PL_strncat(char *dst, const char *src, PRUint32 max);
 193
 194 /*
 195  * PL_strcatn
 196  *
 197  * Appends a copy of the string pointed to by the third argument, to the
 198  * end of the string pointed to by the first.  The second argument specifies
 199  * the maximum size of the destination buffer, including the null termination.
 200  * If the existing string in dst is longer than the max, no action is taken.
 201  * The resulting string will be null-terminated.  A null destination returns
 202  * null; otherwise, the destination argument is returned.
 203  */
 204
 205 PR_EXTERN(char *)
 206 PL_strcatn(char *dst, PRUint32 max, const char *src);
 207
 208 /*
 209  * PL_strcmp
 210  *
 211  * Returns an integer, the sign of which -- positive, zero, or negative --
 212  * reflects the lexical sorting order of the two strings indicated.  The
 213  * result is positive if the first string comes after the second.  The
 214  * NSPR implementation is not i18n.
 215  */
 216
 217 PR_EXTERN(PRIntn)
 218 PL_strcmp(const char *a, const char *b);
 219
 220 /*
 221  * PL_strncmp
 222  *
 223  * Returns an integer, the sign of which -- positive, zero, or negative --
 224  * reflects the lexical sorting order of the two strings indicated, up to
 225  * the maximum specified.  The result is positive if the first string comes
 226  * after the second.  The NSPR implementation is not i18n.  If the maximum
 227  * is zero, only the existance or non-existance (pointer is null) of the
 228  * strings is compared.
 229  */
 230
 231 PR_EXTERN(PRIntn)
 232 PL_strncmp(const char *a, const char *b, PRUint32 max);
 233
 234 /*
 235  * PL_strcasecmp
 236  *
 237  * Returns an integer, the sign of which -- positive, zero or negative --
 238  * reflects the case-insensitive lexical sorting order of the two strings
 239  * indicated.  The result is positive if the first string comes after the
 240  * second.  The NSPR implementation is not i18n.
 241  */
 242
 243 PR_EXTERN(PRIntn)
 244 PL_strcasecmp(const char *a, const char *b);
 245
 246 /*
 247  * PL_strncasecmp
 248  *
 249  * Returns an integer, the sign of which -- positive, zero or negative --
 250  * reflects the case-insensitive lexical sorting order of the first n characters
 251  * of the two strings indicated.  The result is positive if the first string comes
 252  * after the second.  The NSPR implementation is not i18n.
 253  */
 254
 255 PR_EXTERN(PRIntn)
 256 PL_strncasecmp(const char *a, const char *b, PRUint32 max);
 257
 258 /*
 259  * PL_strchr
 260  *
 261  * Returns a pointer to the first instance of the specified character in the
 262  * provided string.  It returns null if the character is not found, or if the
 263  * provided string is null.  The character may be the null character.
 264  */
 265
 266 PR_EXTERN(char *)
 267 PL_strchr(const char *s, char c);
 268
 269 /*
 270  * PL_strrchr
 271  *
 272  * Returns a pointer to the last instance of the specified character in the
 273  * provided string.  It returns null if the character is not found, or if the
 274  * provided string is null.  The character may be the null character.
 275  */
 276
 277 PR_EXTERN(char *)
 278 PL_strrchr(const char *s, char c);
 279
 280 /*
 281  * PL_strnchr
 282  *
 283  * Returns a pointer to the first instance of the specified character within the
 284  * first n characters of the provided string.  It returns null if the character
 285  * is not found, or if the provided string is null.  The character may be the
 286  * null character.
 287  */
 288
 289 PR_EXTERN(char *)
 290 PL_strnchr(const char *s, char c, PRUint32 n);
 291
 292 /*
 293  * PL_strnrchr
 294  *
 295  * Returns a pointer to the last instance of the specified character within the
 296  * first n characters of the provided string.  It returns null if the character is
 297  * not found, or if the provided string is null.  The character may be the null
 298  * character.
 299  */
 300
 301 PR_EXTERN(char *)
 302 PL_strnrchr(const char *s, char c, PRUint32 n);
 303
 304 /*
 305  * NOTE: Looking for strcasechr, strcaserchr, strncasechr, or strncaserchr?
 306  * Use strpbrk, strprbrk, strnpbrk or strnprbrk.
 307  */
 308
 309 /*
 310  * PL_strpbrk
 311  *
 312  * Returns a pointer to the first instance in the first string of any character
 313  * (not including the terminating null character) of the second string.  It returns
 314  * null if either string is null.
 315  */
 316
 317 PR_EXTERN(char *)
 318 PL_strpbrk(const char *s, const char *list);
 319
 320 /*
 321  * PL_strprbrk
 322  *
 323  * Returns a pointer to the last instance in the first string of any character
 324  * (not including the terminating null character) of the second string.  It returns
 325  * null if either string is null.
 326  */
 327
 328 PR_EXTERN(char *)
 329 PL_strprbrk(const char *s, const char *list);
 330
 331 /*
 332  * PL_strnpbrk
 333  *
 334  * Returns a pointer to the first instance (within the first n characters) of any
 335  * character (not including the terminating null character) of the second string.
 336  * It returns null if either string is null.
 337  */
 338
 339 PR_EXTERN(char *)
 340 PL_strnpbrk(const char *s, const char *list, PRUint32 n);
 341
 342 /*
 343  * PL_strnprbrk
 344  *
 345  * Returns a pointer to the last instance (within the first n characters) of any
 346  * character (not including the terminating null character) of the second string.
 347  * It returns null if either string is null.
 348  */
 349
 350 PR_EXTERN(char *)
 351 PL_strnprbrk(const char *s, const char *list, PRUint32 n);
 352
 353 /*
 354  * PL_strstr
 355  *
 356  * Returns a pointer to the first instance of the little string within the
 357  * big one.  It returns null if either string is null.
 358  */
 359
 360 PR_EXTERN(char *)
 361 PL_strstr(const char *big, const char *little);
 362
 363 /*
 364  * PL_strrstr
 365  *
 366  * Returns a pointer to the last instance of the little string within the big one.
 367  * It returns null if either string is null.
 368  */
 369
 370 PR_EXTERN(char *)
 371 PL_strrstr(const char *big, const char *little);
 372
 373 /*
 374  * PL_strnstr
 375  *
 376  * Returns a pointer to the first instance of the little string within the first
 377  * n characters of the big one.  It returns null if either string is null.  It
 378  * returns null if the length of the little string is greater than n.
 379  */
 380
 381 PR_EXTERN(char *)
 382 PL_strnstr(const char *big, const char *little, PRUint32 n);
 383
 384 /*
 385  * PL_strnrstr
 386  *
 387  * Returns a pointer to the last instance of the little string within the first
 388  * n characters of the big one.  It returns null if either string is null.  It
 389  * returns null if the length of the little string is greater than n.
 390  */
 391
 392 PR_EXTERN(char *)
 393 PL_strnrstr(const char *big, const char *little, PRUint32 max);
 394
 395 /*
 396  * PL_strcasestr
 397  *
 398  * Returns a pointer to the first instance of the little string within the big one,
 399  * ignoring case.  It returns null if either string is null.
 400  */
 401
 402 PR_EXTERN(char *)
 403 PL_strcasestr(const char *big, const char *little);
 404
 405 /*
 406  * PL_strcaserstr
 407  *
 408  * Returns a pointer to the last instance of the little string within the big one,
 409  * ignoring case.  It returns null if either string is null.
 410  */
 411
 412 PR_EXTERN(char *)
 413 PL_strcaserstr(const char *big, const char *little);
 414
 415 /*
 416  * PL_strncasestr
 417  *
 418  * Returns a pointer to the first instance of the listtle string within the first
 419  * n characters of the big one, ignoring case.  It returns null if either string is
 420  * null.  It returns null if the length of the little string is greater than n.
 421  */
 422
 423 PR_EXTERN(char *)
 424 PL_strncasestr(const char *big, const char *little, PRUint32 max);
 425
 426 /*
 427  * PL_strncaserstr
 428  *
 429  * Returns a pointer to the last instance of the little string within the first
 430  * n characters of the big one, ignoring case.  It returns null if either string is
 431  * null.  It returns null if the length of the little string is greater than n.
 432  */
 433
 434 PR_EXTERN(char *)
 435 PL_strncaserstr(const char *big, const char *little, PRUint32 max);
 436
 437 /*
 438  * PL_strtok_r
 439  *
 440  * Splits the string s1 into tokens, separated by one or more characters
 441  * from the separator string s2.  The argument lasts points to a
 442  * user-supplied char * pointer in which PL_strtok_r stores information
 443  * for it to continue scanning the same string.
 444  *
 445  * In the first call to PL_strtok_r, s1 points to a string and the value
 446  * of *lasts is ignored.  PL_strtok_r returns a pointer to the first
 447  * token, writes '\0' into the character following the first token, and
 448  * updates *lasts.
 449  *
 450  * In subsequent calls, s1 is null and lasts must stay unchanged from the
 451  * previous call.  The separator string s2 may be different from call to
 452  * call.  PL_strtok_r returns a pointer to the next token in s1.  When no
 453  * token remains in s1, PL_strtok_r returns null.
 454  */
 455
 456 PR_EXTERN(char *)
 457 PL_strtok_r(char *s1, const char *s2, char **lasts);
 458
 459 /*
 460  * Things not (yet?) included: strspn/strcspn, strsep.
 461  * memchr, memcmp, memcpy, memccpy, index, rindex, bcmp, bcopy, bzero.
 462  * Any and all i18n/l10n stuff.
 463  */
 464
 465 PR_END_EXTERN_C
 466
 467 #endif /* _plstr_h */