| Solaris |
|
|
nval.3
Introduction to Library Functions NVAL(3)
NAME
nval - the ksh name/value library
SYNOPSIS
HEADERS/LIBRARIES
#include <nval.h>
libshell.a -lshell
DATA TYPES
Namval_t;
Namfun_t;
Namarr_t;
Namdisc_t;
OPENING/CLOSING
Namval_t *nv_open(const char *name, Dt_t *dict, int flags);
Namval_t *nv_create(const char *name, Dt_t *dict, int flags, Namfun_t *fp);
void nv_close(Namval_t *np);
GETTING AND SETTING VALUES
char *nv_getval(Namval_t *np);
Sfdouble_t nv_getnum(Namval_t *np);
char *nv_name(Namval_t *np);
void nv_putval(Namval_t *np, const char *val, int flags);
void nv_unset(Namval_t *np);
int nv_clone(Namval_t *src, Namval_t *dest, int flags);
ATTRIBUTES AND SIZE
int nv_isnull(Namval_t *np);
int nv_setsize(Namval_t *np, int size);
int nv_size(Namval_t *np);
unsigned nv_isattr(Namval_t *np, unsigned flags);
unsigned nv_onattr(Namval_t *np, unsigned flags);
unsigned nv_offattr(Namval_t *np, unsigned flags);
void nv_newattr(Namval_t *np, unsigned flags, int size);
ARRAY HANDLING
unsigned nv_isarray(Namval_t *np);
Namarr_t *nv_setarray(Namval_t *np,void*(*fun)(Namval_t*,const char*,int));
Namval_t *nv_putsub(Namval_t *np, char *name, long mode);
Namval_t *nv_opensub(Namval_t *np);
void nv_setvec(Namval_t *np, int append, int argc, char *argv[]);
char *nv_getsub(Namval_t *np);
int nv_nextsub(Namval_t *np);
int nv_aindex(Namval_t *np);
DISCIPLINES
Namfun_t *nv_disc(Namval_t *np, Namfun_t *fp, int flags);
Namfun_t *nv_hasdisc(Namval_t *np, const Namdisc_t *dp);
char *nv_getv(Namval_t *np, Namfun_t *fp);
Sfdouble_t nv_getn(Namval_t *np, Namfun_t *fp);
SunOS 5.10 Last change: 12 Feb 2003 1
Introduction to Library Functions NVAL(3)
void nv_putv(Namval_t *np, const char *val, int flags, Namfun_t *fp);
char *nv_setdisc(Namval_t *np, const char *a, Namval_t *f, Namfun_t *fp);
char *nv_adddisc(Namval_t *np, const char **names);
const Namdisc_t *nv_discfun(int which);
MISCELLANEOUS FUNCTIONS
int nv_scan(Dt_t *dict, void(*fn)(Namval_t*,void*), void *data, int mask, int flags);
Dt_t nv_dict(Namval_t *np);
void nv_setvtree(Namval_t *np);
void nv_setref(Namval_t *np);
Namval_t *nv_lastdict(void);
DESCRIPTION
Nval is a library of functions for interacting with name-
value pairs as used in ksh. It is built on top the con-
tainer dictionary type library facility in libcdt. (See
cdt(3)). Each name-value pair is represented by a type
named Namval_t. A Namval_t contains the name, value and
attributes of a variable. Some attributes can have an asso-
ciated number that represents the field width, arithmetic
base, or precision. Additionally, each name-value pair can
be associated with one or more processing disciplines that
affect its behavior.
The function nv_open() returns a pointer to a name-value
pair corresponding to the given name. It can also assign a
value and give attributes to a name-value pair. The argu-
ment dict defines the dictionary to search. A NULL value
causes the shell global variable dictionary to be searched.
The flags argument consists of the bitwise-or of zero or
more of the attributes listed later and zero or more of the
following:
NV_VARNAME: An invalid variable name causes an error.
NV_IDENTIFIER: A variable name that is not an identif-
ier causes an error.
NV_ASSIGN: The name argument can contain an assign-
ment.
NV_NOARRAY: The name argument cannot contain a sub-
script.
NV_NOREF: Do not follow references when finding the
name-value pair.
NV_NOADD: The name-value pair will not be added if it
doesn't exist. Instead, a NULL pointer will be
returned.
SunOS 5.10 Last change: 12 Feb 2003 2
Introduction to Library Functions NVAL(3)
NV_NOSCOPE: Only the top level scope is used.
NV_NOFAIL: Just return NULL when an error occurs. By
default an error message is displayed and the current
command is aborted.
If a name-value pair by this name does not already exist, it
is created unless flags contains the NV_NOADD flag. If
NV_VARNAME, NV_IDENTIFIER and NV_ASSIGN are all not speci-
fied, then no validity check is performed on the name argu-
ment and no further processing is performed. Otherwise, if
NV_ASSIGN is specified, then the characters up to the first
= or += are used to find the name-value pair, and the char-
acters after the = are used to define the value that will be
assigned to this name-value pair. If name does not contain
an =, than no assignment will be made. If the first iden-
tifier in name is a reference and is not preceded by a ., it
will be replaced by the value of the reference to find the
name of a variable. Unless flags contains the NV_NOREF
flag, if the name-value pair give by name has the NV_REF
attribute, it will be replaced by the variable whose name is
the value of this name-value pair. If NV_ASSIGN is set in
the flags argument, the name variable can contain an = and a
value that will be assigned to the name-value pair. Any
attributes appearing in the flags argument will be applied
to the name-value pair after any value is assigned.
It is possible for an application to create additional dic-
tionaries with the cdt library and associate them with
name-value pairs. The nv_dict() function returns the dic-
tionary associated with the specified name-value pair, or if
no dictionary was specified, NULL is returned. The
nv_lastdict() function returns a pointer the the name-value
pair that contains the last dictionary searched on the pre-
vious nv_open().
The nv_close() indicates that the pointer returned by
nv_open() or nv_opensub() will not be referenced again. If
the name-value pair is unset, and not referenced elsewhere,
the name-value pair may be freed.
The nv_name() function returns the name of the given name-
value pair np. The nv_setsize() 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
size is greater than or equal to zero, the current size is
changed to this value. The nv_size() function is equivalent
to nv_setsize() with the second argument negative.
SunOS 5.10 Last change: 12 Feb 2003 3
Introduction to Library Functions NVAL(3)
The nv_getval() function returns the value of the given
name-value pair as a string. A NULL return value indicates
that the name-value pair is unset. The nv_getnum() function
returns the value of the given name-value pair as a double
precision number using the Sfio library (See Sfio(3)) type
Sfdouble_t. For name-value pairs without the NV_INTEGER
attribute, the string value is evaluated as an arithmetic
expression to arrive at a numerical value.
The nv_putval() function is used to assign a value to the
name-value pair np. The flags argument consists zero or
more of the bitwise-or of NV_LONG, NV_SHORT, NV_DOUBLE,
NV_INTEGER, NV_RDONLY, NV_REF, NV_BINARY, and NV_NOFREE.
The presence of NV_RDONLY allows the assignment to occur
even if the name-value pair has the NV_RDONLY attribute.
The presence of NV_INTEGER indicates that the value argument
is actually a pointer to a numerical type. By default this
type is long, but can be modified with NV_LONG, NV_SHORT,
and NV_DOUBLE to represent long long, short, double, long
double, and float. The presence of NV_REF indicates that
the value argument is actually a pointer to a name-value
pair and np should become a reference to this name-value
pair. If NV_NOFREE is specified, value itself becomes the
value of the name-value pair np. Otherwise, a copy of the
value is stored as the value for np.
The nv_unset() function clears out the value and attributes
of the given name-value function but does not free the
name-value pair.
The following attributes can be associated with a name-value
pair:
NV_EXPORT: The export attribute.
NV_RDONLY: The readonly attribute.
NV_LTOU: Lower case characters are converted to upper
case characters.
NV_UTOL: Upper case characters are converted to lower
case characters.
NV_RJUST: Right justify and blank fill. This attri-
bute has an associated size that defines the string
length of the value.
NV_LJUST: Left justify and blank fill. This attribute
has an associated size that defines the string length
of the value.
NV_ZFILL: Without NV_LJUST, right justifies and fills
SunOS 5.10 Last change: 12 Feb 2003 4
Introduction to Library Functions NVAL(3)
with leading zeros. With NV_LJUST, 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.
NV_TAGGED: Indicates the tagged attribute.
NV_INTEGER: 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.
NV_DOUBLE: Used in conjunction with NV_INTEGER 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.
NV_EXPNOTE: Used in conjunction with NV_INTEGER and
NV_DOUBLE 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.
NV_BINARY: The name-value pair contains a buffer of
binary data and nv_size() is the number of bytes for
this data. By default the value will be represented by
the base64 encoding of the buffer. The NV_LJUST flag
may also be specified and causes the buffer size to be
fixed and data either truncated or filled with 0 bytes.
NV_REF: The name-value pair is a name reference vari-
able.
NV_NODISC: All discipline functions are ignored when
performing assignments and lookups.
The nv_isattr() function can test whether or not any of the
attributes given by flags is set. The nv_onattr() and
nv_offattr() functions turn attributes on or off respec-
tively. Only attributes that do not affect the value can be
set in this way. The nv_newattr() 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 size argument is needed
for attributes that require an additional argument such as
justifies variables. Changing the attribute may require
changing the value to agree with the new attributes. For an
array variable, the values for each of the subscripts will
be changed.
SunOS 5.10 Last change: 12 Feb 2003 5
Introduction to Library Functions NVAL(3)
The nv_isarray() function returns a non-zero value if the
specified name-value pair is an array.
The nv_scan() function is used to walk through all name-
value pairs in the dictionary given by dict. If the flags
variable contains the NV_NOSCOPE flag, then only the top
scope will be examined. The remaining flags will be used in
conjunction with mask to further restrict the walk. If mask
is non-zero, only the nodes for which nv_isattr(node,mask)
is equal to flags will be visited. If fn is non-zero, then
this function will be executed for each name-value pair in
the walk. The arguments to fn will be a pointer to the
name-value pair and the data pointer passed to nv_scan().
The number of elements visited will be returned.
The nv_clone() function is used make a copy of the contents
of name-value pair src to another name-value pair dest.
Disciplines provide a way to intercept the lookup and
assignment operations, to manage the creation of sub-
variables, and to extend the operations permitted on a
name-value pair. 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 Namfun_t and Namdisc_t. The
Namdisc_t 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:
size_t dsize;
void (*putval)(Namval_t*,const char*,int,Namfun_t*);
char *(*getval)(Namval_t*,Namfun_t*);
double (*getnum)(Namval_t*,Namfun_t*);
char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);
Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);
Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);
char *(*namef)(Namval_t*,Namfun_t*);
Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);
Namval_t *(*typef)(Namval_t*,Namfun_t*);
The Namfun_t type contains a member named disc which points
to a Namdisc_t structure. To create a discipline with addi-
tional user data, define a structure with an instance of
Namfun_t as the first element. An application must initial-
ize the Namfun_t portion of the structure to zero and then
set the disc field to point to the Namdisc_t structure. The
dsize field of the Namdisc_t structure must be the size of
this structure. A value of 0, indicates that there are no
additional fields and is equivalent to sizeof(Namfun_t). If
different instances of this structure uses different sizes,
then the size field in the Namfun_t can must be set to this
size and overrides the value in the Namdisc_t structure.
SunOS 5.10 Last change: 12 Feb 2003 6
Introduction to Library Functions NVAL(3)
When a variable is referenced by calling the nv_getval()
function, and the NV_NODISC attribute is not set, the get-
val() discipline function is called with a pointer to the
name-value pair, np, and a pointer to the discipline, fp.
Inside the getval() function, the nv_getv() function can be
called to get the value of the name-value pair that would
have resulted if the discipline were not used. The getnum()
discipline is called whenever a numerical value is needed
for the name-value pair np and the NV_NODISC attribute is
not set, The nv_getn() function can be called from within
the getnum() discipline to get the value that would have
resulted if there were no getnum() discipline.
The putval() discipline function is used to override the
assignment of values to a name-value pair. It is called
whenever a value is assigned with nv_putval() and the
NV_NODISC attribute is not set, or when a name-value pair is
unset with nv_unset(). When a name-value pair is unset,
putval() is called with value set to NULL. The nv_putv()
function is used within the putval() to perform the assign-
ment or unset that would have occurred if the discipline had
not been installed.
The createf() discipline function is called from nv_open()
or nv_create() when the name-value pair preceding a . is
found. This function is passed the name-value pointer plus
the remaining string and the current flags argument. The
createf() 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 the behavior will be the same as if an
invalid name had been given to nv_open(). The nv_create()
function may be called within the createf() discipline func-
tion to perform the action that would have occurred by an
earlier nv_open() function.
The setdisc() 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 varname.action to be defined. By
default, each name-value pair can have a get, set, and unset
discipline associated with it. Whenever a builtin or func-
tion whose name is of the form varname.action is defined or
is unset, and action is not get, set, or unset, the set-
disc() function is invoked with the same argument format as
nv_setdisc(). The argument f points to the name-value pair
associated with the function being defined, or NULL if the
function is being unset. If the given action a is not known
by this discipline, it should return the value returned by
calling nv_setdisc(np,a,f,fp) so that it can be searched for
in previously stacked disciplines. Otherwise, the setdisc()
function should save the function name-value pair pointer,
SunOS 5.10 Last change: 12 Feb 2003 7
Introduction to Library Functions NVAL(3)
and return a non-NULL value. The name-value pointer to the
function can be used to invoke the function at an applica-
tion defined point. If the action a is NULL, then f points
to an action name instead of a name-value pair pointer. The
setdisc() must return the name of the action that follows
the action name given by f. If f is also NULL, the name of
the first action must be returned. This allows an applica-
tion to get the list of valid discipline action names
allowed by a given name-value pair.
The nv_adddisc() function is a higher level function that
adds a setdisc discipline to the name-value pair that allows
shell level disciplines to be created for each of the name
specified in names.
The nv_discfun() 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 nv_adddisc() which can be returned with an argu-
ment of NV_DCADD.
The clonef() discipline function is called by nv_clone()
when making a copy of the Namfun_t 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 nv_clone(). It must return a
new instance of the Namfun_t* fp. If omitted, then memory
whose size is determinated by the size field of fp, if non-
zero, or fp->disc, will be allocated and copied from fp.
The namef() discipline function returns the name for this
name-value pair.
The nextf() is used for walking through the list of sub-
variables associated with this name-value pair. If the dic-
tionary argument is NULL, it must return the first sub-
variable. Otherwise, it must return the next sub-variable,
or NULL if there are no more variables.
A discipline is installed or removed with the nv_disc()
function. The following flags can be specified:
NV_FIRST: If fp is non-NULL, 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 np if not already present. Otherwise, the
top of the discipline stack is returned.
NV_LAST: If fp is non-NULL, 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 np if not already present. Otherwise,
SunOS 5.10 Last change: 12 Feb 2003 8
Introduction to Library Functions NVAL(3)
the bottom of the discipline stack is returned.
NV_POP: If fp is non-NULL and it is on the stack, it
is removed and fp is returned. If fp is non-NULL and
is not on the stack, NULL is returned. Otherwise, the
the top discipline is popped and returned.
NV_CLONE: If fp is non-NULL and it is on the stack, it
is replace by a copy created by malloc(3). The nofree
field is set to 0. The new discipline is returned.
Otherwise, NULL is returned.
0: If fp is non-NULL then it is equivalent to
NV_FIRST. Otherwise, it is equivalent to NV_POP.
The nv_hasdisc() function can be used to tell whether a dis-
cipline whose discipline functions are those defined in dp.
A pointer to this discipline is returned.
The nv_aindex() function returns the current index for the
indexed array given by the name-value pair pointer np. The
return value is negative if np refers to an associative
array.
The nv_setarray() function is used to create an associative
array from a name-value pair node. The function fun defines
the semantics of the associative array. Using fun equal to
nv_associative() implements the default associative array
semantics that are used with typeset -A. The function fun
will be called with third argument as follows:
NV_AINIT: This will be called at initialization. The
function you supply must return a pointer to a struc-
ture that contains the type Namarr_t as the first ele-
ment. All other calls receive this value as an argu-
ment.
NV_AFREE: This will be called after all elements of
the name-value pair have been deleted and the array is
to be freed.
NV_ADELETE: The current element should be deleted.
NV_ANEXT: This means that the array subscript should
be advanced to the next subscript. A NULL return indi-
cates that there are no more subscripts.
NV_ANAME: The name of the current subscript must be
returned.
NV_ACURRENT: Returns a pointer to a name-value pair
corresponding to the current subscript, or NULL if this
SunOS 5.10 Last change: 12 Feb 2003 9
Introduction to Library Functions NVAL(3)
array type doesn't create represent each element as a
name-value pair.
If np refers to an array, the nv_getsub() returns a pointer
to the name of the current subscript. Otherwise,
nv_getsub() returns NULL.
The nv_opensub() function returns a pointer to the name-
value pair corresponding to the current subscript in an
associative array. Note that the nv_close() function should
be called when the pointer is no longer needed.
The nv_putsub() function is used to set the subscript for
the next reference to np. If the name argument is not NULL,
it defines the value of the next subscript. The mode argu-
ment can contain one or more of the following flags:
ARRAY_ADD: Add the subscript if not found. Otherwise,
nv_putsub() returns NULL if the given subscript is not
found.
ARRAY_SCAN: Begin a walk through the subscripts start-
ing at the subscript given by name. If name is NULL
the walk is started from the beginning.
ARRAY_UNDEF: This causes any current scan to terminate
and leaves the subscript in an undefined state.
If ARRAY_ADD is not given and the subscript does not exist,
a NULL value is returned.
The nv_nextsub() 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.
The nv_setref() function makes the name-value pair np into a
reference to the variable whose name is given by the value
of np.
The nv_setvtree() function makes the name-value pair np into
a tree structured variable so that nv_getval() 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.
SEE ALSO
cdt(3) shell(3)
AUTHOR
David G. Korn (dgk@research.att.com).
SunOS 5.10 Last change: 12 Feb 2003 10
Generated by GNU enscript 1.6.4.
XWiki Enterprise 2.7.1.34853 - Documentation
Terms of Use
|
Privacy
|
Trademarks
|
Copyright Policy
|
Site Guidelines
|
Site Map
|
Help
Your use of this web site or any of its content or software indicates your agreement to be bound by these Terms of Use.
© 2012, Oracle Corporation and/or its affiliates.