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