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