GksuContext - run programs as other users with su or sudo

GksuContext - run programs as other users with su or sudo — Handler that contains all the necessary information for a program to be run by the libgksu library.

Synopsis




                    GksuContext;
GksuContext*        gksu_context_new                    ();
void                gksu_context_free                   (GksuContext *context);
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_password           (GksuContext *context,
                                                         gchar *password);
const gchar*        gksu_context_get_password           (GksuContext *context);
void                gksu_context_set_login_shell        (GksuContext *context,
                                                         gboolean value);
gboolean            gksu_context_get_login_shell        (GksuContext *context);
void                gksu_context_set_keep_env           (GksuContext *context,
                                                         gboolean value);
gboolean            gksu_context_get_keep_env           (GksuContext *context);
void                gksu_context_set_debug              (GksuContext *context,
                                                         gboolean value);
gboolean            gksu_context_get_debug              (GksuContext *context);
void                gksu_context_set_ssh_fwd            (GksuContext *context,
                                                         gboolean value);
gboolean            gksu_context_get_ssh_fwd            (GksuContext *context);
gboolean            gksu_context_sudo_try_need_password (GksuContext *context);
gboolean            gksu_context_try_need_password      (GksuContext *context);
gboolean            gksu_context_run_full               (GksuContext *context,
                                                         GksuAskPasswordFunc ask_pass,
                                                         gpointer user_data,
                                                         GksuPasswordNotNeededFunc pass_not_needed,
                                                         gpointer pnn_user_data,
                                                         GError **error);
gboolean            gksu_context_run                    (GksuContext *context,
                                                         GError **error);
gboolean            gksu_context_sudo_run_full          (GksuContext *context,
                                                         GksuAskPasswordFunc ask_pass,
                                                         gpointer user_data,
                                                         GksuPasswordNotNeededFunc pass_not_needed,
                                                         gpointer pnn_user_data,
                                                         GError **error);
gboolean            gksu_context_sudo_run               (GksuContext *context,
                                                         GError **error);

Description

Everything that is done by libgksu needs to know a lot of stuff about what to run, as what user to run and some more information, as X authentication information and such. All that information is contained in a GksuContext.

Details

GksuContext

typedef struct {
  GObject parent;

  gchar *xauth;
  gchar *dir;

  gchar *display;

  gchar *user;
  gchar *password;
  gchar *command;

  gboolean login_shell;
  gboolean keep_env;

  gboolean debug;
  gboolean ssh_fwd;
} GksuContext;

Object that holds all configuration information, some important environment variables and some meta-information about mainly x authentication.

GObject parent;

GksuContext is based on GObject

gchar *xauth;

the X authorization token

gchar *dir;

the directory where the .Xauthority file is created in sudo mode

gchar *display;

storage for the DISPLAY environment variable

gchar *user;

user gksu will switch to

gchar *password;

the password that should be passed to su or sudo

gchar *command;

which command to run with su

gboolean login_shell;

should run a login shell?

gboolean keep_env;

should the current environment be kept?

gboolean debug;

show debug information?

gboolean ssh_fwd;

are we running inside a ssh X11 forwarding tunnel?

gksu_context_new ()

GksuContext*        gksu_context_new                    ();

Creates a new context to use gksu with. You must manually free the context with gksu_context_free after use.

Returns :

a new GksuContext.

gksu_context_free ()

void                gksu_context_free                   (GksuContext *context);

Frees the provided GksuContext.

context :

the GksuContext to be freed.

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

void                gksu_context_set_password           (GksuContext *context,
                                                         gchar *password);

Sets up what is the password to be passed to su/sudo. *

context :

the GksuContext you want to modify

password :

the password

gksu_context_get_password ()

const gchar*        gksu_context_get_password           (GksuContext *context);

Gets the password that is set for calling the su/sudo programs.

context :

the GksuContext from which to grab the information

Returns :

a pointer to the string containing the password.

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_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_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_set_ssh_fwd ()

void                gksu_context_set_ssh_fwd            (GksuContext *context,
                                                         gboolean value);

Set up if we are running inside a sshd forwarding session. That's because the X authorization semantics differ a bit. -> THIS SETTING IS CURRENTLY USED FOR NOTHING

context :

the GksuContext you want to modify

value :

TRUE or FALSE

gksu_context_get_ssh_fwd ()

gboolean            gksu_context_get_ssh_fwd            (GksuContext *context);

Finds out if the library is configured as being run inside a ssh X11 forwarding tunnel. -> THIS SETTING IS CURRENTLY USED FOR NOTHING

context :

the GksuContext from which to grab the information

Returns :

TRUE if it is, FALSE otherwise.

gksu_context_sudo_try_need_password ()

gboolean            gksu_context_sudo_try_need_password (GksuContext *context);

Checks if we need to ask for a password or if we have ways of getting the password for ourselves or we simply don't need it. Since 1.3.1.

context :

a GksuContext

Returns :

TRUE if requesting a password is needed, FALSE otherwise.

gksu_context_try_need_password ()

gboolean            gksu_context_try_need_password      (GksuContext *context);

Checks if we need to ask for a password or if we have ways of getting the password for ourselves or we simply don't need it. Since 1.3.0.

context :

a GksuContext

Returns :

TRUE if requesting a password is needed, FALSE otherwise.

gksu_context_run_full ()

gboolean            gksu_context_run_full               (GksuContext *context,
                                                         GksuAskPasswordFunc ask_pass,
                                                         gpointer user_data,
                                                         GksuPasswordNotNeededFunc pass_not_needed,
                                                         gpointer pnn_user_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 GksuAskPasswordFunc function to request a password if needed. and the GksuPasswordNotNeededFunc function if a password won't be needed, so the application has the oportunity of warning the user what it's doing. Since 1.3.3.

context :

a GksuContext

ask_pass :

a GksuAskPasswordFunc

user_data :

a gpointer with user data to be passed to the GksuAskPasswordFunc

pass_not_needed :

a GksuPasswordNotNeededFunc

pnn_user_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 :

the child's error status, 0 if all went fine, -1 if failed

gksu_context_run ()

gboolean            gksu_context_run                    (GksuContext *context,
                                                         GError **error);

This could be considered one of the main functions in GKSu. it is responsible for doing the 'user changing' magic.

context :

a GksuContext

error :

a GError object to be filled with the error code or NULL

Returns :

the child's error status, 0 if all went fine, -1 if failed

gksu_context_sudo_run_full ()

gboolean            gksu_context_sudo_run_full          (GksuContext *context,
                                                         GksuAskPasswordFunc ask_pass,
                                                         gpointer user_data,
                                                         GksuPasswordNotNeededFunc pass_not_needed,
                                                         gpointer pnn_user_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 GksuAskPasswordFunc function to request a password if needed. and the GksuPasswordNotNeededFunc function if a password won't be needed, so the application has the oportunity of warning the user what it's doing. Since 1.3.3.

context :

a GksuContext

ask_pass :

a GksuAskPasswordFunc

user_data :

a gpointer with user data to be passed to the GksuAskPasswordFunc

pass_not_needed :

a GksuPasswordNotNeededFunc

pnn_user_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 :

the child's error status, 0 if all went fine, -1 if failed

gksu_context_sudo_run ()

gboolean            gksu_context_sudo_run               (GksuContext *context,
                                                         GError **error);

This could be considered one of the main functions in GKSu. it is responsible for doing the 'user changing' magic by calling gksu_ask_password() if it needs the user's password it behaves like sudo.

context :

a GksuContext

error :

a GError object to be filled with the error code or NULL

Returns :

the child's error status, 0 if all went fine, -1 if failed

See Also

For convenience Gtk+2.0 widgets to request the user's password take a look at libgksuui1.0 and its API reference.