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.

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:

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.