API Reference

API Reference — This API provides functions to provide su and sudo functionality to its users.

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);
gchar*      gksu_context_get_description    (GksuContext *context);
void        gksu_context_set_description    (GksuContext *context,
                                             gchar *description);
void        gksu_context_set_message        (GksuContext *context,
                                             gchar *message);
gchar*      gksu_context_get_message        (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);
gchar*      gksu_ask_password               (GError **error);
gchar*      gksu_ask_password_full          (GksuContext *context,
                                             gchar *prompt,
                                             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,
  GKSU_ERROR_CANCELED,
  GKSU_ERROR_WRONGAUTOPASS
} 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 string with the user or NULL if not set.

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 string with the command or NULL if not set.

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_get_description ()

gchar*      gksu_context_get_description    (GksuContext *context);

Get the description that the window will have when the default function for requesting the password is called.

context : the GksuContext you want to get the description from.
Returns : a string with the description or NULL if not set.

gksu_context_set_description ()

void        gksu_context_set_description    (GksuContext *context,
                                             gchar *description);

Set the nice name for the action that is being run that the window that asks for the password will have. This is only meant to be used if the default window is used, of course.

context : the GksuContext you want to modify
description : a string to set the description for

gksu_context_set_message ()

void        gksu_context_set_message        (GksuContext *context,
                                             gchar *message);

Set the message that the window that asks for the password will have. This is only meant to be used if the default window is used, of course.

context : the GksuContext you want to modify
message : a string to set the message for

gksu_context_get_message ()

gchar*      gksu_context_get_message        (GksuContext *context);

Get the message that the window will have when the default function for requesting the password is called.

context : the GksuContext you want to get the message from.
Returns : a string with the message or NULL if not set.

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);

Returns TRUE if gksu has been asked to do a grab on keyboard and mouse when asking for the password.

context : the GksuContext you want to ask whether a grab will be done.
Returns : TRUE if yes, FALSE otherwise.

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 : TRUE if all went fine, FALSE 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 : TRUE if all went well, FALSE 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 : TRUE if all went fine, FALSE 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 : TRUE if all went well, FALSE 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 : TRUE if all went fine, FALSE if failed

gksu_ask_password ()

gchar*      gksu_ask_password               (GError **error);

This function uses the gksu infra-structure to request for a password, but instead of passing it to su or sudo to run a command it simply returns the password. This is just a convenience wrapper for gksu_ask_password_full.

error : a GError to be set with the error condition, if an error happens
Returns : a newly allocated string with the password;

gksu_ask_password_full ()

gchar*      gksu_ask_password_full          (GksuContext *context,
                                             gchar *prompt,
                                             GError **error);

This function uses the gksu infra-structure to request for a password, but instead of passing it to su or sudo to run a command it simply returns the password.

context : a GksuContext
prompt : a prompt different from Password:
error : a GError object to be filled with the error code or NULL
Returns : a newly allocated string with the password;