Name

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.

g_option_context_free ()

void        g_option_context_free           (GOptionContext *context);

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

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

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.

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

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 do not start with a dash). But note that GOption cannot reliably determine whether a non-option belongs to a preceding unknown option.

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

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,
  G_OPTION_FLAG_NO_ARG		= 1 << 3,
  G_OPTION_FLAG_FILENAME	= 1 << 4,
  G_OPTION_FLAG_OPTIONAL_ARG    = 1 << 5,
  G_OPTION_FLAG_NOALIAS	        = 1 << 6
} 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.

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 does not exist, adds the entries to it and sets the translation domain.

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.

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 do not free the group after adding it to a context.

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.

g_option_context_get_main_group ()

GOptionGroup* g_option_context_get_main_group       (GOptionContext *context);

Returns a pointer to the main group of context.

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.

g_option_group_free ()

void        g_option_group_free             (GOptionGroup *group);

Frees a GOptionGroup. Note do not free groups which have been added to a GOptionContext.

g_option_group_add_entries ()

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

Adds the options specified in entries to group.

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

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

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, GDestroyNotify destroy_notify, 
                                                     gpointer data,);

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.

Set only the translation domain if gettext() is used, see g_option_group_set_translation_domain().

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.