libgnomesu API Documentation

# Introduction

`libgnomesu` is a library which allows you to run programs as root or another user.

## Functions

All the functions you need are declared in the header file `libgnomesu.h`.

Function | Description
--- | ---
`gboolean gnomesu_exec (gchar *commandline);` | Runs `commandline` as root and wait until it has finished.
`gboolean gnomesu_spawn_command_sync (gchar *user, gchar *commandline);` | Runs `commandline` as `user` and wait until it has exited.
`gboolean gnomesu_spawn_command_async (gchar *user, gchar *commandline, int *pid);` | Runs `commandline` as `user` but do not wait until it has exited.
`gboolean gnomesu_spawn_sync (gchar *user, gchar **argv);` | Runs a program with `argv` as `user` and wait until it has exited.
`gboolean gnomesu_spawn_async (gchar *user, gchar **argv, int *pid);` | Runs a program with `argv` as `user` but do not wait until it has exited.
`gboolean gnomesu_spawn_async2 (const gchar *user, const gchar **argv, GPid *pid, GdkPixbuf *icon, const gchar *title, gboolean show_command);` | Same as `gnomesu_spawn_async()`, but with more parameters which the developer can use to customize the user interface.

## Running a program as root

Let's say you want to run gedit as root. This simple example will do just that:

    /* test.c */
    #include <gtk/gtk.h>
    #include <libgnomesu/libgnomesu.h>

    int
    main (int argc, char *argv[])
    {
        gtk_init (&argc, &argv);

        g_print ("Running gedit...\n");
        if (!gnomesu_exec ("gedit")) {
            g_printerr ("Unable to setup a subprocess!");
            return 1;
        }
        g_print ("Done!\n");
        return 0;
    }

Compile with:

    gcc -Wall test.c -o test $(pkg-config --cflags --libs gtk+-2.0 libgnomesu-1.0)

`libgnomesu` will prompt the user for a password, if necessary. If the user is already root, or if root does not have a password (!), libgnomesu will run gedit without prompting for a password.

## Return value

All `libgnomesu` functions return `TRUE` or `FALSE`. `TRUE` means the function is able to create setup a subprocess. `FALSE` means it failed to setup a subprocess.

Possible reasons why a function returns `FALSE`:

- The user was prompted for a password, but he pressed the Cancel button. This is the most likely reason.
- It it failed to run `fork()`, failed to create a pipe to communicate with the subprocess, etc.

This return value has got nothing to do with whether `commandline` has been successfully run! For example, if you run `gnomesu_exec("this-command-does-not-exists")`, you will get `TRUE` as return value, even though the command failed to run.

## More complex functions

`gnomesu_spawn_command_sync()` is exactly like `gnomesu_exec()`, except that you can also specify as what user you want to run `commandline`.

`gnomesu_spawn_command_async()` is like `gnomesu_command_spawn_sync()`, but doesn't wait until `commandline` has exited. This function returns immediately. It also places the subprocess's PID in the variable `pid` if it's non-`NULL`.

`gnomesu_spawn_sync()` and `gnomesu_spawn_async()` accept an array of strings instead of a commandline string. It is recommended that you use one of these two functions if you want to pass parameters to the program you want to run.