## gnome-util

gnome-util — Miscellaneous utility functions.

## Synopsis

    #include <libgnome/libgnome.h>

    #define     gnome_is_program_in_path        (program)
    const char* g_extension_pointer             (const char *path);
    #define     gnome_util_prepend_user_home    (x)
    #define     gnome_util_home_file            (afile)
    char*       gnome_util_user_shell           (void);
    int         gnome_setenv                    (const char *name,
                                                 const char *value,
                                                 gboolean overwrite);
    void        gnome_unsetenv                  (const char *name);
    void        gnome_clearenv                  (void);

    #define     g_concat_dir_and_file           (dir,file)
    #define     g_file_exists                   (filename)
    #define     g_unix_error_string             (error_num)
    #define     gnome_util_user_home            ()
    #define     g_copy_vector                   (vec)
    #define     gnome_libdir_file               (f)
    #define     gnome_datadir_file              (f)
    #define     gnome_sound_file                (f)
    #define     gnome_pixmap_file               (f)
    #define     gnome_config_file               (f)
    #define     gnome_unconditional_libdir_file (f)
    #define     gnome_unconditional_datadir_file(f)
    #define     gnome_unconditional_sound_file  (f)
    #define     gnome_unconditional_pixmap_file (f)
    #define     gnome_unconditional_config_file (f)

## Description

The functions in this section provide some shortcuts to finding certain file paths. There are also some functions for manipulating environment variables for those systems that do not have ``getenv()`` and similar functions.

### Note

Many of the function in here are now deprecated in favour of similar functions in glib. The preferred replacement function in those cases is indicated below.

## Details

### gnome_is_program_in_path()

    #define     gnome_is_program_in_path(program)

### Warning

`gnome_is_program_in_path` is deprecated and should not be used in newly-written code.

Deprecated, use g_find_program_in_path

`program` : | A program name.
Returns : | `NULL` if program is not on the path or a string allocated with `g_malloc()` with the full path name of the program found.

### g_extension_pointer ()

    const char* g_extension_pointer             (const char *path);

Extracts the extension from the end of a filename (the part after the final '.' in the filename).

`path` : | A filename or file path.
Returns : | A pointer to the extension part of the filename, or a pointer to the end of the string if the filename does not have an extension.

### gnome_util_prepend_user_home()

    #define     gnome_util_prepend_user_home(x)

Prepends the home directory of the user to a filename.

`x` : | A relative filename in the user's home directory.
Returns : | A string containing `x` with the user's home directory path prepended. The string should be freed with `g_free()` when no longer required.

### gnome_util_home_file()

    #define     gnome_util_home_file(afile)

Similar to `gnome_util_prepend_user_home()`, except that "/home/fred/.gnome2", instead of just "/home/fred/" is put on the front.

`afile` : | A filename relative to the user's .gnome2 directory. Returns: A string containing `afile` with the user's home directory path and "/.gnome2" prepended. The string should be freed with `g_free()` when no longer required.

### gnome_util_user_shell ()

    char*       gnome_util_user_shell           (void);

Retrieves the user's preferred shell.

Returns : | A newly allocated string that is the path to the shell.

### gnome_setenv ()

    int         gnome_setenv                    (const char *name,
                                                 const char *value,
                                                 gboolean overwrite);

Adds "`name`=`value`" to the environment. Note that on systems without setenv, this leaks memory so please do not use inside a loop or anything like that. The semantics are the same as the glibc `setenv()` (if `setenv()` exists, it is used).

If `overwrite` is `FALSE` and the variable already exists in the environment, then `0` is returned and the value is not changed.

`name` : | An environment variable name.
`value` : | The value to assign to the environment variable.
`overwrite` : | If `TRUE`, overwrite the existing `name` variable in the environment.
Returns : | `0` on success, `-1` on error

### gnome_unsetenv ()

    void        gnome_unsetenv                  (const char *name);

Removes `name` from the environment. In case there is no native implementation of unsetenv, this could cause leaks depending on the implementation of environment.

`name` : | The environment variable to unset.

### gnome_clearenv ()

    void        gnome_clearenv                  (void);

Clears out the environment completely. In case there is no native implementation of clearenv, this could cause leaks depending on the implementation of environment.

### g_concat_dir_and_file()

    #define     g_concat_dir_and_file(dir,file)

### Warning

`g_concat_dir_and_file` is deprecated and should not be used in newly-written code.

Programs should use `g_build_filename()` instead of this function.

`dir` : | Directory name.
`file` : | Filename.
Returns : | A newly allocated string that is the concatenation of `dir` and `file`, with seperators appropriate for the filesystem automatically taken care of.

### g_file_exists()

    #define     g_file_exists(filename)

### Warning

`g_file_exists` is deprecated and should not be used in newly-written code.

Programs should use g_file_test(`filename`, G_FILE_TEST_EXISTS) instead of this function.

`filename` : | Filename.
Returns : | Returns `TRUE` if `filename` exists, `FALSE` otherwise.

### g_unix_error_string()

    #define     g_unix_error_string(error_num)

### Warning

`g_unix_error_string` is deprecated and should not be used in newly-written code.

Programs should use `g_strerror()` instead of this function. Also, note that the returned string is only valid until the next call to `g_strerror()` or `g_unix_error_string()`.

`error_num` : | A system error number (see C errno documentation for more info).
Returns : | A string describing the error code.

### gnome_util_user_home()

    #define     gnome_util_user_home()

### Warning

`gnome_util_user_home` is deprecated and should not be used in newly-written code.

Programs should use `g_get_home_dir()` instead of this function.

Returns : | The current user's home directory.

### g_copy_vector()

    #define     g_copy_vector(vec)

### Warning

`g_copy_vector` is deprecated and should not be used in newly-written code.

Use `g_strdupv()` instead of this function.

`vec` : | An array of strings. `NULL` terminated.
Returns : | A copy of the `NULL`-terminated string array.

### gnome_libdir_file()

    #define     gnome_libdir_file(f)

### Warning

`gnome_libdir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME library directory (not the application's directory).

### gnome_datadir_file()

    #define     gnome_datadir_file(f)

### Warning

`gnome_datadir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME data directory (not the application's directory).

### gnome_sound_file()

    #define     gnome_sound_file(f)

### Warning

`gnome_sound_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME sound files directory (not the application's directory).

### gnome_pixmap_file()

    #define     gnome_pixmap_file(f)

### Warning

`gnome_pixmap_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME pixmap directory (not the application's directory).

### gnome_config_file()

    #define     gnome_config_file(f)

### Warning

`gnome_config_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME config directory (not the application's directory).

### gnome_unconditional_libdir_file()

    #define     gnome_unconditional_libdir_file(f)

### Warning

`gnome_unconditional_libdir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME library directory (not the application's directory).

### gnome_unconditional_datadir_file()

    #define     gnome_unconditional_datadir_file(f)

### Warning

`gnome_unconditional_datadir_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME data directory (not the application's directory).

### gnome_unconditional_sound_file()

    #define     gnome_unconditional_sound_file(f)

### Warning

`gnome_unconditional_sound_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME sound files directory (not the application's directory).

### gnome_unconditional_pixmap_file()

    #define     gnome_unconditional_pixmap_file(f)

### Warning

`gnome_unconditional_pixmap_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME pixmap directory (not the application's directory).

### gnome_unconditional_config_file()

    #define     gnome_unconditional_config_file(f)

### Warning

`gnome_unconditional_config_file` is deprecated and should not be used in newly-written code.

Programs should use `gnome_program_locate_file()` instead of this function.

`f` : | Filename.
Returns : | A full path to the file `f` that is stored in the system's GNOME config directory (not the application's directory).