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

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 is a compatibility shim over gksu_run_fuller, which, for compatibility reasons, lacks the 'exit_status' argument.

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 is a compatibility shim over gksu_su_fuller, which, for compatibility reasons, lacks the 'exit_status' argument. You should check the documentation for gksu_su_fuller for information about the arguments.

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 is a compatibility shim over gksu_sudo_fuller, which, for compatibility reasons, lacks the 'exit_status' argument. You should check the documentation for gksu_sudo_fuller for information about the arguments.

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;
Generated by GTK-Doc V1.11