1N/A.TH NVAL 3 "12 Feb 2003"
1N/A.ta .8i 1.6i 2.4i 3.2i 4.0i
1N/ANamval_t *nv_open(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP);
1N/ANamval_t *nv_create(const char *\fIname\fP, Dt_t *\fIdict\fP, int \fIflags\fP, Namfun_t *\fIfp\fP);
1N/ANamval_t *nv_namptr(void *\fIptr\fP, int \fIindx\fP);
1N/Avoid nv_close(Namval_t *\fInp\fP);
1N/Avoid nv_delete(Namval_t *\fInp\fP, Dt_t *\fIdict\fP, int \fInofree\fP);
1N/A.SS "GETTING AND SETTING VALUES"
1N/Achar *nv_getval(Namval_t *\fInp\fP);
1N/ASfdouble_t nv_getnum(Namval_t *\fInp\fP);
1N/Achar *nv_name(Namval_t *\fInp\fP);
1N/Avoid nv_putval(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP);
1N/Avoid nv_unset(Namval_t *\fInp\fP, int \fIflags\fP);
1N/Aint nv_clone(Namval_t *\fIsrc\fP, Namval_t *\fIdest\fP, int \fIflags\fP);
1N/A.SS "ATTRIBUTES AND SIZE"
1N/Aint nv_isnull(Namval_t *\fInp\fP);
1N/Aint nv_setsize(Namval_t *\fInp\fP, int \fIsize\fP);
1N/Aint nv_size(Namval_t *\fInp\fP);
1N/Aunsigned nv_isattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
1N/ANamfun_t *nv_isvtree(Namval_t *\fInp\fP);
1N/Aunsigned nv_onattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
1N/Aunsigned nv_offattr(Namval_t *\fInp\fP, unsigned \fIflags\fP);
1N/Avoid nv_newattr(Namval_t *\fInp\fP, unsigned \fIflags\fP, int \fIsize\fP);
1N/Aunsigned nv_isarray(Namval_t *\fInp\fP);
1N/ANamarr_t *nv_setarray(Namval_t *\fInp\fP,void*(*\fIfun\fP)(Namval_t*,const char*,int));
1N/ANamarr_t *nv_arrayptr(Namval_t *\fInp\fP);
1N/ANamval_t *nv_putsub(Namval_t *\fInp\fP, char *\fIname\fP, long \fImode\fP);
1N/ANamval_t *nv_opensub(Namval_t *\fInp\fP);
1N/Avoid nv_setvec(Namval_t *\fInp\fP, int \fIappend\fP, int \fIargc\fP, char *\fIargv\fP[]);
1N/Achar *nv_getsub(Namval_t *\fInp\fP);
1N/Aint nv_nextsub(Namval_t *\fInp\fP);
1N/Aint nv_aindex(Namval_t *\fInp\fP);
1N/ANamfun_t *nv_disc(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP, int \fIflags\fP);
1N/ANamfun_t *nv_hasdisc(Namval_t *\fInp\fP, const Namdisc_t *\fIdp\fP);
1N/Achar *nv_getv(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
1N/ASfdouble_t nv_getn(Namval_t *\fInp\fP, Namfun_t *\fIfp\fP);
1N/Avoid nv_putv(Namval_t *\fInp\fP, const char *\fIval\fP, int \fIflags\fP, Namfun_t *\fIfp\fP);
1N/Achar *nv_setdisc(Namval_t *\fInp\fP, const char *\fIa\fP, Namval_t *\fIf\fP, Namfun_t *\fIfp\fP);
1N/Achar *nv_adddisc(Namval_t *\fInp\fP, const char **\fInames\fP);
1N/Aconst Namdisc_t *nv_discfun(int \fIwhich\fP);
1N/ANamval_t *nv_type(Namval_t *\fInp\fP);
1N/Aint *nv_settype(Namval_t *\fInp\fP, Namval_t *\fItp\fP, int \fIflags\fP);
1N/ANamval_t *nv_mkinttype(char *\fIname\fP, size_t \fIsz\fP, int \fIus\fP, const char *\fIstr\fP, Namdisc_t *\fIdp\fP);
1N/Avoid nv_addtype(Namval_t *\fInp\fP, const char *\fIstr\fP, Optdisc_t* *\fIop\fP, size_t \fIsz\fP);
1N/A.SS "MISCELLANEOUS FUNCTIONS"
1N/Aint nv_scan(Dt_t *\fIdict\fP, void(*\fIfn\fP)(Namval_t*,void*), void *\fIdata\fP, int \fImask\fP, int \fIflags\fP);
1N/ADt_t *nv_dict(Namval_t *\fInp\fP);
1N/Avoid nv_setvtree(Namval_t *\fInp\fP);
1N/Avoid nv_setref(Namval_t *\fInp\fP, Dt_t *\fIdp\fP, int \fIflags\fP);
1N/ANamval_t *nv_lastdict(void);
1N/A\fINval\fP is a library of functions for interacting with name-value
1N/Apairs as used in \f5ksh\fP.
1N/AIt is built on top the container dictionary type library facility
1N/Ain \f5libcdt\fP. (See cdt(3)).
1N/AEach name-value pair is represented by a
1N/Atype named \f5Namval_t\fP.
1N/AA \f5Namval_t\fP contains the name, value and
1N/Aattributes of a variable.
1N/ASome attributes can have an associated number that
1N/Arepresents the field width, arithmetic base, or precision.
1N/AAdditionally, each name-value pair can be associated with
1N/Aone or more processing disciplines that affect
1N/AThe function \f5nv_open()\fP returns a pointer to a name-value
1N/Apair corresponding to the given \fIname\fP.
1N/AIt can also assign a value and give attributes to a name-value pair.
1N/AThe argument \fIdict\fP defines the dictionary to search.
1N/AA \f5NULL\fP value causes the shell global variable dictionary to be searched.
1N/AThe \fIflags\fP argument consists of the bitwise-or of zero or more
1N/Aof the attributes listed later and zero or more of the following:
1N/AAn invalid variable name causes an error.
1N/AA variable name that is not an identifier causes an error.
1N/AThe \fIname\fP argument can contain an assignment.
1N/AThe \fIname\fP argument cannot contain a subscript.
1N/ADo not follow references when finding the name-value pair.
1N/AThe name-value pair will not be added if it doesn't exist.
1N/AInstead, a \f5NULL\fP pointer will be returned.
1N/AOnly the top level scope is used.
1N/AJust return \f5NULL\fP when an error occurs.
1N/ABy default an error message is displayed and the current command
1N/AIf a name-value pair by this name does not already exist, it is
1N/Acreated unless \fIflags\fP contains the \f5NV_NOADD\fP flag.
1N/AIf \f5NV_VARNAME\fP, \f5NV_IDENTIFIER\fP and \f5NV_ASSIGN\fP are
1N/Aall not specified, then no validity check is performed on the \fIname\fP
1N/Aargument and no further processing is performed.
1N/AOtherwise, if \f5NV_ASSIGN\fP is specified, then the characters up
1N/Ato the first \f5=\fP or \f5+=\fP are used to find the name-value pair,
1N/Aand the characters after the \f5=\fP are used to define
1N/Athe value that will be assigned to this name-value pair.
1N/AIf \fIname\fP does not contain an \f5=\fP, than no assignment
1N/AIf the first identifier in \fIname\fP is a reference and is not
1N/Apreceded by a \fB.\fP,
1N/Ait will be replaced by the value of the reference
1N/Ato find the name of a variable.
1N/AUnless \fIflags\fP contains the \f5NV_NOREF\fP flag,
1N/Aif the name-value pair give by \fIname\fP has the \f5NV_REF\fP
1N/Aattribute, it will be replaced by the variable whose name
1N/Ais the value of this name-value pair.
1N/AIf \f5NV_ASSIGN\fP is set in the \fIflags\fP argument,
1N/Athe \fIname\fP variable can contain an \f5=\fP
1N/Aand a value that will be assigned to the name-value pair.
1N/AAny attributes appearing in the \fIflags\fP argument
1N/Awill be applied to the name-value pair after any value is assigned.
1N/AIt is possible for an application to create additional dictionaries
1N/Awith the cdt library and associate them with name-value pairs.
1N/AThe \f5nv_dict()\fP function returns the dictionary associated with
1N/Athe specified name-value pair, or if no dictionary was specified,
1N/A\f5NULL\fP is returned.
1N/AThe \f5nv_lastdict()\fP function returns a pointer the the
1N/Aname-value pair that contains
1N/Athe last dictionary searched on the previous \f5nv_open()\fP.
1N/AName-value pairs can also be allocated without belonging to
1N/Aa dictionary. They will typically be looked up by a \fIcreate\fP
1N/Adiscipline associated with a parent node. In this case the
1N/Anode size will be \f5NV_MINSZ\fP and \fIn\fP nodes can be allocated
1N/Avial \f5calloc(5NV_MINSZ,\fIn\fP)\fP(3).
1N/AThe \f5nv_namptr\fP function can be used on the pointer returned by
1N/A\f5calloc\fP along with the element number to return the
1N/AEach of these nodes must be given the \f5NV_MINIMAL\fP attributes.
1N/AThe \f5nv_close()\fP indicates that the pointer returned by
1N/A\f5nv_open()\fP or \f5nv_opensub()\fP will not be referenced again. If the
1N/Aname-value pair is unset, and not referenced elsewhere,
1N/Athe name-value pair may be freed.
1N/AThe \f5nv_delete()\fP function will remove the node \fInp\fP from
1N/Athe dictionary \fIdict\fP. Unless \fInofree\fP is non-zero, the
1N/Anode \fInp\fP will also be freed.
1N/AThe \f5nv_name()\fP function returns the name of the given name-value
1N/AThe \f5nv_setsize()\fP function returns the size of the field for
1N/Ajustified variables, the arithmetic base for integer variables,
1N/Aand the precision or number of places after the decimal point
1N/Afor floating point variables. If \fIsize\fP is greater than or
1N/Aequal to zero, the current size is changed to this value.
1N/AThe \f5nv_size()\fP function is equivalent to \f5nv_setsize()\fP
1N/Awith the second argument negative.
1N/AThe \f5nv_getval()\fP function returns the value of the given
1N/Aname-value pair as a string. A \f5NULL\fP return value indicates
1N/Athat the name-value pair is unset.
1N/AThe \f5nv_getnum()\fP function returns the value of the given
1N/Aname-value pair as a double precision number using the \f5Sfio\fP
1N/Alibrary (See Sfio(3)) type \f5Sfdouble_t\fP.
1N/AFor name-value pairs without the \f5NV_INTEGER\fP attribute,
1N/Athe string value is evaluated as an arithmetic expression to
1N/Aarrive at a numerical value.
1N/AThe \f5nv_putval()\fP function is used to assign a \fIvalue\fP to
1N/Athe name-value pair \fInp\fP.
1N/AThe \fIflags\fP argument consists zero or more of the bitwise-or
1N/Aof \f5NV_LONG\fP, \f5NV_SHORT\fP, \f5NV_DOUBLE\fP, \f5NV_INTEGER\fP,
1N/A\f5NV_RDONLY\fP, \f5NV_REF\fP, \f5NV_BINARY\fP, and \f5NV_NOFREE\fP.
1N/AThe presence of \f5NV_RDONLY\fP allows the assignment to occur
1N/Aeven if the name-value pair has the \f5NV_RDONLY\fP attribute.
1N/AThe presence of \f5NV_INTEGER\fP indicates that the \fIvalue\fP
1N/Aargument is actually a pointer to a numerical type.
1N/ABy default this type is \f5long\fP, but can be modified with
1N/A\f5NV_LONG\fP, \f5NV_SHORT\fP, and \f5NV_DOUBLE\fP
1N/Ato represent \f5long long\fP, \f5short\fP, \f5double\fP, \f5long double\fP,
1N/AThe presence of \f5NV_REF\fP indicates that the \fIvalue\fP
1N/Aargument is actually a pointer to a name-value pair
1N/Aand \f5np\fP should become a reference to this name-value pair.
1N/AIf \f5NV_NOFREE\fP is specified, \fIvalue\fP itself becomes
1N/Athe value of the name-value pair \fInp\fP.
1N/AOtherwise, a copy of the value is stored
1N/Aas the value for \fInp\fP.
1N/AThe \f5nv_unset()\fP function clears out the value and attributes
1N/Aof the given name-value function but does not free the name-value
1N/AIf called from the \f5putval\fP discipline function, use the \fIflags\fP
1N/Aargument as the \fIflags\fP to \f5nv_unset()\fP. Otherwise, use 0.
1N/AThe following attributes can be associated with a name-value pair:
1N/AThe export attribute.
1N/AThe readonly attribute.
1N/ALower case characters are converted to upper case characters.
1N/AUpper case characters are converted to lower case characters.
1N/ARight justify and blank fill.
1N/AThis attribute has an associated size that defines the
1N/Astring length of the value.
1N/ALeft justify and blank fill.
1N/AThis attribute has an associated size that defines the
1N/Astring length of the value.
1N/AWithout \f5NV_LJUST\fP, right justifies and fills with leading zeros.
1N/AWith \f5NV_LJUST\fP, left justify and strip leading zeros.
1N/ALeft justify and blank fill.
1N/AThis attribute has an associated size that defines the
1N/Astring length of the value.
1N/AIndicates the tagged attribute.
1N/ACauses value to be represented by a number.
1N/AThis attribute has an associated number that defines the
1N/Aarithmetic base to be used when the value is expanded as a string.
1N/AUsed in conjunction with \f5NV_INTEGER\fP to cause value
1N/Ato be stored as a double precision floating point number.
1N/AThis attribute has an associated number that defines the
1N/Anumber of places after the decimal point to be used when
1N/Athe value is expanded as a string.
1N/AUsed in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to
1N/Acause the value to be represented in scientific notation when
1N/Aexpanded as a string.
1N/AThis attribute has an associated number that defines the
1N/Athe precision of the mantissa.
1N/AUsed in conjunction with \f5NV_INTEGER\fP and \f5NV_DOUBLE\fP to
1N/Acause the value to be represented in C99 %a format when expanded as
1N/AThe name-value pair contains a buffer of binary data and \f5nv_size()\fP
1N/Ais the number of bytes for this data. By default the value
1N/Awill be represented by the base64 encoding of the buffer.
1N/AThe \f5NV_LJUST\fP flag may also be specified and causes the buffer
1N/Asize to be fixed and data either truncated or filled with \f50\fP bytes.
1N/AThe name-value pair is a name reference variable.
1N/AThe name-value pair node is not embedded in a dictionary
1N/Aand is minimal size, \f5NV_MINSZ\fP.
1N/AAll discipline functions are ignored when performing assignments
1N/AThe \f5nv_isattr()\fP function can test whether or not any of
1N/Athe attributes given by \fIflags\fP is set.
1N/AThe \f5nv_onattr()\fP and \f5nv_offattr()\fP functions turn attributes
1N/Aon or off respectively. Only attributes that do not affect the
1N/Avalue can be set in this way.
1N/AThe \f5nv_newattr()\fP function can be used to change the
1N/Aattributes and size of the given name-value pair which may result
1N/Ain the value being changed to conform to the new attributes and size.
1N/AThe \fIsize\fP argument is needed for attributes that require
1N/Aan additional argument such as justifies variables.
1N/AChanging the attribute may require changing the value
1N/Ato agree with the new attributes.
1N/AFor an array variable, the values for each of the
1N/Asubscripts will be changed.
1N/AThe \f5nv_isvtree()\fP function returns a pointer to the compound
1N/Avariable discipline if the node \fInp\fP is a compound variable
1N/Aor \f5NULL\fP otherwise.
1N/AThe \f5nv_isarray()\fP function returns a non-zero value if the specified
1N/Aname-value pair is an array.
1N/AThe \f5nv_scan()\fP function is used to walk through
1N/Aall name-value pairs in the dictionary given by \fIdict\fP.
1N/AIf the \f5flags\fP variable contains the \f5NV_NOSCOPE\fP
1N/Aflag, then only the top scope will be examined.
1N/AThe remaining flags will be used in conjunction with \fImask\fP
1N/Ato further restrict the walk.
1N/AIf \fImask\fP is non-zero, only the nodes for which
1N/A\f5nv_isattr(\fP\fInode\fP\f5,\fP\fImask\fP\f5)\fP
1N/Ais equal to \fIflags\fP will be visited.
1N/AIf \fIfn\fP is non-zero, then this function will be executed
1N/Afor each name-value pair in the walk.
1N/AThe arguments to \fIfn\fP will be a pointer to the name-value pair
1N/Aand the \fIdata\fP pointer passed to \f5nv_scan()\fP.
1N/AThe number of elements visited will be returned.
1N/AThe \f5nv_clone()\fP function is used make a copy of the contents of
1N/Aname-value pair \fIsrc\fP to another name-value pair \fIdest\fP.
1N/ADisciplines provide a way to
1N/Aintercept the lookup and assignment operations,
1N/Ato manage the creation of sub-variables,
1N/Aand to extend the operations permitted on a name-value pair.
1N/AA discipline consists of a set of one or more functions and related
1N/Adata that are used to override and extend the operations
1N/Aon a name-value pair.
1N/AA discipline is defined by the types
1N/A\f5Namfun_t\fP and \f5Namdisc_t\fP.
1N/AThe \f5Namdisc_t\fP is not modified by any of these functions and
1N/Acan therefore be shared by several name-value pairs.
1N/AIt contains following public fields in the order listed:
1N/A \f5void (*putval)(Namval_t*,const char*,int,Namfun_t*);\fP
1N/A \f5char *(*getval)(Namval_t*,Namfun_t*);\fP
1N/A \f5double (*getnum)(Namval_t*,Namfun_t*);\fP
1N/A \f5char *(*setdisc)(Namval_t*,const char*,Namval_t*,Namfun_t*);\fP
1N/A \f5Namval_t *(*createf)(Namval_t*,const char*,Namfun_t*);\fP
1N/A \f5Namfun_t *(*clonef)(Namval_t*,Namval_t*,int,Namfun_t*);\fP
1N/A \f5char *(*namef)(Namval_t*,Namfun_t*);\fP
1N/A \f5Namval_t *(*nextf)(Namval_t*,Dt_t*,Namfun_t*);\fP
1N/A \f5Namval_t *(*typef)(Namval_t*,Namfun_t*);\fP
1N/AThe \f5Namfun_t\fP type contains a member named
1N/A\f5disc\fP which points to a \f5Namdisc_t\fP structure.
1N/ATo create a discipline with additional user data,
1N/Adefine a structure with an instance of \f5Namfun_t\fP
1N/Aas the first element.
1N/AAn application must initialize the \f5Namfun_t\fP portion of
1N/Athe structure to zero and then set the \fIdisc\fP field to point
1N/Ato the \f5Namdisc_t\fP structure.
1N/AThe \f5dsize\fP field of the \f5Namdisc_t\fP structure must be
1N/Athe size of this structure. A value of 0,
1N/Aindicates that there are no additional fields and is equivalent
1N/Ato \f5sizeof(Namfun_t)\fP.
1N/AIf different instances of this structure uses different sizes, then
1N/Athe \f5size\fP field in the \f5Namfun_t\fP can must be set to
1N/Athis size and overrides the value in the \f5Namdisc_t\fP structure.
1N/AWhen a variable is referenced by calling the \f5nv_getval()\fP function,
1N/Aand the \f5NV_NODISC\fP attribute is not set,
1N/Athe \f5getval()\fP discipline function is called with a pointer
1N/Ato the name-value pair, \fInp\fP, and a pointer to the discipline,
1N/AInside the \f5getval()\fP function, the \f5nv_getv()\fP function
1N/Acan be called to get the value of the name-value pair that
1N/Awould have resulted if the discipline were not used.
1N/AThe \f5getnum()\fP discipline is called whenever a numerical
1N/Avalue is needed for the name-value pair \fInp\fP
1N/Aand the \f5NV_NODISC\fP attribute is not set,
1N/AThe \f5nv_getn()\fP function can be called from within
1N/Athe \f5getnum()\fP discipline to get the value that would
1N/Ahave resulted if there were no \f5getnum()\fP discipline.
1N/AThe \f5putval\fP\f5()\fP discipline function is used to
1N/Aoverride the assignment of values
1N/Ato a name-value pair.
1N/AIt is called whenever a value is assigned with \f5nv_putval()\fP
1N/Aand the \f5NV_NODISC\fP attribute is not set,
1N/Aor when a name-value pair is unset with \f5nv_unset()\fP.
1N/AWhen a name-value pair is unset, \f5putval\fP\f5()\fP
1N/Ais called with \fIvalue\fP set to \f5NULL\fP.
1N/AThe \f5nv_putv()\fP function is used within the \f5putval()\fP
1N/Ato perform the assignment or unset that would have occurred
1N/Aif the discipline had not been installed.
1N/AThe \f5createf()\fP discipline function is called from
1N/A\f5nv_open()\fP or \f5nv_create()\fP when the name-value pair preceding a
1N/AThis function is passed the name-value pointer plus the remaining string and
1N/Athe current \fIflags\fP argument.
1N/AThe \f5createf()\fP discipline function
1N/Amust return the created name-value pair, otherwise the default action
1N/AIf the name-value pair that is returned is the same as the
1N/Aone given, then the the behavior will be the same as if
1N/Aan invalid name had been given to \f5nv_open()\fP.
1N/AThe \f5nv_create()\fP function may be called within
1N/Athe \f5createf()\fP discipline function
1N/Ato perform the action that would have occurred
1N/Aby an earlier \f5nv_open()\fP function.
1N/AThe \f5setdisc()\fP discipline function is used
1N/Ato extend the set of available shell level discipline functions
1N/Aassociated with a name-value pair by allowing
1N/Abuiltins or functions whose name is of the
1N/Aform \fIvarname\fP\f5.\fP\fIaction\fP to be defined.
1N/ABy default, each name-value pair can have a \f5get\fP,
1N/A\f5set\fP, and \f5unset\fP discipline associated with it.
1N/AWhenever a builtin or function whose name is of the
1N/Aform \fIvarname\fP\f5.\fP\fIaction\fP is defined or is unset,
1N/Aand \fIaction\fP is not \f5get\fP,
1N/A\f5set\fP, or \f5unset\fP, the \fIsetdisc\fP\f5()\fP function is invoked
1N/Awith the same argument format as \f5nv_setdisc\fP\f5()\fP.
1N/AThe argument \fIf\fP points to the name-value pair associated
1N/Awith the function being defined, or \f5NULL\fP if the function is
1N/AIf the given action \fIa\fP is not known by this discipline,
1N/Ait should return the value returned by calling
1N/A\f5nv_setdisc(\fP\fInp\fP\f5,\fP\fIa\fP\f5,\fP\fIf\fP\f5,\fP\fIfp\fP\f5)\fP
1N/Aso that it can be searched for in previously stacked disciplines.
1N/AOtherwise, the \fIsetdisc\fP\f5()\fP function should save the function
1N/Aname-value pair pointer, and return a non-\f5NULL\fP value.
1N/AThe name-value pointer to the function can be used to invoke
1N/Athe function at an application defined point.
1N/AIf the action \fIa\fP is \f5NULL\fP, then \fIf\fP points to
1N/Aan action name instead of a name-value pair pointer.
1N/AThe \fIsetdisc\fP\f5()\fP must return the
1N/Aname of the action that follows the action name given by
1N/A\fIf\fP. If \fIf\fP is also \f5NULL\fP, the name of the first action
1N/AThis allows an application to get the list of valid discipline
1N/Aaction names allowed by a given name-value pair.
1N/AThe \f5nv_adddisc()\fP function is a higher level function that
1N/Aadds a \fIsetdisc\fP discipline to the name-value pair that allows
1N/Ashell level disciplines to be created for each of the name specified
1N/AThe \f5nv_discfun()\fP function can be used to get a pointer to
1N/Adiscipline functions that are provided by the library.
1N/ACurrently, the only one that is provided is the ones used to
1N/Aimplement \f5nv_adddisc()\fP which can be returned with an
1N/Aargument of \f5NV_DCADD\fP.
1N/AThe \f5clonef()\fP discipline function is called by \f5nv_clone()\fP
1N/Awhen making a copy of the \f5Namfun_t\fP discipline to the new node.
1N/AThe first argument is the original node, the second argument is
1N/Athe new node, and the third argument is the flags that were passed
1N/Adown to \f5nv_clone()\fP.
1N/AIt must return a new instance of the \f5Namfun_t*\fP \f5fp\fP.
1N/AIf omitted, then memory whose size is determinated by the \f5size\fP
1N/Afield of \f5fp\fP, if non-zero, or \f5fp->disc\fP, will be allocated
1N/Aand copied from \f5fp\fP.
1N/AThe \f5namef()\fP discipline function returns the name for this name-value pair.
1N/AThe \f5nextf()\fP is used for walking through the list of sub-variables
1N/Aassociated with this name-value pair. If the dictionary argument is
1N/A\f5NULL\fP, it must return the first sub-variable. Otherwise,
1N/Ait must return the next sub-variable, or \f5NULL\fP if there are
1N/AA discipline is installed or removed with the
1N/A\f5nv_disc()\fP function.
1N/AThe following flags can be specified:
1N/AIf \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the top
1N/Aof the stack or pushed onto the top of the stack of disciplines
1N/Aassociated with the given name-value
1N/Apair \fInp\fP if not already present.
1N/AOtherwise, the top of the discipline stack is returned.
1N/AIf \fIfp\fP is non-\f5NULL\fP, the discipline is moved to the bottom
1N/Aof the stack or pushed onto the bottom of the stack of disciplines
1N/Aassociated with the given name-value
1N/Apair \fInp\fP if not already present.
1N/AOtherwise, the bottom of the discipline stack is returned.
1N/AIf \fIfp\fP is non-\f5NULL\fP and it is on the stack,
1N/Ait is removed and \fIfp\fP is returned. If \fIfp\fP is non-\f5NULL\fP
1N/Aand is not on the stack, \f5NULL\fP is returned.
1N/AOtherwise, the the top discipline is popped
1N/AIf \fIfp\fP is non-\f5NULL\fP and it is on the stack,
1N/Ait is replace by a copy created by \f5malloc\fP(3).
1N/AThe \f5nofree\fP field is set to \f50\fP.
1N/AThe new discipline is returned.
1N/AOtherwise, \f5NULL\fP is returned.
1N/AIf \fIfp\fP is non-\f5NULL\fP then it is equivalent to \f5NV_FIRST\fP.
1N/AOtherwise, it is equivalent to \f5NV_POP\fP.
1N/A\f5nv_hasdisc()\fP function can be used to tell whether a discipline
1N/Awhose discipline functions are those defined in \fIdp\fP.
1N/AA pointer to this discipline is returned.
1N/AThe \f5nv_aindex()\fP function returns
1N/Athe current index for
1N/Athe indexed array given by the name-value pair pointer \fInp\fP.
1N/AThe return value is negative if \fInp\fP refers to
1N/Aan associative array.
1N/AThe \f5nv_setarray()\fP function is used to create an associative array
1N/Afrom a name-value pair node.
1N/AThe function \fIfun\fP defines the semantics of the associative
1N/AUsing \fIfun\fP equal to \f5nv_associative()\fP implements the default
1N/Aassociative array semantics
1N/Athat are used with \f5typeset\ -A\fP.
1N/AThe function \fIfun\fP will be called with third argument as follows:
1N/AThis will be called at initialization.
1N/AThe function you supply must return a pointer to a structure
1N/Athat contains the type \f5Namarr_t\fP as the first element.
1N/AAll other calls receive this value as an argument.
1N/AThis will be called after all elements of the name-value pair have been
1N/Adeleted and the array is to be freed.
1N/AThe current element should be deleted.
1N/AThis means that the array subscript should be advanced to the
1N/Anext subscript. A \f5NULL\fP return indicates that there are
1N/AThe name of the current subscript must be returned.
1N/AReturns a pointer to a name-value pair corresponding to the
1N/Acurrent subscript, or \f5NULL\fP if this array type doesn't
1N/Acreate represent each element as a name-value pair.
1N/ASet the current subscript to the name-value pair passed in
1N/Aas the second argument.
1N/AIf \fInp\fP refers to an array,
1N/A\f5nv_arrayptr()\fP returns a pointer to
1N/Athe array discipline structure \f5Namarr_t\fP.
1N/AOtherwise \f5nv_arrayptr()\fP returns \f5NULL\fP.
1N/AIf \fInp\fP refers to an array,
1N/Athe \f5nv_getsub()\fP returns a pointer to
1N/Athe name of the current subscript.
1N/AOtherwise, \f5nv_getsub()\fP
1N/AThe \f5nv_opensub()\fP function returns
1N/Aa pointer to the name-value pair corresponding
1N/Ato the current subscript in an associative array.
1N/ANote that the \f5nv_close()\fP function should be called
1N/Awhen the pointer is no longer needed.
1N/AThe \f5nv_putsub()\fP function is used to
1N/Aset the subscript for the next reference to \f5np\fP.
1N/AIf the \f5name\fP argument is not \f5NULL\fP,
1N/Ait defines the value of the next subscript.
1N/AThe \f5mode\fP argument can contain one or more of the following flags:
1N/AAdd the subscript if not found.
1N/AOtherwise, \f5nv_putsub()\fP returns \f5NULL\fP if the
1N/Agiven subscript is not found.
1N/ABegin a walk through the subscripts starting at the subscript
1N/Agiven by \f5name\fP. If \f5name\fP is \f5NULL\fP
1N/Athe walk is started from the beginning.
1N/AThis causes any current scan to terminate and leaves the
1N/Asubscript in an undefined state.
1N/AIf \f5ARRAY_ADD\fP is not given and the subscript
1N/Adoes not exist, a \f5NULL\fP value is returned.
1N/AThe \f5nv_nextsub()\fP function is used to advance to the
1N/AIt returns 0 if there are no more subscripts or if called
1N/AThe \f5nv_setref()\fP function makes the name-value pair \f5np\fP
1N/Ainto a reference to the variable whose name is given by
1N/Athe value of \f5np\fP. The \f5nv_open()\fP open function is
1N/Acalled with this name, the dictionary given by \f5dp\fP,
1N/Aand the \f5flags\fP argument.
1N/AA \f5NULL\fP value causes the shell global variable dictionary to be searched.
1N/AThe \f5nv_setvtree()\fP function makes the name-value pair \f5np\fP
1N/Ainto a tree structured variable so that \f5nv_getval()\fP
1N/Awill return a string containing all the names and values of
1N/Achildren nodes in a format that can be used in
1N/Aa shell compound assignment.
1N/AThe \f5nv_type()\fP function returns a name_value pair pointer
1N/Athat contains the type definition for the specified name-value pair.
1N/AThe \fInvname\fP field contains the name for the type.
1N/AThe \f5nv_settype()\fP function converts the name-value pair
1N/Agiven by \fInp\fP into the type given by \fItp\fP.
1N/AThe \f5nv_addtype()\fP function adds the name of the type given by
1N/A\fInp\fP to the list of declaration built-ins. The \fIstr\fP
1N/Aargument contains the string used by \f5optget\fP(3) to generate
1N/Athe man page and process the options. The \fIop\fP argument
1N/Aspecifies the callback discipline used by \f5optget\fP(3) and
1N/A\fIsz\fP specifies the size of the callback information so
1N/Athat the discipline \fBoptget\fP(3) can be extended with private
1N/Adata used by the callback function.
1N/AThe \f5nv_mkinttype()\fP function creates named integer types
1N/Aof the specified \fIname\fP. The \fIsize\fP parameter is the size
1N/Ain bytes of the integer variable and \fIus\fP is non-zero
1N/Afor unsigned integer types. If \fIdp\fP is specified then integer
1N/Avariables of this type will all use this discipline.
1N/ADavid G. Korn (dgk@research.att.com).