|
0
|
1 @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}. If you have not
|
|
|
692 yet called @code{pex_get_times} or @code{pex_get_status}, this will
|
|
|
693 try to kill the subprocesses.
|
|
|
694
|
|
|
695 @end deftypefn
|
|
|
696
|
|
|
697 @c pexecute.txh:241
|
|
|
698 @deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, int @var{count}, int *@var{vector})
|
|
|
699
|
|
|
700 Returns the exit status of all programs run using @var{obj}.
|
|
|
701 @var{count} is the number of results expected. The results will be
|
|
|
702 placed into @var{vector}. The results are in the order of the calls
|
|
|
703 to @code{pex_run}. Returns 0 on error, 1 on success.
|
|
|
704
|
|
|
705 @end deftypefn
|
|
|
706
|
|
|
707 @c pexecute.txh:250
|
|
|
708 @deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, int @var{count}, struct pex_time *@var{vector})
|
|
|
709
|
|
|
710 Returns the process execution times of all programs run using
|
|
|
711 @var{obj}. @var{count} is the number of results expected. The
|
|
|
712 results will be placed into @var{vector}. The results are in the
|
|
|
713 order of the calls to @code{pex_run}. Returns 0 on error, 1 on
|
|
|
714 success.
|
|
|
715
|
|
|
716 @code{struct pex_time} has the following fields of the type
|
|
|
717 @code{unsigned long}: @code{user_seconds},
|
|
|
718 @code{user_microseconds}, @code{system_seconds},
|
|
|
719 @code{system_microseconds}. On systems which do not support reporting
|
|
|
720 process times, all the fields will be set to @code{0}.
|
|
|
721
|
|
|
722 @end deftypefn
|
|
|
723
|
|
|
724 @c pexecute.txh:2
|
|
|
725 @deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, const char *@var{pname}, const char *@var{tempbase})
|
|
|
726
|
|
|
727 Prepare to execute one or more programs, with standard output of each
|
|
|
728 program fed to standard input of the next. This is a system
|
|
|
729 independent interface to execute a pipeline.
|
|
|
730
|
|
|
731 @var{flags} is a bitwise combination of the following:
|
|
|
732
|
|
|
733 @table @code
|
|
|
734
|
|
|
735 @vindex PEX_RECORD_TIMES
|
|
|
736 @item PEX_RECORD_TIMES
|
|
|
737 Record subprocess times if possible.
|
|
|
738
|
|
|
739 @vindex PEX_USE_PIPES
|
|
|
740 @item PEX_USE_PIPES
|
|
|
741 Use pipes for communication between processes, if possible.
|
|
|
742
|
|
|
743 @vindex PEX_SAVE_TEMPS
|
|
|
744 @item PEX_SAVE_TEMPS
|
|
|
745 Don't delete temporary files used for communication between
|
|
|
746 processes.
|
|
|
747
|
|
|
748 @end table
|
|
|
749
|
|
|
750 @var{pname} is the name of program to be executed, used in error
|
|
|
751 messages. @var{tempbase} is a base name to use for any required
|
|
|
752 temporary files; it may be @code{NULL} to use a randomly chosen name.
|
|
|
753
|
|
|
754 @end deftypefn
|
|
|
755
|
|
|
756 @c pexecute.txh:155
|
|
|
757 @deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, int @var{flags}, const char *@var{in_name})
|
|
|
758
|
|
|
759 Return a stream for a temporary file to pass to the first program in
|
|
|
760 the pipeline as input.
|
|
|
761
|
|
|
762 The name of the input file is chosen according to the same rules
|
|
|
763 @code{pex_run} uses to choose output file names, based on
|
|
|
764 @var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}.
|
|
|
765
|
|
|
766 Don't call @code{fclose} on the returned stream; the first call to
|
|
|
767 @code{pex_run} closes it automatically.
|
|
|
768
|
|
|
769 If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in
|
|
|
770 binary mode; otherwise, open it in the default mode. Including
|
|
|
771 @code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix.
|
|
|
772 @end deftypefn
|
|
|
773
|
|
|
774 @c pexecute.txh:172
|
|
|
775 @deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, int @var{binary})
|
|
|
776
|
|
|
777 Return a stream @var{fp} for a pipe connected to the standard input of
|
|
|
778 the first program in the pipeline; @var{fp} is opened for writing.
|
|
|
779 You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call
|
|
|
780 that returned @var{obj}.
|
|
|
781
|
|
|
782 You must close @var{fp} using @code{fclose} yourself when you have
|
|
|
783 finished writing data to the pipeline.
|
|
|
784
|
|
|
785 The file descriptor underlying @var{fp} is marked not to be inherited
|
|
|
786 by child processes.
|
|
|
787
|
|
|
788 On systems that do not support pipes, this function returns
|
|
|
789 @code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would
|
|
|
790 like to write code that is portable to all systems the @code{pex}
|
|
|
791 functions support, consider using @code{pex_input_file} instead.
|
|
|
792
|
|
|
793 There are two opportunities for deadlock using
|
|
|
794 @code{pex_input_pipe}:
|
|
|
795
|
|
|
796 @itemize @bullet
|
|
|
797 @item
|
|
|
798 Most systems' pipes can buffer only a fixed amount of data; a process
|
|
|
799 that writes to a full pipe blocks. Thus, if you write to @file{fp}
|
|
|
800 before starting the first process, you run the risk of blocking when
|
|
|
801 there is no child process yet to read the data and allow you to
|
|
|
802 continue. @code{pex_input_pipe} makes no promises about the
|
|
|
803 size of the pipe's buffer, so if you need to write any data at all
|
|
|
804 before starting the first process in the pipeline, consider using
|
|
|
805 @code{pex_input_file} instead.
|
|
|
806
|
|
|
807 @item
|
|
|
808 Using @code{pex_input_pipe} and @code{pex_read_output} together
|
|
|
809 may also cause deadlock. If the output pipe fills up, so that each
|
|
|
810 program in the pipeline is waiting for the next to read more data, and
|
|
|
811 you fill the input pipe by writing more data to @var{fp}, then there
|
|
|
812 is no way to make progress: the only process that could read data from
|
|
|
813 the output pipe is you, but you are blocked on the input pipe.
|
|
|
814
|
|
|
815 @end itemize
|
|
|
816
|
|
|
817 @end deftypefn
|
|
|
818
|
|
|
819 @c pexecute.txh:274
|
|
|
820 @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})
|
|
|
821
|
|
|
822 An interface to permit the easy execution of a
|
|
|
823 single program. The return value and most of the parameters are as
|
|
|
824 for a call to @code{pex_run}. @var{flags} is restricted to a
|
|
|
825 combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and
|
|
|
826 @code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if
|
|
|
827 @code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will
|
|
|
828 be set to the exit status of the program.
|
|
|
829
|
|
|
830 @end deftypefn
|
|
|
831
|
|
|
832 @c pexecute.txh:228
|
|
|
833 @deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, int @var{binary})
|
|
|
834
|
|
|
835 Returns a @code{FILE} pointer which may be used to read the standard
|
|
|
836 error of the last program in the pipeline. When this is used,
|
|
|
837 @code{PEX_LAST} should not be used in a call to @code{pex_run}. After
|
|
|
838 this is called, @code{pex_run} may no longer be called with the same
|
|
|
839 @var{obj}. @var{binary} should be non-zero if the file should be
|
|
|
840 opened in binary mode. Don't call @code{fclose} on the returned file;
|
|
|
841 it will be closed by @code{pex_free}.
|
|
|
842
|
|
|
843 @end deftypefn
|
|
|
844
|
|
|
845 @c pexecute.txh:216
|
|
|
846 @deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, int @var{binary})
|
|
|
847
|
|
|
848 Returns a @code{FILE} pointer which may be used to read the standard
|
|
|
849 output of the last program in the pipeline. When this is used,
|
|
|
850 @code{PEX_LAST} should not be used in a call to @code{pex_run}. After
|
|
|
851 this is called, @code{pex_run} may no longer be called with the same
|
|
|
852 @var{obj}. @var{binary} should be non-zero if the file should be
|
|
|
853 opened in binary mode. Don't call @code{fclose} on the returned file;
|
|
|
854 it will be closed by @code{pex_free}.
|
|
|
855
|
|
|
856 @end deftypefn
|
|
|
857
|
|
|
858 @c pexecute.txh:33
|
|
|
859 @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})
|
|
|
860
|
|
|
861 Execute one program in a pipeline. On success this returns
|
|
|
862 @code{NULL}. On failure it returns an error message, a statically
|
|
|
863 allocated string.
|
|
|
864
|
|
|
865 @var{obj} is returned by a previous call to @code{pex_init}.
|
|
|
866
|
|
|
867 @var{flags} is a bitwise combination of the following:
|
|
|
868
|
|
|
869 @table @code
|
|
|
870
|
|
|
871 @vindex PEX_LAST
|
|
|
872 @item PEX_LAST
|
|
|
873 This must be set on the last program in the pipeline. In particular,
|
|
|
874 it should be set when executing a single program. The standard output
|
|
|
875 of the program will be sent to @var{outname}, or, if @var{outname} is
|
|
|
876 @code{NULL}, to the standard output of the calling program. Do @emph{not}
|
|
|
877 set this bit if you want to call @code{pex_read_output}
|
|
|
878 (described below). After a call to @code{pex_run} with this bit set,
|
|
|
879 @var{pex_run} may no longer be called with the same @var{obj}.
|
|
|
880
|
|
|
881 @vindex PEX_SEARCH
|
|
|
882 @item PEX_SEARCH
|
|
|
883 Search for the program using the user's executable search path.
|
|
|
884
|
|
|
885 @vindex PEX_SUFFIX
|
|
|
886 @item PEX_SUFFIX
|
|
|
887 @var{outname} is a suffix. See the description of @var{outname},
|
|
|
888 below.
|
|
|
889
|
|
|
890 @vindex PEX_STDERR_TO_STDOUT
|
|
|
891 @item PEX_STDERR_TO_STDOUT
|
|
|
892 Send the program's standard error to standard output, if possible.
|
|
|
893
|
|
|
894 @vindex PEX_BINARY_INPUT
|
|
|
895 @vindex PEX_BINARY_OUTPUT
|
|
|
896 @vindex PEX_BINARY_ERROR
|
|
|
897 @item PEX_BINARY_INPUT
|
|
|
898 @itemx PEX_BINARY_OUTPUT
|
|
|
899 @itemx PEX_BINARY_ERROR
|
|
|
900 The standard input (output or error) of the program should be read (written) in
|
|
|
901 binary mode rather than text mode. These flags are ignored on systems
|
|
|
902 which do not distinguish binary mode and text mode, such as Unix. For
|
|
|
903 proper behavior these flags should match appropriately---a call to
|
|
|
904 @code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a
|
|
|
905 call using @code{PEX_BINARY_INPUT}.
|
|
|
906
|
|
|
907 @vindex PEX_STDERR_TO_PIPE
|
|
|
908 @item PEX_STDERR_TO_PIPE
|
|
|
909 Send the program's standard error to a pipe, if possible. This flag
|
|
|
910 cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This
|
|
|
911 flag can be specified only on the last program in pipeline.
|
|
|
912
|
|
|
913 @end table
|
|
|
914
|
|
|
915 @var{executable} is the program to execute. @var{argv} is the set of
|
|
|
916 arguments to pass to the program; normally @code{@var{argv}[0]} will
|
|
|
917 be a copy of @var{executable}.
|
|
|
918
|
|
|
919 @var{outname} is used to set the name of the file to use for standard
|
|
|
920 output. There are two cases in which no output file will be used:
|
|
|
921
|
|
|
922 @enumerate
|
|
|
923 @item
|
|
|
924 if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES}
|
|
|
925 was set in the call to @code{pex_init}, and the system supports pipes
|
|
|
926
|
|
|
927 @item
|
|
|
928 if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is
|
|
|
929 @code{NULL}
|
|
|
930 @end enumerate
|
|
|
931
|
|
|
932 @noindent
|
|
|
933 Otherwise the code will use a file to hold standard
|
|
|
934 output. If @code{PEX_LAST} is not set, this file is considered to be
|
|
|
935 a temporary file, and it will be removed when no longer needed, unless
|
|
|
936 @code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}.
|
|
|
937
|
|
|
938 There are two cases to consider when setting the name of the file to
|
|
|
939 hold standard output.
|
|
|
940
|
|
|
941 @enumerate
|
|
|
942 @item
|
|
|
943 @code{PEX_SUFFIX} is set in @var{flags}. In this case
|
|
|
944 @var{outname} may not be @code{NULL}. If the @var{tempbase} parameter
|
|
|
945 to @code{pex_init} was not @code{NULL}, then the output file name is
|
|
|
946 the concatenation of @var{tempbase} and @var{outname}. If
|
|
|
947 @var{tempbase} was @code{NULL}, then the output file name is a random
|
|
|
948 file name ending in @var{outname}.
|
|
|
949
|
|
|
950 @item
|
|
|
951 @code{PEX_SUFFIX} was not set in @var{flags}. In this
|
|
|
952 case, if @var{outname} is not @code{NULL}, it is used as the output
|
|
|
953 file name. If @var{outname} is @code{NULL}, and @var{tempbase} was
|
|
|
954 not NULL, the output file name is randomly chosen using
|
|
|
955 @var{tempbase}. Otherwise the output file name is chosen completely
|
|
|
956 at random.
|
|
|
957 @end enumerate
|
|
|
958
|
|
|
959 @var{errname} is the file name to use for standard error output. If
|
|
|
960 it is @code{NULL}, standard error is the same as the caller's.
|
|
|
961 Otherwise, standard error is written to the named file.
|
|
|
962
|
|
|
963 On an error return, the code sets @code{*@var{err}} to an @code{errno}
|
|
|
964 value, or to 0 if there is no relevant @code{errno}.
|
|
|
965
|
|
|
966 @end deftypefn
|
|
|
967
|
|
|
968 @c pexecute.txh:142
|
|
|
969 @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})
|
|
|
970
|
|
|
971 Execute one program in a pipeline, permitting the environment for the
|
|
|
972 program to be specified. Behaviour and parameters not listed below are
|
|
|
973 as for @code{pex_run}.
|
|
|
974
|
|
|
975 @var{env} is the environment for the child process, specified as an array of
|
|
|
976 character pointers. Each element of the array should point to a string of the
|
|
|
977 form @code{VAR=VALUE}, with the exception of the last element that must be
|
|
|
978 @code{NULL}.
|
|
|
979
|
|
|
980 @end deftypefn
|
|
|
981
|
|
|
982 @c pexecute.txh:286
|
|
|
983 @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})
|
|
|
984
|
|
|
985 This is the old interface to execute one or more programs. It is
|
|
|
986 still supported for compatibility purposes, but is no longer
|
|
|
987 documented.
|
|
|
988
|
|
|
989 @end deftypefn
|
|
|
990
|
|
|
991 @c strsignal.c:541
|
|
|
992 @deftypefn Supplemental void psignal (int @var{signo}, char *@var{message})
|
|
|
993
|
|
|
994 Print @var{message} to the standard error, followed by a colon,
|
|
|
995 followed by the description of the signal specified by @var{signo},
|
|
|
996 followed by a newline.
|
|
|
997
|
|
|
998 @end deftypefn
|
|
|
999
|
|
|
1000 @c putenv.c:21
|
|
|
1001 @deftypefn Supplemental int putenv (const char *@var{string})
|
|
|
1002
|
|
|
1003 Uses @code{setenv} or @code{unsetenv} to put @var{string} into
|
|
|
1004 the environment or remove it. If @var{string} is of the form
|
|
|
1005 @samp{name=value} the string is added; if no @samp{=} is present the
|
|
|
1006 name is unset/removed.
|
|
|
1007
|
|
|
1008 @end deftypefn
|
|
|
1009
|
|
|
1010 @c pexecute.txh:294
|
|
|
1011 @deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags})
|
|
|
1012
|
|
|
1013 Another part of the old execution interface.
|
|
|
1014
|
|
|
1015 @end deftypefn
|
|
|
1016
|
|
|
1017 @c random.c:39
|
|
|
1018 @deftypefn Supplement {long int} random (void)
|
|
|
1019 @deftypefnx Supplement void srandom (unsigned int @var{seed})
|
|
|
1020 @deftypefnx Supplement void* initstate (unsigned int @var{seed}, void *@var{arg_state}, unsigned long @var{n})
|
|
|
1021 @deftypefnx Supplement void* setstate (void *@var{arg_state})
|
|
|
1022
|
|
|
1023 Random number functions. @code{random} returns a random number in the
|
|
|
1024 range 0 to @code{LONG_MAX}. @code{srandom} initializes the random
|
|
|
1025 number generator to some starting point determined by @var{seed}
|
|
|
1026 (else, the values returned by @code{random} are always the same for each
|
|
|
1027 run of the program). @code{initstate} and @code{setstate} allow fine-grained
|
|
|
1028 control over the state of the random number generator.
|
|
|
1029
|
|
|
1030 @end deftypefn
|
|
|
1031
|
|
|
1032 @c concat.c:173
|
|
|
1033 @deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @dots{}, @code{NULL})
|
|
|
1034
|
|
|
1035 Same as @code{concat}, except that if @var{optr} is not @code{NULL} it
|
|
|
1036 is freed after the string is created. This is intended to be useful
|
|
|
1037 when you're extending an existing string or building up a string in a
|
|
|
1038 loop:
|
|
|
1039
|
|
|
1040 @example
|
|
|
1041 str = reconcat (str, "pre-", str, NULL);
|
|
|
1042 @end example
|
|
|
1043
|
|
|
1044 @end deftypefn
|
|
|
1045
|
|
|
1046 @c rename.c:6
|
|
|
1047 @deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new})
|
|
|
1048
|
|
|
1049 Renames a file from @var{old} to @var{new}. If @var{new} already
|
|
|
1050 exists, it is removed.
|
|
|
1051
|
|
|
1052 @end deftypefn
|
|
|
1053
|
|
|
1054 @c rindex.c:5
|
|
|
1055 @deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c})
|
|
|
1056
|
|
|
1057 Returns a pointer to the last occurrence of the character @var{c} in
|
|
|
1058 the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is
|
|
|
1059 deprecated in new programs in favor of @code{strrchr}.
|
|
|
1060
|
|
|
1061 @end deftypefn
|
|
|
1062
|
|
|
1063 @c setenv.c:22
|
|
|
1064 @deftypefn Supplemental int setenv (const char *@var{name}, const char *@var{value}, int @var{overwrite})
|
|
|
1065 @deftypefnx Supplemental void unsetenv (const char *@var{name})
|
|
|
1066
|
|
|
1067 @code{setenv} adds @var{name} to the environment with value
|
|
|
1068 @var{value}. If the name was already present in the environment,
|
|
|
1069 the new value will be stored only if @var{overwrite} is nonzero.
|
|
|
1070 The companion @code{unsetenv} function removes @var{name} from the
|
|
|
1071 environment. This implementation is not safe for multithreaded code.
|
|
|
1072
|
|
|
1073 @end deftypefn
|
|
|
1074
|
|
|
1075 @c strsignal.c:348
|
|
|
1076 @deftypefn Extension int signo_max (void)
|
|
|
1077
|
|
|
1078 Returns the maximum signal value for which a corresponding symbolic
|
|
|
1079 name or message is available. Note that in the case where we use the
|
|
|
1080 @code{sys_siglist} supplied by the system, it is possible for there to
|
|
|
1081 be more symbolic names than messages, or vice versa. In fact, the
|
|
|
1082 manual page for @code{psignal(3b)} explicitly warns that one should
|
|
|
1083 check the size of the table (@code{NSIG}) before indexing it, since
|
|
|
1084 new signal codes may be added to the system before they are added to
|
|
|
1085 the table. Thus @code{NSIG} might be smaller than value implied by
|
|
|
1086 the largest signo value defined in @code{<signal.h>}.
|
|
|
1087
|
|
|
1088 We return the maximum value that can be used to obtain a meaningful
|
|
|
1089 symbolic name or message.
|
|
|
1090
|
|
|
1091 @end deftypefn
|
|
|
1092
|
|
|
1093 @c sigsetmask.c:8
|
|
|
1094 @deftypefn Supplemental int sigsetmask (int @var{set})
|
|
|
1095
|
|
|
1096 Sets the signal mask to the one provided in @var{set} and returns
|
|
|
1097 the old mask (which, for libiberty's implementation, will always
|
|
|
1098 be the value @code{1}).
|
|
|
1099
|
|
|
1100 @end deftypefn
|
|
|
1101
|
|
|
1102 @c snprintf.c:28
|
|
|
1103 @deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, ...)
|
|
|
1104
|
|
|
1105 This function is similar to sprintf, but it will print at most @var{n}
|
|
|
1106 characters. On error the return value is -1, otherwise it returns the
|
|
|
1107 number of characters that would have been printed had @var{n} been
|
|
|
1108 sufficiently large, regardless of the actual value of @var{n}. Note
|
|
|
1109 some pre-C99 system libraries do not implement this correctly so users
|
|
|
1110 cannot generally rely on the return value if the system version of
|
|
|
1111 this function is used.
|
|
|
1112
|
|
|
1113 @end deftypefn
|
|
|
1114
|
|
|
1115 @c spaces.c:22
|
|
|
1116 @deftypefn Extension char* spaces (int @var{count})
|
|
|
1117
|
|
|
1118 Returns a pointer to a memory region filled with the specified
|
|
|
1119 number of spaces and null terminated. The returned pointer is
|
|
|
1120 valid until at least the next call.
|
|
|
1121
|
|
|
1122 @end deftypefn
|
|
|
1123
|
|
|
1124 @c stpcpy.c:23
|
|
|
1125 @deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src})
|
|
|
1126
|
|
|
1127 Copies the string @var{src} into @var{dst}. Returns a pointer to
|
|
|
1128 @var{dst} + strlen(@var{src}).
|
|
|
1129
|
|
|
1130 @end deftypefn
|
|
|
1131
|
|
|
1132 @c stpncpy.c:23
|
|
|
1133 @deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, size_t @var{len})
|
|
|
1134
|
|
|
1135 Copies the string @var{src} into @var{dst}, copying exactly @var{len}
|
|
|
1136 and padding with zeros if necessary. If @var{len} < strlen(@var{src})
|
|
|
1137 then return @var{dst} + @var{len}, otherwise returns @var{dst} +
|
|
|
1138 strlen(@var{src}).
|
|
|
1139
|
|
|
1140 @end deftypefn
|
|
|
1141
|
|
|
1142 @c strcasecmp.c:15
|
|
|
1143 @deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2})
|
|
|
1144
|
|
|
1145 A case-insensitive @code{strcmp}.
|
|
|
1146
|
|
|
1147 @end deftypefn
|
|
|
1148
|
|
|
1149 @c strchr.c:6
|
|
|
1150 @deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c})
|
|
|
1151
|
|
|
1152 Returns a pointer to the first occurrence of the character @var{c} in
|
|
|
1153 the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the
|
|
|
1154 null character, the results are undefined.
|
|
|
1155
|
|
|
1156 @end deftypefn
|
|
|
1157
|
|
|
1158 @c strdup.c:3
|
|
|
1159 @deftypefn Supplemental char* strdup (const char *@var{s})
|
|
|
1160
|
|
|
1161 Returns a pointer to a copy of @var{s} in memory obtained from
|
|
|
1162 @code{malloc}, or @code{NULL} if insufficient memory was available.
|
|
|
1163
|
|
|
1164 @end deftypefn
|
|
|
1165
|
|
|
1166 @c strerror.c:670
|
|
|
1167 @deftypefn Replacement {const char*} strerrno (int @var{errnum})
|
|
|
1168
|
|
|
1169 Given an error number returned from a system call (typically returned
|
|
|
1170 in @code{errno}), returns a pointer to a string containing the
|
|
|
1171 symbolic name of that error number, as found in @code{<errno.h>}.
|
|
|
1172
|
|
|
1173 If the supplied error number is within the valid range of indices for
|
|
|
1174 symbolic names, but no name is available for the particular error
|
|
|
1175 number, then returns the string @samp{Error @var{num}}, where @var{num}
|
|
|
1176 is the error number.
|
|
|
1177
|
|
|
1178 If the supplied error number is not within the range of valid
|
|
|
1179 indices, then returns @code{NULL}.
|
|
|
1180
|
|
|
1181 The contents of the location pointed to are only guaranteed to be
|
|
|
1182 valid until the next call to @code{strerrno}.
|
|
|
1183
|
|
|
1184 @end deftypefn
|
|
|
1185
|
|
|
1186 @c strerror.c:603
|
|
|
1187 @deftypefn Supplemental char* strerror (int @var{errnoval})
|
|
|
1188
|
|
|
1189 Maps an @code{errno} number to an error message string, the contents
|
|
|
1190 of which are implementation defined. On systems which have the
|
|
|
1191 external variables @code{sys_nerr} and @code{sys_errlist}, these
|
|
|
1192 strings will be the same as the ones used by @code{perror}.
|
|
|
1193
|
|
|
1194 If the supplied error number is within the valid range of indices for
|
|
|
1195 the @code{sys_errlist}, but no message is available for the particular
|
|
|
1196 error number, then returns the string @samp{Error @var{num}}, where
|
|
|
1197 @var{num} is the error number.
|
|
|
1198
|
|
|
1199 If the supplied error number is not a valid index into
|
|
|
1200 @code{sys_errlist}, returns @code{NULL}.
|
|
|
1201
|
|
|
1202 The returned string is only guaranteed to be valid only until the
|
|
|
1203 next call to @code{strerror}.
|
|
|
1204
|
|
|
1205 @end deftypefn
|
|
|
1206
|
|
|
1207 @c strncasecmp.c:15
|
|
|
1208 @deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2})
|
|
|
1209
|
|
|
1210 A case-insensitive @code{strncmp}.
|
|
|
1211
|
|
|
1212 @end deftypefn
|
|
|
1213
|
|
|
1214 @c strncmp.c:6
|
|
|
1215 @deftypefn Supplemental int strncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n})
|
|
|
1216
|
|
|
1217 Compares the first @var{n} bytes of two strings, returning a value as
|
|
|
1218 @code{strcmp}.
|
|
|
1219
|
|
|
1220 @end deftypefn
|
|
|
1221
|
|
|
1222 @c strndup.c:23
|
|
|
1223 @deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n})
|
|
|
1224
|
|
|
1225 Returns a pointer to a copy of @var{s} with at most @var{n} characters
|
|
|
1226 in memory obtained from @code{malloc}, or @code{NULL} if insufficient
|
|
|
1227 memory was available. The result is always NUL terminated.
|
|
|
1228
|
|
|
1229 @end deftypefn
|
|
|
1230
|
|
|
1231 @c strrchr.c:6
|
|
|
1232 @deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c})
|
|
|
1233
|
|
|
1234 Returns a pointer to the last occurrence of the character @var{c} in
|
|
|
1235 the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the
|
|
|
1236 null character, the results are undefined.
|
|
|
1237
|
|
|
1238 @end deftypefn
|
|
|
1239
|
|
|
1240 @c strsignal.c:383
|
|
|
1241 @deftypefn Supplemental {const char *} strsignal (int @var{signo})
|
|
|
1242
|
|
|
1243 Maps an signal number to an signal message string, the contents of
|
|
|
1244 which are implementation defined. On systems which have the external
|
|
|
1245 variable @code{sys_siglist}, these strings will be the same as the
|
|
|
1246 ones used by @code{psignal()}.
|
|
|
1247
|
|
|
1248 If the supplied signal number is within the valid range of indices for
|
|
|
1249 the @code{sys_siglist}, but no message is available for the particular
|
|
|
1250 signal number, then returns the string @samp{Signal @var{num}}, where
|
|
|
1251 @var{num} is the signal number.
|
|
|
1252
|
|
|
1253 If the supplied signal number is not a valid index into
|
|
|
1254 @code{sys_siglist}, returns @code{NULL}.
|
|
|
1255
|
|
|
1256 The returned string is only guaranteed to be valid only until the next
|
|
|
1257 call to @code{strsignal}.
|
|
|
1258
|
|
|
1259 @end deftypefn
|
|
|
1260
|
|
|
1261 @c strsignal.c:448
|
|
|
1262 @deftypefn Extension {const char*} strsigno (int @var{signo})
|
|
|
1263
|
|
|
1264 Given an signal number, returns a pointer to a string containing the
|
|
|
1265 symbolic name of that signal number, as found in @code{<signal.h>}.
|
|
|
1266
|
|
|
1267 If the supplied signal number is within the valid range of indices for
|
|
|
1268 symbolic names, but no name is available for the particular signal
|
|
|
1269 number, then returns the string @samp{Signal @var{num}}, where
|
|
|
1270 @var{num} is the signal number.
|
|
|
1271
|
|
|
1272 If the supplied signal number is not within the range of valid
|
|
|
1273 indices, then returns @code{NULL}.
|
|
|
1274
|
|
|
1275 The contents of the location pointed to are only guaranteed to be
|
|
|
1276 valid until the next call to @code{strsigno}.
|
|
|
1277
|
|
|
1278 @end deftypefn
|
|
|
1279
|
|
|
1280 @c strstr.c:6
|
|
|
1281 @deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub})
|
|
|
1282
|
|
|
1283 This function searches for the substring @var{sub} in the string
|
|
|
1284 @var{string}, not including the terminating null characters. A pointer
|
|
|
1285 to the first occurrence of @var{sub} is returned, or @code{NULL} if the
|
|
|
1286 substring is absent. If @var{sub} points to a string with zero
|
|
|
1287 length, the function returns @var{string}.
|
|
|
1288
|
|
|
1289 @end deftypefn
|
|
|
1290
|
|
|
1291 @c strtod.c:27
|
|
|
1292 @deftypefn Supplemental double strtod (const char *@var{string}, char **@var{endptr})
|
|
|
1293
|
|
|
1294 This ISO C function converts the initial portion of @var{string} to a
|
|
|
1295 @code{double}. If @var{endptr} is not @code{NULL}, a pointer to the
|
|
|
1296 character after the last character used in the conversion is stored in
|
|
|
1297 the location referenced by @var{endptr}. If no conversion is
|
|
|
1298 performed, zero is returned and the value of @var{string} is stored in
|
|
|
1299 the location referenced by @var{endptr}.
|
|
|
1300
|
|
|
1301 @end deftypefn
|
|
|
1302
|
|
|
1303 @c strerror.c:729
|
|
|
1304 @deftypefn Extension int strtoerrno (const char *@var{name})
|
|
|
1305
|
|
|
1306 Given the symbolic name of a error number (e.g., @code{EACCES}), map it
|
|
|
1307 to an errno value. If no translation is found, returns 0.
|
|
|
1308
|
|
|
1309 @end deftypefn
|
|
|
1310
|
|
|
1311 @c strtol.c:33
|
|
|
1312 @deftypefn Supplemental {long int} strtol (const char *@var{string}, char **@var{endptr}, int @var{base})
|
|
|
1313 @deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, char **@var{endptr}, int @var{base})
|
|
|
1314
|
|
|
1315 The @code{strtol} function converts the string in @var{string} to a
|
|
|
1316 long integer value according to the given @var{base}, which must be
|
|
|
1317 between 2 and 36 inclusive, or be the special value 0. If @var{base}
|
|
|
1318 is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x}
|
|
|
1319 to indicate bases 8 and 16, respectively, else default to base 10.
|
|
|
1320 When the base is 16 (either explicitly or implicitly), a prefix of
|
|
|
1321 @code{0x} is allowed. The handling of @var{endptr} is as that of
|
|
|
1322 @code{strtod} above. The @code{strtoul} function is the same, except
|
|
|
1323 that the converted value is unsigned.
|
|
|
1324
|
|
|
1325 @end deftypefn
|
|
|
1326
|
|
|
1327 @c strsignal.c:502
|
|
|
1328 @deftypefn Extension int strtosigno (const char *@var{name})
|
|
|
1329
|
|
|
1330 Given the symbolic name of a signal, map it to a signal number. If no
|
|
|
1331 translation is found, returns 0.
|
|
|
1332
|
|
|
1333 @end deftypefn
|
|
|
1334
|
|
|
1335 @c strverscmp.c:25
|
|
|
1336 @deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2})
|
|
|
1337 The @code{strverscmp} function compares the string @var{s1} against
|
|
|
1338 @var{s2}, considering them as holding indices/version numbers. Return
|
|
|
1339 value follows the same conventions as found in the @code{strverscmp}
|
|
|
1340 function. In fact, if @var{s1} and @var{s2} contain no digits,
|
|
|
1341 @code{strverscmp} behaves like @code{strcmp}.
|
|
|
1342
|
|
|
1343 Basically, we compare strings normally (character by character), until
|
|
|
1344 we find a digit in each string - then we enter a special comparison
|
|
|
1345 mode, where each sequence of digits is taken as a whole. If we reach the
|
|
|
1346 end of these two parts without noticing a difference, we return to the
|
|
|
1347 standard comparison mode. There are two types of numeric parts:
|
|
|
1348 "integral" and "fractional" (those begin with a '0'). The types
|
|
|
1349 of the numeric parts affect the way we sort them:
|
|
|
1350
|
|
|
1351 @itemize @bullet
|
|
|
1352 @item
|
|
|
1353 integral/integral: we compare values as you would expect.
|
|
|
1354
|
|
|
1355 @item
|
|
|
1356 fractional/integral: the fractional part is less than the integral one.
|
|
|
1357 Again, no surprise.
|
|
|
1358
|
|
|
1359 @item
|
|
|
1360 fractional/fractional: the things become a bit more complex.
|
|
|
1361 If the common prefix contains only leading zeroes, the longest part is less
|
|
|
1362 than the other one; else the comparison behaves normally.
|
|
|
1363 @end itemize
|
|
|
1364
|
|
|
1365 @smallexample
|
|
|
1366 strverscmp ("no digit", "no digit")
|
|
|
1367 @result{} 0 // @r{same behavior as strcmp.}
|
|
|
1368 strverscmp ("item#99", "item#100")
|
|
|
1369 @result{} <0 // @r{same prefix, but 99 < 100.}
|
|
|
1370 strverscmp ("alpha1", "alpha001")
|
|
|
1371 @result{} >0 // @r{fractional part inferior to integral one.}
|
|
|
1372 strverscmp ("part1_f012", "part1_f01")
|
|
|
1373 @result{} >0 // @r{two fractional parts.}
|
|
|
1374 strverscmp ("foo.009", "foo.0")
|
|
|
1375 @result{} <0 // @r{idem, but with leading zeroes only.}
|
|
|
1376 @end smallexample
|
|
|
1377
|
|
|
1378 This function is especially useful when dealing with filename sorting,
|
|
|
1379 because filenames frequently hold indices/version numbers.
|
|
|
1380 @end deftypefun
|
|
|
1381
|
|
|
1382 @c tmpnam.c:3
|
|
|
1383 @deftypefn Supplemental char* tmpnam (char *@var{s})
|
|
|
1384
|
|
|
1385 This function attempts to create a name for a temporary file, which
|
|
|
1386 will be a valid file name yet not exist when @code{tmpnam} checks for
|
|
|
1387 it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes,
|
|
|
1388 or be @code{NULL}. Use of this function creates a security risk, and it must
|
|
|
1389 not be used in new projects. Use @code{mkstemp} instead.
|
|
|
1390
|
|
|
1391 @end deftypefn
|
|
|
1392
|
|
|
1393 @c unlink-if-ordinary.c:27
|
|
|
1394 @deftypefn Supplemental int unlink_if_ordinary (const char*)
|
|
|
1395
|
|
|
1396 Unlinks the named file, unless it is special (e.g. a device file).
|
|
|
1397 Returns 0 when the file was unlinked, a negative value (and errno set) when
|
|
|
1398 there was an error deleting the file, and a positive value if no attempt
|
|
|
1399 was made to unlink the file because it is special.
|
|
|
1400
|
|
|
1401 @end deftypefn
|
|
|
1402
|
|
|
1403 @c fopen_unlocked.c:31
|
|
|
1404 @deftypefn Extension void unlock_std_streams (void)
|
|
|
1405
|
|
|
1406 If the OS supports it, ensure that the standard I/O streams,
|
|
|
1407 @code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any
|
|
|
1408 multi-threaded locking. Otherwise do nothing.
|
|
|
1409
|
|
|
1410 @end deftypefn
|
|
|
1411
|
|
|
1412 @c fopen_unlocked.c:23
|
|
|
1413 @deftypefn Extension void unlock_stream (FILE * @var{stream})
|
|
|
1414
|
|
|
1415 If the OS supports it, ensure that the supplied stream is setup to
|
|
|
1416 avoid any multi-threaded locking. Otherwise leave the @code{FILE}
|
|
|
1417 pointer unchanged. If the @var{stream} is @code{NULL} do nothing.
|
|
|
1418
|
|
|
1419 @end deftypefn
|
|
|
1420
|
|
|
1421 @c vasprintf.c:47
|
|
|
1422 @deftypefn Extension int vasprintf (char **@var{resptr}, const char *@var{format}, va_list @var{args})
|
|
|
1423
|
|
|
1424 Like @code{vsprintf}, but instead of passing a pointer to a buffer,
|
|
|
1425 you pass a pointer to a pointer. This function will compute the size
|
|
|
1426 of the buffer needed, allocate memory with @code{malloc}, and store a
|
|
|
1427 pointer to the allocated memory in @code{*@var{resptr}}. The value
|
|
|
1428 returned is the same as @code{vsprintf} would return. If memory could
|
|
|
1429 not be allocated, minus one is returned and @code{NULL} is stored in
|
|
|
1430 @code{*@var{resptr}}.
|
|
|
1431
|
|
|
1432 @end deftypefn
|
|
|
1433
|
|
|
1434 @c vfork.c:6
|
|
|
1435 @deftypefn Supplemental int vfork (void)
|
|
|
1436
|
|
|
1437 Emulates @code{vfork} by calling @code{fork} and returning its value.
|
|
|
1438
|
|
|
1439 @end deftypefn
|
|
|
1440
|
|
|
1441 @c vprintf.c:3
|
|
|
1442 @deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap})
|
|
|
1443 @deftypefnx Supplemental int vfprintf (FILE *@var{stream}, const char *@var{format}, va_list @var{ap})
|
|
|
1444 @deftypefnx Supplemental int vsprintf (char *@var{str}, const char *@var{format}, va_list @var{ap})
|
|
|
1445
|
|
|
1446 These functions are the same as @code{printf}, @code{fprintf}, and
|
|
|
1447 @code{sprintf}, respectively, except that they are called with a
|
|
|
1448 @code{va_list} instead of a variable number of arguments. Note that
|
|
|
1449 they do not call @code{va_end}; this is the application's
|
|
|
1450 responsibility. In @libib{} they are implemented in terms of the
|
|
|
1451 nonstandard but common function @code{_doprnt}.
|
|
|
1452
|
|
|
1453 @end deftypefn
|
|
|
1454
|
|
|
1455 @c vsnprintf.c:28
|
|
|
1456 @deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, const char *@var{format}, va_list @var{ap})
|
|
|
1457
|
|
|
1458 This function is similar to vsprintf, but it will print at most
|
|
|
1459 @var{n} characters. On error the return value is -1, otherwise it
|
|
|
1460 returns the number of characters that would have been printed had
|
|
|
1461 @var{n} been sufficiently large, regardless of the actual value of
|
|
|
1462 @var{n}. Note some pre-C99 system libraries do not implement this
|
|
|
1463 correctly so users cannot generally rely on the return value if the
|
|
|
1464 system version of this function is used.
|
|
|
1465
|
|
|
1466 @end deftypefn
|
|
|
1467
|
|
|
1468 @c waitpid.c:3
|
|
|
1469 @deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int)
|
|
|
1470
|
|
|
1471 This is a wrapper around the @code{wait} function. Any ``special''
|
|
|
1472 values of @var{pid} depend on your implementation of @code{wait}, as
|
|
|
1473 does the return value. The third argument is unused in @libib{}.
|
|
|
1474
|
|
|
1475 @end deftypefn
|
|
|
1476
|
|
|
1477 @c argv.c:293
|
|
|
1478 @deftypefn Extension int writeargv (const char **@var{argv}, FILE *@var{file})
|
|
|
1479
|
|
|
1480 Write each member of ARGV, handling all necessary quoting, to the file
|
|
|
1481 named by FILE, separated by whitespace. Return 0 on success, non-zero
|
|
|
1482 if an error occurred while writing to FILE.
|
|
|
1483
|
|
|
1484 @end deftypefn
|
|
|
1485
|
|
|
1486 @c xatexit.c:11
|
|
|
1487 @deftypefun int xatexit (void (*@var{fn}) (void))
|
|
|
1488
|
|
|
1489 Behaves as the standard @code{atexit} function, but with no limit on
|
|
|
1490 the number of registered functions. Returns 0 on success, or @minus{}1 on
|
|
|
1491 failure. If you use @code{xatexit} to register functions, you must use
|
|
|
1492 @code{xexit} to terminate your program.
|
|
|
1493
|
|
|
1494 @end deftypefun
|
|
|
1495
|
|
|
1496 @c xmalloc.c:38
|
|
|
1497 @deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize})
|
|
|
1498
|
|
|
1499 Allocate memory without fail, and set it to zero. This routine functions
|
|
|
1500 like @code{calloc}, but will behave the same as @code{xmalloc} if memory
|
|
|
1501 cannot be found.
|
|
|
1502
|
|
|
1503 @end deftypefn
|
|
|
1504
|
|
|
1505 @c xexit.c:22
|
|
|
1506 @deftypefn Replacement void xexit (int @var{code})
|
|
|
1507
|
|
|
1508 Terminates the program. If any functions have been registered with
|
|
|
1509 the @code{xatexit} replacement function, they will be called first.
|
|
|
1510 Termination is handled via the system's normal @code{exit} call.
|
|
|
1511
|
|
|
1512 @end deftypefn
|
|
|
1513
|
|
|
1514 @c xmalloc.c:22
|
|
|
1515 @deftypefn Replacement void* xmalloc (size_t)
|
|
|
1516
|
|
|
1517 Allocate memory without fail. If @code{malloc} fails, this will print
|
|
|
1518 a message to @code{stderr} (using the name set by
|
|
|
1519 @code{xmalloc_set_program_name},
|
|
|
1520 if any) and then call @code{xexit}. Note that it is therefore safe for
|
|
|
1521 a program to contain @code{#define malloc xmalloc} in its source.
|
|
|
1522
|
|
|
1523 @end deftypefn
|
|
|
1524
|
|
|
1525 @c xmalloc.c:53
|
|
|
1526 @deftypefn Replacement void xmalloc_failed (size_t)
|
|
|
1527
|
|
|
1528 This function is not meant to be called by client code, and is listed
|
|
|
1529 here for completeness only. If any of the allocation routines fail, this
|
|
|
1530 function will be called to print an error message and terminate execution.
|
|
|
1531
|
|
|
1532 @end deftypefn
|
|
|
1533
|
|
|
1534 @c xmalloc.c:46
|
|
|
1535 @deftypefn Replacement void xmalloc_set_program_name (const char *@var{name})
|
|
|
1536
|
|
|
1537 You can use this to set the name of the program used by
|
|
|
1538 @code{xmalloc_failed} when printing a failure message.
|
|
|
1539
|
|
|
1540 @end deftypefn
|
|
|
1541
|
|
|
1542 @c xmemdup.c:7
|
|
|
1543 @deftypefn Replacement void* xmemdup (void *@var{input}, size_t @var{copy_size}, size_t @var{alloc_size})
|
|
|
1544
|
|
|
1545 Duplicates a region of memory without fail. First, @var{alloc_size} bytes
|
|
|
1546 are allocated, then @var{copy_size} bytes from @var{input} are copied into
|
|
|
1547 it, and the new memory is returned. If fewer bytes are copied than were
|
|
|
1548 allocated, the remaining memory is zeroed.
|
|
|
1549
|
|
|
1550 @end deftypefn
|
|
|
1551
|
|
|
1552 @c xmalloc.c:32
|
|
|
1553 @deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size})
|
|
|
1554 Reallocate memory without fail. This routine functions like @code{realloc},
|
|
|
1555 but will behave the same as @code{xmalloc} if memory cannot be found.
|
|
|
1556
|
|
|
1557 @end deftypefn
|
|
|
1558
|
|
|
1559 @c xstrdup.c:7
|
|
|
1560 @deftypefn Replacement char* xstrdup (const char *@var{s})
|
|
|
1561
|
|
|
1562 Duplicates a character string without fail, using @code{xmalloc} to
|
|
|
1563 obtain memory.
|
|
|
1564
|
|
|
1565 @end deftypefn
|
|
|
1566
|
|
|
1567 @c xstrerror.c:7
|
|
|
1568 @deftypefn Replacement char* xstrerror (int @var{errnum})
|
|
|
1569
|
|
|
1570 Behaves exactly like the standard @code{strerror} function, but
|
|
|
1571 will never return a @code{NULL} pointer.
|
|
|
1572
|
|
|
1573 @end deftypefn
|
|
|
1574
|
|
|
1575 @c xstrndup.c:23
|
|
|
1576 @deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n})
|
|
|
1577
|
|
|
1578 Returns a pointer to a copy of @var{s} with at most @var{n} characters
|
|
|
1579 without fail, using @code{xmalloc} to obtain memory. The result is
|
|
|
1580 always NUL terminated.
|
|
|
1581
|
|
|
1582 @end deftypefn
|
|
|
1583
|
|
|
1584
|
