GOptionArgFunc ()

gboolean
(*GOptionArgFunc) (const gchar *option_name,
                   const gchar *value,
                   gpointer data,
                   GError **error);

The type of function to be passed as callback for G_OPTION_ARG_CALLBACK options.

g_option_context_new ()

GOptionContext *
g_option_context_new (const gchar *parameter_string);

Creates a new option context.

The parameter_string can serve multiple purposes. It can be used to add descriptions for "rest" arguments, which are not parsed by the GOptionContext, typically something like "FILES" or "FILE1 FILE2...". If you are using G_OPTION_REMAINING for collecting "rest" arguments, GLib handles this automatically by using the arg_description of the corresponding GOptionEntry in the usage summary.

Another usage is to give a short summary of the program functionality, like " - frob the strings", which will be displayed in the same line as the usage. For a longer description of the program functionality that should be displayed as a paragraph below the usage line, use g_option_context_set_summary().

Note that the parameter_string is translated using the function set with g_option_context_set_translate_func(), so it should normally be passed untranslated.

Since: 2.6

g_option_context_set_summary ()

void
g_option_context_set_summary (GOptionContext *context,
                              const gchar *summary);

Adds a string to be displayed in --help output before the list of options. This is typically a summary of the program functionality.

Note that the summary is translated (see g_option_context_set_translate_func() and g_option_context_set_translation_domain()).

Since: 2.12

g_option_context_get_summary ()

const gchar *
g_option_context_get_summary (GOptionContext *context);

Returns the summary. See g_option_context_set_summary().

Since: 2.12

g_option_context_set_description ()

void
g_option_context_set_description (GOptionContext *context,
                                  const gchar *description);

Adds a string to be displayed in --help output after the list of options. This text often includes a bug reporting address.

Note that the summary is translated (see g_option_context_set_translate_func()).

Since: 2.12

g_option_context_get_description ()

const gchar *
g_option_context_get_description (GOptionContext *context);

Returns the description. See g_option_context_set_description().

Since: 2.12

GTranslateFunc ()

const gchar *
(*GTranslateFunc) (const gchar *str,
                   gpointer data);

The type of functions which are used to translate user-visible strings, for <option>--help</option> output.

g_option_context_set_translate_func ()

void
g_option_context_set_translate_func (GOptionContext *context,
                                     GTranslateFunc func,
                                     gpointer data,
                                     GDestroyNotify destroy_notify);

Sets the function which is used to translate the contexts user-visible strings, for --help output. If func is NULL, strings are not translated.

Note that option groups have their own translation functions, this function only affects the parameter_string (see g_option_context_new()), the summary (see g_option_context_set_summary()) and the description (see g_option_context_set_description()).

If you are using gettext(), you only need to set the translation domain, see g_option_context_set_translation_domain().

Since: 2.12

g_option_context_set_translation_domain ()

void
g_option_context_set_translation_domain
                               (GOptionContext *context,
                                const gchar *domain);

A convenience function to use gettext() for translating user-visible strings.

Since: 2.12

g_option_context_free ()

void
g_option_context_free (GOptionContext *context);

Frees context and all the groups which have been added to it.

Please note that parsed arguments need to be freed separately (see GOptionEntry).

Since: 2.6

g_option_context_parse ()

gboolean
g_option_context_parse (GOptionContext *context,
                        gint *argc,
                        gchar ***argv,
                        GError **error);

Parses the command line arguments, recognizing options which have been added to context . A side-effect of calling this function is that g_set_prgname() will be called.

If the parsing is successful, any parsed arguments are removed from the array and argc and argv are updated accordingly. A '--' option is stripped from argv unless there are unparsed options before and after it, or some of the options after it start with '-'. In case of an error, argc and argv are left unmodified.

If automatic --help support is enabled (see g_option_context_set_help_enabled()), and the argv array contains one of the recognized help options, this function will produce help output to stdout and call exit (0).

Note that function depends on the current locale for automatic character set conversion of string and filename arguments.

Since: 2.6

g_option_context_parse_strv ()

gboolean
g_option_context_parse_strv (GOptionContext *context,
                             gchar ***arguments,
                             GError **error);

Parses the command line arguments.

This function is similar to g_option_context_parse() except that it respects the normal memory rules when dealing with a strv instead of assuming that the passed-in array is the argv of the main function.

In particular, strings that are removed from the arguments list will be freed using g_free().

On Windows, the strings are expected to be in UTF-8. This is in contrast to g_option_context_parse() which expects them to be in the system codepage, which is how they are passed as argv to main(). See g_win32_get_command_line() for a solution.

This function is useful if you are trying to use GOptionContext with GApplication.

Since: 2.40

g_option_context_set_help_enabled ()

void
g_option_context_set_help_enabled (GOptionContext *context,
                                   gboolean help_enabled);

Enables or disables automatic generation of --help output. By default, g_option_context_parse() recognizes --help, -h, -?, --help-all and --help-groupname and creates suitable output to stdout.

Since: 2.6

g_option_context_get_help_enabled ()

gboolean
g_option_context_get_help_enabled (GOptionContext *context);

Returns whether automatic --help generation is turned on for context . See g_option_context_set_help_enabled().

Since: 2.6

g_option_context_set_ignore_unknown_options ()

void
g_option_context_set_ignore_unknown_options
                               (GOptionContext *context,
                                gboolean ignore_unknown);

Sets whether to ignore unknown options or not. If an argument is ignored, it is left in the argv array after parsing. By default, g_option_context_parse() treats unknown options as error.

This setting does not affect non-option arguments (i.e. arguments which don't start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.

Since: 2.6

g_option_context_get_ignore_unknown_options ()

gboolean
g_option_context_get_ignore_unknown_options
                               (GOptionContext *context);

Returns whether unknown options are ignored or not. See g_option_context_set_ignore_unknown_options().

Since: 2.6

g_option_context_get_help ()

gchar *
g_option_context_get_help (GOptionContext *context,
                           gboolean main_help,
                           GOptionGroup *group);

Returns a formatted, translated help text for the given context. To obtain the text produced by --help, call g_option_context_get_help (context, TRUE, NULL). To obtain the text produced by --help-all, call g_option_context_get_help (context, FALSE, NULL). To obtain the help text for an option group, call g_option_context_get_help (context, FALSE, group).

Since: 2.14

g_option_context_get_strict_posix ()

gboolean
g_option_context_get_strict_posix (GOptionContext *context);

Returns whether strict POSIX code is enabled.

See g_option_context_set_strict_posix() for more information.

Since: 2.44

g_option_context_set_strict_posix ()

void
g_option_context_set_strict_posix (GOptionContext *context,
                                   gboolean strict_posix);

Sets strict POSIX mode.

By default, this mode is disabled.

In strict POSIX mode, the first non-argument parameter encountered (eg: filename) terminates argument processing. Remaining arguments are treated as non-options and are not attempted to be parsed.

If strict POSIX mode is disabled then parsing is done in the GNU way where option arguments can be freely mixed with non-options.

As an example, consider "ls foo -l". With GNU style parsing, this will list "foo" in long mode. In strict POSIX style, this will list the files named "foo" and "-l".

It may be useful to force strict POSIX mode when creating "verb style" command line tools. For example, the "gsettings" command line tool supports the global option "--schemadir" as well as many subcommands ("get", "set", etc.) which each have their own set of arguments. Using strict POSIX mode will allow parsing the global options up to the verb name while leaving the remaining options to be parsed by the relevant subcommand (which can be determined by examining the verb name, which should be present in argv[1] after parsing).

Since: 2.44

g_option_context_add_main_entries ()

void
g_option_context_add_main_entries (GOptionContext *context,
                                   const GOptionEntry *entries,
                                   const gchar *translation_domain);

A convenience function which creates a main group if it doesn't exist, adds the entries to it and sets the translation domain.

Since: 2.6

g_option_context_add_group ()

void
g_option_context_add_group (GOptionContext *context,
                            GOptionGroup *group);

Adds a GOptionGroup to the context , so that parsing with context will recognize the options in the group. Note that this will take ownership of the group and thus the group should not be freed.

Since: 2.6

g_option_context_set_main_group ()

void
g_option_context_set_main_group (GOptionContext *context,
                                 GOptionGroup *group);

Sets a GOptionGroup as main group of the context . This has the same effect as calling g_option_context_add_group(), the only difference is that the options in the main group are treated differently when generating --help output.

Since: 2.6

g_option_context_get_main_group ()

GOptionGroup *
g_option_context_get_main_group (GOptionContext *context);

Returns a pointer to the main group of context .

Since: 2.6

g_option_group_new ()

GOptionGroup *
g_option_group_new (const gchar *name,
                    const gchar *description,
                    const gchar *help_description,
                    gpointer user_data,
                    GDestroyNotify destroy);

Creates a new GOptionGroup.

Since: 2.6

g_option_group_ref ()

GOptionGroup *
g_option_group_ref (GOptionGroup *group);

Increments the reference count of group by one.

Since: 2.44

g_option_group_unref ()

void
g_option_group_unref (GOptionGroup *group);

Decrements the reference count of group by one. If the reference count drops to 0, the group will be freed. and all memory allocated by the group is released.

Since: 2.44

g_option_group_free ()

void
g_option_group_free (GOptionGroup *group);

Frees a GOptionGroup. Note that you must not free groups which have been added to a GOptionContext.

Since: 2.6

g_option_group_add_entries ()

void
g_option_group_add_entries (GOptionGroup *group,
                            const GOptionEntry *entries);

Adds the options specified in entries to group .

Since: 2.6

GOptionParseFunc ()

gboolean
(*GOptionParseFunc) (GOptionContext *context,
                     GOptionGroup *group,
                     gpointer data,
                     GError **error);

The type of function that can be called before and after parsing.

g_option_group_set_parse_hooks ()

void
g_option_group_set_parse_hooks (GOptionGroup *group,
                                GOptionParseFunc pre_parse_func,
                                GOptionParseFunc post_parse_func);

Associates two functions with group which will be called from g_option_context_parse() before the first option is parsed and after the last option has been parsed, respectively.

Note that the user data to be passed to pre_parse_func and post_parse_func can be specified when constructing the group with g_option_group_new().

Since: 2.6

GOptionErrorFunc ()

void
(*GOptionErrorFunc) (GOptionContext *context,
                     GOptionGroup *group,
                     gpointer data,
                     GError **error);

The type of function to be used as callback when a parse error occurs.

g_option_group_set_error_hook ()

void
g_option_group_set_error_hook (GOptionGroup *group,
                               GOptionErrorFunc error_func);

Associates a function with group which will be called from g_option_context_parse() when an error occurs.

Note that the user data to be passed to error_func can be specified when constructing the group with g_option_group_new().

Since: 2.6

g_option_group_set_translate_func ()

void
g_option_group_set_translate_func (GOptionGroup *group,
                                   GTranslateFunc func,
                                   gpointer data,
                                   GDestroyNotify destroy_notify);

Sets the function which is used to translate user-visible strings, for --help output. Different groups can use different GTranslateFuncs. If func is NULL, strings are not translated.

If you are using gettext(), you only need to set the translation domain, see g_option_group_set_translation_domain().

Since: 2.6

g_option_group_set_translation_domain ()

void
g_option_group_set_translation_domain (GOptionGroup *group,
                                       const gchar *domain);

A convenience function to use gettext() for translating user-visible strings.

Since: 2.6

enum GOptionError

Error codes returned by option parsing.

G_OPTION_ERROR

#define G_OPTION_ERROR (g_option_error_quark ())

Error domain for option parsing. Errors in this domain will be from the GOptionError enumeration. See GError for information on error domains.

GOptionContext

typedef struct _GOptionContext GOptionContext;

A GOptionContext struct defines which options are accepted by the commandline option parser. The struct has only private fields and should not be directly accessed.

enum GOptionArg

The GOptionArg enum values determine which type of extra argument the options expect to find. If an option expects an extra argument, it can be specified in several ways; with a short option: -x arg, with a long option: --name arg or combined in a single argument: --name=arg.

enum GOptionFlags

Flags which modify individual options.

G_OPTION_REMAINING

#define G_OPTION_REMAINING ""

If a long option in the main group has this name, it is not treated as a regular option. Instead it collects all non-option arguments which would otherwise be left in argv. The option must be of type G_OPTION_ARG_CALLBACK, G_OPTION_ARG_STRING_ARRAY or G_OPTION_ARG_FILENAME_ARRAY.

Using G_OPTION_REMAINING instead of simply scanning argv for leftover arguments has the advantage that GOption takes care of necessary encoding conversions for strings or filenames.

Since: 2.6

struct GOptionEntry

struct GOptionEntry {
  const gchar *long_name;
  gchar        short_name;
  gint         flags;

  GOptionArg   arg;
  gpointer     arg_data;
  
  const gchar *description;
  const gchar *arg_description;
};

A GOptionEntry struct defines a single option. To have an effect, they must be added to a GOptionGroup with g_option_context_add_main_entries() or g_option_group_add_entries().

GOptionGroup

typedef struct _GOptionGroup GOptionGroup;

A GOptionGroup struct defines the options in a single group. The struct has only private fields and should not be directly accessed.

All options in a group share the same translation function. Libraries which need to parse commandline options are expected to provide a function for getting a GOptionGroup holding their options, which the application can then add to its GOptionContext.