head 1.1; access; symbols PETIDOMO_4_0b6:1.1 PETIDOMO_4_0b5:1.1 PETIDOMO_4_0b4:1.1 PETIDOMO_4_0b3:1.1 BEFORETHL:1.1; locks; strict; comment @# @; 1.1 date 2000.12.13.15.38.37; author simons; state Exp; branches; next ; desc @@ 1.1 log @Imported libargv version 2.4.0. @ text @\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: argv.texi,v 1.1.1.1 1999/08/23 07:35:59 simons Exp $ @@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 @