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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gdb-6.8/] [libiberty/] [functions.texi] - Blame information for rev 855

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

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

powered by: WebSVN 2.1.0

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