getopt_long_only man page on Solaris

Man page or keyword search:  
man Server   20652 pages
apropos Keyword Search (all sections)
Output format
Solaris logo
[printable version]

getopt_long(3C)		 Standard C Library Functions	       getopt_long(3C)

NAME
       getopt_long, getopt_long_only, getopt_clip - parse long command options

SYNOPSIS
       #include <getopt.h>

       int  getopt_long(int  argc,  char * const *argv, const char *shortopts,
       const struct option *longopts, int *indexptr);

       int getopt_long_only(int argc, char * const *argv, const	 char  *short‐
       opts, const struct option *longopts, int *indexptr);

       int  getopt_clip(int  argc,  char * const *argv, const char *shortopts,
       const struct option *longopts, int *indexptr);
       extern char *optarg;
       extern int optind, opterr, optopt;

DESCRIPTION
       These functions are provided as a porting aid for  GNU/Freeware/OpenBSD
       utilities. The getopt_long() function is intended to be as closely com‐
       patible with the GNU and OpenBSD implementations as possible, but since
       these  public  implementations  differ  in some corner cases, it is not
       possible to be fully compatible with both. The differences are  enumer‐
       ated in the NOTES section.

       The  getopt_long()  function is an aid for implementing the GNU command
       line argument conventions. See the GNU documentation for the details of
       these  conventions (glibc 2.2.3). Note that the GNU conventions are not
       POSIX-conforming. Most notably, the GNU conventions allow for  optional
       option-arguments	 and  do not enforce that operands must follow options
       on the command line.

       The  getopt_clip()  function   provides	 an   interface	  similar   to
       getopt_long()  except that it implements the Sun CLIP convention, which
       is slightly more restrictive than the GNU/Freeware conventions. CLIP is
       modeled after the GNU/Freeware conventions but removes POSIX violations
       and syntactic ambiguities (see intro(1)).  Specifically,	 getopt_clip()
       is  a  command line parser that can be used by applications that follow
       the Command Line Interface Paradigm or CLIP syntax guidelines 3, 4,  5,
       6,  7, 9, 10, 15, and 16. The remaining guidelines are not addressed by
       getopt_clip() and are the responsibility of the application.

       The getopt_long() function is similar  to  getopt(3C)  except  that  it
       accepts options in two forms: words and characters, also referred to as
       long options and short options.

       The getopt_long() function can be used in two ways. In the  first  way,
       every long option understood by the program is mapped to a single char‐
       acter that is usually a corresponding short option. The	option	struc‐
       ture  is	 used only to translate from long options to short options. In
       the second way, a long option sets  a  flag  specified  in  the	option
       structure,  or  stores  a  pointer  to the command line argument in the
       address passed to it for options that take arguments. These two methods
       apply individually to each long option. Both methods can be used in the
       same application.

       The  getopt_long()  function  accepts  command  lines  that  interleave
       options	and operands. The getopt_long() function reorders the elements
       of the argv argument such that when all	command	 line  arguments  have
       been  processed,	 all  operands	follow options (and their option-argu‐
       ments) in the argv array and optind points to the  first	 operand.  The
       order  of  options  relative  to other options and operands relative to
       other operands is maintained. The argument "--" is accepted as a delim‐
       iter  indicating	 the  end  of options. No argument reorder occurs past
       this delimeter. Argument reordering can not be unambiguously  performed
       in  all cases. The getopt_long() function depends on a number of inter‐
       nal heuristics to perform the reordering. The argc and  argv  arguments
       are  the	 argument  count  and  argument array as passed to main() (see
       exec(2)).

       The shortopts argument contains the short-option characters  recognized
       by  the	command	 using	these  functions. If a letter is followed by a
       colon (:), the option is	 expected  to  have  an	 option-argument  that
       should  be separated from it by white space. If a character is followed
       by two colons (::), the option takes an optional	 option-argument.  Any
       text  after the option name it is returned in optarg; otherwise, optarg
       is set to 0. A whitespace character can never be used  to  separate  an
       optional option-argument from its associated option.  If shortopts con‐
       tains the character "W" followed by a semicolon (;),  then  -W  foo  is
       treated as the long option --foo.

       If  the first character of the shortopts argument is the plus sign (+),
       getopt_long() enforces  the  POSIX  requirement	that  operands	follow
       options	on the command line by returning -1 and stopping argument pro‐
       cessing upon encountering the first operand (or	"--").	This  behavior
       can  also be specified by setting the environment variable POSIXLY_COR‐
       RECT.

       A hyphen (-) as the first character of the shortopts argument specifies
       that  options  and  operands  can be intermixed in argv but no argument
       reordering is performed. Operands are returned as arguments  to	option
       `\1', and option processing does not stop until "--" or the end of argv
       is found.

       If the first character of the shortopts	argument  (after  a  potential
       plus  or	 minus	character)  is	a  colon  (:),	a colon is returned by
       getopt_long() in response to a missing argument; otherwise, a  question
       mark (?) is returned for this condition.

       The  longopts  argument describes the long options to accept.  It is an
       array of struct option structures, one for each long option. The	 array
       is terminated with an element containing all zeros.

       The struct option structure contains the following members:

       const char *name	       Contains a pointer to the name of the option.

       int has_arg	       Specifies whether the option takes an argument.
			       The possible values, defined in <getopt.h>, are
			       no_argument,	  optional_argument,	   and
			       required_argument.

       int *flag	       Contains the address of an int variable that is
			       the  flag  for this option. The value contained
			       in val is stored in this location  to  indicate
			       that  the  option  was  seen. If flag is a null
			       pointer, then the value	contained  in  val  is
			       returned	 when this option is encountered, oth‐
			       erwise zero is returned.

       int val		       Contains the value to be stored at the variable
			       pointed to by flag or returned by getopt_long()
			       if flag is a null pointer.

       For any long option, getopt_long() returns the index in the array  lon‐
       gopts  of the options definition by storing it in indexptr. The name of
       the option  can	be  retrieved  with  longopts[(*indexptr)].name.  Long
       options	can be distinguished either by the values in their val members
       or by their indices. The indexptr variable can  also  distinguish  long
       options	that  set  flags.  The	value of indexptr after encountering a
       short option is undefined.

       If an option has an argument, the optarg	 global	 variable  is  set  to
       point to the start of the option argument on return from getopt_long();
       otherwise it is set to null. A long option can take an argument in  one
       of  two	forms: --option=arg or --option arg.  If the long option argu‐
       ment is optional, only the "--option=arg" form can be used  to  specify
       the  option  argument.  No  argument  is	 specified  by the simple form
       "--option". The form "--option="	 specifies  an	empty  string  as  the
       option argument.

       Long-option  names  can be abbreviated if the abbreviation is unique or
       an exact match for some defined option. An exact match takes precedence
       over an abbreviated match. Thus, if foo and foobar are acceptable long-
       option names, then specifying --foo on the command line always  matches
       the  former.   Specifying  --f or --fo would not be accepted as a match
       for either.

       The getopt_long() function places in optind the argv index of the  next
       argument to be processed. The optind global variable is external and is
       initialized to 1 before the first  call	to  getopt_long().   When  all
       options	have been processed (that is, up to the first non-option argu‐
       ment), getopt_long() returns -1. The special option "--" (two  hyphens)
       can  be used to delimit the end of the options; when it is encountered,
       -1 is returned and "—" is skipped.  This ooption is useful in  delimit‐
       ing non-option arguments that begin with "-" (hyphen).

       If  getopt_long()  encounters a short option character shortopts string
       or a long option not described in the longopts array,  it  returns  the
       question	 mark (?) character. It also returns a question mark (?) char‐
       acter in response to a missing option argument unless the first charac‐
       ter  of shortopts is a colon (:) (or the second character, if the first
       character is either a plus (+) or  a  minus  (-)),  in  which  case  it
       returns	a  colon  (:).	In either case, if the application has not set
       opterr to 0 and the first character of shortopts is not	a  colon  (:),
       getopt_long() prints a diagnostic message to stderr.

       The  getopt_long_only()	function  is  equivalent  to the getopt_long()
       function except that it allows the user of the application to pass long
       options	with only a single hyphen (-) instead of "--". The "--" prefix
       is still recognized. However, when a single hyphen (-) is  encountered,
       getopt_long_only()  attempts  to	 match this argument to a long option,
       including abreviations of the long option. If a long option starts with
       the  same character as a short option, a single hyphen followed by that
       character (and no other characters)  will  be  recognized  as  a	 short
       option.	Use  of	 getopt_long_only() is strongly discouraged by Sun and
       GNU for new applications.

       The behavior of getopt_clip() differs from that of getopt_long() in the
       following ways:

	 ·  The	 getopt_clip()	function does not perform argument reordering.
	    The getopt_clip() function always enforces the POSIX behavior that
	    all	 options should precede operands on the command line. Specifi‐
	    cally, getopt_clip() does not reorder arguments but returns -1 and
	    stops processing upon encountering the first operand argument.

	 ·
	    The	  environment	variable   POSIXLY_CORRECT   is	 ignored  (the
	    getopt_clip() function behaves as though it were set.)

	 ·  The plus and minus characters do not have a special meaning as the
	    first character of the shortopts argument. They are treated as any
	    other character (other than the colon) would be treated.

	 ·  Optional  option-arguments	are  not  allowed.  The	 behavior   of
	    getopt_clip()  when optional_argument is specified as the value of
	    has_arg in the longopts argument or double colons are included  in
	    the shortopts argument is unspecified.

	 ·  Long-option abbreviations are not recognized.

	 ·  Short options are required to have at least one long-option equiv‐
	    alent. That is, each character in shortopts must appear as the val
	    member  in	one  or	 more  option structures. Similarly, each long
	    option must have a short option equivalent, meaning that  the  val
	    member  of	each  option  structure	 must  appear in the shortopts
	    string.  If these requirements are not met, getopt_clip()  returns
	    -1 and sets errno to EINVAL.

RETURN VALUES
       For  short options (other than -W when W; is in shortopts), these func‐
       tions return the next option character specified on the	command	 line.
       For  long  options,  the value returned by these functions depends upon
       the value of the flag structure element for the identified  option.  If
       flag is NULL, the  value contained in the val structure element for the
       long option encountered on the command line  is	returned.   Otherwise,
       these functions return 0 (and the value specified in the val member for
       the long option is stored into the location pointed to by  flag).  When
       W;  is  in  shortopts and -W is encountered in the command line and the
       option argument to -W matches a long-option name, the return state from
       these functions is as if the long option had been encountered. However,
       if no argument is specified to the long option, optarg is  set  to  the
       option  argument of -W (the long-option name or unique prefix).	If the
       option argument of -W does not match a long option (or unique  prefix),
       the return state is as for any other short option.

       A colon (:) is returned if getopt_long() detects a missing argument and
       the first character of shortopts (other than a possible initial "+"  or
       "-") was a colon (':').

       A  question  mark (?) is returned if getopt_long() encounters an option
       letter not included in shortopts or detects a missing argument and  the
       first character of shortopts (other than a possible initial "+" or "-")
       was not a colon (:).

       The getopt_clip() function expects all short options  to	 have  one  or
       more  long-option  equivalent  and  all	long options to have one short
       option equivalent (see NOTES for details). If  proper  equivalents  are
       not found, getopt_clip() returns -1 and sets errno to EINVAL.

ERRORS
       The getopt_clip() function will fail if:

       EINVAL	       A  short	 option does not have at least one long-option
		       equivalent, or a long option does not have at least one
		       short-option equivalent.

EXAMPLES
       Example 1: Exmple using getopt().

       #include <unistd.h>
       #include <getopt.h>

       /* Flag set by `--verbose'. */
       static int verbose_flag;

       int
       main (int argc, char **argv)
       {
	 int c;

	 while (1) {
	   static struct option long_options[] = {
	     /* These options set a flag. */
	     {"verbose", no_argument, &verbose_flag, 1},
	     {"brief",	 no_argument, &verbose_flag, 0},
	     /* The following options don't set a flag. */
	     {"add",	 no_argument, NULL, 'a'},
	     {"append",	 no_argument, NULL, 'b'},
	     {"delete",	 required_argument, NULL, 'd'},
	     {"create",	 required_argument, NULL, 'c'},
	     {"file",	 required_argument, NULL, 'f'},
	     {0, 0, 0, 0}
	   };
	   /* getopt_long stores the option index here. */
	   int option_index = 0;

	   c = getopt_long (argc, argv, "abc:d:f:",
			    long_options, &option_index);

	   /* Detect the end of the options. */
	   if (c == -1)
	     break;

	   switch (c) {
	     case 0:
	       /* (In this example) only options which set */
	       /* a flag return zero, so do nothing. */
	       break;

	     case 'a':
	       puts ("option --add (-a)\n");
	       break;

	     case 'b':
	       puts ("option --append (-b)\n");
	       break;

	     case 'c':
	       printf ("option --create (-c) with value `%s'\n", optarg);
	       break;

	     case 'd':
	       printf ("option --delete (-d) with value `%s'\n", optarg);
	       break;

	     case 'f':
	       printf ("option --file (-f) with value `%s'\n", optarg);
	       break;

	     case '?':
	       /* getopt_long already printed an error message. */
	       break;

	     default:
	       abort ();
	   }
	 }

	 /* Instead of reporting `--verbose'
	    and `--brief' as they are encountered,
	    we report the final status resulting from them. */
	 if (verbose_flag)
	   puts ("verbose flag is set");

	 /* Print any remaining command line arguments (not options). */
	 if (optind < argc) {
	     printf ("non-option ARGV-elements: ");
	     while (optind < argc)
	       printf ("%s ", argv[optind++]);
	     putchar ('\n');
	   }

	 exit (0);
       }

ENVIRONMENT VARIABLES
       See  environ(5) for descriptions of the following environment variables
       that affect the execution of getopt_long(): LANG, LC_ALL,  and  LC_MES‐
       SAGES.

       POSIXLY_CORRECT	       When set (and the first character of the short‐
			       opts argument is neither a plus or minus sign),
			       the  POSIX  rule	 that all operands must follow
			       all options is enforced. Option processing ter‐
			       minates	when the first operand is encountered.
			       The getopt_clip() function ignores the  setting
			       of  POSIXLY_CORRECT and always behaves as if it
			       were set.

       LC_CTYPE			Determine the locale for the interpretation of
			       sequences  of  bytes as characters in shortopts
			       and the longopts[].name structure members.

USAGE
       The getopt_long() function does not fully check for mandatory arguments
       because	there  is  no  unambiguous algorithm to do so. Given an option
       string a:b and the input -a -b, getopt_long() assumes that  -b  is  the
       mandatory argument to the -a option and not that -a is missing a manda‐
       tory argument. Indeed, the only time a missing option argument  can  be
       reliably detected is when the option is the final option on the command
       line and is not followed by any command arguments.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌─────────────────────────────┬─────────────────────────────┐
       │      ATTRIBUTE TYPE	     │	    ATTRIBUTE VALUE	   │
       ├─────────────────────────────┼─────────────────────────────┤
       │Interface Stability	     │Evolving			   │
       ├─────────────────────────────┼─────────────────────────────┤
       │MT-Level		     │Unsafe			   │
       └─────────────────────────────┴─────────────────────────────┘

SEE ALSO
       intro(1), getopts(1), getopt(3C),  getsubopt(3C),  gettext(3C),	setlo‐
       cale(3C), attributes(5), environ(5), standards(5)

NOTES
       Use  of getopt_long() is discouraged for applications targeted strictly
       for Solaris. It should  be  used	 only  for  applications  targeted  at
       Solaris	and platforms that adhere to the GNU command line conventions.
       The getopt_long_only() function is provided  by	Solaris	 and  GNU  for
       legacy  applications and its use is discouraged by both current conven‐
       tions.

       The differences between the Solaris/GNU and OpenBSD versions  of	 these
       functions are as follows:

	 ·  The	 handling  of  the  hyphen  (-)	 as the first character of the
	    option string in presence of the environment variable POSIXLY_COR‐
	    RECT:

	    Solaris/GNU	    Operands  are returned as arguments to option '1',
			    and option processing does not stop until "--"  or
			    the end of argv is found.

	    OpenBSD	    obeys  POSIXLY_CORRECT and stops at the first non-
			    option.

	 ·  The handling of the hyphen	(-)  within  the  shortopts  parameter
	    string when not the first character.

	    Solaris/GNU	    treats  a single hyphen (-) on the command line as
			    an operand.

	    OpenBSD	    treats a single hyphen (-) on the command line  as
			    an	option. BSD recognizes this behavior as incor‐
			    rect, but maintains it for compatibility.

	 ·  The return value in the event of a missing argument if  the	 first
	    character after "+" or "-" in the option string is not a colon (:)

	    Solaris/GNU	    returns "?".

	    OpenBSD	    returns ":" (since OpenBSD's getopt does).

	 ·  The setting optopt for long options with flag != NULL:

	    Solaris/GNU	    sets optopt to val.

	    OpenBSD	    sets  optopt  to  0	 (since	 val  would  never  be
			    returned).

	 ·  The setting of optarg for long options without  an	argument  that
	    are invoked with -W (W; in option string):

	    Solaris/GNU	    sets  optarg  to  the option name (the argument of
			    -W).

	    OpenBSD	    sets optarg to NULL	 (the  argument	 of  the  long
			    option).

	 ·  The	  handling  of -W with an argument that is not (a prefix to) a
	    known long option (W; in option string):

	    Solaris/GNU	    returns 'W' with optarg set to the unknown option.

	    OpenBSD	    treats as an  error (unknown option)  and  returns
			    "?" with optopt set to 0 and optarg set to NULL.

	 ·  The error messages are different (all).

	 ·  The implementations do not permute the argument vector at the same
	    points in the calling sequence. The aspects normally used  by  the
	    caller (ordering after -1 is returned, value of optind relative to
	    current positions) are the same. Applications  should  not	depend
	    upon the ordering of the argument vector before -1 is returned.

SunOS 5.10			  10 May 2004		       getopt_long(3C)
[top]

List of man pages available for Solaris

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net