util.c

Go to the documentation of this file.

/*****************************************************************************/
/******************************** Documentation ******************************/
/*****************************************************************************/

/**
 * \file
 *  General utility routines shared by several modules.
 */

/*****************************************************************************/
/******************************* Include Files *******************************/
/*****************************************************************************/

#define _GNU_SOURCE             /**< Turn on GNU extensions */
#include <stdio.h>
#include <stdlib.h>
#include <stdarg.h>
#include <stdint.h>
#include <unistd.h>
#include <string.h>
#include <ctype.h>
#include <errno.h>
#include <pwd.h>
#include <grp.h>

#include <sys/param.h>
#include <sys/stat.h>

#include "dhash.h"
#include "util.h"
#include "path_utils.h"
#include "logging.h"
#include "inotify_watch.h"
#include "watch_database.h"

/*****************************************************************************/
/****************************** Internal Defines *****************************/
/*****************************************************************************/

/*****************************************************************************/
/************************** Internal Type Definitions ************************/
/*****************************************************************************/

/*****************************************************************************/
/**********************  External Function Declarations  *********************/
/*****************************************************************************/

/*****************************************************************************/
/**********************  Internal Function Declarations  *********************/
/*****************************************************************************/

/*****************************************************************************/
/*************************  External Global Variables  ***********************/
/*****************************************************************************/

/**
 * Global integer value used to indicate debugging level.
 *
 * The primary use of this variable is to prevent executing code used to
 * generate debug information if that information is not going to be used. It's
 * an efficiency optimization.
 *
 * The larger the value the more verbose debug output should be. Zero indicates
 * no debug information should be generated.
 */
int debug = 0;

/*****************************************************************************/
/*************************  Internal Global Variables  ***********************/
/*****************************************************************************/

/*****************************************************************************/
/****************************  Inline Functions  *****************************/
/*****************************************************************************/

/*****************************************************************************/
/***************************  Internal Functions  ****************************/
/*****************************************************************************/

/*****************************************************************************/
/****************************  Exported Functions  ***************************/
/*****************************************************************************/

/**
 * Callback used by qsort() to compare two hash keys.
 *
 * The two parameters are coerced to pointers to hash_key_t structs. If the key
 * is not a string it is converted to a string. Then the two key strings are
 * compared and the result returned. The primary use of this function is to
 * produce a sorted list of hash keys.
 */
int key_string_cmp(const void *_a, const void *_b)
{
    const hash_key_t *a = _a, *b = _b;
    char buf_a[128], buf_b[128];
    const char *str_a, *str_b;

    switch(a->type) {
    case HASH_KEY_STRING:
        str_a = a->str;
        break;
    case HASH_KEY_ULONG:
        snprintf(buf_a, sizeof(buf_a), "%lu", a->ul);
        str_a = buf_a;
        break;
    default:
        buf_a[0] = 0;
        str_a = buf_a;
    }

    switch(b->type) {
    case HASH_KEY_STRING:
        str_b = b->str;
        break;
    case HASH_KEY_ULONG:
        snprintf(buf_b, sizeof(buf_b), "%lu", b->ul);
        str_b = buf_b;
        break;
    default:
        buf_b[0] = 0;
        str_b = buf_b;
    }

    return strcmp(str_a, str_b);
}

/**
 * Callback used by qsort() to compare two hash entries.
 *
 * The two parameters are coerced to pointers to hash_entry_t structs. If the
 * key in each entry is not a string it is converted to a string. Then the two
 * key strings are compared and the result returned. The primary use of this
 * function is to produce a sorted list of hash entries.
 */
int entry_string_cmp(const void *_a, const void *_b)
{
    const hash_entry_t *a = _a, *b = _b;
    char buf_a[128], buf_b[128];
    const char *str_a, *str_b;

    switch(a->key.type) {
    case HASH_KEY_STRING:
        str_a = a->key.str;
        break;
    case HASH_KEY_ULONG:
        snprintf(buf_a, sizeof(buf_a), "%lu", a->key.ul);
        str_a = buf_a;
        break;
    default:
        buf_a[0] = 0;
        str_a = buf_a;
    }

    switch(b->key.type) {
    case HASH_KEY_STRING:
        str_b = b->key.str;
        break;
    case HASH_KEY_ULONG:
        snprintf(buf_b, sizeof(buf_b), "%lu", b->key.ul);
        str_b = buf_b;
        break;
    default:
        buf_b[0] = 0;
        str_b = buf_b;
    }

    return strcmp(str_a, str_b);
}

/**
 * Generate a string with the keys of a hash table in sorted order.
 * \param[in] table  The hash table to format
 * \param[in] prefix The string inserted before each key. May be NULL.
 * \param[in] suffix The string appended after each key. May be NULL.
 * \return       Pointer to a string which must be freed by the caller.
 *
 */
char *keys_string(hash_table_t *table, const char *prefix, const char *suffix)
{
    int prefix_len, suffix_len, extra_len;
    hash_key_t *keys, *key;
    int error;
    unsigned long i, count;
    int alloc_len;
    char tmp_buf[128];
    char *buf, *p, *buf_end;

    /*
     * Compute how many extra chars we'll need for each key after adding the
     * prefix and suffix.
     */
    prefix_len = prefix ? strlen(prefix) : 0;
    suffix_len = suffix ? strlen(suffix) : 0;
    extra_len = prefix_len + suffix_len;

    /* Get a list of keys in the table and a count of how many there are */
    if ((error = hash_keys(table, &count, &keys)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("could not get key array (%s)\n"),  error_string(error));
        return NULL;
    }

    /* Special case, if the table is empty return the empty string */
    if (count == 0) {
        return strdup("");
    }

    /* Sort the list of keys */
    qsort(keys, count, sizeof(hash_key_t), key_string_cmp);

    /* Iterate over the list and compute the maximum size of the resulting string */
    alloc_len = 0;
    for (i = 0; i < count; i++) {
        key = &keys[i];
        switch(key->type) {
        case HASH_KEY_STRING:
            alloc_len += strlen(key->str) + extra_len;
            break;
        case HASH_KEY_ULONG:
            snprintf(tmp_buf, sizeof(tmp_buf), "%lu", key->ul);
            alloc_len += strlen(tmp_buf) + extra_len;
            break;
        }
    }

    /* Allocate the return string and set up some pointers */
    alloc_len += 1;             /* +1 for NULL terminator */
    if ((buf = malloc(alloc_len)) == NULL) {
        free(keys);
        return NULL;
    }
    p = buf;                    /* current position in buffer */
    buf_end = &buf[alloc_len];  /* non-inclusive end of buffer */

    /* Iterate over the keys appending the prefix, key, and suffix for each key */
    for (i = 0; i < count; i++) {
        key = &keys[i];
        switch(key->type) {
        case HASH_KEY_STRING:
            p += snprintf(p, buf_end - p, "%s%s%s", prefix?prefix:"", key->str, suffix?suffix:"");
            if (p >= buf_end) goto fail; /* should never happen */
            break;
        case HASH_KEY_ULONG:
            p += snprintf(p, buf_end - p, "%s%lu%s", prefix?prefix:"", key->ul, suffix?suffix:"");
            if (p >= buf_end) goto fail; /* should never happen */
            break;
        }
    }
    /* Delete the final suffix */
    if (p > buf) p[-suffix_len] = 0;
    free(keys);
    return buf;
 fail:
    /* exhausted the buffer; NULL terminate then return truncated string */
    buf_end[-1] = 0;   /* should already be NULL terminated, but be safe */
    free(keys);
    return buf;

}

/**
 * Pretty print the contents of the watch_path_table.
 * \param[in] table The table to serialize into a string
 * \return A string with the table contents, caller must free this string.
 *
 * The watch_path_table contains a set of path_watch_t structures indexed by
 * pathname. Generate a list of the table contents, sort the list by pathname,
 * then iterate over each associated path_watch_t structure, pretty print it and
 * append it to the total string. Return the resulting string.
 */
char *watch_path_table_string(hash_table_t *table)
{
    int error;
    hash_entry_t *entries;
    unsigned long i, count;
    struct path_watch_t *pw;
    char *pw_string;
    char *tbl_string;
    size_t alloc_len, alloc_increment;
    size_t pw_string_len, tbl_string_len, needed_len;

    alloc_increment = 1024;
    tbl_string_len = 0;

    if ((tbl_string = malloc(alloc_len = alloc_increment)) == NULL) {
        return NULL;
    }
    *tbl_string = 0;

    /* Get a list of entries in the table */
    if ((error = hash_entries(table, &count, &entries)) != HASH_SUCCESS) {
        log_msg(LOG_ERROR, _("could not get entry array (%s)\n"),  error_string(error));
        return NULL;
    }

    /* Sort the list by pathname */
    qsort(entries, count, sizeof(hash_entry_t), entry_string_cmp);

    /* Iterate over the list */
    for (i = 0; i < count; i++) {
        /* Get the path_watch_t struct and format it */
        pw = (struct path_watch_t *) entries[i].value.ptr;
        if ((pw_string = path_watch_string(pw)) == NULL) {
            free(entries);
            return NULL;
        }
        /* Make sure we've got enough room to append the formatted path_watch_t string plus a newline */
        pw_string_len = strlen(pw_string);
        needed_len = pw_string_len + 1; /* for newline or NULL */
        if (tbl_string_len + needed_len > alloc_len) {
            alloc_len = alloc_len + MAX(needed_len,alloc_increment);
            if ((tbl_string = realloc(tbl_string, alloc_len)) == NULL) {
                free(tbl_string);
                free(entries);
                return NULL;
            }
        }
        /* Append the formatted path_watch_t string, we know there is sufficient room in the destination */
        strncpy(tbl_string + tbl_string_len, pw_string, alloc_len - tbl_string_len);
        tbl_string_len += pw_string_len;

        /* We're done with the formatted entry having just copied, so we can free it now */
        free(pw_string);

        /* Append a newline, we know there is sufficient room in the destination */
        strncpy(tbl_string + tbl_string_len, "\n", alloc_len - tbl_string_len);
        tbl_string_len += 1;
    }
    /* We're done with the list of entries */
    free(entries);

    /* Replace the last newline with a NULL terminator */
    if (tbl_string_len > 0) tbl_string[tbl_string_len - 1] = 0;
    return tbl_string;
}

/**
 * Strip leading and trailing whitespace.
 * Works in place on supplied string.
 */
int strip_whitespace(char *str)
{
    char *p = str;

    /* Find first non-space char, if not at beginning of string shift string left */
    for (p = str; *p && isspace(*p); p++);
    if (p != str) memmove(str, p, strlen(p) + 1);

    /* Goto end of string, working backward replace each space char with NULL */
    for (p = str; *p; p++);
    for (p--; p >= str; p--) {
        if (isspace(*p))
            *p = 0;
        else
            break;
    }
    return SUCCESS;
}

/**
 * Return a static string describing the error code for util errors
 * \param[in] error The error code
 * \return Pointer to thread local static string describing the error code.
 *
 * Note:  IS_UTIL_ERROR(error) code should true otherwise the error code is
 * outside the set of values this function knows about. If the error code is not
 * recognized the string "unknown(XXX)" will be returned instead where XXX is
 * the decimal representation of the error code.
 */
const char *util_error_string(int error)
{
    static __thread char buf[80]; /* thread local static buffer */

    switch(error) {
    case SUCCESS:                       return _("Success");
    case UTIL_ERROR_NOT_FOUND:          return _("Not found");
    default:
        snprintf(buf, sizeof(buf), _("unknown(%d)"), error);
        return buf;
    }
}

/**
 * Return a static string describing the error code for lwatch
 * \param[in] error The error code
 * \return Pointer to thread local static string describing the error code.
 *
 * Note:  IS_LWATCH_ERROR(error) should true otherwise the error code is
 * outside the set of values this function knows about. If the error code is not
 * recognized the string "unknown(XXX)" will be returned instead where XXX is
 * the decimal representation of the error code.
 */
const char *lwatch_error_string(int error)
{
    static __thread char buf[80]; /* thread local static buffer */

    switch(error) {
    case LWATCH_ERROR_CANNOT_MONITOR:        return _("cannot monitor target");
    case LWATCH_ERROR_CANNOT_FIND_PATH_INFO: return _("cannot find path info");
    case LWATCH_ERROR_LOST_RENAME:           return _("one of the paths for a rename event is unknown");
    case LWATCH_ERROR_STAT_NOT_VALID:        return _("stat information is not valid");
    default:
        snprintf(buf, sizeof(buf), _("unknown(%d)"), error);
        return buf;
    }
}

/**
 * Return a static string describing the error code
 * \param[in] error The error code
 * \return Pointer to thread local static string describing the error code.
 *
 * The error code is tested against each of the known error ranges for modules
 * in this project. If the error matches one of the known internal error ranges
 * then the error_string() function for that module is called and it's result
 * returned. Otherwise the result of strerror() is returned.
 */
const char *error_string(int error)
{
    static __thread char buf[256];   /* thread local static buffer for strerror_r() */

    if (IS_HASH_ERROR(error))
        return hash_error_string(error);
    if (IS_INOTIFY_WATCH_ERROR(error))
        return inotify_watch_error_string(error);
    if (IS_PATH_UTILS_ERROR(error))
        return path_utils_error_string(error);
    if (IS_WATCH_DATABASE_ERROR(error))
        return watch_database_error_string(error);
    if (IS_LWATCH_ERROR(error))
        return lwatch_error_string(error);

    strerror_r(error, buf, sizeof(buf));
    return buf;
}

/**
 * Format a time_t value as a string, either in local time or UTC.
 * \param[in] t the time_t value in the UTC time zone to be formatted.
 * \param[in] local If true the formatted string will be in local time, otherwise
 *              the string will be be in UTC (i.e. the zone offset will be zero).
 * \param[in] fmt   Optional strftime format string, if NULL format according to ISO 8601
 * \return      Pointer to a thread local static time string.
 *
 * time_string(t, true, NULL) is the standard way to format time values, it will
 * produce an ISO 8601 formatted string which preserves the local offset. The
 * 8601 string in local time is trivially convertable to UTC during subsequent
 * parsing, there is no loss of information (other than the zone info which was
 * used to set the systems UTC offset). For timestamps the suggested calling
 * parameters will yield the ideal timestamp format.
 */
const char *time_string(time_t t, bool local, const char *fmt)
{
    static __thread char buf[128]; /* thread local static buffer */
    struct tm tm_time;

    if (local)
        localtime_r(&t, &tm_time);
    else
        gmtime_r(&t, &tm_time);

    if (!fmt) {
        if (local) {
            fmt = "%FT%T%z";
        } else {
            fmt = "%FT%TZ";
        }
    }
    strftime(buf, sizeof(buf), fmt, &tm_time);
    return buf;
}

/**
 * Return the file mode flags as a formatted string.
 * \param[in] mode The file mode flags to be formatted.
 * \return     Returns pointer to a thread local static string
 *
 * The format of the string is identical to what "ls -l" produces, e.g.:
 * "-rw-r--r--"
 */
const char *file_mode_string(mode_t mode)
{
    static __thread char buf[11];

  if (S_ISREG (mode))
    buf[0] = '-';
  else if (S_ISDIR (mode))
    buf[0] = 'd';
  else if (S_ISBLK (mode))
    buf[0] = 'b';
  else if (S_ISCHR (mode))
    buf[0] = 'c';
  else if (S_ISLNK (mode))
    buf[0] = 'l';
  else if (S_ISFIFO (mode))
    buf[0] = 'p';
  else if (S_ISSOCK (mode))
    buf[0] = 's';
  else
    buf[0] = '?';

  buf[1] = mode & S_IRUSR ? 'r' : '-';
  buf[2] = mode & S_IWUSR ? 'w' : '-';
  buf[3] = (mode & S_ISUID
            ? (mode & S_IXUSR ? 's' : 'S')
            : (mode & S_IXUSR ? 'x' : '-'));
  buf[4] = mode & S_IRGRP ? 'r' : '-';
  buf[5] = mode & S_IWGRP ? 'w' : '-';
  buf[6] = (mode & S_ISGID
            ? (mode & S_IXGRP ? 's' : 'S')
            : (mode & S_IXGRP ? 'x' : '-'));
  buf[7] = mode & S_IROTH ? 'r' : '-';
  buf[8] = mode & S_IWOTH ? 'w' : '-';
  buf[9] = (mode & S_ISVTX
            ? (mode & S_IXOTH ? 't' : 'T')
            : (mode & S_IXOTH ? 'x' : '-'));
  buf[10] = '\0';

  return buf;
}

/**
 * Given a system uid get the user name as a string.
 * \param[in] uid  The uid whose name is to be looked up.
 * \param[out] name Pointer where to receive name, must call free()
 * \return     Error code
 *
 * Returns SUCCESS (0) if successful, non-zero error code otherwise.
 */
int get_uid_name(uid_t uid, char **name)
{
    struct passwd pw;
    struct passwd *result;
    char *buf;
    size_t bufsize;
    int error;

    *name = NULL;
    bufsize = sysconf(_SC_GETPW_R_SIZE_MAX);
    if (bufsize == -1)          /* Value was indeterminate */
        bufsize = 16384;        /* Should be more than enough */

    if ((buf = malloc(bufsize)) == NULL) {
        error = errno;
        log_msg(LOG_ERROR, "Failed getting uid name for %d, could not alloc buffer for getpwuid_r (%s)", uid, strerror(error));
        *name = NULL;
        return error;
    }

    error = getpwuid_r(uid, &pw, buf, bufsize, &result);
    if (result == NULL) {
        if (error == 0) {
            error = UTIL_ERROR_NOT_FOUND;
            log_msg(LOG_INFO, "uid name for %d was not found (%s)", uid, strerror(error));
        } else {
            log_msg(LOG_ERROR, "getpwuid_r() failed, uid = %d: (%s)", uid, strerror(error));
        }
        *name = strdup(_("unknown"));
        free(buf);
        return error;
    } else {
        *name = strdup(pw.pw_name);
    }

    free(buf);
    return SUCCESS;
}

/**
 * Given a system gid get the group name as a string.
 * \param[in] gid  The gid whose name is to be looked up.
 * \param[out] name Pointer where to receive name, must call free()
 * \return     Error code
 *
 * Returns SUCCESS (0) if successful, non-zero error code otherwise.
 */
int get_gid_name(gid_t gid, char **name)
{
    struct group gr;
    struct group *result;
    char *buf;
    size_t bufsize;
    int error;

    *name = NULL;
    bufsize = sysconf(_SC_GETGR_R_SIZE_MAX);
    if (bufsize == -1)          /* Value was indeterminate */
        bufsize = 16384;        /* Should be more than enough */

    if ((buf = malloc(bufsize)) == NULL) {
        error = errno;
        log_msg(LOG_ERROR, "Failed getting gid name for %d, could not alloc buffer for getgrgid_r (%s)", gid, strerror(error));
        *name = NULL;
        return error;
    }

    error = getgrgid_r(gid, &gr, buf, bufsize, &result);
    if (result == NULL) {
        if (error == 0) {
            error = UTIL_ERROR_NOT_FOUND;
            log_msg(LOG_INFO, "gid name for %d was not found (%s)", gid, strerror(error));
        } else {
            log_msg(LOG_ERROR, "getgrgid_r() failed, gid = %d: (%s)", gid, strerror(error));
        }
        *name = strdup(_("unknown"));
        free(buf);
        return error;
    } else {
        *name = strdup(gr.gr_name);
    }

    free(buf);
    return SUCCESS;
}

---