Gum File

Gum File — Utility functions for file handling

Synopsis

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

gboolean            (*GumFileUpdateCB)                  (GObject *object,
                                                         GumOpType op,
                                                         FILE *source_file,
                                                         FILE *dup_file,
                                                         gpointer user_data,
                                                         GError **error);
enum                GumOpType;
gboolean            gum_file_close_db_files             (const gchar *source_file_path,
                                                         const gchar *dup_file_path,
                                                         FILE *source_file,
                                                         FILE *dup_file,
                                                         GError **error);
gboolean            gum_file_create_home_dir            (const gchar *home_dir,
                                                         uid_t uid,
                                                         gid_t gid,
                                                         guint umask,
                                                         GError **error);
gboolean            gum_file_delete_home_dir            (const gchar *dir,
                                                         GError **error);
struct passwd *     gum_file_find_user_by_gid           (gid_t primary_gid,
                                                         const gchar *filename);
struct group *      gum_file_getgrgid                   (gid_t gid,
                                                         const gchar *filename);
struct group *      gum_file_getgrnam                   (const gchar *grname,
                                                         const gchar *filename);
struct passwd *     gum_file_getpwnam                   (const gchar *username,
                                                         const gchar *filename);
struct passwd *     gum_file_getpwuid                   (uid_t uid,
                                                         const gchar *filename);
struct sgrp *       gum_file_getsgnam                   (const gchar *grname,
                                                         const gchar *filename);
struct spwd *       gum_file_getspnam                   (const gchar *username,
                                                         const gchar *filename);
GFile *             gum_file_new_path                   (const gchar *dir,
                                                         const gchar *filename);
gboolean            gum_file_open_db_files              (const gchar *source_file_path,
                                                         const gchar *dup_file_path,
                                                         FILE **source_file,
                                                         FILE **dup_file,
                                                         GError **error);
gboolean            gum_file_update                     (GObject *object,
                                                         GumOpType op,
                                                         GumFileUpdateCB callback,
                                                         const gchar *source_file_path,
                                                         gpointer user_data,
                                                         GError **error);

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

Details

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.

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.

enum GumOpType

typedef enum {
    GUM_OPTYPE_ADD = 1,
    GUM_OPTYPE_DELETE = 2,
    GUM_OPTYPE_MODIFY = 3
} GumOpType;

This enumeration lists the operations on file entry.

GUM_OPTYPE_ADD

 add an entry

GUM_OPTYPE_DELETE

 delete an entry

GUM_OPTYPE_MODIFY

 modify an entry

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.

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

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.

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.

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.

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

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

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

gid :

 id of the group

filename :

 path to the file. [transfer none]

Returns :

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

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

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

Gets the passwd structure from the file based on username.

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.

uid :

 user id

filename :

 path to the file. [transfer none]

Returns :

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

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

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

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

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

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

Builds complete file path based on the filename and dir.

dir :

 directory path. [transfer none]

filename :

 name of the file. [transfer none]

Returns :

 the GFile if successful, NULL otherwise. [transfer full]

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.

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

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