API Reference

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

Functions

Types and Values

enum GksuError

Description

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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?

Parameters

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.

Parameters

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


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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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 GSettings key that defines whether the default behavior for gksu is su or sudo mode. This is the recommended way of using the library functionality.

Parameters

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.

Parameters

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 gsettings 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.

Parameters

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.

Parameters

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 gsettings 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.

Parameters

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.

Parameters

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 gsettings 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.

Parameters

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.

Parameters

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;

Types and Values

enum GksuError

Members

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