1 .\" Copyright (c) Michael Smith
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
25 .\" $FreeBSD: src/lib/libstand/libstand.3,v 1.5.2.11 2002/06/26 19:14:43 schweikh Exp $
26 .\" $DragonFly: src/lib/libstand/libstand.3,v 1.9 2008/11/23 21:55:52 swildner Exp $
33 .Nd support library for standalone executables
40 provides a set of supporting functions for standalone
41 applications, mimicking where possible the standard
45 The following sections group these functions by kind.
46 Unless specifically described here, see the corresponding section 3
47 manpages for the given functions.
49 String functions are available as documented in
57 .Fn malloc "size_t size"
62 bytes of memory from the heap using a best-fit algorithm.
68 Free the allocated object at
72 .Fn setheap "void *start" "void *limit"
76 This function must be called before calling
83 will be used for the heap; attempting to allocate beyond this will result
90 Provides the behaviour of
92 ie. returns the highest point that the heap has reached.
94 be used during testing to determine the actual heap usage.
100 A set of functions are provided for manipulating a flat variable space similar
101 to the traditional shell-supported environment.
102 Major enhancements are support
103 for set/unset hook functions.
107 .Fn getenv "const char *name"
111 .Fn setenv "const char *name" "char *value" "int overwrite"
115 .Fn putenv "const char *string"
119 .Fn unsetenv "const char *name"
122 These functions behave similarly to their standard library counterparts.
124 .Ft "struct env_var *"
125 .Fn env_getenv "const char *name"
128 Looks up a variable in the environment and returns its entire
132 .Fn env_setenv "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook"
135 Creates a new or sets an existing environment variable called
137 If creating a new variable, the
141 arguments may be specified.
143 The set hook is invoked whenever an attempt
144 is made to set the variable, unless the
148 a set hook will validate the
150 argument, and then call
154 set to actually save the value.
155 The predefined function
157 may be specified to refuse all attempts to set a variable.
159 The unset hook is invoked when an attempt is made to unset a variable.
161 returns zero, the variable will be unset.
162 The predefined function
164 may be used to prevent a variable being unset.
166 .Sh STANDARD LIBRARY SUPPORT
170 .Fn getopt "int argc" "char * const *argv" "const char *optstring"
174 .Fn strtol "const char *nptr" "char **endptr" "int base"
178 .Fn srandom "unsigned long seed"
186 .Fn strerror "int error"
189 Returns error messages for the subset of
193 .It Fn assert expression
199 .Fn setjmp "jmp_buf env"
203 .Fn longjmp "jmp_buf env" "int val"
210 respectively as there is no signal state to manipulate.
221 Read characters from the console into
223 All of the standard cautions apply to this function.
226 .Fn ngets "char *buf" "size_t size"
231 - 1 characters from the console into
235 is less than 1, the function's behaviour is as for
239 .Fn fgetstr "char *buf" "int size" "int fd"
242 Read a line of at most
246 Line terminating characters are stripped, and the buffer is always
248 Returns the number of characters in
250 if successful, or -1 if a read error occurs.
253 .Fn printf "const char *fmt" "..."
257 .Fn vprintf "const char *fmt" "va_list ap"
261 .Fn sprintf "char *buf" "const char *fmt" "..."
265 .Fn vsprintf "char *buf" "const char *fmt" "va_list ap"
268 The *printf functions implement a subset of the standard
270 family functionality and some extensions.
271 The following standard conversions
273 .Cm c , d , n , o , p , s , u , x .
274 The following modifiers are supported:
275 .Cm + , - , # , * , 0 , field width, precision, l .
279 conversion is provided to decode error registers.
281 .Bd -ragged -offset indent
289 where <base> is the output expressed as a control character, e.g. \e10 gives
290 octal, \e20 gives hex.
291 Each <arg> is a sequence of characters, the first of
292 which gives the bit number to be inspected (origin 1) and the next characters
293 (up to a character less than 32) give the text to be displayed if the bit is set.
295 .Bd -ragged -offset indent
299 .Qq \e10\e2BITTWO\e1BITONE\en
303 would give the output
304 .Bd -ragged -offset indent
310 conversion provides a hexdump facility, eg.
311 .Bd -ragged -offset indent
317 .Qq XX:XX:XX:XX:XX:XX
319 .Bd -ragged -offset indent
329 .Sh CHARACTER TESTS AND CONVERSIONS
372 .Fn open "const char *path" "int flags"
375 Similar to the behaviour as specified in
377 except that file creation is not supported, so the mode parameter is not
381 argument may be one of
386 (although no filesystems currently support writing).
396 Close all open files.
399 .Fn read "int fd" "void *buf" "size_t len"
403 .Fn write "int fd" "void *buf" "size_t len"
406 (No filesystems currently support writing.)
409 .Fn lseek "int fd" "off_t offset" "int whence"
412 Files being automatically uncompressed during reading cannot seek backwards
413 from the current point.
416 .Fn stat "const char *path" "struct stat *sb"
420 .Fn fstat "int fd" "struct stat *sb"
427 functions only fill out the following fields in the
430 .Fa st_mode , st_nlink , st_uid , st_gid , st_size .
433 filesystem cannot provide meaningful values for this call, and the
435 filesystem always reports files having uid/gid of zero.
439 supplies a simple internal pager to ease reading the output of large commands.
446 Initialises the pager and tells it that the next line output will be the
448 The environment variable LINES is consulted to determine the number of
449 lines to be displayed before pausing.
458 .Fn pager_output "char *lines"
461 Sends the lines in the nul-terminated buffer at
464 Newline characters are counted in order to determine the number
465 of lines being output (wrapped lines are not accounted for).
467 will return zero when all of the lines have been output, or nonzero if the
468 display was paused and the user elected to quit.
471 .Fn pager_file "char *fname"
474 Attempts to open and display the file
476 Returns -1 on error, 0 at
478 or 1 if the user elects to quit while reading.
487 Successive calls emit the characters in the sequence |, /, -, \\ followed by a
488 backspace in order to provide reassurance to the user.
490 .Sh REQUIRED LOW-LEVEL SUPPORT
491 The following resources are consumed by
493 - stack, heap, console and devices.
495 The stack must be established before
497 functions can be invoked.
498 Stack requirements vary depending on the functions
499 and filesystems used by the consumer and the support layer functions detailed
502 The heap must be established before calling
508 Heap usage will vary depending on the number of simultaneously open files,
509 as well as client behaviour.
510 Automatic decompression will allocate more
511 than 64K of data per open file.
513 Console access is performed via the
518 functions detailed below.
520 Device access is initiated via
522 and is performed through the
527 functions in the device switch structure that
531 The consumer must provide the following support functions:
538 Return a character from the console, used by
547 Returns nonzero if a character is waiting from the console.
553 Write a character to the console, used by
560 and thus by many other functions for debugging and informational output.
563 .Fn devopen "struct open_file *of" "const char *name" "char **file"
566 Open the appropriate device for the file named in
570 a pointer to the remaining body of
572 which does not refer to the device.
577 will be set to point to the
579 structure for the opened device if successful.
580 Device identifiers must
581 always precede the path component, but may otherwise be arbitrarily formatted.
584 and thus for all device-related I/O.
587 .Fn devclose "struct open_file *of"
590 Close the device allocated for
592 The device driver itself will already have been called for the close;
593 this call should clean up any allocation made by
598 .Fn panic "const char *msg" "..."
601 Signal a fatal and unrecoverable error condition.
607 .Sh INTERNAL FILESYSTEMS
608 Internal filesystems are enabled by the consumer exporting the array
609 .Vt struct fs_ops *file_system[] ,
610 which should be initialised with pointers
614 The following filesystem handlers are supplied by
616 the consumer may supply other filesystems of their own:
617 .Bl -hang -width ".Va cd9660_fsops"
626 Linux ext2fs filesystem.
630 File access via TFTP.
634 ISO 9660 (CD-ROM) filesystem.
636 Stacked filesystem supporting gzipped files.
637 When trying the zipfs filesystem,
641 to the end of the filename, and then tries to locate the file using the other
643 Placement of this filesystem in the
645 array determines whether gzipped files will be opened in preference to non-gzipped
647 It is only possible to seek a gzipped file forwards, and
651 on gzipped files will report an invalid length.
656 .Xr bzip2 1 Ns -compressed
662 pointers should be terminated with a NULL.
664 Devices are exported by the supporting code via the array
665 .Vt struct devsw *devsw[]
666 which is a NULL terminated array of pointers to device switch structures.
669 contains contributions from many sources, including:
684 .An Matthew Dillon Aq dillon@backplane.com
687 The reorganisation and port to
689 the environment functions and this manpage were written by
690 .An Mike Smith Aq msmith@FreeBSD.org .
692 The lack of detailed memory usage data is unhelpful.