kov changed libgksu/branches/libgksu2/ChangeLog,
libgksu/branches/libgksu2/docs/libgksu-docs.sgml,
libgksu/branches/libgksu2/docs/libgksu-overrides.txt,
libgksu/branches/libgksu2/docs/libgksu-sections.txt,
libgksu/branches/libgksu2/docs/libgksu-undocumented.txt,
libgksu/branches/libgksu2/docs/libgksu.types,
libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml,
libgksu/branches/libgksu2/docs/libgksu1.2-overrides.txt,
libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt,
libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt,
libgksu/branches/libgksu2/docs/libgksu1.2.types,
libgksu/branches/libgksu2/libgksu/libgksu.c
Gustavo Noronha
kov at costa.debian.org
Sun Jan 8 00:17:55 UTC 2006
Mensagem de log:
revamp documentation
-----
Modified: libgksu/branches/libgksu2/ChangeLog
===================================================================
--- libgksu/branches/libgksu2/ChangeLog 2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/ChangeLog 2006-01-08 00:17:54 UTC (rev 503)
@@ -1,5 +1,10 @@
2006-01-07 Gustavo Noronha Silva <kov at debian.org>
+ * libgksu/libgksu.c, docs/*:
+ - revamp documentation; gtk-doc-style comments added to
+ functions and some fixes to return values were made to
+ match the docs
+
* configure.ac, Makefile.am, others:
- revamping the i18n infra-structure; mainly removing
local intl/ copy and updating files
Copied: libgksu/branches/libgksu2/docs/libgksu-docs.sgml (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml 2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-docs.sgml 2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,13 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
+<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <bookinfo>
+ <title>LibGKSu Reference Manual</title>
+ </bookinfo>
+
+ <chapter>
+ <title>Main Reference</title>
+ <xi:include href="xml/libgksu.xml"/>
+ </chapter>
+</book>
Copied: libgksu/branches/libgksu2/docs/libgksu-overrides.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-overrides.txt)
Copied: libgksu/branches/libgksu2/docs/libgksu-sections.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt 2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-sections.txt 2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,11 @@
+<SECTION>
+<FILE>libgksu</FILE>
+<TITLE>API Reference</TITLE>
+GksuError
+gksu_context_new
+gksu_context_free
+gksu_su
+gksu_su_full
+gksu_sudo
+gksu_sudo_full
+</SECTION>
Copied: libgksu/branches/libgksu2/docs/libgksu-undocumented.txt (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt)
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt 2006-01-07 17:53:42 UTC (rev 497)
+++ libgksu/branches/libgksu2/docs/libgksu-undocumented.txt 2006-01-08 00:17:54 UTC (rev 503)
@@ -0,0 +1,10 @@
+78% symbol docs coverage.
+7 symbols documented.
+0 symbols incomplete.
+2 not documented.
+
+
+GksuError
+
+
+libgksu:Short_Description
Copied: libgksu/branches/libgksu2/docs/libgksu.types (from rev 497, libgksu/branches/libgksu2/docs/libgksu1.2.types)
Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml 2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-docs.sgml 2006-01-08 00:17:54 UTC (rev 503)
@@ -1,13 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<book id="index" xmlns:xi="http://www.w3.org/2001/XInclude">
- <bookinfo>
- <title>LibGKSu Reference Manual</title>
- </bookinfo>
-
- <chapter>
- <title>Main Reference</title>
- <xi:include href="xml/gksu-context.xml"/>
- </chapter>
-</book>
Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-overrides.txt
===================================================================
Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt 2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-sections.txt 2006-01-08 00:17:54 UTC (rev 503)
@@ -1,31 +0,0 @@
-<SECTION>
-<FILE>gksu</FILE>
-</SECTION>
-
-<SECTION>
-<FILE>gksu-context</FILE>
-<TITLE>GksuContext</TITLE>
-GksuContext
-gksu_context_new
-gksu_context_free
-gksu_context_set_user
-gksu_context_get_user
-gksu_context_set_command
-gksu_context_get_command
-gksu_context_set_password
-gksu_context_get_password
-gksu_context_set_login_shell
-gksu_context_get_login_shell
-gksu_context_set_keep_env
-gksu_context_get_keep_env
-gksu_context_set_debug
-gksu_context_get_debug
-gksu_context_set_ssh_fwd
-gksu_context_get_ssh_fwd
-gksu_context_sudo_try_need_password
-gksu_context_try_need_password
-gksu_context_run_full
-gksu_context_run
-gksu_context_sudo_run_full
-gksu_context_sudo_run
-</SECTION>
Deleted: libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt
===================================================================
--- libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt 2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/docs/libgksu1.2-undocumented.txt 2006-01-08 00:17:54 UTC (rev 503)
@@ -1,10 +0,0 @@
-67% symbol docs coverage.
-4 symbols documented.
-0 symbols incomplete.
-2 not documented.
-
-
-gksu_context_free
-gksu_context_new
-
-
Deleted: libgksu/branches/libgksu2/docs/libgksu1.2.types
===================================================================
Modified: libgksu/branches/libgksu2/libgksu/libgksu.c
===================================================================
--- libgksu/branches/libgksu2/libgksu/libgksu.c 2006-01-07 23:27:53 UTC (rev 502)
+++ libgksu/branches/libgksu2/libgksu/libgksu.c 2006-01-08 00:17:54 UTC (rev 503)
@@ -695,6 +695,15 @@
g_free (xauth);
}
+/**
+ * gksu_context_new
+ *
+ * This function should be used when creating a new #GksuContext to
+ * pass to gksu_su_full or gksu_sudo_full. The #GksuContext must be
+ * freed with gksu_context_free.
+ *
+ * Returns: a newly allocated #GksuContext
+ */
GksuContext*
gksu_context_new ()
{
@@ -723,6 +732,12 @@
return context;
}
+/**
+ * gksu_context_free
+ * @context: the #GksuContext to be freed.
+ *
+ * Frees the given #GksuContext.
+ */
void
gksu_context_free (GksuContext *context)
{
@@ -739,25 +754,31 @@
}
/**
- * gksu_context_run_full:
+ * gksu_su_full:
* @context: a #GksuContext
- * @ask_pass: a #GksuAskPasswordFunc
- * @user_data: a #gpointer with user data to be passed to the
+ * @ask_pass: a #GksuAskPassFunc to be called when the lib determines
+ * requesting a password is necessary; it may be NULL, in which case
+ * the standard password request dialog will be used
+ * @ask_pass_data: a #gpointer with user data to be passed to the
* #GksuAskPasswordFunc
- * @pass_not_needed: a #GksuPasswordNotNeededFunc
- * @pnn_user_data: a #gpointer with the user data to be passed to the
+ * @pass_not_needed: a #GksuPassNotNeededFunc that will be called
+ * when the command is being run without the need for requesting
+ * a password; it will only be called if the display-no-pass-info
+ * gconf key is enabled; NULL will have the standard dialog be shown
+ * @pass_not_needed_data: a #gpointer with the user data to be passed to the
* #GksuPasswordNotNeededFunc
* @error: a #GError object to be filled with the error code or NULL
*
* This could be considered one of the main functions in GKSu.
* it is responsible for doing the 'user changing' magic calling
- * the #GksuAskPasswordFunc function to request a password if needed.
- * and the #GksuPasswordNotNeededFunc function if a password won't be
+ * the #GksuAskPassFunc function to request a password if needed.
+ * and the #GksuPassNotNeededFunc function if a password won't be
* needed, so the application has the oportunity of warning the user
* what it's doing.
- * Since 1.3.3.
*
- * Returns: the child's error status, 0 if all went fine, -1 if failed
+ * This function uses su as backend.
+ *
+ * Returns: FALSE if all went fine, TRUE if failed
*/
gboolean
gksu_su_full (GksuContext *context,
@@ -784,7 +805,7 @@
g_set_error (error, gksu_quark, GKSU_ERROR_NOCOMMAND,
_("gksu_run needs a command to be run, "
"none was provided."));
- return -1;
+ return TRUE;
}
if (!context->user)
@@ -795,7 +816,7 @@
g_set_error (error, gksu_quark, GKSU_ERROR_HELPER,
_("The gksu-run-helper command was not found or "
"is not executable."));
- return -1;
+ return TRUE;
}
/*
@@ -843,7 +864,7 @@
g_set_error (error, gksu_quark, GKSU_ERROR_FORK,
_("Failed to fork new process: %s"),
strerror(errno));
- return -1;
+ return TRUE;
}
else
{
@@ -986,7 +1007,7 @@
if (context->debug)
fprintf (stderr, "DEBUG (failed!) buf: -%s-\n", buf);
- return -1;
+ return TRUE;
}
FD_ZERO(&rfds);
@@ -1012,7 +1033,7 @@
_("Could not read from the pipe "
"with the child: %s"),
strerror(errno));
- return -1;
+ return TRUE;
}
if(FD_ISSET(fdpty, &rfds))
@@ -1065,6 +1086,19 @@
return FALSE;
}
+/**
+ * gksu_su
+ * @command_line: the command line that will be executed as other user
+ * @error: a #GError to be set with the error condition, if an error
+ * happens
+ *
+ * This function is a wrapper for gksu_su_run_full. It will call it
+ * without giving the callback functions, which leads to the standard
+ * ones being called. A simple #GksuContext is created to hold the
+ * user name and the command.
+ *
+ * Returns: FALSE if all went well, TRUE if an error happend.
+ */
gboolean
gksu_su (gchar *command_line, GError **error)
{
@@ -1082,25 +1116,31 @@
}
/**
- * gksu_context_sudo_run_full:
+ * gksu_sudo_full:
* @context: a #GksuContext
- * @ask_pass: a #GksuAskPasswordFunc
- * @user_data: a #gpointer with user data to be passed to the
+ * @ask_pass: a #GksuAskPassFunc to be called when the lib determines
+ * requesting a password is necessary; it may be NULL, in which case
+ * the standard password request dialog will be used
+ * @ask_pass_data: a #gpointer with user data to be passed to the
* #GksuAskPasswordFunc
- * @pass_not_needed: a #GksuPasswordNotNeededFunc
- * @pnn_user_data: a #gpointer with the user data to be passed to the
+ * @pass_not_needed: a #GksuPassNotNeededFunc that will be called
+ * when the command is being run without the need for requesting
+ * a password; it will only be called if the display-no-pass-info
+ * gconf key is enabled; NULL will have the standard dialog be shown
+ * @pass_not_needed_data: a #gpointer with the user data to be passed to the
* #GksuPasswordNotNeededFunc
* @error: a #GError object to be filled with the error code or NULL
*
* This could be considered one of the main functions in GKSu.
* it is responsible for doing the 'user changing' magic calling
- * the #GksuAskPasswordFunc function to request a password if needed.
- * and the #GksuPasswordNotNeededFunc function if a password won't be
+ * the #GksuAskPassFunc function to request a password if needed.
+ * and the #GksuPassNotNeededFunc function if a password won't be
* needed, so the application has the oportunity of warning the user
* what it's doing.
- * Since 1.3.3.
*
- * Returns: the child's error status, 0 if all went fine, -1 if failed
+ * This function uses the sudo backend.
+ *
+ * Returns: FALSE if all went fine, TRUE if failed
*/
gboolean
gksu_sudo_full (GksuContext *context,
@@ -1136,7 +1176,7 @@
g_set_error (error, gksu_quark, GKSU_ERROR_NOCOMMAND,
_("gksu_sudo_run needs a command to be run, "
"none was provided."));
- return -1;
+ return TRUE;
}
if (!context->user)
@@ -1161,7 +1201,7 @@
{
g_set_error (error, gksu_quark, GKSU_ERROR_XAUTH,
_("Unable to copy the user's Xauthorization file."));
- return -1;
+ return TRUE;
}
/* sets XAUTHORITY */
@@ -1275,7 +1315,7 @@
_("Error creating pipe: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
if ((pipe(child_pipe)) == -1)
@@ -1284,7 +1324,7 @@
_("Error creating pipe: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
pid = fork();
@@ -1294,7 +1334,7 @@
_("Failed to fork new process: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
else if (pid == 0)
{
@@ -1310,7 +1350,7 @@
_("Failed to exec new process: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
else
{
@@ -1326,7 +1366,7 @@
_("Error opening pipe: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
outfile = fdopen(child_pipe[1], "w");
@@ -1336,7 +1376,7 @@
_("Error opening pipe: %s"),
strerror(errno));
sudo_reset_xauth (context, xauth, xauth_env);
- return -1;
+ return TRUE;
}
/*
@@ -1479,6 +1519,19 @@
return FALSE;
}
+/**
+ * gksu_sudo
+ * @command_line: the command line that will be executed as other user
+ * @error: a #GError to be set with the error condition, if an error
+ * happens
+ *
+ * This function is a wrapper for gksu_sudo_run_full. It will call it
+ * without giving the callback functions, which leads to the standard
+ * ones being called. A simple #GksuContext is created to hold the
+ * user name and the command.
+ *
+ * Returns: FALSE if all went well, TRUE if an error happend.
+ */
gboolean
gksu_sudo (gchar *command_line,
GError **error)
More information about the gksu-commits
mailing list