@c Edit the *.c files, configure with --enable-maintainer-mode,
@c and let gather-docs build you a new copy.
+@c safe-ctype.c:24
+@defvr Extension HOST_CHARSET
+This macro indicates the basic character set and encoding used by the
+host: more precisely, the encoding used for character constants in
+preprocessor @samp{#if} statements (the C "execution character set").
+It is defined by @file{safe-ctype.h}, and will be an integer constant
+with one of the following values:
+
+@ftable @code
+@item HOST_CHARSET_UNKNOWN
+The host character set is unknown - that is, not one of the next two
+possibilities.
+
+@item HOST_CHARSET_ASCII
+The host character set is ASCII.
+
+@item HOST_CHARSET_EBCDIC
+The host character set is some variant of EBCDIC. (Only one of the
+nineteen EBCDIC varying characters is tested; exercise caution.)
+@end ftable
+@end defvr
+
@c alloca.c:26
@deftypefn Replacement void* alloca (size_t @var{size})
@end deftypefn
@c asprintf.c:33
-@deftypefn Extension int asprintf (char **@var{resptr}, char *@var{format}, ...)
+@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
Like @code{sprintf}, but instead of passing a pointer to a buffer, you
pass a pointer to a pointer. This function will compute the size of
the buffer needed, allocate memory with @code{malloc}, and store a
pointer to the allocated memory in @code{*@var{resptr}}. The value
returned is the same as @code{sprintf} would return. If memory could
-not be allocated, zero is returned and @code{NULL} is stored in
+not be allocated, minus one is returned and @code{NULL} is stored in
@code{*@var{resptr}}.
@end deftypefn
system with the single function call @code{freeargv}, which takes the
returned result of @code{buildargv}, as it's argument.
-Returns a pointer to the argument vector if successful. Returns
+Returns a pointer to the argument vector if successful. Returns
@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
memory to complete building the argument vector.
@end deftypefn
@c choose-temp.c:42
-@deftypefn Extension char* choose_temp_base ()
+@deftypefn Extension char* choose_temp_base (void)
Return a prefix for temporary file names or @code{NULL} if unable to
find one. The current directory is chosen if all else fails so the
@end deftypefn
@c concat.c:24
-@deftypefn Extension char* concat (char *@var{s1}, char *@var{s2}, ..., @code{NULL})
+@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
Concatenate zero or more of strings and return the result in freshly
-xmalloc'd memory. Returns @code{NULL} if insufficient memory is
+@code{xmalloc}ed memory. Returns @code{NULL} if insufficient memory is
available. The argument list is terminated by the first @code{NULL}
pointer encountered. Pointers to empty strings are ignored.
Duplicate an argument vector. Simply scans through @var{vector},
duplicating each argument until the terminating @code{NULL} is found.
-Returns a pointer to the argument vector if successful. Returns
+Returns a pointer to the argument vector if successful. Returns
@code{NULL} if there is insufficient memory to complete building the
argument vector.
@c ffs.c:3
@deftypefn Supplemental int ffs (int @var{valu})
-Find the first (least significant) bit set in @var{valu}. Bits are
+Find the first (least significant) bit set in @var{valu}. Bits are
numbered from right to left, starting with bit 1 (corresponding to the
value 1). If @var{valu} is zero, zero is returned.
zero or more characters, or a set of alternate characters in square
brackets, like @samp{[a-gt8]}, which match one character (@code{a}
through @code{g}, or @code{t}, or @code{8}, in this example) if that one
-character is in the set. A set may be inverted (i.e. match anything
+character is in the set. A set may be inverted (i.e., match anything
except what's in the set) by giving @code{^} or @code{!} as the first
character in the set. To include those characters in the set, list them
as anything other than the first character of the set. To include a
@code{flags} controls various aspects of the matching process, and is a
boolean OR of zero or more of the following values (defined in
-@code{<fnmatch.h>}:
+@code{<fnmatch.h>}):
@table @code
@end deftypefn
-@c getruntime.c:78
-@deftypefn Replacement long get_run_time ()
+@c getruntime.c:82
+@deftypefn Replacement long get_run_time (void)
Returns the time used so far, in microseconds. If possible, this is
the time used by this process, else it is the elapsed time since the
@end deftypefn
+@c hex.c:30
+@deftypefn Extension void hex_init (void)
+
+Initializes the array mapping the current character set to
+corresponding hex values. This function must be called before any
+call to @code{hex_p} or @code{hex_value}. If you fail to call it, a
+default ASCII-based table will normally be used on ASCII systems.
+
+@end deftypefn
+
+@c hex.c:39
+@deftypefn Extension int hex_p (int @var{c})
+
+Evaluates to non-zero if the given character is a valid hex character,
+or zero if it is not. Note that the value you pass will be cast to
+@code{unsigned char} within the macro.
+
+@end deftypefn
+
+@c hex.c:47
+@deftypefn Extension unsigned int hex_value (int @var{c})
+
+Returns the numeric equivalent of the given character when interpreted
+as a hexidecimal digit. The result is undefined if you pass an
+invalid hex digit. Note that the value you pass will be cast to
+@code{unsigned char} within the macro.
+
+The @code{hex_value} macro returns @code{unsigned int}, rather than
+signed @code{int}, to make it easier to use in parsing addresses from
+hex dump files: a signed @code{int} would be sign-extended when
+converted to a wider unsigned type --- like @code{bfd_vma}, on some
+systems.
+
+@end deftypefn
+
@c index.c:5
@deftypefn Supplemental char* index (char *@var{s}, int @var{c})
@end deftypefn
+@c safe-ctype.c:45
+@deffn Extension ISALPHA (@var{c})
+@deffnx Extension ISALNUM (@var{c})
+@deffnx Extension ISBLANK (@var{c})
+@deffnx Extension ISCNTRL (@var{c})
+@deffnx Extension ISDIGIT (@var{c})
+@deffnx Extension ISGRAPH (@var{c})
+@deffnx Extension ISLOWER (@var{c})
+@deffnx Extension ISPRINT (@var{c})
+@deffnx Extension ISPUNCT (@var{c})
+@deffnx Extension ISSPACE (@var{c})
+@deffnx Extension ISUPPER (@var{c})
+@deffnx Extension ISXDIGIT (@var{c})
+
+These twelve macros are defined by @file{safe-ctype.h}. Each has the
+same meaning as the corresponding macro (with name in lowercase)
+defined by the standard header @file{ctype.h}. For example,
+@code{ISALPHA} returns true for alphabetic characters and false for
+others. However, there are two differences between these macros and
+those provided by @file{ctype.h}:
+
+@itemize @bullet
+@item These macros are guaranteed to have well-defined behavior for all
+values representable by @code{signed char} and @code{unsigned char}, and
+for @code{EOF}.
+
+@item These macros ignore the current locale; they are true for these
+fixed sets of characters:
+@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
+@item @code{ALPHA} @tab @kbd{A-Za-z}
+@item @code{ALNUM} @tab @kbd{A-Za-z0-9}
+@item @code{BLANK} @tab @kbd{space tab}
+@item @code{CNTRL} @tab @code{!PRINT}
+@item @code{DIGIT} @tab @kbd{0-9}
+@item @code{GRAPH} @tab @code{ALNUM || PUNCT}
+@item @code{LOWER} @tab @kbd{a-z}
+@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space}
+@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
+@item @code{SPACE} @tab @kbd{space tab \n \r \f \v}
+@item @code{UPPER} @tab @kbd{A-Z}
+@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
+@end multitable
+
+Note that, if the host character set is ASCII or a superset thereof,
+all these macros will return false for all values of @code{char} outside
+the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return
+false for characters with numeric values from 128 to 255.
+@end itemize
+@end deffn
+
+@c safe-ctype.c:94
+@deffn Extension ISIDNUM (@var{c})
+@deffnx Extension ISIDST (@var{c})
+@deffnx Extension IS_VSPACE (@var{c})
+@deffnx Extension IS_NVSPACE (@var{c})
+@deffnx Extension IS_SPACE_OR_NUL (@var{c})
+@deffnx Extension IS_ISOBASIC (@var{c})
+These six macros are defined by @file{safe-ctype.h} and provide
+additional character classes which are useful when doing lexical
+analysis of C or similar languages. They are true for the following
+sets of characters:
+
+@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
+@item @code{IDNUM} @tab @kbd{A-Za-z0-9_}
+@item @code{IDST} @tab @kbd{A-Za-z_}
+@item @code{VSPACE} @tab @kbd{\r \n}
+@item @code{NVSPACE} @tab @kbd{space tab \f \v \0}
+@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
+@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT}
+@end multitable
+@end deffn
+
@c lbasename.c:23
@deftypefn Replacement {const char*} lbasename (const char *@var{name})
@end deftypefn
+@c lrealpath.c:25
+@deftypefn Replacement {const char*} lrealpath (const char *@var{name})
+
+Given a pointer to a string containing a pathname, returns a canonical
+version of the filename. Symlinks will be resolved, and ``.'' and ``..''
+components will be simplified. The returned value will be allocated using
+@code{malloc}, or @code{NULL} will be returned on a memory allocation error.
+
+@end deftypefn
+
+@c make-relative-prefix.c:24
+@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
+
+Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
+return the path that is in the same position relative to
+@var{progname}'s directory as @var{prefix} is relative to
+@var{bin_prefix}. That is, a string starting with the directory
+portion of @var{progname}, followed by a relative pathname of the
+difference between @var{bin_prefix} and @var{prefix}.
+
+If @var{progname} does not contain any directory separators,
+@code{make_relative_prefix} will search @env{PATH} to find a program
+named @var{progname}. Also, if @var{progname} is a symbolic link,
+the symbolic link will be resolved.
+
+For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
+@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
+@code{/red/green/blue/gcc}, then this function will return
+@code{/red/green/blue/../../omega/}.
+
+The return value is normally allocated via @code{malloc}. If no
+relative prefix can be found, return @code{NULL}.
+
+@end deftypefn
+
@c make-temp-file.c:138
@deftypefn Replacement char* make_temp_file (const char *@var{suffix})
Return a temporary file name (as a string) or @code{NULL} if unable to
create one. @var{suffix} is a suffix to append to the file name. The
-string is malloced, and the temporary file has been created.
+string is @code{malloc}ed, and the temporary file has been created.
@end deftypefn
@end deftypefn
+@c mempcpy.c:23
+@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
+
+Copies @var{length} bytes from memory region @var{in} to region
+@var{out}. Returns a pointer to @var{out} + @var{length}.
+
+@end deftypefn
+
@c memset.c:6
@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
@var{template} has the form:
@example
- <path>/ccXXXXXX<suffix>
+ @var{path}/ccXXXXXX@var{suffix}
@end example
-@var{suffix_len} tells us how long <suffix> is (it can be zero
-length). The last six characters of @var{template} before <suffix>
-must be @code{XXXXXX}; they are replaced with a string that makes the
+@var{suffix_len} tells us how long @var{suffix} is (it can be zero
+length). The last six characters of @var{template} before @var{suffix}
+must be @samp{XXXXXX}; they are replaced with a string that makes the
filename unique. Returns a file descriptor open on the file for
reading and writing.
@end deftypefn
-@c pexecute.c:67
+@c pexecute.txh:1
@deftypefn Extension int pexecute (const char *@var{program}, char * const *@var{argv}, const char *@var{this_pname}, const char *@var{temp_base}, char **@var{errmsg_fmt}, char **@var{errmsg_arg}, int flags)
Executes a program.
@var{program} and @var{argv} are the arguments to
@code{execv}/@code{execvp}.
-@var{this_pname} is name of the calling program (i.e. @code{argv[0]}).
+@var{this_pname} is name of the calling program (i.e., @code{argv[0]}).
@var{temp_base} is the path name, sans suffix, of a temporary file to
use if needed. This is currently only needed for MS-DOS ports that
don't use @code{go32} (do any still exist?). Ports that don't need it
can pass @code{NULL}.
-(@var{flags} & @code{PEXECUTE_SEARCH}) is non-zero if @code{$PATH} should be searched
-(??? It's not clear that GCC passes this flag correctly). (@var{flags} &
-@code{PEXECUTE_FIRST}) is nonzero for the first process in chain.
-(@var{flags} & @code{PEXECUTE_FIRST}) is nonzero for the last process
-in chain. The first/last flags could be simplified to only mark the
-last of a chain of processes but that requires the caller to always
-mark the last one (and not give up early if some error occurs).
-It's more robust to require the caller to mark both ends of the chain.
+(@code{@var{flags} & PEXECUTE_SEARCH}) is non-zero if @env{PATH}
+should be searched (??? It's not clear that GCC passes this flag
+correctly). (@code{@var{flags} & PEXECUTE_FIRST}) is nonzero for the
+first process in chain. (@code{@var{flags} & PEXECUTE_FIRST}) is
+nonzero for the last process in chain. The first/last flags could be
+simplified to only mark the last of a chain of processes but that
+requires the caller to always mark the last one (and not give up
+early if some error occurs). It's more robust to require the caller
+to mark both ends of the chain.
The result is the pid on systems like Unix where we
@code{fork}/@code{exec} and on systems like WIN32 and OS/2 where we
use @code{spawn}. It is up to the caller to wait for the child.
-The result is the WEXITSTATUS on systems like MS-DOS where we
+The result is the @code{WEXITSTATUS} on systems like MS-DOS where we
@code{spawn} and wait for the child here.
Upon failure, @var{errmsg_fmt} and @var{errmsg_arg} are set to the
text of the error message with an optional argument (if not needed,
-@var{errmsg_arg} is set to @code{NULL}), and -1 is returned.
+@var{errmsg_arg} is set to @code{NULL}), and @minus{}1 is returned.
@code{errno} is available to the caller to use.
@end deftypefn
@end deftypefn
-@c pexecute.c:104
+@c pexecute.txh:39
@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
Waits for a program started by @code{pexecute} to finish.
@var{pid} is the process id of the task to wait for. @var{status} is
-the `status' argument to wait. @var{flags} is currently unused (allows
-future enhancement without breaking upward compatibility). Pass 0 for now.
+the `status' argument to wait. @var{flags} is currently unused
+(allows future enhancement without breaking upward compatibility).
+Pass 0 for now.
The result is the pid of the child reaped, or -1 for failure
(@code{errno} says why).
-On systems that don't support waiting for a particular child, @var{pid} is
-ignored. On systems like MS-DOS that don't really multitask @code{pwait}
-is just a mechanism to provide a consistent interface for the caller.
+On systems that don't support waiting for a particular child,
+@var{pid} is ignored. On systems like MS-DOS that don't really
+multitask @code{pwait} is just a mechanism to provide a consistent
+interface for the caller.
@end deftypefn
@c random.c:39
-@deftypefn Supplement {long int} random ()
+@deftypefn Supplement {long int} random (void)
@deftypefnx Supplement void srandom (unsigned int @var{seed})
@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
@deftypefnx Supplement void* setstate (void *@var{arg_state})
Random number functions. @code{random} returns a random number in the
-range @code{0..LONG_MAX}. @code{srandom} initializes the random
+range 0 to @code{LONG_MAX}. @code{srandom} initializes the random
number generator to some starting point determined by @var{seed}
(else, the values returned by @code{random} are always the same for each
-run of the program). @code{initstate} and @code{setstate} allow fine-grain
+run of the program). @code{initstate} and @code{setstate} allow fine-grained
control over the state of the random number generator.
@end deftypefn
@c concat.c:177
-@deftypefn Extension char* reconcat (char *@var{optr}, char *@var{s1}, ..., @code{NULL})
+@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
is freed after the string is created. This is intended to be useful
@end deftypefn
@c strsignal.c:353
-@deftypefn Extension int signo_max ()
+@deftypefn Extension int signo_max (void)
Returns the maximum signal value for which a corresponding symbolic
name or message is available. Note that in the case where we use the
@end deftypefn
+@c snprintf.c:28
+@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
+
+This function is similar to sprintf, but it will print at most @var{n}
+characters. On error the return value is -1, otherwise it returns the
+number of characters that would have been printed had @var{n} been
+sufficiently large, regardless of the actual value of @var{n}. Note
+some pre-C99 system libraries do not implement this correctly so users
+cannot generally rely on the return value if the system version of
+this function is used.
+
+@end deftypefn
+
@c spaces.c:22
@deftypefn Extension char* spaces (int @var{count})
@end deftypefn
+@c stpcpy.c:23
+@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
+
+Copies the string @var{src} into @var{dst}. Returns a pointer to
+@var{dst} + strlen(@var{src}).
+
+@end deftypefn
+
+@c stpncpy.c:23
+@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
+
+Copies the string @var{src} into @var{dst}, copying exactly @var{len}
+and padding with zeros if necessary. If @var{len} < strlen(@var{src})
+then return @var{dst} + @var{len}, otherwise returns @var{dst} +
+strlen(@var{src}).
+
+@end deftypefn
+
@c strcasecmp.c:15
@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
@end deftypefn
@c vasprintf.c:48
-@deftypefn Extension int vasprintf (char **@var{resptr}, char *@var{format}, va_list @var{args})
+@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
Like @code{vsprintf}, but instead of passing a pointer to a buffer,
you pass a pointer to a pointer. This function will compute the size
of the buffer needed, allocate memory with @code{malloc}, and store a
pointer to the allocated memory in @code{*@var{resptr}}. The value
returned is the same as @code{vsprintf} would return. If memory could
-not be allocated, zero is returned and @code{NULL} is stored in
+not be allocated, minus one is returned and @code{NULL} is stored in
@code{*@var{resptr}}.
@end deftypefn
@end deftypefn
+@c vsnprintf.c:28
+@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
+
+This function is similar to vsprintf, but it will print at most
+@var{n} characters. On error the return value is -1, otherwise it
+returns the number of characters that would have been printed had
+@var{n} been sufficiently large, regardless of the actual value of
+@var{n}. Note some pre-C99 system libraries do not implement this
+correctly so users cannot generally rely on the return value if the
+system version of this function is used.
+
+@end deftypefn
+
@c waitpid.c:3
@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
projects / gcc.git / blobdiff