---
name: "ggParseOptions"
section: "3"
platform: "linux"
package: "libgii1"
version: "1:1.0.2-4.1"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/ggParseOptions"
---

# ggParseOptions(3)

Option parsing

## NAME

**ggParseOptions** - Option parsing

## SYNOPSIS

```
#include <ggi/gg.h>
char *ggParseOptions(const char *str, gg_option *optlist, int count, int flag);
```

## DESCRIPTION

**ggParseOptions** parses a string *str* of options in LibGG's option  format and places the results in the ".name" members of the *optlist*.   The parameter *count* specifies the length of optlist.  The parameter *flags* is a bitwise or of values that alter behavior, the only one defined at this time being GG\_PARSEOPTS\_ALLOW\_UNKNOWN, which, if present, will cause ggParseOptions to ignore options found in the string for which there are no matching entries in optlist (normally this  generates a failure and a warning message).

The normal LibGG option format is defined as follows:

A colon or whitespace is the separator between options.

Option names consist of any character except parenthesis, colons,  whitespace characters, the equals sign ('=') and the NULL ('0')  character.

Option values may consist of any character except the NULL character, however in order to include colons, whitespace characters,  or parenthesis, the option must be quoted.  Option values that begin  with a single or double quote are considered to be quoted, and must end with the same quote character with which they began.  The quotes are  not considered to be part of the option value.  In order to include the quote character in use in  a quoted option value it must be escaped by  a backslash ('') character.  Backslashes always escape, even in  unquoted values, and so must always be escaped with a backslash in order to be included.

Named options begin with a dash (**-**) character followed by an option name and may be boolean (present or not) or may contain an equal sign  to assign the option a string value (everything following the equal sign up to the next forbidden character as described above.)  Matching is  case sensitive, but options can be abbreviated right down to a single  letter as long as the name remains unique among the entries in  *optlist* and the GG\_PARSEOPTS\_ALLOW\_UNKNOWN flag is not used.

Unnamed options do not (duh) have a name field and are positionally mapped to entries in *optlist*.  Unnamed options are processed after  the first option field not starting with a dash is encountered, and  occupy the rest of the option string.  They are assigned to any  unnamed-eligible options (see below) in the order they appear in  optlist, but if any were previously discovered in named form they  forfeit their position in that order.

Options that are eligible to be used in an unnamed fashion must have a  colon or dash prefixed to their optname in the *optlist* when  **ggParseOptions** is invoked.  Unnamed options may appear as named  options as well.  **ggParseOptions** will alter the first character in  the corresponding optname entry in *optlist* to a colon or to a  dash depending on whether the option was present in unnamed or named  form, respectively.  Thus the caller can determine whether the option was presented in named or unnamed form.

Options that appear in boolean form will have the first character in their result changed to "y".  This can be distinguished from an explicit value of "y" because no NULL terminator is appended to the "y".

Options that are not found are left unaltered in *optlist*.

Option names and values in *str* are limited in length to  GG\_MAX\_OPTION\_NAME and GG\_MAX\_OPTION\_RESULT bytes, respectively, including  one byte for a terminating NULL character.

## RETURN VALUE

**ggParseOptions** returns the position in *str* after the last character of a valid option string, or **NULL** if *str* was determined not to be a valid option string.  Even on failure, the contents of *optlist*  may have been altered.