OpenCores
URL https://opencores.org/ocsvn/openrisc_me/openrisc_me/trunk

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [binutils-2.18.50/] [libiberty/] [functions.texi] - Blame information for rev 438

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 38 julius
@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 safe-ctype.c:25
7
@defvr Extension HOST_CHARSET
8
This macro indicates the basic character set and encoding used by the
9
host: more precisely, the encoding used for character constants in
10
preprocessor @samp{#if} statements (the C "execution character set").
11
It is defined by @file{safe-ctype.h}, and will be an integer constant
12
with one of the following values:
13
 
14
@ftable @code
15
@item HOST_CHARSET_UNKNOWN
16
The host character set is unknown - that is, not one of the next two
17
possibilities.
18
 
19
@item HOST_CHARSET_ASCII
20
The host character set is ASCII.
21
 
22
@item HOST_CHARSET_EBCDIC
23
The host character set is some variant of EBCDIC.  (Only one of the
24
nineteen EBCDIC varying characters is tested; exercise caution.)
25
@end ftable
26
@end defvr
27
 
28
@c alloca.c:26
29
@deftypefn Replacement void* alloca (size_t @var{size})
30
 
31
This function allocates memory which will be automatically reclaimed
32
after the procedure exits.  The @libib{} implementation does not free
33
the memory immediately but will do so eventually during subsequent
34
calls to this function.  Memory is allocated using @code{xmalloc} under
35
normal circumstances.
36
 
37
The header file @file{alloca-conf.h} can be used in conjunction with the
38
GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make
39
available this function.  The @code{AC_FUNC_ALLOCA} test requires that
40
client code use a block of preprocessor code to be safe (see the Autoconf
41
manual for more); this header incorporates that logic and more, including
42
the possibility of a GCC built-in function.
43
 
44
@end deftypefn
45
 
46
@c asprintf.c:32
47
@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...)
48
 
49
Like @code{sprintf}, but instead of passing a pointer to a buffer, you
50
pass a pointer to a pointer.  This function will compute the size of
51
the buffer needed, allocate memory with @code{malloc}, and store a
52
pointer to the allocated memory in @code{*@var{resptr}}.  The value
53
returned is the same as @code{sprintf} would return.  If memory could
54
not be allocated, minus one is returned and @code{NULL} is stored in
55
@code{*@var{resptr}}.
56
 
57
@end deftypefn
58
 
59
@c atexit.c:6
60
@deftypefn Supplemental int atexit (void (*@var{f})())
61
 
62
Causes function @var{f} to be called at exit.  Returns 0.
63
 
64
@end deftypefn
65
 
66
@c basename.c:6
67
@deftypefn Supplemental char* basename (const char *@var{name})
68
 
69
Returns a pointer to the last component of pathname @var{name}.
70
Behavior is undefined if the pathname ends in a directory separator.
71
 
72
@end deftypefn
73
 
74
@c bcmp.c:6
75
@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count})
76
 
77
Compares the first @var{count} bytes of two areas of memory.  Returns
78
zero if they are the same, nonzero otherwise.  Returns zero if
79
@var{count} is zero.  A nonzero result only indicates a difference,
80
it does not indicate any sorting order (say, by having a positive
81
result mean @var{x} sorts before @var{y}).
82
 
83
@end deftypefn
84
 
85
@c bcopy.c:3
86
@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length})
87
 
88
Copies @var{length} bytes from memory region @var{in} to region
89
@var{out}.  The use of @code{bcopy} is deprecated in new programs.
90
 
91
@end deftypefn
92
 
93
@c bsearch.c:33
94
@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 *))
95
 
96
Performs a search over an array of @var{nmemb} elements pointed to by
97
@var{base} for a member that matches the object pointed to by @var{key}.
98
The size of each member is specified by @var{size}.  The array contents
99
should be sorted in ascending order according to the @var{compar}
100
comparison function.  This routine should take two arguments pointing to
101
the @var{key} and to an array member, in that order, and should return an
102
integer less than, equal to, or greater than zero if the @var{key} object
103
is respectively less than, matching, or greater than the array member.
104
 
105
@end deftypefn
106
 
107
@c argv.c:124
108
@deftypefn Extension char** buildargv (char *@var{sp})
109
 
110
Given a pointer to a string, parse the string extracting fields
111
separated by whitespace and optionally enclosed within either single
112
or double quotes (which are stripped off), and build a vector of
113
pointers to copies of the string for each field.  The input string
114
remains unchanged.  The last element of the vector is followed by a
115
@code{NULL} element.
116
 
117
All of the memory for the pointer array and copies of the string
118
is obtained from @code{malloc}.  All of the memory can be returned to the
119
system with the single function call @code{freeargv}, which takes the
120
returned result of @code{buildargv}, as it's argument.
121
 
122
Returns a pointer to the argument vector if successful.  Returns
123
@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient
124
memory to complete building the argument vector.
125
 
126
If the input is a null string (as opposed to a @code{NULL} pointer),
127
then buildarg returns an argument vector that has one arg, a null
128
string.
129
 
130
@end deftypefn
131
 
132
@c bzero.c:6
133
@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count})
134
 
135
Zeros @var{count} bytes starting at @var{mem}.  Use of this function
136
is deprecated in favor of @code{memset}.
137
 
138
@end deftypefn
139
 
140
@c calloc.c:6
141
@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize})
142
 
143
Uses @code{malloc} to allocate storage for @var{nelem} objects of
144
@var{elsize} bytes each, then zeros the memory.
145
 
146
@end deftypefn
147
 
148
@c choose-temp.c:42
149
@deftypefn Extension char* choose_temp_base (void)
150
 
151
Return a prefix for temporary file names or @code{NULL} if unable to
152
find one.  The current directory is chosen if all else fails so the
153
program is exited if a temporary directory can't be found (@code{mktemp}
154
fails).  The buffer for the result is obtained with @code{xmalloc}.
155
 
156
This function is provided for backwards compatibility only.  Its use is
157
not recommended.
158
 
159
@end deftypefn
160
 
161
@c make-temp-file.c:87
162
@deftypefn Replacement char* choose_tmpdir ()
163
 
164
Returns a pointer to a directory path suitable for creating temporary
165
files in.
166
 
167
@end deftypefn
168
 
169
@c clock.c:27
170
@deftypefn Supplemental long clock (void)
171
 
172
Returns an approximation of the CPU time used by the process as a
173
@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the
174
number of seconds used.
175
 
176
@end deftypefn
177
 
178
@c concat.c:24
179
@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @dots{}, @code{NULL})
180
 
181
Concatenate zero or more of strings and return the result in freshly
182
@code{xmalloc}ed memory.  Returns @code{NULL} if insufficient memory is
183
available.  The argument list is terminated by the first @code{NULL}
184
pointer encountered.  Pointers to empty strings are ignored.
185
 
186
@end deftypefn
187
 
188
@c argv.c:52
189
@deftypefn Extension char** dupargv (char **@var{vector})
190
 
191
Duplicate an argument vector.  Simply scans through @var{vector},
192
duplicating each argument until the terminating @code{NULL} is found.
193
Returns a pointer to the argument vector if successful.  Returns
194
@code{NULL} if there is insufficient memory to complete building the
195
argument vector.
196
 
197
@end deftypefn
198
 
199
@c strerror.c:567
200
@deftypefn Extension int errno_max (void)
201
 
202
Returns the maximum @code{errno} value for which a corresponding
203
symbolic name or message is available.  Note that in the case where we
204
use the @code{sys_errlist} supplied by the system, it is possible for
205
there to be more symbolic names than messages, or vice versa.  In
206
fact, the manual page for @code{perror(3C)} explicitly warns that one
207
should check the size of the table (@code{sys_nerr}) before indexing
208
it, since new error codes may be added to the system before they are
209
added to the table.  Thus @code{sys_nerr} might be smaller than value
210
implied by the largest @code{errno} value defined in @code{<errno.h>}.
211
 
212
We return the maximum value that can be used to obtain a meaningful
213
symbolic name or message.
214
 
215
@end deftypefn
216
 
217
@c argv.c:348
218
@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp})
219
 
220
The @var{argcp} and @code{argvp} arguments are pointers to the usual
221
@code{argc} and @code{argv} arguments to @code{main}.  This function
222
looks for arguments that begin with the character @samp{@@}.  Any such
223
arguments are interpreted as ``response files''.  The contents of the
224
response file are interpreted as additional command line options.  In
225
particular, the file is separated into whitespace-separated strings;
226
each such string is taken as a command-line option.  The new options
227
are inserted in place of the option naming the response file, and
228
@code{*argcp} and @code{*argvp} will be updated.  If the value of
229
@code{*argvp} is modified by this function, then the new value has
230
been dynamically allocated and can be deallocated by the caller with
231
@code{freeargv}.  However, most callers will simply call
232
@code{expandargv} near the beginning of @code{main} and allow the
233
operating system to free the memory when the program exits.
234
 
235
@end deftypefn
236
 
237
@c fdmatch.c:23
238
@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2})
239
 
240
Check to see if two open file descriptors refer to the same file.
241
This is useful, for example, when we have an open file descriptor for
242
an unnamed file, and the name of a file that we believe to correspond
243
to that fd.  This can happen when we are exec'd with an already open
244
file (@code{stdout} for example) or from the SVR4 @file{/proc} calls
245
that return open file descriptors for mapped address spaces.  All we
246
have to do is open the file by name and check the two file descriptors
247
for a match, which is done by comparing major and minor device numbers
248
and inode numbers.
249
 
250
@end deftypefn
251
 
252
@c fopen_unlocked.c:48
253
@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, const char * @var{mode})
254
 
255
Opens and returns a @code{FILE} pointer via @code{fdopen}.  If the
256
operating system supports it, ensure that the stream is setup to avoid
257
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
258
unchanged.
259
 
260
@end deftypefn
261
 
262
@c ffs.c:3
263
@deftypefn Supplemental int ffs (int @var{valu})
264
 
265
Find the first (least significant) bit set in @var{valu}.  Bits are
266
numbered from right to left, starting with bit 1 (corresponding to the
267
value 1).  If @var{valu} is zero, zero is returned.
268
 
269
@end deftypefn
270
 
271
@c filename_cmp.c:32
272
@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2})
273
 
274
Return zero if the two file names @var{s1} and @var{s2} are equivalent.
275
If not equivalent, the returned value is similar to what @code{strcmp}
276
would return.  In other words, it returns a negative value if @var{s1}
277
is less than @var{s2}, or a positive value if @var{s2} is greater than
278
@var{s2}.
279
 
280
This function does not normalize file names.  As a result, this function
281
will treat filenames that are spelled differently as different even in
282
the case when the two filenames point to the same underlying file.
283
However, it does handle the fact that on DOS-like file systems, forward
284
and backward slashes are equal.
285
 
286
@end deftypefn
287
 
288
@c fnmatch.txh:1
289
@deftypefn Replacement int fnmatch (const char *@var{pattern}, const char *@var{string}, int @var{flags})
290
 
291
Matches @var{string} against @var{pattern}, returning zero if it
292
matches, @code{FNM_NOMATCH} if not.  @var{pattern} may contain the
293
wildcards @code{?} to match any one character, @code{*} to match any
294
zero or more characters, or a set of alternate characters in square
295
brackets, like @samp{[a-gt8]}, which match one character (@code{a}
296
through @code{g}, or @code{t}, or @code{8}, in this example) if that one
297
character is in the set.  A set may be inverted (i.e., match anything
298
except what's in the set) by giving @code{^} or @code{!} as the first
299
character in the set.  To include those characters in the set, list them
300
as anything other than the first character of the set.  To include a
301
dash in the set, list it last in the set.  A backslash character makes
302
the following character not special, so for example you could match
303
against a literal asterisk with @samp{\*}.  To match a literal
304
backslash, use @samp{\\}.
305
 
306
@code{flags} controls various aspects of the matching process, and is a
307
boolean OR of zero or more of the following values (defined in
308
@code{<fnmatch.h>}):
309
 
310
@table @code
311
 
312
@item FNM_PATHNAME
313
@itemx FNM_FILE_NAME
314
@var{string} is assumed to be a path name.  No wildcard will ever match
315
@code{/}.
316
 
317
@item FNM_NOESCAPE
318
Do not interpret backslashes as quoting the following special character.
319
 
320
@item FNM_PERIOD
321
A leading period (at the beginning of @var{string}, or if
322
@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or
323
@code{?} but must be matched explicitly.
324
 
325
@item FNM_LEADING_DIR
326
Means that @var{string} also matches @var{pattern} if some initial part
327
of @var{string} matches, and is followed by @code{/} and zero or more
328
characters.  For example, @samp{foo*} would match either @samp{foobar}
329
or @samp{foobar/grill}.
330
 
331
@item FNM_CASEFOLD
332
Ignores case when performing the comparison.
333
 
334
@end table
335
 
336
@end deftypefn
337
 
338
@c fopen_unlocked.c:39
339
@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, const char * @var{mode})
340
 
341
Opens and returns a @code{FILE} pointer via @code{fopen}.  If the
342
operating system supports it, ensure that the stream is setup to avoid
343
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
344
unchanged.
345
 
346
@end deftypefn
347
 
348
@c argv.c:97
349
@deftypefn Extension void freeargv (char **@var{vector})
350
 
351
Free an argument vector that was built using @code{buildargv}.  Simply
352
scans through @var{vector}, freeing the memory for each argument until
353
the terminating @code{NULL} is found, and then frees @var{vector}
354
itself.
355
 
356
@end deftypefn
357
 
358
@c fopen_unlocked.c:57
359
@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, const char * @var{mode}, FILE * @var{stream})
360
 
361
Opens and returns a @code{FILE} pointer via @code{freopen}.  If the
362
operating system supports it, ensure that the stream is setup to avoid
363
any multi-threaded locking.  Otherwise return the @code{FILE} pointer
364
unchanged.
365
 
366
@end deftypefn
367
 
368
@c getruntime.c:82
369
@deftypefn Replacement long get_run_time (void)
370
 
371
Returns the time used so far, in microseconds.  If possible, this is
372
the time used by this process, else it is the elapsed time since the
373
process started.
374
 
375
@end deftypefn
376
 
377
@c getcwd.c:6
378
@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len})
379
 
380
Copy the absolute pathname for the current working directory into
381
@var{pathname}, which is assumed to point to a buffer of at least
382
@var{len} bytes, and return a pointer to the buffer.  If the current
383
directory's path doesn't fit in @var{len} characters, the result is
384
@code{NULL} and @code{errno} is set.  If @var{pathname} is a null pointer,
385
@code{getcwd} will obtain @var{len} bytes of space using
386
@code{malloc}.
387
 
388
@end deftypefn
389
 
390
@c getpagesize.c:5
391
@deftypefn Supplemental int getpagesize (void)
392
 
393
Returns the number of bytes in a page of memory.  This is the
394
granularity of many of the system memory management routines.  No
395
guarantee is made as to whether or not it is the same as the basic
396
memory management hardware page size.
397
 
398
@end deftypefn
399
 
400
@c getpwd.c:5
401
@deftypefn Supplemental char* getpwd (void)
402
 
403
Returns the current working directory.  This implementation caches the
404
result on the assumption that the process will not call @code{chdir}
405
between calls to @code{getpwd}.
406
 
407
@end deftypefn
408
 
409
@c gettimeofday.c:12
410
@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz})
411
 
412
Writes the current time to @var{tp}.  This implementation requires
413
that @var{tz} be NULL.  Returns 0 on success, -1 on failure.
414
 
415
@end deftypefn
416
 
417
@c hex.c:33
418
@deftypefn Extension void hex_init (void)
419
 
420
Initializes the array mapping the current character set to
421
corresponding hex values.  This function must be called before any
422
call to @code{hex_p} or @code{hex_value}.  If you fail to call it, a
423
default ASCII-based table will normally be used on ASCII systems.
424
 
425
@end deftypefn
426
 
427
@c hex.c:42
428
@deftypefn Extension int hex_p (int @var{c})
429
 
430
Evaluates to non-zero if the given character is a valid hex character,
431
or zero if it is not.  Note that the value you pass will be cast to
432
@code{unsigned char} within the macro.
433
 
434
@end deftypefn
435
 
436
@c hex.c:50
437
@deftypefn Extension {unsigned int} hex_value (int @var{c})
438
 
439
Returns the numeric equivalent of the given character when interpreted
440
as a hexadecimal digit.  The result is undefined if you pass an
441
invalid hex digit.  Note that the value you pass will be cast to
442
@code{unsigned char} within the macro.
443
 
444
The @code{hex_value} macro returns @code{unsigned int}, rather than
445
signed @code{int}, to make it easier to use in parsing addresses from
446
hex dump files: a signed @code{int} would be sign-extended when
447
converted to a wider unsigned type --- like @code{bfd_vma}, on some
448
systems.
449
 
450
@end deftypefn
451
 
452
@c index.c:5
453
@deftypefn Supplemental char* index (char *@var{s}, int @var{c})
454
 
455
Returns a pointer to the first occurrence of the character @var{c} in
456
the string @var{s}, or @code{NULL} if not found.  The use of @code{index} is
457
deprecated in new programs in favor of @code{strchr}.
458
 
459
@end deftypefn
460
 
461
@c insque.c:6
462
@deftypefn Supplemental void insque (struct qelem *@var{elem}, struct qelem *@var{pred})
463
@deftypefnx Supplemental void remque (struct qelem *@var{elem})
464
 
465
Routines to manipulate queues built from doubly linked lists.  The
466
@code{insque} routine inserts @var{elem} in the queue immediately
467
after @var{pred}.  The @code{remque} routine removes @var{elem} from
468
its containing queue.  These routines expect to be passed pointers to
469
structures which have as their first members a forward pointer and a
470
back pointer, like this prototype (although no prototype is provided):
471
 
472
@example
473
struct qelem @{
474
  struct qelem *q_forw;
475
  struct qelem *q_back;
476
  char q_data[];
477
@};
478
@end example
479
 
480
@end deftypefn
481
 
482
@c safe-ctype.c:46
483
@deffn  Extension ISALPHA  (@var{c})
484
@deffnx Extension ISALNUM  (@var{c})
485
@deffnx Extension ISBLANK  (@var{c})
486
@deffnx Extension ISCNTRL  (@var{c})
487
@deffnx Extension ISDIGIT  (@var{c})
488
@deffnx Extension ISGRAPH  (@var{c})
489
@deffnx Extension ISLOWER  (@var{c})
490
@deffnx Extension ISPRINT  (@var{c})
491
@deffnx Extension ISPUNCT  (@var{c})
492
@deffnx Extension ISSPACE  (@var{c})
493
@deffnx Extension ISUPPER  (@var{c})
494
@deffnx Extension ISXDIGIT (@var{c})
495
 
496
These twelve macros are defined by @file{safe-ctype.h}.  Each has the
497
same meaning as the corresponding macro (with name in lowercase)
498
defined by the standard header @file{ctype.h}.  For example,
499
@code{ISALPHA} returns true for alphabetic characters and false for
500
others.  However, there are two differences between these macros and
501
those provided by @file{ctype.h}:
502
 
503
@itemize @bullet
504
@item These macros are guaranteed to have well-defined behavior for all
505
values representable by @code{signed char} and @code{unsigned char}, and
506
for @code{EOF}.
507
 
508
@item These macros ignore the current locale; they are true for these
509
fixed sets of characters:
510
@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada}
511
@item @code{ALPHA}  @tab @kbd{A-Za-z}
512
@item @code{ALNUM}  @tab @kbd{A-Za-z0-9}
513
@item @code{BLANK}  @tab @kbd{space tab}
514
@item @code{CNTRL}  @tab @code{!PRINT}
515
@item @code{DIGIT}  @tab @kbd{0-9}
516
@item @code{GRAPH}  @tab @code{ALNUM || PUNCT}
517
@item @code{LOWER}  @tab @kbd{a-z}
518
@item @code{PRINT}  @tab @code{GRAPH ||} @kbd{space}
519
@item @code{PUNCT}  @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?}
520
@item @code{SPACE}  @tab @kbd{space tab \n \r \f \v}
521
@item @code{UPPER}  @tab @kbd{A-Z}
522
@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f}
523
@end multitable
524
 
525
Note that, if the host character set is ASCII or a superset thereof,
526
all these macros will return false for all values of @code{char} outside
527
the range of 7-bit ASCII.  In particular, both ISPRINT and ISCNTRL return
528
false for characters with numeric values from 128 to 255.
529
@end itemize
530
@end deffn
531
 
532
@c safe-ctype.c:95
533
@deffn  Extension ISIDNUM         (@var{c})
534
@deffnx Extension ISIDST          (@var{c})
535
@deffnx Extension IS_VSPACE       (@var{c})
536
@deffnx Extension IS_NVSPACE      (@var{c})
537
@deffnx Extension IS_SPACE_OR_NUL (@var{c})
538
@deffnx Extension IS_ISOBASIC     (@var{c})
539
These six macros are defined by @file{safe-ctype.h} and provide
540
additional character classes which are useful when doing lexical
541
analysis of C or similar languages.  They are true for the following
542
sets of characters:
543
 
544
@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada}
545
@item @code{IDNUM}        @tab @kbd{A-Za-z0-9_}
546
@item @code{IDST}         @tab @kbd{A-Za-z_}
547
@item @code{VSPACE}       @tab @kbd{\r \n}
548
@item @code{NVSPACE}      @tab @kbd{space tab \f \v \0}
549
@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE}
550
@item @code{ISOBASIC}     @tab @code{VSPACE || NVSPACE || PRINT}
551
@end multitable
552
@end deffn
553
 
554
@c lbasename.c:23
555
@deftypefn Replacement {const char*} lbasename (const char *@var{name})
556
 
557
Given a pointer to a string containing a typical pathname
558
(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the
559
last component of the pathname (@samp{ls.c} in this case).  The
560
returned pointer is guaranteed to lie within the original
561
string.  This latter fact is not true of many vendor C
562
libraries, which return special strings or modify the passed
563
strings for particular input.
564
 
565
In particular, the empty string returns the same empty string,
566
and a path ending in @code{/} returns the empty string after it.
567
 
568
@end deftypefn
569
 
570
@c lrealpath.c:25
571
@deftypefn Replacement {const char*} lrealpath (const char *@var{name})
572
 
573
Given a pointer to a string containing a pathname, returns a canonical
574
version of the filename.  Symlinks will be resolved, and ``.'' and ``..''
575
components will be simplified.  The returned value will be allocated using
576
@code{malloc}, or @code{NULL} will be returned on a memory allocation error.
577
 
578
@end deftypefn
579
 
580
@c make-relative-prefix.c:24
581
@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, const char *@var{bin_prefix}, const char *@var{prefix})
582
 
583
Given three paths @var{progname}, @var{bin_prefix}, @var{prefix},
584
return the path that is in the same position relative to
585
@var{progname}'s directory as @var{prefix} is relative to
586
@var{bin_prefix}.  That is, a string starting with the directory
587
portion of @var{progname}, followed by a relative pathname of the
588
difference between @var{bin_prefix} and @var{prefix}.
589
 
590
If @var{progname} does not contain any directory separators,
591
@code{make_relative_prefix} will search @env{PATH} to find a program
592
named @var{progname}.  Also, if @var{progname} is a symbolic link,
593
the symbolic link will be resolved.
594
 
595
For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta},
596
@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is
597
@code{/red/green/blue/gcc}, then this function will return
598
@code{/red/green/blue/../../omega/}.
599
 
600
The return value is normally allocated via @code{malloc}.  If no
601
relative prefix can be found, return @code{NULL}.
602
 
603
@end deftypefn
604
 
605
@c make-temp-file.c:137
606
@deftypefn Replacement char* make_temp_file (const char *@var{suffix})
607
 
608
Return a temporary file name (as a string) or @code{NULL} if unable to
609
create one.  @var{suffix} is a suffix to append to the file name.  The
610
string is @code{malloc}ed, and the temporary file has been created.
611
 
612
@end deftypefn
613
 
614
@c memchr.c:3
615
@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, size_t @var{n})
616
 
617
This function searches memory starting at @code{*@var{s}} for the
618
character @var{c}.  The search only ends with the first occurrence of
619
@var{c}, or after @var{length} characters; in particular, a null
620
character does not terminate the search.  If the character @var{c} is
621
found within @var{length} characters of @code{*@var{s}}, a pointer
622
to the character is returned.  If @var{c} is not found, then @code{NULL} is
623
returned.
624
 
625
@end deftypefn
626
 
627
@c memcmp.c:6
628
@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, size_t @var{count})
629
 
630
Compares the first @var{count} bytes of two areas of memory.  Returns
631
zero if they are the same, a value less than zero if @var{x} is
632
lexically less than @var{y}, or a value greater than zero if @var{x}
633
is lexically greater than @var{y}.  Note that lexical order is determined
634
as if comparing unsigned char arrays.
635
 
636
@end deftypefn
637
 
638
@c memcpy.c:6
639
@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
640
 
641
Copies @var{length} bytes from memory region @var{in} to region
642
@var{out}.  Returns a pointer to @var{out}.
643
 
644
@end deftypefn
645
 
646
@c memmove.c:6
647
@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, size_t @var{count})
648
 
649
Copies @var{count} bytes from memory area @var{from} to memory area
650
@var{to}, returning a pointer to @var{to}.
651
 
652
@end deftypefn
653
 
654
@c mempcpy.c:23
655
@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, size_t @var{length})
656
 
657
Copies @var{length} bytes from memory region @var{in} to region
658
@var{out}.  Returns a pointer to @var{out} + @var{length}.
659
 
660
@end deftypefn
661
 
662
@c memset.c:6
663
@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, size_t @var{count})
664
 
665
Sets the first @var{count} bytes of @var{s} to the constant byte
666
@var{c}, returning a pointer to @var{s}.
667
 
668
@end deftypefn
669
 
670
@c mkstemps.c:58
671
@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len})
672
 
673
Generate a unique temporary file name from @var{pattern}.
674
@var{pattern} has the form:
675
 
676
@example
677
   @var{path}/ccXXXXXX@var{suffix}
678
@end example
679
 
680
@var{suffix_len} tells us how long @var{suffix} is (it can be zero
681
length).  The last six characters of @var{pattern} before @var{suffix}
682
must be @samp{XXXXXX}; they are replaced with a string that makes the
683
filename unique.  Returns a file descriptor open on the file for
684
reading and writing.
685
 
686
@end deftypefn
687
 
688
@c pexecute.txh:266
689
@deftypefn Extension void pex_free (struct pex_obj @var{obj})
690
 
691
Clean up and free all data associated with @var{obj}.
692
 
693
@end deftypefn
694
 
695
@c pexecute.txh:241
696
@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
697
 
698
Returns the exit status of all programs run using @var{obj}.
699
@var{count} is the number of results expected.  The results will be
700
placed into @var{vector}.  The results are in the order of the calls
701
to @code{pex_run}.  Returns 0 on error, 1 on success.
702
 
703
@end deftypefn
704
 
705
@c pexecute.txh:250
706
@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
707
 
708
Returns the process execution times of all programs run using
709
@var{obj}.  @var{count} is the number of results expected.  The
710
results will be placed into @var{vector}.  The results are in the
711
order of the calls to @code{pex_run}.  Returns 0 on error, 1 on
712
success.
713
 
714
@code{struct pex_time} has the following fields of the type
715
@code{unsigned long}: @code{user_seconds},
716
@code{user_microseconds}, @code{system_seconds},
717
@code{system_microseconds}.  On systems which do not support reporting
718
process times, all the fields will be set to @code{0}.
719
 
720
@end deftypefn
721
 
722
@c pexecute.txh:2
723
@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
724
 
725
Prepare to execute one or more programs, with standard output of each
726
program fed to standard input of the next.  This is a system
727
independent interface to execute a pipeline.
728
 
729
@var{flags} is a bitwise combination of the following:
730
 
731
@table @code
732
 
733
@vindex PEX_RECORD_TIMES
734
@item PEX_RECORD_TIMES
735
Record subprocess times if possible.
736
 
737
@vindex PEX_USE_PIPES
738
@item PEX_USE_PIPES
739
Use pipes for communication between processes, if possible.
740
 
741
@vindex PEX_SAVE_TEMPS
742
@item PEX_SAVE_TEMPS
743
Don't delete temporary files used for communication between
744
processes.
745
 
746
@end table
747
 
748
@var{pname} is the name of program to be executed, used in error
749
messages.  @var{tempbase} is a base name to use for any required
750
temporary files; it may be @code{NULL} to use a randomly chosen name.
751
 
752
@end deftypefn
753
 
754
@c pexecute.txh:155
755
@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
756
 
757
Return a stream for a temporary file to pass to the first program in
758
the pipeline as input.
759
 
760
The name of the input file is chosen according to the same rules
761
@code{pex_run} uses to choose output file names, based on
762
@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
763
 
764
Don't call @code{fclose} on the returned stream; the first call to
765
@code{pex_run} closes it automatically.
766
 
767
If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
768
binary mode; otherwise, open it in the default mode.  Including
769
@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
770
@end deftypefn
771
 
772
@c pexecute.txh:172
773
@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
774
 
775
Return a stream @var{fp} for a pipe connected to the standard input of
776
the first program in the pipeline; @var{fp} is opened for writing.
777
You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
778
that returned @var{obj}.
779
 
780
You must close @var{fp} using @code{fclose} yourself when you have
781
finished writing data to the pipeline.
782
 
783
The file descriptor underlying @var{fp} is marked not to be inherited
784
by child processes.
785
 
786
On systems that do not support pipes, this function returns
787
@code{NULL}, and sets @code{errno} to @code{EINVAL}.  If you would
788
like to write code that is portable to all systems the @code{pex}
789
functions support, consider using @code{pex_input_file} instead.
790
 
791
There are two opportunities for deadlock using
792
@code{pex_input_pipe}:
793
 
794
@itemize @bullet
795
@item
796
Most systems' pipes can buffer only a fixed amount of data; a process
797
that writes to a full pipe blocks.  Thus, if you write to @file{fp}
798
before starting the first process, you run the risk of blocking when
799
there is no child process yet to read the data and allow you to
800
continue.  @code{pex_input_pipe} makes no promises about the
801
size of the pipe's buffer, so if you need to write any data at all
802
before starting the first process in the pipeline, consider using
803
@code{pex_input_file} instead.
804
 
805
@item
806
Using @code{pex_input_pipe} and @code{pex_read_output} together
807
may also cause deadlock.  If the output pipe fills up, so that each
808
program in the pipeline is waiting for the next to read more data, and
809
you fill the input pipe by writing more data to @var{fp}, then there
810
is no way to make progress: the only process that could read data from
811
the output pipe is you, but you are blocked on the input pipe.
812
 
813
@end itemize
814
 
815
@end deftypefn
816
 
817
@c pexecute.txh:272
818
@deftypefn Extension {const char *} pex_one (int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, int *@var{status}, int *@var{err})
819
 
820
An interface to permit the easy execution of a
821
single program.  The return value and most of the parameters are as
822
for a call to @code{pex_run}.  @var{flags} is restricted to a
823
combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
824
@code{PEX_BINARY_OUTPUT}.  @var{outname} is interpreted as if
825
@code{PEX_LAST} were set.  On a successful return, @code{*@var{status}} will
826
be set to the exit status of the program.
827
 
828
@end deftypefn
829
 
830
@c pexecute.txh:228
831
@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
832
 
833
Returns a @code{FILE} pointer which may be used to read the standard
834
error of the last program in the pipeline.  When this is used,
835
@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
836
this is called, @code{pex_run} may no longer be called with the same
837
@var{obj}.  @var{binary} should be non-zero if the file should be
838
opened in binary mode.  Don't call @code{fclose} on the returned file;
839
it will be closed by @code{pex_free}.
840
 
841
@end deftypefn
842
 
843
@c pexecute.txh:216
844
@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
845
 
846
Returns a @code{FILE} pointer which may be used to read the standard
847
output of the last program in the pipeline.  When this is used,
848
@code{PEX_LAST} should not be used in a call to @code{pex_run}.  After
849
this is called, @code{pex_run} may no longer be called with the same
850
@var{obj}.  @var{binary} should be non-zero if the file should be
851
opened in binary mode.  Don't call @code{fclose} on the returned file;
852
it will be closed by @code{pex_free}.
853
 
854
@end deftypefn
855
 
856
@c pexecute.txh:33
857
@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
858
 
859
Execute one program in a pipeline.  On success this returns
860
@code{NULL}.  On failure it returns an error message, a statically
861
allocated string.
862
 
863
@var{obj} is returned by a previous call to @code{pex_init}.
864
 
865
@var{flags} is a bitwise combination of the following:
866
 
867
@table @code
868
 
869
@vindex PEX_LAST
870
@item PEX_LAST
871
This must be set on the last program in the pipeline.  In particular,
872
it should be set when executing a single program.  The standard output
873
of the program will be sent to @var{outname}, or, if @var{outname} is
874
@code{NULL}, to the standard output of the calling program.  Do @emph{not}
875
set this bit if you want to call @code{pex_read_output}
876
(described below).  After a call to @code{pex_run} with this bit set,
877
@var{pex_run} may no longer be called with the same @var{obj}.
878
 
879
@vindex PEX_SEARCH
880
@item PEX_SEARCH
881
Search for the program using the user's executable search path.
882
 
883
@vindex PEX_SUFFIX
884
@item PEX_SUFFIX
885
@var{outname} is a suffix.  See the description of @var{outname},
886
below.
887
 
888
@vindex PEX_STDERR_TO_STDOUT
889
@item PEX_STDERR_TO_STDOUT
890
Send the program's standard error to standard output, if possible.
891
 
892
@vindex PEX_BINARY_INPUT
893
@vindex PEX_BINARY_OUTPUT
894
@vindex PEX_BINARY_ERROR
895
@item PEX_BINARY_INPUT
896
@itemx PEX_BINARY_OUTPUT
897
@itemx PEX_BINARY_ERROR
898
The standard input (output or error) of the program should be read (written) in
899
binary mode rather than text mode.  These flags are ignored on systems
900
which do not distinguish binary mode and text mode, such as Unix.  For
901
proper behavior these flags should match appropriately---a call to
902
@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
903
call using @code{PEX_BINARY_INPUT}.
904
 
905
@vindex PEX_STDERR_TO_PIPE
906
@item PEX_STDERR_TO_PIPE
907
Send the program's standard error to a pipe, if possible.  This flag
908
cannot be specified together with @code{PEX_STDERR_TO_STDOUT}.  This
909
flag can be specified only on the last program in pipeline.
910
 
911
@end table
912
 
913
@var{executable} is the program to execute.  @var{argv} is the set of
914
arguments to pass to the program; normally @code{@var{argv}[0]} will
915
be a copy of @var{executable}.
916
 
917
@var{outname} is used to set the name of the file to use for standard
918
output.  There are two cases in which no output file will be used:
919
 
920
@enumerate
921
@item
922
if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
923
was set in the call to @code{pex_init}, and the system supports pipes
924
 
925
@item
926
if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
927
@code{NULL}
928
@end enumerate
929
 
930
@noindent
931
Otherwise the code will use a file to hold standard
932
output.  If @code{PEX_LAST} is not set, this file is considered to be
933
a temporary file, and it will be removed when no longer needed, unless
934
@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
935
 
936
There are two cases to consider when setting the name of the file to
937
hold standard output.
938
 
939
@enumerate
940
@item
941
@code{PEX_SUFFIX} is set in @var{flags}.  In this case
942
@var{outname} may not be @code{NULL}.  If the @var{tempbase} parameter
943
to @code{pex_init} was not @code{NULL}, then the output file name is
944
the concatenation of @var{tempbase} and @var{outname}.  If
945
@var{tempbase} was @code{NULL}, then the output file name is a random
946
file name ending in @var{outname}.
947
 
948
@item
949
@code{PEX_SUFFIX} was not set in @var{flags}.  In this
950
case, if @var{outname} is not @code{NULL}, it is used as the output
951
file name.  If @var{outname} is @code{NULL}, and @var{tempbase} was
952
not NULL, the output file name is randomly chosen using
953
@var{tempbase}.  Otherwise the output file name is chosen completely
954
at random.
955
@end enumerate
956
 
957
@var{errname} is the file name to use for standard error output.  If
958
it is @code{NULL}, standard error is the same as the caller's.
959
Otherwise, standard error is written to the named file.
960
 
961
On an error return, the code sets @code{*@var{err}} to an @code{errno}
962
value, or to 0 if there is no relevant @code{errno}.
963
 
964
@end deftypefn
965
 
966
@c pexecute.txh:142
967
@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{executable}, char * const *@var{argv}, char * const *@var{env}, int @var{env_size}, const char *@var{outname}, const char *@var{errname}, int *@var{err})
968
 
969
Execute one program in a pipeline, permitting the environment for the
970
program to be specified.  Behaviour and parameters not listed below are
971
as for @code{pex_run}.
972
 
973
@var{env} is the environment for the child process, specified as an array of
974
character pointers.  Each element of the array should point to a string of the
975
form @code{VAR=VALUE}, with the exception of the last element that must be
976
@code{NULL}.
977
 
978
@end deftypefn
979
 
980
@c pexecute.txh:284
981
@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 @var{flags})
982
 
983
This is the old interface to execute one or more programs.  It is
984
still supported for compatibility purposes, but is no longer
985
documented.
986
 
987
@end deftypefn
988
 
989
@c strsignal.c:539
990
@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
991
 
992
Print @var{message} to the standard error, followed by a colon,
993
followed by the description of the signal specified by @var{signo},
994
followed by a newline.
995
 
996
@end deftypefn
997
 
998
@c putenv.c:21
999
@deftypefn Supplemental int putenv (const char *@var{string})
1000
 
1001
Uses @code{setenv} or @code{unsetenv} to put @var{string} into
1002
the environment or remove it.  If @var{string} is of the form
1003
@samp{name=value} the string is added; if no @samp{=} is present the
1004
name is unset/removed.
1005
 
1006
@end deftypefn
1007
 
1008
@c pexecute.txh:292
1009
@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
1010
 
1011
Another part of the old execution interface.
1012
 
1013
@end deftypefn
1014
 
1015
@c random.c:39
1016
@deftypefn Supplement {long int} random (void)
1017
@deftypefnx Supplement void srandom (unsigned int @var{seed})
1018
@deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
1019
@deftypefnx Supplement void* setstate (void *@var{arg_state})
1020
 
1021
Random number functions.  @code{random} returns a random number in the
1022
range 0 to @code{LONG_MAX}.  @code{srandom} initializes the random
1023
number generator to some starting point determined by @var{seed}
1024
(else, the values returned by @code{random} are always the same for each
1025
run of the program).  @code{initstate} and @code{setstate} allow fine-grained
1026
control over the state of the random number generator.
1027
 
1028
@end deftypefn
1029
 
1030
@c concat.c:173
1031
@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
1032
 
1033
Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
1034
is freed after the string is created.  This is intended to be useful
1035
when you're extending an existing string or building up a string in a
1036
loop:
1037
 
1038
@example
1039
  str = reconcat (str, "pre-", str, NULL);
1040
@end example
1041
 
1042
@end deftypefn
1043
 
1044
@c rename.c:6
1045
@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
1046
 
1047
Renames a file from @var{old} to @var{new}.  If @var{new} already
1048
exists, it is removed.
1049
 
1050
@end deftypefn
1051
 
1052
@c rindex.c:5
1053
@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
1054
 
1055
Returns a pointer to the last occurrence of the character @var{c} in
1056
the string @var{s}, or @code{NULL} if not found.  The use of @code{rindex} is
1057
deprecated in new programs in favor of @code{strrchr}.
1058
 
1059
@end deftypefn
1060
 
1061
@c setenv.c:22
1062
@deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
1063
@deftypefnx Supplemental void unsetenv (const char *@var{name})
1064
 
1065
@code{setenv} adds @var{name} to the environment with value
1066
@var{value}.  If the name was already present in the environment,
1067
the new value will be stored only if @var{overwrite} is nonzero.
1068
The companion @code{unsetenv} function removes @var{name} from the
1069
environment.  This implementation is not safe for multithreaded code.
1070
 
1071
@end deftypefn
1072
 
1073
@c strsignal.c:348
1074
@deftypefn Extension int signo_max (void)
1075
 
1076
Returns the maximum signal value for which a corresponding symbolic
1077
name or message is available.  Note that in the case where we use the
1078
@code{sys_siglist} supplied by the system, it is possible for there to
1079
be more symbolic names than messages, or vice versa.  In fact, the
1080
manual page for @code{psignal(3b)} explicitly warns that one should
1081
check the size of the table (@code{NSIG}) before indexing it, since
1082
new signal codes may be added to the system before they are added to
1083
the table.  Thus @code{NSIG} might be smaller than value implied by
1084
the largest signo value defined in @code{<signal.h>}.
1085
 
1086
We return the maximum value that can be used to obtain a meaningful
1087
symbolic name or message.
1088
 
1089
@end deftypefn
1090
 
1091
@c sigsetmask.c:8
1092
@deftypefn Supplemental int sigsetmask (int @var{set})
1093
 
1094
Sets the signal mask to the one provided in @var{set} and returns
1095
the old mask (which, for libiberty's implementation, will always
1096
be the value @code{1}).
1097
 
1098
@end deftypefn
1099
 
1100
@c snprintf.c:28
1101
@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
1102
 
1103
This function is similar to sprintf, but it will print at most @var{n}
1104
characters.  On error the return value is -1, otherwise it returns the
1105
number of characters that would have been printed had @var{n} been
1106
sufficiently large, regardless of the actual value of @var{n}.  Note
1107
some pre-C99 system libraries do not implement this correctly so users
1108
cannot generally rely on the return value if the system version of
1109
this function is used.
1110
 
1111
@end deftypefn
1112
 
1113
@c spaces.c:22
1114
@deftypefn Extension char* spaces (int @var{count})
1115
 
1116
Returns a pointer to a memory region filled with the specified
1117
number of spaces and null terminated.  The returned pointer is
1118
valid until at least the next call.
1119
 
1120
@end deftypefn
1121
 
1122
@c stpcpy.c:23
1123
@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
1124
 
1125
Copies the string @var{src} into @var{dst}.  Returns a pointer to
1126
@var{dst} + strlen(@var{src}).
1127
 
1128
@end deftypefn
1129
 
1130
@c stpncpy.c:23
1131
@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
1132
 
1133
Copies the string @var{src} into @var{dst}, copying exactly @var{len}
1134
and padding with zeros if necessary.  If @var{len} < strlen(@var{src})
1135
then return @var{dst} + @var{len}, otherwise returns @var{dst} +
1136
strlen(@var{src}).
1137
 
1138
@end deftypefn
1139
 
1140
@c strcasecmp.c:15
1141
@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
1142
 
1143
A case-insensitive @code{strcmp}.
1144
 
1145
@end deftypefn
1146
 
1147
@c strchr.c:6
1148
@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
1149
 
1150
Returns a pointer to the first occurrence of the character @var{c} in
1151
the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1152
null character, the results are undefined.
1153
 
1154
@end deftypefn
1155
 
1156
@c strdup.c:3
1157
@deftypefn Supplemental char* strdup (const char *@var{s})
1158
 
1159
Returns a pointer to a copy of @var{s} in memory obtained from
1160
@code{malloc}, or @code{NULL} if insufficient memory was available.
1161
 
1162
@end deftypefn
1163
 
1164
@c strerror.c:670
1165
@deftypefn Replacement {const char*} strerrno (int @var{errnum})
1166
 
1167
Given an error number returned from a system call (typically returned
1168
in @code{errno}), returns a pointer to a string containing the
1169
symbolic name of that error number, as found in @code{<errno.h>}.
1170
 
1171
If the supplied error number is within the valid range of indices for
1172
symbolic names, but no name is available for the particular error
1173
number, then returns the string @samp{Error @var{num}}, where @var{num}
1174
is the error number.
1175
 
1176
If the supplied error number is not within the range of valid
1177
indices, then returns @code{NULL}.
1178
 
1179
The contents of the location pointed to are only guaranteed to be
1180
valid until the next call to @code{strerrno}.
1181
 
1182
@end deftypefn
1183
 
1184
@c strerror.c:603
1185
@deftypefn Supplemental char* strerror (int @var{errnoval})
1186
 
1187
Maps an @code{errno} number to an error message string, the contents
1188
of which are implementation defined.  On systems which have the
1189
external variables @code{sys_nerr} and @code{sys_errlist}, these
1190
strings will be the same as the ones used by @code{perror}.
1191
 
1192
If the supplied error number is within the valid range of indices for
1193
the @code{sys_errlist}, but no message is available for the particular
1194
error number, then returns the string @samp{Error @var{num}}, where
1195
@var{num} is the error number.
1196
 
1197
If the supplied error number is not a valid index into
1198
@code{sys_errlist}, returns @code{NULL}.
1199
 
1200
The returned string is only guaranteed to be valid only until the
1201
next call to @code{strerror}.
1202
 
1203
@end deftypefn
1204
 
1205
@c strncasecmp.c:15
1206
@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
1207
 
1208
A case-insensitive @code{strncmp}.
1209
 
1210
@end deftypefn
1211
 
1212
@c strncmp.c:6
1213
@deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
1214
 
1215
Compares the first @var{n} bytes of two strings, returning a value as
1216
@code{strcmp}.
1217
 
1218
@end deftypefn
1219
 
1220
@c strndup.c:23
1221
@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
1222
 
1223
Returns a pointer to a copy of @var{s} with at most @var{n} characters
1224
in memory obtained from @code{malloc}, or @code{NULL} if insufficient
1225
memory was available.  The result is always NUL terminated.
1226
 
1227
@end deftypefn
1228
 
1229
@c strrchr.c:6
1230
@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
1231
 
1232
Returns a pointer to the last occurrence of the character @var{c} in
1233
the string @var{s}, or @code{NULL} if not found.  If @var{c} is itself the
1234
null character, the results are undefined.
1235
 
1236
@end deftypefn
1237
 
1238
@c strsignal.c:383
1239
@deftypefn Supplemental {const char *} strsignal (int @var{signo})
1240
 
1241
Maps an signal number to an signal message string, the contents of
1242
which are implementation defined.  On systems which have the external
1243
variable @code{sys_siglist}, these strings will be the same as the
1244
ones used by @code{psignal()}.
1245
 
1246
If the supplied signal number is within the valid range of indices for
1247
the @code{sys_siglist}, but no message is available for the particular
1248
signal number, then returns the string @samp{Signal @var{num}}, where
1249
@var{num} is the signal number.
1250
 
1251
If the supplied signal number is not a valid index into
1252
@code{sys_siglist}, returns @code{NULL}.
1253
 
1254
The returned string is only guaranteed to be valid only until the next
1255
call to @code{strsignal}.
1256
 
1257
@end deftypefn
1258
 
1259
@c strsignal.c:446
1260
@deftypefn Extension {const char*} strsigno (int @var{signo})
1261
 
1262
Given an signal number, returns a pointer to a string containing the
1263
symbolic name of that signal number, as found in @code{<signal.h>}.
1264
 
1265
If the supplied signal number is within the valid range of indices for
1266
symbolic names, but no name is available for the particular signal
1267
number, then returns the string @samp{Signal @var{num}}, where
1268
@var{num} is the signal number.
1269
 
1270
If the supplied signal number is not within the range of valid
1271
indices, then returns @code{NULL}.
1272
 
1273
The contents of the location pointed to are only guaranteed to be
1274
valid until the next call to @code{strsigno}.
1275
 
1276
@end deftypefn
1277
 
1278
@c strstr.c:6
1279
@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
1280
 
1281
This function searches for the substring @var{sub} in the string
1282
@var{string}, not including the terminating null characters.  A pointer
1283
to the first occurrence of @var{sub} is returned, or @code{NULL} if the
1284
substring is absent.  If @var{sub} points to a string with zero
1285
length, the function returns @var{string}.
1286
 
1287
@end deftypefn
1288
 
1289
@c strtod.c:27
1290
@deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
1291
 
1292
This ISO C function converts the initial portion of @var{string} to a
1293
@code{double}.  If @var{endptr} is not @code{NULL}, a pointer to the
1294
character after the last character used in the conversion is stored in
1295
the location referenced by @var{endptr}.  If no conversion is
1296
performed, zero is returned and the value of @var{string} is stored in
1297
the location referenced by @var{endptr}.
1298
 
1299
@end deftypefn
1300
 
1301
@c strerror.c:729
1302
@deftypefn Extension int strtoerrno (const char *@var{name})
1303
 
1304
Given the symbolic name of a error number (e.g., @code{EACCES}), map it
1305
to an errno value.  If no translation is found, returns 0.
1306
 
1307
@end deftypefn
1308
 
1309
@c strtol.c:33
1310
@deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
1311
@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
1312
 
1313
The @code{strtol} function converts the string in @var{string} to a
1314
long integer value according to the given @var{base}, which must be
1315
between 2 and 36 inclusive, or be the special value 0.  If @var{base}
1316
is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
1317
to indicate bases 8 and 16, respectively, else default to base 10.
1318
When the base is 16 (either explicitly or implicitly), a prefix of
1319
@code{0x} is allowed.  The handling of @var{endptr} is as that of
1320
@code{strtod} above.  The @code{strtoul} function is the same, except
1321
that the converted value is unsigned.
1322
 
1323
@end deftypefn
1324
 
1325
@c strsignal.c:500
1326
@deftypefn Extension int strtosigno (const char *@var{name})
1327
 
1328
Given the symbolic name of a signal, map it to a signal number.  If no
1329
translation is found, returns 0.
1330
 
1331
@end deftypefn
1332
 
1333
@c strverscmp.c:25
1334
@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
1335
The @code{strverscmp} function compares the string @var{s1} against
1336
@var{s2}, considering them as holding indices/version numbers.  Return
1337
value follows the same conventions as found in the @code{strverscmp}
1338
function.  In fact, if @var{s1} and @var{s2} contain no digits,
1339
@code{strverscmp} behaves like @code{strcmp}.
1340
 
1341
Basically, we compare strings normally (character by character), until
1342
we find a digit in each string - then we enter a special comparison
1343
mode, where each sequence of digits is taken as a whole.  If we reach the
1344
end of these two parts without noticing a difference, we return to the
1345
standard comparison mode.  There are two types of numeric parts:
1346
"integral" and "fractional" (those  begin with a '0'). The types
1347
of the numeric parts affect the way we sort them:
1348
 
1349
@itemize @bullet
1350
@item
1351
integral/integral: we compare values as you would expect.
1352
 
1353
@item
1354
fractional/integral: the fractional part is less than the integral one.
1355
Again, no surprise.
1356
 
1357
@item
1358
fractional/fractional: the things become a bit more complex.
1359
If the common prefix contains only leading zeroes, the longest part is less
1360
than the other one; else the comparison behaves normally.
1361
@end itemize
1362
 
1363
@smallexample
1364
strverscmp ("no digit", "no digit")
1365
    @result{} 0    // @r{same behavior as strcmp.}
1366
strverscmp ("item#99", "item#100")
1367
    @result{} <0   // @r{same prefix, but 99 < 100.}
1368
strverscmp ("alpha1", "alpha001")
1369
    @result{} >0   // @r{fractional part inferior to integral one.}
1370
strverscmp ("part1_f012", "part1_f01")
1371
    @result{} >0   // @r{two fractional parts.}
1372
strverscmp ("foo.009", "foo.0")
1373
    @result{} <0   // @r{idem, but with leading zeroes only.}
1374
@end smallexample
1375
 
1376
This function is especially useful when dealing with filename sorting,
1377
because filenames frequently hold indices/version numbers.
1378
@end deftypefun
1379
 
1380
@c tmpnam.c:3
1381
@deftypefn Supplemental char* tmpnam (char *@var{s})
1382
 
1383
This function attempts to create a name for a temporary file, which
1384
will be a valid file name yet not exist when @code{tmpnam} checks for
1385
it.  @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
1386
or be @code{NULL}.  Use of this function creates a security risk, and it must
1387
not be used in new projects.  Use @code{mkstemp} instead.
1388
 
1389
@end deftypefn
1390
 
1391
@c unlink-if-ordinary.c:27
1392
@deftypefn Supplemental int unlink_if_ordinary (const char*)
1393
 
1394
Unlinks the named file, unless it is special (e.g. a device file).
1395
Returns 0 when the file was unlinked, a negative value (and errno set) when
1396
there was an error deleting the file, and a positive value if no attempt
1397
was made to unlink the file because it is special.
1398
 
1399
@end deftypefn
1400
 
1401
@c fopen_unlocked.c:31
1402
@deftypefn Extension void unlock_std_streams (void)
1403
 
1404
If the OS supports it, ensure that the standard I/O streams,
1405
@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
1406
multi-threaded locking.  Otherwise do nothing.
1407
 
1408
@end deftypefn
1409
 
1410
@c fopen_unlocked.c:23
1411
@deftypefn Extension void unlock_stream (FILE * @var{stream})
1412
 
1413
If the OS supports it, ensure that the supplied stream is setup to
1414
avoid any multi-threaded locking.  Otherwise leave the @code{FILE}
1415
pointer unchanged.  If the @var{stream} is @code{NULL} do nothing.
1416
 
1417
@end deftypefn
1418
 
1419
@c vasprintf.c:47
1420
@deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
1421
 
1422
Like @code{vsprintf}, but instead of passing a pointer to a buffer,
1423
you pass a pointer to a pointer.  This function will compute the size
1424
of the buffer needed, allocate memory with @code{malloc}, and store a
1425
pointer to the allocated memory in @code{*@var{resptr}}.  The value
1426
returned is the same as @code{vsprintf} would return.  If memory could
1427
not be allocated, minus one is returned and @code{NULL} is stored in
1428
@code{*@var{resptr}}.
1429
 
1430
@end deftypefn
1431
 
1432
@c vfork.c:6
1433
@deftypefn Supplemental int vfork (void)
1434
 
1435
Emulates @code{vfork} by calling @code{fork} and returning its value.
1436
 
1437
@end deftypefn
1438
 
1439
@c vprintf.c:3
1440
@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
1441
@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
1442
@deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
1443
 
1444
These functions are the same as @code{printf}, @code{fprintf}, and
1445
@code{sprintf}, respectively, except that they are called with a
1446
@code{va_list} instead of a variable number of arguments.  Note that
1447
they do not call @code{va_end}; this is the application's
1448
responsibility.  In @libib{} they are implemented in terms of the
1449
nonstandard but common function @code{_doprnt}.
1450
 
1451
@end deftypefn
1452
 
1453
@c vsnprintf.c:28
1454
@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
1455
 
1456
This function is similar to vsprintf, but it will print at most
1457
@var{n} characters.  On error the return value is -1, otherwise it
1458
returns the number of characters that would have been printed had
1459
@var{n} been sufficiently large, regardless of the actual value of
1460
@var{n}.  Note some pre-C99 system libraries do not implement this
1461
correctly so users cannot generally rely on the return value if the
1462
system version of this function is used.
1463
 
1464
@end deftypefn
1465
 
1466
@c waitpid.c:3
1467
@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
1468
 
1469
This is a wrapper around the @code{wait} function.  Any ``special''
1470
values of @var{pid} depend on your implementation of @code{wait}, as
1471
does the return value.  The third argument is unused in @libib{}.
1472
 
1473
@end deftypefn
1474
 
1475
@c argv.c:293
1476
@deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
1477
 
1478
Write each member of ARGV, handling all necessary quoting, to the file
1479
named by FILE, separated by whitespace.  Return 0 on success, non-zero
1480
if an error occurred while writing to FILE.
1481
 
1482
@end deftypefn
1483
 
1484
@c xatexit.c:11
1485
@deftypefun int xatexit (void (*@var{fn}) (void))
1486
 
1487
Behaves as the standard @code{atexit} function, but with no limit on
1488
the number of registered functions.  Returns 0 on success, or @minus{}1 on
1489
failure.  If you use @code{xatexit} to register functions, you must use
1490
@code{xexit} to terminate your program.
1491
 
1492
@end deftypefun
1493
 
1494
@c xmalloc.c:38
1495
@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
1496
 
1497
Allocate memory without fail, and set it to zero.  This routine functions
1498
like @code{calloc}, but will behave the same as @code{xmalloc} if memory
1499
cannot be found.
1500
 
1501
@end deftypefn
1502
 
1503
@c xexit.c:22
1504
@deftypefn Replacement void xexit (int @var{code})
1505
 
1506
Terminates the program.  If any functions have been registered with
1507
the @code{xatexit} replacement function, they will be called first.
1508
Termination is handled via the system's normal @code{exit} call.
1509
 
1510
@end deftypefn
1511
 
1512
@c xmalloc.c:22
1513
@deftypefn Replacement void* xmalloc (size_t)
1514
 
1515
Allocate memory without fail.  If @code{malloc} fails, this will print
1516
a message to @code{stderr} (using the name set by
1517
@code{xmalloc_set_program_name},
1518
if any) and then call @code{xexit}.  Note that it is therefore safe for
1519
a program to contain @code{#define malloc xmalloc} in its source.
1520
 
1521
@end deftypefn
1522
 
1523
@c xmalloc.c:53
1524
@deftypefn Replacement void xmalloc_failed (size_t)
1525
 
1526
This function is not meant to be called by client code, and is listed
1527
here for completeness only.  If any of the allocation routines fail, this
1528
function will be called to print an error message and terminate execution.
1529
 
1530
@end deftypefn
1531
 
1532
@c xmalloc.c:46
1533
@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
1534
 
1535
You can use this to set the name of the program used by
1536
@code{xmalloc_failed} when printing a failure message.
1537
 
1538
@end deftypefn
1539
 
1540
@c xmemdup.c:7
1541
@deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
1542
 
1543
Duplicates a region of memory without fail.  First, @var{alloc_size} bytes
1544
are allocated, then @var{copy_size} bytes from @var{input} are copied into
1545
it, and the new memory is returned.  If fewer bytes are copied than were
1546
allocated, the remaining memory is zeroed.
1547
 
1548
@end deftypefn
1549
 
1550
@c xmalloc.c:32
1551
@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
1552
Reallocate memory without fail.  This routine functions like @code{realloc},
1553
but will behave the same as @code{xmalloc} if memory cannot be found.
1554
 
1555
@end deftypefn
1556
 
1557
@c xstrdup.c:7
1558
@deftypefn Replacement char* xstrdup (const char *@var{s})
1559
 
1560
Duplicates a character string without fail, using @code{xmalloc} to
1561
obtain memory.
1562
 
1563
@end deftypefn
1564
 
1565
@c xstrerror.c:7
1566
@deftypefn Replacement char* xstrerror (int @var{errnum})
1567
 
1568
Behaves exactly like the standard @code{strerror} function, but
1569
will never return a @code{NULL} pointer.
1570
 
1571
@end deftypefn
1572
 
1573
@c xstrndup.c:23
1574
@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
1575
 
1576
Returns a pointer to a copy of @var{s} with at most @var{n} characters
1577
without fail, using @code{xmalloc} to obtain memory.  The result is
1578
always NUL terminated.
1579
 
1580
@end deftypefn
1581
 
1582
 

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.