This is libstand; a support library for standalone executables (eg. bootstrap

modules).
Obtained from: NetBSD, with some architectural changes and many additions.

1 files changed, 456 insertions, 0 deletions

diff --git a/lib/libstand/libstand.3 b/lib/libstand/libstand.3
new file mode 100644
index 0000000..4d4b287
--- /dev/null
+++ b/lib/libstand/libstand.3
@@ -0,0 +1,456 @@
+.\" 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.
+.\"
+.\"	$Id$
+.\"
+.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 .
+.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" "..."
+.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 .
+.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 .