---
name: "getopts"
section: "3"
platform: "linux"
package: "libbash"
version: "0.9.11-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/getopts/3"
---

# getopts(3)

libbash library for command line parameters parsing

## NAME

**getopts** – libbash library for command line parameters parsing

## SYNOPSIS

*$retval*\
 **getopt\_long** ⟨Instructions⟩ ⟨Parameters⟩

## DESCRIPTION

This is a documentation for *libbash* getopts library, that implements *getopt\_long* function for [bash(1)](/bash/1.md). For documentation of bash getopts function, please see [getopts(1)](/getopts/1.md) ( getopts(1posix) on some systems).

Here is a table for reference:

- [getopts(1)](/getopts/1.md)

  (or 1posix on some systems) implemented by *bash*

- [getopts(3)](/getopts/3.md)

  implemented by *libbash*.

- [getopt(1)](/getopt/1.md)

  implemented by getopt utils (part of util-linux)

- [getopt\_long(1)](/getopt_long/1.md)

  implemented by *libbash* and installed to section 1 instead of 3 to prevent collision with C man pages.

- [getopt(3)](/getopt/3.md)

  implemented by GNU C library.

- [getopt\_long(3)](/getopt_long/3.md)

  implemented by GNU C library.

I have also seen separate getopt utility which part of util-linux package.

The  *getopt\_long* function parses the command line arguments.  It uses *Instructions* as the rules for parsing the *Parameters*.

### The Instructions

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**.

  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’.

  - **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.

### The Parameters

The  *Parameters* are simply the parameters you wish to parse.

## 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*.

## 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)
```

## 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.

## AUTHORS

Hai Zaar ⟨haizaar@haizaar.com⟩ Gil Ran ⟨gil@ran4.net⟩

## SEE ALSO

[ldbash(1)](/ldbash/1.md), [getopt\_long(1)](/getopt_long/1.md), [getopts(1)](/getopts/1.md), [getopt(1)](/getopt/1.md), libbash(1), [getopt(3)](/getopt/3.md), [getopt\_long(3)](/getopt_long/3.md)