include/libiberty.h

   1 /* Function declarations for libiberty.
   2
   3    Copyright 2001, 2002, 2005 Free Software Foundation, Inc.
   4
   5    Note - certain prototypes declared in this header file are for
   6    functions whoes implementation copyright does not belong to the
   7    FSF.  Those prototypes are present in this file for reference
   8    purposes only and their presence in this file should not construed
   9    as an indication of ownership by the FSF of the implementation of
  10    those functions in any way or form whatsoever.
  11
  12    This program is free software; you can redistribute it and/or modify
  13    it under the terms of the GNU General Public License as published by
  14    the Free Software Foundation; either version 2, or (at your option)
  15    any later version.
  16
  17    This program is distributed in the hope that it will be useful,
  18    but WITHOUT ANY WARRANTY; without even the implied warranty of
  19    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20    GNU General Public License for more details.
  21
  22    You should have received a copy of the GNU General Public License
  23    along with this program; if not, write to the Free Software
  24    Foundation, Inc., 59 Temple Place - Suite 330,
  25    Boston, MA 02111-1307, USA.
  26
  27    Written by Cygnus Support, 1994.
  28
  29    The libiberty library provides a number of functions which are
  30    missing on some operating systems.  We do not declare those here,
  31    to avoid conflicts with the system header files on operating
  32    systems that do support those functions.  In this file we only
  33    declare those functions which are specific to libiberty.  */
  34
  35 #ifndef LIBIBERTY_H
  36 #define LIBIBERTY_H
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 #include "ansidecl.h"
  43
  44 /* Get a definition for size_t.  */
  45 #include <stddef.h>
  46 /* Get a definition for va_list.  */
  47 #include <stdarg.h>
  48
  49 #include <stdio.h>
  50
  51 /* If the OS supports it, ensure that the supplied stream is setup to
  52    avoid any multi-threaded locking.  Otherwise leave the FILE pointer
  53    unchanged.  If the stream is NULL do nothing.  */
  54
  55 extern void unlock_stream (FILE *);
  56
  57 /* Open and return a FILE pointer.  If the OS supports it, ensure that
  58    the stream is setup to avoid any multi-threaded locking.  Otherwise
  59    return the FILE pointer unchanged.  */
  60
  61 extern FILE *fopen_unlocked (const char *, const char *);
  62 extern FILE *fdopen_unlocked (int, const char *);
  63 extern FILE *freopen_unlocked (const char *, const char *, FILE *);
  64
  65 /* Build an argument vector from a string.  Allocates memory using
  66    malloc.  Use freeargv to free the vector.  */
  67
  68 extern char **buildargv (const char *) ATTRIBUTE_MALLOC;
  69
  70 /* Free a vector returned by buildargv.  */
  71
  72 extern void freeargv (char **);
  73
  74 /* Duplicate an argument vector. Allocates memory using malloc.  Use
  75    freeargv to free the vector.  */
  76
  77 extern char **dupargv (char **) ATTRIBUTE_MALLOC;
  78
  79
  80 /* Return the last component of a path name.  Note that we can't use a
  81    prototype here because the parameter is declared inconsistently
  82    across different systems, sometimes as "char *" and sometimes as
  83    "const char *" */
  84
  85 /* HAVE_DECL_* is a three-state macro: undefined, 0 or 1.  If it is
  86    undefined, we haven't run the autoconf check so provide the
  87    declaration without arguments.  If it is 0, we checked and failed
  88    to find the declaration so provide a fully prototyped one.  If it
  89    is 1, we found it so don't provide any declaration at all.  */
  90 #if !HAVE_DECL_BASENAME
  91 #if defined (__GNU_LIBRARY__ ) || defined (__linux__) || defined (__FreeBSD__) || defined (__OpenBSD__) || defined(__NetBSD__) || defined (__CYGWIN__) || defined (__CYGWIN32__) || defined (__MINGW32__) || defined (HAVE_DECL_BASENAME)
  92 extern char *basename (const char *);
  93 #else
  94 extern char *basename ();
  95 #endif
  96 #endif
  97
  98 /* A well-defined basename () that is always compiled in.  */
  99
 100 extern const char *lbasename (const char *);
 101
 102 /* A well-defined realpath () that is always compiled in.  */
 103
 104 extern char *lrealpath (const char *);
 105
 106 /* Concatenate an arbitrary number of strings.  You must pass NULL as
 107    the last argument of this function, to terminate the list of
 108    strings.  Allocates memory using xmalloc.  */
 109
 110 extern char *concat (const char *, ...) ATTRIBUTE_MALLOC ATTRIBUTE_SENTINEL;
 111
 112 /* Concatenate an arbitrary number of strings.  You must pass NULL as
 113    the last argument of this function, to terminate the list of
 114    strings.  Allocates memory using xmalloc.  The first argument is
 115    not one of the strings to be concatenated, but if not NULL is a
 116    pointer to be freed after the new string is created, similar to the
 117    way xrealloc works.  */
 118
 119 extern char *reconcat (char *, const char *, ...) ATTRIBUTE_MALLOC ATTRIBUTE_SENTINEL;
 120
 121 /* Determine the length of concatenating an arbitrary number of
 122    strings.  You must pass NULL as the last argument of this function,
 123    to terminate the list of strings.  */
 124
 125 extern unsigned long concat_length (const char *, ...) ATTRIBUTE_SENTINEL;
 126
 127 /* Concatenate an arbitrary number of strings into a SUPPLIED area of
 128    memory.  You must pass NULL as the last argument of this function,
 129    to terminate the list of strings.  The supplied memory is assumed
 130    to be large enough.  */
 131
 132 extern char *concat_copy (char *, const char *, ...) ATTRIBUTE_SENTINEL;
 133
 134 /* Concatenate an arbitrary number of strings into a GLOBAL area of
 135    memory.  You must pass NULL as the last argument of this function,
 136    to terminate the list of strings.  The supplied memory is assumed
 137    to be large enough.  */
 138
 139 extern char *concat_copy2 (const char *, ...) ATTRIBUTE_SENTINEL;
 140
 141 /* This is the global area used by concat_copy2.  */
 142
 143 extern char *libiberty_concat_ptr;
 144
 145 /* Concatenate an arbitrary number of strings.  You must pass NULL as
 146    the last argument of this function, to terminate the list of
 147    strings.  Allocates memory using alloca.  The arguments are
 148    evaluated twice!  */
 149 #define ACONCAT(ACONCAT_PARAMS) \
 150   (libiberty_concat_ptr = alloca (concat_length ACONCAT_PARAMS + 1), \
 151    concat_copy2 ACONCAT_PARAMS)
 152
 153 /* Check whether two file descriptors refer to the same file.  */
 154
 155 extern int fdmatch (int fd1, int fd2);
 156
 157 /* Return the position of the first bit set in the argument.  */
 158 /* Prototypes vary from system to system, so we only provide a
 159    prototype on systems where we know that we need it.  */
 160 #if defined (HAVE_DECL_FFS) && !HAVE_DECL_FFS
 161 extern int ffs(int);
 162 #endif
 163
 164 /* Get the working directory.  The result is cached, so don't call
 165    chdir() between calls to getpwd().  */
 166
 167 extern char * getpwd (void);
 168
 169 /* Get the current time.  */
 170 /* Prototypes vary from system to system, so we only provide a
 171    prototype on systems where we know that we need it.  */
 172 #ifdef __MINGW32__
 173 /* Forward declaration to avoid #include <sys/time.h>.   */
 174 struct timeval;
 175 extern int gettimeofday (struct timeval *, void *);
 176 #endif
 177
 178 /* Get the amount of time the process has run, in microseconds.  */
 179
 180 extern long get_run_time (void);
 181
 182 /* Generate a relocated path to some installation directory.  Allocates
 183    return value using malloc.  */
 184
 185 extern char *make_relative_prefix (const char *, const char *,
 186                                    const char *) ATTRIBUTE_MALLOC;
 187
 188 /* Choose a temporary directory to use for scratch files.  */
 189
 190 extern char *choose_temp_base (void) ATTRIBUTE_MALLOC;
 191
 192 /* Return a temporary file name or NULL if unable to create one.  */
 193
 194 extern char *make_temp_file (const char *) ATTRIBUTE_MALLOC;
 195
 196 /* Remove a link to a file unless it is special. */
 197
 198 extern int unlink_if_ordinary (const char *);
 199
 200 /* Allocate memory filled with spaces.  Allocates using malloc.  */
 201
 202 extern const char *spaces (int count);
 203
 204 /* Return the maximum error number for which strerror will return a
 205    string.  */
 206
 207 extern int errno_max (void);
 208
 209 /* Return the name of an errno value (e.g., strerrno (EINVAL) returns
 210    "EINVAL").  */
 211
 212 extern const char *strerrno (int);
 213
 214 /* Given the name of an errno value, return the value.  */
 215
 216 extern int strtoerrno (const char *);
 217
 218 /* ANSI's strerror(), but more robust.  */
 219
 220 extern char *xstrerror (int);
 221
 222 /* Return the maximum signal number for which strsignal will return a
 223    string.  */
 224
 225 extern int signo_max (void);
 226
 227 /* Return a signal message string for a signal number
 228    (e.g., strsignal (SIGHUP) returns something like "Hangup").  */
 229 /* This is commented out as it can conflict with one in system headers.
 230    We still document its existence though.  */
 231
 232 /*extern const char *strsignal (int);*/
 233
 234 /* Return the name of a signal number (e.g., strsigno (SIGHUP) returns
 235    "SIGHUP").  */
 236
 237 extern const char *strsigno (int);
 238
 239 /* Given the name of a signal, return its number.  */
 240
 241 extern int strtosigno (const char *);
 242
 243 /* Register a function to be run by xexit.  Returns 0 on success.  */
 244
 245 extern int xatexit (void (*fn) (void));
 246
 247 /* Exit, calling all the functions registered with xatexit.  */
 248
 249 extern void xexit (int status) ATTRIBUTE_NORETURN;
 250
 251 /* Set the program name used by xmalloc.  */
 252
 253 extern void xmalloc_set_program_name (const char *);
 254
 255 /* Report an allocation failure.  */
 256 extern void xmalloc_failed (size_t) ATTRIBUTE_NORETURN;
 257
 258 /* Allocate memory without fail.  If malloc fails, this will print a
 259    message to stderr (using the name set by xmalloc_set_program_name,
 260    if any) and then call xexit.  */
 261
 262 extern void *xmalloc (size_t) ATTRIBUTE_MALLOC;
 263
 264 /* Reallocate memory without fail.  This works like xmalloc.  Note,
 265    realloc type functions are not suitable for attribute malloc since
 266    they may return the same address across multiple calls. */
 267
 268 extern void *xrealloc (void *, size_t);
 269
 270 /* Allocate memory without fail and set it to zero.  This works like
 271    xmalloc.  */
 272
 273 extern void *xcalloc (size_t, size_t) ATTRIBUTE_MALLOC;
 274
 275 /* Copy a string into a memory buffer without fail.  */
 276
 277 extern char *xstrdup (const char *) ATTRIBUTE_MALLOC;
 278
 279 /* Copy at most N characters from string into a buffer without fail.  */
 280
 281 extern char *xstrndup (const char *, size_t) ATTRIBUTE_MALLOC;
 282
 283 /* Copy an existing memory buffer to a new memory buffer without fail.  */
 284
 285 extern void *xmemdup (const void *, size_t, size_t) ATTRIBUTE_MALLOC;
 286
 287 /* Physical memory routines.  Return values are in BYTES.  */
 288 extern double physmem_total (void);
 289 extern double physmem_available (void);
 290
 291
 292 /* These macros provide a K&R/C89/C++-friendly way of allocating structures
 293    with nice encapsulation.  The XDELETE*() macros are technically
 294    superfluous, but provided here for symmetry.  Using them consistently
 295    makes it easier to update client code to use different allocators such
 296    as new/delete and new[]/delete[].  */
 297
 298 /* Scalar allocators.  */
 299
 300 #define XNEW(T)                 ((T *) xmalloc (sizeof (T)))
 301 #define XCNEW(T)                ((T *) xcalloc (1, sizeof (T)))
 302 #define XDELETE(P)              free ((void*) (P))
 303
 304 /* Array allocators.  */
 305
 306 #define XNEWVEC(T, N)           ((T *) xmalloc (sizeof (T) * (N)))
 307 #define XCNEWVEC(T, N)          ((T *) xcalloc ((N), sizeof (T)))
 308 #define XRESIZEVEC(T, P, N)     ((T *) xrealloc ((void *) (P), sizeof (T) * (N)))
 309 #define XDELETEVEC(P)           free ((void*) (P))
 310
 311 /* Allocators for variable-sized structures and raw buffers.  */
 312
 313 #define XNEWVAR(T, S)           ((T *) xmalloc ((S)))
 314 #define XCNEWVAR(T, S)          ((T *) xcalloc (1, (S)))
 315 #define XRESIZEVAR(T, P, S)     ((T *) xrealloc ((P), (S)))
 316
 317 /* Type-safe obstack allocator.  */
 318
 319 #define XOBNEW(O, T)            ((T *) obstack_alloc ((O), sizeof (T)))
 320
 321
 322 /* hex character manipulation routines */
 323
 324 #define _hex_array_size 256
 325 #define _hex_bad        99
 326 extern const unsigned char _hex_value[_hex_array_size];
 327 extern void hex_init (void);
 328 #define hex_p(c)        (hex_value (c) != _hex_bad)
 329 /* If you change this, note well: Some code relies on side effects in
 330    the argument being performed exactly once.  */
 331 #define hex_value(c)    ((unsigned int) _hex_value[(unsigned char) (c)])
 332
 333 /* Flags for pex_init.  These are bits to be or'ed together.  */
 334
 335 /* Record subprocess times, if possible.  */
 336 #define PEX_RECORD_TIMES        0x1
 337
 338 /* Use pipes for communication between processes, if possible.  */
 339 #define PEX_USE_PIPES           0x2
 340
 341 /* Save files used for communication between processes.  */
 342 #define PEX_SAVE_TEMPS          0x4
 343
 344 /* Prepare to execute one or more programs, with standard output of
 345    each program fed to standard input of the next.
 346    FLAGS        As above.
 347    PNAME        The name of the program to report in error messages.
 348    TEMPBASE     A base name to use for temporary files; may be NULL to
 349                 use a random name.
 350    Returns NULL on error.  */
 351
 352 extern struct pex_obj *pex_init (int flags, const char *pname,
 353                                  const char *tempbase);
 354
 355 /* Flags for pex_run.  These are bits to be or'ed together.  */
 356
 357 /* Last program in pipeline.  Standard output of program goes to
 358    OUTNAME, or, if OUTNAME is NULL, to standard output of caller.  Do
 359    not set this if you want to call pex_read_output.  After this is
 360    set, pex_run may no longer be called with the same struct
 361    pex_obj.  */
 362 #define PEX_LAST                0x1
 363
 364 /* Search for program in executable search path.  */
 365 #define PEX_SEARCH              0x2
 366
 367 /* OUTNAME is a suffix.  */
 368 #define PEX_SUFFIX              0x4
 369
 370 /* Send program's standard error to standard output.  */
 371 #define PEX_STDERR_TO_STDOUT    0x8
 372
 373 /* Input file should be opened in binary mode.  This flag is ignored
 374    on Unix.  */
 375 #define PEX_BINARY_INPUT        0x10
 376
 377 /* Output file should be opened in binary mode.  This flag is ignored
 378    on Unix.  For proper behaviour PEX_BINARY_INPUT and
 379    PEX_BINARY_OUTPUT have to match appropriately--i.e., a call using
 380    PEX_BINARY_OUTPUT should be followed by a call using
 381    PEX_BINARY_INPUT.  */
 382 #define PEX_BINARY_OUTPUT       0x20
 383
 384 /* Execute one program.  Returns NULL on success.  On error returns an
 385    error string (typically just the name of a system call); the error
 386    string is statically allocated.
 387
 388    OBJ          Returned by pex_init.
 389
 390    FLAGS        As above.
 391
 392    EXECUTABLE   The program to execute.
 393
 394    ARGV         NULL terminated array of arguments to pass to the program.
 395
 396    OUTNAME      Sets the output file name as follows:
 397
 398                 PEX_SUFFIX set (OUTNAME may not be NULL):
 399                   TEMPBASE parameter to pex_init not NULL:
 400                     Output file name is the concatenation of TEMPBASE
 401                     and OUTNAME.
 402                   TEMPBASE is NULL:
 403                     Output file name is a random file name ending in
 404                     OUTNAME.
 405                 PEX_SUFFIX not set:
 406                   OUTNAME not NULL:
 407                     Output file name is OUTNAME.
 408                   OUTNAME NULL, TEMPBASE not NULL:
 409                     Output file name is randomly chosen using
 410                     TEMPBASE.
 411                   OUTNAME NULL, TEMPBASE NULL:
 412                     Output file name is randomly chosen.
 413
 414                 If PEX_LAST is not set, the output file name is the
 415                 name to use for a temporary file holding stdout, if
 416                 any (there will not be a file if PEX_USE_PIPES is set
 417                 and the system supports pipes).  If a file is used, it
 418                 will be removed when no longer needed unless
 419                 PEX_SAVE_TEMPS is set.
 420
 421                 If PEX_LAST is set, and OUTNAME is not NULL, standard
 422                 output is written to the output file name.  The file
 423                 will not be removed.  If PEX_LAST and PEX_SUFFIX are
 424                 both set, TEMPBASE may not be NULL.
 425
 426    ERRNAME      If not NULL, this is the name of a file to which
 427                 standard error is written.  If NULL, standard error of
 428                 the program is standard error of the caller.
 429
 430    ERR          On an error return, *ERR is set to an errno value, or
 431                 to 0 if there is no relevant errno.
 432 */
 433
 434 extern const char *pex_run (struct pex_obj *obj, int flags,
 435                             const char *executable, char * const *argv,
 436                             const char *outname, const char *errname,
 437                             int *err);
 438
 439 /* Read the standard output of the last program to be executed.
 440    pex_run can not be called after this.  BINARY should be non-zero if
 441    the file should be opened in binary mode; this is ignored on Unix.
 442    Returns NULL on error.  Don't call fclose on the returned FILE; it
 443    will be closed by pex_free.  */
 444
 445 extern FILE *pex_read_output (struct pex_obj *, int binary);
 446
 447 /* Return exit status of all programs in VECTOR.  COUNT indicates the
 448    size of VECTOR.  The status codes in the vector are in the order of
 449    the calls to pex_run.  Returns 0 on error, 1 on success.  */
 450
 451 extern int pex_get_status (struct pex_obj *, int count, int *vector);
 452
 453 /* Return times of all programs in VECTOR.  COUNT indicates the size
 454    of VECTOR.  struct pex_time is really just struct timeval, but that
 455    is not portable to all systems.  Returns 0 on error, 1 on
 456    success.  */
 457
 458 struct pex_time
 459 {
 460   unsigned long user_seconds;
 461   unsigned long user_microseconds;
 462   unsigned long system_seconds;
 463   unsigned long system_microseconds;
 464 };
 465
 466 extern int pex_get_times (struct pex_obj *, int count,
 467                           struct pex_time *vector);
 468
 469 /* Clean up a pex_obj.  */
 470
 471 extern void pex_free (struct pex_obj *);
 472
 473 /* Just execute one program.  Return value is as for pex_run.
 474    FLAGS        Combination of PEX_SEARCH and PEX_STDERR_TO_STDOUT.
 475    EXECUTABLE   As for pex_run.
 476    ARGV         As for pex_run.
 477    PNAME        As for pex_init.
 478    OUTNAME      As for pex_run when PEX_LAST is set.
 479    ERRNAME      As for pex_run.
 480    STATUS       Set to exit status on success.
 481    ERR          As for pex_run.
 482 */
 483
 484 extern const char *pex_one (int flags, const char *executable,
 485                             char * const *argv, const char *pname,
 486                             const char *outname, const char *errname,
 487                             int *status, int *err);
 488
 489 /* pexecute and pwait are the old pexecute interface, still here for
 490    backward compatibility.  Don't use these for new code.  Instead,
 491    use pex_init/pex_run/pex_get_status/pex_free, or pex_one.  */
 492
 493 /* Definitions used by the pexecute routine.  */
 494
 495 #define PEXECUTE_FIRST   1
 496 #define PEXECUTE_LAST    2
 497 #define PEXECUTE_ONE     (PEXECUTE_FIRST + PEXECUTE_LAST)
 498 #define PEXECUTE_SEARCH  4
 499 #define PEXECUTE_VERBOSE 8
 500
 501 /* Execute a program.  */
 502
 503 extern int pexecute (const char *, char * const *, const char *,
 504                      const char *, char **, char **, int);
 505
 506 /* Wait for pexecute to finish.  */
 507
 508 extern int pwait (int, int *, int);
 509
 510 #if !HAVE_DECL_ASPRINTF
 511 /* Like sprintf but provides a pointer to malloc'd storage, which must
 512    be freed by the caller.  */
 513
 514 extern int asprintf (char **, const char *, ...) ATTRIBUTE_PRINTF_2;
 515 #endif
 516
 517 #if !HAVE_DECL_VASPRINTF
 518 /* Like vsprintf but provides a pointer to malloc'd storage, which
 519    must be freed by the caller.  */
 520
 521 extern int vasprintf (char **, const char *, va_list)
 522   ATTRIBUTE_PRINTF(2,0);
 523 #endif
 524
 525 #define ARRAY_SIZE(a) (sizeof (a) / sizeof ((a)[0]))
 526
 527 /* Drastically simplified alloca configurator.  If we're using GCC,
 528    we use __builtin_alloca; otherwise we use the C alloca.  The C
 529    alloca is always available.  You can override GCC by defining
 530    USE_C_ALLOCA yourself.  The canonical autoconf macro C_ALLOCA is
 531    also set/unset as it is often used to indicate whether code needs
 532    to call alloca(0).  */
 533 extern void *C_alloca (size_t) ATTRIBUTE_MALLOC;
 534 #undef alloca
 535 #if GCC_VERSION >= 2000 && !defined USE_C_ALLOCA
 536 # define alloca(x) __builtin_alloca(x)
 537 # undef C_ALLOCA
 538 # define ASTRDUP(X) \
 539   (__extension__ ({ const char *const libiberty_optr = (X); \
 540    const unsigned long libiberty_len = strlen (libiberty_optr) + 1; \
 541    char *const libiberty_nptr = (char *const) alloca (libiberty_len); \
 542    (char *) memcpy (libiberty_nptr, libiberty_optr, libiberty_len); }))
 543 #else
 544 # define alloca(x) C_alloca(x)
 545 # undef USE_C_ALLOCA
 546 # define USE_C_ALLOCA 1
 547 # undef C_ALLOCA
 548 # define C_ALLOCA 1
 549 extern const char *libiberty_optr;
 550 extern char *libiberty_nptr;
 551 extern unsigned long libiberty_len;
 552 # define ASTRDUP(X) \
 553   (libiberty_optr = (X), \
 554    libiberty_len = strlen (libiberty_optr) + 1, \
 555    libiberty_nptr = (char *) alloca (libiberty_len), \
 556    (char *) memcpy (libiberty_nptr, libiberty_optr, libiberty_len))
 557 #endif
 558
 559 #ifdef __cplusplus
 560 }
 561 #endif
 562
 563
 564 #endif /* ! defined (LIBIBERTY_H) */