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

Subversion Repositories openrisc_me

[/] [openrisc/] [trunk/] [gnu-src/] [gcc-4.5.1/] [libiberty/] [functions.texi] - Blame information for rev 387

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

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

powered by: WebSVN 2.1.0

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