enum GOptionError

typedef enum
{
  G_OPTION_ERROR_UNKNOWN_OPTION,
  G_OPTION_ERROR_BAD_VALUE,
  G_OPTION_ERROR_FAILED
} 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.

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.

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.

g_option_context_new ()

GOptionContext* g_option_context_new        (const gchar *parameter_string);

Creates a new option context.

Since 2.6

g_option_context_free ()

void        g_option_context_free           (GOptionContext *context);

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

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

Since 2.6

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, -?, --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

enum GOptionArg

typedef enum
{
  G_OPTION_ARG_NONE,
  G_OPTION_ARG_STRING,
  G_OPTION_ARG_INT,
  G_OPTION_ARG_CALLBACK,
  G_OPTION_ARG_FILENAME,
  G_OPTION_ARG_STRING_ARRAY,
  G_OPTION_ARG_FILENAME_ARRAY
} 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

typedef enum
{
  G_OPTION_FLAG_HIDDEN       = 1 << 0,
  G_OPTION_FLAG_IN_MAIN      = 1 << 1,
  G_OPTION_FLAG_REVERSE	     = 1 << 2
} 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_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

GOptionEntry

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

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

A GOptionEntry 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().

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

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

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 the group will be freed together with the context when g_option_context_free() is called, so you must not free the group yourself after adding it to a context.

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_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 pre_parse_func and post_parse_func can be specified when constructing the group with g_option_group_new().

Since 2.6

GTranslateFunc ()

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

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

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