1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>libgnomesu API documentation</title>
<link rel="stylesheet" type="text/css" href="libgnomesu.css">
</head>
<body>
<div id="title">libgnomesu API Documentation</div>
<div id="main">
<h1>Introduction</h1>
<code>libgnomesu</code> is a library which allows you to run programs as root or another user.
<h2>Functions</h2>
All the functions you need are declared in the header file <code>libgnomesu.h</code>.
<p>
<table id="functionIndex">
<tr>
<th>Function</th>
<th>Description</th>
</tr>
<tr>
<td><code>gboolean gnomesu_exec (gchar *commandline);</code></td>
<td>Runs <code>commandline</code> as root and wait until it has finished.</td>
</tr>
<tr>
<td><code>gboolean gnomesu_spawn_command_sync (gchar *user, gchar *commandline);</code></td>
<td>Runs <code>commandline</code> as <code>user</code> and wait until it has exited.</td>
</tr>
<tr>
<td><code>gboolean gnomesu_spawn_command_async (gchar *user, gchar *commandline, int *pid);</code></td>
<td>Runs <code>commandline</code> as <code>user</code> but do not wait until it has exited.</td>
</tr>
<tr>
<td><code>gboolean gnomesu_spawn_sync (gchar *user, gchar **argv);</code></td>
<td>Runs a program with <code>argv</code> as <code>user</code> and wait until it has exited.</td>
</tr>
<tr>
<td><code>gboolean gnomesu_spawn_async (gchar *user, gchar **argv, int *pid);</code></td>
<td>Runs a program with <code>argv</code> as <code>user</code> but do not wait until it has exited.</td>
</tr>
<tr>
<td><code>gboolean gnomesu_spawn_async2 (const gchar *user, const gchar **argv, GPid *pid,
GdkPixbuf *icon, const gchar *title, gboolean show_command);</code></td>
<td>Same as <code>gnomesu_spawn_async()</code>, but with more parameters which the developer can use to
customize the user interface.</td>
</table>
<p class="p"><h2>Running a program as root</h2>
Let's say you want to run gedit as root. This simple example will do just that:
<pre class="example">
<span class="comment">/* test.c */</span>
<span class="cinc">#include</span> <span class="cinc2"><gtk/gtk.h></span>
<span class="cinc">#include</span> <span class="cinc2"><libgnomesu/libgnomesu.h></span>
<span class="ctype">int</span>
main (<span class="ctype">int</span> argc, <span class="ctype">char *</span>argv[])
{
gtk_init (&argc, &argv);
g_print (<span class="cstr">"Running gedit...\n"</span>);
<span class="ckey">if</span> (!gnomesu_exec (<span class="cstr">"gedit"</span>)) {
g_printerr (<span class="cstr">"Unable to setup a subprocess!"</span>);
<span class="ckey">return</span> <span class="cnum">1</span>;
}
g_print (<span class="cstr">"Done!\n"</span>);
<span class="ckey">return</span> <span class="cnum">0</span>;
}
</pre>
Compile with:
<pre>gcc -Wall test.c -o test $(pkg-config --cflags --libs gtk+-2.0 libgnomesu-1.0)</pre>
<p>
<code>libgnomesu</code> 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.
<p class="p"><h2>Return value</h2>
All <code>libgnomesu</code> functions return <code>TRUE</code> or <code>FALSE</code>.
<code>TRUE</code> means the function is able to create setup a subprocess. <code>FALSE</code> means it failed to setup a subprocess.
<p>
Possible reasons why a function returns <code>FALSE</code>:
<ul>
<li>The user was prompted for a password, but he pressed the Cancel button. This is the most likely reason.</li>
<li>It it failed to run <code>fork()</code>, failed to create a pipe to communicate with the subprocess, etc.</li>
</ul>
<p>
This return value has got nothing to do with whether <code>commandline</code> has been successfully run!
For example, if you run <code>gnomesu_exec("this-command-does-not-exists")</code>, you will get <code>TRUE</code>
as return value, even though the command failed to run.
<p class="p"><h2>More complex functions</h2>
<code>gnomesu_spawn_command_sync()</code> is exactly like <code>gnomesu_exec()</code>,
except that you can also specify as what user you want to run <code>commandline</code>.
<p>
<code>gnomesu_spawn_command_async()</code> is like <code>gnomesu_command_spawn_sync()</code>,
but doesn't wait until <code>commandline</code> has exited. This function returns immediately.
It also places the subprocess's PID in the variable <code>pid</code> if it's non-<code>NULL</code>.
<p>
<code>gnomesu_spawn_sync()</code> and <code>gnomesu_spawn_async()</code> 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.
</div>
</body>
</html>
|
