libiberty/functions.texi

   1 @c Automatically generated from *.c and others (the comments before
   2 @c each entry tell you which file and where in that file).  DO NOT EDIT!
   3 @c Edit the *.c files, configure with --enable-maintainer-mode,
   4 @c and let gather-docs build you a new copy.
   5
   6 @c alloca.c:26
   7 @deftypefn Replacement void* alloca (size_t)
   8
   9 This function allocates memory which will be automatically reclaimed
  10 after the procedure exits.  The @libib{} implementation does not free
  11 the memory immediately but will do so eventually during subsequent
  12 calls to this function.  Memory is allocated using @code{xmalloc} under
  13 normal circumstances.
  14
  15 The header file @file{alloca-conf.h} can be used in conjunction with the
  16 GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
  17 available this function.  The @code{AC_FUNC_ALLOCA} test requires that
  18 client code use a block of preprocessor code to be safe (see the Autoconf
  19 manual for more); this header incorporates that logic and more, including
  20 the possibility of a GCC builtin function.
  21
  22 @end deftypefn
  23
  24 @c atexit.c:6
  25 @deftypefn Supplemental int atexit (void (*@var{f})())
  26
  27 Causes function @var{f} to be called at exit.  Returns 0.
  28
  29 @end deftypefn
  30
  31 @c basename.c:6
  32 @deftypefn Supplemental char* basename (const char *@var{name})
  33
  34 Returns a pointer to the last component of pathname @var{name}.
  35 Behavior is undefined if the pathname ends in a directory separator.
  36
  37 @end deftypefn
  38
  39 @c bcmp.c:6
  40 @deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
  41
  42 Compares the first @var{count} bytes of two areas of memory.  Returns
  43 zero if they are the same, non-zero otherwise.  Returns zero if
  44 @var{count} is zero.  A non-zero result only indicates a difference,
  45 it does not indicate any sorting order (say, by having a positive
  46 result mean @var{x} sorts before @var{y}).
  47
  48 @end deftypefn
  49
  50 @c bcopy.c:3
  51 @deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
  52
  53 Copies @var{length} bytes from memory region @var{in} to region
  54 @var{out}.  The use of @code{bcopy} is deprecated in new programs.
  55
  56 @end deftypefn
  57
  58 @c bsearch.c:33
  59 @deftypefn Supplemental void* bsearch (const void *@var{key}, const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, int (*@var{compar})(const void *, const void *))
  60
  61 Performs a search over an array of @var{nmemb} elements pointed to by
  62 @var{base} for a member that matches the object pointed to by @var{key}.
  63 The size of each member is specified by @var{size}.  The array contents
  64 should be sorted in ascending order according to the @var{compar}
  65 comparison function.  This routine should take two arguments pointing to
  66 the @var{key} and to an array member, in that order, and should return an
  67 integer less than, equal to, or greater than zero if the @var{key} object
  68 is respecitively less than, matching, or greater than the array member.
  69
  70 @end deftypefn
  71
  72 @c bzero.c:6
  73 @deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
  74
  75 Zeros @var{count} bytes starting at @var{mem}.  Use if this function
  76 is deprecated in favor of @code{memset}.
  77
  78 @end deftypefn
  79
  80 @c calloc.c:6
  81 @deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
  82
  83 Uses @code{malloc} to allocate storage for @var{nelem} objects of
  84 @var{elsize} bytes each, then zeros the memory.
  85
  86 @end deftypefn
  87
  88 @c clock.c:27
  89 @deftypefn Supplemental long clock ()
  90
  91 Returns an approximation of the CPU time used by the process as a
  92 @code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
  93 number of seconds used.
  94
  95 @end deftypefn
  96
  97 @c strerror.c:566
  98 @deftypefn Replacement int errno_max (void)
  99
 100 Returns the maximum @code{errno} value for which a corresponding
 101 symbolic name or message is available.  Note that in the case where we
 102 use the @code{sys_errlist} supplied by the system, it is possible for
 103 there to be more symbolic names than messages, or vice versa.  In
 104 fact, the manual page for @code{perror(3C)} explicitly warns that one
 105 should check the size of the table (@code{sys_nerr}) before indexing
 106 it, since new error codes may be added to the system before they are
 107 added to the table.  Thus @code{sys_nerr} might be smaller than value
 108 implied by the largest @code{errno} value defined in @file{errno.h}.
 109
 110 We return the maximum value that can be used to obtain a meaningful
 111 symbolic name or message.
 112
 113 @end deftypefn
 114
 115 @c getcwd.c:6
 116 @deftypefn Supplemental char* getcwd (char *@var{pathname}, @var{len})
 117
 118 Copy the absolute pathname for the current working directory into
 119 @var{pathname}, which is assumed to point to a buffer of at least
 120 @var{len} bytes, and return a pointer to the buffer.  If the current
 121 directory's path doesn't fit in @var{len} characters, the result is
 122 NULL and @var{errno} is set.  If @var{pathname} is a null pointer,
 123 @code{getcwd} will obtain @var{len} bytes of space using
 124 @code{malloc}.
 125
 126 @end deftypefn
 127
 128 @c getpagesize.c:5
 129 @deftypefn Supplemental int getpagesize ()
 130
 131 Returns the number of bytes in a page of memory.  This is the
 132 granularity of many of the system memory management routines.  No
 133 guarantee is made as to whether or not it is the same as the basic
 134 memory management hardware page size.
 135
 136 @end deftypefn
 137
 138 @c getpwd.c:5
 139 @deftypefn Supplemental char* getpwd ()
 140
 141 Returns the current working directory.  This implementation caches the
 142 result on the assumption that the process will not call @code{chdir}
 143 between calls to @code{getpwd}.
 144
 145 @end deftypefn
 146
 147 @c index.c:5
 148 @deftypefn Supplemental char* index (char *@var{s}, int @var{c})
 149
 150 Returns a pointer to the first occurance of the character @var{c} in
 151 the string @var{s}, or NULL if not found.  The use of @code{index} is
 152 deprecated in new programs in favor of @code{strchr}.
 153
 154 @end deftypefn
 155
 156 @c memchr.c:3
 157 @deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
 158
 159 This function searches memory starting at @code{*}@var{src} for the
 160 character @var{c}.  The search only ends with the first occurrence of
 161 @var{c}, or after @var{length} characters; in particular, a null
 162 character does not terminate the search.  If the character @var{c} is
 163 found within @var{length} characters of @code{*}@var{src}, a pointer
 164 to the character is returned. If @var{c} is not found, then NULL is
 165 returned.
 166
 167 @end deftypefn
 168
 169 @c memcmp.c:6
 170 @deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
 171
 172 Compares the first @var{count} bytes of two areas of memory.  Returns
 173 zero if they are the same, a value less than zero if @var{x} is
 174 lexically less than @var{y}, or a value greater than zero if @var{x}
 175 is lexically greater than @var{y}.  Note that lexical order is determined
 176 as if comparing unsigned char arrays.
 177
 178 @end deftypefn
 179
 180 @c memcpy.c:6
 181 @deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
 182
 183 Copies @var{length} bytes from memory region @var{in} to region
 184 @var{out}.  Returns a pointer to @var{out}.
 185
 186 @end deftypefn
 187
 188 @c memmove.c:6
 189 @deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
 190
 191 Copies @var{count} bytes from memory area @var{from} to memory area
 192 @var{to}, returning a pointer to @var{to}.
 193
 194 @end deftypefn
 195
 196 @c memset.c:6
 197 @deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
 198
 199 Sets the first @var{count} bytes of @var{s} to the constant byte
 200 @var{c}, returning a pointer to @var{s}.
 201
 202 @end deftypefn
 203
 204 @c putenv.c:21
 205 @deftypefn Supplemental int putenv (const char *@var{string})
 206
 207 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
 208 the environment or remove it.  If @var{string} is of the form
 209 @samp{name=value} the string is added; if no `=' is present the
 210 name is unset/removed.
 211
 212 @end deftypefn
 213
 214 @c rename.c:6
 215 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
 216
 217 Renames a file from @var{old} to @var{new}.  If @var{new} already
 218 exists, it is removed.
 219
 220 @end deftypefn
 221
 222 @c rindex.c:5
 223 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
 224
 225 Returns a pointer to the last occurance of the character @var{c} in
 226 the string @var{s}, or NULL if not found.  The use of @code{rindex} is
 227 deprecated in new programs in favor of @code{strrchr}.
 228
 229 @end deftypefn
 230
 231 @c setenv.c:22
 232 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
 233 @deftypefnx Supplemental void unsetenv (const char *@var{name})
 234
 235 @code{setenv} adds @var{name} to the environment with value
 236 @var{value}.  If the name was already present in the environment,
 237 the new value will be stored only if @var{overwrite} is non-zero.
 238 The companion @code{unsetenv} function removes @var{name} from the
 239 environment.  This implementation is not safe for multithreaded code.
 240
 241 @end deftypefn
 242
 243 @c sigsetmask.c:8
 244 @deftypefn Supplemental int sigsetmask (int @var{set})
 245
 246 Sets the signal mask to the one provided in @var{set} and returns
 247 the old mask (which, for libiberty's implementation, will always
 248 be the value @code{1}).
 249
 250 @end deftypefn
 251
 252 @c strcasecmp.c:15
 253 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
 254
 255 A case-insensitive @code{strcmp}.
 256
 257 @end deftypefn
 258
 259 @c strchr.c:6
 260 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
 261
 262 Returns a pointer to the first occurance of the character @var{c} in
 263 the string @var{s}, or NULL if not found.  If @var{c} is itself the
 264 null character, the results are undefined.
 265
 266 @end deftypefn
 267
 268 @c strdup.c:3
 269 @deftypefn Supplemental char* strdup (const char *@var{s})
 270
 271 Returns a pointer to a copy of @var{s} in memory obtained from
 272 @code{malloc}, or NULL if insufficient memory was available.
 273
 274 @end deftypefn
 275
 276 @c strerror.c:670
 277 @deftypefn Replacement const char* strerrno (int @var{errnum})
 278
 279 Given an error number returned from a system call (typically returned
 280 in @code{errno}), returns a pointer to a string containing the
 281 symbolic name of that error number, as found in @file{errno.h}.
 282
 283 If the supplied error number is within the valid range of indices for
 284 symbolic names, but no name is available for the particular error
 285 number, then returns the string @samp{"Error NUM"}, where NUM is the
 286 error number.
 287
 288 If the supplied error number is not within the range of valid
 289 indices, then returns NULL.
 290
 291 The contents of the location pointed to are only guaranteed to be
 292 valid until the next call to strerrno.
 293
 294 @end deftypefn
 295
 296 @c strerror.c:602
 297 @deftypefn Replacement char* strerror (int @var{errnoval})
 298
 299 Maps an @code{errno} number to an error message string, the contents
 300 of which are implementation defined.  On systems which have the
 301 external variables @code{sys_nerr} and @code{sys_errlist}, these
 302 strings will be the same as the ones used by @code{perror}.
 303
 304 If the supplied error number is within the valid range of indices for
 305 the @code{sys_errlist}, but no message is available for the particular
 306 error number, then returns the string @samp{"Error NUM"}, where NUM is
 307 the error number.
 308
 309 If the supplied error number is not a valid index into
 310 @code{sys_errlist}, returns NULL.
 311
 312 The returned string is only guaranteed to be valid only until the
 313 next call to @code{strerror}.
 314
 315 @end deftypefn
 316
 317 @c strncasecmp.c:15
 318 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
 319
 320 A case-insensitive @code{strncmp}.
 321
 322 @end deftypefn
 323
 324 @c strncmp.c:6
 325 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
 326
 327 Compares the first @var{n} bytes of two strings, returning a value as
 328 @code{strcmp}.
 329
 330 @end deftypefn
 331
 332 @c strrchr.c:6
 333 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
 334
 335 Returns a pointer to the last occurance of the character @var{c} in
 336 the string @var{s}, or NULL if not found.  If @var{c} is itself the
 337 null character, the results are undefined.
 338
 339 @end deftypefn
 340
 341 @c strstr.c:6
 342 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
 343
 344 This function searches for the substring @var{sub} in the string
 345 @var{string}, not including the terminating NUL characters.  A pointer
 346 to the first occurance of @var{sub} is returned, or NULL if the
 347 substring is absent.  If @var{sub} points to a string with zero
 348 length, the function returns @var{string}.
 349
 350 @end deftypefn
 351
 352 @c strtod.c:27
 353 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
 354
 355 This ANSI C function converts the initial portion of @var{string} to a
 356 @code{double}.  If @var{endptr} is not NULL, a pointer to the
 357 character after the last character used in the conversion is stored in
 358 the location referenced by @var{endptr}.  If no conversion is
 359 performed, zero is returned and the value of @var{string} is stored in
 360 the location referenced by @var{endptr}.
 361
 362 @end deftypefn
 363
 364 @c strerror.c:730
 365 @deftypefn Replacement int strtoerrno (const char *@var{name})
 366
 367 Given the symbolic name of a error number (e.g., @code{EACCESS}), map it
 368 to an errno value.  If no translation is found, returns 0.
 369
 370 @end deftypefn
 371
 372 @c strtol.c:33
 373 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
 374
 375 The @code{strtol} function converts the string in @var{string} to a
 376 long integer value according to the given @var{base}, which must be
 377 between 2 and 36 inclusive, or be the special value 0.  If @var{base}
 378 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
 379 to indicate bases 8 and 16, respectively, else default to base 10.
 380 When the base is 16 (either explicitly or implicitly), a prefix of
 381 @code{0x} is allowed.  The handling of endptr is as that of
 382 @code{strtod} above.
 383
 384 @end deftypefn
 385
 386 @c tmpnam.c:3
 387 @deftypefn Supplemental char* tmpnam (char *@var{s})
 388
 389 This function attempts to create a name for a temporary file, which
 390 will be a valid file name yet not exist when @code{tmpnam} checks for
 391 it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
 392 or be NULL.  Use of this function creates a security risk, and it must
 393 not be used in new projects.  Use @code{mkstemp} instead.
 394
 395 @end deftypefn
 396
 397 @c vfork.c:6
 398 @deftypefn Supplemental int vfork ()
 399
 400 Emulates @code{vfork} by calling @code{fork} and returning its value.
 401
 402 @end deftypefn
 403
 404 @c vprintf.c:3
 405 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
 406 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
 407 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
 408
 409 These functions are the same as @code{printf}, @code{fprintf}, and
 410 @code{sprintf}, respectively, except that they are called with a
 411 @code{va_list} instead of a variable number of arguments.  Note that
 412 they do not call @code{va_end}; this is the application's
 413 responsibility.  In @libib{} they are implemented in terms of the
 414 nonstandard but common function @code{_doprnt}.
 415
 416 @end deftypefn
 417
 418 @c waitpid.c:3
 419 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
 420
 421 This is a wrapper around the @code{wait} function.  Any ``special''
 422 values of @var{pid} depend on your implementation of @code{wait}, as
 423 does the return value.  The third argument is unused in @libib{}.
 424
 425 @end deftypefn
 426
 427 @c xatexit.c:11
 428 @deftypefun int xatexit (void (*@var{fn}) (void))
 429
 430 Behaves as the standard @code{atexit} function, but with no limit on
 431 the number of registered funtions.  Returns 0 on success, or -1 on
 432 failure.  If you use @code{xatexit} to register functions, you must use
 433 @code{xexit} to terminate your program.
 434
 435 @end deftypefun
 436
 437 @c xmalloc.c:37
 438 @deftypefn Replacement void* xcalloc (size_t, size_t)
 439
 440 Allocate memory without fail, and set it to zero.  This routine functions
 441 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
 442 cannot be found.
 443
 444 @end deftypefn
 445
 446 @c xexit.c:22
 447 @deftypefn Replacement void xexit (int @var{code})
 448
 449 Terminates the program.  If any functions have been registered with
 450 the @code{xatexit} rpelacement function, they will be called first.
 451 Termination is handled via the system's normal @code{exit} call.
 452
 453 @end deftypefn
 454
 455 @c xmalloc.c:22
 456 @deftypefn Replacement void* xmalloc (size_t)
 457
 458 Allocate memory without fail.  If @code{malloc} fails, this will print
 459 a message to stderr (using the name set by @code{xmalloc_set_program_name},
 460 if any) and then call @code{xexit}.  Note that it is therefore safe for
 461 a program to contain @code{#define malloc xmalloc} in its source.
 462
 463 @end deftypefn
 464
 465 @c xmalloc.c:52
 466 @deftypefn Replacement void xmalloc_failed (size_t)
 467
 468 This function is not meant to be called by client code, and is listed
 469 here for completeness only.  If any of the allocation routines fail, this
 470 function will be called to print an error message and terminate execution.
 471
 472 @end deftypefn
 473
 474 @c xmalloc.c:45
 475 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
 476
 477 You can use this to set the name of the program used by
 478 @code{xmalloc_failed} when printing a failure message.
 479
 480 @end deftypefn
 481
 482 @c xmemdup.c:7
 483 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
 484
 485 Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
 486 are allocated, then @var{copy_size} bytes from @var{input} are copied into
 487 it, and the new memory is returned.  If fewer bytes are copied than were
 488 allocated, the remaining memory is zeroed.
 489
 490 @end deftypefn
 491
 492 @c xmalloc.c:31
 493 @deftypefn Replacement void* xrealloc (void*, size_t)
 494 Reallocate memory without fail.  This routine functions like @code{realloc},
 495 but will behave the same as @code{xmalloc} if memory cannot be found.
 496
 497 @end deftypefn
 498
 499 @c xstrdup.c:7
 500 @deftypefn Replacement char* xstrdup (const char *@var{s})
 501
 502 Duplicates a character string without fail, using @code{xmalloc} to
 503 obtain memory.
 504
 505 @end deftypefn
 506
 507 @c xstrerror.c:7
 508 @deftypefn Replacement char* xstrerror (int @var{errnum})
 509
 510 Behaves exactly like the standard @code{strerror} function, but
 511 will never return a NULL pointer.
 512
 513 @end deftypefn
 514
 515