gumd API Reference Manual: Gum File

Gum File

Gum File — Utility functions for file handling

Functions

gboolean	(*GumFileUpdateCB) ()
gboolean	gum_file_update ()
gboolean	gum_file_open_db_files ()
gboolean	gum_file_close_db_files ()
struct passwd *	gum_file_getpwnam ()
struct passwd *	gum_file_getpwuid ()
struct passwd *	gum_file_find_user_by_gid ()
struct spwd *	gum_file_getspnam ()
struct group *	gum_file_getgrnam ()
struct group *	gum_file_getgrgid ()
struct sgrp *	gum_file_getsgnam ()
GFile *	gum_file_new_path ()
gboolean	gum_file_create_home_dir ()
gboolean	gum_file_delete_home_dir ()

Types and Values

enum

GumOpType

Object Hierarchy

Includes

#include <gum/common/gum-file.h>

Description

Below is the code snippet, which demonstrate how can file update function be used to add, remove or modify an entry in the user/group database file (e.g. /etc/passwd).


  gboolean _custom_update_file_entries (GObject *obj, GumOpType op,
     FILE *source_file, FILE *dup_file, gpointer user_data, GError **error)
  {
     //loop through the file entries and modify as per operation type
     return TRUE;
  }

  void update_file_entries ()
  {
     GObject* obj = NULL;
     GError *error = NULL;
     const gchar *source_file = "/tmp/passwd";
     gum_file_update (obj, GUM_OPTYPE_ADD,
      (GumFileUpdateCB)_custom_update_file_entries, source_file, NULL,
      &error);
  }

Functions

GumFileUpdateCB ()

gboolean
(*GumFileUpdateCB) (GObject *object,
                    GumOpType op,
                    FILE *source_file,
                    FILE *dup_file,
                    gpointer user_data,
                    GError **error);

Callback can be used for adding, deleting or modifying file entries. It is invoked in gum_file_update function.

Parameters

object	the instance of GObject.	[transfer none]
op	the GumOpType operation to be done on the file entry.	[transfer none]
source_file	the source file pointer.	[transfer none]
dup_file	the duplicate file pointer.	[transfer none]
user_data	the user data
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

gum_file_update ()

gboolean
gum_file_update (GObject *object,
                 GumOpType op,
                 GumFileUpdateCB callback,
                 const gchar *source_file_path,
                 gpointer user_data,
                 GError **error);

Opens the files and invokes the callback to do the required operation. Finally files are flushed and closed.

Parameters

object	the instance of GObject; can be NULL.	[transfer none]
op	the GumOpType operation to be done on file entry the source file.	[transfer none]
callback	the callback GumFileUpdateCB to be invoked when the source and duplicate files are opened to be handled.	[transfer none]
source_file_path	the source file path.	[transfer none]
user_data	user data to be passed on to the `callback`
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

gum_file_open_db_files ()

gboolean
gum_file_open_db_files (const gchar *source_file_path,
                        const gchar *dup_file_path,
                        FILE **source_file,
                        FILE **dup_file,
                        GError **error);

Opens the source file source_file_path in read mode. Then creates the duplicate file dup_file_path in write mode and copies source file attributes to the duplicate file. Open file handles are set in source_file and dup_file .

Parameters

source_file_path	the path to source file.	[transfer none]
dup_file_path	the path to duplicate file, created from the source file.	[transfer none]
source_file	the file pointer created when source file is opened in read mode.	[transfer none]
dup_file	the file pointer created when duplicate file is opened in write mode.	[transfer none]
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

gum_file_close_db_files ()

gboolean
gum_file_close_db_files (const gchar *source_file_path,
                         const gchar *dup_file_path,
                         FILE *source_file,
                         FILE *dup_file,
                         GError **error);

Closes the duplicate file dup_file_path after flushing all the data. Backup of the source file source_file_path is created and duplicate file is renamed to as the source file.

Parameters

source_file_path	the path to source file.	[transfer none]
dup_file_path	the path to duplicate file.	[transfer none]
source_file	the source file pointer.	[transfer none]
dup_file	the duplicate file pointer.	[transfer none]
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

gum_file_getpwnam ()

struct passwd *
gum_file_getpwnam (const gchar *username,
                   const gchar *filename);

Gets the passwd structure from the file based on username.

Parameters

username	name of the user.	[transfer none]
filename	path to the file.	[transfer none]

Returns

passwd structure if successful, NULL otherwise.

[transfer full]

gum_file_getpwuid ()

struct passwd *
gum_file_getpwuid (uid_t uid,
                   const gchar *filename);

Gets the passwd structure from the file based on uid.

Parameters

uid	user id
filename	path to the file.	[transfer none]

Returns

passwd structure if successful, NULL otherwise.

[transfer full]

gum_file_find_user_by_gid ()

struct passwd *
gum_file_find_user_by_gid (gid_t primary_gid,
                           const gchar *filename);

Gets the passwd structure from the file based on the primary group id.

Parameters

primary_gid	primary gid of the user
filename	path to the file.	[transfer none]

Returns

passwd structure if successful, NULL otherwise.

[transfer full]

gum_file_getspnam ()

struct spwd *
gum_file_getspnam (const gchar *username,
                   const gchar *filename);

Gets the spwd structure from the file based on the username.

Parameters

username	name of the user.	[transfer none]
filename	path to the file.	[transfer none]

Returns

spwd structure if successful, NULL otherwise.

[transfer full]

gum_file_getgrnam ()

struct group *
gum_file_getgrnam (const gchar *grname,
                   const gchar *filename);

Gets the group structure from the file based on the groupname grname .

Parameters

grname	name of the group.	[transfer none]
filename	path to the file.	[transfer none]

Returns

group structure if successful, NULL otherwise.

[transfer full]

gum_file_getgrgid ()

struct group *
gum_file_getgrgid (gid_t gid,
                   const gchar *filename);

Gets the group structure from the file based on the gid.

Parameters

gid	id of the group
filename	path to the file.	[transfer none]

Returns

group structure if successful, NULL otherwise.

[transfer full]

gum_file_getsgnam ()

struct sgrp *
gum_file_getsgnam (const gchar *grname,
                   const gchar *filename);

Gets the sgrp structure from the file based on the groupname grname .

Parameters

grname	name of the group.	[transfer none]
filename	path to the file.	[transfer none]

Returns

sgrp structure if successful, NULL otherwise.

[transfer full]

gum_file_new_path ()

GFile *
gum_file_new_path (const gchar *dir,
                   const gchar *filename);

Builds complete file path based on the filename and dir .

Parameters

dir	directory path.	[transfer none]
filename	name of the file.	[transfer none]

Returns

the GFile if successful, NULL otherwise.

[transfer full]

gum_file_create_home_dir ()

gboolean
gum_file_create_home_dir (const gchar *home_dir,
                          uid_t uid,
                          gid_t gid,
                          guint umask,
                          GError **error);

Creates the home directory of the user. All the files from the GUM_CONFIG_GENERAL_SKEL_DIR are copied (recursively) to the user home directory.

Parameters

home_dir	path to the user home directory
uid	id of the user
gid	group id of the user
umask	the umask to be used for setting the mode of the files/directories
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

gum_file_delete_home_dir ()

gboolean
gum_file_delete_home_dir (const gchar *dir,
                          GError **error);

Deletes the directory and its sub-directories recursively.

Parameters

dir	the path to the directory.	[transfer none]
error	the GError which is set in case of an error.	[transfer none]

Returns

TRUE if successful, FALSE otherwise and error is set.

Types and Values

enum GumOpType

This enumeration lists the operations on file entry.

Members

GUM_OPTYPE_ADD	add an entry
GUM_OPTYPE_DELETE	delete an entry
GUM_OPTYPE_MODIFY	modify an entry