.\" $Header: argtype.3,v 1.0 90/11/17 11:34:06 brad Exp $ .TH ARGTYPE 3 .SH NAME argtype \- argument type functions used by parseargs(3) .SH SYNOPSIS #include .PP .nf \s-1BOOL\s+1 argUsage( argdesc, argstr, copyf ); \s-1BOOL\s+1 argEnd( argdesc, argstr, copyf ); \s-1BOOL\s+1 argDummy( argdesc, argstr, copyf ); \s-1BOOL\s+1 argBool( argdesc, argstr, copyf ); \s-1BOOL\s+1 argSBool( argdesc, argstr, copyf ); \s-1BOOL\s+1 argUBool( argdesc, argstr, copyf ); \s-1BOOL\s+1 argTBool( argdesc, argstr, copyf ); \s-1BOOL\s+1 argChar( argdesc, argstr, copyf ); \s-1BOOL\s+1 argStr( argdesc, argstr, copyf ); \s-1BOOL\s+1 argInt( argdesc, argstr, copyf ); \s-1BOOL\s+1 argShort( argdesc, argstr, copyf ); \s-1BOOL\s+1 argLong( argdesc, argstr, copyf ); \s-1BOOL\s+1 argFloat( argdesc, argstr, copyf ); \s-1BOOL\s+1 argDouble( argdesc, argstr, copyf ); \s-1BOOL\s+1 listStr( argdesc, argstr, copyf ); \s-1void\s+1 listFree( arglist ); \s-1void\s+1 vecFree( argvec, type ); \s-1void\s+1 vecDeepFree( argvec, type ); \s-1ARGDESC\s+1 *argdesc; char *argstr; \s-1BOOL\s+1 copyf; ArgList *arglist; .fi .SH "DESCRIPTION" .PP Each of these converts a parameter value to the internal form, including validity checking. Their parameters and return values all behave similarly. One of these routines are called when an argunent of that particular type is matched by one of the argument parsing function in \fIparseargs\fP(3). When such an argument is matched, its argument translation routines is invoked and is passed (1) the address of the argument descriptor for the matched argument, (2) the possible argument string for that matched argument, and (3) a boolean filed that is \s-1TRUE\s+1 only if the second parameter points to temporary storage (indicating that some copying may need to be done instead of just pointing to the same object). Once the argument translation routine is invoked, it is responsible for converting the argument string to the desired internal form (perhaps a number), and assigning the resultant value to the \fIarg_valp(ad)\fP field of the argument descriptor (this includes handling any necessary (re)allocation if the matched argument has the \s-1ARGVEC\s+1 flag enabled). If the argument is an \s-1ARGVEC\s+1 or \s-1ARGLIST\s+1 then the routine is responsible for allocating any space, copying the arg-flags to the value-specific flags, and setting the \s-1ARGCOPYF\fP flag for the value if it needs to be allocated as well. .SH "RETURN VALUE" .IP "TRUE" 8 The conversion was successful and the entire value was used. .IP "FALSE" 8 The conversion failed. The reason for failure should be diagnosed using \fIusrerr\fP(3). .IP "-\fIN\fP" 8 The conversion was successful but only \fIN\fP characters of the value were used, the remaining characters may still match other arguments. .SH "PSEUDO-TYPES" .PP .I ArgUsage is used to specify an argument that causes the command usage to be printed. .I ArgDummy is used to force an item to show up in usage-messages but the item itself is never matched against any argumenmts from the command-line. .I ArgEnd is used by Amiga style command-lines to indicate an argument that forces all remaining arguments to be considered positional args. These three are dummy functions. The routines themselves do nothing of importance, we just need to have their addresses available for identification in the corresponding command-line styles. .SH "STRING-TYPES" .PP \fIArgStr\fP is one of the few argument translation routines that actually uses the \fIcopyf\fP flag. If \fIcopyf\fP is true then the string is duplicated. \fIArgStr\fP assigns the given string (or a copy of it) to the value referenced by \fIarg_valp(ad)\fP (unless the argument is a vector in which case the given string is appended to the end). \fIArgStr\fP ensures that the very last item in a vector of strings (the one accessed as \f4vec.array[ vec.count ]\fP) will always be \s-1NULL\s+1. .SH "CHARACTER-TYPES" .PP .I ArgChar assigns the given character to the value referenced by \fIarg_valp(ad)\fP (unless the argument is a vector in which case the given character is appended to the end). .I ArgChar ensures that the very last item in a vector of character (the one accessed as \f4vec.array[ vec.count ]\fP) will always be a \s-1NULL\s+1 byte so that the resulting vector may also be used as a \s-1NULL\s+1 terminated string. Unlike \fIargStr\fP, \fIargChar\fP will translate character escape sequences such as `\\n' and `\\012'. .SH "INTEGER-TYPES" .PP Each of these functions converts the given string to the desired integral type. The value may be specified as an octal number by specifying the first digit to be 0. Similarly, If the first two characters are `0x' then the number is treated as hexadecimal. .SH "FLOATING-POINT-TYPES" .PP Each of these functions converts the given string to the desired floating-point type. .SH "BOOLEAN-TYPES" .PP \fIArgBool\fP and \fIargSBool\fP set a boolean value (if no value is given). \fIArgUBool\fP unsets a boolean value (if no value is given). \fIArgTBool\fP toggles a boolean value (if no value is given). If a value is supplied to any of these routines, then the string is looked up in a table and assigned the corresponding value. If a value is supplied for an argument that was matched via its single character name and is part of the same argv element as the argument-name (so that both \fBARGKEYWORD\fP and \fBARGVALSEP\fP are not set), then only the first character of the value is used (unless it is not found in our table, in which case the value is ignored and the default action is taken). The table used for single-character-options is the following: .IP "`0' or `-'" The corresponding boolean flag is set to \s-1FALSE\s+1. .IP "`1' or `+'" The corresponding boolean flag is set to \s-1TRUE\s+1. .IP "`^' or `~'" The corresponding boolean flag is toggled. .PP The possible argument strings for long-options (keywords) are as follows (case-insensitive): .IP "``0'', ``-'', ``OFF'', or ``FALSE''" The corresponding boolean flag is set to \s-1FALSE\s+1. .IP "``1'', ``+'', ``ON'', or ``TRUE''" The corresponding boolean flag is set to \s-1TRUE\s+1. .SH LIST TYPES .PP The \fIlistStr\fP argument translation routine is only intended for use on behalf of arguments that have the \s-1ARGLIST\s+1 flag enabled. It will allocate space for a new node (and for the new string if \fIcopyf\fP is set) and append it to the end of the list. The argument-list may later be deallocated by invoking the function \fIlistFree\fP and passing it the address of the first item in the list. .PP \fIVecFree\fP is a macro that is used to deallocate argument-vectors. It will free the array and flags fields of a vector, set them to \s-1NULL\s+1, and set the count field to zero. \fIVecDeepFree\fP is a macro that is similar to \fIvecFree\fP but will additionally look at each item in the array; any component of the array that had \s-1ARGCOPYF\s+1 enabled will also be deallocated. Both macros are given the vector structure to free followed by the type of the items in the vector. .SH SEE ALSO .IR parseargs (3), .IR parseargs (1),