usr/src/man/man1/getoptcvt.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T
   3 .\" Copyright (c) 2000, Sun Microsystems, Inc.
   4 .\"  All Rights Reserved
   5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   6 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   7 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   8 .TH GETOPTCVT 1 "Jan 7, 2000"
   9 .SH NAME
  10 getoptcvt \- convert to getopts to parse command options
  11 .SH SYNOPSIS
  12 .LP
  13 .nf
  14 \fB/usr/lib/getoptcvt\fR [\fB-b\fR] \fIfilename\fR
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fB/usr/lib/getoptcvt\fR
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 \fB/usr/lib/getoptcvt\fR reads the shell script in \fIfilename\fR, converts it
  26 to use \fBgetopts\fR instead of \fBgetopt\fR, and writes the results on the
  27 standard output.
  28 .sp
  29 .LP
  30 \fBgetopts\fR is a built-in Bourne shell command used to parse positional
  31 parameters and to check for valid options. See \fBsh\fR(1). It supports all
  32 applicable rules of the command syntax standard (see Rules 3-10,
  33 \fBIntro\fR(1)). It should be used in place of the \fBgetopt\fR command. (See
  34 the NOTES section below.) The syntax for the shell's built-in \fBgetopts\fR
  35 command is:
  36 .sp
  37 .LP
  38 \fBgetopts\fR \fIoptstring\fR \fIname\fR [ \fIargument\fR\|.\|.\|.\|]
  39 .sp
  40 .LP
  41 \fIoptstring\fR must contain the option letters the command using \fBgetopts\fR
  42 will recognize; if a letter is followed by a colon (\fB:\fR), the option is
  43 expected to have an argument, or group of arguments, which must be separated
  44 from it by white space.
  45 .sp
  46 .LP
  47 Each time it is invoked, \fBgetopts\fR places the next option in the shell
  48 variable \fIname\fR and the index of the next argument to be processed in the
  49 shell variable \fBOPTIND\fR. Whenever the shell or a shell script is invoked,
  50 \fBOPTIND\fR is initialized to \fB1\fR.
  51 .sp
  52 .LP
  53 When an option requires an option-argument, \fBgetopts\fR places it in the
  54 shell variable \fBOPTARG\fR.
  55 .sp
  56 .LP
  57 If an illegal option is encountered, \fB?\fR will be placed in \fIname\fR.
  58 .sp
  59 .LP
  60 When the end of options is encountered, \fBgetopts\fR exits with a non-zero
  61 exit status. The special option \fB \(mi\(mi\fR may be used to delimit the end
  62 of the options.
  63 .sp
  64 .LP
  65 By default, \fBgetopts\fR parses the positional parameters. If extra arguments
  66 (\fIargument\fR .\|.\|.) are given on the \fBgetopts\fR command line,
  67 \fBgetopts\fR parses them instead.
  68 .sp
  69 .LP
  70 So that all new commands will adhere to the command syntax standard described
  71 in \fBIntro\fR(1), they should use \fBgetopts\fR or \fBgetopt\fR to parse
  72 positional parameters and check for options that are valid for that command
  73 (see the NOTES section below).
  74 .SH OPTIONS
  75 .sp
  76 .LP
  77 The following option is supported:
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fB-b\fR\fR
  82 .ad
  83 .RS 6n
  84 Makes the converted script portable to earlier releases of the UNIX system.
  85 \fB/usr/lib/getoptcvt\fR modifies the shell script in \fIfilename\fR so that
  86 when the resulting shell script is executed, it determines at run time whether
  87 to invoke \fBgetopts\fR or \fBgetopt\fR.
  88 .RE
  89
  90 .SH EXAMPLES
  91 .LP
  92 \fBExample 1 \fRProcessing the arguments for a command
  93 .sp
  94 .LP
  95 The following fragment of a shell program shows how one might process the
  96 arguments for a command that can take the options \fB-a\fR or \fB-b\fR, as well
  97 as the option \fB-o\fR, which requires an option-argument:
  98
  99 .sp
 100 .in +2
 101 .nf
 102 while getopts abo: c
 103 do
 104       case $c in
 105       a | b)     FLAG=$c;;
 106       o)         OARG=$OPTARG;;
 107       \e?)        echo $USAGE
 108                  exit 2;;
 109       esac
 110 done
 111 shift `expr $OPTIND \(mi 1`
 112 .fi
 113 .in -2
 114
 115 .LP
 116 \fBExample 2 \fREquivalent code expressions
 117 .sp
 118 .LP
 119 This code accepts any of the following as equivalent:
 120
 121 .sp
 122 .in +2
 123 .nf
 124 \fBcmd -a -b -o "xxx z yy" filename
 125 cmd -a -b -o "xxx z yy" -filename
 126 cmd -ab -o xxx,z,yy filename
 127 cmd -ab -o "xxx z yy" filename
 128 cmd -o xxx,z,yy b a filename\fR
 129 .fi
 130 .in -2
 131 .sp
 132
 133 .SH ENVIRONMENT VARIABLES
 134 .sp
 135 .LP
 136 See \fBenviron\fR(5) for descriptions of the following environment variables
 137 that affect the execution of \fBgetopts\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR,
 138 and \fBNLSPATH\fR.
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBOPTIND\fR \fR
 143 .ad
 144 .RS 11n
 145 This variable is used by \fBgetoptcvt\fR as the index of the next argument to
 146 be processed.
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fBOPTARG\fR \fR
 153 .ad
 154 .RS 11n
 155 This variable is used by \fBgetoptcvt\fR to store the argument if an option is
 156 using arguments.
 157 .RE
 158
 159 .SH EXIT STATUS
 160 .sp
 161 .LP
 162 The following exit values are returned:
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fB0\fR \fR
 167 .ad
 168 .RS 7n
 169 An option, specified or unspecified by \fIoptstring\fR, was found.
 170 .RE
 171
 172 .sp
 173 .ne 2
 174 .na
 175 \fB\fB>0\fR \fR
 176 .ad
 177 .RS 7n
 178 The end of options was encountered or an error occurred.
 179 .RE
 180
 181 .SH ATTRIBUTES
 182 .sp
 183 .LP
 184 See \fBattributes\fR(5) for descriptions of the following attributes:
 185 .sp
 186
 187 .sp
 188 .TS
 189 box;
 190 c | c
 191 l | l .
 192 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 193 CSI     enabled
 194 .TE
 195
 196 .SH SEE ALSO
 197 .sp
 198 .LP
 199 \fBIntro\fR(1), \fBgetopts\fR(1), \fBsh\fR(1), \fBshell_builtins\fR(1),
 200 \fBgetopt\fR(3C), \fBattributes\fR(5)
 201 .SH DIAGNOSTICS
 202 .sp
 203 .LP
 204 \fBgetopts\fR prints an error message on the standard error when it encounters
 205 an option letter not included in \fIoptstring\fR.
 206 .SH NOTES
 207 .sp
 208 .LP
 209 Although the following command syntax rule (see \fBIntro\fR(1)) relaxations are
 210 permitted under the current implementation, they should not be used because
 211 they may not be supported in future releases of the system. As in the EXAMPLES
 212 section above, \fB-a\fR and \fB-b\fR are options, and the option \fB-o\fR
 213 requires an option-argument. The following example violates Rule 5:  options
 214 with option-arguments must not be grouped with other options:
 215 .sp
 216 .in +2
 217 .nf
 218 example% \fBcmd -aboxxx filename\fR
 219 .fi
 220 .in -2
 221 .sp
 222
 223 .sp
 224 .LP
 225 The following example violates Rule 6: there must be white space after an
 226 option that takes an option-argument:
 227 .sp
 228 .in +2
 229 .nf
 230 example% \fBcmd -ab oxxx filename\fR
 231 .fi
 232 .in -2
 233 .sp
 234
 235 .sp
 236 .LP
 237 Changing the value of the shell variable \fBOPTIND\fR or parsing different sets
 238 of arguments may lead to unexpected results.