GETOPTS(3)

💖 NAME 💖

okay so bestie, gather round — getopts is a libbash library for parsing command line parameters. that's the whole vibe. parsing. arguments. slay.

---

✨ SYNOPSIS ✨

$retval getopt_long ⟨Instructions⟩ ⟨Parameters⟩

---

🦋 DESCRIPTION 🦋

so this is the docs for the libbash getopts library, and it implements the getopt_long function for bash(1). if you're actually looking for the docs of bash's own getopts function, bestie you're in the wrong room — go see getopts(1) (or getopts(1posix) on some systems, depending on where you live).

here's the reference rundown so you don't get confused, because there are so many things named basically the same thing:

• getopts(1) — (or 1posix on some systems) implemented by bash
• getopts(3) — implemented by libbash
• getopt(1) — implemented by getopt utils (part of util-linux)
• getopt_long(1) — implemented by libbash and installed to section 1 instead of 3 to prevent collision with C man pages
• getopt(3) — implemented by GNU C library
• getopt_long(3) — implemented by GNU C library

and yeah, i've also seen a separate getopt utility which is part of the util-linux package. the naming situation is a whole mess, no cap.

the getopt_long function parses the command line arguments. it uses Instructions as the rules for parsing the Parameters. that's it. that's the whole job. 💅

🎀 The Instructions 🎀

Instructions is a string that specifies rules for parameters parsing. the instructions string is built of a group of independent instructions, separated by a white space. each instruction must have the following structure:

-<SingleLetter>|--<MultiLetter>-><VariableName>[:]

this structure contains three parts:

• -<SingleLetter> — this is the parameter single-letter sign. for example -h.
• --<MultiLetter> — this is the parameter's corresponding multi-letter sign. for example --help.
• <VariableName>[:] — this is the name of the variable that will contain the parameter value. for example: HELP.

so the Variable name can represent one of two variables types:

• Flag variable (not followed by :) — in this case, it will hold the value 1 if 'on' (i.e. was specified on command line) and will not be defined if 'off'. it's giving light switch energy honestly.
• Value variable (followed by :) — in this case, the value it will hold is the string that was given as the next parameter in the Parameters string (separated by white-space or =). if input contains more then one instance of the considered command line option, an array of the given parameters will be set as the value of the variable. iconic behaviour fr fr.

🌸 The Parameters 🌸

the Parameters are simply the parameters you wish to parse. that's literally it. no tricks. 🫶

---

👑 RETURN VALUE 👑

this function returns a string that contains a set of variables definitions. in order to define the variables, this string should be given as a parameter to eval function. this value is returned in the variable $retval.

yes bestie you have to eval it. that's the deal. that's the contract. 💀

---

🔥 EXAMPLES 🔥

parse command line parameters looking for the flags -h | --help and -v | --version and for the value -p | --path:

getopt_long '-h|--help->HELP
              -v|--version->VERSION
              -p|--path->PATH:' $*
eval $retval

in this example, for the parameters --help --path=/usr/ the variables that will be created are:

HELP=1
PATH=/usr/

for the parameters --help --path=/usr --path=/bin the variables that will be created are:

HELP=1
PATH=(/usr /bin)

look at that array pop off. 🍓

---

💀 BUGS 💀

values must not contain the string __getopts__. this string will be parsed as a single white-space.

a value should not start with an already defined multi-letter sign. if such a value exists, it will be treated as the equivalent singe-letter sign. this bug only accures when using a single-letter sign, or a multi-letter sign that are not followed by a =.

for example: if we have a script named foo, and we parse the parameters -d|--dir: and -f|--file:, then

foo -d --file

and

foo --dir --file

will not work

foo --dir=--file

will work.

okay so lowkey this one bites people. the = is doing heavy lifting here. don't forget it. 🙈

---

💜 AUTHORS 💜

• Hai Zaar <haizaar@haizaar.com>
• Gil Ran <gil@ran4.net>

---

🌈 SEE ALSO 🌈

ldbash(1), getopt_long(1), getopts(1), getopt(1), libbash(1), getopt(3), getopt_long(3)

---

and that's a wrap bestie 🎀 this page came out of the Linux source, it's UNDATED (yes, no date, we don't know when, and honestly? mysterious main character energy ✨), and it's filed under GETOPTS(3) for the LOCAL manual. go parse some args, you're gonna eat. 💅🦋