external/cde
1
0
Fork 0
mirror of git://git.code.sf.net/p/cdesktopenv/code synced 2025-03-09 15:50:02 +00:00
Code Issues Releases Wiki Activity

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

Browse source 
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
Download patch file Download diff file Expand all files Collapse all files

2
src/cmd/INIT/hurl.sh
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?]
}
[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
transferred.]:[bytes]
[v:verbose?Verbose trace.]

38
src/cmd/INIT/package.sh
View file

@ -98,7 +98,7 @@ export TMPDIR
src="cmd contrib etc lib"
use="/usr/common /exp /usr/local /usr/add-on /usr/addon /usr/tools /usr /opt"
usr="/home"
lib="" # nee /usr/local/lib /usr/local/shlib
lib="" # need /usr/local/lib /usr/local/shlib
ccs="/usr/kvm /usr/ccs/bin"
org="gnu GNU"
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.]
[+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
[\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
are listed. \apackage\a may be a package or component name.]
[+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
\bmake\b (default), \btest\b or \bwrite\b action. \bold\b
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
ignored. \bfailed\b lists failures only and \bpath\b lists the
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
readable then it is sourced to initialize the environment. 32 or 64
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
against the checksum files in
\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)]
[+lcl?Generate a package archive suitable for
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
\bpkgadd\b(1).]
[+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 only changes from a previous base package.
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
deltas referring to the current base. Only the \btgz\b and
\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
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
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
the descriptions and components.]
[+?\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.
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
makefile compiler workarounds, e.g., if \b$HOSTTYPE\b matches \bhp.*\b
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.]
[+?Each component contains an \bast\b \bnmake\b(1) makefile (either
\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
no support for old-make/gnu-make makefiles; if the binaries are just
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
[${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
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.
${bP}
${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
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
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
@ -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.
${bP}
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
${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
@ -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}
${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
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
the terminal and captured in ${bB}\$INSTALLROOT/lib/package/gen/make.out${eB}:${bX}
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.
release [ [CC]YY-MM-DD [ [cc]yy-mm-dd ] ] [ package ]
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
be a package or component name.
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
recent make (default), test or write action. old specifies the
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
failures only and path lists the results file path only.
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
sourced to initialize the environment. 32 or 64 implies
\$PACKAGEROOT of . and specifies the target architecture word
size (which may be silently ignored.)
size (which may be silently ignored).
verify [ PACKAGE ]
Verify installed binary files against the checksum files in
\$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
complete copy of all components. A delta package contains
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
base is overwritten if there are no deltas referring to the
current base. Only the tgz and lcl formats support delta.

2
src/cmd/INIT/proto.c
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, "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, "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, "http://www.gnu.org/copyleft/gpl.html",sizeof( "http://www.gnu.org/copyleft/gpl.html")-1, 0);
comment(&notice, &buf, ((char*)0), 0, 0);

2
src/cmd/INIT/regress.sh
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
redirected through regular files.]
[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]
[x:trace?Enable debug tracing.]
[v:verbose?List differences between actual (<) and expected (>) output,

4
src/cmd/INIT/release.c
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 ]]"
" (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"
" 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"
" 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"
" standard input is read.]"
"[+?The entries for each \afile\a are annotated with the file directory name.]"

4
src/cmd/INIT/rt.sh
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]
[-license?http://www.eclipse.org/org/documents/epl-v10.html]
[+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
operands are specified then \btest\b is assumed. If \b-\b is
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.]
[h!:heading?Enable per-file heading when more than one \afile\a operand
follows \b-\b.]
[v:verbose?Run with \vREGRESSFLAGS=-v\v.]
[v:verbose?Run with \bREGRESSFLAGS=-v\b.]
[ test ... | - [ file ... ] ]

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

2
src/cmd/ksh93/README
View file

@ -37,7 +37,7 @@ The options have the following defaults and meanings:
beginning of the trap.
BRACEPAT on C-shell type abc{d,e}f style file generation
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.
CMDLIB_DIR "\"/opt/ast/bin\""
The default virtual directory prefix for path-bound

4
src/cmd/ksh93/data/builtins.c
View file

@ -732,11 +732,11 @@ const char sh_optgetopts[] =
"[+n?Associate -\anumber\a and +\anumber\a options with the first "
"option with numeric arguments.]"
"[+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 "
"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 "
"\bfind\b(1).)]"
"\bfind\b(1)).]"
"[+s?\anumber\a specifies the \b--??man\b section number, "
"\b1\b by default.]"
"}"

542
src/cmd/ksh93/nval.3
View file

@ -1,7 +1,7 @@
.fp 5 CW
.TH NVAL 3 "12 Feb 2003"
.SH NAME
\fBnval\fR \- the \f5ksh\fP name/value library
\fBnval\fR \- the \f3ksh\fP name/value library
.SH SYNOPSIS
.ta .8i 1.6i 2.4i 3.2i 4.0i
.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_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);
void nv_close(Namval_t *\fInp\fP);
void nv_delete(Namval_t *\fInp\fP, Dt_t *\fIdict\fP, int \fInofree\fP);
void nv_close(Namval_t *\fInp\fP);
void nv_delete(Namval_t *\fInp\fP, Dt_t *\fIdict\fP, int \fInofree\fP);
.ft R
.fi
.SS "GETTING AND SETTING VALUES"
.nf
.ft 5
char *nv_getval(Namval_t *\fInp\fP);
char *nv_getval(Namval_t *\fInp\fP);
Sfdouble_t nv_getnum(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_unset(Namval_t *\fInp\fP, int \fIflags\fP);
int nv_clone(Namval_t *\fIsrc\fP, Namval_t *\fIdest\fP, int \fIflags\fP);
char *nv_name(Namval_t *\fInp\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);
int nv_clone(Namval_t *\fIsrc\fP, Namval_t *\fIdest\fP, int \fIflags\fP);
.ft R
.fi
.SS "ATTRIBUTES AND SIZE"
.nf
.ft 5
int nv_isnull(Namval_t *\fInp\fP);
int nv_setsize(Namval_t *\fInp\fP, int \fIsize\fP);
int nv_size(Namval_t *\fInp\fP);
unsigned nv_isattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
int nv_isnull(Namval_t *\fInp\fP);
int nv_setsize(Namval_t *\fInp\fP, int \fIsize\fP);
int nv_size(Namval_t *\fInp\fP);
unsigned nv_isattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
Namfun_t *nv_isvtree(Namval_t *\fInp\fP);
unsigned nv_onattr(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);
unsigned nv_onattr(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);
.ft R
.fi
.SS "ARRAY HANDLING"
.nf
.ft 5
unsigned nv_isarray(Namval_t *\fInp\fP);
Namarr_t *nv_setarray(Namval_t *\fInp\fP,void*(*\fIfun\fP)(Namval_t*,const char*,int));
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_arrayptr(Namval_t *\fInp\fP);
Namval_t *nv_putsub(Namval_t *\fInp\fP, char *\fIname\fP, long \fImode\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[]);
char *nv_getsub(Namval_t *\fInp\fP);
int nv_nextsub(Namval_t *\fInp\fP);
int nv_aindex(Namval_t *\fInp\fP);
void nv_setvec(Namval_t *\fInp\fP, int \fIappend\fP, int \fIargc\fP, char *\fIargv\fP[]);
char *nv_getsub(Namval_t *\fInp\fP);
int nv_nextsub(Namval_t *\fInp\fP);
int nv_aindex(Namval_t *\fInp\fP);
.ft R
.fi
.SS "DISCIPLINES"
@ -74,11 +74,11 @@ int nv_aindex(Namval_t *\fInp\fP);
.ft 5
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);
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);
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_adddisc(Namval_t *\fInp\fP, const char **\fInames\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_adddisc(Namval_t *\fInp\fP, const char **\fInames\fP);
const Namdisc_t *nv_discfun(int \fIwhich\fP);
.ft R
.fi
@ -86,29 +86,29 @@ const Namdisc_t *nv_discfun(int \fIwhich\fP);
.nf
.ft 5
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);
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
.fi
.SS "MISCELLANEOUS FUNCTIONS"
.nf
.ft 5
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);
void nv_setvtree(Namval_t *\fInp\fP);
void nv_setref(Namval_t *\fInp\fP, Dt_t *\fIdp\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);
void nv_setvtree(Namval_t *\fInp\fP);
void nv_setref(Namval_t *\fInp\fP, Dt_t *\fIdp\fP, int \fIflags\fP);
Namval_t *nv_lastdict(void);
.ft R
.fi
.SH DESCRIPTION
\fINval\fP is a library of functions for interacting with name-value
pairs as used in \f5ksh\fP.
It is built on top the container dictionary type library facility
in \f5libcdt\fP. (See cdt(3)).
pairs as used in \f3ksh\fP.
It is built on top of the container dictionary type library facility
in \f3libcdt\fP. (See cdt(3)).
Each name-value pair is represented by a
type named \f5Namval_t\fP.
A \f5Namval_t\fP contains the name, value and
type named \f3Namval_t\fP.
A \f3Namval_t\fP contains the name, value and
attributes of a variable.
Some attributes can have an associated number that
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
its behavior.
.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.
It can also assign a value and give attributes to a name-value pair.
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
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:
.IP
\f5NV_VARNAME\fP:
\f3NV_VARNAME\fP:
An invalid variable name causes an error.
.IP
\f5NV_IDENTIFIER\fP:
\f3NV_IDENTIFIER\fP:
A variable name that is not an identifier causes an error.
.IP
\f5NV_ASSIGN\fP:
\f3NV_ASSIGN\fP:
The \fIname\fP argument can contain an assignment.
.IP
\f5NV_NOARRAY\fP:
\f3NV_NOARRAY\fP:
The \fIname\fP argument cannot contain a subscript.
.IP
\f5NV_NOREF\fP:
\f3NV_NOREF\fP:
Do not follow references when finding the name-value pair.
.IP
\f5NV_NOADD\fP:
\f3NV_NOADD\fP:
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
\f5NV_NOSCOPE\fP:
\f3NV_NOSCOPE\fP:
Only the top level scope is used.
.IP
\f5NV_NOFAIL\fP:
Just return \f5NULL\fP when an error occurs.
\f3NV_NOFAIL\fP:
Just return \f3NULL\fP when an error occurs.
By default an error message is displayed and the current command
is aborted.
.IP
.PP
If a name-value pair by this name does not already exist, it is
created unless \fIflags\fP contains the \f5NV_NOADD\fP flag.
If \f5NV_VARNAME\fP, \f5NV_IDENTIFIER\fP and \f5NV_ASSIGN\fP are
created unless \fIflags\fP contains the \f3NV_NOADD\fP flag.
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
argument and no further processing is performed.
Otherwise, if \f5NV_ASSIGN\fP is specified, then the characters up
to the first \f5=\fP or \f5+=\fP are used to find the name-value pair,
and the characters after the \f5=\fP are used to define
Otherwise, if \f3NV_ASSIGN\fP is specified, then the characters up
to the first \f3=\fP or \f3+=\fP are used to find the name-value pair,
and the characters after the \f3=\fP are used to define
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.
If the first identifier in \fIname\fP is a reference and is not
preceded by a \fB.\fP,
it will be replaced by the value of the reference
to find the name of a variable.
Unless \fIflags\fP contains the \f5NV_NOREF\fP flag,
if the name-value pair give by \fIname\fP has the \f5NV_REF\fP
Unless \fIflags\fP contains the \f3NV_NOREF\fP flag,
if the name-value pair give by \fIname\fP has the \f3NV_REF\fP
attribute, it will be replaced by the variable whose name
is the value of this name-value pair.
If \f5NV_ASSIGN\fP is set in the \fIflags\fP argument,
the \fIname\fP variable can contain an \f5=\fP
If \f3NV_ASSIGN\fP is set in the \fIflags\fP argument,
the \fIname\fP variable can contain an \f3=\fP
and a value that will be assigned to the name-value pair.
Any attributes appearing in the \fIflags\fP argument
will be applied to the name-value pair after any value is assigned.
.PP
It is possible for an application to create additional dictionaries
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,
\f5NULL\fP is returned.
The \f5nv_lastdict()\fP function returns a pointer to the
\f3NULL\fP is returned.
The \f3nv_lastdict()\fP function returns a pointer to the
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
Name-value pairs can also be allocated without belonging to
a dictionary. They will typically be looked up by a \fIcreate\fP
discipline associated with a parent node. In this case the
node size will be \f5NV_MINSZ\fP and \fIn\fP nodes can be allocated
vial \f5calloc(5NV_MINSZ,\fIn\fP)\fP(3).
The \f5nv_namptr\fP function can be used on the pointer returned by
\f5calloc\fP along with the element number to return the
node size will be \f3NV_MINSZ\fP and \fIn\fP nodes can be allocated
vial \f3calloc(5NV_MINSZ,\fP\fIn\fP\f3)\fP(3).
The \f3nv_namptr\fP function can be used on the pointer returned by
\f3calloc\fP along with the element number to return the
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
The \f5nv_close()\fP indicates that the pointer returned by
\f5nv_open()\fP or \f5nv_opensub()\fP will not be referenced again. If the
The \f3nv_close()\fP indicates that the pointer returned by
\f3nv_open()\fP or \f3nv_opensub()\fP will not be referenced again. If the
name-value pair is unset, and not referenced elsewhere,
the name-value pair may be freed.
.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
node \fInp\fP will also be freed.
.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.
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,
and the precision or number of places after the decimal point
for floating point variables. If \fIsize\fP is greater than or
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.
.PP
The \f5nv_getval()\fP function returns the value of the given
name-value pair as a string. A \f5NULL\fP return value indicates
The \f3nv_getval()\fP function returns the value of the given
name-value pair as a string. A \f3NULL\fP return value indicates
that the name-value pair is unset.
The \f5nv_getnum()\fP function returns the value of the given
name-value pair as a double precision number using the \f5Sfio\fP
library (see sfio(3)) type \f5Sfdouble_t\fP.
For name-value pairs without the \f5NV_INTEGER\fP attribute,
The \f3nv_getnum()\fP function returns the value of the given
name-value pair as a double precision number using the \f3Sfio\fP
library (see sfio(3)) type \f3Sfdouble_t\fP.
For name-value pairs without the \f3NV_INTEGER\fP attribute,
the string value is evaluated as an arithmetic expression to
arrive at a numerical value.
.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 \fIflags\fP argument consists zero or more of the bitwise-or
of \f5NV_LONG\fP, \f5NV_SHORT\fP, \f5NV_DOUBLE\fP, \f5NV_INTEGER\fP,
\f5NV_RDONLY\fP, \f5NV_REF\fP, \f5NV_BINARY\fP, and \f5NV_NOFREE\fP.
The presence of \f5NV_RDONLY\fP allows the assignment to occur
even if the name-value pair has the \f5NV_RDONLY\fP attribute.
The presence of \f5NV_INTEGER\fP indicates that the \fIvalue\fP
of \f3NV_LONG\fP, \f3NV_SHORT\fP, \f3NV_DOUBLE\fP, \f3NV_INTEGER\fP,
\f3NV_RDONLY\fP, \f3NV_REF\fP, \f3NV_BINARY\fP, and \f3NV_NOFREE\fP.
The presence of \f3NV_RDONLY\fP allows the assignment to occur
even if the name-value pair has the \f3NV_RDONLY\fP attribute.
The presence of \f3NV_INTEGER\fP indicates that the \fIvalue\fP
argument is actually a pointer to a numerical type.
By default this type is \f5long\fP, but can be modified with
\f5NV_LONG\fP, \f5NV_SHORT\fP, and \f5NV_DOUBLE\fP
to represent \f5long long\fP, \f5short\fP, \f5double\fP, \f5long double\fP,
and \f5float\fP.
The presence of \f5NV_REF\fP indicates that the \fIvalue\fP
By default this type is \f3long\fP, but can be modified with
\f3NV_LONG\fP, \f3NV_SHORT\fP, and \f3NV_DOUBLE\fP
to represent \f3long long\fP, \f3short\fP, \f3double\fP, \f3long double\fP,
and \f3float\fP.
The presence of \f3NV_REF\fP indicates that the \fIvalue\fP
argument is actually a pointer to a name-value pair
and \f5np\fP should become a reference to this name-value pair.
If \f5NV_NOFREE\fP is specified, \fIvalue\fP itself becomes
and \f3np\fP should become a reference to this name-value pair.
If \f3NV_NOFREE\fP is specified, \fIvalue\fP itself becomes
the value of the name-value pair \fInp\fP.
Otherwise, a copy of the value is stored
as the value for \fInp\fP.
.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
pair.
If called from the \f5putval\fP discipline function, use the \fIflags\fP
argument as the \fIflags\fP to \f5nv_unset()\fP. Otherwise, use 0.
If called from the \f3putval\fP discipline function, use the \fIflags\fP
argument as the \fIflags\fP to \f3nv_unset()\fP. Otherwise, use 0.
.PP
The following attributes can be associated with a name-value pair:
.IP
\f5NV_EXPORT\fP:
\f3NV_EXPORT\fP:
The export attribute.
.IP
\f5NV_RDONLY\fP:
\f3NV_RDONLY\fP:
The readonly attribute.
.IP
\f5NV_LTOU\fP:
\f3NV_LTOU\fP:
Lower case characters are converted to upper case characters.
.IP
\f5NV_UTOL\fP:
\f3NV_UTOL\fP:
Upper case characters are converted to lower case characters.
.IP
\f5NV_RJUST\fP:
\f3NV_RJUST\fP:
Right justify and blank fill.
This attribute has an associated size that defines the
string length of the value.
.IP
\f5NV_LJUST\fP:
\f3NV_LJUST\fP:
Left justify and blank fill.
This attribute has an associated size that defines the
string length of the value.
.IP
\f5NV_ZFILL\fP:
Without \f5NV_LJUST\fP, right justifies and fills with leading zeros.
With \f5NV_LJUST\fP, left justify and strip leading zeros.
\f3NV_ZFILL\fP:
Without \f3NV_LJUST\fP, right justifies and fills with leading zeros.
With \f3NV_LJUST\fP, left justify and strip leading zeros.
Left justify and blank fill.
This attribute has an associated size that defines the
string length of the value.
.IP
\f5NV_TAGGED\fP:
\f3NV_TAGGED\fP:
Indicates the tagged attribute.
.IP
\f5NV_INTEGER\fP:
\f3NV_INTEGER\fP:
Causes value to be represented by a number.
This attribute has an associated number that defines the
arithmetic base to be used when the value is expanded as a string.
.IP
\f5NV_DOUBLE\fP:
Used in conjunction with \f5NV_INTEGER\fP to cause value
\f3NV_DOUBLE\fP:
Used in conjunction with \f3NV_INTEGER\fP to cause value
to be stored as a double precision floating point number.
This attribute has an associated number that defines the
number of places after the decimal point to be used when
the value is expanded as a string.
.IP
\f5NV_EXPNOTE\fP:
Used in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to
\f3NV_EXPNOTE\fP:
Used in conjunction with \f3NV_INTEGER\fP and \f3NV_DOUBLE\fP to
cause the value to be represented in scientific notation when
expanded as a string.
This attribute has an associated number that defines the
the precision of the mantissa.
.IP
\f5NV_HEXFLOAT\fP:
Used in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to
\f3NV_HEXFLOAT\fP:
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
a string.
.IP
\f5NV_BINARY\fP:
The name-value pair contains a buffer of binary data and \f5nv_size()\fP
\f3NV_BINARY\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
will be represented by the base64 encoding of the buffer.
The \f5NV_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.
The \f3NV_LJUST\fP flag may also be specified and causes the buffer
size to be fixed and data either truncated or filled with \f30\fP bytes.
.IP
\f5NV_REF\fP:
\f3NV_REF\fP:
The name-value pair is a name reference variable.
.IP
\f5NV_MINIMAL\fP:
\f3NV_MINIMAL\fP:
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
\f5NV_NODISC\fP:
\f3NV_NODISC\fP:
All discipline functions are ignored when performing assignments
and lookups.
.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 \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
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
in the value being changed to conform to the new attributes and size.
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
subscripts will be changed.
.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
or \f5NULL\fP otherwise.
or \f3NULL\fP otherwise.
.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.
.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.
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.
The remaining flags will be used in conjunction with \fImask\fP
to further restrict the walk.
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.
If \fIfn\fP is non-zero, then this function will be executed
for each name-value pair in the walk.
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.
.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.
.PP
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
on a name-value pair.
A discipline is defined by the types
\f5Namfun_t\fP and \f5Namdisc_t\fP.
The \f5Namdisc_t\fP is not modified by any of these functions and
\f3Namfun_t\fP and \f3Namdisc_t\fP.
The \f3Namdisc_t\fP is not modified by any of these functions and
can therefore be shared by several name-value pairs.
It contains following public fields in the order listed:
.nf
\f5size_t dsize;\fP
\f5void (*putval)(Namval_t*,const char*,int,Namfun_t*);\fP
\f5char *(*getval)(Namval_t*,Namfun_t*);\fP
\f5double (*getnum)(Namval_t*,Namfun_t*);\fP
\f5char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);\fP
\f5Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);\fP
\f5Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);\fP
\f5char *(*namef)(Namval_t*,Namfun_t*);\fP
\f5Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);\fP
\f5Namval_t *(*typef)(Namval_t*,Namfun_t*);\fP
\f3size_t dsize;\fP
\f3void (*putval)(Namval_t*,const char*,int,Namfun_t*);\fP
\f3char *(*getval)(Namval_t*,Namfun_t*);\fP
\f3double (*getnum)(Namval_t*,Namfun_t*);\fP
\f3char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);\fP
\f3Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);\fP
\f3Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);\fP
\f3char *(*namef)(Namval_t*,Namfun_t*);\fP
\f3Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);\fP
\f3Namval_t *(*typef)(Namval_t*,Namfun_t*);\fP
.fi
The \f5Namfun_t\fP type contains a member named
\f5disc\fP which points to a \f5Namdisc_t\fP structure.
The \f3Namfun_t\fP type contains a member named
\f3disc\fP which points to a \f3Namdisc_t\fP structure.
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.
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
to the \f5Namdisc_t\fP structure.
The \f5dsize\fP field of the \f5Namdisc_t\fP structure must be
to the \f3Namdisc_t\fP structure.
The \f3dsize\fP field of the \f3Namdisc_t\fP structure must be
the size of this structure. A value of 0,
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
the \f5size\fP field in the \f5Namfun_t\fP can must be set to
this size and overrides the value in the \f5Namdisc_t\fP structure.
the \f3size\fP field in the \f3Namfun_t\fP can must be set to
this size and overrides the value in the \f3Namdisc_t\fP structure.
.PP
When a variable is referenced by calling the \f5nv_getval()\fP function,
and the \f5NV_NODISC\fP attribute is not set,
the \f5getval()\fP discipline function is called with a pointer
When a variable is referenced by calling the \f3nv_getval()\fP function,
and the \f3NV_NODISC\fP attribute is not set,
the \f3getval()\fP discipline function is called with a pointer
to the name-value pair, \fInp\fP, and a pointer to the discipline,
\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
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
and the \f5NV_NODISC\fP attribute is not set,
The \f5nv_getn()\fP function can be called from within
the \f5getnum()\fP discipline to get the value that would
have resulted if there were no \f5getnum()\fP discipline.
and the \f3NV_NODISC\fP attribute is not set,
The \f3nv_getn()\fP function can be called from within
the \f3getnum()\fP discipline to get the value that would
have resulted if there were no \f3getnum()\fP discipline.
.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
to a name-value pair.
It is called whenever a value is assigned with \f5nv_putval()\fP
and the \f5NV_NODISC\fP attribute is not set,
or when a name-value pair is unset with \f5nv_unset()\fP.
When a name-value pair is unset, \f5putval\fP\f5()\fP
is called with \fIvalue\fP set to \f5NULL\fP.
The \f5nv_putv()\fP function is used within the \f5putval()\fP
It is called whenever a value is assigned with \f3nv_putval()\fP
and the \f3NV_NODISC\fP attribute is not set,
or when a name-value pair is unset with \f3nv_unset()\fP.
When a name-value pair is unset, \f3putval\fP\f3()\fP
is called with \fIvalue\fP set to \f3NULL\fP.
The \f3nv_putv()\fP function is used within the \f3putval()\fP
to perform the assignment or unset that would have occurred
if the discipline had not been installed.
.PP
The \f5createf()\fP discipline function is called from
\f5nv_open()\fP or \f5nv_create()\fP when the name-value pair preceding a
The \f3createf()\fP discipline function is called from
\f3nv_open()\fP or \f3nv_create()\fP when the name-value pair preceding a
.B \s+2.\s-2
is found.
This function is passed the name-value pointer plus the remaining string and
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
will be taken.
If the name-value pair that is returned is the same as the
one given, then the behavior will be the same as if
an invalid name had been given to \f5nv_open()\fP.
The \f5nv_create()\fP function may be called within
the \f5createf()\fP discipline function
an invalid name had been given to \f3nv_open()\fP.
The \f3nv_create()\fP function may be called within
the \f3createf()\fP discipline function
to perform the action that would have occurred
by an earlier \f5nv_open()\fP function.
by an earlier \f3nv_open()\fP function.
.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
associated with a name-value pair by allowing
builtins or functions whose name is of the
form \fIvarname\fP\f5.\fP\fIaction\fP to be defined.
By default, each name-value pair can have a \f5get\fP,
\f5set\fP, and \f5unset\fP discipline associated with it.
form \fIvarname\fP\f3.\fP\fIaction\fP to be defined.
By default, each name-value pair can have a \f3get\fP,
\f3set\fP, and \f3unset\fP discipline associated with it.
Whenever a builtin or function whose name is of the
form \fIvarname\fP\f5.\fP\fIaction\fP is defined or is unset,
and \fIaction\fP is not \f5get\fP,
\f5set\fP, or \f5unset\fP, the \fIsetdisc\fP\f5()\fP function is invoked
with the same argument format as \f5nv_setdisc\fP\f5()\fP.
form \fIvarname\fP\f3.\fP\fIaction\fP is defined or is unset,
and \fIaction\fP is not \f3get\fP,
\f3set\fP, or \f3unset\fP, the \fIsetdisc\fP\f3()\fP function is invoked
with the same argument format as \f3nv_setdisc\fP\f3()\fP.
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.
If the given action \fIa\fP is not known by this discipline,
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.
Otherwise, the \fIsetdisc\fP\f5()\fP function should save the function
name-value pair pointer, and return a non-\f5NULL\fP value.
Otherwise, the \fIsetdisc\fP\f3()\fP function should save the function
name-value pair pointer, and return a non-\f3NULL\fP value.
The name-value pointer to the function can be used to invoke
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.
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
\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.
This allows an application to get the list of valid discipline
action names allowed by a given name-value pair.
.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
shell level disciplines to be created for each of the name specified
in \f5names\fP.
in \f3names\fP.
.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.
Currently, the only one that is provided is the ones used to
implement \f5nv_adddisc()\fP which can be returned with an
argument of \f5NV_DCADD\fP.
implement \f3nv_adddisc()\fP which can be returned with an
argument of \f3NV_DCADD\fP.
.PP
The \f5clonef()\fP discipline function is called by \f5nv_clone()\fP
when making a copy of the \f5Namfun_t\fP discipline to the new node.
The \f3clonef()\fP discipline function is called by \f3nv_clone()\fP
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 new node, and the third argument is the flags that were passed
down to \f5nv_clone()\fP.
It must return a new instance of the \f5Namfun_t*\fP \f5fp\fP.
If omitted, then memory whose size is determined by the \f5size\fP
field of \f5fp\fP, if non-zero, or \f5fp->disc\fP, will be allocated
and copied from \f5fp\fP.
down to \f3nv_clone()\fP.
It must return a new instance of the \f3Namfun_t*\fP \f3fp\fP.
If omitted, then memory whose size is determined by the \f3size\fP
field of \f3fp\fP, if non-zero, or \f3fp->disc\fP, will be allocated
and copied from \f3fp\fP.
.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
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
\f5NULL\fP, it must return the first sub-variable. Otherwise,
it must return the next sub-variable, or \f5NULL\fP if there are
\f3NULL\fP, it must return the first sub-variable. Otherwise,
it must return the next sub-variable, or \f3NULL\fP if there are
no more variables.
.PP
A discipline is installed or removed with the
\f5nv_disc()\fP function.
\f3nv_disc()\fP function.
The following flags can be specified:
.IP
\f5NV_FIRST\fP:
If \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the top
\f3NV_FIRST\fP:
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
associated with the given name-value
pair \fInp\fP if not already present.
Otherwise, the top of the discipline stack is returned.
.IP
\f5NV_LAST\fP:
If \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the bottom
\f3NV_LAST\fP:
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
associated with the given name-value
pair \fInp\fP if not already present.
Otherwise, the bottom of the discipline stack is returned.
.IP
\f5NV_POP\fP:
If \fIfp\fP is non-\f5NULL\fP and it is on the stack,
it is removed and \fIfp\fP is returned. If \fIfp\fP is non-\f5NULL\fP
and is not on the stack, \f5NULL\fP is returned.
\f3NV_POP\fP:
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-\f3NULL\fP
and is not on the stack, \f3NULL\fP is returned.
Otherwise, the top discipline is popped
and returned.
.IP
\f5NV_CLONE\fP:
If \fIfp\fP is non-\f5NULL\fP and it is on the stack,
it is replaced by a copy created by \f5malloc\fP(3).
The \f5nofree\fP field is set to \f50\fP.
\f3NV_CLONE\fP:
If \fIfp\fP is non-\f3NULL\fP and it is on the stack,
it is replaced by a copy created by \f3malloc\fP(3).
The \f3nofree\fP field is set to \f30\fP.
The new discipline is returned.
Otherwise, \f5NULL\fP is returned.
Otherwise, \f3NULL\fP is returned.
.IP
\f50\fP:
If \fIfp\fP is non-\f5NULL\fP then it is equivalent to \f5NV_FIRST\fP.
Otherwise, it is equivalent to \f5NV_POP\fP.
\f30\fP:
If \fIfp\fP is non-\f3NULL\fP then it is equivalent to \f3NV_FIRST\fP.
Otherwise, it is equivalent to \f3NV_POP\fP.
.PP
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.
A pointer to this discipline is returned.
.PP
The \f5nv_aindex()\fP function returns
The \f3nv_aindex()\fP function returns
the current index for
the indexed array given by the name-value pair pointer \fInp\fP.
The return value is negative if \fInp\fP refers to
an associative array.
.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.
The function \fIfun\fP defines the semantics of the associative
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
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:
.IP
\f5NV_AINIT\fP:
\f3NV_AINIT\fP:
This will be called at initialization.
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.
.IP
\f5NV_AFREE\fP:
\f3NV_AFREE\fP:
This will be called after all elements of the name-value pair have been
deleted and the array is to be freed.
.IP
\f5NV_ADELETE\fP:
\f3NV_ADELETE\fP:
The current element should be deleted.
.IP
\f5NV_ANEXT\fP:
\f3NV_ANEXT\fP:
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.
.IP
\f5NV_ANAME\fP:
\f3NV_ANAME\fP:
The name of the current subscript must be returned.
.IP
\f5NV_ACURRENT\fP:
\f3NV_ACURRENT\fP:
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.
.IP
\f5NV_ASETSUB\fP:
\f3NV_ASETSUB\fP:
Set the current subscript to the name-value pair passed in
as the second argument.
.PP
If \fInp\fP refers to an array,
\f5nv_arrayptr()\fP returns a pointer to
the array discipline structure \f5Namarr_t\fP.
Otherwise \f5nv_arrayptr()\fP returns \f5NULL\fP.
\f3nv_arrayptr()\fP returns a pointer to
the array discipline structure \f3Namarr_t\fP.
Otherwise \f3nv_arrayptr()\fP returns \f3NULL\fP.
.PP
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.
Otherwise, \f5nv_getsub()\fP
returns \f5NULL\fP.
Otherwise, \f3nv_getsub()\fP
returns \f3NULL\fP.
.PP
The \f5nv_opensub()\fP function returns
The \f3nv_opensub()\fP function returns
a pointer to the name-value pair corresponding
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.
.PP
The \f5nv_putsub()\fP function is used to
set the subscript for the next reference to \f5np\fP.
If the \f5name\fP argument is not \f5NULL\fP,
The \f3nv_putsub()\fP function is used to
set the subscript for the next reference to \f3np\fP.
If the \f3name\fP argument is not \f3NULL\fP,
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
\f5ARRAY_ADD\fP:
\f3ARRAY_ADD\fP:
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.
.IP
\f5ARRAY_SCAN\fP:
\f3ARRAY_SCAN\fP:
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.
.IP
\f5ARRAY_UNDEF\fP:
\f3ARRAY_UNDEF\fP:
This causes any current scan to terminate and leaves the
subscript in an undefined state.
.PP
If \f5ARRAY_ADD\fP is not given and the subscript
does not exist, a \f5NULL\fP value is returned.
If \f3ARRAY_ADD\fP is not given and the subscript
does not exist, a \f3NULL\fP value is returned.
.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.
It returns 0 if there are no more subscripts or if called
when not in a scan.
.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
the value of \f5np\fP. The \f5nv_open()\fP open function is
called with this name, the dictionary given by \f5dp\fP,
and the \f5flags\fP argument.
A \f5NULL\fP value causes the shell global variable dictionary to be searched.
the value of \f3np\fP. The \f3nv_open()\fP open function is
called with this name, the dictionary given by \f3dp\fP,
and the \f3flags\fP argument.
A \f3NULL\fP value causes the shell global variable dictionary to be searched.
.PP
The \f5nv_setvtree()\fP function makes the name-value pair \f5np\fP
into a tree structured variable so that \f5nv_getval()\fP
The \f3nv_setvtree()\fP function makes the name-value pair \f3np\fP
into a tree structured variable so that \f3nv_getval()\fP
will return a string containing all the names and values of
children nodes in a format that can be used in
a shell compound assignment.
.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.
The \fInvname\fP field contains the name for the type.
.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.
.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
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
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
that the discipline \fBoptget\fP(3) can be extended with private
data used by the callback function.
.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
in bytes of the integer variable and \fIus\fP is non-zero
for unsigned integer types. If \fIdp\fP is specified then integer

10
src/cmd/ksh93/sh.1
View file

@ -800,7 +800,7 @@ is preceded by a tilde, then it is checked up to a
.B /
to see if it matches a user name in the
password database (see
.IR getpwname (3).)
.IR getpwname (3)).
If a match is found, the
.B \(ap
and the matched login name are replaced by the
@ -1581,9 +1581,9 @@ the call to this function.
Finally when
.B _
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"\^
below.).
below.)
.TP
.B !
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
(as if it had been defined with the
.IB name ()
syntax.)
syntax).
Otherwise if
.I name\^
refers to a file, the
@ -6758,7 +6758,7 @@ or
.B %f
formats, separates groups of digits with the grouping delimiter
.RB ( ,
on groups of 3 in the C locale.)
on groups of 3 in the C locale).
.PD
.PP
.RE

2
src/cmd/ksh93/sh/init.c
View file

@ -416,7 +416,7 @@ static void put_cdpath(register Namval_t* np,const char *val,int flags,Namfun_t
}
#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)
{
Shell_t *shp = sh_getinterp();

2
src/cmd/ksh93/sh/main.c
View file

@ -186,7 +186,7 @@ int sh_main(int ac, char *av[], Shinit_f userinit)
#if SHOPT_REMOTE
/*
* 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))
sh_onoption(SH_RC);

2
src/cmd/ksh93/sh/path.c
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)
{
/*
* 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
*/
char *sp = (char*)sh_malloc(strlen(path)+3);

315
src/cmd/ksh93/shell.3
View file

@ -1,7 +1,7 @@
.fp 5 CW
.TH SHELL 3 "28 Feb 2003" AST
.SH NAME
\fBshell\fR \- a \f5ksh\fP library interface
\fBshell\fR \- a \f3ksh\fP library interface
.SH SYNOPSIS
.ta .8i 1.6i 2.4i 3.2i 4.0i 4.8i 5.6i
.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_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_onoption(int \fIoption\fP);
unsigned int sh_offoption(int \fIoption\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_run(int \fIargc\fP, char *\fIargv\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_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);
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_run(int \fIargc\fP, char *\fIargv\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_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_setscope(Shscope_t *\fIscope\fP);
int (*sh_fdnotify(int(*\fIfn\fP)(int,int)))(int,int);
char *sh_fmtq(const char *\fIstring\fP);
void *sh_waitnotify(Shwait_f \fIfn\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);
.ft R
.fi
.SH DESCRIPTION
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.
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
this interface. It also defines replacement definitions for
the standard library functions
\f5access()\fP,
\f5close()\fP,
\f5dup()\fP,
\f5exit()\fP,
\f5fcntl()\fP,
\f5lseek()\fP,
\f5open()\fP,
\f5pipe()\fP,
\f5read()\fP,
\f3access()\fP,
\f3close()\fP,
\f3dup()\fP,
\f3exit()\fP,
\f3fcntl()\fP,
\f3lseek()\fP,
\f3open()\fP,
\f3pipe()\fP,
\f3read()\fP,
and
\f5write()\fP
\f3write()\fP
that must be used
with all code
intended to be compiled as built-in commands.
.P
The \f5<shell.h>\fP header includes \f5<ast.h>\fP which
in turn includes the standard include files, \f5<stddef.h>\fP,
\f5<stdlib.h>\fP, \f5<stdarg.h>\fP, \f5<limits.h>\fP,
\f5<stdio.h>\fP, \f5<string.h>\fP, \f5<unistd.h>\fP,
\f5<sys/types.h>\fP, \f5<fcntl.h>\fP, and \f5<locale.h>\fP.
The \f5<shell.h>\fP header also includes the headers
\f5<cdt.h>\fP,
\f5<cmd.h>\fP,
\f5<sfio.h>\fP,
\f5<nval.h>\fP,
\f5<stk.h>\fP,
and \f5<error.h>\fP
The \f3<shell.h>\fP header includes \f3<ast.h>\fP which
in turn includes the standard include files, \f3<stddef.h>\fP,
\f3<stdlib.h>\fP, \f3<stdarg.h>\fP, \f3<limits.h>\fP,
\f3<stdio.h>\fP, \f3<string.h>\fP, \f3<unistd.h>\fP,
\f3<sys/types.h>\fP, \f3<fcntl.h>\fP, and \f3<locale.h>\fP.
The \f3<shell.h>\fP header also includes the headers
\f3<cdt.h>\fP,
\f3<cmd.h>\fP,
\f3<sfio.h>\fP,
\f3<nval.h>\fP,
\f3<stk.h>\fP,
and \f3<error.h>\fP
so that in most cases, programs only require the single
header \f5<shell.h>\fP.
header \f3<shell.h>\fP.
.PP
Programs can use this library in one of the following ways:
.PD 0
@ -97,321 +97,322 @@ Programs can use this library in one of the following ways:
.B 1
To write builtin commands and/or other code that will be loaded
into the shell by loading dynamic libraries
at run time using the \f5builtin\fP(1) command.
In this case the shell will look for a function named \f5lib_init\fP
at run time using the \f3builtin\fP(1) command.
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
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
\f5Shbltin_t\fP.
In addition, for each argument named on the \f5builtin\fP
command line, it will look for a function named \f5b_\fP\fIname\fP\f5()\fP
\f3Shbltin_t\fP.
In addition, for each argument named on the \f3builtin\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.
.TP
.B 2
To build separate a separate command that uses the shell as a
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
are invoked.
The arguments \fIargc\fP and \fIargv\fP are the number
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
.B 3
To build a new version of \f5ksh\fP with extended capabilities,
for example \f5tksh\fP(1).
In this case, the user writes a \f5main()\fP function that
calls \f5sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments
from \f5main\fP and pointer to function, \fIfn\fP as a third
To build a new version of \f3ksh\fP with extended capabilities,
for example \f3tksh\fP(1).
In this case, the user writes a \f3main()\fP function that
calls \f3sh_main()\fP with the \fIargc\fP and \fIargv\fP arguments
from \f3main\fP and pointer to function, \fIfn\fP as a third
argument.. The function \fIfn\fP will
be invoked with argument \f50\fP after \f5ksh\fP has done initialization,
but before \f5ksh\fP has processed any start up files or executed
be invoked with argument \f30\fP after \f3ksh\fP has done initialization,
but before \f3ksh\fP has processed any start up files or executed
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
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 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.
.PD
.PP
The \f5Shell_t\fP structure contains the following fields:
The \f3Shell_t\fP structure contains the following fields:
.nf
.ft 5
Shopt_t \fIoptions\fP; \fR/* set -o options */\fP
Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP
Dt_t *\fIfun_tree\fP; \fR/* shell function dictionary */\fP
Dt_t *\fIalias_tree\fP; \fR/* shell alias dictionary */\fP
Dt_t *\fIbltin_tree\fP; \fR/* shell built-in dictionary */\fP
Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP
char *\fIinfile_name\fP; \fR/* path name of current input file */\fP
int \fIinlineno\fP; \fR/* line number of current input file */\fP
int \fIexitval\fP; \fR/* most recent exit value */\fP
Shopt_t \fIoptions\fP; \fR/* set -o options */\fP
Dt_t *\fIvar_tree\fP; \fR/* shell variable dictionary */\fP
Dt_t *\fIfun_tree\fP; \fR/* shell function 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 *\fItrack_tree\fP; \fR/* shell hash table */\fP
Shscope_t *\fItopscope\fP; \fR/* pointer to top-level scope */\fP
char *\fIinfile_name\fP; \fR/* path name of current input file */\fP
int \fIinlineno\fP; \fR/* line number of current input file */\fP
int \fIexitval\fP; \fR/* most recent exit value */\fP
.ft R
.fi
This structure is returned by \f5sh_init()\fP but can also be retrieved
by a call to \f5sh_getinterp()\fP.
This structure is returned by \f3sh_init()\fP but can also be retrieved
by a call to \f3sh_getinterp()\fP.
.PP
All built-in commands to the shell are invoked with
three arguments. The first two arguments give the
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 type \f5Shbltin_t\fP. This structure contains \f5shp\fP which is a pointer
to the shell interpreter, and \f5ptr\fP which is a pointer that
of type \f3Shbltin_t\fP. This structure contains \f3shp\fP which is a pointer
to the shell interpreter, and \f3ptr\fP which is a pointer that
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.
It takes the name of the built-in, \fIname\fP, a pointer
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.
If, \fIfn\fP is non-\f5NULL\fP the built-in command
is added or replaced. Otherwise, \f5sh_addbuiltin()\fP will
return a pointer to the built-in if it exists or \f5NULL\fP otherwise.
If \fIarg\fP is \f5(void*)1\fP the built-in will be deleted.
If, \fIfn\fP is non-\f3NULL\fP the built-in command
is added or replaced. Otherwise, \f3sh_addbuiltin()\fP will
return a pointer to the built-in if it exists or \f3NULL\fP otherwise.
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.
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
if the given pathname is encountered when performing
a path search.
When adding or replacing a built-in,
\f5sh_addbuiltin()\fP function returns a pointer to
the name-value pair corresponding to the built-in on success and \f5NULL\fP
\f3sh_addbuiltin()\fP function returns a pointer to
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.
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
cannot be deleted.
.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.
The \fIoption\fP argument can be any one of the following:
.IP
\f5SH_ALLEXPORT\fP:
The \f5NV_EXPORT\fP attribute is given to each variable whose
\f3SH_ALLEXPORT\fP:
The \f3NV_EXPORT\fP attribute is given to each variable whose
name is an identifier when a value is assigned.
.IP
\f5SH_BGNICE\fP:
\f3SH_BGNICE\fP:
Each background process is run at a lower priority.
.IP
\f5SH_ERREXIT\fP:
\f3SH_ERREXIT\fP:
Causes a non-interactive shell to exit when a command,
other than a conditional command, returns non-zero.
.IP
\f5SH_EMACS\fP:
\f3SH_EMACS\fP:
The emacs editing mode.
.IP
\f5SH_GMACS\fP:
\f3SH_GMACS\fP:
Same as the emacs editing mode except for the behavior of CONTROL-T.
.IP
\f5SH_HISTORY\fP:
\f3SH_HISTORY\fP:
Indicates that the history file has been created and that
commands can be logged.
.IP
\f5SH_IGNOREEOF\fP:
\f3SH_IGNOREEOF\fP:
Do not treat end-of-file as exit.
.IP
\f5SH_INTERACTIVE\fP:
\f3SH_INTERACTIVE\fP:
Set for interactive shells.
Do not set or unset this option.
.IP
\f5SH_MARKDIRS\fP:
\f3SH_MARKDIRS\fP:
A \fB/\fP is added to the end of each directory generated by pathname
expansion.
.IP
\f5SH_MONITOR\fP:
\f3SH_MONITOR\fP:
Indicates that the monitor option is enabled for job control.
.IP
\f5SH_NOCLOBBER\fP:
\f3SH_NOCLOBBER\fP:
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
in \f5<fcntl.h>\fP
created with \fB>\fP will have the \f3O_EXCL\fP bit set as described
in \f3<fcntl.h>\fP
.IP
\f5SH_NOGLOB\fP:
\f3SH_NOGLOB\fP:
Do not perform pathname expansion.
.IP
\f5SH_NOLOG\fP:
\f3SH_NOLOG\fP:
Do not save function definitions in the history file.
.IP
\f5SH_NOTIFY\fP:
\f3SH_NOTIFY\fP:
Cause a message to be generated as soon as each background job completes.
.IP
\f5SH_NOUNSET\fP:
\f3SH_NOUNSET\fP:
Cause the shell to fail with an error of an unset variable is
referenced.
.IP
\f5SH_PRIVILEGED\fP:
\f3SH_PRIVILEGED\fP:
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
the real uid and gid.
.IP
\f5SH_VERBOSE\fP:
\f3SH_VERBOSE\fP:
Cause each line to be echoed as it is read by the parser.
.IP
\f5SH_XTRACE\fP:
\f3SH_XTRACE\fP:
Cause each command to be displayed after all expansions, but
before execution.
.IP
\f5SH_VI\fP:
\f3SH_VI\fP:
The vi edit mode.
.IP
\f5SH_VIRAW\fP:
\f3SH_VIRAW\fP:
Read character at a time rather than line at a time when
in vi edit mode.
.IP
.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 value of \f50\fP for \fImode\fP indicates that \fIname\fP
refers to a string. A value of \f51\fP for \fImode\fP
indicates that \fIname\fP is an \f5Sfio_t*\fP to an open stream.
A value of \f52\fP for \fImode\fP indicates that \fIname\fP
points to a parse tree that has been returned by \f5sh_parse()\fP.
A value of \f30\fP for \fImode\fP indicates that \fIname\fP
refers to a string. A value of \f31\fP for \fImode\fP
indicates that \fIname\fP is an \f3Sfio_t*\fP to an open stream.
A value of \f32\fP for \fImode\fP indicates that \fIname\fP
points to a parse tree that has been returned by \f3sh_parse()\fP.
The complete file associated with the string or file
is compiled and then executed so that aliases defined
within the string or file will not take effect until
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.
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.
.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.
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
performing a path search.
.PP
The \f5sh_eval()\fP function executes a string or file
The \f3sh_eval()\fP function executes a string or file
stream \fIsp\fP.
If \fImode\fP is non-zero and the history file has
been created, the stream defined by \fIsp\fP
will be appended to the history file as a command.
.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
\fIsp\fP, and compilation flags, and returns a pointer
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:
.IP
\f5SH_NL\fP:
\f3SH_NL\fP:
Treat new-lines as \fB;\fP.
.IP
\f5SH_EOF\fP:
\f3SH_EOF\fP:
An end of file causes syntax error. By default it will
be treated as a new-line.
.PP
\f5ksh\fP executes each function defined with the \f5function\fP
reserved word in a separate scope. The \f5Shscope_t\fP type
\f3ksh\fP executes each function defined with the \f3function\fP
reserved word in a separate scope. The \f3Shscope_t\fP type
provides an interface to some of the information that
is available on each scope. The structure contains
the following public members:
.nf
\f5Sh_scope_t *par_scope;\fP
\f5int argc;\fP
\f5char **argv;\fP
\f5char *cmdname;\fP
\f5Dt_t *var_tree;\fP
\f3Sh_scope_t *par_scope;\fP
\f3int argc;\fP
\f3char **argv;\fP
\f3char *cmdname;\fP
\f3Dt_t *var_tree;\fP
.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.
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
argument uses the symbolic constants associated with \f5lseek()\fP
to indicate whether the \f5Iscope\fP argument is absolute,
argument uses the symbolic constants associated with \f3lseek()\fP
to indicate whether the \f3Iscope\fP argument is absolute,
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
old current scope.
.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
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
as arguments.
.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 script.
The argument \fIfunnode\fP is a pointer to the shell function
or built-in to execute.
The argument \fIvarnode\fP is a pointer to the name
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.
.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.
If a built-in takes a substantial amount of time
to execute, then it should check for interrupts
periodically by calling \f5sh_sigcheck()\fP.
If a signal is pending, \f5sh_sigcheck()\fP will exit
periodically by calling \f3sh_sigcheck()\fP.
If a signal is pending, \f3sh_sigcheck()\fP will exit
the function you are calling and return to the point
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
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.
If \fIsflag\fP is true, the shell will stop sleeping when
any signal is received; otherwise signals such as \f5SIGCONT\fP
and \f5SIGINFO\fP are treated normally.
any signal is received; otherwise signals such as \f3SIGCONT\fP
and \f3SIGINFO\fP are treated normally.
.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
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
must be saved or copied.
.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.
It is provided for extensions that need to keep track of
file descriptors that could be changed by shell commands.
The function \fIfn\fP is called with two arguments.
The first argument is the original file descriptor. The
second argument is the new file descriptor for duplicating
files, and \f5SH_FDCLOSE\fP when a file has been closed.
The previously installed \f5sh_fdnotify()\fP function pointer
files, and \f3SH_FDCLOSE\fP when a file has been closed.
The previously installed \f3sh_fdnotify()\fP function pointer
is returned.
.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
a slow device or waiting for a process to complete.
This function can process events and run shell commands
until there is input, the timer is reached or a signal arises.
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.
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.
The third argument is 0 for input file descriptors
and 1 for output file descriptor.
The function needs to return a value \f5>0\fP if there
is input on the file descriptor, and a value \f5<0\fP
The function needs to return a value \f3>0\fP if there
is input on the file descriptor, and a value \f3<0\fP
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
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
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
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
one of the following symbolic constants:
.IP
\f5SH_IOCOPROCESS\fP:
\f3SH_IOCOPROCESS\fP:
The stream corresponding to the most recent co-process.
.IP
\f5SH_IOHISTFILE\fP:
\f3SH_IOHISTFILE\fP:
The stream corresponding to the history file.
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
builtin(1)
cdt(3)

6
src/cmd/ksh93/tests/builtins.sh
View file

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

2
src/cmd/ksh93/tests/path.sh
View file

@ -878,8 +878,6 @@ got=$?
"(expected $exp, got $got)"
# 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"; }')
exp=127
PATH=$PWD $SHELL -c "$long_cmd" > /dev/null 2>&1

8
src/cmd/ksh93/tests/variables.sh
View file

@ -44,14 +44,6 @@ set abc def
if [[ $_ != def ]]
then err_exit _ variable not working
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
if [[ ! $PWD -ef . ]]
then err_exit PWD variable failed, not equivalent to .