| LibGKSu Reference Manual | ||||
|---|---|---|---|---|
GksuContext;
GksuContext* gksu_context_new ();
void gksu_context_free (GksuContext *context);
void gksu_context_set_user (GksuContext *context,
gchar *username);
const gchar* gksu_context_get_user (GksuContext *context);
void gksu_context_set_command (GksuContext *context,
gchar *command);
const gchar* gksu_context_get_command (GksuContext *context);
void gksu_context_set_password (GksuContext *context,
gchar *password);
const gchar* gksu_context_get_password (GksuContext *context);
void gksu_context_set_login_shell (GksuContext *context,
gboolean value);
gboolean gksu_context_get_login_shell (GksuContext *context);
void gksu_context_set_keep_env (GksuContext *context,
gboolean value);
gboolean gksu_context_get_keep_env (GksuContext *context);
void gksu_context_set_debug (GksuContext *context,
gboolean value);
gboolean gksu_context_get_debug (GksuContext *context);
void gksu_context_set_ssh_fwd (GksuContext *context,
gboolean value);
gboolean gksu_context_get_ssh_fwd (GksuContext *context);
gboolean gksu_context_sudo_try_need_password
(GksuContext *context);
gboolean gksu_context_try_need_password (GksuContext *context);
gboolean gksu_context_run_full (GksuContext *context,
GksuAskPasswordFunc ask_pass,
gpointer user_data,
GksuPasswordNotNeededFunc pass_not_needed,
gpointer pnn_user_data,
GError **error);
gboolean gksu_context_run (GksuContext *context,
GError **error);
gboolean gksu_context_sudo_run_full (GksuContext *context,
GksuAskPasswordFunc ask_pass,
gpointer user_data,
GksuPasswordNotNeededFunc pass_not_needed,
gpointer pnn_user_data,
GError **error);
gboolean gksu_context_sudo_run (GksuContext *context,
GError **error);
Everything that is done by libgksu needs to know a lot of stuff about what to run, as what user to run and some more information, as X authentication information and such. All that information is contained in a GksuContext.
typedef struct {
GObject parent;
gchar *xauth;
gchar *dir;
gchar *display;
gchar *user;
gchar *password;
gchar *command;
gboolean login_shell;
gboolean keep_env;
gboolean debug;
gboolean ssh_fwd;
} GksuContext;
Object that holds all configuration information, some important environment variables and some meta-information about mainly x authentication.
GObject parent; |
GksuContext is based on GObject |
gchar *xauth; |
the X authorization token |
gchar *dir; |
the directory where the .Xauthority file is created in sudo mode |
gchar *display; |
storage for the DISPLAY environment variable |
gchar *user; |
user gksu will switch to |
gchar *password; |
the password that should be passed to su or sudo |
gchar *command; |
which command to run with su |
gboolean login_shell; |
should run a login shell? |
gboolean keep_env; |
should the current environment be kept? |
gboolean debug; |
show debug information? |
gboolean ssh_fwd; |
are we running inside a ssh X11 forwarding tunnel? |
GksuContext* gksu_context_new ();
Creates a new context to use gksu with. You must manually free the context with gksu_context_free after use.
| Returns : | a new GksuContext. |
void gksu_context_free (GksuContext *context);
Frees the provided GksuContext.
context : |
the GksuContext to be freed. |
void gksu_context_set_user (GksuContext *context, gchar *username);
Sets up what user the command will be run as. The default is root, but you can run the command as any user.
context : |
the GksuContext you want to modify |
username : |
the target username |
const gchar* gksu_context_get_user (GksuContext *context);
Gets the user the command will be run as, as set by gksu_context_set_user.
context : |
the GksuContext from which to grab the information |
| Returns : | a pointer to the string containing the username. |
void gksu_context_set_command (GksuContext *context, gchar *command);
Sets up what command will run with the target user.
context : |
the GksuContext you want to modify |
command : |
the command that shall be ran |
const gchar* gksu_context_get_command (GksuContext *context);
Gets the command that will be run, as set by gksu_context_set_command.
context : |
the GksuContext from which to grab the information |
| Returns : | a pointer to the string containing the command. |
void gksu_context_set_password (GksuContext *context, gchar *password);
Sets up what is the password to be passed to su/sudo. *
context : |
the GksuContext you want to modify |
password : |
the password |
const gchar* gksu_context_get_password (GksuContext *context);
Gets the password that is set for calling the su/sudo programs.
context : |
the GksuContext from which to grab the information |
| Returns : | a pointer to the string containing the password. |
void gksu_context_set_login_shell (GksuContext *context, gboolean value);
Should the shell in which the command will be run be a login shell?
context : |
the GksuContext you want to modify |
value : |
TRUE or FALSE |
gboolean gksu_context_get_login_shell (GksuContext *context);
Finds out if the shell created by the underlying su process will be a login shell.
context : |
the GksuContext from which to grab the information |
| Returns : | TRUE if the shell will be a login shell, FALSE otherwise. |
void gksu_context_set_keep_env (GksuContext *context, gboolean value);
Should the environment be kept as it is? Defaults to TRUE. Notice that setting this to FALSE may cause the X authorization stuff to fail.
context : |
the GksuContext you want to modify |
value : |
TRUE or FALSE |
gboolean gksu_context_get_keep_env (GksuContext *context);
Finds out if the environment in which the program will be run will be reset.
context : |
the GksuContext from which to grab the information |
| Returns : | TRUE if the environment is going to be kept, FALSE otherwise. |
void gksu_context_set_debug (GksuContext *context, gboolean value);
Set up if debuging information should be printed.
context : |
the GksuContext you want to modify |
value : |
TRUE or FALSE |
gboolean gksu_context_get_debug (GksuContext *context);
Finds out if the library is configured to print debuging information.
context : |
the GksuContext from which to grab the information |
| Returns : | TRUE if it is, FALSE otherwise. |
void gksu_context_set_ssh_fwd (GksuContext *context, gboolean value);
Set up if we are running inside a sshd forwarding session. That's because the X authorization semantics differ a bit. -> THIS SETTING IS CURRENTLY USED FOR NOTHING
context : |
the GksuContext you want to modify |
value : |
TRUE or FALSE |
gboolean gksu_context_get_ssh_fwd (GksuContext *context);
Finds out if the library is configured as being run inside a ssh X11 forwarding tunnel. -> THIS SETTING IS CURRENTLY USED FOR NOTHING
context : |
the GksuContext from which to grab the information |
| Returns : | TRUE if it is, FALSE otherwise. |
gboolean gksu_context_sudo_try_need_password
(GksuContext *context);
Checks if we need to ask for a password or if we have ways of getting the password for ourselves or we simply don't need it. Since 1.3.1.
context : |
a GksuContext |
| Returns : | TRUE if requesting a password is needed, FALSE otherwise. |
gboolean gksu_context_try_need_password (GksuContext *context);
Checks if we need to ask for a password or if we have ways of getting the password for ourselves or we simply don't need it. Since 1.3.0.
context : |
a GksuContext |
| Returns : | TRUE if requesting a password is needed, FALSE otherwise. |
gboolean gksu_context_run_full (GksuContext *context, GksuAskPasswordFunc ask_pass, gpointer user_data, GksuPasswordNotNeededFunc pass_not_needed, gpointer pnn_user_data, GError **error);
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 needed, so the application has the oportunity of warning the user what it's doing. Since 1.3.3.
context : |
a GksuContext |
ask_pass : |
a GksuAskPasswordFunc |
user_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 GksuPasswordNotNeededFunc |
error : |
a GError object to be filled with the error code or NULL |
| Returns : | the child's error status, 0 if all went fine, -1 if failed |
gboolean gksu_context_run (GksuContext *context, GError **error);
This could be considered one of the main functions in GKSu. it is responsible for doing the 'user changing' magic.
context : |
a GksuContext |
error : |
a GError object to be filled with the error code or NULL |
| Returns : | the child's error status, 0 if all went fine, -1 if failed |
gboolean gksu_context_sudo_run_full (GksuContext *context, GksuAskPasswordFunc ask_pass, gpointer user_data, GksuPasswordNotNeededFunc pass_not_needed, gpointer pnn_user_data, GError **error);
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 needed, so the application has the oportunity of warning the user what it's doing. Since 1.3.3.
context : |
a GksuContext |
ask_pass : |
a GksuAskPasswordFunc |
user_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 GksuPasswordNotNeededFunc |
error : |
a GError object to be filled with the error code or NULL |
| Returns : | the child's error status, 0 if all went fine, -1 if failed |
gboolean gksu_context_sudo_run (GksuContext *context, GError **error);
This could be considered one of the main functions in GKSu.
it is responsible for doing the 'user changing' magic by
calling gksu_ask_password() if it needs the user's password
it behaves like sudo.
context : |
a GksuContext |
error : |
a GError object to be filled with the error code or NULL |
| Returns : | the child's error status, 0 if all went fine, -1 if failed |