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