diff options
Diffstat (limited to 'lib/libstand/libstand.3')
| -rw-r--r-- | lib/libstand/libstand.3 | 474 |
1 files changed, 474 insertions, 0 deletions
diff --git a/lib/libstand/libstand.3 b/lib/libstand/libstand.3 new file mode 100644 index 0000000..99fbb54 --- /dev/null +++ b/lib/libstand/libstand.3 @@ -0,0 +1,474 @@ +.\" Copyright (c) Michael Smith +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR Ohttp://wafu.netgate.net/tama/unix/indexe.htmlTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd June 22, 1998 +.Dt LIBSTAND 3 +.Os FreeBSD 3.0 +.Sh NAME +.Nm libstand +.Nd support library for standalone executables +.Sh SYNOPSIS +.Fd #include <stand.h> +.Sh DESCRIPTION +.Nm +provides a set of supporting functions for standalone +applications, mimicking where possible the standard BSD programming +environment. The following sections group these functions by kind. +Unless specifically described here, see the corresponding section 3 +manpages for the given functions. +.Sh STRING FUNCTIONS +String functions are available as documented in +.Xr string 3 +and +.Xr bstring 3 . +.Sh MEMORY ALLOCATION +.Bl -hang -width 10n +.It Fn "void *malloc" "size_t size" +.Pp +Allocate +.Fa size +bytes of memory from the heap using a best-fit algorithm. +.It Fn "void free" "void *ptr" +.Pp +Free the allocated object at +.Fa ptr . +.It Fn "void setheap" "void *start" "void *limit" +.Pp +Initialise the heap. This function must be called before calling +.Fn alloc +for the first time. The region between +.Fa start +and +.Fa limit +will be used for the heap; attempting to allocate beyond this will result +in a panic. +.It Fn "char *sbrk" "int junk" +.Pp +Provides the behaviour of +.Fn sbrk 0 , +ie. returns the highest point that the heap has reached. This value can +be used during testing to determine the actual heap usage. The +.Fa junk +argument is ignored. +.El +.Sh ENVIRONMENT +A set of functions are provided for manipulating a flat variable space similar +to the traditional shell-supported evironment. Major enhancements are support +for set/unset hook functions. +.Bl -hang -width 10n +.It Fn "char *getenv" "const char *name" +.It Fn "int setenv" "const char *name" "char *value" "int overwrite" +.It Fn "int putenv" "const char *string" +.It Fn "int unsetenv" "const char *name" +.Pp +These functions behave similarly to their standard library counterparts. +.It Fn "struct env_var *env_getenv" "const char *name" +.Pp +Looks up a variable in the environment and returns its entire +data structure. +.It Fn "int env_setenv" "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook" +.Pp +Creates a new or sets an existing environment variable called +.Fa name . +If creating a new variable, the +.Fa sethook +and +.Fa unsethook +arguments may be specified. +.Pp +The set hook is invoked whenever an attempt +is made to set the variable, unless the EV_NOHOOK flag is set. Typically +a set hook will validate the +.Fa value +argument, and then call +.Fn env_setenv +again with EV_NOHOOK set to actually save the value. The predefined function +.Fn env_noset +may be specified to refuse all attempts to set a variable. +.Pp +The unset hook is invoked when an attempt is made to unset a variable. If it +returns zero, the variable will be unset. The predefined function +.Fa env_nounset +may be used to prevent a variable being unset. +.El +.Sh STANDARD LIBRARY SUPPORT +.Bl -hang -width 10n +.It Fn "int getopt" "int argc" "char * const *argv" "cont char *optstring" +.It Fn "long strtol" "const char *nptr" "char **endptr" "int base" +.It Fn "void srandom" "unsigned long seed" +.It Fn "unsigned long random" "void" +.It Fn "char *strerror" "int error" +.Pp +Returns error messages for the subset of errno values supported by +.Nm No . +.It Fn "assert" "expression" +.Pp +Requires +.Fd #include <assert.h> +.It Fn "int setjmp" "jmp_buf env" +.It Fn "void longjmp" "jmp_buf env" "int val" +.Pp +Defined as +.Fn _setjmp +and +.Fn _lonjmp +respectively as there is no signal state to manipulate. Requires +.Fd #include <setjmp.h> +.El +.Sh CHARACTER I/O +.Bl -hang -width 10n +.It Fn "void gets" "char *buf" +.Pp +Read characters from the console into +.Fa buf . +All of the standard cautions apply to this function. +.It Fn "void ngets" "char *buf" "size_t size" +.Pp +Read at most +.Fa size +- 1 characters from the console into +.Fa buf . +If +.Fa size +is less than 1, the function's behaviour is as for +.Fn gets . +.It Fn "int fgetstr" "char *buf" "int size" "int fd" +.Pp +Read a line of at most +.Fa size +characters into +.Fa buf . +Line terminating characters are stripped, and the buffer is always nul +terminated. Returns the number of characters in +.Fa buf +if successful, or -1 if a read error occurs. +.It Fn "int printf" "const char *fmt" "..." +.It Fn "void vprintf" "const char *fmt" "va_list ap" +.It Fn "int sprintf" "char *buf" "const char *fmt" "..." +.It Fn "void vsprintf" "char *buf" "const char *fmt" "va_list ap" +.Pp +The *printf functions implement a subset of the standard +.Fn printf +family functionality and some extensions. The following standard conversions +are supported: c,d,n,o,p,s,u,x. The following modifiers are supported: ++,-,#,*,0,field width,precision,l. +.Pp +The +.Li b +conversion is provided to decode error registers. Its usage is: +.Pp +.Bd -offset indent +printf( +.Qq reg=%b\en , +regval, +.Qq <base><arg>* +); +.Ed + +where <base> is the output expressed as a control character, eg. \e10 gives +octal, \e20 gives hex. Each <arg> is a sequence of characters, the first of +which gives the bit number to be inspected (origin 1) and the next characters +(up to a character less than 32) give the text to be displayed if the bit is set. +Thus +.Pp +.Bd -offset indent +printf( +.Qq reg=%b\en +3 +.Qq \e10\e2BITTWO\e1BITONE\en +); +.Ed + +would give the output +.Pp +.Bd -offset indent +reg=3<BITTWO,BITONE> +.Ed +.Pp +The +.Li D +conversion provides a hexdump facility, eg. +.Pp +.Bd -offset indent -literal +printf( +.Qq %6D , +ptr, +.Qq \: +); gives +.Qq XX:XX:XX:XX:XX:XX +.Ed +.Bd -offset indent -literal +printf( +.Qq %*D , +len, +ptr, +.Qq "\ " +); gives +.Qq XX XX XX ... +.Ed +.El +.Sh CHARACTER TESTS AND CONVERSIONS +.Bl -hang -width 10n +.It Fn "int isupper" "int c" +.It Fn "int islower" "int c" +.It Fn "int isspace" "int c" +.It Fn "int isdigit" "int c" +.It Fn "int isxdigit" "int c" +.It Fn "int isascii" "int c" +.It Fn "int isalpha" "int c" +.It Fn "int toupper" "int c" +.It Fn "int tolower" "int c" +.El +.Sh FILE I/O +.Bl -hang -width 10n +.It Fn "int open" "const char *path" "int flags" +.Pp +Similar to the behaviour as specified in +.Xr open 2 , +except that file creation is not supported, so the mode parameter is not +required. The +.Fa flags +argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no filesystems +currently support writing). +.It Fn "int close" "int fd" +.It Fn "void closeall" "void" +.Pp +Close all open files. +.It Fn "ssize_t read" "int fd" "void *buf" "size_t len" +.It Fn "ssize_t write" "int fd" "void *buf" "size_t len" +.Pp +(No filesystems currently support writing.) +.It Fn "off_t lseek" "int fd" "off_t offset" "int whence" +.Pp +Files being automatically uncompressed during reading cannot seek backwards +from the current point. +.It Fn "int stat" "const char *path" "struct stat *sb" +.It Fn "int fstat" "int fd" "struct stat *sb" +.Pp +The +.Fn stat +and +.Fn fstat +functions only fill out the following fields in the +.Fa sb +structure: st_mode,st_nlink,st_uid,st_gid,st_size. The +.Nm tftp +filesystem cannot provide meaningful values for this call, and the +.Nm cd9660 +filesystem always reports files having uid/gid of zero. +.El +.Sh PAGER +.Nm +supplies a simple internal pager to ease reading the output of large commands. +.Bl -hang -width 10n +.It Fn "void pager_open" +.Pp +Initialises the pager and tells it that the next line output will be the top of the +display. The environment variable LINES is consulted to determine the number of +lines to be displayed before pausing. +.It Fn "void pager_close" "void" +.Pp +Closes the pager. +.It Fn "void pager_output" "char *lines" +.Pp +Sends the lines in the nul-terminated buffer at +.Fa lines +to the pager. Newline characters are counted in order to determine the number +of lines being output (wrapped lines are not accounted for). +.Fn pager_output +will return zero when all of the lines have been output, or nonzero if the +display was paused and the user elected to quit. +.It Fn "int pager_file" "char *fname" +.Pp +Attempts to open and display the file +.Fa fname. + Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading. +.El +.Sh MISC +.Bl -hang -width 10n +.It Fn "void twiddle" "void" +.Pp +Successive calls emit the characters in the sequence |,/,-,\\ followed by a +backspace in order to provide reassurance to the user. +.El +.Sh REQUIRED LOW-LEVEL SUPPORT +The following resources are consumed by +.Nm +- stack, heap, console and devices. +.Pp +The stack must be established before +.Nm +functions can be invoked. Stack requirements vary depending on the functions +and filesystems used by the consumer and the support layer functions detailed +below. +.Pp +The heap must be established before calling +.Fn alloc +or +.Fn open +by calling +.Fn setheap . +Heap usage will vary depending on the number of simultaneously open files, +as well as client behaviour. Automatic decompression will allocate more +than 64K of data per open file. +.Pp +Console access is performed via the +.Fn getchar , +.Fn putchar +and +.Fn ischar +functions detailed below. +.Pp +Device access is initiated via +.Fn devopen +and is performed through the +.Fn dv_strategy , +.Fn dv_ioctl +and +.Fn dv_close +functions in the device switch structure that +.Fn devopen +returns. +.Pp +The consumer must provide the following support functions: +.Bl -hang -width 10n +.It Fn "int getchar" "void" +.Pp +Return a character from the console, used by +.Fn gets , +.Fn ngets +and pager functions. +.It Fn "int ischar" "void" +.Pp +Returns nonzero if a character is waiting from the console. +.It Fn "void putchar" "int" +.Pp +Write a character to the console, used by +.Fn gets , +.Fn ngets , +.Fn *printf , +.Fn panic +and +.Fn twiddle +and thus by many other functions for debugging and informational output. +.It Fn "int devopen" "struct open_file *of" "const char *name" "char **file" +.Pp +Open the appropriate device for the file named in +.Fa name , +returning in +.Fa file +a pointer to the remaining body of +.Fa name +which does not refer to the device. The +.Va f_dev +field in +.Fa of +will be set to point to the +.Dv devsw +structure for the opened device if successful. Device identifiers must +always precede the path component, but may otherwise be arbitrarily formatted. +Used by +.Fn open +and thus for all device-related I/O. +.It Fn "int devclose" "struct open_file *of" +Close the device allocated for +.Fa of . +The device driver itself will already have been called for the close; this call +should clean up any allocation made by devopen only. +.It Fn "void panic" "const char *msg" "..." +.Pp +Signal a fatal and unrecoverable error condition. The +.Fa msg ... +arguments are as for +.Fn printf . +.El +.Sh INTERNAL FILESYSTEMS +Internal filesystems are enabled by the consumer exporting the array +.Dv struct fs_ops *file_system[], which should be initialised with pointers +to +.Dv struct fs_ops +structures. The following filesystem handlers are supplied by +.Nm No , +the consumer may supply other filesystems of their own: +.Bl -hang -width "cd9660_fsops " +.It ufs_fsops +The BSD UFS. +.It tftp_fsops +File access via TFTP. +.It nfs_fsops +File access via NFS. +.It cd9660_fsops +ISO 9660 (CD-ROM) filesystem. +.It zipfs_fsops +Stacked filesystem supporting gzipped files. When trying the zipfs filesystem, +.Nm +appends +.Li .gz +to the end of the filename, and then tries to locate the file using the other +filesystems. Placement of this filesystem in the +.Dv file_system[] +array determines whether gzipped files will be opened in preference to non-gzipped +files. It is only possible to seek a gzipped file forwards, and +.Fn stat +and +.Fn fstat +on gzipped files will report an invalid length. +.El +.Pp +The array of +.Dv struct fs_ops +pointers should be terminated with a NULL. +.Sh DEVICES +Devices are exported by the supporting code via the array +.Dv struct devsw *devsw[] +which is a NULL terminated array of pointers to device switch structures. +.Sh BUGS +.Pp +The lack of detailed memory usage data is unhelpful. +.Sh HISTORY +.Nm +contains contributions from many sources, including: +.Bl -bullet -compact +.It +.Nm libsa +from +.Nx +.It +.Nm libc +and +.Nm libkern +from +.Fx 3.0 . +.It +.Nm zalloc +from +.An Matthew Dillon Aq dillon@backplane.com +.El +.Pp +The reorganisation and port to +.Fx 3.0 , +the environment functions and this manpage were written by +.An Mike Smith Aq msmith@freebsd.org . |
