LibGKSu Reference Manual: API Reference

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

## Functions

GksuContext * | gksu_context_new ()
void | gksu_context_set_user ()
const gchar * | gksu_context_get_user ()
void | gksu_context_set_command ()
const gchar * | gksu_context_get_command ()
void | gksu_context_set_keep_env ()
gboolean | gksu_context_get_keep_env ()
gchar * | gksu_context_get_description ()
void | gksu_context_set_description ()
void | gksu_context_set_message ()
gchar * | gksu_context_get_message ()
void | gksu_context_set_login_shell ()
gboolean | gksu_context_get_login_shell ()
void | gksu_context_set_grab ()
gboolean | gksu_context_get_grab ()
void | gksu_context_set_debug ()
gboolean | gksu_context_get_debug ()
void | gksu_context_free ()
gboolean | gksu_run ()
gboolean | gksu_run_full ()
gboolean | gksu_su ()
gboolean | gksu_su_full ()
gboolean | gksu_sudo ()
gboolean | gksu_sudo_full ()
gchar * | gksu_ask_password ()
gchar * | gksu_ask_password_full ()

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

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

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

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

#### 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 |  |