API Reference

API Reference —

Synopsis




enum        GksuError;
GksuContext* gksu_context_new               ();
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_keep_env       (GksuContext *context,
                                             gboolean value);
gboolean    gksu_context_get_keep_env       (GksuContext *context);
void        gksu_context_set_login_shell    (GksuContext *context,
                                             gboolean value);
gboolean    gksu_context_get_login_shell    (GksuContext *context);
void        gksu_context_set_grab           (GksuContext *context,
                                             gboolean value);
gboolean    gksu_context_get_grab           (GksuContext *context);
void        gksu_context_set_debug          (GksuContext *context,
                                             gboolean value);
gboolean    gksu_context_get_debug          (GksuContext *context);
void        gksu_context_free               (GksuContext *context);
gboolean    gksu_run                        (gchar *command_line,
                                             GError **error);
gboolean    gksu_run_full                   (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_data,
                                             GError **error);
gboolean    gksu_su                         (gchar *command_line,
                                             GError **error);
gboolean    gksu_su_full                    (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_data,
                                             GError **error);
gboolean    gksu_sudo                       (gchar *command_line,
                                             GError **error);
gboolean    gksu_sudo_full                  (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_data,
                                             GError **error);

Description

Details

enum GksuError

typedef enum
{
  GKSU_ERROR_XAUTH,
  GKSU_ERROR_HELPER,
  GKSU_ERROR_NOCOMMAND,
  GKSU_ERROR_NOPASSWORD,
  GKSU_ERROR_FORK,
  GKSU_ERROR_EXEC,
  GKSU_ERROR_PIPE,
  GKSU_ERROR_PIPEREAD,
  GKSU_ERROR_WRONGPASS,
  GKSU_ERROR_CHILDFAILED,
  GKSU_ERROR_NOT_ALLOWED
} GksuError;


gksu_context_new ()

GksuContext* 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

gksu_context_set_user ()

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

gksu_context_get_user ()

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.

gksu_context_set_command ()

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

gksu_context_get_command ()

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.

gksu_context_set_keep_env ()

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

gksu_context_get_keep_env ()

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.

gksu_context_set_login_shell ()

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

gksu_context_get_login_shell ()

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.

gksu_context_set_grab ()

void        gksu_context_set_grab           (GksuContext *context,
                                             gboolean value);

context :
value :

gksu_context_get_grab ()

gboolean    gksu_context_get_grab           (GksuContext *context);

context :
Returns :

gksu_context_set_debug ()

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

gksu_context_get_debug ()

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.

gksu_context_free ()

void        gksu_context_free               (GksuContext *context);

Frees the given GksuContext.

context : the GksuContext to be freed.

gksu_run ()

gboolean    gksu_run                        (gchar *command_line,
                                             GError **error);

This function is a wrapper for gksu_sudo/gksu_su. It will call one of them, depending on the GConf key that defines whether the default behavior for gksu is su or sudo mode. This is the recommended way of using the library functionality.

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
Returns : FALSE if all went well, TRUE if an error happend.

gksu_run_full ()

gboolean    gksu_run_full                   (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_data,
                                             GError **error);

This function is a wrapper for gksu_sudo_full/gksu_su_full. It will call one of them, depending on the GConf key that defines whether the default behavior for gksu is su or sudo mode. This is the recommended way of using the library functionality.

context : a GksuContext
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 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
Returns : FALSE if all went fine, TRUE if failed

gksu_su ()

gboolean    gksu_su                         (gchar *command_line,
                                             GError **error);

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.

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
Returns : FALSE if all went well, TRUE if an error happend.

gksu_su_full ()

gboolean    gksu_su_full                    (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_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 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.

This function uses su as backend.

context : a GksuContext
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 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
Returns : FALSE if all went fine, TRUE if failed

gksu_sudo ()

gboolean    gksu_sudo                       (gchar *command_line,
                                             GError **error);

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.

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
Returns : FALSE if all went well, TRUE if an error happend.

gksu_sudo_full ()

gboolean    gksu_sudo_full                  (GksuContext *context,
                                             GksuAskPassFunc ask_pass,
                                             gpointer ask_pass_data,
                                             GksuPassNotNeededFunc pass_not_needed,
                                             gpointer pass_not_needed_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 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.

This function uses the sudo backend.

context : a GksuContext
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 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
Returns : FALSE if all went fine, TRUE if failed