Home | History | Annotate | Line # | Download | only in getopt
getopt.1 revision 1.1 
      1 .Dd June 21, 1993
      2 .Dt GETOPT 1
      3 .Os
      4 .Sh NAME
      5 .Nm getopt
      6 .Nd parse command options
      7 .Sh SYNOPSIS
      8 .Nm set \-\- \`getopt optstring $*\`
      9 .Sh DESCRIPTION
     10 .Nm Getopt
     11 is used to break up options in command lines for easy parsing by
     12 shell procedures, and to check for legal options.
     13 .Op Optstring
     14 is a string of recognized option letters (see
     15 .Xr getopt 3
     16 );
     17 if a letter is followed by a colon, the option
     18 is expected to have an argument which may or may not be
     19 separated from it by white space.
     20 The special option
     21 .B \-\-
     22 is used to delimit the end of the options.
     23 .Nm Getopt
     24 will place
     25 .B \-\-
     26 in the arguments at the end of the options,
     27 or recognize it if used explicitly.
     28 The shell arguments
     29 (\fB$1 $2\fR ...) are reset so that each option is
     30 preceded by a
     31 .B \-
     32 and in its own shell argument;
     33 each option argument is also in its own shell argument.
     34 .Sh EXAMPLE
     35 The following code fragment shows how one might process the arguments
     36 for a command that can take the options
     37 .Op a
     38 and
     39 .Op b ,
     40 and the option
     41 .Op o ,
     42 which requires an argument.
     43 .Pp
     44 .Bd -literal -offset indent
     45 set \-\- \`getopt abo: $*\`
     46 if test $? != 0
     47 then
     48 	echo 'Usage: ...'
     49 	exit 2
     50 fi
     51 for i
     52 do
     53 	case "$i"
     54 	in
     55 		\-a|\-b)
     56 			flag=$i; shift;;
     57 		\-o)
     58 			oarg=$2; shift; shift;;
     59 		\-\-)
     60 			shift; break;;
     61 	esac
     62 done
     63 .Ed
     64 .Pp
     65 This code will accept any of the following as equivalent:
     66 .Pp
     67 .Bd -literal -offset indent
     68 cmd \-aoarg file file
     69 cmd \-a \-o arg file file
     70 cmd \-oarg -a file file
     71 cmd \-a \-oarg \-\- file file
     72 .Ed
     73 .Sh SEE ALSO
     74 .Xr sh 1 ,
     75 .Xr getopt 3
     76 .Sh DIAGNOSTICS
     77 .Nm Getopt
     78 prints an error message on the standard error output when it
     79 encounters an option letter not included in
     80 .Op optstring .
     81 .Sh HISTORY
     82 Written by Henry Spencer, working from a Bell Labs manual page.
     83 Behavior believed identical to the Bell version.
     84 .Sh BUGS
     85 Whatever
     86 .Xr getopt 3
     87 has.
     88 .Pp
     89 Arguments containing white space or imbedded shell metacharacters
     90 generally will not survive intact;  this looks easy to fix but isn't.
     91 .Pp
     92 The error message for an invalid option is identified as coming
     93 from
     94 .Nm getopt
     95 rather than from the shell procedure containing the invocation
     96 of
     97 .Nm getopt ;
     98 this again is hard to fix.
     99 .Pp
    100 The precise best way to use the
    101 .Nm set
    102 command to set the arguments without disrupting the value(s) of
    103 shell options varies from one shell version to another.
    104 varies from one shell version to another.
    105