g-application-run (application argv)

application -- a g-application instance
argv -- a list of strings with command line parameters, or nil

An integer with the exit status.

Runs the application. This function is intended to be run from the main function and its return value is intended to be returned by the main function. Although you are expected to pass the argv parameters from the main function to this function, it is possible to pass no arguments, if the command line arguments are not available or command line handling is not required. Note that on Windows, the command line arguments are ignored, and the g_win32_get_command_line() function is called internally, for proper support of Unicode command line arguments.

The g-application instance will attempt to parse the command line arguments. You can add command line flags to the list of recognised options by way of the g-application-add-main-option-entries function. After this, the "handle-local-options" signal is emitted, from which the application can inspect the values of its option entries.

The "handle-local-options" signal handler is a good place to handle options such as --version, where an immediate reply from the local process is desired, instead of communicating with an already-running instance. A "handle-local-options" signal handler can stop further processing by returning a non-negative value, which then becomes the exit status of the process.

What happens next depends on the g-application-flags flags: if the :handles-command-line flag was specified then the remaining command line arguments are sent to the primary instance, where a "command-line" signal is emitted. Otherwise, the remaining command line arguments are assumed to be a list of files. If there are no files listed, the application is activated via the "activate" signal. If there are one or more files, and the :handles-open flag was specified then the files are opened via the "open" signal.

If you are interested in doing more complicated local handling of the command line then you should implement your own g-application subclass and override the local_command_line() virtual function. In this case, you most likely want to return true from your local_command_line() implementation to suppress the default handling.

If, after the above is done, the use count of the application is zero then the exit status is returned immediately. If the use count is non-zero then the default main context is iterated until the use count falls to zero, at which point 0 is returned.

If the :is-service flag is set, then the service will run for as much as 10 seconds with a use count of zero while waiting for the message that caused the activation to arrive. After that, if the use count falls to zero the application will exit immediately, except in the case that the g-application-inactivity-timeout function is in use.

This function sets the program name with the g-prgname function, if not already set, to the basename of the first value of the command line arguments.

Much like the g-main-loop-run function, this function will acquire the main context for the duration that the application is running.

Applications that are not explicitly flagged as services or launchers, i.e. neither the :is-service or the :is-launcher values are given as flags, will check, from the default handler for the local_command_line virtual function, if the --gapplication-service option was given in the command line. If this flag is present then normal command line processing is interrupted and the :is-service flag is set. This provides a "compromise" solution whereby running an application directly from the command line will invoke it in the normal way, which can be useful for debugging, while still allowing applications to be D-Bus activated in service mode. The D-Bus service file should invoke the executable with the --gapplication-service option as the sole command line argument. This approach is suitable for use by most graphical applications but should not be used from applications like editors that need precise control over when processes invoked via the command line will exit and what their exit status will be.