usr.bin/getopt/getopt.1

   1 .\"     $NetBSD: getopt.1,v 1.19 2010/01/24 20:13:28 dholland Exp $
   2 .Dd November 28, 2009
   3 .Dt GETOPT 1
   4 .Os
   5 .Sh NAME
   6 .Nm getopt
   7 .Nd parse command options
   8 .Sh SYNOPSIS
   9 .Li args=\`getopt optstring $*\`
  10 .Pp
  11 .Li set \-\- \`getopt optstring $*\`
  12 .Sh DESCRIPTION
  13 .Nm
  14 is used to break up options in command lines for easy parsing by
  15 shell procedures, and to check for legal options.
  16 .Op Optstring
  17 is a string of recognized option letters (see
  18 .Xr getopt 3 ) ;
  19 if a letter is followed by a colon, the option
  20 is expected to have an argument which may or may not be
  21 separated from it by white space.
  22 The special option
  23 .Dq \-\-
  24 is used to delimit the end of the options.
  25 .Nm
  26 will place
  27 .Dq \-\-
  28 in the arguments at the end of the options,
  29 or recognize it if used explicitly.
  30 The shell arguments
  31 .Pq Ev $1 , Ev $2 , ...
  32 are reset so that each option is
  33 preceded by a
  34 .Dq \-
  35 and in its own shell argument;
  36 each option argument is also in its own shell argument.
  37 .Pp
  38 .Nm
  39 should not be used in new scripts; use the shell builtin
  40 .Nm getopts
  41 instead.
  42 .Sh EXAMPLES
  43 The following code fragment shows how one might process the arguments
  44 for a command that can take the options
  45 .Op a
  46 and
  47 .Op b ,
  48 and the option
  49 .Op c ,
  50 which requires an argument.
  51 .Pp
  52 .Bd -literal -offset indent
  53 args=\`getopt abc: $*\`
  54 if [ $? \-ne 0 ]; then
  55         echo 'Usage: ...'
  56         exit 2
  57 fi
  58 set \-\- $args
  59 while [ $# \-gt 0 ]; do
  60         case "$1" in
  61                 \-a|\-b)
  62                         flag=$1
  63                         ;;
  64                 \-c)
  65                         carg=$2; shift
  66                         ;;
  67                 \-\-)
  68                         shift; break
  69                         ;;
  70         esac
  71         shift
  72 done
  73 .Ed
  74 .Pp
  75 This code will accept any of the following as equivalent:
  76 .Pp
  77 .Bd -literal -offset indent
  78 cmd \-acarg file file
  79 cmd \-a \-c arg file file
  80 cmd \-carg -a file file
  81 cmd \-a \-carg \-\- file file
  82 .Ed
  83 .Pp
  84 .St -p1003.2
  85 mandates that the
  86 .Xr sh 1
  87 set command return the value of 0 for the exit status.
  88 Therefore, the exit status of the
  89 .Nm
  90 command is lost when
  91 .Nm
  92 and the
  93 .Xr sh 1
  94 set command are used on the same line.
  95 The example given is one way to detect errors found by
  96 .Nm .
  97 .Sh DIAGNOSTICS
  98 .Nm
  99 prints an error message on the standard error output when it
 100 encounters an option letter not included in
 101 .Op optstring .
 102 .Sh SEE ALSO
 103 .Xr sh 1 ,
 104 .Xr getopt 3
 105 .Sh HISTORY
 106 Written by Henry Spencer, working from a Bell Labs manual page.
 107 Behavior believed identical to the Bell version.
 108 .Sh BUGS
 109 Whatever
 110 .Xr getopt 3
 111 has.
 112 .Pp
 113 Arguments containing white space or embedded shell metacharacters
 114 generally will not survive intact;  this looks easy to fix but isn't.
 115 .Pp
 116 The error message for an invalid option is identified as coming
 117 from
 118 .Nm
 119 rather than from the shell procedure containing the invocation
 120 of
 121 .Nm ;
 122 this again is hard to fix.
 123 .Pp
 124 The precise best way to use the
 125 .Ic set
 126 command to set the arguments without disrupting the value(s) of
 127 shell options varies from one shell version to another.