gretl_paths

gretl_paths

Synopsis

enum                SearchLocation;
enum                HelpPaths;
enum                PkgType;
typedef             ConfigPaths;
void                set_string_table_written            (void);
int                 gretl_string_table_written          (void);
int                 gretl_path_prepend                  (char *file,
                                                         const char *path);
int                 gretl_normalize_path                (char *path);
int                 slash_terminate                     (char *path);
void                set_stdio_use_utf8                  (void);
int                 get_stdio_use_utf8                  (void);
int                 string_is_utf8                      (const unsigned char *s);
FILE *              gretl_fopen                         (const char *fname,
                                                         const char *mode);
FILE *              gretl_fopen_with_recode             (const char *fname,
                                                         const char *mode,
                                                         char **recoded_fname);
int                 gretl_test_fopen                    (const char *fname,
                                                         const char *mode);
FILE *              gretl_read_user_file                (const char *fname);
FILE *              gretl_mktemp                        (char *pattern,
                                                         const char *mode);
int                 gretl_open                          (const char *pathname,
                                                         int flags);
int                 gretl_rename                        (const char *oldpath,
                                                         const char *newpath);
int                 gretl_remove                        (const char *path);
gzFile              gretl_gzopen                        (const char *fname,
                                                         const char *mode);
int                 gretl_stat                          (const char *fname,
                                                         struct stat *buf);
int                 gretl_mkdir                         (const char *path);
int                 gretl_chdir                         (const char *path);
DIR *               gretl_opendir                       (const char *name);
int                 gretl_deltree                       (const char *path);
int                 gretl_setenv                        (const char *name,
                                                         const char *value);
int                 gretl_write_access                  (char *fname);
int                 gretl_is_xml_file                   (const char *fname);
int                 gretl_isdir                         (const char *path);
char *              gretl_addpath                       (char *fname,
                                                         int script);
int                 getopenfile                         (const char *line,
                                                         char *fname,
                                                         gretlopt opt);
int                 fname_has_path                      (const char *fname);
int                 has_system_prefix                   (const char *fname,
                                                         int locus);
void                show_paths                          (void);
int                 gretl_set_paths                     (ConfigPaths *paths,
                                                         gretlopt opt);
int                 gretl_update_paths                  (ConfigPaths *cpaths,
                                                         gretlopt opt);
char **             get_plausible_search_dirs           (int type,
                                                         int *n_dirs);
char *              gretl_function_package_get_path     (const char *name,
                                                         PkgType type);
void                set_gretl_plugin_path               (const char *path);
const char *        helpfile_path                       (int id);
const char *        gretl_home                          (void);
const char *        gretl_lib_path                      (void);
const char *        gretl_dotdir                        (void);
const char *        gretl_workdir                       (void);
const char *        gretl_default_workdir               (void);
const char *        maybe_get_default_workdir           (void);
char *              gretl_make_dotpath                  (const char *basename);
int                 set_gretl_work_dir                  (const char *path);
const char *        gretl_maybe_switch_dir              (const char *fname);
char *              gretl_maybe_prepend_dir             (char *fname);
const char *        gretl_gnuplot_path                  (void);
const char *        gretl_plotfile                      (void);
char *              set_gretl_plotfile                  (const char *fname);
void                report_plot_written                 (PRN *prn);
const char *        gretl_binbase                       (void);
const char *        gretl_tramo                         (void);
const char *        gretl_tramo_dir                     (void);
const char *        gretl_x12_arima                     (void);
const char *        gretl_x12_arima_dir                 (void);
const char *        gretl_rbin_path                     (void);
const char *        gretl_rlib_path                     (void);
const char *        gretl_png_font                      (void);
const char *        gretl_oxl_path                      (void);
const char *        gretl_octave_path                   (void);
const char *        gretl_stata_path                    (void);
const char *        gretl_python_path                   (void);
const char *        gretl_current_dir                   (void);
void                gretl_set_current_dir               (const char *s);
void                set_gretl_png_font                  (const char *s);
void                win32_set_gretldir                  (const char *progname);
void                get_gretl_rc_path                   (char *rcfile);
int                 cli_read_rc                         (void);
const char *        gretl_app_support_dir               (void);

Description

Details

enum SearchLocation

typedef enum {
    CURRENT_DIR,
    DATA_SEARCH,
    DB_SEARCH,
    SCRIPT_SEARCH,
    FUNCS_SEARCH,
    USER_SEARCH
} SearchLocation;

CURRENT_DIR

DATA_SEARCH

DB_SEARCH

SCRIPT_SEARCH

FUNCS_SEARCH

USER_SEARCH


enum HelpPaths

typedef enum {
    GRETL_HELPFILE,
    GRETL_CMD_HELPFILE,
    GRETL_CLI_HELPFILE
} HelpPaths;

GRETL_HELPFILE

GRETL_CMD_HELPFILE

GRETL_CLI_HELPFILE


enum PkgType

typedef enum {
    PKG_ALL,
    PKG_SUBDIR,
    PKG_TOPLEV
} PkgType;

PKG_ALL

PKG_SUBDIR

PKG_TOPLEV


ConfigPaths

typedef struct ConfigPaths_ ConfigPaths;


set_string_table_written ()

void                set_string_table_written            (void);


gretl_string_table_written ()

int                 gretl_string_table_written          (void);


gretl_path_prepend ()

int                 gretl_path_prepend                  (char *file,
                                                         const char *path);

Creates a path string by prepending path, plus an appropriate separator if needed, to file. The result is written back into file: this variable is assumed to have storage for at least MAXLEN characters.

file :

target filename.

path :

path to prepend.

Returns :

0 on success, or 1 if the final path string would exceed MAXLEN characters (including nul-termination).

gretl_normalize_path ()

int                 gretl_normalize_path                (char *path);


slash_terminate ()

int                 slash_terminate                     (char *path);

Check whether path is already slash-terminated, and if not, append a SLASH; path should be a large enough array to accept an extra byte.

path :

path string.

Returns :

1 if a slash was appended, otherwise 0.

set_stdio_use_utf8 ()

void                set_stdio_use_utf8                  (void);

Sets gretl's internal state so as to ensure that filenames are given in UTF-8 when passed to functions such as the C library's fopen().


get_stdio_use_utf8 ()

int                 get_stdio_use_utf8                  (void);

Returns :

1 if filenames should be in UTF-8 when passed to the C library's fopen() and friends, otherwise 0.

string_is_utf8 ()

int                 string_is_utf8                      (const unsigned char *s);


gretl_fopen ()

FILE *              gretl_fopen                         (const char *fname,
                                                         const char *mode);

A wrapper for the C library's fopen(), making allowance for the possibility that fname has to be converted from UTF-8 to the locale encoding or vice versa.

fname :

name of file to be opened.

mode :

mode in which to open the file.

Returns :

file pointer, or NULL on failure.

gretl_fopen_with_recode ()

FILE *              gretl_fopen_with_recode             (const char *fname,
                                                         const char *mode,
                                                         char **recoded_fname);

A wrapper for the C library's fopen(), making allowance for the possibility that fname has to be converted from UTF-8 to the locale encoding or vice versa. If conversion is carried out, the newly allocated recoded filename is returned via the last argument (otherwise that argument is not touched).

fname :

name of file to be opened.

mode :

mode in which to open the file.

recoded_fname :

location to receive recoded filename, if recoding is needed.

Returns :

file pointer, or NULL on failure.

gretl_test_fopen ()

int                 gretl_test_fopen                    (const char *fname,
                                                         const char *mode);

Attempts to open fname in the given mode; if the opening is successful the stream is then closed.

fname :

name of file to be opened.

mode :

mode as used with fopen().

Returns :

0 on success, -1 on filename encoding failure, or the system errno on failure of fopen().

gretl_read_user_file ()

FILE *              gretl_read_user_file                (const char *fname);

Attempts to open fname in read-only mode. If the file is not found when the name is used "as is", we use gretl_maybe_prepend_dir() to prepend the user's gretl working directory and try again.

fname :

name of file to open.

Returns :

file pointer, or NULL on failure.

gretl_mktemp ()

FILE *              gretl_mktemp                        (char *pattern,
                                                         const char *mode);

A wrapper for the combination of mkstemp() and fdopen(), making allowance for the possibility that template has to be converted from UTF-8 to the locale encoding or vice versa. On successful exit template holds the name of the newly created file.

pattern :

template for filename; must end with "XXXXXX".

mode :

e.g. "w" for text use or "wb" for binary mode.

Returns :

file pointer, or NULL on failure.

gretl_open ()

int                 gretl_open                          (const char *pathname,
                                                         int flags);

A wrapper for the C library's open(), making allowance for the possibility that pathname has to be converted from UTF-8 to the locale encoding or vice versa.

pathname :

name of file to be opened.

flags :

flags to pass to the system open().

Returns :

new file descriptor, or -1 on error.

gretl_rename ()

int                 gretl_rename                        (const char *oldpath,
                                                         const char *newpath);

A wrapper for the C library's rename(), making allowance for the possibility that oldpath and/or newpath have to be converted from UTF-8 to the locale encoding or vice versa.

oldpath :

name of file to be opened.

newpath :

new name to give the file.

Returns :

0 on success, non-zero on failure.

gretl_remove ()

int                 gretl_remove                        (const char *path);

A wrapper for remove(), making allowance for the possibility that path has to be converted from UTF-8 to the locale encoding or vice versa.

path :

name of file or directory to remove.

Returns :

0 on sucess, non-zero on failure.

gretl_gzopen ()

gzFile              gretl_gzopen                        (const char *fname,
                                                         const char *mode);

A wrapper for zlib's gzopen(), making allowance for the possibility that fname has to be converted from UTF-8 to the locale encoding or vice versa.

fname :

name of gzipped file to be opened.

mode :

mode in which to open the file.

Returns :

pointer to gzip stream, or NULL on failure.

gretl_stat ()

int                 gretl_stat                          (const char *fname,
                                                         struct stat *buf);

A wrapper for the C library's stat(), making allowance for the possibility that fname has to be converted from UTF-8 to the locale encoding or vice versa.

fname :

name of file to be examined.

buf :

pointer to a C struct stat.

Returns :

0 on success, non-zero on failure.

gretl_mkdir ()

int                 gretl_mkdir                         (const char *path);

Calls the underlying library function to create the specified directory with mode 0755. If the directory in question already exists, this does not count as an error.

path :

name of directory to be created.

Returns :

0 on success, non-zero on error.

gretl_chdir ()

int                 gretl_chdir                         (const char *path);

A wrapper for POSIX chdir(), making allowance for the possibility that path has to be converted from UTF-8 to the locale encoding or vice versa.

path :

name of directory.

Returns :

0 on sucess, non-zero on failure.

gretl_opendir ()

DIR *               gretl_opendir                       (const char *name);


gretl_deltree ()

int                 gretl_deltree                       (const char *path);

Carries out recursive deletion of the specified directory. Note: the current working directory should be set to one level above path when this function is called. FIXME.

path :

name of directory to be deleted.

Returns :

0 on success, non-zero on error.

gretl_setenv ()

int                 gretl_setenv                        (const char *name,
                                                         const char *value);

Cross-platform wrapper for setenv().

name :

name of variable to be set.

value :

value to set.

Returns :

0 on success, non-zero on failure.

gretl_write_access ()

int                 gretl_write_access                  (char *fname);

fname :

name of file to test.

Returns :

0 on success (meaning that the current user has write access to fname), non-zero on failure.

gretl_is_xml_file ()

int                 gretl_is_xml_file                   (const char *fname);

fname :

name of file to test.

Returns :

1 if fname appears to be a (possibly gzipped) XML file, otherwise 0.

gretl_isdir ()

int                 gretl_isdir                         (const char *path);

A test for whether or not path is the name of a directory, allowing for the possibility that path has to be converted from UTF-8 to the locale encoding or vice versa.

path :

path to check.

Returns :

1 if path is the name of a directory, else 0.

gretl_addpath ()

char *              gretl_addpath                       (char *fname,
                                                         int script);

Elementary path-searching: try adding various paths to the given fname and see if it can be opened. Usually called by getopenfile().

fname :

initially given file name.

script :

if non-zero, suppose the file is a command script.

Returns :

the full name of the file that was found, or NULL if no file could be found.

getopenfile ()

int                 getopenfile                         (const char *line,
                                                         char *fname,
                                                         gretlopt opt);

Elementary path-searching: try adding various paths to the given fname and see if it can be opened.

line :

command line (e.g. "open foo").

fname :

filename to be filled out.

opt :

if includes OPT_W, treat as web filename and don't try to add path; if OPT_S, treat as a script; if OPT_I we're responding to the "include" command.

Returns :

0 on successful parsing of line, 1 on error.

fname_has_path ()

int                 fname_has_path                      (const char *fname);


has_system_prefix ()

int                 has_system_prefix                   (const char *fname,
                                                         int locus);


show_paths ()

void                show_paths                          (void);


gretl_set_paths ()

int                 gretl_set_paths                     (ConfigPaths *paths,
                                                         gretlopt opt);


gretl_update_paths ()

int                 gretl_update_paths                  (ConfigPaths *cpaths,
                                                         gretlopt opt);


get_plausible_search_dirs ()

char **             get_plausible_search_dirs           (int type,
                                                         int *n_dirs);

type :

should be DATA_SEARCH for data file packages, DB_SEARCH for gretl databases, or FUNCS_SEARCH for function packages.

n_dirs :

location to receive the number of directories.

Returns :

an array of plausible search paths, depending on the type of search. The array should be freed when you are done with it, using strings_array_free().

gretl_function_package_get_path ()

char *              gretl_function_package_get_path     (const char *name,
                                                         PkgType type);

Searches a list of directories in which we might expect to find function packages, and, if the package in question is found, returns a newly allocated string holding the full path to the package's gfn file. Public (system) directories are searched first, then directories in the user's filespace.

name :

the name of the package to find, without the .gfn extension.

type :

PKG_SUBDIR for a recognized gretl "addon", PKG_TOPLEV for a package file not in a subdirectory, or PKG_ALL for a package that may be at either level.

Returns :

allocated path on success, otherwise NULL.

set_gretl_plugin_path ()

void                set_gretl_plugin_path               (const char *path);

For use by third-party code: the purpose of this function is to ensure that libgretl can find its plugins.

prefix, if given, should be the path under which the plugins are installed. On a unix-type system this might be, for example, /usr/local/lib/gretl-gtk2; on MS Windows it might be c:\program files\gretl\plugins.

path :

path to the gretl plugins.

helpfile_path ()

const char *        helpfile_path                       (int id);


gretl_home ()

const char *        gretl_home                          (void);


gretl_lib_path ()

const char *        gretl_lib_path                      (void);


gretl_dotdir ()

const char *        gretl_dotdir                        (void);


gretl_workdir ()

const char *        gretl_workdir                       (void);


gretl_default_workdir ()

const char *        gretl_default_workdir               (void);

Returns :

the full path to the default value of the user's gretl working directory, or NULL if it happens that this path cannot be determined, or is not writable by the current user.

maybe_get_default_workdir ()

const char *        maybe_get_default_workdir           (void);

Acts like gretl_default_workdir(), except that this function returns NULL if the default working directory is the same as the current gretl working directory, as returned by gretl_workdir().

Returns :

a path, or NULL.

gretl_make_dotpath ()

char *              gretl_make_dotpath                  (const char *basename);


set_gretl_work_dir ()

int                 set_gretl_work_dir                  (const char *path);


gretl_maybe_switch_dir ()

const char *        gretl_maybe_switch_dir              (const char *fname);


gretl_maybe_prepend_dir ()

char *              gretl_maybe_prepend_dir             (char *fname);

If fname starts with the construction "~/" to indicate the user's HOME, replace this with the full path to that directory. Otherwise, if fname is not already an absolute path, prepend either the gretl "shelldir" or the user's gretl working directory, depending on whether or USE_CWD is set. Otherwise do nothing.

fname :

the original filename, which should be in a location of length FILENAME_MAX.

Returns :

the possibly modified filename.

gretl_gnuplot_path ()

const char *        gretl_gnuplot_path                  (void);


gretl_plotfile ()

const char *        gretl_plotfile                      (void);


set_gretl_plotfile ()

char *              set_gretl_plotfile                  (const char *fname);


report_plot_written ()

void                report_plot_written                 (PRN *prn);


gretl_binbase ()

const char *        gretl_binbase                       (void);


gretl_tramo ()

const char *        gretl_tramo                         (void);


gretl_tramo_dir ()

const char *        gretl_tramo_dir                     (void);


gretl_x12_arima ()

const char *        gretl_x12_arima                     (void);


gretl_x12_arima_dir ()

const char *        gretl_x12_arima_dir                 (void);


gretl_rbin_path ()

const char *        gretl_rbin_path                     (void);


gretl_rlib_path ()

const char *        gretl_rlib_path                     (void);


gretl_png_font ()

const char *        gretl_png_font                      (void);


gretl_oxl_path ()

const char *        gretl_oxl_path                      (void);


gretl_octave_path ()

const char *        gretl_octave_path                   (void);


gretl_stata_path ()

const char *        gretl_stata_path                    (void);


gretl_python_path ()

const char *        gretl_python_path                   (void);


gretl_current_dir ()

const char *        gretl_current_dir                   (void);


gretl_set_current_dir ()

void                gretl_set_current_dir               (const char *s);


set_gretl_png_font ()

void                set_gretl_png_font                  (const char *s);


win32_set_gretldir ()

void                win32_set_gretldir                  (const char *progname);


get_gretl_rc_path ()

void                get_gretl_rc_path                   (char *rcfile);


cli_read_rc ()

int                 cli_read_rc                         (void);


gretl_app_support_dir ()

const char *        gretl_app_support_dir               (void);