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