154feed06SJason King.\" 254feed06SJason King.\" Copyright (c) 1988, 1991, 1993 354feed06SJason King.\" The Regents of the University of California. All rights reserved. 454feed06SJason King.\" 554feed06SJason King.\" Redistribution and use in source and binary forms, with or without 654feed06SJason King.\" modification, are permitted provided that the following conditions 754feed06SJason King.\" are met: 854feed06SJason King.\" 1. Redistributions of source code must retain the above copyright 954feed06SJason King.\" notice, this list of conditions and the following disclaimer. 1054feed06SJason King.\" 2. Redistributions in binary form must reproduce the above copyright 1154feed06SJason King.\" notice, this list of conditions and the following disclaimer in the 1254feed06SJason King.\" documentation and/or other materials provided with the distribution. 1354feed06SJason King.\" 3. Neither the name of the University nor the names of its contributors 1454feed06SJason King.\" may be used to endorse or promote products derived from this software 1554feed06SJason King.\" without specific prior written permission. 1654feed06SJason King.\" 1754feed06SJason King.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 1854feed06SJason King.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 1954feed06SJason King.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 2054feed06SJason King.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 2154feed06SJason King.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 2254feed06SJason King.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 2354feed06SJason King.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 2454feed06SJason King.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 2554feed06SJason King.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 2654feed06SJason King.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 2754feed06SJason King.\" SUCH DAMAGE. 2854feed06SJason King.\" 2954feed06SJason King.\" 3054feed06SJason King.\" Copyright 2018 Jason King 3154feed06SJason King.\" Copyright 2018, Joyent, Inc. 3231c9b836SRobert Mustacchi.\" Copyright 2020 Oxide Computer Company 3354feed06SJason King.\" 3431c9b836SRobert Mustacchi.Dd August 10, 2020 3554feed06SJason King.Dt GETOPT_LONG 3C 3654feed06SJason King.Os 3754feed06SJason King.Sh NAME 3854feed06SJason King.Nm getopt_long , 3931c9b836SRobert Mustacchi.Nm getopt_long_clip , 4054feed06SJason King.Nm getopt_long_only 4154feed06SJason King.Nd get long options from command line argument list 4254feed06SJason King.Sh SYNOPSIS 4354feed06SJason King.In getopt.h 4454feed06SJason King.Vt extern char *optarg ; 4554feed06SJason King.Vt extern int optind ; 4654feed06SJason King.Vt extern int optopt ; 4754feed06SJason King.Vt extern int opterr ; 4854feed06SJason King.Ft int 4954feed06SJason King.Fo getopt_long 5054feed06SJason King.Fa "int argc" 5154feed06SJason King.Fa "char * const *argv" 5254feed06SJason King.Fa "const char *optstring" 5354feed06SJason King.Fa "const struct option *longopts" 5454feed06SJason King.Fa "int *longindex" 5554feed06SJason King.Fc 5654feed06SJason King.Ft int 5754feed06SJason King.Fo getopt_long_only 5854feed06SJason King.Fa "int argc" 5954feed06SJason King.Fa "char * const *argv" 6054feed06SJason King.Fa "const char *optstring" 6154feed06SJason King.Fa "const struct option *longopts" 6254feed06SJason King.Fa "int *longindex" 6354feed06SJason King.Fc 6454feed06SJason King.Ft int 6554feed06SJason King.Fo getopt_long_clip 6654feed06SJason King.Fa "int argc" 6754feed06SJason King.Fa "char * const *argv" 6854feed06SJason King.Fa "const char *optstring" 6954feed06SJason King.Fa "const struct option *longopts" 7054feed06SJason King.Fa "int *longindex" 7154feed06SJason King.Fc 7254feed06SJason King.Sh DESCRIPTION 7354feed06SJason KingThe 7454feed06SJason King.Fn getopt_long 7554feed06SJason Kingfunction is similar to 7654feed06SJason King.Xr getopt 3C 7731c9b836SRobert Mustacchibut it accepts options in two forms: short options and long options. 7831c9b836SRobert MustacchiShort options are the traditional option flags that use a hyphen followed 7931c9b836SRobert Mustacchiby a single character. 8031c9b836SRobert MustacchiThis is the only form of option that is portable and it is supported by 8154feed06SJason King.Xr getopt 3C . 8231c9b836SRobert MustacchiNote, some implementation of 8331c9b836SRobert Mustacchi.Xr getopt 3C 8431c9b836SRobert Mustacchido support non-standard extensions for long options; however, these are 8531c9b836SRobert Mustacchinot portable and not considered in this manual page. 8631c9b836SRobert MustacchiCommon example of short options are: 8731c9b836SRobert Mustacchi.Fl a , 8831c9b836SRobert Mustacchi.Fl l , 8931c9b836SRobert Mustacchiand 9031c9b836SRobert Mustacchi.Fl r . 9131c9b836SRobert MustacchiLong options use two hyphen characters are generally full words. 9231c9b836SRobert MustacchiThe long versions of the above might be: 9331c9b836SRobert Mustacchi.Fl -all , 9431c9b836SRobert Mustacchi.Fl -list , 9531c9b836SRobert Mustacchiand 9631c9b836SRobert Mustacchi.Fl -recursive . 9731c9b836SRobert Mustacchi.Pp 9854feed06SJason KingThe 9954feed06SJason King.Fn getopt_long 10031c9b836SRobert Mustacchifunction can be used to: 10131c9b836SRobert Mustacchi.Bl -enum 10231c9b836SRobert Mustacchi.It 10331c9b836SRobert MustacchiSupport an option with both short and long forms. 10431c9b836SRobert Mustacchi.It 10531c9b836SRobert MustacchiSupport an option with only a short form. 10631c9b836SRobert Mustacchi.It 10731c9b836SRobert MustacchiSupport an option with only a long form. 10831c9b836SRobert Mustacchi.El 10954feed06SJason King.Pp 11031c9b836SRobert MustacchiTo have a short option selected, as with 11131c9b836SRobert Mustacchi.Xr getopt 3C , 11231c9b836SRobert Mustacchiit must be listed in 11331c9b836SRobert Mustacchi.Fa optstring . 11431c9b836SRobert MustacchiLong options are instead listed in the 11531c9b836SRobert Mustacchi.Fa longopts 11631c9b836SRobert Mustacchiarray. 11731c9b836SRobert MustacchiFor an option to have both a short and long form it must be present in 11831c9b836SRobert Mustacchiboth 11931c9b836SRobert Mustacchi.Fa optstring 12031c9b836SRobert Mustacchiand 12131c9b836SRobert Mustacchi.Fa longopts . 12231c9b836SRobert Mustacchi.Pp 12331c9b836SRobert MustacchiLong options can be handled in two different ways. 12431c9b836SRobert MustacchiIn the first way, every long option understood by the program has a 12531c9b836SRobert Mustacchicorresponding short option, and the option structure is only used to 12631c9b836SRobert Mustacchitranslate from long options to short options. 12754feed06SJason KingWhen used in this fashion, 12854feed06SJason King.Fn getopt_long 12954feed06SJason Kingbehaves identically to 13054feed06SJason King.Xr getopt 3C . 13154feed06SJason KingThis is a good way to add long option processing to an existing program 13254feed06SJason Kingwith the minimum of rewriting. 13354feed06SJason King.Pp 13454feed06SJason KingIn the second mechanism, a long option sets a flag in the 13554feed06SJason King.Vt option 13654feed06SJason Kingstructure passed, or will store a pointer to the command line argument 13754feed06SJason Kingin the 13854feed06SJason King.Vt option 13954feed06SJason Kingstructure passed to it for options that take arguments. 14054feed06SJason KingAdditionally, 14154feed06SJason Kingthe long option's argument may be specified as a single argument with 14254feed06SJason Kingan equal sign, e.g., 14354feed06SJason King.Pp 14454feed06SJason King.Dl "myprogram --myoption=somevalue" 14554feed06SJason King.Pp 14654feed06SJason KingWhen a long option is processed, the call to 14754feed06SJason King.Fn getopt_long 14854feed06SJason Kingwill return 0. 14954feed06SJason KingFor this reason, long option processing without 15054feed06SJason Kingshortcuts is not backwards compatible with 15154feed06SJason King.Xr getopt 3C . 15254feed06SJason King.Pp 15354feed06SJason KingIt is possible to combine these methods, providing for long options 15454feed06SJason Kingprocessing with short option equivalents for some options. 15554feed06SJason KingLess 15654feed06SJason Kingfrequently used options would be processed as long options only. 15754feed06SJason King.Pp 15854feed06SJason KingIn 15954feed06SJason King.Fn getopt_long 16054feed06SJason Kingand 16154feed06SJason King.Fn getopt_long_only , 16254feed06SJason King.Fa optstring 16354feed06SJason Kingacts similar to 16454feed06SJason King.Fa optstring 16554feed06SJason Kingin 16631c9b836SRobert Mustacchi.Xr getopt 3C , 16731c9b836SRobert Mustacchilisting the set of supported short option flags. 16854feed06SJason KingIn addition, 16954feed06SJason King.Fa optstring 17054feed06SJason Kingcan begin with 17154feed06SJason King.Ql + 17254feed06SJason Kingor 17354feed06SJason King.Ql - . 17454feed06SJason KingIf 17554feed06SJason King.Fa optstring 17654feed06SJason Kingbegins with 17754feed06SJason King.Ql + , 17854feed06SJason Kingthe first non-option terminates option processing. 17954feed06SJason KingThis is equivalent to setting the environment variable 18054feed06SJason King.Ev POSIXLY_CORRECT . 18154feed06SJason KingIf 18254feed06SJason King.Fa optstring 18354feed06SJason Kingbegins with 18454feed06SJason King.Ql - , 18554feed06SJason Kingnon-options are treated as options to the argument 18654feed06SJason King.Ql \e1 . 18754feed06SJason King.Pp 18854feed06SJason KingIf 18954feed06SJason King.Fa optstring 19054feed06SJason Kingdoes not begin with 19154feed06SJason King.Ql + 19254feed06SJason Kingand 19354feed06SJason King.Ev POSIXLY_CORRECT 19454feed06SJason Kingis not set, if 19554feed06SJason King.Ql W\&; 19654feed06SJason Kingappears in 19754feed06SJason King.Fa optstring , 19854feed06SJason King.Ql "-W myoption" 19954feed06SJason Kingis treated the same as 20054feed06SJason King.Ql "--myoption" 20154feed06SJason Kingand 20254feed06SJason King.Va optarg 20354feed06SJason Kingis set to 20454feed06SJason King.Ql myoption . 20554feed06SJason King.Pp 20654feed06SJason KingIn 20754feed06SJason King.Fn getopt_long_clip , 20854feed06SJason King.Ql + 20954feed06SJason Kingand 21054feed06SJason King.Ql - 21154feed06SJason Kingare ignored at the beginning of a string. 21254feed06SJason King.Pp 21354feed06SJason KingThe 21454feed06SJason King.Fn getopt_long , 21554feed06SJason King.Fn getopt_long_only , 21654feed06SJason Kingand 21754feed06SJason King.Fn getopt_long_clip 21854feed06SJason Kingfunctions require a structure to be initialized describing the long 21954feed06SJason Kingoptions. 22054feed06SJason KingThe structure is: 22154feed06SJason King.Bd -literal -offset indent 22254feed06SJason Kingstruct option { 22354feed06SJason King char *name; 22454feed06SJason King int has_arg; 22554feed06SJason King int *flag; 22654feed06SJason King int val; 22754feed06SJason King}; 22854feed06SJason King.Ed 22954feed06SJason King.Pp 23054feed06SJason KingThe 23154feed06SJason King.Fa name 23231c9b836SRobert Mustacchifield should contain the option name without the leading double hyphen. 23354feed06SJason King.Pp 23454feed06SJason KingThe 23554feed06SJason King.Fa has_arg 23654feed06SJason Kingfield should be one of: 23754feed06SJason King.Pp 23854feed06SJason King.Bl -tag -width ".Dv optional_argument" -offset indent -compact 23954feed06SJason King.It Dv no_argument 24054feed06SJason Kingno argument to the option is expected 24154feed06SJason King.It Dv required_argument 24254feed06SJason Kingan argument to the option is required 24354feed06SJason King.It Dv optional_argument 24454feed06SJason Kingan argument to the option may be presented 24554feed06SJason King.El 24654feed06SJason King.Pp 24754feed06SJason KingIf 24854feed06SJason King.Fa flag 24954feed06SJason Kingis not 25054feed06SJason King.Dv NULL , 25154feed06SJason Kingthen the integer pointed to by it will be set to the 25254feed06SJason Kingvalue in the 25354feed06SJason King.Fa val 25454feed06SJason Kingfield and 25554feed06SJason King.Va optopt 25654feed06SJason Kingwill be set to 25754feed06SJason King.Sy 0 . 25854feed06SJason KingIf the 25954feed06SJason King.Fa flag 26054feed06SJason Kingfield is 26154feed06SJason King.Dv NULL , 26254feed06SJason Kingthen the 26354feed06SJason King.Fa val 26454feed06SJason Kingfield will be returned and 26554feed06SJason King.Va optopt 26654feed06SJason Kingis set to the value in the 26754feed06SJason King.Fa val 26854feed06SJason Kingfield. 26954feed06SJason KingSetting 27054feed06SJason King.Fa flag 27154feed06SJason Kingto 27254feed06SJason King.Dv NULL 27354feed06SJason Kingand setting 27454feed06SJason King.Fa val 27554feed06SJason Kingto the corresponding short option will make this function act just 27654feed06SJason Kinglike 27754feed06SJason King.Xr getopt 3C . 27854feed06SJason King.Pp 27954feed06SJason KingIf the 28054feed06SJason King.Fa longindex 28154feed06SJason Kingfield is not 28254feed06SJason King.Dv NULL , 28354feed06SJason Kingthen the integer pointed to by it will be set to the index of the long 28454feed06SJason Kingoption relative to 28554feed06SJason King.Fa longopts . 28654feed06SJason King.Pp 28754feed06SJason KingThe last element of the 28854feed06SJason King.Fa longopts 28954feed06SJason Kingarray has to be filled with zeroes. 29054feed06SJason King.Pp 29154feed06SJason KingThe 29254feed06SJason King.Fn getopt_long_only 29354feed06SJason Kingfunction behaves identically to 29454feed06SJason King.Fn getopt_long 29554feed06SJason Kingwith the exception that long options may start with 29654feed06SJason King.Ql - 29754feed06SJason Kingin addition to 29854feed06SJason King.Ql -- . 29954feed06SJason KingIf an option starting with 30054feed06SJason King.Ql - 30154feed06SJason Kingdoes not match a long option but does match a single-character option, 30254feed06SJason Kingthe single-character option is returned. 30354feed06SJason King.Pp 30454feed06SJason KingThe 30554feed06SJason King.Fn getopt_long_clip 30654feed06SJason Kingfunction is a variation of 30754feed06SJason King.Fn getopt_long 30854feed06SJason Kingexcept that options must also adhere to the Sun CLIP specification. 30954feed06SJason KingSpecifically, the major differences from 31054feed06SJason King.Fn getopt_long 31154feed06SJason Kingare: 31254feed06SJason King.Bl -bullet -offset indent 31354feed06SJason King.It 31454feed06SJason KingAll option arguments are required 31554feed06SJason King.Po 31654feed06SJason King.Dv optional_argument 31754feed06SJason Kingis treated the same as 31854feed06SJason King.Dv required_argument 31954feed06SJason King.Pc . 32054feed06SJason King.It 32154feed06SJason KingLong options cannot be abbreviated on the command line. 32254feed06SJason King.It 32331c9b836SRobert MustacchiLong options must use a double hyphen 32454feed06SJason King.Pq Ql -- . 32554feed06SJason King.It 32654feed06SJason KingOption processing stops at the first non-option. 32754feed06SJason King.It 32831c9b836SRobert MustacchiAll long options must have an equivalent short option (single character) and 32954feed06SJason Kingvice-versa. 33054feed06SJason King.It 33154feed06SJason KingA leading 33254feed06SJason King.Ql + 33354feed06SJason Kingor 33454feed06SJason King.Ql - 33554feed06SJason Kingin 33654feed06SJason King.Fa optstring 33754feed06SJason Kingis ignored. 33854feed06SJason King.Fa optstring 33954feed06SJason Kingis treated as if it began after the leading 34054feed06SJason King.Ql + 34154feed06SJason Kingor 34254feed06SJason King.Ql - . 34354feed06SJason King.El 34454feed06SJason King.Pp 34554feed06SJason KingOn each call to 34654feed06SJason King.Fn getopt_long , 34754feed06SJason King.Fn getopt_long_only , 34854feed06SJason Kingor 34954feed06SJason King.Fn getopt_long , 35054feed06SJason King.Va optind 35154feed06SJason Kingis set to the 35254feed06SJason King.Va argv 35354feed06SJason Kingindex of the 35454feed06SJason King.Em next 35554feed06SJason Kingargument to be processed. 35654feed06SJason King.Va optind 35754feed06SJason Kingis initialized to 35854feed06SJason King.Sy 1 35954feed06SJason Kingprior to the first invocation of 36054feed06SJason King.Fn getopt_long , 36154feed06SJason King.Fn getopt_long_only , 36254feed06SJason Kingor 36354feed06SJason King.Fn getopt_long_clip . 36454feed06SJason King.Pp 36554feed06SJason KingIf 36654feed06SJason King.Va opterr 36754feed06SJason Kingis set to a non-zero value and 36854feed06SJason King.Fa optstring 36954feed06SJason Kingdoes not start with 37054feed06SJason King.Ql \&: , 37154feed06SJason King.Fn getopt_long , 37254feed06SJason King.Fn getopt_long_only , 37354feed06SJason Kingand 37454feed06SJason King.Fn getopt_long_clip 37554feed06SJason Kingwill print an error message to 37654feed06SJason King.Sy stderr 37754feed06SJason Kingwhen an error or invalid option is encountered. 37854feed06SJason King.Sh RETURN VALUES 37954feed06SJason KingIf the 38054feed06SJason King.Fa flag 38154feed06SJason Kingfield in 38254feed06SJason King.Vt "struct option" 38354feed06SJason Kingis 38454feed06SJason King.Dv NULL , 38554feed06SJason King.Fn getopt_long 38654feed06SJason Kingand 38754feed06SJason King.Fn getopt_long_only 38854feed06SJason Kingreturn the value specified in the 38954feed06SJason King.Fa val 39054feed06SJason Kingfield, which is usually just the corresponding short option. 39154feed06SJason KingIf 39254feed06SJason King.Fa flag 39354feed06SJason Kingis not 39454feed06SJason King.Dv NULL , 39554feed06SJason Kingthese functions return 0 and store 39654feed06SJason King.Fa val 39754feed06SJason Kingin the location pointed to by 39854feed06SJason King.Fa flag . 39954feed06SJason KingThese functions return 40054feed06SJason King.Ql \&: 40154feed06SJason Kingif there was a missing option argument, 40254feed06SJason King.Ql \&? 40354feed06SJason Kingif the user specified an unknown or ambiguous option, and 40454feed06SJason King\-1 when the argument list has been exhausted. 40554feed06SJason King.Pp 40654feed06SJason KingIf a long option to 40754feed06SJason King.Fn getopt_long_clip 40854feed06SJason Kingis missing its equivalent short option (or vice-versa),\-1 is returned on the 40954feed06SJason Kingfirst call to 41054feed06SJason King.Fn getopt_long_clip , 41154feed06SJason Kingand 41254feed06SJason King.Dv errno 41354feed06SJason Kingis set to 41454feed06SJason King.Er EINVAL . 41554feed06SJason KingIf 41654feed06SJason King.Va opterr 41754feed06SJason Kingis set to a non-zero value and 41854feed06SJason King.Fa optstring 41954feed06SJason Kingdoes not start with 42054feed06SJason King.Ql \&: , 42154feed06SJason Kingan error message will be written to 42254feed06SJason King.Sy stderr . 42354feed06SJason King.Pp 42454feed06SJason KingIf 42554feed06SJason King.Fa optstring 42654feed06SJason Kingdoes not start with 42754feed06SJason King.Ql \&: 42854feed06SJason Kingand 42954feed06SJason King.Fn getopt_long , 43054feed06SJason King.Fn getopt_long_only , 43154feed06SJason Kingor 43254feed06SJason King.Fn getopt_long_clip 43354feed06SJason Kingreturn 43454feed06SJason King.Ql \&: 43554feed06SJason Kingor 43654feed06SJason King.Ql \&? , 43754feed06SJason Kingif 43854feed06SJason King.Va opterr 43954feed06SJason Kingis set to a non-zero value, an error message is written to 44054feed06SJason King.Dv stderr . 44154feed06SJason King.Sh ENVIRONMENT 44254feed06SJason KingThe following environment variables can effect the execution of 44354feed06SJason King.Nm getopt_long , 44454feed06SJason King.Nm getopt_long_only , 44554feed06SJason Kingand 44654feed06SJason King.Nm getopt_long_clip : 44754feed06SJason King.Ev LANG , 44854feed06SJason King.Ev LC_ALL , 44954feed06SJason King.Ev LC_MESSAGES . 45054feed06SJason KingSee 451*bbf21555SRichard Lowe.Xr environ 7 . 45254feed06SJason King.Bl -tag -width ".Ev POSIXLY_CORRECT" 45354feed06SJason King.It Ev POSIXLY_CORRECT 45454feed06SJason KingIf set, option processing stops when the first non-option is found and 45554feed06SJason Kinga leading 45654feed06SJason King.Ql - 45754feed06SJason Kingor 45854feed06SJason King.Ql + 45954feed06SJason Kingin the 46054feed06SJason King.Fa optstring 46154feed06SJason Kingis ignored. 46254feed06SJason King.El 46354feed06SJason King.Sh USAGE 46454feed06SJason KingSimilar to 46554feed06SJason King.Xr getopt 3C , 46654feed06SJason Kingsince there is no unambiguous way to detect a missing option-argument except when the 46754feed06SJason Kingoption is the last option on the command line, the 46854feed06SJason King.Fn getopt_long , 46954feed06SJason King.Fn getopt_long_only , 47054feed06SJason Kingand 47154feed06SJason King.Fn getopt_long_clip 47254feed06SJason Kingfunctions cannot fully check for mandatory arguments. 47354feed06SJason KingFor example, the option string 47454feed06SJason King.Ql ho\&: 47554feed06SJason Kingwith an input of 47654feed06SJason King.Ql Fl o Fl h 47754feed06SJason Kingwill assume that 47854feed06SJason King.Ql Fl h 47954feed06SJason Kingis the required argument to 48054feed06SJason King.Fl o 48154feed06SJason Kinginstead of assuming that 48254feed06SJason King.Fl o 48354feed06SJason Kingis missing its option-argument. 48454feed06SJason King.Pp 48554feed06SJason KingLike 48654feed06SJason King.Xr getopt 3C , 48754feed06SJason Kinggrouping options taking or requiring arguments with other options is a violation of the 48854feed06SJason KingBasic Utility Command syntax standard (see 48954feed06SJason King.Xr Intro 1 ) . 49054feed06SJason KingFor example, given the option string 49154feed06SJason King.Ql cde\&: , 49254feed06SJason Kingrunning: 49354feed06SJason King.Pp 49454feed06SJason King.Dl cmd Fl cde Ar ieio 49554feed06SJason King.Pp 49654feed06SJason Kingis incorrect. 49754feed06SJason KingCurrent versions of 49854feed06SJason King.Nm getopt_long , 49954feed06SJason King.Nm getopt_long_only , 50054feed06SJason Kingand 50154feed06SJason King.Nm getopt_long_clip 50254feed06SJason Kingaccept this, however future versions may not support this. 50354feed06SJason KingThe correct invocation would be: 50454feed06SJason King.Pp 50554feed06SJason King.Dl cmd Fl cd Fl e Ar ieio 50654feed06SJason King.Sh EXAMPLES 50731c9b836SRobert Mustacchi.Sy Example 1 50831c9b836SRobert MustacchiBasic usage of 50931c9b836SRobert Mustacchi.Fn getopt_long . 51031c9b836SRobert Mustacchi.Pp 51131c9b836SRobert MustacchiIn this example, the short options, 51231c9b836SRobert Mustacchi.Fl b 51331c9b836SRobert Mustacchiand 51431c9b836SRobert Mustacchi.Fl f 51531c9b836SRobert Mustacchiare treated the same way as their corresponding long options 51631c9b836SRobert Mustacchi.Fl -buffy 51731c9b836SRobert Mustacchiand 51831c9b836SRobert Mustacchi.Fl -fluoride . 51931c9b836SRobert MustacchiThe long option 52031c9b836SRobert Mustacchi.Fl -daggerset 52131c9b836SRobert Mustacchiis only matched as a long option. 52231c9b836SRobert Mustacchi.Pp 52354feed06SJason King.Bd -literal -compact 52454feed06SJason Kingint bflag, ch, fd; 52554feed06SJason Kingint daggerset; 52654feed06SJason King 52754feed06SJason King/* options descriptor */ 52854feed06SJason Kingstatic struct option longopts[] = { 52954feed06SJason King { "buffy", no_argument, NULL, 'b' }, 53054feed06SJason King { "fluoride", required_argument, NULL, 'f' }, 53154feed06SJason King { "daggerset", no_argument, \*[Am]daggerset, 1 }, 53254feed06SJason King { NULL, 0, NULL, 0 } 53354feed06SJason King}; 53454feed06SJason King 53554feed06SJason Kingbflag = 0; 53654feed06SJason Kingwhile ((ch = getopt_long(argc, argv, "bf:", longopts, NULL)) != -1) { 53754feed06SJason King switch (ch) { 53854feed06SJason King case 'b': 53954feed06SJason King bflag = 1; 54054feed06SJason King break; 54154feed06SJason King case 'f': 54254feed06SJason King if ((fd = open(optarg, O_RDONLY, 0)) == -1) 54354feed06SJason King err(1, "unable to open %s", optarg); 54454feed06SJason King break; 54554feed06SJason King case 0: 54654feed06SJason King if (daggerset) { 54754feed06SJason King fprintf(stderr,"Buffy will use her dagger to " 54854feed06SJason King "apply fluoride to dracula's teeth\en"); 54954feed06SJason King } 55054feed06SJason King break; 55154feed06SJason King default: 55254feed06SJason King usage(); 55354feed06SJason King } 55454feed06SJason King} 55554feed06SJason Kingargc -= optind; 55654feed06SJason Kingargv += optind; 55754feed06SJason King.Ed 55831c9b836SRobert Mustacchi.Pp 55931c9b836SRobert Mustacchi.Sy Example 2 56031c9b836SRobert MustacchiMixing short-only and long-only options. 56131c9b836SRobert Mustacchi.Pp 56231c9b836SRobert MustacchiThis example has a program that uses both short and long options and 56331c9b836SRobert Mustacchialways causes the option to be handled in a way that is similar to 56431c9b836SRobert Mustacchi.Xr getopt 3C 56531c9b836SRobert Mustacchiregardless of if it is short or long. 56631c9b836SRobert MustacchiOptions that are only long options are assigned a character value that 56731c9b836SRobert Mustacchiis outside of the common 8-bit range 56831c9b836SRobert Mustacchi.Po 56931c9b836SRobert Mustacchistarting at 57031c9b836SRobert Mustacchi.Dv USHRT_MAX 57131c9b836SRobert Mustacchi+ 1. 57231c9b836SRobert Mustacchi.Pc 57331c9b836SRobert MustacchiThis allows them to still integrate into a normal 57431c9b836SRobert Mustacchi.Xr getopt 3C 57531c9b836SRobert Mustacchistyle option processing loop. 57631c9b836SRobert Mustacchi.Pp 57731c9b836SRobert MustacchiIn the following code, 57831c9b836SRobert Mustacchi.Fl s 57931c9b836SRobert Mustacchiis only usable as a short option while 58031c9b836SRobert Mustacchi.Fl -long-only 58131c9b836SRobert Mustacchiis only usable as a long option, hence 58231c9b836SRobert Mustacchi.Fl s 58331c9b836SRobert Mustacchiis only specified in 58431c9b836SRobert Mustacchi.Fa optstring 58531c9b836SRobert Mustacchiand 58631c9b836SRobert Mustacchi.Fl -long-only 58731c9b836SRobert Mustacchiis only specified in the 58831c9b836SRobert Mustacchi.Fa longopts 58931c9b836SRobert Mustacchi.Vt option 59031c9b836SRobert Mustacchiarray. 59131c9b836SRobert Mustacchi.Pp 59231c9b836SRobert Mustacchi.Bd -literal -compact 59331c9b836SRobert Mustacchi#include <getopt.h> 59431c9b836SRobert Mustacchi#include <stdio.h> 59531c9b836SRobert Mustacchi#include <limits.h> 59631c9b836SRobert Mustacchi 59731c9b836SRobert Mustacchienum longopt_chars { 59831c9b836SRobert Mustacchi LONG_ONLY = USHRT_MAX +1 59931c9b836SRobert Mustacchi}; 60031c9b836SRobert Mustacchi 60131c9b836SRobert Mustacchistatic struct option longopts[] = { 60231c9b836SRobert Mustacchi { "all", no_argument, NULL, 'a' }, 60331c9b836SRobert Mustacchi { "list", no_argument, NULL, 'l' }, 60431c9b836SRobert Mustacchi { "long-only", no_argument, NULL, LONG_ONLY }, 60531c9b836SRobert Mustacchi { "output", required_argument, NULL, 'o' }, 60631c9b836SRobert Mustacchi { NULL } 60731c9b836SRobert Mustacchi}; 60831c9b836SRobert Mustacchi 60931c9b836SRobert Mustacchiint 61031c9b836SRobert Mustacchimain(int argc, char *argv[]) 61131c9b836SRobert Mustacchi{ 61231c9b836SRobert Mustacchi int ch; 61331c9b836SRobert Mustacchi 61431c9b836SRobert Mustacchi while ((ch = getopt_long(argc, argv, "alo:s", longopts, 61531c9b836SRobert Mustacchi NULL)) != -1) { 61631c9b836SRobert Mustacchi switch (ch) { 61731c9b836SRobert Mustacchi case 'a': 61831c9b836SRobert Mustacchi printf("found -a\en"); 61931c9b836SRobert Mustacchi break; 62031c9b836SRobert Mustacchi case 'l': 62131c9b836SRobert Mustacchi printf("found -l\en"); 62231c9b836SRobert Mustacchi break; 62331c9b836SRobert Mustacchi case 'o': 62431c9b836SRobert Mustacchi printf("found -o: %s\en", optarg); 62531c9b836SRobert Mustacchi break; 62631c9b836SRobert Mustacchi case 's': 62731c9b836SRobert Mustacchi printf("found -s\en"); 62831c9b836SRobert Mustacchi break; 62931c9b836SRobert Mustacchi case LONG_ONLY: 63031c9b836SRobert Mustacchi printf("found --long-only\en"); 63131c9b836SRobert Mustacchi break; 63231c9b836SRobert Mustacchi default: 63331c9b836SRobert Mustacchi break; 63431c9b836SRobert Mustacchi } 63531c9b836SRobert Mustacchi } 63631c9b836SRobert Mustacchi 63731c9b836SRobert Mustacchi return (0); 63831c9b836SRobert Mustacchi} 63931c9b836SRobert Mustacchi.Ed 64054feed06SJason King.Sh ERRORS 64154feed06SJason KingThe 64254feed06SJason King.Fn getopt_long_clip 64354feed06SJason Kingfunction will fail if: 64454feed06SJason King.Bl -tag -width EINVAL 64554feed06SJason King.It Er EINVAL 64654feed06SJason KingA short option is missing a corresponding long option, or vice-versa. 64754feed06SJason King.El 64854feed06SJason King.Pp 64954feed06SJason KingThere are no errors defined for 65054feed06SJason King.Fn getopt_long 65154feed06SJason Kingand 65254feed06SJason King.Fn getopt_long_only . 65354feed06SJason King.Sh IMPLEMENTATION DIFFERENCES 65454feed06SJason KingWhile the illumos implementations of 65554feed06SJason King.Nm getopt_long 65654feed06SJason Kingand 65754feed06SJason King.Nm getopt_long_only 65854feed06SJason Kingare broadly compatible with other implementations, the following edge cases 65954feed06SJason Kinghave historically been known to vary among implementations: 66054feed06SJason King.Bl -bullet 66154feed06SJason King.It 66254feed06SJason KingThe setting of 66354feed06SJason King.Va optopt 66454feed06SJason Kingfor long options with 66554feed06SJason King.Fa flag 66654feed06SJason King!= 66754feed06SJason King.Dv NULL 66854feed06SJason Kingin 66954feed06SJason King.Vt struct option . 67054feed06SJason KingIn illumos, 67154feed06SJason King.Va optopt 67254feed06SJason Kingis set to 0 (since 67354feed06SJason King.Fa val 67454feed06SJason Kingwould never be returned). 67554feed06SJason King.It 67654feed06SJason KingThe setting of 67754feed06SJason King.Va optarg 67854feed06SJason Kingfor long options without an argument that are 67954feed06SJason Kinginvoked via 68054feed06SJason King.Ql -W 68154feed06SJason King.Ql ( W\&; 68254feed06SJason Kingin 68354feed06SJason King.Fa optstring ) . 68454feed06SJason Kingillumos sets 68554feed06SJason King.Va optarg 68654feed06SJason Kingto the option name (the argument of 68754feed06SJason King.Ql -W ) . 68854feed06SJason King.It 68954feed06SJason KingThe handling of 69054feed06SJason King.Ql -W 69154feed06SJason Kingwith an argument that is not (a prefix to) a known 69254feed06SJason Kinglong option 69354feed06SJason King.Ql ( W\&; 69454feed06SJason Kingin 69554feed06SJason King.Fa optstring ) . 69654feed06SJason Kingillumos treats this as an error (unknown option) and returns 69754feed06SJason King.Ql \&? 69854feed06SJason Kingwith 69954feed06SJason King.Va optopt 70054feed06SJason Kingset to 0 and 70154feed06SJason King.Va optarg 70254feed06SJason Kingset to 70354feed06SJason King.Dv NULL . 70454feed06SJason King.It 70554feed06SJason Kingillumos 70654feed06SJason Kingmay not permute the argument vector at the same points in 70754feed06SJason Kingthe calling sequence as other implementations. 70854feed06SJason KingThe aspects normally used by 70954feed06SJason Kingthe caller (ordering after \-1 is returned, the value of 71054feed06SJason King.Va optind 71154feed06SJason Kingrelative 71254feed06SJason Kingto current positions) are the same, though. 71354feed06SJason King(We often do fewer variable swaps.) 71454feed06SJason King.El 71554feed06SJason King.Sh INTERFACE STABILITY 71654feed06SJason KingCommitted 71754feed06SJason King.Sh MT-LEVEL 71854feed06SJason KingUnsafe 71954feed06SJason King.Sh SEE ALSO 72054feed06SJason King.Xr getopt 3C 72154feed06SJason King.Sh BUGS 72254feed06SJason KingThe 72354feed06SJason King.Fa argv 72454feed06SJason Kingargument is not really 72554feed06SJason King.Vt const 72654feed06SJason Kingas its elements may be permuted (unless 72754feed06SJason King.Ev POSIXLY_CORRECT 72854feed06SJason Kingis set). 729