1
0
Fork 0
mirror of git://git.code.sf.net/p/cdesktopenv/code synced 2025-03-09 15:50:02 +00:00

Lots of man page fixes and some other minor fixes (#284)

Noteworthy changes:
- The man pages have been updated to fix a ton of instances of
  runaway underlining (this was done with `sed -i 's/\\f5/\\f3/g'`
  commands). This commit dramatically increased in size because
  of this change.
- The documentation for spawnveg(3) has been extended with
  information about its usage of posix_spawn(3) and vfork(2).
- The documentation for tmfmt(3) has been updated with the changes
  previously made to the man pages for the printf and date builtins
  (though the latter builtin is disabled by default).
- The shell's tracked alias tree (hash table) is now documented in
  the shell(3) man page.
- Removed the commented out regression test for an ERRNO variable
  as the COMPATIBILITY file states it was removed in ksh93.
This commit is contained in:
Johnothan King 2021-04-23 14:02:30 -07:00 committed by GitHub
parent 2c22ace1e6
commit 086d504393
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
51 changed files with 2195 additions and 2094 deletions

2
NEWS
View file

@ -64,7 +64,7 @@ Any uppercase BUG_* names are modernish shell bug IDs.
- Corrected a memory fault when an attempt was made to unset the default - Corrected a memory fault when an attempt was made to unset the default
nameref KSH_VERSION from the shell environment prior to any other name nameref KSH_VERSION from the shell environment prior to any other name
reference variable creation or modificaton. reference variable creation or modification.
2021-04-11: 2021-04-11:

View file

@ -98,7 +98,7 @@ export TMPDIR
src="cmd contrib etc lib" src="cmd contrib etc lib"
use="/usr/common /exp /usr/local /usr/add-on /usr/addon /usr/tools /usr /opt" use="/usr/common /exp /usr/local /usr/add-on /usr/addon /usr/tools /usr /opt"
usr="/home" usr="/home"
lib="" # nee /usr/local/lib /usr/local/shlib lib="" # need /usr/local/lib /usr/local/shlib
ccs="/usr/kvm /usr/ccs/bin" ccs="/usr/kvm /usr/ccs/bin"
org="gnu GNU" org="gnu GNU"
makefiles="Mamfile" # ksh 93u+m no longer uses these: Nmakefile nmakefile Makefile makefile makefiles="Mamfile" # ksh 93u+m no longer uses these: Nmakefile nmakefile Makefile makefile
@ -331,7 +331,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
results.] results.]
[+release\b [ [\aCC\a]]\aYY-MM-DD\a [ [\acc\a]]\ayy-mm-dd\a ]]]] [ \apackage\a ]]?Display [+release\b [ [\aCC\a]]\aYY-MM-DD\a [ [\acc\a]]\ayy-mm-dd\a ]]]] [ \apackage\a ]]?Display
recent changes for the date range [\aCC\a]]\aYY-MM-DD\a (up to recent changes for the date range [\aCC\a]]\aYY-MM-DD\a (up to
[\acc\a]]\ayy-mm-dd\a.), where \b-\b means lowest (or highest.) [\acc\a]]\ayy-mm-dd\a), where \b-\b means lowest (or highest).
If no dates are specified then changes for the last 4 months If no dates are specified then changes for the last 4 months
are listed. \apackage\a may be a package or component name.] are listed. \apackage\a may be a package or component name.]
[+remove\b [ \apackage\a ]]?Remove files installed for [+remove\b [ \apackage\a ]]?Remove files installed for
@ -340,7 +340,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
results and interesting messages captured by the most recent results and interesting messages captured by the most recent
\bmake\b (default), \btest\b or \bwrite\b action. \bold\b \bmake\b (default), \btest\b or \bwrite\b action. \bold\b
specifies the previous results, if any (current and previous specifies the previous results, if any (current and previous
results are retained.) \b$HOME/.pkgresults\b, if it exists, results are retained). \b$HOME/.pkgresults\b, if it exists,
must contain an \begrep\b(1) expression of result lines to be must contain an \begrep\b(1) expression of result lines to be
ignored. \bfailed\b lists failures only and \bpath\b lists the ignored. \bfailed\b lists failures only and \bpath\b lists the
results file path name only.] results file path name only.]
@ -394,7 +394,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
directory. If the file \b$INSTALLROOT/lib/package/profile\b is directory. If the file \b$INSTALLROOT/lib/package/profile\b is
readable then it is sourced to initialize the environment. 32 or 64 readable then it is sourced to initialize the environment. 32 or 64
implies \b$PACKAGEROOT\b of . and specifies the target architecture implies \b$PACKAGEROOT\b of . and specifies the target architecture
word size (which may be silently ignored.)] word size (which may be silently ignored).]
[+verify\b [ \apackage\a ]]?Verify installed binary files [+verify\b [ \apackage\a ]]?Verify installed binary files
against the checksum files in against the checksum files in
\b$INSTALLROOT/lib/\b\apackage\a\b/gen/*.sum\b. The checksum \b$INSTALLROOT/lib/\b\apackage\a\b/gen/*.sum\b. The checksum
@ -430,7 +430,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
archive and \aNPD\a file, suitable for \bexpmake\b(1)] archive and \aNPD\a file, suitable for \bexpmake\b(1)]
[+lcl?Generate a package archive suitable for [+lcl?Generate a package archive suitable for
restoration into the local source tree (i.e., the restoration into the local source tree (i.e., the
source is not annotated for licencing.)] source is not annotated for licencing).]
[+pkg?Generate a \bpkgmk\b(1) package suitable for [+pkg?Generate a \bpkgmk\b(1) package suitable for
\bpkgadd\b(1).] \bpkgadd\b(1).]
[+rpm?Generate an \brpm\b(1) package.] [+rpm?Generate an \brpm\b(1) package.]
@ -450,7 +450,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
package contains a complete copy of all components. A delta package contains a complete copy of all components. A delta
package contains only changes from a previous base package. package contains only changes from a previous base package.
Delta recipients must have the \bast\b \bpax\b(1) command (in Delta recipients must have the \bast\b \bpax\b(1) command (in
the \bast-base\b package.) If neither \bbase\b nor \bdelta\b is the \bast-base\b package). If neither \bbase\b nor \bdelta\b is
specified, then the current base is overwritten if there are no specified, then the current base is overwritten if there are no
deltas referring to the current base. Only the \btgz\b and deltas referring to the current base. Only the \btgz\b and
\blcl\b formats support \bdelta\b. If \bbase\b is specified \blcl\b formats support \bdelta\b. If \bbase\b is specified
@ -520,14 +520,14 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
since the two most recent base releases. Component \bRELEASE\b files since the two most recent base releases. Component \bRELEASE\b files
contain tag lines of the form [\aYY\a]]\aYY-MM-DD\a [ \atext\a ]] (or contain tag lines of the form [\aYY\a]]\aYY-MM-DD\a [ \atext\a ]] (or
\bdate\b(1) format dates) followed by README text, in reverse \bdate\b(1) format dates) followed by README text, in reverse
chronological order (newer entries at the top of the file.) \bpackage chronological order (newer entries at the top of the file). \bpackage
release\b lists this information, and \bpackage contents ...\b lists release\b lists this information, and \bpackage contents ...\b lists
the descriptions and components.] the descriptions and components.]
[+?\b$HOSTYPE\b names the current binary architecture and is determined [+?\b$HOSTYPE\b names the current binary architecture and is determined
by the output of \bpackage\b (no arguments.) The \b$HOSTTYPE\b naming by the output of \bpackage\b (no arguments). The \b$HOSTTYPE\b naming
scheme is used to separate incompatible executable and object formats. scheme is used to separate incompatible executable and object formats.
All architecture specific binaries are placed under \b$INSTALLROOT\b All architecture specific binaries are placed under \b$INSTALLROOT\b
(\b$PACKAGEROOT/arch/$HOSTTYPE\b.) There are a few places that match (\b$PACKAGEROOT/arch/$HOSTTYPE\b). There are a few places that match
against \b$HOSTTYPE\b when making binaries; these are limited to against \b$HOSTTYPE\b when making binaries; these are limited to
makefile compiler workarounds, e.g., if \b$HOSTTYPE\b matches \bhp.*\b makefile compiler workarounds, e.g., if \b$HOSTTYPE\b matches \bhp.*\b
then turn off the optimizer for these objects. All other architecture then turn off the optimizer for these objects. All other architecture
@ -538,7 +538,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
compilers on the same architecture.] compilers on the same architecture.]
[+?Each component contains an \bast\b \bnmake\b(1) makefile (either [+?Each component contains an \bast\b \bnmake\b(1) makefile (either
\bNmakefile\b or \bMakefile\b) and a \bMAM\b (make abstract machine) \bNmakefile\b or \bMakefile\b) and a \bMAM\b (make abstract machine)
file (\bMamfile\b.) A Mamfile contains a portable makefile description file (\bMamfile\b). A Mamfile contains a portable makefile description
that is used by \bmamake\b(1) to simulate \bnmake\b. Currently there is that is used by \bmamake\b(1) to simulate \bnmake\b. Currently there is
no support for old-make/gnu-make makefiles; if the binaries are just no support for old-make/gnu-make makefiles; if the binaries are just
being built then \bmamake\b will suffice; if source or makefile being built then \bmamake\b will suffice; if source or makefile
@ -873,13 +873,13 @@ ${bB}CHANGES${eB} or ${bB}ChangeLog${eB} files dated since the two most recent b
releases. Component ${bB}RELEASE${eB} files contain tag lines of the form releases. Component ${bB}RELEASE${eB} files contain tag lines of the form
[${bI}CC${eI}]${bI}YY-MM-DD${eI} [ ${bI}TEXT${eI} ] (or ${Mdate} format dates) followed by README [${bI}CC${eI}]${bI}YY-MM-DD${eI} [ ${bI}TEXT${eI} ] (or ${Mdate} format dates) followed by README
text, in reverse chronological order (newer entries at the top of the text, in reverse chronological order (newer entries at the top of the
file.) ${bF}package release${eF} generates this information, and file). ${bF}package release${eF} generates this information, and
${bF}package contents ...${eF} lists the descriptions and components. ${bF}package contents ...${eF} lists the descriptions and components.
${bP} ${bP}
${bB}\$HOSTYPE${eB} names the current binary architecture and is determined by the ${bB}\$HOSTYPE${eB} names the current binary architecture and is determined by the
output of ${bF}package${eF} (no arguments.) The ${bB}\$HOSTTYPE${eB} naming scheme is used output of ${bF}package${eF} (no arguments). The ${bB}\$HOSTTYPE${eB} naming scheme is used
to separate incompatible executable and object formats. All architecture to separate incompatible executable and object formats. All architecture
specific binaries are placed under ${bB}\$INSTALLROOT${eB} (${bB}\$PACKAGEROOT/arch/\$HOSTTYPE${eB}.) specific binaries are placed under ${bB}\$INSTALLROOT${eB} (${bB}\$PACKAGEROOT/arch/\$HOSTTYPE${eB}).
There are a few places that match against ${bB}\$HOSTTYPE${eB} when making binaries; these There are a few places that match against ${bB}\$HOSTTYPE${eB} when making binaries; these
are limited to makefile compiler workarounds, e.g., if ${bB}\$HOSTTYPE${eB} matches are limited to makefile compiler workarounds, e.g., if ${bB}\$HOSTTYPE${eB} matches
'hp.*' then turn off the optimizer for these objects. All other architecture 'hp.*' then turn off the optimizer for these objects. All other architecture
@ -889,7 +889,7 @@ optionally set the default ${bB}CC${eB} and ${bB}CCFLAGS${eB}. This is handy for
farms that support different compilers on the same architecture. farms that support different compilers on the same architecture.
${bP} ${bP}
Each component contains an ${bB}ast${eB} ${Mnmake} makefile (either ${bB}Nmakefile${eB} or ${bB}Makefile${eB}) Each component contains an ${bB}ast${eB} ${Mnmake} makefile (either ${bB}Nmakefile${eB} or ${bB}Makefile${eB})
and a ${bI}MAM${eI} (make abstract machine) file (${bB}Mamfile${eB}.) A Mamfile contains a portable and a ${bI}MAM${eI} (make abstract machine) file (${bB}Mamfile${eB}). A Mamfile contains a portable
makefile description that is used by ${bB}\$INSTALLROOT/bin/mamake${eB} to simulate makefile description that is used by ${bB}\$INSTALLROOT/bin/mamake${eB} to simulate
${bB}nmake${eB}. Currently there is no support for old-make/gnu-make makefiles; if ${bB}nmake${eB}. Currently there is no support for old-make/gnu-make makefiles; if
the binaries are just being built then ${bB}mamake${eB} will suffice; if source or the binaries are just being built then ${bB}mamake${eB} will suffice; if source or
@ -947,7 +947,7 @@ ${bT}(5)${bD}Determine the list of package names you want from the download site
bin/package setup source${eX}${eD} bin/package setup source${eX}${eD}
${bT}(6)${bD}Build and install; all generated files are placed under ${bB}arch/${eB}${bI}HOSTTYPE${eI} ${bT}(6)${bD}Build and install; all generated files are placed under ${bB}arch/${eB}${bI}HOSTTYPE${eI}
(${bB}\$INSTALLROOT${eB}), where ${bI}HOSTTYPE${eI} is the output of ${bB}bin/package${eB} (with no (${bB}\$INSTALLROOT${eB}), where ${bI}HOSTTYPE${eI} is the output of ${bB}bin/package${eB} (with no
arguments.) ${bI}name=value${eI} arguments are supported; ${bB}CC${eB} and ${bB}debug=1${eB} (compile arguments). ${bI}name=value${eI} arguments are supported; ${bB}CC${eB} and ${bB}debug=1${eB} (compile
with -g instead of -O) are likely candidates. The output is written to with -g instead of -O) are likely candidates. The output is written to
the terminal and captured in ${bB}\$INSTALLROOT/lib/package/gen/make.out${eB}:${bX} the terminal and captured in ${bB}\$INSTALLROOT/lib/package/gen/make.out${eB}:${bX}
bin/package make${eX}${eD} bin/package make${eX}${eD}
@ -1152,7 +1152,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
regress diff(1) the current and previous package test results. regress diff(1) the current and previous package test results.
release [ [CC]YY-MM-DD [ [cc]yy-mm-dd ] ] [ package ] release [ [CC]YY-MM-DD [ [cc]yy-mm-dd ] ] [ package ]
Display recent changes since [CC]YY-MM-DD (up to [cc]yy-mm-dd), Display recent changes since [CC]YY-MM-DD (up to [cc]yy-mm-dd),
where - means lowest (or highest.) If no dates are specified where - means lowest (or highest). If no dates are specified
then changes for the last 4 months are listed. PACKAGE may then changes for the last 4 months are listed. PACKAGE may
be a package or component name. be a package or component name.
remove PACKAGE remove PACKAGE
@ -1161,7 +1161,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
List results and interesting messages captured by the most List results and interesting messages captured by the most
recent make (default), test or write action. old specifies the recent make (default), test or write action. old specifies the
previous results, if any (current and previous results are previous results, if any (current and previous results are
retained.) $HOME/.pkgresults, if it exists, must contain an retained). $HOME/.pkgresults, if it exists, must contain an
egrep(1) expression of result lines to be ignored. failed lists egrep(1) expression of result lines to be ignored. failed lists
failures only and path lists the results file path only. failures only and path lists the results file path only.
setup [ beta ] [ binary ] [ source ] [ ARCHITECTURE ... ] [ URL ] [ PACKAGE ... ] setup [ beta ] [ binary ] [ source ] [ ARCHITECTURE ... ] [ URL ] [ PACKAGE ... ]
@ -1216,7 +1216,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
\$INSTALLROOT/lib/package/profile is readable then it is \$INSTALLROOT/lib/package/profile is readable then it is
sourced to initialize the environment. 32 or 64 implies sourced to initialize the environment. 32 or 64 implies
\$PACKAGEROOT of . and specifies the target architecture word \$PACKAGEROOT of . and specifies the target architecture word
size (which may be silently ignored.) size (which may be silently ignored).
verify [ PACKAGE ] verify [ PACKAGE ]
Verify installed binary files against the checksum files in Verify installed binary files against the checksum files in
\$INSTALLROOT/lib/package/gen/*.sum. The checksum files contain \$INSTALLROOT/lib/package/gen/*.sum. The checksum files contain
@ -1270,7 +1270,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
be either a base or delta. A base package contains a be either a base or delta. A base package contains a
complete copy of all components. A delta package contains complete copy of all components. A delta package contains
only changes from a previous base package. Delta recipients only changes from a previous base package. Delta recipients
must have the ast pax(1) command (in the ast-base package.) must have the ast pax(1) command (in the ast-base package).
If neither base nor delta is specified, then the current If neither base nor delta is specified, then the current
base is overwritten if there are no deltas referring to the base is overwritten if there are no deltas referring to the
current base. Only the tgz and lcl formats support delta. current base. Only the tgz and lcl formats support delta.

View file

@ -21,7 +21,7 @@ dd { margin-left:3em; }
<P><CENTER><FONT color=red><FONT face=courier><H3><A name="ksh features">ksh features</A></H3></FONT></FONT></CENTER> <P><CENTER><FONT color=red><FONT face=courier><H3><A name="ksh features">ksh features</A></H3></FONT></FONT></CENTER>
KSH-93 is the most recent version of the KornShell Language described in KSH-93 is the most recent version of the KornShell Language described in
<EM>The KornShell Command and Programming Language</EM>, <EM>The KornShell Command and Programming Language</EM>,
by Morris Bolsky and David Korn of AT&amp;T Research (nee Bell Laboratories). by Morris Bolsky and David Korn of AT&amp;T Research.
The KornShell is a shell programming language, The KornShell is a shell programming language,
which is upward compatible with which is upward compatible with
<EM>sh</EM> <EM>sh</EM>

View file

@ -49,7 +49,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
[+curl -s -L -o - \aurl\a?] [+curl -s -L -o - \aurl\a?]
} }
[a:authorize?The url authorization user name and password, separated [a:authorize?The url authorization user name and password, separated
by \b:\b (one colon character.)]:[user::password] by \b:\b (one colon character).]:[user::password]
[s:size?Terminate the data transmission after \abytes\a have been [s:size?Terminate the data transmission after \abytes\a have been
transferred.]:[bytes] transferred.]:[bytes]
[v:verbose?Verbose trace.] [v:verbose?Verbose trace.]

View file

@ -98,7 +98,7 @@ export TMPDIR
src="cmd contrib etc lib" src="cmd contrib etc lib"
use="/usr/common /exp /usr/local /usr/add-on /usr/addon /usr/tools /usr /opt" use="/usr/common /exp /usr/local /usr/add-on /usr/addon /usr/tools /usr /opt"
usr="/home" usr="/home"
lib="" # nee /usr/local/lib /usr/local/shlib lib="" # need /usr/local/lib /usr/local/shlib
ccs="/usr/kvm /usr/ccs/bin" ccs="/usr/kvm /usr/ccs/bin"
org="gnu GNU" org="gnu GNU"
makefiles="Mamfile" # ksh 93u+m no longer uses these: Nmakefile nmakefile Makefile makefile makefiles="Mamfile" # ksh 93u+m no longer uses these: Nmakefile nmakefile Makefile makefile
@ -331,7 +331,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
results.] results.]
[+release\b [ [\aCC\a]]\aYY-MM-DD\a [ [\acc\a]]\ayy-mm-dd\a ]]]] [ \apackage\a ]]?Display [+release\b [ [\aCC\a]]\aYY-MM-DD\a [ [\acc\a]]\ayy-mm-dd\a ]]]] [ \apackage\a ]]?Display
recent changes for the date range [\aCC\a]]\aYY-MM-DD\a (up to recent changes for the date range [\aCC\a]]\aYY-MM-DD\a (up to
[\acc\a]]\ayy-mm-dd\a.), where \b-\b means lowest (or highest.) [\acc\a]]\ayy-mm-dd\a), where \b-\b means lowest (or highest).
If no dates are specified then changes for the last 4 months If no dates are specified then changes for the last 4 months
are listed. \apackage\a may be a package or component name.] are listed. \apackage\a may be a package or component name.]
[+remove\b [ \apackage\a ]]?Remove files installed for [+remove\b [ \apackage\a ]]?Remove files installed for
@ -340,7 +340,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
results and interesting messages captured by the most recent results and interesting messages captured by the most recent
\bmake\b (default), \btest\b or \bwrite\b action. \bold\b \bmake\b (default), \btest\b or \bwrite\b action. \bold\b
specifies the previous results, if any (current and previous specifies the previous results, if any (current and previous
results are retained.) \b$HOME/.pkgresults\b, if it exists, results are retained). \b$HOME/.pkgresults\b, if it exists,
must contain an \begrep\b(1) expression of result lines to be must contain an \begrep\b(1) expression of result lines to be
ignored. \bfailed\b lists failures only and \bpath\b lists the ignored. \bfailed\b lists failures only and \bpath\b lists the
results file path name only.] results file path name only.]
@ -394,7 +394,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
directory. If the file \b$INSTALLROOT/lib/package/profile\b is directory. If the file \b$INSTALLROOT/lib/package/profile\b is
readable then it is sourced to initialize the environment. 32 or 64 readable then it is sourced to initialize the environment. 32 or 64
implies \b$PACKAGEROOT\b of . and specifies the target architecture implies \b$PACKAGEROOT\b of . and specifies the target architecture
word size (which may be silently ignored.)] word size (which may be silently ignored).]
[+verify\b [ \apackage\a ]]?Verify installed binary files [+verify\b [ \apackage\a ]]?Verify installed binary files
against the checksum files in against the checksum files in
\b$INSTALLROOT/lib/\b\apackage\a\b/gen/*.sum\b. The checksum \b$INSTALLROOT/lib/\b\apackage\a\b/gen/*.sum\b. The checksum
@ -430,7 +430,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
archive and \aNPD\a file, suitable for \bexpmake\b(1)] archive and \aNPD\a file, suitable for \bexpmake\b(1)]
[+lcl?Generate a package archive suitable for [+lcl?Generate a package archive suitable for
restoration into the local source tree (i.e., the restoration into the local source tree (i.e., the
source is not annotated for licencing.)] source is not annotated for licencing).]
[+pkg?Generate a \bpkgmk\b(1) package suitable for [+pkg?Generate a \bpkgmk\b(1) package suitable for
\bpkgadd\b(1).] \bpkgadd\b(1).]
[+rpm?Generate an \brpm\b(1) package.] [+rpm?Generate an \brpm\b(1) package.]
@ -450,7 +450,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
package contains a complete copy of all components. A delta package contains a complete copy of all components. A delta
package contains only changes from a previous base package. package contains only changes from a previous base package.
Delta recipients must have the \bast\b \bpax\b(1) command (in Delta recipients must have the \bast\b \bpax\b(1) command (in
the \bast-base\b package.) If neither \bbase\b nor \bdelta\b is the \bast-base\b package). If neither \bbase\b nor \bdelta\b is
specified, then the current base is overwritten if there are no specified, then the current base is overwritten if there are no
deltas referring to the current base. Only the \btgz\b and deltas referring to the current base. Only the \btgz\b and
\blcl\b formats support \bdelta\b. If \bbase\b is specified \blcl\b formats support \bdelta\b. If \bbase\b is specified
@ -520,14 +520,14 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
since the two most recent base releases. Component \bRELEASE\b files since the two most recent base releases. Component \bRELEASE\b files
contain tag lines of the form [\aYY\a]]\aYY-MM-DD\a [ \atext\a ]] (or contain tag lines of the form [\aYY\a]]\aYY-MM-DD\a [ \atext\a ]] (or
\bdate\b(1) format dates) followed by README text, in reverse \bdate\b(1) format dates) followed by README text, in reverse
chronological order (newer entries at the top of the file.) \bpackage chronological order (newer entries at the top of the file). \bpackage
release\b lists this information, and \bpackage contents ...\b lists release\b lists this information, and \bpackage contents ...\b lists
the descriptions and components.] the descriptions and components.]
[+?\b$HOSTYPE\b names the current binary architecture and is determined [+?\b$HOSTYPE\b names the current binary architecture and is determined
by the output of \bpackage\b (no arguments.) The \b$HOSTTYPE\b naming by the output of \bpackage\b (no arguments). The \b$HOSTTYPE\b naming
scheme is used to separate incompatible executable and object formats. scheme is used to separate incompatible executable and object formats.
All architecture specific binaries are placed under \b$INSTALLROOT\b All architecture specific binaries are placed under \b$INSTALLROOT\b
(\b$PACKAGEROOT/arch/$HOSTTYPE\b.) There are a few places that match (\b$PACKAGEROOT/arch/$HOSTTYPE\b). There are a few places that match
against \b$HOSTTYPE\b when making binaries; these are limited to against \b$HOSTTYPE\b when making binaries; these are limited to
makefile compiler workarounds, e.g., if \b$HOSTTYPE\b matches \bhp.*\b makefile compiler workarounds, e.g., if \b$HOSTTYPE\b matches \bhp.*\b
then turn off the optimizer for these objects. All other architecture then turn off the optimizer for these objects. All other architecture
@ -538,7 +538,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
compilers on the same architecture.] compilers on the same architecture.]
[+?Each component contains an \bast\b \bnmake\b(1) makefile (either [+?Each component contains an \bast\b \bnmake\b(1) makefile (either
\bNmakefile\b or \bMakefile\b) and a \bMAM\b (make abstract machine) \bNmakefile\b or \bMakefile\b) and a \bMAM\b (make abstract machine)
file (\bMamfile\b.) A Mamfile contains a portable makefile description file (\bMamfile\b). A Mamfile contains a portable makefile description
that is used by \bmamake\b(1) to simulate \bnmake\b. Currently there is that is used by \bmamake\b(1) to simulate \bnmake\b. Currently there is
no support for old-make/gnu-make makefiles; if the binaries are just no support for old-make/gnu-make makefiles; if the binaries are just
being built then \bmamake\b will suffice; if source or makefile being built then \bmamake\b will suffice; if source or makefile
@ -873,13 +873,13 @@ ${bB}CHANGES${eB} or ${bB}ChangeLog${eB} files dated since the two most recent b
releases. Component ${bB}RELEASE${eB} files contain tag lines of the form releases. Component ${bB}RELEASE${eB} files contain tag lines of the form
[${bI}CC${eI}]${bI}YY-MM-DD${eI} [ ${bI}TEXT${eI} ] (or ${Mdate} format dates) followed by README [${bI}CC${eI}]${bI}YY-MM-DD${eI} [ ${bI}TEXT${eI} ] (or ${Mdate} format dates) followed by README
text, in reverse chronological order (newer entries at the top of the text, in reverse chronological order (newer entries at the top of the
file.) ${bF}package release${eF} generates this information, and file). ${bF}package release${eF} generates this information, and
${bF}package contents ...${eF} lists the descriptions and components. ${bF}package contents ...${eF} lists the descriptions and components.
${bP} ${bP}
${bB}\$HOSTYPE${eB} names the current binary architecture and is determined by the ${bB}\$HOSTYPE${eB} names the current binary architecture and is determined by the
output of ${bF}package${eF} (no arguments.) The ${bB}\$HOSTTYPE${eB} naming scheme is used output of ${bF}package${eF} (no arguments). The ${bB}\$HOSTTYPE${eB} naming scheme is used
to separate incompatible executable and object formats. All architecture to separate incompatible executable and object formats. All architecture
specific binaries are placed under ${bB}\$INSTALLROOT${eB} (${bB}\$PACKAGEROOT/arch/\$HOSTTYPE${eB}.) specific binaries are placed under ${bB}\$INSTALLROOT${eB} (${bB}\$PACKAGEROOT/arch/\$HOSTTYPE${eB}).
There are a few places that match against ${bB}\$HOSTTYPE${eB} when making binaries; these There are a few places that match against ${bB}\$HOSTTYPE${eB} when making binaries; these
are limited to makefile compiler workarounds, e.g., if ${bB}\$HOSTTYPE${eB} matches are limited to makefile compiler workarounds, e.g., if ${bB}\$HOSTTYPE${eB} matches
'hp.*' then turn off the optimizer for these objects. All other architecture 'hp.*' then turn off the optimizer for these objects. All other architecture
@ -889,7 +889,7 @@ optionally set the default ${bB}CC${eB} and ${bB}CCFLAGS${eB}. This is handy for
farms that support different compilers on the same architecture. farms that support different compilers on the same architecture.
${bP} ${bP}
Each component contains an ${bB}ast${eB} ${Mnmake} makefile (either ${bB}Nmakefile${eB} or ${bB}Makefile${eB}) Each component contains an ${bB}ast${eB} ${Mnmake} makefile (either ${bB}Nmakefile${eB} or ${bB}Makefile${eB})
and a ${bI}MAM${eI} (make abstract machine) file (${bB}Mamfile${eB}.) A Mamfile contains a portable and a ${bI}MAM${eI} (make abstract machine) file (${bB}Mamfile${eB}). A Mamfile contains a portable
makefile description that is used by ${bB}\$INSTALLROOT/bin/mamake${eB} to simulate makefile description that is used by ${bB}\$INSTALLROOT/bin/mamake${eB} to simulate
${bB}nmake${eB}. Currently there is no support for old-make/gnu-make makefiles; if ${bB}nmake${eB}. Currently there is no support for old-make/gnu-make makefiles; if
the binaries are just being built then ${bB}mamake${eB} will suffice; if source or the binaries are just being built then ${bB}mamake${eB} will suffice; if source or
@ -947,7 +947,7 @@ ${bT}(5)${bD}Determine the list of package names you want from the download site
bin/package setup source${eX}${eD} bin/package setup source${eX}${eD}
${bT}(6)${bD}Build and install; all generated files are placed under ${bB}arch/${eB}${bI}HOSTTYPE${eI} ${bT}(6)${bD}Build and install; all generated files are placed under ${bB}arch/${eB}${bI}HOSTTYPE${eI}
(${bB}\$INSTALLROOT${eB}), where ${bI}HOSTTYPE${eI} is the output of ${bB}bin/package${eB} (with no (${bB}\$INSTALLROOT${eB}), where ${bI}HOSTTYPE${eI} is the output of ${bB}bin/package${eB} (with no
arguments.) ${bI}name=value${eI} arguments are supported; ${bB}CC${eB} and ${bB}debug=1${eB} (compile arguments). ${bI}name=value${eI} arguments are supported; ${bB}CC${eB} and ${bB}debug=1${eB} (compile
with -g instead of -O) are likely candidates. The output is written to with -g instead of -O) are likely candidates. The output is written to
the terminal and captured in ${bB}\$INSTALLROOT/lib/package/gen/make.out${eB}:${bX} the terminal and captured in ${bB}\$INSTALLROOT/lib/package/gen/make.out${eB}:${bX}
bin/package make${eX}${eD} bin/package make${eX}${eD}
@ -1152,7 +1152,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
regress diff(1) the current and previous package test results. regress diff(1) the current and previous package test results.
release [ [CC]YY-MM-DD [ [cc]yy-mm-dd ] ] [ package ] release [ [CC]YY-MM-DD [ [cc]yy-mm-dd ] ] [ package ]
Display recent changes since [CC]YY-MM-DD (up to [cc]yy-mm-dd), Display recent changes since [CC]YY-MM-DD (up to [cc]yy-mm-dd),
where - means lowest (or highest.) If no dates are specified where - means lowest (or highest). If no dates are specified
then changes for the last 4 months are listed. PACKAGE may then changes for the last 4 months are listed. PACKAGE may
be a package or component name. be a package or component name.
remove PACKAGE remove PACKAGE
@ -1161,7 +1161,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
List results and interesting messages captured by the most List results and interesting messages captured by the most
recent make (default), test or write action. old specifies the recent make (default), test or write action. old specifies the
previous results, if any (current and previous results are previous results, if any (current and previous results are
retained.) $HOME/.pkgresults, if it exists, must contain an retained). $HOME/.pkgresults, if it exists, must contain an
egrep(1) expression of result lines to be ignored. failed lists egrep(1) expression of result lines to be ignored. failed lists
failures only and path lists the results file path only. failures only and path lists the results file path only.
setup [ beta ] [ binary ] [ source ] [ ARCHITECTURE ... ] [ URL ] [ PACKAGE ... ] setup [ beta ] [ binary ] [ source ] [ ARCHITECTURE ... ] [ URL ] [ PACKAGE ... ]
@ -1216,7 +1216,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
\$INSTALLROOT/lib/package/profile is readable then it is \$INSTALLROOT/lib/package/profile is readable then it is
sourced to initialize the environment. 32 or 64 implies sourced to initialize the environment. 32 or 64 implies
\$PACKAGEROOT of . and specifies the target architecture word \$PACKAGEROOT of . and specifies the target architecture word
size (which may be silently ignored.) size (which may be silently ignored).
verify [ PACKAGE ] verify [ PACKAGE ]
Verify installed binary files against the checksum files in Verify installed binary files against the checksum files in
\$INSTALLROOT/lib/package/gen/*.sum. The checksum files contain \$INSTALLROOT/lib/package/gen/*.sum. The checksum files contain
@ -1270,7 +1270,7 @@ ${bT}(5)${bD}Read all unread package archive(s):${bX}
be either a base or delta. A base package contains a be either a base or delta. A base package contains a
complete copy of all components. A delta package contains complete copy of all components. A delta package contains
only changes from a previous base package. Delta recipients only changes from a previous base package. Delta recipients
must have the ast pax(1) command (in the ast-base package.) must have the ast pax(1) command (in the ast-base package).
If neither base nor delta is specified, then the current If neither base nor delta is specified, then the current
base is overwritten if there are no deltas referring to the base is overwritten if there are no deltas referring to the
current base. Only the tgz and lcl formats support delta. current base. Only the tgz and lcl formats support delta.

View file

@ -2310,7 +2310,7 @@ astlicense __PARAM__((char* p, int size, char* file, char* options, int cc1, int
comment(&notice, &buf, ((char*)0), 0, 0); comment(&notice, &buf, ((char*)0), 0, 0);
comment( &notice, &buf, "You should have received a copy of the",sizeof( "You should have received a copy of the")-1, 0); comment( &notice, &buf, "You should have received a copy of the",sizeof( "You should have received a copy of the")-1, 0);
comment( &notice, &buf, "GNU General Public License",sizeof( "GNU General Public License")-1, 0); comment( &notice, &buf, "GNU General Public License",sizeof( "GNU General Public License")-1, 0);
comment( &notice, &buf, "along with this software (see the file COPYING.)",sizeof( "along with this software (see the file COPYING.)")-1, 0); comment( &notice, &buf, "along with this software (see the file COPYING).",sizeof( "along with this software (see the file COPYING).")-1, 0);
comment( &notice, &buf, "If not, a copy is available at",sizeof( "If not, a copy is available at")-1, 0); comment( &notice, &buf, "If not, a copy is available at",sizeof( "If not, a copy is available at")-1, 0);
comment( &notice, &buf, "http://www.gnu.org/copyleft/gpl.html",sizeof( "http://www.gnu.org/copyleft/gpl.html")-1, 0); comment( &notice, &buf, "http://www.gnu.org/copyleft/gpl.html",sizeof( "http://www.gnu.org/copyleft/gpl.html")-1, 0);
comment(&notice, &buf, ((char*)0), 0, 0); comment(&notice, &buf, ((char*)0), 0, 0);

View file

@ -53,7 +53,7 @@ case $(getopts '[-][123:xyz]' opt --xyz 2>/dev/null; echo 0$opt) in
[r!:regular?Run each test with the standard input and standard output [r!:regular?Run each test with the standard input and standard output
redirected through regular files.] redirected through regular files.]
[t:test?Run only tests matching \apattern\a. Tests are numbered and [t:test?Run only tests matching \apattern\a. Tests are numbered and
consist of at least two digits (0 filled if necessary.) Tests matching consist of at least two digits (0 filled if necessary). Tests matching
\b+(0)\b are always run.]:[pattern] \b+(0)\b are always run.]:[pattern]
[x:trace?Enable debug tracing.] [x:trace?Enable debug tracing.]
[v:verbose?List differences between actual (<) and expected (>) output, [v:verbose?List differences between actual (<) and expected (>) output,

View file

@ -44,9 +44,9 @@ static const char usage[] =
" contain date tag lines of the form [\acc\a]]\ayy-mm-dd\a [ \atext\a ]]" " contain date tag lines of the form [\acc\a]]\ayy-mm-dd\a [ \atext\a ]]"
" (or \bdate\b(1) default format), where \acc\a is determined by a Y2K" " (or \bdate\b(1) default format), where \acc\a is determined by a Y2K"
" window year of 69 (we can produce an example coding dated 1991 - this" " window year of 69 (we can produce an example coding dated 1991 - this"
" can be patented?, how about 1+1=2?.) The date tag lines are followed by" " can be patented?, how about 1+1=2?). The date tag lines are followed by"
" \areadme\a text in reverse chronological order (newer entries at the" " \areadme\a text in reverse chronological order (newer entries at the"
" top of the file.) If no selection options are specified then all" " top of the file). If no selection options are specified then all"
" changes are listed. If no \afile\a operands are specified then the" " changes are listed. If no \afile\a operands are specified then the"
" standard input is read.]" " standard input is read.]"
"[+?The entries for each \afile\a are annotated with the file directory name.]" "[+?The entries for each \afile\a are annotated with the file directory name.]"

View file

@ -35,7 +35,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
[-copyright?Copyright (c) 2005-2012 AT&T Intellectual Property] [-copyright?Copyright (c) 2005-2012 AT&T Intellectual Property]
[-license?http://www.eclipse.org/org/documents/epl-v10.html] [-license?http://www.eclipse.org/org/documents/epl-v10.html]
[+NAME?rt - run "nmake test" and filter output] [+NAME?rt - run "nmake test" and filter output]
[+DESCRIPTION?\brt\b runs \vnmake test\v and filters the regression [+DESCRIPTION?\brt\b runs \bnmake test\b and filters the regression
test output to contain only test summary lines. If no \atest\a test output to contain only test summary lines. If no \atest\a
operands are specified then \btest\b is assumed. If \b-\b is operands are specified then \btest\b is assumed. If \b-\b is
specified then the \afile\a operands, or the standard input specified then the \afile\a operands, or the standard input
@ -44,7 +44,7 @@ case `(getopts '[-][123:xyz]' opt --xyz; echo 0$opt) 2>/dev/null` in
[f:failed?Only list failed test results.] [f:failed?Only list failed test results.]
[h!:heading?Enable per-file heading when more than one \afile\a operand [h!:heading?Enable per-file heading when more than one \afile\a operand
follows \b-\b.] follows \b-\b.]
[v:verbose?Run with \vREGRESSFLAGS=-v\v.] [v:verbose?Run with \bREGRESSFLAGS=-v\b.]
[ test ... | - [ file ... ] ] [ test ... | - [ file ... ] ]

0
src/cmd/builtin/features/pty Executable file → Normal file
View file

View file

@ -37,7 +37,7 @@ The options have the following defaults and meanings:
beginning of the trap. beginning of the trap.
BRACEPAT on C-shell type abc{d,e}f style file generation BRACEPAT on C-shell type abc{d,e}f style file generation
CMDLIB_HDR "<cmdlist.h>" CMDLIB_HDR "<cmdlist.h>"
The header in which yuo can provide a custom list of The header in which you can provide a custom list of
libcmd commands to provide as path-bound built-ins. libcmd commands to provide as path-bound built-ins.
CMDLIB_DIR "\"/opt/ast/bin\"" CMDLIB_DIR "\"/opt/ast/bin\""
The default virtual directory prefix for path-bound The default virtual directory prefix for path-bound

View file

@ -732,11 +732,11 @@ const char sh_optgetopts[] =
"[+n?Associate -\anumber\a and +\anumber\a options with the first " "[+n?Associate -\anumber\a and +\anumber\a options with the first "
"option with numeric arguments.]" "option with numeric arguments.]"
"[+o?The \b-\b option character prefix is optional (supports " "[+o?The \b-\b option character prefix is optional (supports "
"obsolete \bps\b(1) option syntax.)]" "obsolete \bps\b(1) option syntax).]"
"[+p?\anumber\a specifies the number of \b-\b characters that must " "[+p?\anumber\a specifies the number of \b-\b characters that must "
"prefix long option names. The default is \b2\b; \b0\b, \b1\b or " "prefix long option names. The default is \b2\b; \b0\b, \b1\b or "
"\b2\b are accepted (e.g., \bp0\b for \bdd\b(1) and \bp1\b for " "\b2\b are accepted (e.g., \bp0\b for \bdd\b(1) and \bp1\b for "
"\bfind\b(1).)]" "\bfind\b(1)).]"
"[+s?\anumber\a specifies the \b--??man\b section number, " "[+s?\anumber\a specifies the \b--??man\b section number, "
"\b1\b by default.]" "\b1\b by default.]"
"}" "}"

View file

@ -1,7 +1,7 @@
.fp 5 CW .fp 5 CW
.TH NVAL 3 "12 Feb 2003" .TH NVAL 3 "12 Feb 2003"
.SH NAME .SH NAME
\fBnval\fR \- the \f5ksh\fP name/value library \fBnval\fR \- the \f3ksh\fP name/value library
.SH SYNOPSIS .SH SYNOPSIS
.ta .8i 1.6i 2.4i 3.2i 4.0i .ta .8i 1.6i 2.4i 3.2i 4.0i
.SS "HEADERS/LIBRARIES" .SS "HEADERS/LIBRARIES"
@ -26,47 +26,47 @@ Namdisc_t;
Namval_t *nv_open(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP); Namval_t *nv_open(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP);
Namval_t *nv_create(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP, Namfun_t *\fIfp\fP); Namval_t *nv_create(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP, Namfun_t *\fIfp\fP);
Namval_t *nv_namptr(void *\fIptr\fP, int \fIindx\fP); Namval_t *nv_namptr(void *\fIptr\fP, int \fIindx\fP);
void nv_close(Namval_t *\fInp\fP); void nv_close(Namval_t *\fInp\fP);
void nv_delete(Namval_t *\fInp\fP, Dt_t *\fIdict\fP, int \fInofree\fP); void nv_delete(Namval_t *\fInp\fP, Dt_t *\fIdict\fP, int \fInofree\fP);
.ft R .ft R
.fi .fi
.SS "GETTING AND SETTING VALUES" .SS "GETTING AND SETTING VALUES"
.nf .nf
.ft 5 .ft 5
char *nv_getval(Namval_t *\fInp\fP); char *nv_getval(Namval_t *\fInp\fP);
Sfdouble_t nv_getnum(Namval_t *\fInp\fP); Sfdouble_t nv_getnum(Namval_t *\fInp\fP);
char *nv_name(Namval_t *\fInp\fP); char *nv_name(Namval_t *\fInp\fP);
void nv_putval(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP); void nv_putval(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP);
void nv_unset(Namval_t *\fInp\fP, int \fIflags\fP); void nv_unset(Namval_t *\fInp\fP, int \fIflags\fP);
int nv_clone(Namval_t *\fIsrc\fP, Namval_t *\fIdest\fP, int \fIflags\fP); int nv_clone(Namval_t *\fIsrc\fP, Namval_t *\fIdest\fP, int \fIflags\fP);
.ft R .ft R
.fi .fi
.SS "ATTRIBUTES AND SIZE" .SS "ATTRIBUTES AND SIZE"
.nf .nf
.ft 5 .ft 5
int nv_isnull(Namval_t *\fInp\fP); int nv_isnull(Namval_t *\fInp\fP);
int nv_setsize(Namval_t *\fInp\fP, int \fIsize\fP); int nv_setsize(Namval_t *\fInp\fP, int \fIsize\fP);
int nv_size(Namval_t *\fInp\fP); int nv_size(Namval_t *\fInp\fP);
unsigned nv_isattr(Namval_t *\fInp\fP, unsigned \fIflags\fP); unsigned nv_isattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
Namfun_t *nv_isvtree(Namval_t *\fInp\fP); Namfun_t *nv_isvtree(Namval_t *\fInp\fP);
unsigned nv_onattr(Namval_t *\fInp\fP, unsigned \fIflags\fP); unsigned nv_onattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
unsigned nv_offattr(Namval_t *\fInp\fP, unsigned \fIflags\fP); unsigned nv_offattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
void nv_newattr(Namval_t *\fInp\fP, unsigned \fIflags\fP, int \fIsize\fP); void nv_newattr(Namval_t *\fInp\fP, unsigned \fIflags\fP, int \fIsize\fP);
.ft R .ft R
.fi .fi
.SS "ARRAY HANDLING" .SS "ARRAY HANDLING"
.nf .nf
.ft 5 .ft 5
unsigned nv_isarray(Namval_t *\fInp\fP); unsigned nv_isarray(Namval_t *\fInp\fP);
Namarr_t *nv_setarray(Namval_t *\fInp\fP,void*(*\fIfun\fP)(Namval_t*,const char*,int)); Namarr_t *nv_setarray(Namval_t *\fInp\fP, void*(*\fIfun\fP)(Namval_t*, const char*, int));
Namarr_t *nv_arrayptr(Namval_t *\fInp\fP); Namarr_t *nv_arrayptr(Namval_t *\fInp\fP);
Namval_t *nv_putsub(Namval_t *\fInp\fP, char *\fIname\fP, long \fImode\fP); Namval_t *nv_putsub(Namval_t *\fInp\fP, char *\fIname\fP, long \fImode\fP);
Namval_t *nv_opensub(Namval_t *\fInp\fP); Namval_t *nv_opensub(Namval_t *\fInp\fP);
void nv_setvec(Namval_t *\fInp\fP, int \fIappend\fP, int \fIargc\fP, char *\fIargv\fP[]); void nv_setvec(Namval_t *\fInp\fP, int \fIappend\fP, int \fIargc\fP, char *\fIargv\fP[]);
char *nv_getsub(Namval_t *\fInp\fP); char *nv_getsub(Namval_t *\fInp\fP);
int nv_nextsub(Namval_t *\fInp\fP); int nv_nextsub(Namval_t *\fInp\fP);
int nv_aindex(Namval_t *\fInp\fP); int nv_aindex(Namval_t *\fInp\fP);
.ft R .ft R
.fi .fi
.SS "DISCIPLINES" .SS "DISCIPLINES"
@ -74,11 +74,11 @@ int nv_aindex(Namval_t *\fInp\fP);
.ft 5 .ft 5
Namfun_t *nv_disc(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP, int \fIflags\fP); Namfun_t *nv_disc(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP, int \fIflags\fP);
Namfun_t *nv_hasdisc(Namval_t *\fInp\fP, const Namdisc_t *\fIdp\fP); Namfun_t *nv_hasdisc(Namval_t *\fInp\fP, const Namdisc_t *\fIdp\fP);
char *nv_getv(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP); char *nv_getv(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
Sfdouble_t nv_getn(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP); Sfdouble_t nv_getn(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
void nv_putv(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP, Namfun_t *\fIfp\fP); void nv_putv(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP, Namfun_t *\fIfp\fP);
char *nv_setdisc(Namval_t *\fInp\fP, const char *\fIa\fP, Namval_t *\fIf\fP, Namfun_t *\fIfp\fP); char *nv_setdisc(Namval_t *\fInp\fP, const char *\fIa\fP, Namval_t *\fIf\fP, Namfun_t *\fIfp\fP);
char *nv_adddisc(Namval_t *\fInp\fP, const char **\fInames\fP); char *nv_adddisc(Namval_t *\fInp\fP, const char **\fInames\fP);
const Namdisc_t *nv_discfun(int \fIwhich\fP); const Namdisc_t *nv_discfun(int \fIwhich\fP);
.ft R .ft R
.fi .fi
@ -86,29 +86,29 @@ const Namdisc_t *nv_discfun(int \fIwhich\fP);
.nf .nf
.ft 5 .ft 5
Namval_t *nv_type(Namval_t *\fInp\fP); Namval_t *nv_type(Namval_t *\fInp\fP);
int *nv_settype(Namval_t *\fInp\fP, Namval_t *\fItp\fP, int \fIflags\fP); int *nv_settype(Namval_t *\fInp\fP, Namval_t *\fItp\fP, int \fIflags\fP);
Namval_t *nv_mkinttype(char *\fIname\fP, size_t \fIsz\fP, int \fIus\fP, const char *\fIstr\fP, Namdisc_t *\fIdp\fP); Namval_t *nv_mkinttype(char *\fIname\fP, size_t \fIsz\fP, int \fIus\fP, const char *\fIstr\fP, Namdisc_t *\fIdp\fP);
void nv_addtype(Namval_t *\fInp\fP, const char *\fIstr\fP, Optdisc_t* *\fIop\fP, size_t \fIsz\fP); void nv_addtype(Namval_t *\fInp\fP, const char *\fIstr\fP, Optdisc_t* *\fIop\fP, size_t \fIsz\fP);
.ft R .ft R
.fi .fi
.SS "MISCELLANEOUS FUNCTIONS" .SS "MISCELLANEOUS FUNCTIONS"
.nf .nf
.ft 5 .ft 5
int nv_scan(Dt_t *\fIdict\fP, void(*\fIfn\fP)(Namval_t*,void*), void *\fIdata\fP, int \fImask\fP, int \fIflags\fP); int nv_scan(Dt_t *\fIdict\fP, void(*\fIfn\fP)(Namval_t*,void*), void *\fIdata\fP, int \fImask\fP, int \fIflags\fP);
Dt_t *nv_dict(Namval_t *\fInp\fP); Dt_t *nv_dict(Namval_t *\fInp\fP);
void nv_setvtree(Namval_t *\fInp\fP); void nv_setvtree(Namval_t *\fInp\fP);
void nv_setref(Namval_t *\fInp\fP, Dt_t *\fIdp\fP, int \fIflags\fP); void nv_setref(Namval_t *\fInp\fP, Dt_t *\fIdp\fP, int \fIflags\fP);
Namval_t *nv_lastdict(void); Namval_t *nv_lastdict(void);
.ft R .ft R
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
\fINval\fP is a library of functions for interacting with name-value \fINval\fP is a library of functions for interacting with name-value
pairs as used in \f5ksh\fP. pairs as used in \f3ksh\fP.
It is built on top the container dictionary type library facility It is built on top of the container dictionary type library facility
in \f5libcdt\fP. (See cdt(3)). in \f3libcdt\fP. (See cdt(3)).
Each name-value pair is represented by a Each name-value pair is represented by a
type named \f5Namval_t\fP. type named \f3Namval_t\fP.
A \f5Namval_t\fP contains the name, value and A \f3Namval_t\fP contains the name, value and
attributes of a variable. attributes of a variable.
Some attributes can have an associated number that Some attributes can have an associated number that
represents the field width, arithmetic base, or precision. represents the field width, arithmetic base, or precision.
@ -116,225 +116,225 @@ Additionally, each name-value pair can be associated with
one or more processing disciplines that affect one or more processing disciplines that affect
its behavior. its behavior.
.PP .PP
The function \f5nv_open()\fP returns a pointer to a name-value The function \f3nv_open()\fP returns a pointer to a name-value
pair corresponding to the given \fIname\fP. pair corresponding to the given \fIname\fP.
It can also assign a value and give attributes to a name-value pair. It can also assign a value and give attributes to a name-value pair.
The argument \fIdict\fP defines the dictionary to search. The argument \fIdict\fP defines the dictionary to search.
A \f5NULL\fP value causes the shell global variable dictionary to be searched. A \f3NULL\fP value causes the shell global variable dictionary to be searched.
.PP .PP
The \fIflags\fP argument consists of the bitwise-or of zero or more The \fIflags\fP argument consists of the bitwise-or of zero or more
of the attributes listed later and zero or more of the following: of the attributes listed later and zero or more of the following:
.IP .IP
\f5NV_VARNAME\fP: \f3NV_VARNAME\fP:
An invalid variable name causes an error. An invalid variable name causes an error.
.IP .IP
\f5NV_IDENTIFIER\fP: \f3NV_IDENTIFIER\fP:
A variable name that is not an identifier causes an error. A variable name that is not an identifier causes an error.
.IP .IP
\f5NV_ASSIGN\fP: \f3NV_ASSIGN\fP:
The \fIname\fP argument can contain an assignment. The \fIname\fP argument can contain an assignment.
.IP .IP
\f5NV_NOARRAY\fP: \f3NV_NOARRAY\fP:
The \fIname\fP argument cannot contain a subscript. The \fIname\fP argument cannot contain a subscript.
.IP .IP
\f5NV_NOREF\fP: \f3NV_NOREF\fP:
Do not follow references when finding the name-value pair. Do not follow references when finding the name-value pair.
.IP .IP
\f5NV_NOADD\fP: \f3NV_NOADD\fP:
The name-value pair will not be added if it doesn't exist. The name-value pair will not be added if it doesn't exist.
Instead, a \f5NULL\fP pointer will be returned. Instead, a \f3NULL\fP pointer will be returned.
.IP .IP
\f5NV_NOSCOPE\fP: \f3NV_NOSCOPE\fP:
Only the top level scope is used. Only the top level scope is used.
.IP .IP
\f5NV_NOFAIL\fP: \f3NV_NOFAIL\fP:
Just return \f5NULL\fP when an error occurs. Just return \f3NULL\fP when an error occurs.
By default an error message is displayed and the current command By default an error message is displayed and the current command
is aborted. is aborted.
.IP .IP
.PP .PP
If a name-value pair by this name does not already exist, it is If a name-value pair by this name does not already exist, it is
created unless \fIflags\fP contains the \f5NV_NOADD\fP flag. created unless \fIflags\fP contains the \f3NV_NOADD\fP flag.
If \f5NV_VARNAME\fP, \f5NV_IDENTIFIER\fP and \f5NV_ASSIGN\fP are If \f3NV_VARNAME\fP, \f3NV_IDENTIFIER\fP and \f3NV_ASSIGN\fP are
all not specified, then no validity check is performed on the \fIname\fP all not specified, then no validity check is performed on the \fIname\fP
argument and no further processing is performed. argument and no further processing is performed.
Otherwise, if \f5NV_ASSIGN\fP is specified, then the characters up Otherwise, if \f3NV_ASSIGN\fP is specified, then the characters up
to the first \f5=\fP or \f5+=\fP are used to find the name-value pair, to the first \f3=\fP or \f3+=\fP are used to find the name-value pair,
and the characters after the \f5=\fP are used to define and the characters after the \f3=\fP are used to define
the value that will be assigned to this name-value pair. the value that will be assigned to this name-value pair.
If \fIname\fP does not contain an \f5=\fP, then no assignment If \fIname\fP does not contain an \f3=\fP, then no assignment
will be made. will be made.
If the first identifier in \fIname\fP is a reference and is not If the first identifier in \fIname\fP is a reference and is not
preceded by a \fB.\fP, preceded by a \fB.\fP,
it will be replaced by the value of the reference it will be replaced by the value of the reference
to find the name of a variable. to find the name of a variable.
Unless \fIflags\fP contains the \f5NV_NOREF\fP flag, Unless \fIflags\fP contains the \f3NV_NOREF\fP flag,
if the name-value pair give by \fIname\fP has the \f5NV_REF\fP if the name-value pair give by \fIname\fP has the \f3NV_REF\fP
attribute, it will be replaced by the variable whose name attribute, it will be replaced by the variable whose name
is the value of this name-value pair. is the value of this name-value pair.
If \f5NV_ASSIGN\fP is set in the \fIflags\fP argument, If \f3NV_ASSIGN\fP is set in the \fIflags\fP argument,
the \fIname\fP variable can contain an \f5=\fP the \fIname\fP variable can contain an \f3=\fP
and a value that will be assigned to the name-value pair. and a value that will be assigned to the name-value pair.
Any attributes appearing in the \fIflags\fP argument Any attributes appearing in the \fIflags\fP argument
will be applied to the name-value pair after any value is assigned. will be applied to the name-value pair after any value is assigned.
.PP .PP
It is possible for an application to create additional dictionaries It is possible for an application to create additional dictionaries
with the cdt library and associate them with name-value pairs. with the cdt library and associate them with name-value pairs.
The \f5nv_dict()\fP function returns the dictionary associated with The \f3nv_dict()\fP function returns the dictionary associated with
the specified name-value pair, or if no dictionary was specified, the specified name-value pair, or if no dictionary was specified,
\f5NULL\fP is returned. \f3NULL\fP is returned.
The \f5nv_lastdict()\fP function returns a pointer to the The \f3nv_lastdict()\fP function returns a pointer to the
name-value pair that contains name-value pair that contains
the last dictionary searched on the previous \f5nv_open()\fP. the last dictionary searched on the previous \f3nv_open()\fP.
.PP .PP
Name-value pairs can also be allocated without belonging to Name-value pairs can also be allocated without belonging to
a dictionary. They will typically be looked up by a \fIcreate\fP a dictionary. They will typically be looked up by a \fIcreate\fP
discipline associated with a parent node. In this case the discipline associated with a parent node. In this case the
node size will be \f5NV_MINSZ\fP and \fIn\fP nodes can be allocated node size will be \f3NV_MINSZ\fP and \fIn\fP nodes can be allocated
vial \f5calloc(5NV_MINSZ,\fIn\fP)\fP(3). vial \f3calloc(5NV_MINSZ,\fP\fIn\fP\f3)\fP(3).
The \f5nv_namptr\fP function can be used on the pointer returned by The \f3nv_namptr\fP function can be used on the pointer returned by
\f5calloc\fP along with the element number to return the \f3calloc\fP along with the element number to return the
corresponding node. corresponding node.
Each of these nodes must be given the \f5NV_MINIMAL\fP attributes. Each of these nodes must be given the \f3NV_MINIMAL\fP attributes.
.PP .PP
The \f5nv_close()\fP indicates that the pointer returned by The \f3nv_close()\fP indicates that the pointer returned by
\f5nv_open()\fP or \f5nv_opensub()\fP will not be referenced again. If the \f3nv_open()\fP or \f3nv_opensub()\fP will not be referenced again. If the
name-value pair is unset, and not referenced elsewhere, name-value pair is unset, and not referenced elsewhere,
the name-value pair may be freed. the name-value pair may be freed.
.PP .PP
The \f5nv_delete()\fP function will remove the node \fInp\fP from The \f3nv_delete()\fP function will remove the node \fInp\fP from
the dictionary \fIdict\fP. Unless \fInofree\fP is non-zero, the the dictionary \fIdict\fP. Unless \fInofree\fP is non-zero, the
node \fInp\fP will also be freed. node \fInp\fP will also be freed.
.PP .PP
The \f5nv_name()\fP function returns the name of the given name-value The \f3nv_name()\fP function returns the name of the given name-value
pair \fInp\fP. pair \fInp\fP.
The \f5nv_setsize()\fP function returns the size of the field for The \f3nv_setsize()\fP function returns the size of the field for
justified variables, the arithmetic base for integer variables, justified variables, the arithmetic base for integer variables,
and the precision or number of places after the decimal point and the precision or number of places after the decimal point
for floating point variables. If \fIsize\fP is greater than or for floating point variables. If \fIsize\fP is greater than or
equal to zero, the current size is changed to this value. equal to zero, the current size is changed to this value.
The \f5nv_size()\fP function is equivalent to \f5nv_setsize()\fP The \f3nv_size()\fP function is equivalent to \f3nv_setsize()\fP
with the second argument negative. with the second argument negative.
.PP .PP
The \f5nv_getval()\fP function returns the value of the given The \f3nv_getval()\fP function returns the value of the given
name-value pair as a string. A \f5NULL\fP return value indicates name-value pair as a string. A \f3NULL\fP return value indicates
that the name-value pair is unset. that the name-value pair is unset.
The \f5nv_getnum()\fP function returns the value of the given The \f3nv_getnum()\fP function returns the value of the given
name-value pair as a double precision number using the \f5Sfio\fP name-value pair as a double precision number using the \f3Sfio\fP
library (see sfio(3)) type \f5Sfdouble_t\fP. library (see sfio(3)) type \f3Sfdouble_t\fP.
For name-value pairs without the \f5NV_INTEGER\fP attribute, For name-value pairs without the \f3NV_INTEGER\fP attribute,
the string value is evaluated as an arithmetic expression to the string value is evaluated as an arithmetic expression to
arrive at a numerical value. arrive at a numerical value.
.PP .PP
The \f5nv_putval()\fP function is used to assign a \fIvalue\fP to The \f3nv_putval()\fP function is used to assign a \fIvalue\fP to
the name-value pair \fInp\fP. the name-value pair \fInp\fP.
The \fIflags\fP argument consists zero or more of the bitwise-or The \fIflags\fP argument consists zero or more of the bitwise-or
of \f5NV_LONG\fP, \f5NV_SHORT\fP, \f5NV_DOUBLE\fP, \f5NV_INTEGER\fP, of \f3NV_LONG\fP, \f3NV_SHORT\fP, \f3NV_DOUBLE\fP, \f3NV_INTEGER\fP,
\f5NV_RDONLY\fP, \f5NV_REF\fP, \f5NV_BINARY\fP, and \f5NV_NOFREE\fP. \f3NV_RDONLY\fP, \f3NV_REF\fP, \f3NV_BINARY\fP, and \f3NV_NOFREE\fP.
The presence of \f5NV_RDONLY\fP allows the assignment to occur The presence of \f3NV_RDONLY\fP allows the assignment to occur
even if the name-value pair has the \f5NV_RDONLY\fP attribute. even if the name-value pair has the \f3NV_RDONLY\fP attribute.
The presence of \f5NV_INTEGER\fP indicates that the \fIvalue\fP The presence of \f3NV_INTEGER\fP indicates that the \fIvalue\fP
argument is actually a pointer to a numerical type. argument is actually a pointer to a numerical type.
By default this type is \f5long\fP, but can be modified with By default this type is \f3long\fP, but can be modified with
\f5NV_LONG\fP, \f5NV_SHORT\fP, and \f5NV_DOUBLE\fP \f3NV_LONG\fP, \f3NV_SHORT\fP, and \f3NV_DOUBLE\fP
to represent \f5long long\fP, \f5short\fP, \f5double\fP, \f5long double\fP, to represent \f3long long\fP, \f3short\fP, \f3double\fP, \f3long double\fP,
and \f5float\fP. and \f3float\fP.
The presence of \f5NV_REF\fP indicates that the \fIvalue\fP The presence of \f3NV_REF\fP indicates that the \fIvalue\fP
argument is actually a pointer to a name-value pair argument is actually a pointer to a name-value pair
and \f5np\fP should become a reference to this name-value pair. and \f3np\fP should become a reference to this name-value pair.
If \f5NV_NOFREE\fP is specified, \fIvalue\fP itself becomes If \f3NV_NOFREE\fP is specified, \fIvalue\fP itself becomes
the value of the name-value pair \fInp\fP. the value of the name-value pair \fInp\fP.
Otherwise, a copy of the value is stored Otherwise, a copy of the value is stored
as the value for \fInp\fP. as the value for \fInp\fP.
.PP .PP
The \f5nv_unset()\fP function clears out the value and attributes The \f3nv_unset()\fP function clears out the value and attributes
of the given name-value function but does not free the name-value of the given name-value function but does not free the name-value
pair. pair.
If called from the \f5putval\fP discipline function, use the \fIflags\fP If called from the \f3putval\fP discipline function, use the \fIflags\fP
argument as the \fIflags\fP to \f5nv_unset()\fP. Otherwise, use 0. argument as the \fIflags\fP to \f3nv_unset()\fP. Otherwise, use 0.
.PP .PP
The following attributes can be associated with a name-value pair: The following attributes can be associated with a name-value pair:
.IP .IP
\f5NV_EXPORT\fP: \f3NV_EXPORT\fP:
The export attribute. The export attribute.
.IP .IP
\f5NV_RDONLY\fP: \f3NV_RDONLY\fP:
The readonly attribute. The readonly attribute.
.IP .IP
\f5NV_LTOU\fP: \f3NV_LTOU\fP:
Lower case characters are converted to upper case characters. Lower case characters are converted to upper case characters.
.IP .IP
\f5NV_UTOL\fP: \f3NV_UTOL\fP:
Upper case characters are converted to lower case characters. Upper case characters are converted to lower case characters.
.IP .IP
\f5NV_RJUST\fP: \f3NV_RJUST\fP:
Right justify and blank fill. Right justify and blank fill.
This attribute has an associated size that defines the This attribute has an associated size that defines the
string length of the value. string length of the value.
.IP .IP
\f5NV_LJUST\fP: \f3NV_LJUST\fP:
Left justify and blank fill. Left justify and blank fill.
This attribute has an associated size that defines the This attribute has an associated size that defines the
string length of the value. string length of the value.
.IP .IP
\f5NV_ZFILL\fP: \f3NV_ZFILL\fP:
Without \f5NV_LJUST\fP, right justifies and fills with leading zeros. Without \f3NV_LJUST\fP, right justifies and fills with leading zeros.
With \f5NV_LJUST\fP, left justify and strip leading zeros. With \f3NV_LJUST\fP, left justify and strip leading zeros.
Left justify and blank fill. Left justify and blank fill.
This attribute has an associated size that defines the This attribute has an associated size that defines the
string length of the value. string length of the value.
.IP .IP
\f5NV_TAGGED\fP: \f3NV_TAGGED\fP:
Indicates the tagged attribute. Indicates the tagged attribute.
.IP .IP
\f5NV_INTEGER\fP: \f3NV_INTEGER\fP:
Causes value to be represented by a number. Causes value to be represented by a number.
This attribute has an associated number that defines the This attribute has an associated number that defines the
arithmetic base to be used when the value is expanded as a string. arithmetic base to be used when the value is expanded as a string.
.IP .IP
\f5NV_DOUBLE\fP: \f3NV_DOUBLE\fP:
Used in conjunction with \f5NV_INTEGER\fP to cause value Used in conjunction with \f3NV_INTEGER\fP to cause value
to be stored as a double precision floating point number. to be stored as a double precision floating point number.
This attribute has an associated number that defines the This attribute has an associated number that defines the
number of places after the decimal point to be used when number of places after the decimal point to be used when
the value is expanded as a string. the value is expanded as a string.
.IP .IP
\f5NV_EXPNOTE\fP: \f3NV_EXPNOTE\fP:
Used in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to Used in conjunction with \f3NV_INTEGER\fP and \f3NV_DOUBLE\fP to
cause the value to be represented in scientific notation when cause the value to be represented in scientific notation when
expanded as a string. expanded as a string.
This attribute has an associated number that defines the This attribute has an associated number that defines the
the precision of the mantissa. the precision of the mantissa.
.IP .IP
\f5NV_HEXFLOAT\fP: \f3NV_HEXFLOAT\fP:
Used in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to Used in conjunction with \f3NV_INTEGER\fP and \f3NV_DOUBLE\fP to
cause the value to be represented in C99 %a format when expanded as cause the value to be represented in C99 %a format when expanded as
a string. a string.
.IP .IP
\f5NV_BINARY\fP: \f3NV_BINARY\fP:
The name-value pair contains a buffer of binary data and \f5nv_size()\fP The name-value pair contains a buffer of binary data and \f3nv_size()\fP
is the number of bytes for this data. By default the value is the number of bytes for this data. By default the value
will be represented by the base64 encoding of the buffer. will be represented by the base64 encoding of the buffer.
The \f5NV_LJUST\fP flag may also be specified and causes the buffer The \f3NV_LJUST\fP flag may also be specified and causes the buffer
size to be fixed and data either truncated or filled with \f50\fP bytes. size to be fixed and data either truncated or filled with \f30\fP bytes.
.IP .IP
\f5NV_REF\fP: \f3NV_REF\fP:
The name-value pair is a name reference variable. The name-value pair is a name reference variable.
.IP .IP
\f5NV_MINIMAL\fP: \f3NV_MINIMAL\fP:
The name-value pair node is not embedded in a dictionary The name-value pair node is not embedded in a dictionary
and is minimal size, \f5NV_MINSZ\fP. and is minimal size, \f3NV_MINSZ\fP.
.IP .IP
\f5NV_NODISC\fP: \f3NV_NODISC\fP:
All discipline functions are ignored when performing assignments All discipline functions are ignored when performing assignments
and lookups. and lookups.
.PP .PP
The \f5nv_isattr()\fP function can test whether or not any of The \f3nv_isattr()\fP function can test whether or not any of
the attributes given by \fIflags\fP is set. the attributes given by \fIflags\fP is set.
The \f5nv_onattr()\fP and \f5nv_offattr()\fP functions turn attributes The \f3nv_onattr()\fP and \f3nv_offattr()\fP functions turn attributes
on or off respectively. Only attributes that do not affect the on or off respectively. Only attributes that do not affect the
value can be set in this way. value can be set in this way.
The \f5nv_newattr()\fP function can be used to change the The \f3nv_newattr()\fP function can be used to change the
attributes and size of the given name-value pair which may result attributes and size of the given name-value pair which may result
in the value being changed to conform to the new attributes and size. in the value being changed to conform to the new attributes and size.
The \fIsize\fP argument is needed for attributes that require The \fIsize\fP argument is needed for attributes that require
@ -344,29 +344,29 @@ to agree with the new attributes.
For an array variable, the values for each of the For an array variable, the values for each of the
subscripts will be changed. subscripts will be changed.
.PP .PP
The \f5nv_isvtree()\fP function returns a pointer to the compound The \f3nv_isvtree()\fP function returns a pointer to the compound
variable discipline if the node \fInp\fP is a compound variable variable discipline if the node \fInp\fP is a compound variable
or \f5NULL\fP otherwise. or \f3NULL\fP otherwise.
.PP .PP
The \f5nv_isarray()\fP function returns a non-zero value if the specified The \f3nv_isarray()\fP function returns a non-zero value if the specified
name-value pair is an array. name-value pair is an array.
.PP .PP
The \f5nv_scan()\fP function is used to walk through The \f3nv_scan()\fP function is used to walk through
all name-value pairs in the dictionary given by \fIdict\fP. all name-value pairs in the dictionary given by \fIdict\fP.
If the \f5flags\fP variable contains the \f5NV_NOSCOPE\fP If the \f3flags\fP variable contains the \f3NV_NOSCOPE\fP
flag, then only the top scope will be examined. flag, then only the top scope will be examined.
The remaining flags will be used in conjunction with \fImask\fP The remaining flags will be used in conjunction with \fImask\fP
to further restrict the walk. to further restrict the walk.
If \fImask\fP is non-zero, only the nodes for which If \fImask\fP is non-zero, only the nodes for which
\f5nv_isattr(\fP\fInode\fP\f5,\fP\fImask\fP\f5)\fP \f3nv_isattr(\fP\fInode\fP\f3,\fP\fImask\fP\f3)\fP
is equal to \fIflags\fP will be visited. is equal to \fIflags\fP will be visited.
If \fIfn\fP is non-zero, then this function will be executed If \fIfn\fP is non-zero, then this function will be executed
for each name-value pair in the walk. for each name-value pair in the walk.
The arguments to \fIfn\fP will be a pointer to the name-value pair The arguments to \fIfn\fP will be a pointer to the name-value pair
and the \fIdata\fP pointer passed to \f5nv_scan()\fP. and the \fIdata\fP pointer passed to \f3nv_scan()\fP.
The number of elements visited will be returned. The number of elements visited will be returned.
.PP .PP
The \f5nv_clone()\fP function is used make a copy of the contents of The \f3nv_clone()\fP function is used make a copy of the contents of
name-value pair \fIsrc\fP to another name-value pair \fIdest\fP. name-value pair \fIsrc\fP to another name-value pair \fIdest\fP.
.PP .PP
Disciplines provide a way to Disciplines provide a way to
@ -377,304 +377,304 @@ A discipline consists of a set of one or more functions and related
data that are used to override and extend the operations data that are used to override and extend the operations
on a name-value pair. on a name-value pair.
A discipline is defined by the types A discipline is defined by the types
\f5Namfun_t\fP and \f5Namdisc_t\fP. \f3Namfun_t\fP and \f3Namdisc_t\fP.
The \f5Namdisc_t\fP is not modified by any of these functions and The \f3Namdisc_t\fP is not modified by any of these functions and
can therefore be shared by several name-value pairs. can therefore be shared by several name-value pairs.
It contains following public fields in the order listed: It contains following public fields in the order listed:
.nf .nf
\f5size_t dsize;\fP \f3size_t dsize;\fP
\f5void (*putval)(Namval_t*,const char*,int,Namfun_t*);\fP \f3void (*putval)(Namval_t*,const char*,int,Namfun_t*);\fP
\f5char *(*getval)(Namval_t*,Namfun_t*);\fP \f3char *(*getval)(Namval_t*,Namfun_t*);\fP
\f5double (*getnum)(Namval_t*,Namfun_t*);\fP \f3double (*getnum)(Namval_t*,Namfun_t*);\fP
\f5char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);\fP \f3char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);\fP
\f5Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);\fP \f3Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);\fP
\f5Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);\fP \f3Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);\fP
\f5char *(*namef)(Namval_t*,Namfun_t*);\fP \f3char *(*namef)(Namval_t*,Namfun_t*);\fP
\f5Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);\fP \f3Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);\fP
\f5Namval_t *(*typef)(Namval_t*,Namfun_t*);\fP \f3Namval_t *(*typef)(Namval_t*,Namfun_t*);\fP
.fi .fi
The \f5Namfun_t\fP type contains a member named The \f3Namfun_t\fP type contains a member named
\f5disc\fP which points to a \f5Namdisc_t\fP structure. \f3disc\fP which points to a \f3Namdisc_t\fP structure.
To create a discipline with additional user data, To create a discipline with additional user data,
define a structure with an instance of \f5Namfun_t\fP define a structure with an instance of \f3Namfun_t\fP
as the first element. as the first element.
An application must initialize the \f5Namfun_t\fP portion of An application must initialize the \f3Namfun_t\fP portion of
the structure to zero and then set the \fIdisc\fP field to point the structure to zero and then set the \fIdisc\fP field to point
to the \f5Namdisc_t\fP structure. to the \f3Namdisc_t\fP structure.
The \f5dsize\fP field of the \f5Namdisc_t\fP structure must be The \f3dsize\fP field of the \f3Namdisc_t\fP structure must be
the size of this structure. A value of 0, the size of this structure. A value of 0,
indicates that there are no additional fields and is equivalent indicates that there are no additional fields and is equivalent
to \f5sizeof(Namfun_t)\fP. to \f3sizeof(Namfun_t)\fP.
If different instances of this structure uses different sizes, then If different instances of this structure uses different sizes, then
the \f5size\fP field in the \f5Namfun_t\fP can must be set to the \f3size\fP field in the \f3Namfun_t\fP can must be set to
this size and overrides the value in the \f5Namdisc_t\fP structure. this size and overrides the value in the \f3Namdisc_t\fP structure.
.PP .PP
When a variable is referenced by calling the \f5nv_getval()\fP function, When a variable is referenced by calling the \f3nv_getval()\fP function,
and the \f5NV_NODISC\fP attribute is not set, and the \f3NV_NODISC\fP attribute is not set,
the \f5getval()\fP discipline function is called with a pointer the \f3getval()\fP discipline function is called with a pointer
to the name-value pair, \fInp\fP, and a pointer to the discipline, to the name-value pair, \fInp\fP, and a pointer to the discipline,
\fIfp\fP. \fIfp\fP.
Inside the \f5getval()\fP function, the \f5nv_getv()\fP function Inside the \f3getval()\fP function, the \f3nv_getv()\fP function
can be called to get the value of the name-value pair that can be called to get the value of the name-value pair that
would have resulted if the discipline were not used. would have resulted if the discipline were not used.
The \f5getnum()\fP discipline is called whenever a numerical The \f3getnum()\fP discipline is called whenever a numerical
value is needed for the name-value pair \fInp\fP value is needed for the name-value pair \fInp\fP
and the \f5NV_NODISC\fP attribute is not set, and the \f3NV_NODISC\fP attribute is not set,
The \f5nv_getn()\fP function can be called from within The \f3nv_getn()\fP function can be called from within
the \f5getnum()\fP discipline to get the value that would the \f3getnum()\fP discipline to get the value that would
have resulted if there were no \f5getnum()\fP discipline. have resulted if there were no \f3getnum()\fP discipline.
.PP .PP
The \f5putval\fP\f5()\fP discipline function is used to The \f3putval\fP\f3()\fP discipline function is used to
override the assignment of values override the assignment of values
to a name-value pair. to a name-value pair.
It is called whenever a value is assigned with \f5nv_putval()\fP It is called whenever a value is assigned with \f3nv_putval()\fP
and the \f5NV_NODISC\fP attribute is not set, and the \f3NV_NODISC\fP attribute is not set,
or when a name-value pair is unset with \f5nv_unset()\fP. or when a name-value pair is unset with \f3nv_unset()\fP.
When a name-value pair is unset, \f5putval\fP\f5()\fP When a name-value pair is unset, \f3putval\fP\f3()\fP
is called with \fIvalue\fP set to \f5NULL\fP. is called with \fIvalue\fP set to \f3NULL\fP.
The \f5nv_putv()\fP function is used within the \f5putval()\fP The \f3nv_putv()\fP function is used within the \f3putval()\fP
to perform the assignment or unset that would have occurred to perform the assignment or unset that would have occurred
if the discipline had not been installed. if the discipline had not been installed.
.PP .PP
The \f5createf()\fP discipline function is called from The \f3createf()\fP discipline function is called from
\f5nv_open()\fP or \f5nv_create()\fP when the name-value pair preceding a \f3nv_open()\fP or \f3nv_create()\fP when the name-value pair preceding a
.B \s+2.\s-2 .B \s+2.\s-2
is found. is found.
This function is passed the name-value pointer plus the remaining string and This function is passed the name-value pointer plus the remaining string and
the current \fIflags\fP argument. the current \fIflags\fP argument.
The \f5createf()\fP discipline function The \f3createf()\fP discipline function
must return the created name-value pair, otherwise the default action must return the created name-value pair, otherwise the default action
will be taken. will be taken.
If the name-value pair that is returned is the same as the If the name-value pair that is returned is the same as the
one given, then the behavior will be the same as if one given, then the behavior will be the same as if
an invalid name had been given to \f5nv_open()\fP. an invalid name had been given to \f3nv_open()\fP.
The \f5nv_create()\fP function may be called within The \f3nv_create()\fP function may be called within
the \f5createf()\fP discipline function the \f3createf()\fP discipline function
to perform the action that would have occurred to perform the action that would have occurred
by an earlier \f5nv_open()\fP function. by an earlier \f3nv_open()\fP function.
.PP .PP
The \f5setdisc()\fP discipline function is used The \f3setdisc()\fP discipline function is used
to extend the set of available shell level discipline functions to extend the set of available shell level discipline functions
associated with a name-value pair by allowing associated with a name-value pair by allowing
builtins or functions whose name is of the builtins or functions whose name is of the
form \fIvarname\fP\f5.\fP\fIaction\fP to be defined. form \fIvarname\fP\f3.\fP\fIaction\fP to be defined.
By default, each name-value pair can have a \f5get\fP, By default, each name-value pair can have a \f3get\fP,
\f5set\fP, and \f5unset\fP discipline associated with it. \f3set\fP, and \f3unset\fP discipline associated with it.
Whenever a builtin or function whose name is of the Whenever a builtin or function whose name is of the
form \fIvarname\fP\f5.\fP\fIaction\fP is defined or is unset, form \fIvarname\fP\f3.\fP\fIaction\fP is defined or is unset,
and \fIaction\fP is not \f5get\fP, and \fIaction\fP is not \f3get\fP,
\f5set\fP, or \f5unset\fP, the \fIsetdisc\fP\f5()\fP function is invoked \f3set\fP, or \f3unset\fP, the \fIsetdisc\fP\f3()\fP function is invoked
with the same argument format as \f5nv_setdisc\fP\f5()\fP. with the same argument format as \f3nv_setdisc\fP\f3()\fP.
The argument \fIf\fP points to the name-value pair associated The argument \fIf\fP points to the name-value pair associated
with the function being defined, or \f5NULL\fP if the function is with the function being defined, or \f3NULL\fP if the function is
being unset. being unset.
If the given action \fIa\fP is not known by this discipline, If the given action \fIa\fP is not known by this discipline,
it should return the value returned by calling it should return the value returned by calling
\f5nv_setdisc(\fP\fInp\fP\f5,\fP\fIa\fP\f5,\fP\fIf\fP\f5,\fP\fIfp\fP\f5)\fP \f3nv_setdisc(\fP\fInp\fP\f3,\fP\fIa\fP\f3,\fP\fIf\fP\f3,\fP\fIfp\fP\f3)\fP
so that it can be searched for in previously stacked disciplines. so that it can be searched for in previously stacked disciplines.
Otherwise, the \fIsetdisc\fP\f5()\fP function should save the function Otherwise, the \fIsetdisc\fP\f3()\fP function should save the function
name-value pair pointer, and return a non-\f5NULL\fP value. name-value pair pointer, and return a non-\f3NULL\fP value.
The name-value pointer to the function can be used to invoke The name-value pointer to the function can be used to invoke
the function at an application defined point. the function at an application defined point.
If the action \fIa\fP is \f5NULL\fP, then \fIf\fP points to If the action \fIa\fP is \f3NULL\fP, then \fIf\fP points to
an action name instead of a name-value pair pointer. an action name instead of a name-value pair pointer.
The \fIsetdisc\fP\f5()\fP must return the The \fIsetdisc\fP\f3()\fP must return the
name of the action that follows the action name given by name of the action that follows the action name given by
\fIf\fP. If \fIf\fP is also \f5NULL\fP, the name of the first action \fIf\fP. If \fIf\fP is also \f3NULL\fP, the name of the first action
must be returned. must be returned.
This allows an application to get the list of valid discipline This allows an application to get the list of valid discipline
action names allowed by a given name-value pair. action names allowed by a given name-value pair.
.PP .PP
The \f5nv_adddisc()\fP function is a higher level function that The \f3nv_adddisc()\fP function is a higher level function that
adds a \fIsetdisc\fP discipline to the name-value pair that allows adds a \fIsetdisc\fP discipline to the name-value pair that allows
shell level disciplines to be created for each of the name specified shell level disciplines to be created for each of the name specified
in \f5names\fP. in \f3names\fP.
.PP .PP
The \f5nv_discfun()\fP function can be used to get a pointer to The \f3nv_discfun()\fP function can be used to get a pointer to
discipline functions that are provided by the library. discipline functions that are provided by the library.
Currently, the only one that is provided is the ones used to Currently, the only one that is provided is the ones used to
implement \f5nv_adddisc()\fP which can be returned with an implement \f3nv_adddisc()\fP which can be returned with an
argument of \f5NV_DCADD\fP. argument of \f3NV_DCADD\fP.
.PP .PP
The \f5clonef()\fP discipline function is called by \f5nv_clone()\fP The \f3clonef()\fP discipline function is called by \f3nv_clone()\fP
when making a copy of the \f5Namfun_t\fP discipline to the new node. when making a copy of the \f3Namfun_t\fP discipline to the new node.
The first argument is the original node, the second argument is The first argument is the original node, the second argument is
the new node, and the third argument is the flags that were passed the new node, and the third argument is the flags that were passed
down to \f5nv_clone()\fP. down to \f3nv_clone()\fP.
It must return a new instance of the \f5Namfun_t*\fP \f5fp\fP. It must return a new instance of the \f3Namfun_t*\fP \f3fp\fP.
If omitted, then memory whose size is determined by the \f5size\fP If omitted, then memory whose size is determined by the \f3size\fP
field of \f5fp\fP, if non-zero, or \f5fp->disc\fP, will be allocated field of \f3fp\fP, if non-zero, or \f3fp->disc\fP, will be allocated
and copied from \f5fp\fP. and copied from \f3fp\fP.
.PP .PP
The \f5namef()\fP discipline function returns the name for this name-value pair. The \f3namef()\fP discipline function returns the name for this name-value pair.
.PP .PP
The \f5nextf()\fP is used for walking through the list of sub-variables The \f3nextf()\fP is used for walking through the list of sub-variables
associated with this name-value pair. If the dictionary argument is associated with this name-value pair. If the dictionary argument is
\f5NULL\fP, it must return the first sub-variable. Otherwise, \f3NULL\fP, it must return the first sub-variable. Otherwise,
it must return the next sub-variable, or \f5NULL\fP if there are it must return the next sub-variable, or \f3NULL\fP if there are
no more variables. no more variables.
.PP .PP
A discipline is installed or removed with the A discipline is installed or removed with the
\f5nv_disc()\fP function. \f3nv_disc()\fP function.
The following flags can be specified: The following flags can be specified:
.IP .IP
\f5NV_FIRST\fP: \f3NV_FIRST\fP:
If \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the top If \fIfp\fP is non-\f3NULL\fP, the discipline is moved to the top
of the stack or pushed onto the top of the stack of disciplines of the stack or pushed onto the top of the stack of disciplines
associated with the given name-value associated with the given name-value
pair \fInp\fP if not already present. pair \fInp\fP if not already present.
Otherwise, the top of the discipline stack is returned. Otherwise, the top of the discipline stack is returned.
.IP .IP
\f5NV_LAST\fP: \f3NV_LAST\fP:
If \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the bottom If \fIfp\fP is non-\f3NULL\fP, the discipline is moved to the bottom
of the stack or pushed onto the bottom of the stack of disciplines of the stack or pushed onto the bottom of the stack of disciplines
associated with the given name-value associated with the given name-value
pair \fInp\fP if not already present. pair \fInp\fP if not already present.
Otherwise, the bottom of the discipline stack is returned. Otherwise, the bottom of the discipline stack is returned.
.IP .IP
\f5NV_POP\fP: \f3NV_POP\fP:
If \fIfp\fP is non-\f5NULL\fP and it is on the stack, If \fIfp\fP is non-\f3NULL\fP and it is on the stack,
it is removed and \fIfp\fP is returned. If \fIfp\fP is non-\f5NULL\fP it is removed and \fIfp\fP is returned. If \fIfp\fP is non-\f3NULL\fP
and is not on the stack, \f5NULL\fP is returned. and is not on the stack, \f3NULL\fP is returned.
Otherwise, the top discipline is popped Otherwise, the top discipline is popped
and returned. and returned.
.IP .IP
\f5NV_CLONE\fP: \f3NV_CLONE\fP:
If \fIfp\fP is non-\f5NULL\fP and it is on the stack, If \fIfp\fP is non-\f3NULL\fP and it is on the stack,
it is replaced by a copy created by \f5malloc\fP(3). it is replaced by a copy created by \f3malloc\fP(3).
The \f5nofree\fP field is set to \f50\fP. The \f3nofree\fP field is set to \f30\fP.
The new discipline is returned. The new discipline is returned.
Otherwise, \f5NULL\fP is returned. Otherwise, \f3NULL\fP is returned.
.IP .IP
\f50\fP: \f30\fP:
If \fIfp\fP is non-\f5NULL\fP then it is equivalent to \f5NV_FIRST\fP. If \fIfp\fP is non-\f3NULL\fP then it is equivalent to \f3NV_FIRST\fP.
Otherwise, it is equivalent to \f5NV_POP\fP. Otherwise, it is equivalent to \f3NV_POP\fP.
.PP .PP
The The
\f5nv_hasdisc()\fP function can be used to tell whether a discipline \f3nv_hasdisc()\fP function can be used to tell whether a discipline
whose discipline functions are those defined in \fIdp\fP. whose discipline functions are those defined in \fIdp\fP.
A pointer to this discipline is returned. A pointer to this discipline is returned.
.PP .PP
The \f5nv_aindex()\fP function returns The \f3nv_aindex()\fP function returns
the current index for the current index for
the indexed array given by the name-value pair pointer \fInp\fP. the indexed array given by the name-value pair pointer \fInp\fP.
The return value is negative if \fInp\fP refers to The return value is negative if \fInp\fP refers to
an associative array. an associative array.
.PP .PP
The \f5nv_setarray()\fP function is used to create an associative array The \f3nv_setarray()\fP function is used to create an associative array
from a name-value pair node. from a name-value pair node.
The function \fIfun\fP defines the semantics of the associative The function \fIfun\fP defines the semantics of the associative
array. array.
Using \fIfun\fP equal to \f5nv_associative()\fP implements the default Using \fIfun\fP equal to \f3nv_associative()\fP implements the default
associative array semantics associative array semantics
that are used with \f5typeset\ -A\fP. that are used with \f3typeset\ -A\fP.
The function \fIfun\fP will be called with third argument as follows: The function \fIfun\fP will be called with third argument as follows:
.IP .IP
\f5NV_AINIT\fP: \f3NV_AINIT\fP:
This will be called at initialization. This will be called at initialization.
The function you supply must return a pointer to a structure The function you supply must return a pointer to a structure
that contains the type \f5Namarr_t\fP as the first element. that contains the type \f3Namarr_t\fP as the first element.
All other calls receive this value as an argument. All other calls receive this value as an argument.
.IP .IP
\f5NV_AFREE\fP: \f3NV_AFREE\fP:
This will be called after all elements of the name-value pair have been This will be called after all elements of the name-value pair have been
deleted and the array is to be freed. deleted and the array is to be freed.
.IP .IP
\f5NV_ADELETE\fP: \f3NV_ADELETE\fP:
The current element should be deleted. The current element should be deleted.
.IP .IP
\f5NV_ANEXT\fP: \f3NV_ANEXT\fP:
This means that the array subscript should be advanced to the This means that the array subscript should be advanced to the
next subscript. A \f5NULL\fP return indicates that there are next subscript. A \f3NULL\fP return indicates that there are
no more subscripts. no more subscripts.
.IP .IP
\f5NV_ANAME\fP: \f3NV_ANAME\fP:
The name of the current subscript must be returned. The name of the current subscript must be returned.
.IP .IP
\f5NV_ACURRENT\fP: \f3NV_ACURRENT\fP:
Returns a pointer to a name-value pair corresponding to the Returns a pointer to a name-value pair corresponding to the
current subscript, or \f5NULL\fP if this array type doesn't current subscript, or \f3NULL\fP if this array type doesn't
create represent each element as a name-value pair. create represent each element as a name-value pair.
.IP .IP
\f5NV_ASETSUB\fP: \f3NV_ASETSUB\fP:
Set the current subscript to the name-value pair passed in Set the current subscript to the name-value pair passed in
as the second argument. as the second argument.
.PP .PP
If \fInp\fP refers to an array, If \fInp\fP refers to an array,
\f5nv_arrayptr()\fP returns a pointer to \f3nv_arrayptr()\fP returns a pointer to
the array discipline structure \f5Namarr_t\fP. the array discipline structure \f3Namarr_t\fP.
Otherwise \f5nv_arrayptr()\fP returns \f5NULL\fP. Otherwise \f3nv_arrayptr()\fP returns \f3NULL\fP.
.PP .PP
If \fInp\fP refers to an array, If \fInp\fP refers to an array,
the \f5nv_getsub()\fP returns a pointer to the \f3nv_getsub()\fP returns a pointer to
the name of the current subscript. the name of the current subscript.
Otherwise, \f5nv_getsub()\fP Otherwise, \f3nv_getsub()\fP
returns \f5NULL\fP. returns \f3NULL\fP.
.PP .PP
The \f5nv_opensub()\fP function returns The \f3nv_opensub()\fP function returns
a pointer to the name-value pair corresponding a pointer to the name-value pair corresponding
to the current subscript in an associative array. to the current subscript in an associative array.
Note that the \f5nv_close()\fP function should be called Note that the \f3nv_close()\fP function should be called
when the pointer is no longer needed. when the pointer is no longer needed.
.PP .PP
The \f5nv_putsub()\fP function is used to The \f3nv_putsub()\fP function is used to
set the subscript for the next reference to \f5np\fP. set the subscript for the next reference to \f3np\fP.
If the \f5name\fP argument is not \f5NULL\fP, If the \f3name\fP argument is not \f3NULL\fP,
it defines the value of the next subscript. it defines the value of the next subscript.
The \f5mode\fP argument can contain one or more of the following flags: The \f3mode\fP argument can contain one or more of the following flags:
.IP .IP
\f5ARRAY_ADD\fP: \f3ARRAY_ADD\fP:
Add the subscript if not found. Add the subscript if not found.
Otherwise, \f5nv_putsub()\fP returns \f5NULL\fP if the Otherwise, \f3nv_putsub()\fP returns \f3NULL\fP if the
given subscript is not found. given subscript is not found.
.IP .IP
\f5ARRAY_SCAN\fP: \f3ARRAY_SCAN\fP:
Begin a walk through the subscripts starting at the subscript Begin a walk through the subscripts starting at the subscript
given by \f5name\fP. If \f5name\fP is \f5NULL\fP given by \f3name\fP. If \f3name\fP is \f3NULL\fP
the walk is started from the beginning. the walk is started from the beginning.
.IP .IP
\f5ARRAY_UNDEF\fP: \f3ARRAY_UNDEF\fP:
This causes any current scan to terminate and leaves the This causes any current scan to terminate and leaves the
subscript in an undefined state. subscript in an undefined state.
.PP .PP
If \f5ARRAY_ADD\fP is not given and the subscript If \f3ARRAY_ADD\fP is not given and the subscript
does not exist, a \f5NULL\fP value is returned. does not exist, a \f3NULL\fP value is returned.
.PP .PP
The \f5nv_nextsub()\fP function is used to advance to the The \f3nv_nextsub()\fP function is used to advance to the
next subscript. next subscript.
It returns 0 if there are no more subscripts or if called It returns 0 if there are no more subscripts or if called
when not in a scan. when not in a scan.
.PP .PP
The \f5nv_setref()\fP function makes the name-value pair \f5np\fP The \f3nv_setref()\fP function makes the name-value pair \f3np\fP
into a reference to the variable whose name is given by into a reference to the variable whose name is given by
the value of \f5np\fP. The \f5nv_open()\fP open function is the value of \f3np\fP. The \f3nv_open()\fP open function is
called with this name, the dictionary given by \f5dp\fP, called with this name, the dictionary given by \f3dp\fP,
and the \f5flags\fP argument. and the \f3flags\fP argument.
A \f5NULL\fP value causes the shell global variable dictionary to be searched. A \f3NULL\fP value causes the shell global variable dictionary to be searched.
.PP .PP
The \f5nv_setvtree()\fP function makes the name-value pair \f5np\fP The \f3nv_setvtree()\fP function makes the name-value pair \f3np\fP
into a tree structured variable so that \f5nv_getval()\fP into a tree structured variable so that \f3nv_getval()\fP
will return a string containing all the names and values of will return a string containing all the names and values of
children nodes in a format that can be used in children nodes in a format that can be used in
a shell compound assignment. a shell compound assignment.
.PP .PP
The \f5nv_type()\fP function returns a name_value pair pointer The \f3nv_type()\fP function returns a name_value pair pointer
that contains the type definition for the specified name-value pair. that contains the type definition for the specified name-value pair.
The \fInvname\fP field contains the name for the type. The \fInvname\fP field contains the name for the type.
.PP .PP
The \f5nv_settype()\fP function converts the name-value pair The \f3nv_settype()\fP function converts the name-value pair
given by \fInp\fP into the type given by \fItp\fP. given by \fInp\fP into the type given by \fItp\fP.
.PP .PP
The \f5nv_addtype()\fP function adds the name of the type given by The \f3nv_addtype()\fP function adds the name of the type given by
\fInp\fP to the list of declaration built-ins. The \fIstr\fP \fInp\fP to the list of declaration built-ins. The \fIstr\fP
argument contains the string used by \f5optget\fP(3) to generate argument contains the string used by \f3optget\fP(3) to generate
the man page and process the options. The \fIop\fP argument the man page and process the options. The \fIop\fP argument
specifies the callback discipline used by \f5optget\fP(3) and specifies the callback discipline used by \f3optget\fP(3) and
\fIsz\fP specifies the size of the callback information so \fIsz\fP specifies the size of the callback information so
that the discipline \fBoptget\fP(3) can be extended with private that the discipline \fBoptget\fP(3) can be extended with private
data used by the callback function. data used by the callback function.
.P .P
The \f5nv_mkinttype()\fP function creates named integer types The \f3nv_mkinttype()\fP function creates named integer types
of the specified \fIname\fP. The \fIsize\fP parameter is the size of the specified \fIname\fP. The \fIsize\fP parameter is the size
in bytes of the integer variable and \fIus\fP is non-zero in bytes of the integer variable and \fIus\fP is non-zero
for unsigned integer types. If \fIdp\fP is specified then integer for unsigned integer types. If \fIdp\fP is specified then integer

View file

@ -800,7 +800,7 @@ is preceded by a tilde, then it is checked up to a
.B / .B /
to see if it matches a user name in the to see if it matches a user name in the
password database (see password database (see
.IR getpwname (3).) .IR getpwname (3)).
If a match is found, the If a match is found, the
.B \(ap .B \(ap
and the matched login name are replaced by the and the matched login name are replaced by the
@ -1581,9 +1581,9 @@ the call to this function.
Finally when Finally when
.B _ .B _
is used as the name of the first variable of a type definition, is used as the name of the first variable of a type definition,
the new type is derived from the type of the first variable (See the new type is derived from the type of the first variable. (See
.I "Type Variables"\^ .I "Type Variables"\^
below.). below.)
.TP .TP
.B ! .B !
The process id or the pool name and job number of the last background command The process id or the pool name and job number of the last background command
@ -5622,7 +5622,7 @@ reserved word syntax,
the function is executed in the current environment the function is executed in the current environment
(as if it had been defined with the (as if it had been defined with the
.IB name () .IB name ()
syntax.) syntax).
Otherwise if Otherwise if
.I name\^ .I name\^
refers to a file, the refers to a file, the
@ -6758,7 +6758,7 @@ or
.B %f .B %f
formats, separates groups of digits with the grouping delimiter formats, separates groups of digits with the grouping delimiter
.RB ( , .RB ( ,
on groups of 3 in the C locale.) on groups of 3 in the C locale).
.PD .PD
.PP .PP
.RE .RE

View file

@ -416,7 +416,7 @@ static void put_cdpath(register Namval_t* np,const char *val,int flags,Namfun_t
} }
#ifdef _hdr_locale #ifdef _hdr_locale
/* Trap for LC_ALL, LC_CTYPE, LC_MESSAGES, LC_COLLATE and LANG */ /* Trap for the LC_* and LANG variables */
static void put_lang(Namval_t* np,const char *val,int flags,Namfun_t *fp) static void put_lang(Namval_t* np,const char *val,int flags,Namfun_t *fp)
{ {
Shell_t *shp = sh_getinterp(); Shell_t *shp = sh_getinterp();

View file

@ -186,7 +186,7 @@ int sh_main(int ac, char *av[], Shinit_f userinit)
#if SHOPT_REMOTE #if SHOPT_REMOTE
/* /*
* Building ksh with SHOPT_REMOTE=1 causes ksh to set --rc if stdin is * Building ksh with SHOPT_REMOTE=1 causes ksh to set --rc if stdin is
* a socket (presumably part of a remote shell invocation.) * a socket (presumably part of a remote shell invocation).
*/ */
if(!sh_isoption(SH_RC) && !fstat(0, &statb) && REMOTE(statb.st_mode)) if(!sh_isoption(SH_RC) && !fstat(0, &statb) && REMOTE(statb.st_mode))
sh_onoption(SH_RC); sh_onoption(SH_RC);

View file

@ -1198,7 +1198,7 @@ pid_t path_spawn(Shell_t *shp,const char *opath,register char **argv, char **env
if(*path!='/' && path!=opath) if(*path!='/' && path!=opath)
{ {
/* /*
* The following code because execv(foo,) and execv(./foo,) * The following code is because execv(foo,) and execv(./foo,)
* may not yield the same results * may not yield the same results
*/ */
char *sp = (char*)sh_malloc(strlen(path)+3); char *sp = (char*)sh_malloc(strlen(path)+3);

View file

@ -1,7 +1,7 @@
.fp 5 CW .fp 5 CW
.TH SHELL 3 "28 Feb 2003" AST .TH SHELL 3 "28 Feb 2003" AST
.SH NAME .SH NAME
\fBshell\fR \- a \f5ksh\fP library interface \fBshell\fR \- a \f3ksh\fP library interface
.SH SYNOPSIS .SH SYNOPSIS
.ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i 5.6i .ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i 5.6i
.SS "HEADERS/LIBRARIES" .SS "HEADERS/LIBRARIES"
@ -30,66 +30,66 @@ int sh_main(int \fIargc\fP, char *\fIargv\fP[], Sh_init \fIfn\fP);
Shell_t *sh_init(int \fIargc\fP, char *\fIargv\fP[]); Shell_t *sh_init(int \fIargc\fP, char *\fIargv\fP[]);
Shell_t *sh_getinterp(void); Shell_t *sh_getinterp(void);
Namval_t *sh_addbuiltin(const char *\fIname\fP,Sh_bltin_f \fIfn\fP,void *\fIarg\fP); Namval_t *sh_addbuiltin(const char *\fIname\fP, Sh_bltin_f \fIfn\fP, void *\fIarg\fP);
unsigned int sh_isoption(int \fIoption\fP); unsigned int sh_isoption(int \fIoption\fP);
unsigned int sh_onoption(int \fIoption\fP); unsigned int sh_onoption(int \fIoption\fP);
unsigned int sh_offoption(int \fIoption\fP); unsigned int sh_offoption(int \fIoption\fP);
void *sh_parse(Shell_t *\fIshp\fP, Sfio_t *\fIsp\fP, int \fIflags\fP); void *sh_parse(Shell_t *\fIshp\fP, Sfio_t *\fIsp\fP, int \fIflags\fP);
int sh_trap(const char *\fIstring\fP, int \fImode\fP); int sh_trap(const char *\fIstring\fP, int \fImode\fP);
int sh_run(int \fIargc\fP, char *\fIargv\fP[]); int sh_run(int \fIargc\fP, char *\fIargv\fP[]);
int sh_eval(Sfio_t *\fIsp\fP,int \fImode\fP); int sh_eval(Sfio_t *\fIsp\fP, int \fImode\fP);
int sh_fun(Namval_t *\fIfunnode\fP, Namval_t *\fIvarnode\fP, char *\fIargv\fP[]); int sh_fun(Namval_t *\fIfunnode\fP, Namval_t *\fIvarnode\fP, char *\fIargv\fP[]);
int sh_funscope(int \fIargc\fP,char *\fIargv\fP[],int(*\fIfn\fP)(void*),void *\fIarg\fP,int \fIflags\fP); int sh_funscope(int \fIargc\fP, char *\fIargv\fP[], int(*\fIfn\fP)(void*), void *\fIarg\fP, int \fIflags\fP);
Shscope_t *sh_getscope(int \fIindex\fP,int \fIwhence\fP); Shscope_t *sh_getscope(int \fIindex\fP, int \fIwhence\fP);
Shscope_t *sh_setscope(Shscope_t *\fIscope\fP); Shscope_t *sh_setscope(Shscope_t *\fIscope\fP);
int (*sh_fdnotify(int(*\fIfn\fP)(int,int)))(int,int); int (*sh_fdnotify(int(*\fIfn\fP)(int,int)))(int,int);
char *sh_fmtq(const char *\fIstring\fP); char *sh_fmtq(const char *\fIstring\fP);
void *sh_waitnotify(Shwait_f \fIfn\fP); void *sh_waitnotify(Shwait_f \fIfn\fP);
void sh_delay(double \fIsec\fP, int \fIsflag\fP); void sh_delay(double \fIsec\fP, int \fIsflag\fP);
Sfio_t *sh_iogetiop(int \fIfd\fP, int \fImode\fP); Sfio_t *sh_iogetiop(int \fIfd\fP, int \fImode\fP);
int sh_sigcheck(void); int sh_sigcheck(void);
.ft R .ft R
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
The \fIShell\fP library is a set of functions used for The \fIShell\fP library is a set of functions used for
writing extensions to \f5ksh\fP or writing commands writing extensions to \f3ksh\fP or writing commands
that embed shell command processing. that embed shell command processing.
The include file \f5<shell.h>\fP contains the type definitions, The include file \f3<shell.h>\fP contains the type definitions,
function prototypes and symbolic constants defined by function prototypes and symbolic constants defined by
this interface. It also defines replacement definitions for this interface. It also defines replacement definitions for
the standard library functions the standard library functions
\f5access()\fP, \f3access()\fP,
\f5close()\fP, \f3close()\fP,
\f5dup()\fP, \f3dup()\fP,
\f5exit()\fP, \f3exit()\fP,
\f5fcntl()\fP, \f3fcntl()\fP,
\f5lseek()\fP, \f3lseek()\fP,
\f5open()\fP, \f3open()\fP,
\f5pipe()\fP, \f3pipe()\fP,
\f5read()\fP, \f3read()\fP,
and and
\f5write()\fP \f3write()\fP
that must be used that must be used
with all code with all code
intended to be compiled as built-in commands. intended to be compiled as built-in commands.
.P .P
The \f5<shell.h>\fP header includes \f5<ast.h>\fP which The \f3<shell.h>\fP header includes \f3<ast.h>\fP which
in turn includes the standard include files, \f5<stddef.h>\fP, in turn includes the standard include files, \f3<stddef.h>\fP,
\f5<stdlib.h>\fP, \f5<stdarg.h>\fP, \f5<limits.h>\fP, \f3<stdlib.h>\fP, \f3<stdarg.h>\fP, \f3<limits.h>\fP,
\f5<stdio.h>\fP, \f5<string.h>\fP, \f5<unistd.h>\fP, \f3<stdio.h>\fP, \f3<string.h>\fP, \f3<unistd.h>\fP,
\f5<sys/types.h>\fP, \f5<fcntl.h>\fP, and \f5<locale.h>\fP. \f3<sys/types.h>\fP, \f3<fcntl.h>\fP, and \f3<locale.h>\fP.
The \f5<shell.h>\fP header also includes the headers The \f3<shell.h>\fP header also includes the headers
\f5<cdt.h>\fP, \f3<cdt.h>\fP,
\f5<cmd.h>\fP, \f3<cmd.h>\fP,
\f5<sfio.h>\fP, \f3<sfio.h>\fP,
\f5<nval.h>\fP, \f3<nval.h>\fP,
\f5<stk.h>\fP, \f3<stk.h>\fP,
and \f5<error.h>\fP and \f3<error.h>\fP
so that in most cases, programs only require the single so that in most cases, programs only require the single
header \f5<shell.h>\fP. header \f3<shell.h>\fP.
.PP .PP
Programs can use this library in one of the following ways: Programs can use this library in one of the following ways:
.PD 0 .PD 0
@ -97,321 +97,322 @@ Programs can use this library in one of the following ways:
.B 1 .B 1
To write builtin commands and/or other code that will be loaded To write builtin commands and/or other code that will be loaded
into the shell by loading dynamic libraries into the shell by loading dynamic libraries
at run time using the \f5builtin\fP(1) command. at run time using the \f3builtin\fP(1) command.
In this case the shell will look for a function named \f5lib_init\fP In this case the shell will look for a function named \f3lib_init\fP
in your library and, if found, will execute this function with in your library and, if found, will execute this function with
two arguments. The first two arguments. The first
argument will be an \f5int\fP with value \f50\fP when the library is loaded. argument will be an \f3int\fP with value \f30\fP when the library is loaded.
The second argument will contain a pointer to a structure of type The second argument will contain a pointer to a structure of type
\f5Shbltin_t\fP. \f3Shbltin_t\fP.
In addition, for each argument named on the \f5builtin\fP In addition, for each argument named on the \f3builtin\fP
command line, it will look for a function named \f5b_\fP\fIname\fP\f5()\fP command line, it will look for a function named \f3b_\fP\fIname\fP\f3()\fP
in your library and will \fIname\fP as a built-in. in your library and will \fIname\fP as a built-in.
.TP .TP
.B 2 .B 2
To build separate a separate command that uses the shell as a To build separate a separate command that uses the shell as a
library at compile or run time. library at compile or run time.
In this case the \f5sh_init()\fP function must be called to In this case the \f3sh_init()\fP function must be called to
initialize this library before any other commands in this library initialize this library before any other commands in this library
are invoked. are invoked.
The arguments \fIargc\fP and \fIargv\fP are the number The arguments \fIargc\fP and \fIargv\fP are the number
of arguments and the vector of arguments as supplied by the shell. of arguments and the vector of arguments as supplied by the shell.
It returns a pointer the \f5Shell_t\fP. It returns a pointer the \f3Shell_t\fP.
.TP .TP
.B 3 .B 3
To build a new version of \f5ksh\fP with extended capabilities, To build a new version of \f3ksh\fP with extended capabilities,
for example \f5tksh\fP(1). for example \f3tksh\fP(1).
In this case, the user writes a \f5main()\fP function that In this case, the user writes a \f3main()\fP function that
calls \f5sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments calls \f3sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments
from \f5main\fP and pointer to function, \fIfn\fP as a third from \f3main\fP and pointer to function, \fIfn\fP as a third
argument.. The function \fIfn\fP will argument.. The function \fIfn\fP will
be invoked with argument \f50\fP after \f5ksh\fP has done initialization, be invoked with argument \f30\fP after \f3ksh\fP has done initialization,
but before \f5ksh\fP has processed any start up files or executed but before \f3ksh\fP has processed any start up files or executed
any commands. The function \fIfn\fP any commands. The function \fIfn\fP
will be invoked with an argument of \f51\fP before \f5ksh\fP will be invoked with an argument of \f31\fP before \f3ksh\fP
begins to execute a script that has been invoked by name begins to execute a script that has been invoked by name
since \f5ksh\fP cleans up memory and long jumps back to since \f3ksh\fP cleans up memory and long jumps back to
the beginning of the shell in this case. the beginning of the shell in this case.
The function \fIfn\fP will be called with argument \f5-1\fP before The function \fIfn\fP will be called with argument \f3-1\fP before
the shell exits. the shell exits.
.PD .PD
.PP .PP
The \f5Shell_t\fP structure contains the following fields: The \f3Shell_t\fP structure contains the following fields:
.nf .nf
.ft 5 .ft 5
Shopt_t \fIoptions\fP; \fR/* set -o options */\fP Shopt_t \fIoptions\fP; \fR/* set -o options */\fP
Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP
Dt_t *\fIfun_tree\fP; \fR/* shell function dictionary */\fP Dt_t *\fIfun_tree\fP; \fR/* shell function dictionary */\fP
Dt_t *\fIalias_tree\fP; \fR/* shell alias dictionary */\fP Dt_t *\fIalias_tree\fP; \fR/* shell alias dictionary */\fP
Dt_t *\fIbltin_tree\fP; \fR/* shell built-in dictionary */\fP Dt_t *\fIbltin_tree\fP; \fR/* shell built-in dictionary */\fP
Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP Dt_t *\fItrack_tree\fP; \fR/* shell hash table */\fP
char *\fIinfile_name\fP; \fR/* path name of current input file */\fP Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP
int \fIinlineno\fP; \fR/* line number of current input file */\fP char *\fIinfile_name\fP; \fR/* path name of current input file */\fP
int \fIexitval\fP; \fR/* most recent exit value */\fP int \fIinlineno\fP; \fR/* line number of current input file */\fP
int \fIexitval\fP; \fR/* most recent exit value */\fP
.ft R .ft R
.fi .fi
This structure is returned by \f5sh_init()\fP but can also be retrieved This structure is returned by \f3sh_init()\fP but can also be retrieved
by a call to \f5sh_getinterp()\fP. by a call to \f3sh_getinterp()\fP.
.PP .PP
All built-in commands to the shell are invoked with All built-in commands to the shell are invoked with
three arguments. The first two arguments give the three arguments. The first two arguments give the
number of arguments and the argument list number of arguments and the argument list
and uses the same conventions as the \f5main()\fP function and uses the same conventions as the \f3main()\fP function
of a program. The third argument is a pointer to a structure of a program. The third argument is a pointer to a structure
of type \f5Shbltin_t\fP. This structure contains \f5shp\fP which is a pointer of type \f3Shbltin_t\fP. This structure contains \f3shp\fP which is a pointer
to the shell interpreter, and \f5ptr\fP which is a pointer that to the shell interpreter, and \f3ptr\fP which is a pointer that
can be associated with each built-in. can be associated with each built-in.
The \f5sh_addbuiltin()\fP function is used to add, replace or delete The \f3sh_addbuiltin()\fP function is used to add, replace or delete
built-in commands. built-in commands.
It takes the name of the built-in, \fIname\fP, a pointer It takes the name of the built-in, \fIname\fP, a pointer
to the function that implements the built-in, \fIfn\fP, and to the function that implements the built-in, \fIfn\fP, and
a pointer that will be passed to the function in the \f5ptr\fP field when a pointer that will be passed to the function in the \f3ptr\fP field when
it is invoked. it is invoked.
If, \fIfn\fP is non-\f5NULL\fP the built-in command If, \fIfn\fP is non-\f3NULL\fP the built-in command
is added or replaced. Otherwise, \f5sh_addbuiltin()\fP will is added or replaced. Otherwise, \f3sh_addbuiltin()\fP will
return a pointer to the built-in if it exists or \f5NULL\fP otherwise. return a pointer to the built-in if it exists or \f3NULL\fP otherwise.
If \fIarg\fP is \f5(void*)1\fP the built-in will be deleted. If \fIarg\fP is \f3(void*)1\fP the built-in will be deleted.
The \fIname\fP argument can be in the format of a pathname. The \fIname\fP argument can be in the format of a pathname.
It cannot be the name of any of the special built-in commands. It cannot be the name of any of the special built-in commands.
If \fIname\fP contains a \f5/\fP, the built-in is the basename of If \fIname\fP contains a \f3/\fP, the built-in is the basename of
the pathname and the built-in will only be executed the pathname and the built-in will only be executed
if the given pathname is encountered when performing if the given pathname is encountered when performing
a path search. a path search.
When adding or replacing a built-in, When adding or replacing a built-in,
\f5sh_addbuiltin()\fP function returns a pointer to \f3sh_addbuiltin()\fP function returns a pointer to
the name-value pair corresponding to the built-in on success and \f5NULL\fP the name-value pair corresponding to the built-in on success and \f3NULL\fP
if it is unable to add or replace the built-in. if it is unable to add or replace the built-in.
When deleting a built-in, \f5NULL\fP is returned on success or When deleting a built-in, \f3NULL\fP is returned on success or
if not found, and the name-value pair pointer is returned if the built-in if not found, and the name-value pair pointer is returned if the built-in
cannot be deleted. cannot be deleted.
.PP .PP
The functions \f5sh_onoption()\fP, \f5sh_offoption()\fP, \f5sh_isoption()\fP The functions \f3sh_onoption()\fP, \f3sh_offoption()\fP, \f3sh_isoption()\fP
are used to set, unset, and test for shell options respectively. are used to set, unset, and test for shell options respectively.
The \fIoption\fP argument can be any one of the following: The \fIoption\fP argument can be any one of the following:
.IP .IP
\f5SH_ALLEXPORT\fP: \f3SH_ALLEXPORT\fP:
The \f5NV_EXPORT\fP attribute is given to each variable whose The \f3NV_EXPORT\fP attribute is given to each variable whose
name is an identifier when a value is assigned. name is an identifier when a value is assigned.
.IP .IP
\f5SH_BGNICE\fP: \f3SH_BGNICE\fP:
Each background process is run at a lower priority. Each background process is run at a lower priority.
.IP .IP
\f5SH_ERREXIT\fP: \f3SH_ERREXIT\fP:
Causes a non-interactive shell to exit when a command, Causes a non-interactive shell to exit when a command,
other than a conditional command, returns non-zero. other than a conditional command, returns non-zero.
.IP .IP
\f5SH_EMACS\fP: \f3SH_EMACS\fP:
The emacs editing mode. The emacs editing mode.
.IP .IP
\f5SH_GMACS\fP: \f3SH_GMACS\fP:
Same as the emacs editing mode except for the behavior of CONTROL-T. Same as the emacs editing mode except for the behavior of CONTROL-T.
.IP .IP
\f5SH_HISTORY\fP: \f3SH_HISTORY\fP:
Indicates that the history file has been created and that Indicates that the history file has been created and that
commands can be logged. commands can be logged.
.IP .IP
\f5SH_IGNOREEOF\fP: \f3SH_IGNOREEOF\fP:
Do not treat end-of-file as exit. Do not treat end-of-file as exit.
.IP .IP
\f5SH_INTERACTIVE\fP: \f3SH_INTERACTIVE\fP:
Set for interactive shells. Set for interactive shells.
Do not set or unset this option. Do not set or unset this option.
.IP .IP
\f5SH_MARKDIRS\fP: \f3SH_MARKDIRS\fP:
A \fB/\fP is added to the end of each directory generated by pathname A \fB/\fP is added to the end of each directory generated by pathname
expansion. expansion.
.IP .IP
\f5SH_MONITOR\fP: \f3SH_MONITOR\fP:
Indicates that the monitor option is enabled for job control. Indicates that the monitor option is enabled for job control.
.IP .IP
\f5SH_NOCLOBBER\fP: \f3SH_NOCLOBBER\fP:
The \fB>\fP redirection will fail if the file exists. Each file The \fB>\fP redirection will fail if the file exists. Each file
created with \fB>\fP will have the \f5O_EXCL\fP bit set as described created with \fB>\fP will have the \f3O_EXCL\fP bit set as described
in \f5<fcntl.h>\fP in \f3<fcntl.h>\fP
.IP .IP
\f5SH_NOGLOB\fP: \f3SH_NOGLOB\fP:
Do not perform pathname expansion. Do not perform pathname expansion.
.IP .IP
\f5SH_NOLOG\fP: \f3SH_NOLOG\fP:
Do not save function definitions in the history file. Do not save function definitions in the history file.
.IP .IP
\f5SH_NOTIFY\fP: \f3SH_NOTIFY\fP:
Cause a message to be generated as soon as each background job completes. Cause a message to be generated as soon as each background job completes.
.IP .IP
\f5SH_NOUNSET\fP: \f3SH_NOUNSET\fP:
Cause the shell to fail with an error of an unset variable is Cause the shell to fail with an error of an unset variable is
referenced. referenced.
.IP .IP
\f5SH_PRIVILEGED\fP: \f3SH_PRIVILEGED\fP:
This mode is on whenever the effective uid (gid) is not equal to the real This mode is on whenever the effective uid (gid) is not equal to the real
uid (gid). Turning this off causes the effective uid and gid to be set to uid (gid). Turning this off causes the effective uid and gid to be set to
the real uid and gid. the real uid and gid.
.IP .IP
\f5SH_VERBOSE\fP: \f3SH_VERBOSE\fP:
Cause each line to be echoed as it is read by the parser. Cause each line to be echoed as it is read by the parser.
.IP .IP
\f5SH_XTRACE\fP: \f3SH_XTRACE\fP:
Cause each command to be displayed after all expansions, but Cause each command to be displayed after all expansions, but
before execution. before execution.
.IP .IP
\f5SH_VI\fP: \f3SH_VI\fP:
The vi edit mode. The vi edit mode.
.IP .IP
\f5SH_VIRAW\fP: \f3SH_VIRAW\fP:
Read character at a time rather than line at a time when Read character at a time rather than line at a time when
in vi edit mode. in vi edit mode.
.IP .IP
.PP .PP
The \f5sh_trap()\fP function can be used to compile and execute The \f3sh_trap()\fP function can be used to compile and execute
a string or file. a string or file.
A value of \f50\fP for \fImode\fP indicates that \fIname\fP A value of \f30\fP for \fImode\fP indicates that \fIname\fP
refers to a string. A value of \f51\fP for \fImode\fP refers to a string. A value of \f31\fP for \fImode\fP
indicates that \fIname\fP is an \f5Sfio_t*\fP to an open stream. indicates that \fIname\fP is an \f3Sfio_t*\fP to an open stream.
A value of \f52\fP for \fImode\fP indicates that \fIname\fP A value of \f32\fP for \fImode\fP indicates that \fIname\fP
points to a parse tree that has been returned by \f5sh_parse()\fP. points to a parse tree that has been returned by \f3sh_parse()\fP.
The complete file associated with the string or file The complete file associated with the string or file
is compiled and then executed so that aliases defined is compiled and then executed so that aliases defined
within the string or file will not take effect until within the string or file will not take effect until
the next command is executed. the next command is executed.
The shell's \f5$?\fP special parameter is made local to the string The shell's \f3$?\fP special parameter is made local to the string
or file executed so that it is not affected for subsequent commands. or file executed so that it is not affected for subsequent commands.
The return value of \f5sh_trap()\fP is the exit status of The return value of \f3sh_trap()\fP is the exit status of
the last command executed by the string or file. the last command executed by the string or file.
.PP .PP
The \f5sh_run()\fP function will run the command given by The \f3sh_run()\fP function will run the command given by
by the argument list \fIargv\fP containing \fIargc\fP elements. by the argument list \fIargv\fP containing \fIargc\fP elements.
If \fIargv\fP\f5[0]\fP does not contain a \f5/\fP, it will If \fIargv\fP\f3[0]\fP does not contain a \f3/\fP, it will
be checked to see if it is a built-in or function before be checked to see if it is a built-in or function before
performing a path search. performing a path search.
.PP .PP
The \f5sh_eval()\fP function executes a string or file The \f3sh_eval()\fP function executes a string or file
stream \fIsp\fP. stream \fIsp\fP.
If \fImode\fP is non-zero and the history file has If \fImode\fP is non-zero and the history file has
been created, the stream defined by \fIsp\fP been created, the stream defined by \fIsp\fP
will be appended to the history file as a command. will be appended to the history file as a command.
.PP .PP
The \f5sh_parse()\fP function takes a pointer to the The \f3sh_parse()\fP function takes a pointer to the
shell interpreter \fIshp\fP, a pointer to a string or file stream shell interpreter \fIshp\fP, a pointer to a string or file stream
\fIsp\fP, and compilation flags, and returns a pointer \fIsp\fP, and compilation flags, and returns a pointer
to a parse tree of the compiled stream. This pointer can to a parse tree of the compiled stream. This pointer can
be used in subsequent calls to \f5sh_trap()\fP. be used in subsequent calls to \f3sh_trap()\fP.
The compilation flags can be zero or more of the following: The compilation flags can be zero or more of the following:
.IP .IP
\f5SH_NL\fP: \f3SH_NL\fP:
Treat new-lines as \fB;\fP. Treat new-lines as \fB;\fP.
.IP .IP
\f5SH_EOF\fP: \f3SH_EOF\fP:
An end of file causes syntax error. By default it will An end of file causes syntax error. By default it will
be treated as a new-line. be treated as a new-line.
.PP .PP
\f5ksh\fP executes each function defined with the \f5function\fP \f3ksh\fP executes each function defined with the \f3function\fP
reserved word in a separate scope. The \f5Shscope_t\fP type reserved word in a separate scope. The \f3Shscope_t\fP type
provides an interface to some of the information that provides an interface to some of the information that
is available on each scope. The structure contains is available on each scope. The structure contains
the following public members: the following public members:
.nf .nf
\f5Sh_scope_t *par_scope;\fP \f3Sh_scope_t *par_scope;\fP
\f5int argc;\fP \f3int argc;\fP
\f5char **argv;\fP \f3char **argv;\fP
\f5char *cmdname;\fP \f3char *cmdname;\fP
\f5Dt_t *var_tree;\fP \f3Dt_t *var_tree;\fP
.fi .fi
The \f5sh_getscope()\fP function can be used to get the The \f3sh_getscope()\fP function can be used to get the
scope information associated with existing scope. scope information associated with existing scope.
Scopes are numbered from \f50\fP for the global scope Scopes are numbered from \f30\fP for the global scope
up to the current scope level. The \fIwhence\fP up to the current scope level. The \fIwhence\fP
argument uses the symbolic constants associated with \f5lseek()\fP argument uses the symbolic constants associated with \f3lseek()\fP
to indicate whether the \f5Iscope\fP argument is absolute, to indicate whether the \f3Iscope\fP argument is absolute,
relative to the current scope, or relative to the topmost scope. relative to the current scope, or relative to the topmost scope.
The\f5sh_setscope()\fP function can be used to make a The\f3sh_setscope()\fP function can be used to make a
a known scope the current scope. It returns a pointer to the a known scope the current scope. It returns a pointer to the
old current scope. old current scope.
.PP .PP
The \f5sh_funscope()\fP function can be used to run a function The \f3sh_funscope()\fP function can be used to run a function
in a new scope. The arguments \fIargc\fP and \fIargv\fP in a new scope. The arguments \fIargc\fP and \fIargv\fP
are the number of arguments and the list of arguments are the number of arguments and the list of arguments
respectively. If \fIfn\fP is non-\f5NULL\fP, then respectively. If \fIfn\fP is non-\f3NULL\fP, then
this function is invoked with \fIargc\fP, \fIargv\fP, and \fIarg\fP this function is invoked with \fIargc\fP, \fIargv\fP, and \fIarg\fP
as arguments. as arguments.
.PP .PP
The \f5sh_fun()\fP function can be called within a The \f3sh_fun()\fP function can be called within a
discipline function or built-in extension to execute a discipline function or built-in extension to execute a
discipline function script. discipline function script.
The argument \fIfunnode\fP is a pointer to the shell function The argument \fIfunnode\fP is a pointer to the shell function
or built-in to execute. or built-in to execute.
The argument \fIvarnode\fP is a pointer to the name The argument \fIvarnode\fP is a pointer to the name
value pair that has defined this discipline. value pair that has defined this discipline.
The array \fIargv\fP is a \f5NULL\fP terminated list of The array \fIargv\fP is a \f3NULL\fP terminated list of
arguments that are passed to the function. arguments that are passed to the function.
.PP .PP
By default, \f5ksh\fP only records but does not act By default, \f3ksh\fP only records but does not act
on signals when running a built-in command. on signals when running a built-in command.
If a built-in takes a substantial amount of time If a built-in takes a substantial amount of time
to execute, then it should check for interrupts to execute, then it should check for interrupts
periodically by calling \f5sh_sigcheck()\fP. periodically by calling \f3sh_sigcheck()\fP.
If a signal is pending, \f5sh_sigcheck()\fP will exit If a signal is pending, \f3sh_sigcheck()\fP will exit
the function you are calling and return to the point the function you are calling and return to the point
where the most recent built-in was invoked, or where where the most recent built-in was invoked, or where
\f5sh_eval()\fP or \f5sh_trap()\fP was called. \f3sh_eval()\fP or \f3sh_trap()\fP was called.
.PP .PP
The \f5sh_delay()\fP function is used to cause the The \f3sh_delay()\fP function is used to cause the
shell to sleep for a period of time defined by \fIsec\fP. shell to sleep for a period of time defined by \fIsec\fP.
If \fIsflag\fP is true, the shell will stop sleeping when If \fIsflag\fP is true, the shell will stop sleeping when
any signal is received; otherwise signals such as \f5SIGCONT\fP any signal is received; otherwise signals such as \f3SIGCONT\fP
and \f5SIGINFO\fP are treated normally. and \f3SIGINFO\fP are treated normally.
.PP .PP
The \f5sh_fmtq()\fP function can be used to convert a string The \f3sh_fmtq()\fP function can be used to convert a string
into a string that is quoted so that it can be reinput into a string that is quoted so that it can be reinput
to the shell. The quoted string returned by \f5sh_fmtq\fP to the shell. The quoted string returned by \f3sh_fmtq\fP
may be returned on the current stack, so that it may be returned on the current stack, so that it
must be saved or copied. must be saved or copied.
.PP .PP
The \f5sh_fdnotify()\fP function causes the function \fIfn\fP The \f3sh_fdnotify()\fP function causes the function \fIfn\fP
to be called whenever the shell duplicates or closes a file. to be called whenever the shell duplicates or closes a file.
It is provided for extensions that need to keep track of It is provided for extensions that need to keep track of
file descriptors that could be changed by shell commands. file descriptors that could be changed by shell commands.
The function \fIfn\fP is called with two arguments. The function \fIfn\fP is called with two arguments.
The first argument is the original file descriptor. The The first argument is the original file descriptor. The
second argument is the new file descriptor for duplicating second argument is the new file descriptor for duplicating
files, and \f5SH_FDCLOSE\fP when a file has been closed. files, and \f3SH_FDCLOSE\fP when a file has been closed.
The previously installed \f5sh_fdnotify()\fP function pointer The previously installed \f3sh_fdnotify()\fP function pointer
is returned. is returned.
.PP .PP
The \f5sh_waitnotify()\fP function causes the function \fIfn\fP The \f3sh_waitnotify()\fP function causes the function \fIfn\fP
to be called whenever the shell is waiting for input from to be called whenever the shell is waiting for input from
a slow device or waiting for a process to complete. a slow device or waiting for a process to complete.
This function can process events and run shell commands This function can process events and run shell commands
until there is input, the timer is reached or a signal arises. until there is input, the timer is reached or a signal arises.
It is called with three arguments. The first is the file It is called with three arguments. The first is the file
descriptor from which the shell trying to read or \f5\-1\fP descriptor from which the shell trying to read or \f3\-1\fP
if the shell is waiting for a process to complete. if the shell is waiting for a process to complete.
The second is a timeout in milliseconds. The second is a timeout in milliseconds.
A value of \f5\-1\fP for the timeout means that A value of \f3\-1\fP for the timeout means that
no timeout should be set. no timeout should be set.
The third argument is 0 for input file descriptors The third argument is 0 for input file descriptors
and 1 for output file descriptor. and 1 for output file descriptor.
The function needs to return a value \f5>0\fP if there The function needs to return a value \f3>0\fP if there
is input on the file descriptor, and a value \f5<0\fP is input on the file descriptor, and a value \f3<0\fP
if the timeout is reached or a signal has occurred. if the timeout is reached or a signal has occurred.
A value of \f50\fP indicates A value of \f30\fP indicates
that the function has returned without processing and that the shell that the function has returned without processing and that the shell
should wait for input or process completion. should wait for input or process completion.
The previous installed \f5sh_waitnotify()\fP function pointer is returned. The previous installed \f3sh_waitnotify()\fP function pointer is returned.
.PP .PP
The \f5sh_iogetiop()\fP function returns a pointer to the The \f3sh_iogetiop()\fP function returns a pointer to the
Sfio stream corresponding to file descriptor number \fIfd\fP Sfio stream corresponding to file descriptor number \fIfd\fP
and the given mode \fImode\fP. The mode can be either and the given mode \fImode\fP. The mode can be either
\f5SF_READ\fP or \f5SF_WRITE\fP. \f3SF_READ\fP or \f3SF_WRITE\fP.
The \fIfd\fP argument can the number of an open file descriptor or The \fIfd\fP argument can the number of an open file descriptor or
one of the following symbolic constants: one of the following symbolic constants:
.IP .IP
\f5SH_IOCOPROCESS\fP: \f3SH_IOCOPROCESS\fP:
The stream corresponding to the most recent co-process. The stream corresponding to the most recent co-process.
.IP .IP
\f5SH_IOHISTFILE\fP: \f3SH_IOHISTFILE\fP:
The stream corresponding to the history file. The stream corresponding to the history file.
If no stream exists corresponding to \fIfd\fP or the stream If no stream exists corresponding to \fIfd\fP or the stream
can not be accessed in the specified mode, \f5NULL\fP is returned. can not be accessed in the specified mode, \f3NULL\fP is returned.
.SH SEE ALSO .SH SEE ALSO
builtin(1) builtin(1)
cdt(3) cdt(3)

View file

@ -280,7 +280,7 @@ if [[ $(trap --version 2> /dev/null;print done) != done ]]
then err_exit 'trap builtin terminating after --version' then err_exit 'trap builtin terminating after --version'
fi fi
if [[ $(set --version 2> /dev/null;print done) != done ]] if [[ $(set --version 2> /dev/null;print done) != done ]]
then err_exit 'set builtin terminating after --veresion' then err_exit 'set builtin terminating after --version'
fi fi
unset -f foobar unset -f foobar
function foobar function foobar
@ -776,7 +776,7 @@ unset foo
integer foo=1 integer foo=1
exp=4 exp=4
got=$(foo+=3 command eval 'echo $foo') got=$(foo+=3 command eval 'echo $foo')
[[ $exp == $got ]] || err_exit "[1]: += assignment for environment variables doesn't work with 'command special_builtin'" \ [[ $exp == $got ]] || err_exit "Test 1: += assignment for environment variables doesn't work with 'command special_builtin'" \
"(expected $exp, got $got)" "(expected $exp, got $got)"
foo+=3 command eval 'test $foo' foo+=3 command eval 'test $foo'
(( foo == 1 )) || err_exit "environment isn't restored after 'command special_builtin'" \ (( foo == 1 )) || err_exit "environment isn't restored after 'command special_builtin'" \
@ -788,7 +788,7 @@ got=$(foo+=3 eval 'echo $foo')
unset foo unset foo
exp=barbaz exp=barbaz
got=$(foo=bar; foo+=baz command eval 'echo $foo') got=$(foo=bar; foo+=baz command eval 'echo $foo')
[[ $exp == $got ]] || err_exit "[2]: += assignment for environment variables doesn't work with 'command special_builtin'" \ [[ $exp == $got ]] || err_exit "Test 2: += assignment for environment variables doesn't work with 'command special_builtin'" \
"(expected $exp, got $got)" "(expected $exp, got $got)"
# Attempting to modify a readonly variable with the += operator should fail # Attempting to modify a readonly variable with the += operator should fail

View file

@ -878,8 +878,6 @@ got=$?
"(expected $exp, got $got)" "(expected $exp, got $got)"
# Tests for attempting to use a command name that's too long. # Tests for attempting to use a command name that's too long.
# To make the error messages readable, the long string is replaced
# with 'LONG_CMD_NAME' in the err_exit output.
long_cmd=$(awk -v ORS= 'BEGIN { for(i=0;i<500;i++) print "xxxxxxxxxx"; }') long_cmd=$(awk -v ORS= 'BEGIN { for(i=0;i<500;i++) print "xxxxxxxxxx"; }')
exp=127 exp=127
PATH=$PWD $SHELL -c "$long_cmd" > /dev/null 2>&1 PATH=$PWD $SHELL -c "$long_cmd" > /dev/null 2>&1

View file

@ -44,14 +44,6 @@ set abc def
if [[ $_ != def ]] if [[ $_ != def ]]
then err_exit _ variable not working then err_exit _ variable not working
fi fi
# ERRNO
#set abc def
#rm -f foobar#
#ERRNO=
#2> /dev/null < foobar#
#if (( ERRNO == 0 ))
#then err_exit ERRNO variable not working
#fi
# PWD # PWD
if [[ ! $PWD -ef . ]] if [[ ! $PWD -ef . ]]
then err_exit PWD variable failed, not equivalent to . then err_exit PWD variable failed, not equivalent to .

View file

@ -63,30 +63,30 @@ special purpose libraries such as
The The
.B libast .B libast
related header files are installed in the directories related header files are installed in the directories
.LR include/ast . .BR include/ast .
Routines that do not advertize their own headers are prototyped in Routines that do not advertize their own headers are prototyped in
.LR <ast.h> . .BR <ast.h> .
.L <ast.h> .B <ast.h>
is ANSI, K&R and C++ compatible and includes or defines the equivalent of is ANSI, K&R and C++ compatible and includes or defines the equivalent of
.LR <limits.h> , .BR <limits.h> ,
.LR <stddef.h> , .BR <stddef.h> ,
.LR <stdlib.h> , .BR <stdlib.h> ,
.LR <sys/types.h> , .BR <sys/types.h> ,
.L <string.h> .B <string.h>
and and
.LR <unistd.h> . .BR <unistd.h> .
Other libraries that depend on Other libraries that depend on
.B libast .B libast
may also have headers installed in the may also have headers installed in the
.L include/ast .B include/ast
directories. directories.
.SH FILES .SH FILES
.nf .nf
include/ast the \fBast\fP package header directory include/ast the \fBast\fP package header directory
lib/libast.a the \fBlibast\fP library lib/libast.a the \fBlibast\fP library
lib/libast-g.a the \fBlibast\fP library compiled for debugging lib/libast-g.a the \fBlibast\fP library compiled for debugging
lib/libast-pg.a the \fBlibast\fP library compiled for profiling lib/libast-pg.a the \fBlibast\fP library compiled for profiling
lib/libast.so.4.0 the \fBlibast\fP shared library lib/libast.so.4.0 the \fBlibast\fP shared library
.fi .fi
.SH "SEE ALSO" .SH "SEE ALSO"
intro(3), intro(3),

View file

@ -107,71 +107,71 @@ int asorelax(long);
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
\fIASO\fP provides functions to perform atomic scalar operations. \fIASO\fP provides functions to perform atomic scalar operations.
The functions on the type \f5uint32_t\fP will be fully described below. The functions on the type \f3uint32_t\fP will be fully described below.
Other functions work similarly on their respective types. Other functions work similarly on their respective types.
Some of the functions may be macros that call other functions. Some of the functions may be macros that call other functions.
64 bit operations are provided if the compiler supports 64 bit integers and/or pointers. 64 bit operations are provided if the compiler supports 64 bit integers and/or pointers.
.PP .PP
.Ss "TYPES" .Ss "TYPES"
.PP .PP
\f5uint8_t, uint16_t, uint32_t, uint64_t\fP \f3uint8_t, uint16_t, uint32_t, uint64_t\fP
These are \fIunsigned integer\fP types of different sizes in bits. These are \fIunsigned integer\fP types of different sizes in bits.
For example, \f5uint32_t\fP represents the type of unsigned integer with 32 bits or 4 bytes. For example, \f3uint32_t\fP represents the type of unsigned integer with 32 bits or 4 bytes.
.PP .PP
.Ss "OPERATIONS" .Ss "OPERATIONS"
.PP .PP
.Ss " uint32_t asoget32(uint32_t* from);" .Ss " uint32_t asoget32(uint32_t* from);"
This function returns the value \f5*from\fP. This function returns the value \f3*from\fP.
.PP .PP
.Ss " uint32_t asoinc32(uint32_t* dest);" .Ss " uint32_t asoinc32(uint32_t* dest);"
.Ss " uint32_t asodec32(uint32_t* dest);" .Ss " uint32_t asodec32(uint32_t* dest);"
These functions increment \f5*dest\fP by 1 and decrement \f5*dest\fP by 1 in an atomic step. These functions increment \f3*dest\fP by 1 and decrement \f3*dest\fP by 1 in an atomic step.
The return value is the old value in \f5*dest\fP. The return value is the old value in \f3*dest\fP.
Consider an example where two concurrent threads/processes call \f5asoinc32()\fP Consider an example where two concurrent threads/processes call \f3asoinc32()\fP
on the same \f5dest\fP with values, say \fIv1\fP and \fIv2\fP. on the same \f3dest\fP with values, say \fIv1\fP and \fIv2\fP.
The eventual value in \f5dest\fP The eventual value in \f3dest\fP
will be as if \f5*dest += 2\fP was performed in a single-threaded execution. will be as if \f3*dest += 2\fP was performed in a single-threaded execution.
That should be contrasted with a situation where, instead of \f5asoinc32()\fP or \f5asodec32()\fP, That should be contrasted with a situation where, instead of \f3asoinc32()\fP or \f3asodec32()\fP,
only normal increment (++) or decrement (--) were used. only normal increment (++) or decrement (--) were used.
Then, the end result could be either \f5*dest += 1\fP or \f5*dest += 2\fP, Then, the end result could be either \f3*dest += 1\fP or \f3*dest += 2\fP,
depending on states of the hardware cache and process scheduling. depending on states of the hardware cache and process scheduling.
.PP .PP
.Ss " uint32_t asocas32(uint32_t* dest, uint32_t tstval, uint32_t newval);" .Ss " uint32_t asocas32(uint32_t* dest, uint32_t tstval, uint32_t newval);"
This function provides the atomic \fIcompare-and-swap\fP operation. This function provides the atomic \fIcompare-and-swap\fP operation.
If the current content of \f5dest\fP is equal to \f5tstval\fP then it will be set to \f5newval\fP. If the current content of \f3dest\fP is equal to \f3tstval\fP then it will be set to \f3newval\fP.
If multiple threads/processes are performing the same operations only one will succeed with a If multiple threads/processes are performing the same operations only one will succeed with a
return value of \f5tstval\fP. return value of \f3tstval\fP.
The return value is the old value in \f5*dest\fP. The return value is the old value in \f3*dest\fP.
.PP .PP
.Ss " void asorelax(long nsec)" .Ss " void asorelax(long nsec)"
This function causes the calling process or thread to briefly pause This function causes the calling process or thread to briefly pause
for \f5nsec\fP nanoseconds. for \f3nsec\fP nanoseconds.
It is useful to implement tight loops that occasionally yield control. It is useful to implement tight loops that occasionally yield control.
.PP .PP
.Ss " int asolock(unsigned int* lock, unsigned int key, int type)" .Ss " int asolock(unsigned int* lock, unsigned int key, int type)"
This function uses \f5key\fP, a non-zero unsigned integer, to lock or unlock the \f5lock\fP. This function uses \f3key\fP, a non-zero unsigned integer, to lock or unlock the \f3lock\fP.
It returns \f50\fP on success and \f5-1\fP on failure. It returns \f30\fP on success and \f3-1\fP on failure.
The argument \f5type\fP can take one of the following values: The argument \f3type\fP can take one of the following values:
.Tp .Tp
\f5ASO_UNLOCK\fP: \f3ASO_UNLOCK\fP:
This unlocks the lock if it was locked with \f5key\fP. It is an error to try This unlocks the lock if it was locked with \f3key\fP. It is an error to try
unlocking a lock of a different key. unlocking a lock of a different key.
.Tp .Tp
\f5ASO_TRYLOCK\fP: \f3ASO_TRYLOCK\fP:
This makes a single attempt to use the given \f5key\fP to acquire a lock. This makes a single attempt to use the given \f3key\fP to acquire a lock.
An error will result if the lock is already locked with a different key. An error will result if the lock is already locked with a different key.
.Tp .Tp
\f5ASO_LOCK\fP: \f3ASO_LOCK\fP:
This is a regular locking call. If the lock is locked with a different key, This is a regular locking call. If the lock is locked with a different key,
this call will wait until the lock is open, then lock it with the given \f5key\fP. this call will wait until the lock is open, then lock it with the given \f3key\fP.
.Tp .Tp
\f5ASO_SPINLOCK\fP: \f3ASO_SPINLOCK\fP:
Regardless of what key is currently locking the lock, Regardless of what key is currently locking the lock,
this call will always wait until the lock is open, then lock it with the given \f5key\fP. this call will always wait until the lock is open, then lock it with the given \f3key\fP.
Note that, if the lock is already locked with \f5key\fP, this call can result Note that, if the lock is already locked with \f3key\fP, this call can result
in a deadlock unless that lock can be opened by some other mechanism, e.g., in a deadlock unless that lock can be opened by some other mechanism, e.g.,
by a different process or thread. by a different process or thread.
.PP .PP
@ -186,108 +186,108 @@ for (;;) {
/* an error occurred */; /* an error occurred */;
} }
.Ce .Ce
The value of \f5iteration\fP should be \f51\fP (\fInot\fP \f50\fP) for the first loop iteration. The value of \f3iteration\fP should be \f31\fP (\fInot\fP \f30\fP) for the first loop iteration.
\f50\fP is returned on success, \f5-1\fP on failure. \f30\fP is returned on success, \f3-1\fP on failure.
If \f5iteration mod 4\fP is \f50\fP then \f5asorelax(1)\fP is called to temporarily relinquish If \f3iteration mod 4\fP is \f30\fP then \f3asorelax(1)\fP is called to temporarily relinquish
the processor. the processor.
If \f5Asodisc_t.hung != 0\fP and \f5Asodisc_t.errorf != 0\fP and If \f3Asodisc_t.hung != 0\fP and \f3Asodisc_t.errorf != 0\fP and
\f5iteration mod (2**Asodisc_t.hung-1)\fP is \f50\fP, \f3iteration mod (2**Asodisc_t.hung-1)\fP is \f30\fP,
then \f5Asodisc_t.errorf\fP is called with type \f5ASO_HUNG\fP then \f3Asodisc_t.errorf\fP is called with type \f3ASO_HUNG\fP
and \f5-1\fP is returned. and \f3-1\fP is returned.
.PP .PP
.Ss "DISCIPLINE" .Ss "DISCIPLINE"
.PP .PP
The Asodisc_t discipline structure allows the caller to modify default behavior. The Asodisc_t discipline structure allows the caller to modify default behavior.
The \fIASO\fP discipline is global for all threads and forked children of the current process. The \fIASO\fP discipline is global for all threads and forked children of the current process.
The discipline is set and modified by the \f5asoinit()\fP function, described below. The discipline is set and modified by the \f3asoinit()\fP function, described below.
The structure members are: The structure members are:
.Tp .Tp
\f5uint32_t version;\fP \f3uint32_t version;\fP
This must be set to \f5ASO_VERSION\fP by the caller and is used by the implementation to detect This must be set to \f3ASO_VERSION\fP by the caller and is used by the implementation to detect
release differences between the caller and the implementation. release differences between the caller and the implementation.
The version is integer of the form \fIYYYYMMDD\fP where \fIYYYY\fP is the release year, \fIMM\fP The version is integer of the form \fIYYYYMMDD\fP where \fIYYYY\fP is the release year, \fIMM\fP
is the release month, and \fIDD\fP is the release day of month. is the release month, and \fIDD\fP is the release day of month.
This allows the implementation to be forwards and backwards binary compatible with all releases. This allows the implementation to be forwards and backwards binary compatible with all releases.
.Tp .Tp
\f5unsigned int hung;\fP \f3unsigned int hung;\fP
An error occurs if \f5asoloop\fP() is called \f52**Asometh_t.hung\fP times without gaining access to the loop resource. An error occurs if \f3asoloop\fP() is called \f32**Asometh_t.hung\fP times without gaining access to the loop resource.
The default value \f50\fP disables the test. The default value \f30\fP disables the test.
.Tp .Tp
\f5Asoerror_f errorf;\fP \f3Asoerror_f errorf;\fP
\f5int (*errorf)(int type, const char* mesg);\fP \f3int (*errorf)(int type, const char* mesg);\fP
If \f5errorf\fP != \f50\fP then it is called for each \fIASO\fP fatal library condition. If \f3errorf\fP != \f30\fP then it is called for each \fIASO\fP fatal library condition.
\f5type\fP may be one of: \f5ASO_METHOD\fP - a method error; \f5ASO_HUNG\fP - \f5asoloop\fP() was called \f3type\fP may be one of: \f3ASO_METHOD\fP - a method error; \f3ASO_HUNG\fP - \f3asoloop\fP() was called
\f52**Asometh_t.hung\fP times with no access to the loop resource. \f32**Asometh_t.hung\fP times with no access to the loop resource.
\f5mesg\fP is a 0-terminated message description. \f3mesg\fP is a 0-terminated message description.
.Ss " void ASODISC(Asodisc_t* disc, Asoerror_f errorf);" .Ss " void ASODISC(Asodisc_t* disc, Asoerror_f errorf);"
.PP .PP
This function-like-macro initializes \f5disc->version = ASO_VERSION\fP, \f5disc->errorf = errorf\fP, This function-like-macro initializes \f3disc->version = ASO_VERSION\fP, \f3disc->errorf = errorf\fP,
and the remaining \f5disc\fP members to \f50\fP. and the remaining \f3disc\fP members to \f30\fP.
.PP .PP
.Ss "METHODS" .Ss "METHODS"
.PP .PP
Several atomic locking methods are implemented for atomic operations Several atomic locking methods are implemented for atomic operations
not supported by \fIintrinsic\fP functions or assembly instructions. not supported by \fIintrinsic\fP functions or assembly instructions.
Methods are controlled by the \f5asometh()\fP and \f5asoinit()\fP Methods are controlled by the \f3asometh()\fP and \f3asoinit()\fP
functions, described below. functions, described below.
The \fIASO\fP method is global for all threads and forked children of the current process. The \fIASO\fP method is global for all threads and forked children of the current process.
A given method may have multiple types. A given method may have multiple types.
The methods types are: The methods types are:
.Tp .Tp
\f5ASO_INTRINSIC\fP: \f3ASO_INTRINSIC\fP:
Some hardware platforms provide machine instructions to implement these operations directly. Some hardware platforms provide machine instructions to implement these operations directly.
In that case, if a local compiler permits, calls to these \fIintrinsic\fP functions In that case, if a local compiler permits, calls to these \fIintrinsic\fP functions
may be translated directly into their corresponding machine instructions. may be translated directly into their corresponding machine instructions.
When necessary the implementation can use only the intrinsic \fIcompare-and-swap\fP When necessary the implementation can use only the intrinsic \fIcompare-and-swap\fP
function on the largest integer type to emulate all other \fIASO\fP operations. function on the largest integer type to emulate all other \fIASO\fP operations.
The \f5ASO_INTRINSIC\fP method type is the default when supported by the compiler. The \f3ASO_INTRINSIC\fP method type is the default when supported by the compiler.
It may be used for single-process single-thread, multi-thread, and It may be used for single-process single-thread, multi-thread, and
multi-process applications. multi-process applications.
When supported by the hardware / compiler, the library provides the "\fBintrinsic\fP" method with type When supported by the hardware / compiler, the library provides the "\fBintrinsic\fP" method with type
\f5ASO_INTRINSIC|ASO_PROCESS|ASO_THREAD|ASO_SIGNAL\fP. \f3ASO_INTRINSIC|ASO_PROCESS|ASO_THREAD|ASO_SIGNAL\fP.
.Tp .Tp
\f5ASO_SIGNAL\fP: \f3ASO_SIGNAL\fP:
This method type is suitable only for single-process single-thread applications. This method type is suitable only for single-process single-thread applications.
It can be used to provide locking between asynchronous \fBsignal\fP(2) handlers It can be used to provide locking between asynchronous \fBsignal\fP(2) handlers
and the main program. and the main program.
The library provides the "\fBsignal\fP" method with type \f5ASO_SIGNAL\fP. The library provides the "\fBsignal\fP" method with type \f3ASO_SIGNAL\fP.
This is the default method type when \f5ASO_INTRINSIC\fP is not supported. This is the default method type when \f3ASO_INTRINSIC\fP is not supported.
.Tp .Tp
\f5ASO_THREAD\fP: \f3ASO_THREAD\fP:
This method type is suitable for single-process single-thread, and multi-thread applications. This method type is suitable for single-process single-thread, and multi-thread applications.
It typically requires thread library support, and since the default \f5aso\fP library It typically requires thread library support, and since the default \f3aso\fP library
is not linked with a thread library, no \f5ASO_THREAD\fP method is provided by default. is not linked with a thread library, no \f3ASO_THREAD\fP method is provided by default.
Threaded applications must link with \fB-ltaso\fP (before \fB-laso\fP or \fB-last\fP) Threaded applications must link with \fB-ltaso\fP (before \fB-laso\fP or \fB-last\fP)
in order to access \f5ASO_THREAD\fP methods. in order to access \f3ASO_THREAD\fP methods.
The \fB-ltaso\fP library provides the "\fBspin\fP" (using \fBpthread_spin_lock\fP(3)) and The \fB-ltaso\fP library provides the "\fBspin\fP" (using \fBpthread_spin_lock\fP(3)) and
"\fBmutex"\fP (using \fBpthread_mutex_lock\fP(3)) methods with type \f5ASO_THREAD|ASO_SIGNAL\fP. "\fBmutex"\fP (using \fBpthread_mutex_lock\fP(3)) methods with type \f3ASO_THREAD|ASO_SIGNAL\fP.
.Tp .Tp
\f5ASO_PROCESS\fP: \f3ASO_PROCESS\fP:
This method type is suitable for single-process single-thread, and multi-process applications. This method type is suitable for single-process single-thread, and multi-process applications.
Some \f5ASO_PROCESS\fP methods may also be suitable for multi-thread applications (if they have the \f5ASO_THREAD\fP type.) Some \f3ASO_PROCESS\fP methods may also be suitable for multi-thread applications (if they have the \f3ASO_THREAD\fP type).
These methods are typically and noticeably \fIslow\fP, up to 2 orders of magnitude slower than These methods are typically and noticeably \fIslow\fP, up to 2 orders of magnitude slower than
\f5ASO_INTRINSIC\fP for some applications. \f3ASO_INTRINSIC\fP for some applications.
They are provided as a last resort when other methods are not available. They are provided as a last resort when other methods are not available.
The library provides the "\fBsemaphore\fP" method with type \f5ASO_PROCESS|ASO_THREAD|ASO_SIGNAL\fP The library provides the "\fBsemaphore\fP" method with type \f3ASO_PROCESS|ASO_THREAD|ASO_SIGNAL\fP
and the "\fBfcntl\fP" method with type \f5ASO_PROCESS|ASO_SIGNAL\fP. and the "\fBfcntl\fP" method with type \f3ASO_PROCESS|ASO_SIGNAL\fP.
.Ss " Asometh_t* asometh(int type, void* data);" .Ss " Asometh_t* asometh(int type, void* data);"
This function looks up methods by type or name. This function looks up methods by type or name.
If type is \f50\fP and \f5data\fP is \f50\fP then the current method is returned; a valid method If type is \f30\fP and \f3data\fP is \f30\fP then the current method is returned; a valid method
will always be returned for this call. will always be returned for this call.
If type is \f50\fP then \f5data\fP is treated as a \f50\fP-terminated string method name; If type is \f30\fP then \f3data\fP is treated as a \f30\fP-terminated string method name;
\f50\fP is returned if no matching method is found. \f30\fP is returned if no matching method is found.
The pseudo-type \f5ASO_NEXT\fP generates the list of all methods in successive calls: The pseudo-type \f3ASO_NEXT\fP generates the list of all methods in successive calls:
.Cs .Cs
Asometh_t* meth; Asometh_t* meth;
meth = 0; meth = 0;
while (meth = asometh(ASO_NEXT, meth)) while (meth = asometh(ASO_NEXT, meth))
/* examine meth->... */ /* examine meth->... */
.Ce .Ce
Otherwise if \f5type\fP is not \f50\fP and not \f5ASO_NEXT\fP it is treated as a combination of the ordered types Otherwise if \f3type\fP is not \f30\fP and not \f3ASO_NEXT\fP it is treated as a combination of the ordered types
\f5ASO_THREAD\fP, \f5ASO_SIGNAL\fP, \f5ASO_INTRINSIC\fP, \f5ASO_PROCESS\fP: \f3ASO_THREAD\fP, \f3ASO_SIGNAL\fP, \f3ASO_INTRINSIC\fP, \f3ASO_PROCESS\fP:
the first method with \f5(meth->type & type) != 0\fP is returned; the first method with \f3(meth->type & type) != 0\fP is returned;
\f50\fP is returned if no matching method is found. \f30\fP is returned if no matching method is found.
Method names are treated as a name, optionally followed by a list of Method names are treated as a name, optionally followed by a list of
\fB,\fP\fIname\fP=\fIvalue\fP details, and optionally ending with \fB,\fP\fIpathname\fP. \fB,\fP\fIname\fP=\fIvalue\fP details, and optionally ending with \fB,\fP\fIpathname\fP.
@ -295,25 +295,25 @@ The \fBsemaphore\fP method uses \fBsize\fP=\fInumber\fP to specify
the number of semaphores and hashes \fIpathname\fP to determine the semaphore IPC key. the number of semaphores and hashes \fIpathname\fP to determine the semaphore IPC key.
The \fBfcntl\fP method uses \fBsize\fP=\fInumber\fP to specify The \fBfcntl\fP method uses \fBsize\fP=\fInumber\fP to specify
the number of 1 byte file locks and uses \fIpathname\fP as the the number of 1 byte file locks and uses \fIpathname\fP as the
file to lock using \f5fcntl(F_SETLCK[W])\fP. file to lock using \f3fcntl(F_SETLCK[W])\fP.
.Ss " int asoinit(const char* details, Asometh_t* meth, Asodisc_t* disc);" .Ss " int asoinit(const char* details, Asometh_t* meth, Asodisc_t* disc);"
This function sets the global discipline to \f5disc\fP, This function sets the global discipline to \f3disc\fP,
closes the current method (releasing its resources), closes the current method (releasing its resources),
temporarily instantiates the default method temporarily instantiates the default method
(either \f5ASO_INTRINSIC\fP if available or \f5AS_SIGNAL\fP otherwise), (either \f3ASO_INTRINSIC\fP if available or \f3AS_SIGNAL\fP otherwise),
and initializes \f5meth\fP and instantiates it as the new method. and initializes \f3meth\fP and instantiates it as the new method.
If \f5disc\fP is \f50\fP then the global discipline is not modified. If \f3disc\fP is \f30\fP then the global discipline is not modified.
If \f5meth\fP is \f50\fP then \f51\fP is returned if \f5asoinit()\fP has If \f3meth\fP is \f30\fP then \f31\fP is returned if \f3asoinit()\fP has
already been called to initialize a method, otherwise \f50\fP is returned. already been called to initialize a method, otherwise \f30\fP is returned.
If \f5meth->lockf\fP is \f50\fP and \f5(meth->type & ASO_INTRINSIC) != 0\fP If \f3meth->lockf\fP is \f30\fP and \f3(meth->type & ASO_INTRINSIC) != 0\fP
then \f5-1\fP is returned and the current method is not changed. then \f3-1\fP is returned and the current method is not changed.
If an error occurs instantiating \f5meth\fP then the current method is If an error occurs instantiating \f3meth\fP then the current method is
set to the default and \f5-1\fP is returned. set to the default and \f3-1\fP is returned.
Otherwise \f50\fP is returned on success. Otherwise \f30\fP is returned on success.
Method resources are released by the next \f5asometh()\fP call, Method resources are released by the next \f3asometh()\fP call,
or by an \fIASO\fP cleanup function called via \f5atexit\fP(2). or by an \fIASO\fP cleanup function called via \f3atexit\fP(2).
System global method resources are released on last use; System global method resources are released on last use;
this includes removing semaphore keys or this includes removing semaphore keys or
physical files that may be used by some methods. physical files that may be used by some methods.
@ -334,8 +334,8 @@ if (data || !(asometh(0, 0)->type & (ASO_INTRINSIC|ASO_THREAD))) {
} }
/* ready for \fIASO\fP operations */ /* ready for \fIASO\fP operations */
.Ce .Ce
A multi-process application would check for \f5(ASO_INTRINSIC|ASO_PROCESS)\fP A multi-process application would check for \f3(ASO_INTRINSIC|ASO_PROCESS)\fP
instead of \f5(ASO_INTRINSIC|ASO_THREAD)\fP. instead of \f3(ASO_INTRINSIC|ASO_THREAD)\fP.
.PP .PP
.SH IMPLEMENTATION NOTES .SH IMPLEMENTATION NOTES
@ -344,13 +344,13 @@ multiple discipline/method handles within a single process, the \fIASO\fP
library allows only one discipline and method to be set at a time, with the additional library allows only one discipline and method to be set at a time, with the additional
restriction that it may only be set by the main and only thread of the calling process. restriction that it may only be set by the main and only thread of the calling process.
For this reason there is no open/close interface with an instantiation handle; For this reason there is no open/close interface with an instantiation handle;
instead the global discipline/method is simply initialized by \f5asoinit()\fP. instead the global discipline/method is simply initialized by \f3asoinit()\fP.
\f5ASO_THREAD\fP and \f5ASO_PROCESS\fP methods rely on the \f5Asometh_t.lockf()\fP \f3ASO_THREAD\fP and \f3ASO_PROCESS\fP methods rely on the \f3Asometh_t.lockf()\fP
being sufficiently "heavy" to flush the calling thread/process memory cache being sufficiently "heavy" to flush the calling thread/process memory cache
so the subsequent \fIASO\fP operation operates on the physical memory location so the subsequent \fIASO\fP operation operates on the physical memory location
instead of the cached location. There is currently no other portable mechanism instead of the cached location. There is currently no other portable mechanism
that guarantees this other than the \f5ASO_INTRINSIC\fP method. that guarantees this other than the \f3ASO_INTRINSIC\fP method.
.PP .PP
.SH AUTHOR .SH AUTHOR

View file

@ -74,7 +74,7 @@ In this case if
is is
.L 0 .L 0
then then
\f5"/"\fP \f3"/"\fP
is used. is used.
Otherwise if Otherwise if
.I path .I path
@ -92,7 +92,7 @@ If
is is
.L 0 .L 0
then a valid string is always returned; then a valid string is always returned;
\f5""\fP \f3""\fP
is returned if is returned if
.I name .I name
has no configuration value. has no configuration value.
@ -179,7 +179,7 @@ If
.I path .I path
is is
.L 0 .L 0
then \f5"/"\fP is used where appropriate. then \f3"/"\fP is used where appropriate.
If If
.I flags .I flags
is is

View file

@ -133,20 +133,20 @@ to the end offset of the \fIi\fP-th parenthesized subexpression.
\fInsub\fP is 1/2 the number of elements in \fIsub\fP. \fInsub\fP is 1/2 the number of elements in \fIsub\fP.
\fIflags\fP controls the matching: \fIflags\fP controls the matching:
.Tp .Tp
\f5STR_MAXIMAL\fP: \f3STR_MAXIMAL\fP:
Maximal match. Maximal match.
The default is minimal (first) match. The default is minimal (first) match.
.Tp .Tp
\f5STR_LEFT\fP: \f3STR_LEFT\fP:
Implicit left anchor. Implicit left anchor.
.Tp .Tp
\f5STR_RIGHT\fP: \f3STR_RIGHT\fP:
Implicit right anchor. Implicit right anchor.
.Tp .Tp
\f5STR_ICASE\fP: \f3STR_ICASE\fP:
Ignore case. Ignore case.
.Tp .Tp
\f5STR_GROUP\fP: \f3STR_GROUP\fP:
(|&) inside [@|*|+{n,m}](...) only. (|&) inside [@|*|+{n,m}](...) only.
.Ss "int strmatch(const char* \fIstring\fP, const char* \fIpattern\fP, int* \fIsub\fP, int \fInsub\fP, int \fIflags\fP)" .Ss "int strmatch(const char* \fIstring\fP, const char* \fIpattern\fP, int* \fIsub\fP, int \fInsub\fP, int \fIflags\fP)"
Equivalent to strgrpmatch(\fIstring\fP,\fIpattern\fP,0,0,STR_MAXIMAL|STR_LEFT|STR_RIGHT). Equivalent to strgrpmatch(\fIstring\fP,\fIpattern\fP,0,0,STR_MAXIMAL|STR_LEFT|STR_RIGHT).

File diff suppressed because it is too large Load diff

View file

@ -53,7 +53,7 @@ void liberror(const char* \fIlibrary\fP, int \fIlevel\fP, ...);
debug(\fIstatement\fP) debug(\fIstatement\fP)
message((int \fIlevel\fP, ...)) message((int \fIlevel\fP, ...))
libmessage((const char* \fIlibrary\fI, int \fIlevel\fP, ...)) libmessage((const char* \fIlibrary\fP, int \fIlevel\fP, ...))
.EE .EE
.SH DESCRIPTION .SH DESCRIPTION
.L error .L error

View file

@ -6,7 +6,7 @@
.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
.PP .PP
.nf .nf
\f5 \f3
#include <ftwalk.h> #include <ftwalk.h>
int ftwalk(char* path, int (*userf)(struct FTW* ftw), int options, int ftwalk(char* path, int (*userf)(struct FTW* ftw), int options,
@ -226,7 +226,7 @@ preferences specified by
the routine \fIftw\fR provided in System V. the routine \fIftw\fR provided in System V.
However, it is more general than \fIftw\fR However, it is more general than \fIftw\fR
and suitable for use as a base in implementing and suitable for use as a base in implementing
popular tools such as \fIls, find, tar, du,\fR and \fIrm\fR. popular tools such as \fIls\fR, \fIfind\fR, \fItar\fR, \fIdu\fR, and \fIrm\fR.
\fIFtwalk\fR also handles symbolic links and hard links gracefully. \fIFtwalk\fR also handles symbolic links and hard links gracefully.
.SH AUTHORS .SH AUTHORS
Phong Vo, Glenn Fowler, Dave Korn Phong Vo, Glenn Fowler, Dave Korn

View file

@ -360,7 +360,7 @@ The basic operations may be qualified by the following
the parenthesized list): the parenthesized list):
.RS .RS
.TP .TP
.L "HASH_BUCKET (HASH_CREATE,HASH_DELETE,HASH_LOOKUP)" .L "HASH_BUCKET (HASH_CREATE, HASH_DELETE, HASH_LOOKUP)"
.L name .L name
is a pointer to a bucket that has already been entered into the table. is a pointer to a bucket that has already been entered into the table.
.TP .TP
@ -379,7 +379,7 @@ is a pointer to a bucket that has not been entered into the table.
.L "HASH_NOSCOPE (HASH_LOOKUP)" .L "HASH_NOSCOPE (HASH_LOOKUP)"
The lookup is restricted to the top level scope. The lookup is restricted to the top level scope.
.TP .TP
.L "HASH_OPAQUE (HASH_CREATE,HASH_DELETE)" .L "HASH_OPAQUE (HASH_CREATE, HASH_DELETE)"
Sets Sets
.L (HASH_CREATE) .L (HASH_CREATE)
or clears or clears
@ -389,13 +389,13 @@ the
property for the bucket. property for the bucket.
An opaque bucket is not visible in lower scopes. An opaque bucket is not visible in lower scopes.
.TP .TP
.L "HASH_SCOPE (HASH_CREATE,HASH_DELETE)" .L "HASH_SCOPE (HASH_CREATE, HASH_DELETE)"
All scopes are searched for the bucket. All scopes are searched for the bucket.
If the bucket is not found for If the bucket is not found for
.L HASH_CREATE .L HASH_CREATE
then a new bucket is created in the lowest scope. then a new bucket is created in the lowest scope.
.TP .TP
.L "HASH_VALUE (HASH_CREATE,HASH_LOOKUP)" .L "HASH_VALUE (HASH_CREATE, HASH_LOOKUP)"
For For
.L HASH_CREATE .L HASH_CREATE
the bucket the bucket

View file

@ -38,7 +38,7 @@
.. ..
.TH IP6 3 .TH IP6 3
.SH NAME .SH NAME
ip6 \- IP V6 address support ip6 \- IPv6 address support
.SH SYNOPSIS .SH SYNOPSIS
.EX .EX
#include <ip6.h> #include <ip6.h>
@ -49,7 +49,7 @@ int strtoip6(const char* str, char** end, unsigned char* addr, unsigned c
.SH DESCRIPTION .SH DESCRIPTION
.L fmtip6() .L fmtip6()
formats the IPV6 address formats the IPv6 address
.L addr .L addr
with optional prefix bits with optional prefix bits
.L bits .L bits
@ -58,9 +58,9 @@ to the formatted value.
.PP .PP
.L strtoip6() .L strtoip6()
converts a formatted IPV6 address from the 0-terminated string converts a formatted IPv6 address from the 0-terminated string
.L str .L str
into a host order IPV6 address in into a host order IPv6 address in
.L addr .L addr
which must be a buffer of at least which must be a buffer of at least
.L IP6ADDR .L IP6ADDR

View file

@ -63,7 +63,7 @@ command magic file.
.L magicopen .L magicopen
returns a magic session handle that is passed to all of the other routines. returns a magic session handle that is passed to all of the other routines.
.I flags .I flags
may be may be:
.TP .TP
.L MAGIC_MIME .L MAGIC_MIME
Return the MIME type string rather than the magic file description. Return the MIME type string rather than the magic file description.
@ -209,7 +209,7 @@ and
.L } .L }
records have no other fields. records have no other fields.
.TP .TP
\fIid\f5{\fR \fIid\f3{\fR
A function declaration and call for the single character identifier A function declaration and call for the single character identifier
.IR id . .IR id .
The function return is a nesting block end record The function return is a nesting block end record
@ -217,7 +217,7 @@ The function return is a nesting block end record
Function may be redefined. Function may be redefined.
Functions have no arguments or return value. Functions have no arguments or return value.
.TP .TP
\fIid\f5()\fR \fIid\f3()\fR
A call to the function A call to the function
.IR id . .IR id .
.PP .PP
@ -414,7 +414,7 @@ may be an integral constant or one of the following builtin function calls:
A recursive call to the magic algorithm starting with the data at A recursive call to the magic algorithm starting with the data at
.LR offset . .LR offset .
.TP .TP
\f5loop(\fIfunction\fP,\fIoffset\fP,\fIincrement\fP)\fR \f3loop(\fIfunction\fP, \fIoffset\fP, \fIincrement\fP)\fR
Call Call
.I function .I function
starting at starting at
@ -446,7 +446,7 @@ then a
.I space .I space
is placed between the descriptions is placed between the descriptions
(most optional descriptions start with (most optional descriptions start with
.IR comma .) .IR comma ).
The data value at The data value at
.L offset .L offset
can be referenced in the description using can be referenced in the description using

View file

@ -40,6 +40,7 @@
.SH NAME .SH NAME
modecanon \- canonical file mode representation modecanon \- canonical file mode representation
.SH SYNOPSIS .SH SYNOPSIS
.EX
#include <modex.h> #include <modex.h>
int modei(int \fIexternal\fP); int modei(int \fIexternal\fP);
@ -70,7 +71,7 @@ takes an internal mode representation
.I internal .I internal
and returns the equivalent external representation. and returns the equivalent external representation.
.PP .PP
The traditional bit access macro (\f5S_\fP prefix changes to \f5X_\fP) are: The traditional bit access macro (\f3S_\fP prefix changes to \f3X_\fP) are:
.L X_IFMT , .L X_IFMT ,
.L X_IFSOCK , .L X_IFSOCK ,
.L X_IFLNK , .L X_IFLNK ,

View file

@ -117,7 +117,7 @@ is equivalent to
calls calls
.IR execvp (3) .IR execvp (3)
as as
.L "execvp(a\fIrgv\fP[0],\fIargv\fP)" .L "execvp(a\fIrgv\fP[0], \fIargv\fP)"
with the process preroot set to with the process preroot set to
.IR dir . .IR dir .
.I argv .I argv

View file

@ -122,13 +122,13 @@ and
for the child and parent process context respectively. for the child and parent process context respectively.
Valid operations are: Valid operations are:
.TP .TP
\f5PROC_FD_CLOSE(\fIfd\fP,\fIcontext\fP)\fR \f3PROC_FD_CLOSE(\fIfd\fP, \fIcontext\fP)\fR
The file descriptor The file descriptor
.I fd .I fd
is closed in is closed in
.IR context . .IR context .
.TP .TP
\f5PROC_FD_DUP(\fIfrom\fP,\fIto\fP,\fIcontext\fP)\fR \f3PROC_FD_DUP(\fIfrom\fP, \fIto\fP, \fIcontext\fP)\fR
The file descriptor The file descriptor
.I from .I from
is is
@ -138,21 +138,21 @@ into the file descriptor
in in
.IR context . .IR context .
.TP .TP
\f5PROC_SIG_DFL(\fIsig\fP)\fR \f3PROC_SIG_DFL(\fIsig\fP)\fR
The signal handler for The signal handler for
.I sig .I sig
is set to is set to
.L SIG_DFL .L SIG_DFL
in the child context. in the child context.
.TP .TP
\f5PROC_SIG_IGN(\fIsig\fP)\fR \f3PROC_SIG_IGN(\fIsig\fP)\fR
The signal handler for The signal handler for
.I sig .I sig
is set to is set to
.L SIG_IGN .L SIG_IGN
in the child context. in the child context.
.TP .TP
\f5PROC_SYS_PGRP(\fIpgid\fP)\fR \f3PROC_SYS_PGRP(\fIpgid\fP)\fR
The child process group is set to The child process group is set to
.IR pgid . .IR pgid .
.I pgid .I pgid
@ -171,7 +171,7 @@ The child process becomes a process group leader.
The child process joins the process group The child process joins the process group
.IR pgid . .IR pgid .
.TP .TP
\f5PROC_SYS_UMASK(\fImask\fP)\fR \f3PROC_SYS_UMASK(\fImask\fP)\fR
The child process group file creation mask is set to The child process group file creation mask is set to
.IR mask . .IR mask .
.PP .PP

View file

@ -41,69 +41,69 @@ extern int dcdelunion(Sfdisc_t* disc);
.PP .PP
I/O disciplines are used to extend the data processing power of I/O disciplines are used to extend the data processing power of
\fIsfio\fP streams. The convention for using the disciplines \fIsfio\fP streams. The convention for using the disciplines
in this package is to use the call \f5dcnewXXX()\fP to create in this package is to use the call \f3dcnewXXX()\fP to create
a discipline of the type \f5XXX\fP and to use \f5dcdelXXX()\fP a discipline of the type \f3XXX\fP and to use \f3dcdelXXX()\fP
to destroy it. to destroy it.
A discipline is enable by inserting it into the desired A discipline is enable by inserting it into the desired
stream using the \f5sfdisc()\fP call. A discipline can be used on only stream using the \f3sfdisc()\fP call. A discipline can be used on only
one stream. It is unsafe to share a discipline on two or more streams one stream. It is unsafe to share a discipline on two or more streams
since the discipline may maintain states between successive IO calls. since the discipline may maintain states between successive IO calls.
For multiple uses, \f5dcnewXXX()\fP should be used For multiple uses, \f3dcnewXXX()\fP should be used
to create a distinct discipline for each stream. to create a distinct discipline for each stream.
Each discipline structure is equipped with an exception handler Each discipline structure is equipped with an exception handler
that causes self-destruction when the associated stream is closed. that causes self-destruction when the associated stream is closed.
.PP .PP
.Ss " Sfdisc_t* dcnewskable(Sfio_t* f);" .Ss " Sfdisc_t* dcnewskable(Sfio_t* f);"
.Ss " int dcdelskable(Sfdisc_t* disc);" .Ss " int dcdelskable(Sfdisc_t* disc);"
\f5dcnewskable()\fP creates a discipline that when inserted \f3dcnewskable()\fP creates a discipline that when inserted
on the stream \f5f\fP will ensure that \f5f\fP is seekable. on the stream \f3f\fP will ensure that \f3f\fP is seekable.
If \f5f\fP is originally unseekable, data will be shadowed If \f3f\fP is originally unseekable, data will be shadowed
in a temporary file stream to allow seekability. in a temporary file stream to allow seekability.
\f5dcnewskable()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewskable()\fP returns the discipline on success and \f3NULL\fP on failure.
.Ss " Sfdisc_t* dcnewtee(Sfio_t* tee);" .Ss " Sfdisc_t* dcnewtee(Sfio_t* tee);"
.Ss " int dcdeltee(Sfdisc_t* disc);" .Ss " int dcdeltee(Sfdisc_t* disc);"
\f5dcnewtee()\fP creates a discipline that \f3dcnewtee()\fP creates a discipline that
when inserted into a stream \f5f\fP will duplicate to the stream \f5tee\fP when inserted into a stream \f3f\fP will duplicate to the stream \f3tee\fP
any data written to \f5f\fP. any data written to \f3f\fP.
\f5dcnewtee()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewtee()\fP returns the discipline on success and \f3NULL\fP on failure.
.Ss " Sfdisc_t* dcnewfilter(char* cmd);" .Ss " Sfdisc_t* dcnewfilter(char* cmd);"
.Ss " int dcdelfilter(Sfdisc_t* disc);" .Ss " int dcdelfilter(Sfdisc_t* disc);"
\f5dcnewfilter()\fP creates a discipline that \f3dcnewfilter()\fP creates a discipline that
when inserted into a stream \f5f\fP will run the command \f5cmd\fP when inserted into a stream \f3f\fP will run the command \f3cmd\fP
to process any input data before making it available to the application. to process any input data before making it available to the application.
For example, \f5dcnewfilter("uncompress")\fP is an equivalent but slower For example, \f3dcnewfilter("uncompress")\fP is an equivalent but slower
alternative to the lzw discipline below. alternative to the lzw discipline below.
\f5dcnewfilter()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewfilter()\fP returns the discipline on success and \f3NULL\fP on failure.
.Ss " Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);" .Ss " Sfdisc_t* dcnewsubstream(Sfio_t* base, long offset, long extent);"
.Ss " int dcdelsubstream(Sfdisc_t* disc);" .Ss " int dcdelsubstream(Sfdisc_t* disc);"
\f5dcnewsubstream()\fP creates a discipline that \f3dcnewsubstream()\fP creates a discipline that
reserves a portion of the stream \f5base\fP starting at \f5offset\fP reserves a portion of the stream \f3base\fP starting at \f3offset\fP
with length \f5extent\fP and makes this portion appear as if it is with length \f3extent\fP and makes this portion appear as if it is
a stream. When this discipline is inserted into a stream, it will make a stream. When this discipline is inserted into a stream, it will make
cause all IO operations on this stream to take place in the reserved cause all IO operations on this stream to take place in the reserved
portion of the \f5base\fP stream. portion of the \f3base\fP stream.
\f5dcnewsubstream()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewsubstream()\fP returns the discipline on success and \f3NULL\fP on failure.
.Ss " Sfdisc_t* dcnewlzw(void); .Ss " Sfdisc_t* dcnewlzw(void);
.Ss " int dcdellzw(Sfdisc_t* disc);" .Ss " int dcdellzw(Sfdisc_t* disc);"
\f5dcnewlzw()\fP creates a discipline that when inserted into \f3dcnewlzw()\fP creates a discipline that when inserted into
a stream \f5f\fP will run the \fBuncompress\fP algorithm a stream \f3f\fP will run the \fBuncompress\fP algorithm
on input data from \f5f\fP before making it available to the on input data from \f3f\fP before making it available to the
application. This is useful to allow applications to process application. This is useful to allow applications to process
data from a file packed with the UNIX \fBcompress\fP utility data from a file packed with the UNIX \fBcompress\fP utility
as if the data is in plain text. as if the data is in plain text.
\f5dcnewlzw()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewlzw()\fP returns the discipline on success and \f3NULL\fP on failure.
.Ss " Sfdisc_t* dcnewunion(Sfio_t** list, int n); .Ss " Sfdisc_t* dcnewunion(Sfio_t** list, int n);
.Ss " int dcdelunion(Sfdisc_t* disc);" .Ss " int dcdelunion(Sfdisc_t* disc);"
\f5dcnewunion()\fP creates a discipline that concatenates \f3dcnewunion()\fP creates a discipline that concatenates
input data from all \f5n\fP streams in \f5list\fP. input data from all \f3n\fP streams in \f3list\fP.
When inserted into a stream \f5f\fP, this discipline will cause When inserted into a stream \f3f\fP, this discipline will cause
all input operations on \f5f\fP to come from the merged data stream. all input operations on \f3f\fP to come from the merged data stream.
\f5dcnewunion()\fP returns the discipline on success and \f5NULL\fP on failure. \f3dcnewunion()\fP returns the discipline on success and \f3NULL\fP on failure.
.SH ACKNOWLEDGMENTS .SH ACKNOWLEDGMENTS
Dave Korn contributed the substream discipline. Dave Korn contributed the substream discipline.

File diff suppressed because it is too large Load diff

View file

@ -40,36 +40,37 @@
.SH NAME .SH NAME
sig \- signal interface routines sig \- signal interface routines
.SH SYNOPSIS .SH SYNOPSIS
.EX
.L "#include <ast.h>" .L "#include <ast.h>"
.L "#include <sig.h>" .L "#include <sig.h>"
.sp .sp
.L "int sigunblock(int sig);" .L "int sigunblock(int sig);"
.L "int sigcritical(int op);" .L "int sigcritical(int op);"
.SH DESCRIPTION .SH DESCRIPTION
.L sigunblock .B sigunblock
is called to is called to
unblocks the signal unblocks the signal
.L sig .B sig
from within a handler currently servicing from within a handler currently servicing
.LR sig . .BR sig .
.PP .PP
.L sigcritical .B sigcritical
controls a critical region for the controls a critical region for the
.LR SIGINT , .BR SIGINT ,
.L SIGQUIT .B SIGQUIT
and and
.L SIGHUP .B SIGHUP
signals. signals.
.L "op > 0" .B "op > 0"
pushes the region, pushes the region,
.L "op == 0" .B "op == 0"
pops the region, and pops the region, and
.L "op < 0" .B "op < 0"
returns non-zero if any signals are being held in the current returns non-zero if any signals are being held in the current
critical region. critical region.
Signal critical regions may be nested. Signal critical regions may be nested.
The current critical region level is returned, The current critical region level is returned,
.L \-1 .B \-1
on error. on error.
.SH "SEE ALSO" .SH "SEE ALSO"
signal(2) signal(2)

View file

@ -44,7 +44,7 @@ spawnveg \- process spawn with process group and session control
.sp .sp
.L "int spawnveg(const char* command, char** argv, char** envv, pid_t pgid);" .L "int spawnveg(const char* command, char** argv, char** envv, pid_t pgid);"
.SH DESCRIPTION .SH DESCRIPTION
.L spwanveg .L spawnveg
combines combines
.IR fork (2), .IR fork (2),
.IR exec (2), .IR exec (2),
@ -52,6 +52,12 @@ combines
and and
.IR setsid (2) .IR setsid (2)
into a single call. into a single call.
If one of either
.IR posix_spawn (3)
or
.IR vfork (2)
is available, those functions are preferred over
.IR fork .
.PP .PP
.LR command , .LR command ,
.L argv .L argv
@ -75,5 +81,10 @@ The new process becomes a process group leader.
.L >1 .L >1
The new process joins the process group The new process joins the process group
.IR pgid . .IR pgid .
.SH CAVEATS
The
.L spawnveg
function cannot set the terminal process group.
As a result, it is incompatible with job control when used with terminals.
.SH "SEE ALSO" .SH "SEE ALSO"
fork(2), exec(2), setpgid(2), setsid(2), spawnve(2) fork(2), exec(2), setpgid(2), setsid(2), spawnve(2)

View file

@ -6,7 +6,7 @@
.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
.PP .PP
.nf .nf
\f5 \f3
#include <stak.h> #include <stak.h>
Stak_t *stakcreate(int \fIflags\fP); Stak_t *stakcreate(int \fIflags\fP);
@ -29,13 +29,13 @@ char *stakfreeze(unsigned \fIextra\fP);
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
\f5stak\fP is a package of routines designed to provide efficient \f3stak\fP is a package of routines designed to provide efficient
stack oriented dynamic storage. stack oriented dynamic storage.
A stack abstraction consists of an ordered list of contiguous A stack abstraction consists of an ordered list of contiguous
memory regions, called stack frames, that can hold objects of memory regions, called stack frames, that can hold objects of
arbitrary size. arbitrary size.
A stack is represented by the type \f5Stak_t\fP A stack is represented by the type \f3Stak_t\fP
defined in header \f5<stak.h>\fP. defined in header \f3<stak.h>\fP.
At any instant there is one active stack. At any instant there is one active stack.
Variable size objects can be Variable size objects can be
added to the active stack added to the active stack
@ -53,36 +53,36 @@ relative offsets ranging from zero to the current offset of the object.
There is a preset initial active stack. There is a preset initial active stack.
To use an additional stack, it is necessary to create it and to To use an additional stack, it is necessary to create it and to
install it as the active stack. install it as the active stack.
A stack is created with the \f5stakcreate\fP() function. A stack is created with the \f3stakcreate\fP() function.
A \fIflags\fP argument of \f5STAK_SMALL\fP indicates that unused A \fIflags\fP argument of \f3STAK_SMALL\fP indicates that unused
space on the stack should be freed whenever this stack ceases space on the stack should be freed whenever this stack ceases
to be the active stack. to be the active stack.
If successful, If successful,
\f5stakcreate\fP() returns a pointer to a stack whose reference \f3stakcreate\fP() returns a pointer to a stack whose reference
count is 1. count is 1.
Otherwise, \f5stakcreate\fP() returns a null pointer. Otherwise, \f3stakcreate\fP() returns a null pointer.
The \f5staklink\fP() function increases the reference count for the The \f3staklink\fP() function increases the reference count for the
given \fIstack\fP and returns the increased count. given \fIstack\fP and returns the increased count.
The \f5stakinstall\fP() function The \f3stakinstall\fP() function
makes the specified \fIstack\fP the active stack and returns a pointer makes the specified \fIstack\fP the active stack and returns a pointer
to the previous active stack. to the previous active stack.
When the \fIoverflow\fP argument is not null, When the \fIoverflow\fP argument is not null,
it specifies a function that will it specifies a function that will
be called whenever \f5malloc\fP(3) fails while trying to grow the be called whenever \f3malloc\fP(3) fails while trying to grow the
stack. stack.
The \fIoverflow\fP function will be called with the size that was passed The \fIoverflow\fP function will be called with the size that was passed
to \f5malloc\fP(3). to \f3malloc\fP(3).
The \fIoverflow\fP function can call \f5exit\fP(3), call \f5longjmp\fP(3) The \fIoverflow\fP function can call \f3exit\fP(3), call \f3longjmp\fP(3)
or return. or return.
If the \f5overflow\fP function returns, If the \f3overflow\fP function returns,
it must return a pointer to a memory region of the given size. it must return a pointer to a memory region of the given size.
The default action is to write an error to standard error and to The default action is to write an error to standard error and to
call \f5exit\fP(2) with a non-zero exit value. call \f3exit\fP(2) with a non-zero exit value.
When \fIstack\fP is a null pointer, When \fIstack\fP is a null pointer,
the active stack is not changed the active stack is not changed
but the \fIoverflow\fP function for the active stack can be changed but the \fIoverflow\fP function for the active stack can be changed
and a pointer to the active stack is returned. and a pointer to the active stack is returned.
The \f5stakdelete\fP() function decrements the reference count and The \f3stakdelete\fP() function decrements the reference count and
frees the memory associated with frees the memory associated with
the specified stack the specified stack
when the reference count is zero. when the reference count is zero.
@ -90,20 +90,20 @@ The effect of subsequent references to objects
on the stack are undefined. on the stack are undefined.
.PP .PP
The The
\f5stakalloc\fP() function returns an aligned pointer to space on the \f3stakalloc\fP() function returns an aligned pointer to space on the
active stack that can be used to hold any object of the given \fIsize\fP. active stack that can be used to hold any object of the given \fIsize\fP.
\f5stakalloc\fP() is similar to \f5malloc\fP(3) except that individual \f3stakalloc\fP() is similar to \f3malloc\fP(3) except that individual
items returned by \f5stakalloc\fP() can not be freed. items returned by \f3stakalloc\fP() can not be freed.
\f5stakalloc\fP() causes the offset of the current object to be set to \f3stakalloc\fP() causes the offset of the current object to be set to
zero. zero.
.PP .PP
The The
\f5stakcopy\fP() function copies the given string onto the stack \f3stakcopy\fP() function copies the given string onto the stack
and returns a pointer to the \fIstring\fP on the stack. and returns a pointer to the \fIstring\fP on the stack.
\f5stakcopy\fP() causes the offset of the current object to be set to \f3stakcopy\fP() causes the offset of the current object to be set to
zero. zero.
.PP .PP
The \f5stakset\fP() function finds the frame containing the given The \f3stakset\fP() function finds the frame containing the given
\fIaddress\fP, frees all frames that were created after the one containing \fIaddress\fP, frees all frames that were created after the one containing
the given \fIaddress\fP, and sets the current object to the given the given \fIaddress\fP, and sets the current object to the given
\fIaddress\fP. \fIaddress\fP.
@ -116,39 +116,39 @@ stack, the program aborts and dumps core.
The remaining functions are used to build the current object incrementally. The remaining functions are used to build the current object incrementally.
An object that is built incrementally on the stack will An object that is built incrementally on the stack will
always occupy contiguous memory within a stack frame but always occupy contiguous memory within a stack frame but
until \f5stakfreeze\fP() is called, until \f3stakfreeze\fP() is called,
the location in memory for the object can change. the location in memory for the object can change.
There is a current offset associated with the current object that There is a current offset associated with the current object that
determines where subsequent operations apply. determines where subsequent operations apply.
Initially, this offset is zero, and the offset changes as a result Initially, this offset is zero, and the offset changes as a result
of the operations you specify. of the operations you specify.
The \f5stakseek\fP() function is used set the offset for the The \f3stakseek\fP() function is used set the offset for the
current object. current object.
The \fIoffset\fP argument to \f5stakseek\fP() specifies the new The \fIoffset\fP argument to \f3stakseek\fP() specifies the new
offset for the current object. offset for the current object.
The frame will be extended or moved The frame will be extended or moved
if \f5offset\fP causes the new current offset to extend beyond the if \f3offset\fP causes the new current offset to extend beyond the
current frame. current frame.
\f5stakseek\fP() returns a pointer to the beginning of the current object. \f3stakseek\fP() returns a pointer to the beginning of the current object.
The \f5staktell\fP() function gives the offset of the current object. The \f3staktell\fP() function gives the offset of the current object.
.PP .PP
The \f5stakputc\fP() function adds a given character to the current object The \f3stakputc\fP() function adds a given character to the current object
on the stack. on the stack.
The current offset is advanced by 1. The current offset is advanced by 1.
The \f5stakputs\fP() function appends the given \fIstring\fP onto the current The \f3stakputs\fP() function appends the given \fIstring\fP onto the current
object in the stack and returns the length of the string. object in the stack and returns the length of the string.
The current offset is advanced by the length of the string. The current offset is advanced by the length of the string.
The \f5stakwrite\fP() function appends the given \fIsize\fP byte memory The \f3stakwrite\fP() function appends the given \fIsize\fP byte memory
region starting at \fIaddress\fP onto the current region starting at \fIaddress\fP onto the current
object in the stack and advances the current offset by \fIsize\fP. object in the stack and advances the current offset by \fIsize\fP.
The current offset is returned. The current offset is returned.
.PP .PP
The \f5stakptr\fP() function converts the given \f5offset\fP The \f3stakptr\fP() function converts the given \f3offset\fP
for the current object into a memory address on the stack. for the current object into a memory address on the stack.
This address is only valid until another stack operation is given. This address is only valid until another stack operation is given.
The result is not defined if \fIoffset\fP exceeds the size of the current The result is not defined if \fIoffset\fP exceeds the size of the current
object. object.
The \f5stakfreeze\fP() The \f3stakfreeze\fP()
function terminates the current object on the function terminates the current object on the
stack and returns a pointer to the beginning of this object. stack and returns a pointer to the beginning of this object.
If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack
@ -157,7 +157,7 @@ contain zero and the contents of the remaining bytes are undefined.
.PP .PP
.SH HISTORY .SH HISTORY
The The
\f5stak\fP \f3stak\fP
interface was derived from similar routines in the KornShell code interface was derived from similar routines in the KornShell code
that is used for building parse trees and carrying out expansions. that is used for building parse trees and carrying out expansions.
It provides an efficient mechanism for grouping dynamically allocated It provides an efficient mechanism for grouping dynamically allocated
@ -165,6 +165,6 @@ objects so that they can be freed all at once rather than individually.
.SH AUTHOR .SH AUTHOR
David Korn David Korn
.SH SEE ALSO .SH SEE ALSO
\f5exit(2)\fP \f3exit(2)\fP
\f5longjmp(3)\fP \f3longjmp(3)\fP
\f5malloc(3)\fP \f3malloc(3)\fP

View file

@ -6,7 +6,7 @@
.ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i .ta .75i 1.5i 2.25i 3i 3.75i 4.5i 5.25i 6i
.PP .PP
.nf .nf
\f5 \f3
#include <stk.h> #include <stk.h>
Stk_t *stkopen(int \fIflags\fP); Stk_t *stkopen(int \fIflags\fP);
@ -27,17 +27,17 @@ int stkon(Stk *\fIstack\fP, char* \fIaddr\fP)
.fi .fi
.SH DESCRIPTION .SH DESCRIPTION
.PP .PP
\f5stk\fP is a package of routines designed to provide efficient \f3stk\fP is a package of routines designed to provide efficient
stack oriented dynamic storage. stack oriented dynamic storage.
A stack abstraction consists of an ordered list of contiguous A stack abstraction consists of an ordered list of contiguous
memory regions, called stack frames, that can hold objects of memory regions, called stack frames, that can hold objects of
arbitrary size. arbitrary size.
A stack is represented by the type \f5Stk_t\fP A stack is represented by the type \f3Stk_t\fP
defined in header \f5<stk.h>\fP. defined in header \f3<stk.h>\fP.
The type \f5Stk_t\fP is compatible with the type \f5Sfio_t\fP The type \f3Stk_t\fP is compatible with the type \f3Sfio_t\fP
defined by the \f5sfio\fP(3) library. defined by the \f3sfio\fP(3) library.
At any instant there is one active stack which can be referenced At any instant there is one active stack which can be referenced
by the constant \f5stkstd\fP. by the constant \f3stkstd\fP.
Variable size objects can be Variable size objects can be
added to the active stack added to the active stack
and programs can reference these objects directly with pointers. and programs can reference these objects directly with pointers.
@ -54,36 +54,36 @@ relative offsets ranging from zero to the current offset of the object.
There is a preset initial active stack. There is a preset initial active stack.
To use an additional stack, it is necessary to create it and to To use an additional stack, it is necessary to create it and to
install it as the active stack. install it as the active stack.
A stack is created with the \f5stkopen\fP() function. A stack is created with the \f3stkopen\fP() function.
A \fIflags\fP argument of \f5STK_SMALL\fP indicates that unused A \fIflags\fP argument of \f3STK_SMALL\fP indicates that unused
space on the stack should be freed whenever this stack ceases space on the stack should be freed whenever this stack ceases
to be the active stack. to be the active stack.
If successful, If successful,
\f5stkopen\fP() returns a pointer to a stack whose reference \f3stkopen\fP() returns a pointer to a stack whose reference
count is 1. count is 1.
Otherwise, \f5stkopen\fP() returns a null pointer. Otherwise, \f3stkopen\fP() returns a null pointer.
The \f5stklink\fP() function increases the reference count for the The \f3stklink\fP() function increases the reference count for the
given \fIstack\fP and returns the increased count. given \fIstack\fP and returns the increased count.
The \f5stkinstall\fP() function The \f3stkinstall\fP() function
makes the specified \fIstack\fP the active stack and returns a pointer makes the specified \fIstack\fP the active stack and returns a pointer
to the previous active stack. to the previous active stack.
When the \fIoverflow\fP argument is not null, When the \fIoverflow\fP argument is not null,
it specifies a function that will it specifies a function that will
be called whenever \f5malloc\fP(3) fails while trying to grow the be called whenever \f3malloc\fP(3) fails while trying to grow the
stack. stack.
The \fIoverflow\fP function will be called with the size that was passed The \fIoverflow\fP function will be called with the size that was passed
to \f5malloc\fP(3). to \f3malloc\fP(3).
The \fIoverflow\fP function can call \f5exit\fP(3), call \f5longjmp\fP(3) The \fIoverflow\fP function can call \f3exit\fP(3), call \f3longjmp\fP(3)
or return. or return.
If the \f5overflow\fP function returns, If the \f3overflow\fP function returns,
it must return a pointer to a memory region of the given size. it must return a pointer to a memory region of the given size.
The default action is to write an error to standard error and to The default action is to write an error to standard error and to
call \f5exit\fP(2) with a non-zero exit value. call \f3exit\fP(2) with a non-zero exit value.
When \fIstack\fP is a null pointer, When \fIstack\fP is a null pointer,
the active stack is not changed the active stack is not changed
but the \fIoverflow\fP function for the active stack can be changed but the \fIoverflow\fP function for the active stack can be changed
and a pointer to the active stack is returned. and a pointer to the active stack is returned.
The \f5stkclose\fP() function decrements the reference count and The \f3stkclose\fP() function decrements the reference count and
frees the memory associated with frees the memory associated with
the specified stack the specified stack
when the reference count is zero. when the reference count is zero.
@ -91,20 +91,20 @@ The effect of subsequent references to objects
on the stack are undefined. on the stack are undefined.
.PP .PP
The The
\f5stkalloc\fP() function returns an aligned pointer to space on the \f3stkalloc\fP() function returns an aligned pointer to space on the
active stack that can be used to hold any object of the given \fIsize\fP. active stack that can be used to hold any object of the given \fIsize\fP.
\f5stkalloc\fP() is similar to \f5malloc\fP(3) except that individual \f3stkalloc\fP() is similar to \f3malloc\fP(3) except that individual
items returned by \f5stkalloc\fP() can not be freed. items returned by \f3stkalloc\fP() can not be freed.
\f5stkalloc\fP() causes the offset of the current object to be set to \f3stkalloc\fP() causes the offset of the current object to be set to
zero. zero.
.PP .PP
The The
\f5stkcopy\fP() function copies the given string onto the stack \f3stkcopy\fP() function copies the given string onto the stack
and returns a pointer to the \fIstring\fP on the stack. and returns a pointer to the \fIstring\fP on the stack.
\f5stkcopy\fP() causes the offset of the current object to be set to \f3stkcopy\fP() causes the offset of the current object to be set to
zero. zero.
.PP .PP
The \f5stkset\fP() function finds the frame containing the given The \f3stkset\fP() function finds the frame containing the given
\fIaddress\fP, frees all frames that were created after the one containing \fIaddress\fP, frees all frames that were created after the one containing
the given \fIaddress\fP, and sets the current object to the given the given \fIaddress\fP, and sets the current object to the given
\fIaddress\fP. \fIaddress\fP.
@ -114,45 +114,45 @@ If \fIaddress\fP is null, the stack is reset to the beginning.
If it is non-null, but is not the address of an object on the If it is non-null, but is not the address of an object on the
stack, the program aborts and dumps core. stack, the program aborts and dumps core.
.PP .PP
The \f5sfio\fP(3) output functions can be used to build The \f3sfio\fP(3) output functions can be used to build
current object incrementally. current object incrementally.
An object that is built incrementally on the stack will An object that is built incrementally on the stack will
always occupy contiguous memory within a stack frame but always occupy contiguous memory within a stack frame but
until \f5stkfreeze\fP() is called, until \f3stkfreeze\fP() is called,
the location in memory for the object can change. the location in memory for the object can change.
There is a current offset associated with the current object that There is a current offset associated with the current object that
determines where subsequent operations apply. determines where subsequent operations apply.
Initially, this offset is zero, and the offset changes as a result Initially, this offset is zero, and the offset changes as a result
of the operations you specify. of the operations you specify.
The \f5stkseek\fP() function is used set the offset for the The \f3stkseek\fP() function is used set the offset for the
current object. current object.
The \fIoffset\fP argument to \f5stkseek\fP() specifies the new The \fIoffset\fP argument to \f3stkseek\fP() specifies the new
offset for the current object. offset for the current object.
The frame will be extended or moved The frame will be extended or moved
if \f5offset\fP causes the new current offset to extend beyond the if \f3offset\fP causes the new current offset to extend beyond the
current frame. current frame.
\f5stkseek\fP() returns a pointer to the beginning of the current object. \f3stkseek\fP() returns a pointer to the beginning of the current object.
The \f5stktell\fP() function gives the offset of the current object. The \f3stktell\fP() function gives the offset of the current object.
.PP .PP
The \f5stkptr\fP() function converts the given \f5offset\fP The \f3stkptr\fP() function converts the given \f3offset\fP
for the current object into a memory address on the stack. for the current object into a memory address on the stack.
This address is only valid until another stack operation is given. This address is only valid until another stack operation is given.
The result is not defined if \fIoffset\fP exceeds the size of the current The result is not defined if \fIoffset\fP exceeds the size of the current
object. object.
The \f5stkfreeze\fP() The \f3stkfreeze\fP()
function terminates the current object on the function terminates the current object on the
stack and returns a pointer to the beginning of this object. stack and returns a pointer to the beginning of this object.
If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack If \fIextra\fP is non-zero, \fIextra\fP bytes are added to the stack
before the current object is terminated. The first added byte will before the current object is terminated. The first added byte will
contain zero and the contents of the remaining bytes are undefined. contain zero and the contents of the remaining bytes are undefined.
.PP .PP
The \f5stkon\fP() The \f3stkon\fP()
function returns non-zero if the address given by \fIaddr\fP is function returns non-zero if the address given by \fIaddr\fP is
on the stack \fIstack\fP and \f50\fP otherwise. on the stack \fIstack\fP and \f30\fP otherwise.
.PP .PP
.SH HISTORY .SH HISTORY
The The
\f5stk\fP \f3stk\fP
interface was derived from similar routines in the KornShell code interface was derived from similar routines in the KornShell code
that is used for building parse trees and carrying out expansions. that is used for building parse trees and carrying out expansions.
It provides an efficient mechanism for grouping dynamically allocated It provides an efficient mechanism for grouping dynamically allocated
@ -160,7 +160,7 @@ objects so that they can be freed all at once rather than individually.
.SH AUTHOR .SH AUTHOR
David Korn David Korn
.SH SEE ALSO .SH SEE ALSO
\f5exit(2)\fP \f3exit(2)\fP
\f5longjmp(3)\fP \f3longjmp(3)\fP
\f5malloc(3)\fP \f3malloc(3)\fP
\f5sfio(3)\fP \f3sfio(3)\fP

View file

@ -109,7 +109,7 @@ environment variable.
Times are relative to Times are relative to
.B UTC .B UTC
(universal coordinated time, i.e., (universal coordinated time, i.e.,
.BR GMT .) .BR GMT ).
Otherwise times are relative to the local time zone. Otherwise times are relative to the local time zone.
Set by Set by
.L tminit() .L tminit()
@ -232,7 +232,7 @@ may also be preceded by
.B E .B E
for alternate era representation or for alternate era representation or
.B O .B O
for alternate digit representation (if supported by the current locale.) for alternate digit representation (if supported by the current locale).
Finally, an integral Finally, an integral
.I width .I width
preceding preceding
@ -262,6 +262,9 @@ Full weekday name.
.B b .B b
Abbreviated month name. Abbreviated month name.
.TP .TP
.B B
Full month name.
.TP
.B c .B c
.BR ctime (3) .BR ctime (3)
style date without the trailing style date without the trailing
@ -285,26 +288,27 @@ Blank padded day of month number.
Unpadded day of month number. Unpadded day of month number.
.TP .TP
.B f .B f
Locale default override date format. Date as
.IR %Y.%m.%d-%H:%M:%S .
.TP .TP
.B F .B F
Locale default date format ISO 8601:2000 standard date format; equivalent to
.RL ( tm_info.format[40] .) .IR %Y-%m-%d .
.TP .TP
.B h .B h
Abbreviated month name. Abbreviated month name.
.TP .TP
.B H .B H
24-hour clock hour. 24-hour clock hour, zero-padded.
.TP .TP
.B i .B i
International International
.BR date (1) .BR date (1)
date that includes the time zone type name date that includes the time zone type name
.RL ( tm_info.format[107] .) .RL ( tm_info.format[107] ).
.TP .TP
.B I .B I
12-hour clock hour. 12-hour clock hour, zero-padded.
.TP .TP
.B j .B j
1-offset Julian date. 1-offset Julian date.
@ -313,9 +317,7 @@ date that includes the time zone type name
0-offset Julian date. 0-offset Julian date.
.TP .TP
.B k .B k
.BR date (1) 24-hour clock hour, blank-padded.
style date
.RL ( tm_info.format[106] .)
.TP .TP
.B K .B K
Language neutral, all numeric, no embedded space date Language neutral, all numeric, no embedded space date
@ -324,12 +326,7 @@ suitable for sorting:
.LR '"%Y-%m-%d+%H:%M:%S"' . .LR '"%Y-%m-%d+%H:%M:%S"' .
.TP .TP
.B l .B l
.BR ls (1) 12-hour clock hour, blank-padded.
.B \-l
date that lists recent dates with
.L %g
and distant dates with
.BR %G .
.TP .TP
.B m .B m
Month number. Month number.
@ -342,16 +339,22 @@ Minutes.
character. character.
.TP .TP
.B N .B N
The time zone type or nation code. Nanoseconds 000000000-999999999.
.TP .TP
.B p .B p
Meridian (e.g., Meridian (e.g.,
.B AM .B AM
or or
.BR PM .) .BR PM ).
.TP
.B P
Lowercase meridian (e.g.,
.B am
or
.BR pm ).
.TP .TP
.B q .B q
The nanosecond part of the time. The quarter of the year.
.TP .TP
\fB%Q\fP\fI<delim>recent<delim>distant<delim>\fP \fB%Q\fP\fI<delim>recent<delim>distant<delim>\fP
Recent dates are formatted with Recent dates are formatted with
@ -406,7 +409,7 @@ Weekday number with 1 for Monday, 7 for Sunday.
Week number with Sunday as the first day. Week number with Sunday as the first day.
.TP .TP
.B V .B V
ISO week number (i18n is \fIfun\fP.) ISO week number (i18n is \fIfun\fP).
.TP .TP
.B w .B w
Weekday number with 0 for Sunday, 6 for Saturday. Weekday number with 0 for Sunday, 6 for Saturday.
@ -425,7 +428,7 @@ Local time style, using
that includes the hours and minutes. that includes the hours and minutes.
.TP .TP
.B y .B y
2-digit year (you'll be sorry.) 2-digit year (you'll be sorry).
.TP .TP
.B Y .B Y
4-digit year. 4-digit year.
@ -478,7 +481,7 @@ Equivalent to
.BR %s . .BR %s .
.TP .TP
\fP?\fP\fIalternate\fP \fP?\fP\fIalternate\fP
Use The
.I alternate .I alternate
format is a default format override has not been specified. format is a default format override has not been specified.
e.g., e.g.,
@ -486,7 +489,7 @@ e.g.,
uses uses
.BR %?%l . .BR %?%l .
Export Export
\f5TM_OPTIONS="format='\fP\fIoverride\fP\f5'"\fP \f3TM_OPTIONS="format='\fP\fIoverride\fP\f3'"\fP
to override the default. to override the default.
.PD .PD
.RE .RE

View file

@ -229,13 +229,16 @@ Full weekday name.
.B b .B b
Abbreviated month name. Abbreviated month name.
.TP .TP
.B B
Full month name.
.TP
.B c .B c
.IR ctime (3) .BR ctime (3)
style date without the trailing style date without the trailing
.BR newline . .BR newline .
.TP .TP
.B C .B C
.IR date (1) .BR date (1)
style date. style date.
.TP .TP
.B d .B d
@ -251,19 +254,28 @@ Blank padded day of month number.
.B E .B E
Unpadded day of month number. Unpadded day of month number.
.TP .TP
.B f
Date as
.IR %Y.%m.%d-%H:%M:%S .
.TP
.B F
ISO 8601:2000 standard date format; equivalent to
.IR %Y-%m-%d .
.TP
.B h .B h
Abbreviated month name. Abbreviated month name.
.TP .TP
.B H .B H
24-hour clock hour. 24-hour clock hour, zero-padded.
.TP .TP
.B i .B i
International International
.IR date (1) .BR date (1)
date that includes the time zone type name. date that includes the time zone type name
.RL ( tm_info.format[107] ).
.TP .TP
.B I .B I
12-hour clock hour. 12-hour clock hour, zero-padded.
.TP .TP
.B j .B j
1-offset Julian date. 1-offset Julian date.
@ -271,13 +283,17 @@ date that includes the time zone type name.
.B J .B J
0-offset Julian date. 0-offset Julian date.
.TP .TP
.B k
24-hour clock hour, blank-padded.
.TP
.B K
Language neutral, all numeric, no embedded space date
with larger to smaller time units from left to right,
suitable for sorting:
.LR '"%Y-%m-%d+%H:%M:%S"' .
.TP
.B l .B l
.IR ls (1) 12-hour clock hour, blank-padded.
.B \-l
date that lists recent dates with
.IR hh : mm
and distant dates with
.IR yyyy .
.TP .TP
.B m .B m
Month number. Month number.
@ -289,12 +305,36 @@ Minutes.
.B newline .B newline
character. character.
.TP .TP
.B N
Nanoseconds 000000000-999999999.
.TP
.B p .B p
Meridian (e.g., Meridian (e.g.,
.B AM .B AM
or or
.BR PM ). .BR PM ).
.TP .TP
.B P
Lowercase meridian (e.g.,
.B am
or
.BR pm ).
.TP
.B q
The quarter of the year.
.TP
\fB%Q\fP\fI<delim>recent<delim>distant<delim>\fP
Recent dates are formatted with
.I recent
and distant dates are formatted with
.IR distant ,
where
.I <delim>
is any character not appearing in
.I recent
or
.IR distant .
.TP
.B r .B r
12-hour time as 12-hour time as
.IR hh : mm : ss .IR hh : mm : ss
@ -304,8 +344,22 @@ or
24-hour time as 24-hour time as
.IR hh : mm . .IR hh : mm .
.TP .TP
.B s
Seconds since the epoch.
.RI . prec
preceding
.B s
appends
.I prec
nanosecond digits,
.B 9
if
.I prec
is omitted.
.TP
.B S .B S
Seconds. .I seconds.subseconds
since the epoch.
.TP .TP
.B t .B t
.B tab .B tab
@ -315,11 +369,17 @@ character.
24-hour time as 24-hour time as
.IR hh : mm : ss . .IR hh : mm : ss .
.TP .TP
.B u
Weekday number with 1 for Monday, 7 for Sunday.
.TP
.B U .B U
Week number with Sunday as the first day. Week number with Sunday as the first day.
.TP .TP
.B V
ISO week number (i18n is \fIfun\fP).
.TP
.B w .B w
Weekday number. Weekday number with 0 for Sunday, 6 for Saturday.
.TP .TP
.B W .B W
Week number with Monday as the first day. Week number with Monday as the first day.
@ -335,37 +395,69 @@ Local time style, using
that includes the hours and minutes. that includes the hours and minutes.
.TP .TP
.B y .B y
2-digit year. 2-digit year (you'll be sorry).
.TP .TP
.B Y .B Y
4-digit year. 4-digit year.
.TP .TP
.B z .B z
Time zone type name. Time zone
.I SHHMM
west of UTC offset where
.I S
is
.B +
or
.BR - .
.TP .TP
.B Z .B Z
Time zone name. Time zone name.
.TP .TP
.BI + flag =[=]][-+]]\fIflag\fP
.TP Set (default or +) or clear (-)
.BI \- flag .I flag
Temporarily (until in
.L tmform()
returns) sets (+) or clears (\-) the
.L tm_info.flags .L tm_info.flags
flags specified by for the remainder of
.IR flag : .IR format ,
or for the remainder of the process if
.B ==
is specified.
.I flag
may be:
.RS .RS
.TP .TP
.B l .B l
.L TM_LEAP .L (TM_LEAP)
Enable leap second adjustments.
.TP
.B s
.L (TM_SUBSECOND)
Append nanosecond
.B .%N
to
.BR %S .
.TP .TP
.B u .B u
.L TM_UTC .L (TM_UTC)
UTC time zone.
.RE .RE
.TP .TP
.B # .B #
Number of seconds since the epoch. Equivalent to
.BR %s .
.TP
\fP?\fP\fIalternate\fP
The
.I alternate
format is a default format override has not been specified.
e.g.,
.BR ls (1)
uses
.BR %?%l .
Export
\f3TM_OPTIONS="format='\fP\fIoverride\fP\f3'"\fP
to override the default.
.PD .PD
.RE .RE
.TP .TP
@ -568,6 +660,8 @@ values may get clobbered by the
.I tm .I tm
library routines as the library routines as the
.IR ctime (3) .IR ctime (3)
and
.IR localtime (3)
routines typically return pointers to a single static routines typically return pointers to a single static
.L "struct tm" .L "struct tm"
area. area.

View file

@ -155,7 +155,7 @@ argument vector and the maximum number of elements in the vector.
and and
.L %v .L %v
data may also be counted length strings of the form data may also be counted length strings of the form
\f5(\fIcount\fP:\fIdata\fP)\fR \f3(\fIcount\fP:\fIdata\fP)\fR
where where
.I count .I count
is the number of characters in is the number of characters in

View file

@ -120,7 +120,7 @@ and
to modify its arguments on startup. to modify its arguments on startup.
Its a handy way to override default options on a directory by directory basis Its a handy way to override default options on a directory by directory basis
without modify the standard control files without modify the standard control files
(\f5Makefile\fP in this case.) (\f3Makefile\fP in this case).
.SH CAVEATS .SH CAVEATS
This paradigm is not recommended for all commands; only a few exceptions This paradigm is not recommended for all commands; only a few exceptions
make sense. make sense.

View file

@ -1,6 +1,6 @@
.fp 5 CW .fp 5 CW
.de MW .de MW
\f5\\$1\fP \f3\\$1\fP
.. ..
.TH VMALLOC 3 "1 May 1998" .TH VMALLOC 3 "1 May 1998"
.SH NAME .SH NAME
@ -75,18 +75,18 @@ for parceling out blocks of storage and a
Automatic locking prevents interference by reentrant Automatic locking prevents interference by reentrant
access to a region. access to a region.
.PP .PP
Pointers to space have type \f5Void_t*\fP Pointers to space have type \f3Void_t*\fP
where \f5Void_t\fP is \f5#define\fPd as \f5void\fP if possible, otherwise \f5char\fP. where \f3Void_t\fP is \f3#define\fPd as \f3void\fP if possible, otherwise \f3char\fP.
Space is counted in type \f5size_t\fP. Space is counted in type \f3size_t\fP.
.ne 4 .ne 4
.SS Regions .SS Regions
Regions have type \f5Vmalloc_t\fP. Regions have type \f3Vmalloc_t\fP.
Two predefined regions are pointed to by: Two predefined regions are pointed to by:
.TP .TP
.MW Vmheap .MW Vmheap
A general-purpose region, with best-fit A general-purpose region, with best-fit
allocation, and system memory discipline \f5Vmdcsystem\fP. allocation, and system memory discipline \f3Vmdcsystem\fP.
.PP .PP
These functions manipulate regions: These functions manipulate regions:
.PP .PP
@ -94,7 +94,7 @@ These functions manipulate regions:
creates a region with memory discipline \fIdisc\fP, creates a region with memory discipline \fIdisc\fP,
allocation method \fImeth\fP, allocation method \fImeth\fP,
and a setting for control \fIflags\fP. and a setting for control \fIflags\fP.
It returns a pointer to the region on success and \f5NULL\fP on failure. It returns a pointer to the region on success and \f3NULL\fP on failure.
The flags, represented by bit values or-ed together, are: The flags, represented by bit values or-ed together, are:
.TP .TP
.MW VM_SHARE .MW VM_SHARE
@ -104,7 +104,7 @@ This region may be accessed concurrently by multiple threads or processes.
Place tracing messages for each allocation event Place tracing messages for each allocation event
on the tracing file established by \fIvmtrace\fP. on the tracing file established by \fIvmtrace\fP.
.TP .TP
\f5VM_DBCHECK\fP, \f5VM_DBABORT\fP \f3VM_DBCHECK\fP, \f3VM_DBABORT\fP
.br .br
See \fBDebugging\fP below. See \fBDebugging\fP below.
.PP .PP
@ -112,7 +112,7 @@ See \fBDebugging\fP below.
closes a \fIregion\fP and releases all associated memory closes a \fIregion\fP and releases all associated memory
according to the region's discipline. according to the region's discipline.
The first segment obtained from the discipline's The first segment obtained from the discipline's
\f5memoryf\fP function (see `Disciplines' below) will be the last released. \f3memoryf\fP function (see `Disciplines' below) will be the last released.
\fIvmclose\fP returns \-1 on failure and a non-negative value otherwise. \fIvmclose\fP returns \-1 on failure and a non-negative value otherwise.
.PP .PP
.I vmclear .I vmclear
@ -121,7 +121,7 @@ It returns \-1 on failure and a non-negative value otherwise.
.PP .PP
.I vmcompact .I vmcompact
releases as much of a \fIregion\fP's releases as much of a \fIregion\fP's
free space to its discipline's \f5memoryf\fP free space to its discipline's \f3memoryf\fP
function as possible. function as possible.
It returns a nonnegative value on success and \-1 on failure. It returns a nonnegative value on success and \-1 on failure.
.PP .PP
@ -129,17 +129,17 @@ It returns a nonnegative value on success and \-1 on failure.
adjusts and queries a \fIregion\fP's \fIflags\fP. adjusts and queries a \fIregion\fP's \fIflags\fP.
The indicated flags are turned on if \fItype\fP is nonzero, off if zero. The indicated flags are turned on if \fItype\fP is nonzero, off if zero.
\fIvmset\fP returns the previous value of all flags. \fIvmset\fP returns the previous value of all flags.
Thus, \f5vmset(region,0,0)\fP queries the flags without changing them. Thus, \f3vmset(region,0,0)\fP queries the flags without changing them.
In addition to the settable flags, one of In addition to the settable flags, one of
\f5VM_MTBEST\fP, \f5VM_MTDEBUG\fP, \f5VM_MTPROFILE\fP, \f3VM_MTBEST\fP, \f3VM_MTDEBUG\fP, \f3VM_MTPROFILE\fP,
\f5VM_MTPOOL\fP, or \f5VM_MTLAST\fP \f3VM_MTPOOL\fP, or \f3VM_MTLAST\fP
is returned to indicate the method used in creating the \fIregion\fP. is returned to indicate the method used in creating the \fIregion\fP.
.PP .PP
.I vmdisc .I vmdisc
changes the discipline of \fIregion\fP to the given new discipline changes the discipline of \fIregion\fP to the given new discipline
\fIdisc\fP if \fIdisc\fP is not \f5NULL\fP and its \f5memoryf\fP function \fIdisc\fP if \fIdisc\fP is not \f3NULL\fP and its \f3memoryf\fP function
is the same as the current discipline. If the current discipline is the same as the current discipline. If the current discipline
has an \f5exceptf\fP function, it will be called with event \f5VM_DISC\fP. has an \f3exceptf\fP function, it will be called with event \f3VM_DISC\fP.
This function always returns the current discipline. This function always returns the current discipline.
.PP .PP
.I vmmopen .I vmmopen
@ -173,11 +173,11 @@ to create their own memory allocation regions.
.PP .PP
.I vmmvalue .I vmmvalue
manages pairs of \fIkey\fP and \fIvalue\fP in a region opened via \fIvmopen()\fP. manages pairs of \fIkey\fP and \fIvalue\fP in a region opened via \fIvmopen()\fP.
If \fIop\fP is \f5VM_MMGET\fP, the value associated with \f5key\fP is returned. If \fIop\fP is \f3VM_MMGET\fP, the value associated with \f3key\fP is returned.
If \fIop\fP is \f5VM_MMSET\fP, the value associated with \f5key\fP will be If \fIop\fP is \f3VM_MMSET\fP, the value associated with \f3key\fP will be
set to \fIvalue\fP. set to \fIvalue\fP.
If \fIop\fP is \f5VM_MMADD\fP, the value associated with \f5key\fP will be If \fIop\fP is \f3VM_MMADD\fP, the value associated with \f3key\fP will be
treated as a signed long value to which \f5val\fP (also treated as a signed long value) treated as a signed long value to which \f3val\fP (also treated as a signed long value)
will be added. will be added.
The call always returns the updated data value associated with \fIkey\fP. The call always returns the updated data value associated with \fIkey\fP.
.PP .PP
@ -196,7 +196,7 @@ for dynamically linked libraries, etc.
returns a pointer to a block of the requested \fIsize\fP returns a pointer to a block of the requested \fIsize\fP
in a \fIregion\fP, aligned to the \fIstrictest alignment\fP in a \fIregion\fP, aligned to the \fIstrictest alignment\fP
that is suitable for the needs of any basic data type. that is suitable for the needs of any basic data type.
It returns \f5NULL\fP on failure. It returns \f3NULL\fP on failure.
.PP .PP
.I vmalign .I vmalign
works like \fIvmalloc\fP, but returns a block aligned to a common works like \fIvmalloc\fP, but returns a block aligned to a common
@ -206,27 +206,27 @@ multiple of \fIalign\fP and the \fIstrictest alignment\fP.
attempts to change the length of the block pointed to by attempts to change the length of the block pointed to by
\fIaddr\fP to the specified \fIsize\fP. \fIaddr\fP to the specified \fIsize\fP.
If that is impossible and \fItype\fP has If that is impossible and \fItype\fP has
at least one of \f5VM_RSMOVE\fP and \f5VM_RSCOPY\fP, at least one of \f3VM_RSMOVE\fP and \f3VM_RSCOPY\fP,
a new block is allocated and the old block is freed. a new block is allocated and the old block is freed.
The bit \f5VM_RSCOPY\fP also causes The bit \f3VM_RSCOPY\fP also causes
the new block to be initialized with the new block to be initialized with
as much of the old contents as will fit. as much of the old contents as will fit.
When a resized block gets larger, the new space will be cleared When a resized block gets larger, the new space will be cleared
if \fItype\fP has the bit \f5VM_RSZERO\fP. if \fItype\fP has the bit \f3VM_RSZERO\fP.
\fIvmresize\fP \fIvmresize\fP
returns a pointer to the final block, or \f5NULL\fP on failure. returns a pointer to the final block, or \f3NULL\fP on failure.
If \fIaddr\fP is \f5NULL\fP, \fIvmresize\fP behaves like \fIvmalloc\fP; If \fIaddr\fP is \f3NULL\fP, \fIvmresize\fP behaves like \fIvmalloc\fP;
otherwise, if \fIsize\fP is 0, it behaves like \fIvmfree\fP. otherwise, if \fIsize\fP is 0, it behaves like \fIvmfree\fP.
.PP .PP
.I vmfree .I vmfree
makes the currently allocated block pointed to by makes the currently allocated block pointed to by
\fIaddr\fP available for future allocations in its \fIregion\fP. \fIaddr\fP available for future allocations in its \fIregion\fP.
If \fIaddr\fP is \f5NULL\fP, \fIvmfree\fP does nothing. If \fIaddr\fP is \f3NULL\fP, \fIvmfree\fP does nothing.
It returns \-1 on error, and nonnegative otherwise. It returns \-1 on error, and nonnegative otherwise.
.PP .PP
.I vmnewof .I vmnewof
is a macro function that attempts to change the length of is a macro function that attempts to change the length of
the block pointed to by \fIaddr\fP to the size \f5n*sizeof(type)+x\fP. the block pointed to by \fIaddr\fP to the size \f3n*sizeof(type)+x\fP.
If the block is moved, new space will be initialized with as much of the If the block is moved, new space will be initialized with as much of the
old content as will fit. old content as will fit.
Additional space will be set to zero. Additional space will be set to zero.
@ -242,21 +242,21 @@ based on chunks of memory obtained from the heap region \fIVmheap\fP.
This call opens a new region. This call opens a new region.
.TP .TP
.MW "vmgetmem(region, 0, 0)" .MW "vmgetmem(region, 0, 0)"
This call closes the given \f5region\fP. This call closes the given \f3region\fP.
.TP .TP
.MW "vmgetmem(region,0,n)" .MW "vmgetmem(region,0,n)"
This call allocates a block of length \f5n\fP and clears it to zeros. This call allocates a block of length \f3n\fP and clears it to zeros.
.TP .TP
.MW "vmgetmem(region,p,0)" .MW "vmgetmem(region,p,0)"
This call frees the block \f5p\fP. This call frees the block \f3p\fP.
.TP .TP
.MW "vmgetmem(region,p,n)" .MW "vmgetmem(region,p,n)"
This call resizes the block \f5p\fP to length \f5n\fP This call resizes the block \f3p\fP to length \f3n\fP
and clears the new memory to zeros if the block grows. and clears the new memory to zeros if the block grows.
The block may be moved as deemed necessary by the allocator. The block may be moved as deemed necessary by the allocator.
.PP .PP
.SS "Memory disciplines" .SS "Memory disciplines"
Memory disciplines have type \f5Vmdisc_t\fP, Memory disciplines have type \f3Vmdisc_t\fP,
a structure with these members: a structure with these members:
.in +.5i .in +.5i
.nf .nf
@ -270,32 +270,32 @@ a structure with these members:
.TP .TP
.MW round .MW round
If this value is positive, all size arguments to the If this value is positive, all size arguments to the
\f5memoryf\fP function will be multiples of it. \f3memoryf\fP function will be multiples of it.
.TP .TP
.MW memoryf .MW memoryf
Points to a function to get or release segments of space for the Points to a function to get or release segments of space for the
\fIregion\fP. \fIregion\fP.
.TP .TP
.MW exceptf .MW exceptf
If this pointer is not \f5NULL\fP, If this pointer is not \f3NULL\fP,
the function it points to is called to announce the function it points to is called to announce
events in a \fIregion\fP. events in a \fIregion\fP.
.PP .PP
There are two standard disciplines, both with \f5round\fP being 0 and \f5exceptf\fP being \f5NULL\fP. There are two standard disciplines, both with \f3round\fP being 0 and \f3exceptf\fP being \f3NULL\fP.
.TP .TP
.MW Vmdcsystem .MW Vmdcsystem
A discipline whose \f5memoryf\fP function gets space from the operation system A discipline whose \f3memoryf\fP function gets space from the operation system
via different available methods which include \fImmap(2)\fP, \fIsbrk(2)\fP and via different available methods which include \fImmap(2)\fP, \fIsbrk(2)\fP and
functions from the WIN32 API. functions from the WIN32 API.
For historical reason, \fIVmdcsbrk\fP is also available and functions like \fIVmdcsystem\fP. For historical reason, \fIVmdcsbrk\fP is also available and functions like \fIVmdcsystem\fP.
.TP .TP
.MW Vmdcheap .MW Vmdcheap
A discipline whose \f5memoryf\fP function gets space from the region \f5Vmheap\fP. A discipline whose \f3memoryf\fP function gets space from the region \f3Vmheap\fP.
A region with \f5Vmdcheap\fP discipline and \f5Vmlast\fP A region with \f3Vmdcheap\fP discipline and \f3Vmlast\fP
allocation is good for building throwaway data structures. allocation is good for building throwaway data structures.
.PP .PP
A \fImemoryf\fP A \fImemoryf\fP
function returns a pointer to a memory segment on success, and \f5NULL\fP on failure. function returns a pointer to a memory segment on success, and \f3NULL\fP on failure.
When \fInsz >= 0\fP and \fIcsz > 0\fP, When \fInsz >= 0\fP and \fIcsz > 0\fP,
the function first attempts to change the current segment \fIaddr\fP to fit \fInsz\fP the function first attempts to change the current segment \fIaddr\fP to fit \fInsz\fP
(for example, \fInsz == 0\fP means deleting the segment \fIaddr\fP). (for example, \fInsz == 0\fP means deleting the segment \fIaddr\fP).
@ -309,26 +309,26 @@ function is called for events identified by \fItype\fP, which is coded thus:
.TP .TP
.MW VM_OPEN .MW VM_OPEN
This event is raised at the start of the process to open a new region. This event is raised at the start of the process to open a new region.
Argument \fIobj\fP will be a pointer to an object of type \f5Void_t*\fP Argument \fIobj\fP will be a pointer to an object of type \f3Void_t*\fP
initialized to NULL before the call. The return value of \fIexceptf\fP initialized to NULL before the call. The return value of \fIexceptf\fP
is significant as follows: is significant as follows:
On a negative return value, \fIvmopen\fP will terminate with failure. On a negative return value, \fIvmopen\fP will terminate with failure.
On a zero return value, \fIexceptf\fP may set \f5*((Void_t**)obj)\fP On a zero return value, \fIexceptf\fP may set \f3*((Void_t**)obj)\fP
to some non-NULL value to tell \fIvmopen\fP to some non-NULL value to tell \fIvmopen\fP
to allocate the region handle itself via \fImemoryf\fP. Otherwise, to allocate the region handle itself via \fImemoryf\fP. Otherwise,
the region handle will be allocated from the \f5Vmheap\fP region. the region handle will be allocated from the \f3Vmheap\fP region.
On a positive return value, On a positive return value,
the new region is being reconstructed the new region is being reconstructed
based on existing states of some previous region. based on existing states of some previous region.
In this case, \fIexceptf\fP should set \f5*(Void_t**)\fP\fIobj\fP to point to In this case, \fIexceptf\fP should set \f3*(Void_t**)\fP\fIobj\fP to point to
the field \f5Vmalloc_t.data\fP of the corresponding previous region the field \f3Vmalloc_t.data\fP of the corresponding previous region
(see \f5VM_CLOSE\fP below). (see \f3VM_CLOSE\fP below).
If the handle of the previous region was allocated If the handle of the previous region was allocated
via \fImemoryf\fP as discussed above in the case of the zero return value, via \fImemoryf\fP as discussed above in the case of the zero return value,
then it will be exactly restored. Otherwise, a new handle will be allocated from \f5Vmheap\fP. then it will be exactly restored. Otherwise, a new handle will be allocated from \f3Vmheap\fP.
The ability to create regions sharing the same states allows for The ability to create regions sharing the same states allows for
managing shared and/or persistent memory. managing shared and/or persistent memory.
.TP .TP
@ -342,13 +342,13 @@ The return value of \fIexceptf\fP is significant as follows:
On a negative return value, \fIvmclose\fP immediately returns with failure. On a negative return value, \fIvmclose\fP immediately returns with failure.
On a zero return value, \fIvmclose\fP proceeds normally by calling \f5memoryf\fP to free On a zero return value, \fIvmclose\fP proceeds normally by calling \f3memoryf\fP to free
all allocated memory segments and also freeing the region itself. all allocated memory segments and also freeing the region itself.
On a positive return value, \fIvmclose\fP will only free the region On a positive return value, \fIvmclose\fP will only free the region
without deallocating the associated memory segments. That is, without deallocating the associated memory segments. That is,
the field \fIVmalloc_t.data\fP of the region handle remains intact. the field \fIVmalloc_t.data\fP of the region handle remains intact.
This is useful for managing shared and/or persistent memory (see \f5VM_OPEN\fP above). This is useful for managing shared and/or persistent memory (see \f3VM_OPEN\fP above).
.TP .TP
.MW VM_ENDCLOSE .MW VM_ENDCLOSE
This event is raised at the end of the process to close a region. This event is raised at the end of the process to close a region.
@ -356,7 +356,7 @@ The return value of \fIexceptf\fP will be ignored.
.TP .TP
.MW VM_NOMEM .MW VM_NOMEM
An attempt to extend the region by the amount An attempt to extend the region by the amount
\f5(size_t)\fP\fIobj\fP failed. The region is unlocked, so the \f3(size_t)\fP\fIobj\fP failed. The region is unlocked, so the
\fIexceptf\fP function may free blocks. \fIexceptf\fP function may free blocks.
If the function returns a positive value the memory If the function returns a positive value the memory
request will be repeated. request will be repeated.
@ -365,7 +365,7 @@ request will be repeated.
The discipline structure is being changed. The discipline structure is being changed.
.SS "Allocation methods" .SS "Allocation methods"
Methods are of type \f5Vmethod_t*\fP. Methods are of type \f3Vmethod_t*\fP.
.TP .TP
.MW Vmbest .MW Vmbest
An approximately best-fit allocation strategy. An approximately best-fit allocation strategy.
@ -373,7 +373,7 @@ An approximately best-fit allocation strategy.
.MW Vmlast .MW Vmlast
A strategy for building structures that are only deleted in whole. A strategy for building structures that are only deleted in whole.
Only the latest allocated block can be freed. Only the latest allocated block can be freed.
This means that as soon as a block \f5a\fP is allocated, This means that as soon as a block \f3a\fP is allocated,
\fIvmfree\fP calls on blocks other than \c5a\fP are ignored. \fIvmfree\fP calls on blocks other than \c5a\fP are ignored.
.TP .TP
.MW Vmpool .MW Vmpool
@ -391,15 +391,15 @@ freeing a block twice.
An allocation method that records and prints summaries of memory usage. An allocation method that records and prints summaries of memory usage.
.SS Debugging .SS Debugging
The method \f5Vmdebug\fP is used to debug common memory violation problems. The method \f3Vmdebug\fP is used to debug common memory violation problems.
When a problem is found, When a problem is found,
a warning message is written to file descriptor 2 (standard error). a warning message is written to file descriptor 2 (standard error).
In addition, if flag \f5VM_DBABORT\fP is on, In addition, if flag \f3VM_DBABORT\fP is on,
the program is terminated by calling \fIabort\fP(2). the program is terminated by calling \fIabort\fP(2).
Each message is a line of self-explanatory fields separated by colons. Each message is a line of self-explanatory fields separated by colons.
The optional flag \f5-DVMFL\fP, if used during compilation, The optional flag \f3-DVMFL\fP, if used during compilation,
enables recording of file names and line numbers. enables recording of file names and line numbers.
The following functions work with method \f5Vmdebug\fP. The following functions work with method \f3Vmdebug\fP.
.PP .PP
.I vmdebug .I vmdebug
resets the file descriptor to write out warnings to the given argument. resets the file descriptor to write out warnings to the given argument.
@ -407,10 +407,10 @@ By default, this file descriptor is 2, the standard error.
\fIvmdebug\fP returns the previous file descriptor. \fIvmdebug\fP returns the previous file descriptor.
.PP .PP
.I vmdbcheck .I vmdbcheck
checks a region using \f5Vmdebug\fP or \f5Vmbest\fP for integrity. checks a region using \f3Vmdebug\fP or \f3Vmbest\fP for integrity.
If \f5Vmdebug\fP, this also checks for block overwriting errors. If \f3Vmdebug\fP, this also checks for block overwriting errors.
On errors, \fIvmdbwarn\fP is called. On errors, \fIvmdbwarn\fP is called.
If flag \f5VM_DBCHECK\fP is on, If flag \f3VM_DBCHECK\fP is on,
\fIvmdbcheck\fP is called at each invocation of \fIvmdbcheck\fP is called at each invocation of
\fIvmalloc\fP, \fIvmfree\fP, or \fIvmresize\fP. \fIvmalloc\fP, \fIvmfree\fP, or \fIvmresize\fP.
.PP .PP
@ -420,10 +420,10 @@ to be watched, and reported whenever met in
\fIvmalloc\fP, \fIvmresize\fP or \fIvmfree\fP. \fIvmalloc\fP, \fIvmresize\fP or \fIvmfree\fP.
The watch list has finite size and if it becomes full, The watch list has finite size and if it becomes full,
watches will be removed in a first-in-first-out fashion. watches will be removed in a first-in-first-out fashion.
If \fIaddr\fP is \f5NULL\fP, If \fIaddr\fP is \f3NULL\fP,
all current watches are canceled. all current watches are canceled.
\fIvmdbwatch\fP returns the watch bumped out due to an insertion \fIvmdbwatch\fP returns the watch bumped out due to an insertion
into a full list or \f5NULL\fP otherwise. into a full list or \f3NULL\fP otherwise.
.PP .PP
.I vmdbwarn .I vmdbwarn
is an internal function that processes is an internal function that processes
@ -433,17 +433,17 @@ but is a good place to plant debugger traps because
control goes there at every trouble. control goes there at every trouble.
.SS "Profiling" .SS "Profiling"
The method \f5Vmprofile\fP is used to profile memory usage. The method \f3Vmprofile\fP is used to profile memory usage.
Profiling data are maintained in private memory of a process so Profiling data are maintained in private memory of a process so
\f5Vmprofile\fP should be avoided from regions manipulating \f3Vmprofile\fP should be avoided from regions manipulating
persistent or shared memory. persistent or shared memory.
The optional flag \f5-DVMFL\fP, if used during compilation, The optional flag \f3-DVMFL\fP, if used during compilation,
enables recording of file names and line numbers. enables recording of file names and line numbers.
.PP .PP
.I vmprofile .I vmprofile
prints memory usage summary. prints memory usage summary.
The summary is restricted to region \fIvm\fP if \fIvm\fP is not \f5NULL\fP; The summary is restricted to region \fIvm\fP if \fIvm\fP is not \f3NULL\fP;
otherwise, it is for all regions created with \f5Vmprofile\fP. otherwise, it is for all regions created with \f3Vmprofile\fP.
Summary records are written to file descriptor \fIfd\fP as lines with Summary records are written to file descriptor \fIfd\fP as lines with
colon-separated fields. Here are some of the fields: colon-separated fields. Here are some of the fields:
.TP .TP
@ -468,15 +468,15 @@ A region is busy if some allocation operation is accessing it.
returns the region to which the block pointed to by returns the region to which the block pointed to by
\fIaddr\fP belongs. \fIaddr\fP belongs.
This works only in regions that allocate with This works only in regions that allocate with
\f5Vmbest\fP, \f5Vmdebug\fP or \f5Vmprofile\fP. \f3Vmbest\fP, \f3Vmdebug\fP or \f3Vmprofile\fP.
.PP .PP
.I vmsegment .I vmsegment
finds if some segment of memory in \fIregion\fP finds if some segment of memory in \fIregion\fP
contains the address \fIaddr\fP. contains the address \fIaddr\fP.
It returns the address of a found segment or \f5NULL\fP if none found. It returns the address of a found segment or \f3NULL\fP if none found.
.PP .PP
.I vmwalk .I vmwalk
walks all segments in \fIregion\fP or if \fIregion\fP is \f5NULL\fP, walks all segments in \fIregion\fP or if \fIregion\fP is \f3NULL\fP,
all segments in all regions. all segments in all regions.
At each segment, \fI(*walkf)(vm,addr,size,disc)\fP At each segment, \fI(*walkf)(vm,addr,size,disc)\fP
is called where \fIvm\fP is the region, \fIaddr\fP is the segment, is called where \fIvm\fP is the region, \fIaddr\fP is the segment,
@ -489,7 +489,7 @@ checks whether \fIaddr\fP
points to an address within some allocated block of the given region. points to an address within some allocated block of the given region.
If not, it returns \-1. If not, it returns \-1.
If so, it returns the offset from the beginning of the block. If so, it returns the offset from the beginning of the block.
The function does not work for a \f5Vmlast\fP region except The function does not work for a \f3Vmlast\fP region except
on the latest allocated block. on the latest allocated block.
.PP .PP
.I vmsize .I vmsize
@ -498,12 +498,12 @@ It returns \-1 if \fIaddr\fP
does not point to a valid block in the region. does not point to a valid block in the region.
Sizes may be padded beyond that requested; in Sizes may be padded beyond that requested; in
particular no block has size 0. particular no block has size 0.
The function does not work for a \f5Vmlast\fP region except The function does not work for a \f3Vmlast\fP region except
on the latest allocated block. on the latest allocated block.
.PP .PP
.I vmstat .I vmstat
gathers statistics on the given \fIregion\fP. gathers statistics on the given \fIregion\fP.
If \f5region\fP is NULL, it computes statistics for the \fIMalloc\fP calls. If \f3region\fP is NULL, it computes statistics for the \fIMalloc\fP calls.
This may include summing statistics from more than one regions constructed to avoid blocking This may include summing statistics from more than one regions constructed to avoid blocking
due to parallel or asynchronous operations. due to parallel or asynchronous operations.
If \fIstatb\fP is not NULL, \fIvmstat\fP computes and stores the statistics in \fIstatb\fP then returns 0. If \fIstatb\fP is not NULL, \fIvmstat\fP computes and stores the statistics in \fIstatb\fP then returns 0.
@ -511,27 +511,27 @@ If \fIstatb\fP is NULL, no statistics will be computed and
the returned value is either 1 if the region is busy, i.e., the returned value is either 1 if the region is busy, i.e.,
being accessed by some allocation call or 0 otherwise. being accessed by some allocation call or 0 otherwise.
A \f5Vmstat_t\fP structure has at least these members: A \f3Vmstat_t\fP structure has at least these members:
.in +.5i .in +.5i
.nf .nf
.ta \w'\f5size_t \fP'u +\w'\f5extent \fP'u .ta \w'\f3size_t \fP'u +\w'\f3extent \fP'u
.MW "int n_busy; /* # of busy blocks */ .MW "int n_busy; /* # of busy blocks */
.MW "int n_free; /* # of free blocks */ .MW "int n_free; /* # of free blocks */
.MW "size_t s_busy; /* total busy space */ .MW "size_t s_busy; /* total busy space */
.MW "size_t s_free; /* total free space */ .MW "size_t s_free; /* total free space */
.MW "size_t m_busy; /* maximum busy block size */ .MW "size_t m_busy; /* maximum busy block size */
.MW "size_t m_free; /* maximum free block size */ .MW "size_t m_free; /* maximum free block size */
.MW "int n_seg; /* count of segments */ .MW "int n_seg; /* count of segments */
.MW "size_t extent; /* memory extent of region */ .MW "size_t extent; /* memory extent of region */
.MW "int n_region; /* total Malloc regions */ .MW "int n_region; /* total Malloc regions */
.MW "int n_open; /* non-blocked operations */ .MW "int n_open; /* non-blocked operations */
.MW "int n_lock; /* blocked operations */ .MW "int n_lock; /* blocked operations */
.MW "int n_probe; /* region searches */ .MW "int n_probe; /* region searches */
.fi .fi
.in -.5i .in -.5i
.PP .PP
Bookkeeping overhead is counted in \f5extent\fP, Bookkeeping overhead is counted in \f3extent\fP,
but not in \f5s_busy\fP or \f5s_free\fP. but not in \f3s_busy\fP or \f3s_free\fP.
.PP .PP
.I vmtrace .I vmtrace
establishes file descriptor \fIfd\fP establishes file descriptor \fIfd\fP
@ -539,7 +539,7 @@ as the trace file and returns
the previous value of the trace file descriptor. the previous value of the trace file descriptor.
The trace descriptor is initially invalid. The trace descriptor is initially invalid.
Output is sent to the trace file by successful allocation Output is sent to the trace file by successful allocation
events when flag \f5VM_TRACE\fP is on. events when flag \f3VM_TRACE\fP is on.
.PP .PP
Tools for analyzing traces are described in \fImtreplay\fP(1). Tools for analyzing traces are described in \fImtreplay\fP(1).
The trace record for an allocation event The trace record for an allocation event
@ -563,11 +563,11 @@ The address of the affected region.
.TP .TP
.I method .I method
A string that tells the region's method: A string that tells the region's method:
\f5best\fP, \f5last\fP, \f5pool\fP, \f5profile\fP, or \f5debug\fP. \f3best\fP, \f3last\fP, \f3pool\fP, \f3profile\fP, or \f3debug\fP.
.PP .PP
.I vmtrbusy .I vmtrbusy
outputs a trace of all currently busy blocks in region \f5vm\fP. outputs a trace of all currently busy blocks in region \f3vm\fP.
This only works with the \f5Vmbest\fP, \f5Vmdebug\fP and \f5Vmprofile\fP methods. This only works with the \f3Vmbest\fP, \f3Vmdebug\fP and \f3Vmprofile\fP methods.
.PP .PP
.I vmdata .I vmdata
returns the core data of the given region. returns the core data of the given region.
@ -592,7 +592,7 @@ set the maximum number of these extra regions to \fIregmax\fP.
.PP .PP
These functions are instrumented for run-time debugging, profiling and tracing. These functions are instrumented for run-time debugging, profiling and tracing.
For accurate reporting of files and line numbers, For accurate reporting of files and line numbers,
application code should include \f5vmalloc.h\fP and compile with \f5-DVMFL\fP. application code should include \f3vmalloc.h\fP and compile with \f3-DVMFL\fP.
The \fBVMALLOC_OPTIONS\fP environment variable, checked once before the first The \fBVMALLOC_OPTIONS\fP environment variable, checked once before the first
memory allocation, controls the memory allocation method, debugging and tracing; memory allocation, controls the memory allocation method, debugging and tracing;
its value is a comma or space separated list of its value is a comma or space separated list of
@ -649,7 +649,7 @@ combines the features of these obsolete environment variables:
{ \fBVMCHECK VMDEBUG VMETHOD VMPROFILE VMTRACE\fP }. { \fBVMCHECK VMDEBUG VMETHOD VMPROFILE VMTRACE\fP }.
.SH RECENT CHANGES .SH RECENT CHANGES
\f5Vmlast\fP: allocated blocks are now allowed to be resized (09/1998). \f3Vmlast\fP: allocated blocks are now allowed to be resized (09/1998).
.SH SEE ALSO .SH SEE ALSO
\fImtreplay\fP(1), \fImalloc\fP(3). \fImtreplay\fP(1), \fImalloc\fP(3).

View file

@ -953,7 +953,7 @@ astlicense(char* p, int size, char* file, char* options, int cc1, int cc2, int c
comment(&notice, &buf, NiL, 0, 0); comment(&notice, &buf, NiL, 0, 0);
COMMENT(&notice, &buf, "You should have received a copy of the", 0); COMMENT(&notice, &buf, "You should have received a copy of the", 0);
COMMENT(&notice, &buf, "GNU General Public License", 0); COMMENT(&notice, &buf, "GNU General Public License", 0);
COMMENT(&notice, &buf, "along with this software (see the file COPYING.)", 0); COMMENT(&notice, &buf, "along with this software (see the file COPYING).", 0);
COMMENT(&notice, &buf, "If not, a copy is available at", 0); COMMENT(&notice, &buf, "If not, a copy is available at", 0);
COMMENT(&notice, &buf, "http://www.gnu.org/copyleft/gpl.html", 0); COMMENT(&notice, &buf, "http://www.gnu.org/copyleft/gpl.html", 0);
comment(&notice, &buf, NiL, 0, 0); comment(&notice, &buf, NiL, 0, 0);

View file

@ -201,7 +201,7 @@ large_gam(x)
return (u); return (u);
} }
/* /*
* Good to < 1 ulp. (provably .90 ulp; .87 ulp on 1,000,000 runs.) * Good to < 1 ulp. (Provably .90 ulp; .87 ulp on 1,000,000 runs.)
* It also has correct monotonicity. * It also has correct monotonicity.
*/ */
static double static double

View file

@ -82,7 +82,7 @@ extern long int random();
state information will give 7 longs worth of state information, which will state information will give 7 longs worth of state information, which will
allow a degree seven polynomial. (Note: The zeroeth word of state allow a degree seven polynomial. (Note: The zeroeth word of state
information also has some other information stored in it; see setstate information also has some other information stored in it; see setstate
for details). The random number generation technique is a linear feedback for details.) The random number generation technique is a linear feedback
shift register approach, employing trinomials (since there are fewer terms shift register approach, employing trinomials (since there are fewer terms
to sum up that way). In this approach, the least significant bit of all to sum up that way). In this approach, the least significant bit of all
the numbers in the state table will act as a linear feedback shift register, the numbers in the state table will act as a linear feedback shift register,
@ -170,7 +170,7 @@ static long int randtbl[DEG_3 + 1] =
pointer. These two pointers are always rand_sep places aparts, as they pointer. These two pointers are always rand_sep places aparts, as they
cycle through the state information. (Yes, this does mean we could get cycle through the state information. (Yes, this does mean we could get
away with just one pointer, but the code for random is more efficient away with just one pointer, but the code for random is more efficient
this way). The pointers are left positioned as they would be from the call: this way.) The pointers are left positioned as they would be from the call:
initstate(1, randtbl, 128); initstate(1, randtbl, 128);
(The position of the rear pointer, rptr, is really 0 (as explained above (The position of the rear pointer, rptr, is really 0 (as explained above
in the initialization of randtbl) because the state table pointer is set in the initialization of randtbl) because the state table pointer is set

View file

@ -42,7 +42,7 @@ static const char usage[] =
" \ayymmddHHMM.SS\a, or \ammddHHMMccyy.SS\a or \accyymmddHHMM.SS\a." " \ayymmddHHMM.SS\a, or \ammddHHMMccyy.SS\a or \accyymmddHHMM.SS\a."
" Conflicting standards and practice allow a leading or trailing" " Conflicting standards and practice allow a leading or trailing"
" 2 or 4 digit year for the 10 and 12 digit forms; the X/Open trailing" " 2 or 4 digit year for the 10 and 12 digit forms; the X/Open trailing"
" form is used to disambiguate (\btouch\b(1) uses the leading form.)" " form is used to disambiguate (\btouch\b(1) uses the leading form)."
" Avoid the 10 digit form to avoid confusion. The digit fields are:]{" " Avoid the 10 digit form to avoid confusion. The digit fields are:]{"
" [+cc?Century - 1, 19-20.]" " [+cc?Century - 1, 19-20.]"
" [+yy?Year in century, 00-99.]" " [+yy?Year in century, 00-99.]"
@ -82,7 +82,7 @@ static const char usage[] =
" are padded with \b0\b and string fields are padded with space." " are padded with \b0\b and string fields are padded with space."
" \afield\a may also be preceded by \bE\b for alternate era" " \afield\a may also be preceded by \bE\b for alternate era"
" representation or \bO\b for alternate digit representation (if" " representation or \bO\b for alternate digit representation (if"
" supported by the current locale.) Finally, an integral \awidth\a" " supported by the current locale). Finally, an integral \awidth\a"
" preceding \afield\a truncates the field to \awidth\a characters." " preceding \afield\a truncates the field to \awidth\a characters."
" The fields are:]:[format]{" " The fields are:]:[format]{"
" [+%?% character]" " [+%?% character]"

View file

@ -43,7 +43,7 @@ static const char usage[] =
"is written.]" "is written.]"
"[n:name?Write the name instead of the numeric ID.]" "[n:name?Write the name instead of the numeric ID.]"
"[r:real?Writes real ID instead of the effective ID.]" "[r:real?Writes real ID instead of the effective ID.]"
"[[a?This option is ignored.]" "[a?This option is ignored.]"
"[g:group?Writes only the group ID.]" "[g:group?Writes only the group ID.]"
"[u:user?Writes only the user ID.]" "[u:user?Writes only the user ID.]"
"[G:groups?Writes only the supplementary group IDs.]" "[G:groups?Writes only the supplementary group IDs.]"

View file

@ -39,8 +39,8 @@ static const char usage[] =
"[p:parents?Create any missing intermediate pathname components. For " "[p:parents?Create any missing intermediate pathname components. For "
"each dir operand that does not name an existing directory, effects " "each dir operand that does not name an existing directory, effects "
"equivalent to those caused by the following command shall occur: " "equivalent to those caused by the following command shall occur: "
"\vmkdir -p -m $(umask -S),u+wx $(dirname dir) && mkdir [-m mode]] " "\bmkdir -p -m $(umask -S),u+wx $(dirname dir) && mkdir [-m mode]] "
"dir\v where the \b-m\b mode option represents that option supplied to " "dir\b where the \b-m\b mode option represents that option supplied to "
"the original invocation of \bmkdir\b, if any. Each dir operand that " "the original invocation of \bmkdir\b, if any. Each dir operand that "
"names an existing directory shall be ignored without error.]" "names an existing directory shall be ignored without error.]"
"[v:verbose?Print a message on the standard error for each created " "[v:verbose?Print a message on the standard error for each created "