1998-08-20 08:19:55 +00:00
|
|
|
.\" 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
|
2002-06-02 10:05:55 +00:00
|
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
1998-08-20 08:19:55 +00:00
|
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
|
|
.\" SUCH DAMAGE.
|
|
|
|
.\"
|
1999-08-28 00:22:10 +00:00
|
|
|
.\" $FreeBSD$
|
1998-08-20 08:19:55 +00:00
|
|
|
.\"
|
2004-08-06 15:29:54 +00:00
|
|
|
.Dd August 6, 2004
|
1998-08-20 08:19:55 +00:00
|
|
|
.Dt LIBSTAND 3
|
2001-07-10 13:41:46 +00:00
|
|
|
.Os
|
1998-08-20 08:19:55 +00:00
|
|
|
.Sh NAME
|
|
|
|
.Nm libstand
|
|
|
|
.Nd support library for standalone executables
|
|
|
|
.Sh SYNOPSIS
|
2001-10-01 16:09:29 +00:00
|
|
|
.In stand.h
|
1998-08-20 08:19:55 +00:00
|
|
|
.Sh DESCRIPTION
|
2003-03-24 15:56:36 +00:00
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm
|
2003-03-24 15:56:36 +00:00
|
|
|
library provides a set of supporting functions for standalone
|
2001-08-14 10:01:54 +00:00
|
|
|
applications, mimicking where possible the standard
|
|
|
|
.Bx
|
|
|
|
programming
|
2004-07-02 23:52:20 +00:00
|
|
|
environment.
|
|
|
|
The following sections group these functions by kind.
|
1998-08-20 08:19:55 +00:00
|
|
|
Unless specifically described here, see the corresponding section 3
|
|
|
|
manpages for the given functions.
|
|
|
|
.Sh STRING FUNCTIONS
|
|
|
|
String functions are available as documented in
|
2001-07-15 07:53:42 +00:00
|
|
|
.Xr string 3
|
1998-08-20 08:19:55 +00:00
|
|
|
and
|
|
|
|
.Xr bstring 3 .
|
|
|
|
.Sh MEMORY ALLOCATION
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft "void *"
|
|
|
|
.Fn malloc "size_t size"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Allocate
|
|
|
|
.Fa size
|
|
|
|
bytes of memory from the heap using a best-fit algorithm.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn free "void *ptr"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Free the allocated object at
|
|
|
|
.Fa ptr .
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn setheap "void *start" "void *limit"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2004-07-02 23:52:20 +00:00
|
|
|
Initialise the heap.
|
|
|
|
This function must be called before calling
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn alloc
|
2004-07-02 23:52:20 +00:00
|
|
|
for the first time.
|
|
|
|
The region between
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa start
|
|
|
|
and
|
|
|
|
.Fa limit
|
|
|
|
will be used for the heap; attempting to allocate beyond this will result
|
|
|
|
in a panic.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft "char *"
|
|
|
|
.Fn sbrk "int junk"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Provides the behaviour of
|
|
|
|
.Fn sbrk 0 ,
|
2004-07-02 23:52:20 +00:00
|
|
|
i.e., returns the highest point that the heap has reached.
|
|
|
|
This value can
|
|
|
|
be used during testing to determine the actual heap usage.
|
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa junk
|
|
|
|
argument is ignored.
|
|
|
|
.El
|
|
|
|
.Sh ENVIRONMENT
|
|
|
|
A set of functions are provided for manipulating a flat variable space similar
|
2004-07-02 23:52:20 +00:00
|
|
|
to the traditional shell-supported environment.
|
|
|
|
Major enhancements are support
|
1998-08-20 08:19:55 +00:00
|
|
|
for set/unset hook functions.
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft "char *"
|
|
|
|
.Fn getenv "const char *name"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn setenv "const char *name" "char *value" "int overwrite"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn putenv "const char *string"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn unsetenv "const char *name"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
These functions behave similarly to their standard library counterparts.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft "struct env_var *"
|
|
|
|
.Fn env_getenv "const char *name"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2001-07-15 07:53:42 +00:00
|
|
|
Looks up a variable in the environment and returns its entire
|
1998-08-20 08:19:55 +00:00
|
|
|
data structure.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn env_setenv "const char *name" "int flags" "char *value" "ev_sethook_t sethook" "ev_unsethook_t unsethook"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Creates a new or sets an existing environment variable called
|
|
|
|
.Fa name .
|
2001-07-15 07:53:42 +00:00
|
|
|
If creating a new variable, the
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa sethook
|
|
|
|
and
|
|
|
|
.Fa unsethook
|
|
|
|
arguments may be specified.
|
|
|
|
.Pp
|
|
|
|
The set hook is invoked whenever an attempt
|
2004-07-02 23:52:20 +00:00
|
|
|
is made to set the variable, unless the EV_NOHOOK flag is set.
|
|
|
|
Typically
|
1998-08-20 08:19:55 +00:00
|
|
|
a set hook will validate the
|
|
|
|
.Fa value
|
|
|
|
argument, and then call
|
|
|
|
.Fn env_setenv
|
2004-07-02 23:52:20 +00:00
|
|
|
again with EV_NOHOOK set to actually save the value.
|
|
|
|
The predefined function
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn env_noset
|
|
|
|
may be specified to refuse all attempts to set a variable.
|
|
|
|
.Pp
|
2000-03-02 09:14:21 +00:00
|
|
|
The unset hook is invoked when an attempt is made to unset a variable.
|
2001-07-15 07:53:42 +00:00
|
|
|
If it
|
2004-07-03 22:30:10 +00:00
|
|
|
returns zero, the variable will be unset.
|
2004-07-02 23:52:20 +00:00
|
|
|
The predefined function
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa env_nounset
|
|
|
|
may be used to prevent a variable being unset.
|
|
|
|
.El
|
|
|
|
.Sh STANDARD LIBRARY SUPPORT
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
2002-06-02 10:05:55 +00:00
|
|
|
.Fn getopt "int argc" "char * const *argv" "const char *optstring"
|
2001-02-01 16:38:02 +00:00
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft long
|
|
|
|
.Fn strtol "const char *nptr" "char **endptr" "int base"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn srandom "unsigned long seed"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft "unsigned long"
|
|
|
|
.Fn random void
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft "char *"
|
|
|
|
.Fn strerror "int error"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Returns error messages for the subset of errno values supported by
|
2001-02-22 15:03:09 +00:00
|
|
|
.Nm .
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Fn assert expression
|
1998-11-01 09:31:08 +00:00
|
|
|
.Pp
|
|
|
|
Requires
|
2003-09-10 19:24:35 +00:00
|
|
|
.In assert.h .
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn setjmp "jmp_buf env"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn longjmp "jmp_buf env" "int val"
|
|
|
|
.Xc
|
1998-11-01 09:31:08 +00:00
|
|
|
.Pp
|
1998-11-04 07:39:53 +00:00
|
|
|
Defined as
|
|
|
|
.Fn _setjmp
|
2001-07-15 07:53:42 +00:00
|
|
|
and
|
2002-06-02 10:05:55 +00:00
|
|
|
.Fn _longjmp
|
2004-07-02 23:52:20 +00:00
|
|
|
respectively as there is no signal state to manipulate.
|
|
|
|
Requires
|
2003-09-10 19:24:35 +00:00
|
|
|
.In setjmp.h .
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Sh CHARACTER I/O
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn gets "char *buf"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Read characters from the console into
|
|
|
|
.Fa buf .
|
|
|
|
All of the standard cautions apply to this function.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn ngets "char *buf" "size_t size"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.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 .
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn fgetstr "char *buf" "int size" "int fd"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Read a line of at most
|
|
|
|
.Fa size
|
|
|
|
characters into
|
|
|
|
.Fa buf .
|
2002-12-05 08:50:00 +00:00
|
|
|
Line terminating characters are stripped, and the buffer is always
|
|
|
|
.Dv NUL
|
2004-07-02 23:52:20 +00:00
|
|
|
terminated.
|
|
|
|
Returns the number of characters in
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa buf
|
|
|
|
if successful, or -1 if a read error occurs.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn printf "const char *fmt" "..."
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn vprintf "const char *fmt" "va_list ap"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn sprintf "char *buf" "const char *fmt" "..."
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn vsprintf "char *buf" "const char *fmt" "va_list ap"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
The *printf functions implement a subset of the standard
|
|
|
|
.Fn printf
|
2004-07-02 23:52:20 +00:00
|
|
|
family functionality and some extensions.
|
|
|
|
The following standard conversions
|
|
|
|
are supported: c,d,n,o,p,s,u,x.
|
|
|
|
The following modifiers are supported:
|
1998-08-20 08:19:55 +00:00
|
|
|
+,-,#,*,0,field width,precision,l.
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Li b
|
2004-07-02 23:52:20 +00:00
|
|
|
conversion is provided to decode error registers.
|
|
|
|
Its usage is:
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2000-12-29 14:08:20 +00:00
|
|
|
.Bd -ragged -offset indent
|
2001-07-15 07:53:42 +00:00
|
|
|
printf(
|
|
|
|
.Qq reg=%b\en ,
|
|
|
|
regval,
|
1998-08-20 08:19:55 +00:00
|
|
|
.Qq <base><arg>*
|
|
|
|
);
|
|
|
|
.Ed
|
2000-12-29 14:08:20 +00:00
|
|
|
.Pp
|
2004-07-02 23:52:20 +00:00
|
|
|
where <base> is the output expressed as a control character, e.g.\& \e10 gives
|
|
|
|
octal, \e20 gives hex.
|
|
|
|
Each <arg> is a sequence of characters, the first of
|
1998-08-20 08:19:55 +00:00
|
|
|
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
|
2000-12-29 14:08:20 +00:00
|
|
|
.Bd -ragged -offset indent
|
1998-08-20 08:19:55 +00:00
|
|
|
printf(
|
2004-08-06 11:24:37 +00:00
|
|
|
.Qq reg=%b\en ,
|
|
|
|
3,
|
1998-08-20 08:19:55 +00:00
|
|
|
.Qq \e10\e2BITTWO\e1BITONE\en
|
|
|
|
);
|
|
|
|
.Ed
|
2000-12-29 14:08:20 +00:00
|
|
|
.Pp
|
1998-08-20 08:19:55 +00:00
|
|
|
would give the output
|
|
|
|
.Pp
|
2000-12-29 14:08:20 +00:00
|
|
|
.Bd -ragged -offset indent
|
1998-08-20 08:19:55 +00:00
|
|
|
reg=3<BITTWO,BITONE>
|
|
|
|
.Ed
|
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Li D
|
2004-07-02 23:52:20 +00:00
|
|
|
conversion provides a hexdump facility, e.g.
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2000-12-29 14:08:20 +00:00
|
|
|
.Bd -ragged -offset indent
|
1998-08-20 08:19:55 +00:00
|
|
|
printf(
|
|
|
|
.Qq %6D ,
|
|
|
|
ptr,
|
2000-12-29 14:08:20 +00:00
|
|
|
.Qq \&:
|
2004-07-03 22:30:10 +00:00
|
|
|
); gives
|
1998-08-20 08:19:55 +00:00
|
|
|
.Qq XX:XX:XX:XX:XX:XX
|
|
|
|
.Ed
|
2000-12-29 14:08:20 +00:00
|
|
|
.Bd -ragged -offset indent
|
1998-08-20 08:19:55 +00:00
|
|
|
printf(
|
|
|
|
.Qq %*D ,
|
|
|
|
len,
|
|
|
|
ptr,
|
|
|
|
.Qq "\ "
|
2004-07-03 22:30:10 +00:00
|
|
|
); gives
|
1998-08-20 08:19:55 +00:00
|
|
|
.Qq XX XX XX ...
|
|
|
|
.Ed
|
|
|
|
.El
|
|
|
|
.Sh CHARACTER TESTS AND CONVERSIONS
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isupper "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn islower "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isspace "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isdigit "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isxdigit "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isascii "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn isalpha "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn toupper "int c"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn tolower "int c"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Sh FILE I/O
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn open "const char *path" "int flags"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Similar to the behaviour as specified in
|
|
|
|
.Xr open 2 ,
|
|
|
|
except that file creation is not supported, so the mode parameter is not
|
2004-07-02 23:52:20 +00:00
|
|
|
required.
|
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa flags
|
2002-12-12 17:26:04 +00:00
|
|
|
argument may be one of O_RDONLY, O_WRONLY and O_RDWR (although no file systems
|
1998-08-20 08:19:55 +00:00
|
|
|
currently support writing).
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn close "int fd"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn closeall void
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Close all open files.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft ssize_t
|
|
|
|
.Fn read "int fd" "void *buf" "size_t len"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft ssize_t
|
|
|
|
.Fn write "int fd" "void *buf" "size_t len"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2002-12-12 17:26:04 +00:00
|
|
|
(No file systems currently support writing.)
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft off_t
|
|
|
|
.Fn lseek "int fd" "off_t offset" "int whence"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Files being automatically uncompressed during reading cannot seek backwards
|
|
|
|
from the current point.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn stat "const char *path" "struct stat *sb"
|
|
|
|
.Xc
|
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn fstat "int fd" "struct stat *sb"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
The
|
|
|
|
.Fn stat
|
|
|
|
and
|
|
|
|
.Fn fstat
|
|
|
|
functions only fill out the following fields in the
|
|
|
|
.Fa sb
|
2004-07-02 23:52:20 +00:00
|
|
|
structure: st_mode,st_nlink,st_uid,st_gid,st_size.
|
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm tftp
|
2002-12-12 17:26:04 +00:00
|
|
|
file system cannot provide meaningful values for this call, and the
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm cd9660
|
2002-12-12 17:26:04 +00:00
|
|
|
file system always reports files having uid/gid of zero.
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Sh PAGER
|
2003-03-24 15:56:36 +00:00
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm
|
2003-03-24 15:56:36 +00:00
|
|
|
library supplies a simple internal pager to ease reading the output of large
|
|
|
|
commands.
|
1998-08-20 08:19:55 +00:00
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn pager_open
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Initialises the pager and tells it that the next line output will be the top of the
|
2004-07-02 23:52:20 +00:00
|
|
|
display.
|
|
|
|
The environment variable LINES is consulted to determine the number of
|
1998-08-20 08:19:55 +00:00
|
|
|
lines to be displayed before pausing.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn pager_close void
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Closes the pager.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
2001-02-22 10:58:30 +00:00
|
|
|
.Ft int
|
2001-02-01 16:38:02 +00:00
|
|
|
.Fn pager_output "char *lines"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2002-12-05 08:50:00 +00:00
|
|
|
Sends the lines in the
|
|
|
|
.Dv NUL Ns
|
|
|
|
-terminated buffer at
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa lines
|
2004-07-02 23:52:20 +00:00
|
|
|
to the pager.
|
|
|
|
Newline characters are counted in order to determine the number
|
1998-08-20 08:19:55 +00:00
|
|
|
of lines being output (wrapped lines are not accounted for).
|
2003-03-24 15:56:36 +00:00
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn pager_output
|
2003-03-24 15:56:36 +00:00
|
|
|
function will return zero when all of the lines have been output, or nonzero
|
|
|
|
if the display was paused and the user elected to quit.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn pager_file "char *fname"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Attempts to open and display the file
|
2001-01-19 14:15:40 +00:00
|
|
|
.Fa fname .
|
|
|
|
Returns -1 on error, 0 at EOF, or 1 if the user elects to quit while reading.
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Sh MISC
|
|
|
|
.Bl -hang -width 10n
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn twiddle void
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2001-07-15 07:53:42 +00:00
|
|
|
Successive calls emit the characters in the sequence |,/,-,\\ followed by a
|
1998-08-20 08:19:55 +00:00
|
|
|
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
|
2004-07-02 23:52:20 +00:00
|
|
|
functions can be invoked.
|
|
|
|
Stack requirements vary depending on the functions
|
2002-12-12 17:26:04 +00:00
|
|
|
and file systems used by the consumer and the support layer functions detailed
|
1998-08-20 08:19:55 +00:00
|
|
|
below.
|
|
|
|
.Pp
|
2001-07-15 07:53:42 +00:00
|
|
|
The heap must be established before calling
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn alloc
|
2001-07-15 07:53:42 +00:00
|
|
|
or
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn open
|
|
|
|
by calling
|
|
|
|
.Fn setheap .
|
|
|
|
Heap usage will vary depending on the number of simultaneously open files,
|
2004-07-02 23:52:20 +00:00
|
|
|
as well as client behaviour.
|
|
|
|
Automatic decompression will allocate more
|
1998-08-20 08:19:55 +00:00
|
|
|
than 64K of data per open file.
|
|
|
|
.Pp
|
2001-07-15 07:53:42 +00:00
|
|
|
Console access is performed via the
|
1998-08-20 08:19:55 +00:00
|
|
|
.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
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn getchar void
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Return a character from the console, used by
|
|
|
|
.Fn gets ,
|
|
|
|
.Fn ngets
|
|
|
|
and pager functions.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn ischar void
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Returns nonzero if a character is waiting from the console.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn putchar int
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Write a character to the console, used by
|
2001-07-15 07:53:42 +00:00
|
|
|
.Fn gets ,
|
|
|
|
.Fn ngets ,
|
|
|
|
.Fn *printf ,
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn panic
|
|
|
|
and
|
|
|
|
.Fn twiddle
|
|
|
|
and thus by many other functions for debugging and informational output.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn devopen "struct open_file *of" "const char *name" "char **file"
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
|
|
|
Open the appropriate device for the file named in
|
|
|
|
.Fa name ,
|
|
|
|
returning in
|
|
|
|
.Fa file
|
2001-07-15 07:53:42 +00:00
|
|
|
a pointer to the remaining body of
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa name
|
2004-07-02 23:52:20 +00:00
|
|
|
which does not refer to the device.
|
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Va f_dev
|
2001-07-15 07:53:42 +00:00
|
|
|
field in
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa of
|
|
|
|
will be set to point to the
|
2001-02-01 16:38:02 +00:00
|
|
|
.Vt devsw
|
2004-07-02 23:52:20 +00:00
|
|
|
structure for the opened device if successful.
|
|
|
|
Device identifiers must
|
1998-08-20 08:19:55 +00:00
|
|
|
always precede the path component, but may otherwise be arbitrarily formatted.
|
|
|
|
Used by
|
|
|
|
.Fn open
|
|
|
|
and thus for all device-related I/O.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft int
|
|
|
|
.Fn devclose "struct open_file *of"
|
|
|
|
.Xc
|
2004-12-29 02:18:24 +00:00
|
|
|
.Pp
|
1998-08-20 08:19:55 +00:00
|
|
|
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.
|
2001-02-01 16:38:02 +00:00
|
|
|
.It Xo
|
|
|
|
.Ft void
|
|
|
|
.Fn panic "const char *msg" "..."
|
|
|
|
.Xc
|
1998-08-20 08:19:55 +00:00
|
|
|
.Pp
|
2004-07-02 23:52:20 +00:00
|
|
|
Signal a fatal and unrecoverable error condition.
|
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fa msg ...
|
|
|
|
arguments are as for
|
|
|
|
.Fn printf .
|
|
|
|
.El
|
2002-12-12 17:26:04 +00:00
|
|
|
.Sh INTERNAL FILE SYSTEMS
|
|
|
|
Internal file systems are enabled by the consumer exporting the array
|
2001-02-01 16:38:02 +00:00
|
|
|
.Vt struct fs_ops *file_system[] ,
|
|
|
|
which should be initialised with pointers
|
1998-08-20 08:19:55 +00:00
|
|
|
to
|
2001-02-01 16:38:02 +00:00
|
|
|
.Vt struct fs_ops
|
2004-07-02 23:52:20 +00:00
|
|
|
structures.
|
|
|
|
The following file system handlers are supplied by
|
2001-02-22 15:03:09 +00:00
|
|
|
.Nm ,
|
2002-12-12 17:26:04 +00:00
|
|
|
the consumer may supply other file systems of their own:
|
2001-10-01 12:52:24 +00:00
|
|
|
.Bl -hang -width ".Va cd9660_fsops"
|
|
|
|
.It Va ufs_fsops
|
2001-08-14 10:01:54 +00:00
|
|
|
The
|
|
|
|
.Bx
|
|
|
|
UFS.
|
2001-10-01 12:52:24 +00:00
|
|
|
.It Va ext2fs_fsops
|
2002-12-12 17:26:04 +00:00
|
|
|
Linux ext2fs file system.
|
2001-10-01 12:52:24 +00:00
|
|
|
.It Va tftp_fsops
|
1998-08-20 08:19:55 +00:00
|
|
|
File access via TFTP.
|
2001-10-01 12:52:24 +00:00
|
|
|
.It Va nfs_fsops
|
1998-08-20 08:19:55 +00:00
|
|
|
File access via NFS.
|
2001-10-01 12:52:24 +00:00
|
|
|
.It Va cd9660_fsops
|
2002-12-12 17:26:04 +00:00
|
|
|
ISO 9660 (CD-ROM) file system.
|
2002-12-19 19:34:59 +00:00
|
|
|
.It Va gzipfs_fsops
|
2002-12-12 17:26:04 +00:00
|
|
|
Stacked file system supporting gzipped files.
|
2002-12-19 19:34:59 +00:00
|
|
|
When trying the gzipfs file system,
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm
|
|
|
|
appends
|
|
|
|
.Li .gz
|
|
|
|
to the end of the filename, and then tries to locate the file using the other
|
2004-07-02 23:52:20 +00:00
|
|
|
file systems.
|
|
|
|
Placement of this file system in the
|
2001-02-01 16:38:02 +00:00
|
|
|
.Va file_system[]
|
1998-08-20 08:19:55 +00:00
|
|
|
array determines whether gzipped files will be opened in preference to non-gzipped
|
2004-07-02 23:52:20 +00:00
|
|
|
files.
|
|
|
|
It is only possible to seek a gzipped file forwards, and
|
1998-08-20 08:19:55 +00:00
|
|
|
.Fn stat
|
|
|
|
and
|
|
|
|
.Fn fstat
|
|
|
|
on gzipped files will report an invalid length.
|
2001-10-01 12:52:24 +00:00
|
|
|
.It Va bzipfs_fsops
|
|
|
|
The same as
|
2002-12-19 19:34:59 +00:00
|
|
|
.Va gzipfs_fsops ,
|
2001-10-01 12:52:24 +00:00
|
|
|
but for
|
|
|
|
.Xr bzip2 1 Ns -compressed
|
|
|
|
files.
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
The array of
|
2001-02-01 16:38:02 +00:00
|
|
|
.Vt struct fs_ops
|
1998-08-20 08:19:55 +00:00
|
|
|
pointers should be terminated with a NULL.
|
|
|
|
.Sh DEVICES
|
|
|
|
Devices are exported by the supporting code via the array
|
2001-02-01 16:38:02 +00:00
|
|
|
.Vt struct devsw *devsw[]
|
1998-08-20 08:19:55 +00:00
|
|
|
which is a NULL terminated array of pointers to device switch structures.
|
|
|
|
.Sh BUGS
|
|
|
|
The lack of detailed memory usage data is unhelpful.
|
|
|
|
.Sh HISTORY
|
2003-03-24 15:56:36 +00:00
|
|
|
The
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm
|
2003-03-24 15:56:36 +00:00
|
|
|
library contains contributions from many sources, including:
|
1998-08-20 08:19:55 +00:00
|
|
|
.Bl -bullet -compact
|
2001-07-15 07:53:42 +00:00
|
|
|
.It
|
1998-08-20 08:19:55 +00:00
|
|
|
.Nm libsa
|
|
|
|
from
|
|
|
|
.Nx
|
|
|
|
.It
|
|
|
|
.Nm libc
|
|
|
|
and
|
|
|
|
.Nm libkern
|
|
|
|
from
|
|
|
|
.Fx 3.0 .
|
1998-11-01 09:31:08 +00:00
|
|
|
.It
|
|
|
|
.Nm zalloc
|
|
|
|
from
|
|
|
|
.An Matthew Dillon Aq dillon@backplane.com
|
1998-08-20 08:19:55 +00:00
|
|
|
.El
|
|
|
|
.Pp
|
|
|
|
The reorganisation and port to
|
|
|
|
.Fx 3.0 ,
|
|
|
|
the environment functions and this manpage were written by
|
2001-08-13 16:33:00 +00:00
|
|
|
.An Mike Smith Aq msmith@FreeBSD.org .
|