834 lines
28 KiB
Plaintext
834 lines
28 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@c %**start of header
|
|
@setfilename argv.info
|
|
@settitle Argv Tutorial
|
|
@c %**end of header
|
|
|
|
@c ================================================================
|
|
@c This file has the new style title page commands.
|
|
@c Also, it uses `@@include' files instead of `@@input' files.
|
|
|
|
@c Run using special version of `texinfo.tex'.
|
|
|
|
@c Also, run `makeinfo' rather than `texinfo-format-buffer'.
|
|
@c ================================================================
|
|
|
|
@c ================================================================
|
|
@c $Id$
|
|
@c ================================================================
|
|
|
|
@ifinfo
|
|
This file is an introduction to the Argv library which handles the
|
|
process of command-line arguments.
|
|
|
|
Copyright 1992 to 1998 by Gray Watson.
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries a copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
|
|
@end ignore
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
chapter entitled ``Copying'' are included exactly as in the original,
|
|
and provided that the entire resulting derived work is distributed under
|
|
the terms of a permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that the chapter entitled ``Copying'' may be included in a
|
|
translation approved by the author instead of in the original English.
|
|
@end ifinfo
|
|
|
|
@titlepage
|
|
@title Argv Library
|
|
@subtitle Version 2.4.0
|
|
@subtitle October 1998
|
|
@author Gray Watson
|
|
|
|
@page
|
|
Copyright 1992 to 1998 by Gray Watson.
|
|
|
|
Published by Gray Watson
|
|
|
|
Permission is granted to make and distribute verbatim copies of this
|
|
manual provided the copyright notice and this permission notice are
|
|
preserved on all copies.
|
|
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided also that the
|
|
chapter entitled ``Copying'' are included exactly as in the original,
|
|
and provided that the entire resulting derived work is distributed under
|
|
the terms of a permission notice identical to this one.
|
|
|
|
Permission is granted to copy and distribute translations of this manual
|
|
into another language, under the above conditions for modified versions,
|
|
except that the chapter entitled ``Copying'' may be included in a
|
|
translation approved by the author instead of in the original English.
|
|
@end titlepage
|
|
|
|
@node Top, Copying, (dir), (dir)
|
|
@top Argv Library
|
|
|
|
@ifinfo
|
|
Version 2.4.0 -- October 1998
|
|
@end ifinfo
|
|
|
|
@cindex introduction
|
|
@cindex author
|
|
|
|
The argv library has been designed to handle the argument processing
|
|
needs of most Unix software and to provide a consistent usage framework
|
|
for user applications.
|
|
|
|
The library is reasonably portable having been run successfully on at
|
|
least the following operating systems: AIX, BSDI, DG/UX, FreeBSD, HPUX,
|
|
Irix, Linux, MS-DOG, NeXT, OSF, Solaris, SunOS, Ultrix, Unixware, and
|
|
even Unicos on a Cray Y-MP.
|
|
|
|
The package includes the library, configuration scripts, shell-script
|
|
utility application, test program, and extensive documentation (text,
|
|
texi, info, ps). Documentation is available online at URL
|
|
@code{http://www.letters.com/argv/}.
|
|
|
|
The library is available via ftp from @samp{ftp.letters.com} in the
|
|
@file{/src/argv} directory. @xref{How To Get}. I can be reached via my
|
|
web page @samp{http://www.letters.com/~gray/} with any questions or
|
|
feedback. Please include the version number of the library that you are
|
|
using as well as your machine and operating system types.
|
|
|
|
Gray Watson.
|
|
|
|
@menu
|
|
* Copying:: Library copying conditions.
|
|
* Overview:: Description of how to use the library.
|
|
* Details:: Details about the library's operations.
|
|
* General Usage:: Invoking Programs Which Use the Library.
|
|
* Plugs:: A couple soapbox comments.
|
|
* Index of Concepts:: Index of concepts in the manual.
|
|
@ifinfo
|
|
* Full Node Listings:: Listing of all the nodes in the manual.
|
|
@end ifinfo
|
|
@end menu
|
|
|
|
@node Copying, Overview, Top, Top
|
|
@chapter Library Copying Conditions
|
|
|
|
@cindex copying
|
|
@cindex license
|
|
@cindex library permissions
|
|
@cindex permissions of the library
|
|
|
|
Copyright 1992 to 1998 by Gray Watson.
|
|
|
|
Gray Watson makes no representations about the suitability of the
|
|
software described herein for any purpose. It is provided ``as is''
|
|
without express or implied warranty. The name of Gray Watson cannot be
|
|
used in advertising or publicity pertaining to distribution of the
|
|
document or software without specific, written prior permission.
|
|
|
|
Permission to use, copy, modify, and distribute this software for any
|
|
purpose and without fee is hereby granted, provided that the above
|
|
copyright notice and this permission notice appear in all copies, and
|
|
that the name of Gray Watson not be used in advertising or publicity
|
|
pertaining to distribution of the document or software without specific,
|
|
written prior permission.
|
|
|
|
Gray Watson makes no representations about the suitability of the
|
|
software described herein for any purpose. It is provided "as is"
|
|
without express or implied warranty.
|
|
|
|
@node Overview, Details, Copying, Top
|
|
@chapter How to Use the Library
|
|
|
|
@menu
|
|
* Concepts:: General concepts behind the library.
|
|
* How To Get:: How to get the library.
|
|
* Installation:: How to install the library.
|
|
* Getting Started:: Getting started with the library.
|
|
@end menu
|
|
|
|
@node Concepts, How To Get, Overview, Overview
|
|
@section The General Concepts Behind the Library
|
|
|
|
@cindex command line arguments
|
|
@cindex unix command line
|
|
|
|
One thing that almost all Unix executables need to do is process the
|
|
@dfn{command line arguments}. Whether this is to enable verbose mode or
|
|
specify the files for a utility to work on, code has to be written to
|
|
process these user specified options.
|
|
|
|
@example
|
|
int main(int argc, char **argv)
|
|
@{
|
|
...
|
|
@}
|
|
@end example
|
|
|
|
As you must know, the command line arguments in most Unix systems are
|
|
passed in as arguments to @code{main()} (seen above). The @code{argc}
|
|
integer argument contains the number of arguments specified. The
|
|
@code{argv} variable holds the arguments themselves. It can be thought
|
|
of as a pointer to a list of character pointers -- or an array of
|
|
character pointers.
|
|
|
|
To get a particular argument from @code{argv}, you use @code{argv[x]}
|
|
where @code{x} is an integer whose value is from 0 to @code{argc - 1}.
|
|
In most Unix implementations, the zeroth argument is always the name the
|
|
program was executed with. For instance, if you typed @samp{./ls -al},
|
|
@code{argc} would equal 2 and the value of @code{argv[0]} would be
|
|
@samp{"./ls"}. The value for @code{argv[1]} would be @samp{"-al"}.
|
|
|
|
@cindex getopt
|
|
Currently, most programmers either write code on a per program basis to
|
|
process arguments or they use the @code{getopt()} routine. Writing
|
|
argument processing code for each program results in improper and
|
|
inconsistent argument handling. Although better, @code{getopt()} does
|
|
not provide the structure needed to ensure conformity in argument
|
|
processing and still requires significant code to be written by the
|
|
programmer.
|
|
|
|
The goal for this library was to achieve a standardized way of
|
|
processing arguments -- especially in terms of error and usage messages.
|
|
Important consideration was also given to reducing the programming time
|
|
necessary to enable the functionality.
|
|
|
|
@node How To Get, Installation, Concepts, Overview
|
|
@section How to get the library.
|
|
|
|
@cindex downloading the library
|
|
@cindex getting the source
|
|
|
|
The newest versions of the argv library are available via anonymous ftp
|
|
from @samp{ftp.letters.com} in the @file{/src/argv} directory.
|
|
|
|
@cindex anonymous ftp
|
|
@cindex ftp
|
|
|
|
To use anonymous ftp, you ftp to the site and when the system prompts
|
|
you for a login-id or username you enter @kbd{anonymous}. When it
|
|
prompts you for a password you enter your email address. You then can
|
|
change-directory (cd) into @file{/src/argv} and get the @file{README}
|
|
and @file{argv.tar.gz} files.
|
|
|
|
The versions in this repository also include such files as a
|
|
postscript version of the manual and other large files which may not
|
|
have been included in the distribution you received.
|
|
|
|
@node Installation, Getting Started, How To Get, Overview
|
|
@section Installing the Library
|
|
|
|
@cindex installing the library
|
|
@cindex compiling the library
|
|
@cindex building the library
|
|
@cindex configuring the library
|
|
@cindex making the library
|
|
|
|
To configure, compile, and install the library, follow these steps
|
|
carefully.
|
|
|
|
@enumerate
|
|
|
|
@cindex configure script
|
|
@cindex conf.h file
|
|
|
|
@item Type @kbd{sh ./configure} to configure the library. You may want
|
|
to first examine the @file{config.help} file for some information about
|
|
configure. Configure should generate the @file{Makefile} and some
|
|
configuration files automatically.
|
|
|
|
@emph{NOTE}: It seems that some versions of tr (especially from HP-UX)
|
|
don't understand @code{tr '[a-z]' '[A-Z]'}. Since configure uses tr
|
|
often, you may need to either get GNU's tr (in their textutils package)
|
|
or generate the @file{Makefile} and @file{conf.h} files by hand.
|
|
|
|
@item You may want to examine the @file{Makefile} and @file{conf.h} files
|
|
created by configure to make sure it did its job correctly.
|
|
|
|
@item Typing @kbd{make} should be enough to build @file{libargv.a}
|
|
and the @file{argv_shell} utility. If it does not work, please send me
|
|
some notes so future users can profit from your experiences.
|
|
|
|
@cindex ANSI-C compiler
|
|
@cindex Deansify.pl script
|
|
|
|
@emph{NOTE}: The code is pretty dependent on a good ANSI-C compiler. If
|
|
the configure script gives the @samp{WARNING} that you do not have an
|
|
ANSI-C compiler, you may still be able to add some sort of option to
|
|
your compiler to make it ANSI. If there such is an option, please send
|
|
it to the author so it can be added to the configure script. Otherwise,
|
|
you will have to try @kbd{make noansi}. This will run the
|
|
@file{Deansify.pl} perl script on the code which:
|
|
|
|
@itemize @bullet
|
|
@item @emph{WARNING}: modifies the source code in place
|
|
@item changes all @code{void *} references to @code{char *}.
|
|
@item fixes all functions to remove @code{foo(char * var)} declarations.
|
|
@end itemize
|
|
|
|
If it doesn't work you may have to do Deansify.pl's job by hand.
|
|
|
|
@item Typing @kbd{make tests} should build the @file{argv_t} test
|
|
program. This can be run and given arguments to test the various
|
|
library features.
|
|
|
|
@item Typing @kbd{make install} should install the @file{libargv.a}
|
|
library in @file{/usr/local/lib}, the @file{argv_shell} utility in
|
|
@file{/usr/local/bin}, and the @file{argv.info} documentation file in
|
|
@file{/usr/local/info}.
|
|
|
|
You may have specified a @samp{--prefix=PATH} option to configure in
|
|
which can @samp{/usr/local} will have been replaced with @samp{PATH}.
|
|
|
|
@end enumerate
|
|
|
|
See the Getting Started section to get up and running with the library.
|
|
@xref{Getting Started}.
|
|
|
|
@node Getting Started, , Installation, Overview
|
|
@section Getting Started with the Library
|
|
|
|
@cindex quick start
|
|
@cindex getting started
|
|
@cindex jump start
|
|
@cindex how to begin
|
|
@cindex where to begin
|
|
|
|
This section should give you a quick idea on how to get going.
|
|
|
|
@enumerate
|
|
|
|
@item Make sure you have the latest version of the library. It is
|
|
available via anonymous ftp from @samp{ftp.letters.com} in the
|
|
@file{/src/argv} directory. @xref{How To Get}.
|
|
|
|
@item Follow the installation instructions on how to configure and
|
|
make and install the library (i.e. type: @kbd{make install}).
|
|
@xref{Installation}.
|
|
|
|
@item Examine the @file{argv_t.c} test program source to see an
|
|
example of how to program with the library. After adding the
|
|
appropriate @code{argv_t} structure array to your main source file, you
|
|
need to compile and link your programs with the library.
|
|
|
|
@item The first time your program is run, the library makes a number
|
|
of checks as to the validity of the argument structures being used. You
|
|
may have to note and fix reported problems.
|
|
|
|
@item Run your program with the @samp{--usage} argument and voila.
|
|
|
|
@end enumerate
|
|
|
|
@node Details, General Usage, Overview, Top
|
|
@chapter The Library's Operations
|
|
|
|
@menu
|
|
* Argv_t Structure:: The argv_t structure and it's usage.
|
|
* Special Short Args:: The special ar_short_arg values.
|
|
* Types of Variables:: The different variable types.
|
|
* Variable Arrays:: Using arguments which ``absorb'' arrays.
|
|
@end menu
|
|
|
|
@node Argv_t Structure, Special Short Args, Details, Details
|
|
@section The argv_t Structure and It's Usage
|
|
|
|
The argv_t argument structure is as follows:
|
|
|
|
@example
|
|
typedef struct @{
|
|
char ar_short_arg; /* short argument */
|
|
char *ar_long_arg; /* long argument */
|
|
short ar_type; /* type of variable */
|
|
void *ar_variable; /* point to variable to set */
|
|
char *ar_var_label; /* label for var description */
|
|
char *ar_help_label; /* help lable for the arg */
|
|
@} argv_t;
|
|
@end example
|
|
|
|
The @code{ar_short_arg} element contains the character value of the
|
|
short option ('d' for @samp{-d}) or special codes such as ARGV_LAST
|
|
which identifies the last element in the array. @xref{Special Short
|
|
Args}.
|
|
|
|
The @code{ar_long_arg} element (if not-NULL) holds the string which is
|
|
the long version of @code{ar_short_arg}. For instance, with @samp{-d},
|
|
you might have "delete". This would mean that @samp{-d} and
|
|
@samp{--delete} would be equivalent. @samp{--} is the long-option
|
|
prefix per POSIX specs.
|
|
|
|
You would define an array of these arguments at the top of the file with
|
|
@code{main()} in it.
|
|
|
|
@example
|
|
static char copy = ARGV_FALSE;
|
|
|
|
static argv_t args[] = @{
|
|
@{ 'c', "copy", ARGV_BOOL, ©, NULL, "copy-files flag" @},
|
|
@{ 'g', "group", ARGV_CHAR_P, &group, "group", "name of group to set" @},
|
|
...
|
|
@{ ARGV_LAST @}
|
|
@};
|
|
|
|
...
|
|
|
|
int main(int argc, char ** argv)
|
|
@{
|
|
argv_process(args, argc, argv);
|
|
@}
|
|
@end example
|
|
|
|
@node Special Short Args, Types of Variables, Argv_t Structure, Details
|
|
@section The Special ar_short_arg Values
|
|
|
|
There are 3 types of arguments:
|
|
|
|
@table @dfn
|
|
@item optional
|
|
Arguments that may or may not be supplied by the user.
|
|
|
|
@item mandatory
|
|
Arguments that must be supplied by the user. For instance grep must be
|
|
given an expression on the command line.
|
|
|
|
If the argument is a mandatory argument which has no -%c prefix then the
|
|
@code{ar_short_arg} element should be assigned ARGV_MAND.
|
|
|
|
@item maybe
|
|
Arguments that might be specified by the caller but are not mandatory.
|
|
For instance, you can grep a file or you can grep standard-input. The
|
|
file should be a maybe argument.
|
|
|
|
If this is a maybe argument then use ARGV_MAYBE in the
|
|
@code{ar_short_arg} field.
|
|
|
|
@end table
|
|
|
|
To mark the last entry in the structure list use ARGV_LAST. ARGV_OR
|
|
also works.
|
|
|
|
@node Types of Variables, Variable Arrays, Special Short Args, Details
|
|
@section The argv_t Structure and It's Usage
|
|
|
|
Ar_type holds the type of the argument whether an optional argument or
|
|
mandatory. Below are the available values for this field.
|
|
|
|
@table @code
|
|
@item ARGV_BOOL
|
|
character type, sets the variable to ARGV_TRUE if used
|
|
|
|
@item ARGV_BOOL_NEG
|
|
like ARGV_BOOL but sets the variable to ARGV_FALSE if used
|
|
|
|
@item ARGV_BOOL_ARG
|
|
like ARGV_BOOL but takes a yes/no argument
|
|
|
|
@item ARGV_CHAR
|
|
a single character
|
|
|
|
@item ARGV_CHAR_P
|
|
a string of characters (character pointer)
|
|
|
|
@item ARGV_FLOAT
|
|
a floating pointer number
|
|
|
|
@item ARGV_SHORT
|
|
a short integer number
|
|
|
|
@item ARGV_INT
|
|
an integer number
|
|
|
|
@item ARGV_U_INT
|
|
an unsigned integer number
|
|
|
|
@item ARGV_LONG
|
|
a long integer number
|
|
|
|
@item ARGV_U_LONG
|
|
an unsigned long integer number
|
|
|
|
@item ARGV_BIN
|
|
a binary base-2 number (0s and 1s)
|
|
|
|
@item ARGV_OCT
|
|
an octal base-8 number (0 to 7)
|
|
|
|
@item ARGV_HEX
|
|
a hexadecimal base-16 number (0 to 9 and A to F)
|
|
|
|
@item ARGV_INCR
|
|
a integer type which is incremented each time it is specified
|
|
|
|
@item ARGV_SIZE
|
|
a long integer size number which understands b for bytes, k for
|
|
kilobytes, m for megabytes, and g for gigabytes
|
|
|
|
@item ARGV_U_SIZE
|
|
an unsigned long integer version of ARGV_SIZE
|
|
|
|
@item ARGV_BOOL_INT
|
|
like ARGV_BOOL except the variable is an integer and not a character
|
|
|
|
@item ARGV_BOOL_INT_NEG
|
|
like ARGV_BOOL_NEG except the variable is an integer and not a character
|
|
|
|
@item ARGV_BOOL_INT_ARG
|
|
like ARGV_BOOL_ARG except the variable is an integer and not a character
|
|
|
|
@end table
|
|
|
|
For printing out of the type of the argument on the command line, use
|
|
the @samp{--argv-display} option which will display the argument, its
|
|
type and value. It will display the variables' default values if no
|
|
arguments specified before it on the command line otherwise it will show
|
|
the values the variables are set to after processing the arguments.
|
|
|
|
Basically the argument processing routines, examine the type of the
|
|
variable, absorb another argument (if necessary), and then translate the
|
|
string argument (if necessary) and write the data into the address
|
|
stored in the ar_variable field.
|
|
|
|
ARGV_BOOL, ARGV_BOOL_NEG, ARGV_INCR, ARGV_BOOL_INT, and
|
|
ARGV_BOOL_INT_NEG are special in the above list in that they do not
|
|
require another argument. With @samp{ls -l}, for example, the @samp{-l}
|
|
flag lives on its own. With @samp{install -m 444 @dots{}}, on the other
|
|
hand, @samp{444} is an octal number argument associated with @samp{-m}
|
|
and will be translated and assigned to the @samp{-m} mode variable.
|
|
|
|
@node Variable Arrays, , Types of Variables, Details
|
|
@section Using Arguments Which ``Absorb'' Arrays.
|
|
|
|
Needs to be written. Sorry.
|
|
|
|
@node General Usage, Plugs, Details, Top
|
|
@chapter Invoking Programs Which Use the Library
|
|
|
|
@menu
|
|
* Usage Messages:: How to get usage messages from argv programs.
|
|
* Specifying Arguments:: How to specify arguments to argv programs.
|
|
* Long Versus Short:: Long versus short arguments.
|
|
* Global Environment Variable:: Settings for all argv programs.
|
|
* Program Environment Variable:: Arguments for a specific argv program.
|
|
@end menu
|
|
|
|
@node Usage Messages, Specifying Arguments, General Usage, General Usage
|
|
@section How to get usage messages from argv programs
|
|
|
|
If a program @samp{install} has the library compiled in you should be
|
|
able to do a @samp{install --usage-long} to get the long-format usage
|
|
message.
|
|
|
|
@example
|
|
Usage: install
|
|
[-c] or --copy-files = copy file(s), don't move %t
|
|
[-g group] or --group-id = group id name (default bin) %s
|
|
[-m octal-mode] or --mode-value = permissions mode value %o
|
|
[-o owner] or --owner-id = owner id name (default bin) %s
|
|
[-s] or --strip = strip destination binary %t
|
|
[file(s)] directory/destination = files to install or mkdir arg
|
|
@end example
|
|
|
|
In the above example, the program install's usage message is detailed.
|
|
The @samp{[-c]} line details the copy-files flag. You can either enable
|
|
it with a @samp{-c} or @samp{--copy-files}. The description of the flag
|
|
follows with lastly, a @samp{%t} showing that it is a @dfn{true/false}
|
|
flag.
|
|
|
|
The @samp{[-g]} line shows the group-id flag. It is different from the
|
|
@samp{-c} flag since, if used, it takes a group string argument (notice
|
|
the @samp{%s} at the end of the line indicating it takes a string
|
|
argument).
|
|
|
|
@samp{install --usage-short} or just @samp{--usage} will get you a
|
|
condensed usage message:
|
|
|
|
@example
|
|
Usage: install [-cs] [-g group] [-m octal-mode] [-o owner] [file(s)]
|
|
directory/destination
|
|
@end example
|
|
|
|
@node Specifying Arguments, Long Versus Short, Usage Messages, General Usage
|
|
@section How to Specify Arguments to Argv Programs
|
|
|
|
Specifying arguments to a program which uses the library is quite
|
|
straight-forward and standardized. Once you have learned how to do it
|
|
once, you can use any program with it.
|
|
|
|
There are five basic types of arguments as defined by the library:
|
|
|
|
@table @dfn
|
|
|
|
@item true/false flags
|
|
Do not have an associated value and the program will get a True if one
|
|
is specified else False.
|
|
|
|
The @samp{-c} in @samp{install -c}.
|
|
|
|
@item variable flags
|
|
Have an associate value which will be supplied to the program.
|
|
|
|
The @samp{-m} in @samp{install -m 0644} will get the value @samp{0644}.
|
|
|
|
@item values
|
|
Arguments without a @samp{-} and are associated values for the variable
|
|
flags.
|
|
|
|
@item mandatory
|
|
Arguments without a @samp{-} but are @emph{not} associated to variable
|
|
flags. These can be supplied to the program if allowed. They are
|
|
mandatory in that they must be supplied. If the program asks for 3
|
|
arguments, 3 must be supplied. @emph{NOTE} that order is important with
|
|
these.
|
|
|
|
The @samp{from} and @samp{to} arguments in @samp{install from to}.
|
|
|
|
@item maybe
|
|
These are the same as the mandatory arguments except they are optional
|
|
arguments and can but do not have to be supplied.
|
|
|
|
The @samp{file} argument in @samp{ls file} since @samp{ls} does not
|
|
require a file to be listed to work.
|
|
|
|
@end table
|
|
|
|
The values for the variable flags are assigned in a straight
|
|
First-In-First-Out queue. In @samp{install -m -g 0644 bin}, the value
|
|
@samp{0644} is assigned to the @samp{-m} flag and the value @samp{bin}
|
|
is assigned to @samp{-g}.
|
|
|
|
Additional values that cannot be matched to variable flags will become
|
|
mandatory or maybe arguments if the program is configured to accept
|
|
them.
|
|
|
|
@example
|
|
install from -c -m -g 0644 -o wheel -s jim to
|
|
@end example
|
|
|
|
In the previous convoluted example, @samp{from} and @samp{to} are
|
|
mandatory arguments, @samp{-c} and @samp{-s} are true/false flags,
|
|
@samp{-m} gets assigned @samp{0644}, @samp{-g} gets @samp{wheel}, and
|
|
@samp{-o} gets @samp{jim}. It would be much easier to write it as:
|
|
|
|
@example
|
|
install -cs -m 0644 -g wheel -o jim to from
|
|
@end example
|
|
|
|
@node Long Versus Short, Global Environment Variable, Specifying Arguments, General Usage
|
|
@section Long Versus Short Arguments
|
|
|
|
Needs to be written. Sorry.
|
|
|
|
@node Global Environment Variable, Program Environment Variable, Long Versus Short, General Usage
|
|
@section Global Settings For All Argv Programs
|
|
|
|
@cindex environment variable
|
|
@cindex GLOBAL_ARGV
|
|
|
|
An @dfn{environment variable} is a variable that is part of the user's
|
|
working environment and is shared by all the programs. The
|
|
@samp{GLOBAL_ARGV} variable is used by the argv library to customize its
|
|
behavior at runtime. It can be set by hand and should probably be
|
|
entered into your shell's runtime configuration or @dfn{RC} file.
|
|
|
|
@cindex C shell usage
|
|
@cindex csh usage
|
|
@cindex tcsh usage
|
|
To set the variable, C shell (csh or tcsh) users need to invoke:
|
|
|
|
@example
|
|
setenv GLOBAL_ARGV value
|
|
@end example
|
|
|
|
@cindex Bourne shell usage
|
|
@cindex sh usage
|
|
@cindex bash usage
|
|
@cindex ksh usage
|
|
@cindex zsh usage
|
|
Bourne shell (sh, bash, ksh, or zsh) users should use:
|
|
|
|
@example
|
|
GLOBAL_ARGV=value
|
|
export GLOBAL_ARGV
|
|
@end example
|
|
|
|
The value in the above example is a comma separated list of tokens each
|
|
having a corresponding value. The tokens and their values are described
|
|
below:
|
|
|
|
@itemize @bullet
|
|
|
|
@item close -- close argument acceptance
|
|
|
|
Enables the handling of arguments such as @samp{-m=444} where @samp{-m}
|
|
is a flag and @samp{444} is its value.
|
|
|
|
Values: disable, enable.
|
|
|
|
@itemize @bullet
|
|
@item disable -- treat @samp{=} like a normal argument
|
|
@item enable (default) -- enable the @samp{-x=10} format
|
|
@end itemize
|
|
|
|
@item env -- environment variable handling
|
|
|
|
Enables the processing of the @samp{ARGV_*} variables. If you have a
|
|
set of options that you always use for @samp{ls} for instance, you cat
|
|
set the @samp{ARGV_LS} environmental variable to hold these options.
|
|
For instance: @samp{setenv ARGV_LS "-sCF"}.
|
|
|
|
Values: none, before, after.
|
|
|
|
@itemize @bullet
|
|
@item none -- No processed at all
|
|
@item before (default) -- options from env variable are processed
|
|
Before command line
|
|
@item after -- env options processed After command line
|
|
@end itemize
|
|
|
|
@item error -- handling of usage errors
|
|
|
|
Whenever you do not use a command correctly, this token determines how
|
|
the library reports errors to you.
|
|
|
|
Values: none, see, short, shortrem, long, all.
|
|
|
|
@itemize @bullet
|
|
@item none -- on errors print nothing but error message
|
|
@item see (default) -- on errors print see --usage for more info.
|
|
@item short -- on errors print the short-format usage messages
|
|
@item shortrem -- on errors print short-format + how to get long
|
|
@item long -- on errors print the long-format usage messages
|
|
@item all -- on errors print the long-format usage messages + help, etc.
|
|
@end itemize
|
|
|
|
@item multi -- the handling of arguments specified more than once
|
|
|
|
If you use am argument twice on the command line, this token determines
|
|
if the library should say it is an error.
|
|
|
|
Values: accept, reject.
|
|
|
|
@itemize @bullet
|
|
@item accept (default) -- it's NOT an error if specified more than once
|
|
@item reject -- it's an error if specified more than once
|
|
@end itemize
|
|
|
|
@item usage -- usage messages for --usage
|
|
|
|
Determines what messages the library prints when you use the
|
|
@samp{--usage} option.
|
|
|
|
Values: short, shortrem, long, all.
|
|
|
|
@itemize @bullet
|
|
@item short (default) -- default is the short-format messages
|
|
@item shortrem -- default is the short-format messages + how to get long
|
|
@item long -- default is the long-format messages
|
|
@item all -- default is the long-format messages + help, usage, version
|
|
@end itemize
|
|
|
|
@end itemize
|
|
|
|
Examples:
|
|
|
|
@example
|
|
# accept -x=10, no env variables, long messages on errors,
|
|
# accept multiple uses, and print all messages on --usage.
|
|
setenv GLOBAL_ARGV close=accept,env=none,error=long,multi=accept,usage=all
|
|
|
|
# process env variable options before command line,
|
|
# and reject multiple argument uses
|
|
setenv GLOBAL_ARGV env=before,error=long,multi=reject
|
|
@end example
|
|
|
|
@node Program Environment Variable, , Global Environment Variable, General Usage
|
|
@section Arguments For a Specific Argv Program
|
|
|
|
Needs to be written. Sorry.
|
|
|
|
@node Plugs, Index of Concepts, General Usage, Top
|
|
@chapter Plugs and Soapbox Comments
|
|
|
|
@cindex plugs
|
|
@cindex soapbox comments
|
|
|
|
Since I have your attention I would like to talk for a second about a
|
|
couple of things that I feel strongly about. If you would like any more
|
|
information about the below, please mail to the supplied addresses or
|
|
drop me a line with any questions.
|
|
|
|
@table @asis
|
|
@item The Electronic Frontier Foundation (EFF)
|
|
@cindex EFF
|
|
@cindex Electronic Frontier Foundation
|
|
The EFF is a organization committed to ensuring that the rules,
|
|
regulations, and laws being applied to emerging communications
|
|
technologies are in keeping with our society's highest traditions of the
|
|
free and open flow of ideas and information while protecting personal
|
|
privacy. http://www.eff.org/
|
|
|
|
@item Computer Professionals for Social Responsibility (CPSR)
|
|
@cindex CPSR
|
|
@cindex Computer Professionals for Social Responsibility
|
|
CPSR is a public-interest alliance of computer scientists and others
|
|
interested in the impact of computer technology on society. We work to
|
|
influence decisions regarding the development and use of computers
|
|
because those decisions have far-reaching consequences and reflect basic
|
|
values and priorities. http://www.cpsr.org/
|
|
@end table
|
|
|
|
@node Index of Concepts, Full Node Listings, Plugs, Top
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
@contents
|
|
|
|
@ifinfo
|
|
|
|
@node Full Node Listings, , Index of Concepts, Top
|
|
@unnumbered Detailed Node Listing
|
|
|
|
@menu
|
|
Top.
|
|
|
|
* Copying:: Library copying conditions.
|
|
* Overview:: Description of how to use the library.
|
|
* Details:: Details about the library's operations.
|
|
* General Usage:: Invoking Programs Which Use the Library.
|
|
* Plugs:: A couple soapbox comments.
|
|
* Index of Concepts:: Index of concepts in the manual.
|
|
* Full Node Listings:: Listing of all the nodes in the manual.
|
|
|
|
Overview.
|
|
|
|
* Concepts:: General concepts behind the library.
|
|
* How To Get:: How to get the library.
|
|
* Installation:: How to install the library.
|
|
* Getting Started:: Getting started with the library.
|
|
|
|
Details
|
|
|
|
* Argv_t Structure:: The argv_t structure and it's usage.
|
|
* Special Short Args:: The special ar_short_arg values.
|
|
* Types of Variables:: The different variable types.
|
|
* Variable Arrays:: Using arguments which ``absorb'' arrays.
|
|
|
|
General Usage
|
|
|
|
* Usage Messages:: How to get usage messages from argv programs.
|
|
* Specifying Arguments:: How to specify arguments to argv programs.
|
|
* Long Versus Short:: Long versus short arguments.
|
|
* Global Environment Variable:: Settings for all argv programs.
|
|
* Program Environment Variable:: Arguments for a specific argv program.
|
|
|
|
@end menu
|
|
|
|
@end ifinfo
|
|
@bye
|