GETOPT(1)

💖 GETOPT(1) 💖

okay so this is the manual page for getopt — that's the User Commands one, bestie, not the C library thing (iykyk). Let's get into it 🫶

---

✨ NAME ✨

getopt — parse command options, but like, the enhanced version 💅

---

🌸 SYNOPSIS 🌸

getopt optstring parameters

getopt [options] [--] optstring parameters

getopt [options] -o|--options optstring [options] [--] parameters

---

🦋 DESCRIPTION 🦋

So here's the vibe: getopt breaks up (parses) the options in command lines so your shell procedures can deal with them without losing their minds, and it also checks that the options are actually valid. It does all this by using the GNU getopt(3) routines underneath. no cap.

The parameters you call getopt with split into two parts, and this is the part where everyone gets confused so pay attention:

• the options that change how getopt does its parsing — that's the options and the optstring in the SYNOPSIS
• the parameters that are gonna get parsed — that's parameters in the SYNOPSIS

That second part starts at the first non-option parameter that isn't an option argument, or right after the first time you hit --. And if there's no -o or --options option hanging out in the first part, then the first parameter of the second part gets used as the short options string. iconic behavior honestly.

If the environment variable GETOPT_COMPATIBLE is set, or if the first parameter isn't an option (like, it doesn't start with a - — that's the first format in the SYNOPSIS), then getopt will generate output that's compatible with what other versions of getopt(1) spit out. It'll still do parameter shuffling and recognize optional arguments though — check the COMPATIBILITY section for the details.

Traditional implementations of getopt(1) literally cannot cope with whitespace and other (shell-specific) special characters in arguments and non-option parameters. 😭 To fix that whole situation, this implementation can generate quoted output which has to be interpreted by the shell again (usually by using the eval command). The effect is that those characters get preserved — but you have to call getopt in a way that's no longer compatible with other versions (that's the second or third format in the SYNOPSIS). And if you wanna know whether this enhanced version of getopt(1) is even installed on your machine, there's a special test option (-T) for exactly that. 💅

---

👑 OPTIONS 👑

• -a, --alternative — let long options start with a single -.
• -l, --longoptions longopts — the long (multi-character) options to be recognized. You can drop more than one option name at once by separating the names with commas or whitespace (spaces, tabs, or newlines). This option can be given more than once — the longopts are cumulative, they stack. Each long option name in longopts may be followed by one colon to say it has a required argument, and by two colons to say it has an optional argument.
• -n, --name progname — the name that the getopt(3) routines will use when they report errors. Heads up though: errors from getopt(1) itself are still reported as coming from getopt.
• -o, --options shortopts — the short (one-character) options to be recognized. If this option isn't found, the first parameter of getopt that doesn't start with a - (and isn't an option argument) gets used as the short options string. Each short option character in shortopts may be followed by one colon for a required argument, and two colons for an optional argument. Also, the first character of shortopts may be + or - to influence how options are parsed and how output is generated — see the SCANNING MODES section for the tea.
• -q, --quiet — disable error reporting by getopt(3).
• -Q, --quiet-output — don't generate normal output. Errors are still reported by getopt(3), unless you also use -q.
• -s, --shell shell — set the quoting conventions to those of shell. If the -s option isn't given, the BASH conventions are used. Valid arguments right now are sh, bash, csh, and tcsh.
• -T, --test — test whether your getopt(1) is this enhanced version or an old dusty one. This generates no output at all, and sets the error status to 4. Other implementations of getopt(1) — and this version too, if the environment variable GETOPT_COMPATIBLE is set — will return -- and error status 0.
• -u, --unquoted — do not quote the output. And ngl, whitespace and special (shell-dependent) characters can cause absolute havoc in this mode (like they do with other getopt(1) implementations). you've been warned 💀
• -U, --unknown — leave unknown options as they are and suppress error messages from getopt(3). Since there's no way to know whether an unknown option requires an argument, a non-option argument that follows the unknown option after a whitespace is considered an option argument — so the argument gets left untouched and printed next to the respective unknown option. To prevent unexpected behavior, short options should be specified individually.
• -h, --help — display help text and exit.
• -V, --version — display version and exit.

---

🔥 PARSING 🔥

This section specifies the format of the second part of the parameters of getopt (the parameters in the SYNOPSIS). The next section (OUTPUT) describes the output that gets generated. These parameters were typically the parameters a shell function was called with. And care must be taken that each parameter the shell function was called with corresponds to exactly one parameter in the parameter list of getopt (peep the EXAMPLES). All parsing is done by the GNU getopt(3) routines. periodt.

The parameters are parsed from left to right. Each parameter gets classified as one of these:

• a short option
• a long option
• an argument to an option
• a non-option parameter

A simple short option is a - followed by a short option character — except for the :, ; and ? characters, because those are reserved by getopt(3). If the option has a required argument, it may be written directly after the option character, or as the next parameter (i.e., separated by whitespace on the command line). If the option has an optional argument, it must be written directly after the option character if it's present.

You can specify several short options after one -, as long as all of them (except possibly the last) don't have required or optional arguments. slay.

A long option normally begins with -- followed by the long option name. If the option has a required argument, it may be written directly after the long option name separated by =, or as the next argument (i.e., separated by whitespace on the command line). If the option has an optional argument, it must be written directly after the long option name, separated by =, if present. (And if you add the = but put nothing behind it, it's interpreted as if no argument was present — yeah that's a slight bug, see the BUGS section.) Long options may be abbreviated, as long as the abbreviation isn't ambiguous.

Each parameter that doesn't start with a -, and isn't a required argument of a previous option, is a non-option parameter. And each parameter after a -- parameter is always interpreted as a non-option parameter. If the environment variable POSIXLY_CORRECT is set, or if the short option string started with a +, then all remaining parameters are interpreted as non-option parameters the second the first non-option parameter is found. no takebacks.

---

🌈 OUTPUT 🌈

Output is generated for each element described in the previous section. It's done in the same order as the elements are specified in the input — except for non-option parameters, those are the exception bestie. Output can be done in compatible (unquoted) mode, or in such a way that whitespace and other special characters within arguments and non-option parameters are preserved (see QUOTING). When the output is processed in the shell script, it'll seem to be composed of distinct elements that can be processed one by one (by using the shift command in most shell languages). This is imperfect in unquoted mode though, because elements can get split at unexpected places if they contain whitespace or special characters. 🙈

If there are problems parsing the parameters — like a required argument isn't found, or an option isn't recognized — an error gets reported on stderr, there will be no output for the offending element, and a non-zero error status is returned.

For a short option, a single - and the option character are generated as one parameter. If the option has an argument, the next parameter will be the argument. If the option takes an optional argument but none was found, the next parameter will be generated but be empty in quoting mode — while in unquoted (compatible) mode, no second parameter gets generated at all. And note: many other getopt(1) implementations do not support optional arguments. 😌

If several short options were specified after a single -, each one will be present in the output as a separate parameter.

For a long option, -- and the full option name are generated as one parameter. This happens regardless of whether the option was abbreviated or specified with a single - in the input. Arguments are handled the same as with short options.

Normally, no non-option parameters output is generated until all options and their arguments have been generated. Then -- is generated as a single parameter, and after it come the non-option parameters in the order they were found, each as a separate parameter. The only exception: if the first character of the short options string was a -, then non-option parameter output is generated at the place they're found in the input. (And that's not supported if the first format of the SYNOPSIS is used — in that case all preceding occurrences of - and + are ignored.)

---

💜 QUOTING 💜

In compatibility mode, whitespace or 'special' characters in arguments or non-option parameters are not handled correctly. Because the output gets fed to the shell script, the script has no idea how it's supposed to break the output into separate parameters. To get around this whole problem, this implementation offers quoting. The idea is simple: output gets generated with quotes around each parameter. Then when that output is fed to the shell again (usually by a shell eval command), it splits correctly into separate parameters. 🎀

Quoting is not enabled if:

• the environment variable GETOPT_COMPATIBLE is set,
• the first form of the SYNOPSIS is used, or
• the option -u is found.

Different shells use different quoting conventions, so you can use the -s option to pick the shell you're using. These are the shells currently supported: sh, bash, csh and tcsh. But actually — only two 'flavors' are distinguished: sh-like quoting conventions and csh-like quoting conventions. Chances are, if you're using some other shell script language, one of these flavors will still work for you. ✨

---

🌸 part 1 done — part 2 is coming with the rest, don't go anywhere bestie 💖

🌀 SCANNING MODES 🌀

Okay bestie, plot twist time: the very first character of your short options string can be a - or a +, and that little guy is doing a LOT of heavy lifting — it switches up the whole scanning mode. 💅

• If you're using the first calling form in the SYNOPSIS, those leading characters get ignored, bestie. Not important. But — and this is the sneaky part — the environment variable POSIXLY_CORRECT is still examined. So it's not like you get a free pass, okurrr. 🙈
• If the first character is +, or if the environment variable POSIXLY_CORRECT is set, parsing just stops the moment it finds the first non-option parameter (like, a parameter that doesn't start with a -) that isn't an option argument. Everything left over after that? All of it gets interpreted as non-option parameters. That's the whole rest of the line, no cap. ✋
• If the first character is -, non-option parameters get outputted right where they're found. Whereas in normal operation they all get collected at the end of output, after a -- parameter has been generated. And yes, that -- parameter is still generated in this mode too — it's just always gonna be the very last parameter. Periodt. 🎀

---

🤝 COMPATIBILITY 🤝

This version of getopt(1) is written to be as compatible as possible with other versions. Usually you can just swap them out with this one, no modifications, and get some advantages out of it. Slay. ✨

If the first character of the first parameter of getopt is not a -, getopt goes into compatibility mode. It'll interpret its first parameter as the string of short options, and all the other arguments get parsed. It will still do parameter shuffling (meaning all non-option parameters are output at the end) — unless the environment variable POSIXLY_CORRECT is set, in which case getopt will prepend a + before short options automatically. Look at it being helpful. 🫶

The environment variable GETOPT_COMPATIBLE forces getopt into compatibility mode. Setting both this environment variable and POSIXLY_CORRECT offers 100% compatibility for 'difficult' programs. Usually though? Neither is needed. Chill. 😌

In compatibility mode, leading - and + characters in the short options string are ignored. Gone. Bye. 💀

---

🚨 RETURN CODES 🚨

Listen up, because these matter:

• 0 — successful parsing, we ate that 💅
• 1 — getopt(3) returns errors
• 2 — it does not understand its own parameters (embarrassing, honestly)
• 3 — an internal error occurs, like out-of-memory 😭
• 4 — it is called with -T

---

🌈 EXAMPLES 🌈

Example scripts for (ba)sh and (t)csh are provided with the getopt(1) distribution, and they're installed in /usr/share/doc/util-linux. Go look, bestie, they're right there. 🎀

---

🌸 ENVIRONMENT 🌸

• POSIXLY_CORRECT — This environment variable is examined by the getopt(3) routines. If it's set, parsing stops as soon as a parameter is found that is not an option or an option argument. All remaining parameters are also interpreted as non-option parameters, regardless of whether they start with a -. Yes, even then. It does not care. 😤
• GETOPT_COMPATIBLE — Forces getopt to use the first calling format as specified in the SYNOPSIS.

---

💀 BUGS 💀

Not me exposing the flaws but okay, we keep it real here.

• getopt(3) can parse long options with optional arguments that are given an empty optional argument — but it cannot do this for short options. And this getopt(1) treats optional arguments that are empty as if they were not present. Wild, I know. 🙈
• The syntax for when you don't want any short option variables at all is not very intuitive. You literally have to set them explicitly to the empty string. It's giving "why is it like this" but that's just how it is. 😭

---

👑 AUTHOR 👑

Frodo Looijaard <frodo@frodo.looijaard.name> — iconic name, iconic author, no notes. ✨

---

🔗 SEE ALSO 🔗

bash(1), tcsh(1), getopt(3)

---

🐛 REPORTING BUGS 🐛

For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>. Found a problem? Tell them, bestie, they wanna know. 💖

---

📦 AVAILABILITY 📦

The getopt command is part of the util-linux package, which can be downloaded from the Linux Kernel Archive at <https://www.kernel.org/pub/linux/utils/util-linux/>. Go get your goodies. 🎁

---

And that's the whole page, bestie — this one's from <b>util-linux 2.42.4</b>, dated <b>2026-09-21</b>, and it's the <b>GETOPT(1)</b> manual. Go forth and parse responsibly. 💅✨🦋