git.saurik.com Git - apple/shell_cmds.git/blame_incremental

... / ...

Commit	Line	Data
	1	.\" $NetBSD: getopt.1,v 1.8 1997/10/19 02:16:57 lukem Exp $
	2	.Dd June 21, 1993
	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	);
	20	if a letter is followed by a colon, the option
	21	is expected to have an argument which may or may not be
	22	separated from it by white space.
	23	The special option
	24	.Dq \-\-
	25	is used to delimit the end of the options.
	26	.Nm
	27	will place
	28	.Dq \-\-
	29	in the arguments at the end of the options,
	30	or recognize it if used explicitly.
	31	The shell arguments
	32	(\fB$1 $2\fR ...) 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	.Sh EXAMPLE
	38	The following code fragment shows how one might process the arguments
	39	for a command that can take the options
	40	.Op a
	41	and
	42	.Op b ,
	43	and the option
	44	.Op o ,
	45	which requires an argument.
	46	.Pp
	47	.Bd -literal -offset indent
	48	args=\`getopt abo: $*\`
	49	if test $? != 0
	50	then
	51	echo 'Usage: ...'
	52	exit 2
	53	fi
	54	set \-\- $args
	55	for i
	56	do
	57	case "$i"
	58	in
	59	\-a\|\-b)
	60	flag=$i; shift;;
	61	\-o)
	62	oarg=$2; shift; shift;;
	63	\-\-)
	64	shift; break;;
	65	esac
	66	done
	67	.Ed
	68	.Pp
	69	This code will accept any of the following as equivalent:
	70	.Pp
	71	.Bd -literal -offset indent
	72	cmd \-aoarg file file
	73	cmd \-a \-o arg file file
	74	cmd \-oarg -a file file
	75	cmd \-a \-oarg \-\- file file
	76	.Ed
	77	.Pp
	78	.St -p1003.2
	79	mandates that the
	80	.Xr sh 1
	81	set command return the value of 0 for the exit status. Therefore,
	82	the exit status of the
	83	.Nm
	84	command is lost when
	85	.Nm
	86	and the
	87	.Xr sh 1
	88	set command are used on the same line. The example given
	89	is one way to detect errors found by
	90	.Nm "" .
	91	.Sh SEE ALSO
	92	.Xr sh 1 ,
	93	.Xr getopt 3
	94	.Sh DIAGNOSTICS
	95	.Nm
	96	prints an error message on the standard error output when it
	97	encounters an option letter not included in
	98	.Op optstring .
	99	.Sh HISTORY
	100	Written by Henry Spencer, working from a Bell Labs manual page.
	101	Behavior believed identical to the Bell version.
	102	.Sh BUGS
	103	Whatever
	104	.Xr getopt 3
	105	has.
	106	.Pp
	107	Arguments containing white space or embedded shell metacharacters
	108	generally will not survive intact; this looks easy to fix but isn't.
	109	.Pp
	110	The error message for an invalid option is identified as coming
	111	from
	112	.Nm
	113	rather than from the shell procedure containing the invocation
	114	of
	115	.Nm "" ;
	116	this again is hard to fix.
	117	.Pp
	118	The precise best way to use the
	119	.Ic set
	120	command to set the arguments without disrupting the value(s) of
	121	shell options varies from one shell version to another.