/*
uf_dirpath.h
File description:
Prototypes for initialization of directory search path module. Using the
subroutines in this file you can:
. Add the directories of one path to another path.
. Add directories represented by strings to a path.
. Add directories represented by environment variable strings to a path.
. Retrieve the name of the current directory (with respect to an internal
index) in a path.
. Return the number of directories in a path.
. Return the index of the current directory in a path.
. Extract the directories from a path.
. Get the nth (as specified by index) directory from a path.
. Retrieve the name of the previous directory (with respect to an internal
index) in a path.
. Create a path from directories represented by strings.
. Find the first file with a specific name in a path.
. Prepare to index through each directory in a path.
******************************************************************************/
#ifndef UF_DIRPATH_H_INCLUDED
#define UF_DIRPATH_H_INCLUDED
#include <uf_defs.h>
#include <libufun_exports.h>
/******************************************************************************
Creates a path from the value of an environment variable.
Environment: Internal and External
See Also: UF_DIRPATH_create_from_dirs
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_create_from_env(
const char * env ,/* <I>
name of environment variable
*/
tag_t * retval_tag /* <O>
NULL_TAG or tag of path
*/
);
/******************************************************************************
Creates a path from directories represented by strings.
Environment: Internal and External
See Also: UF_DIRPATH_create_from_env
Please refer to example
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_create_from_dirs(
const int count ,/* <I>
number of directories
*/
const char ** dirs ,/* <I>
directories
*/
tag_t * retval_tag /* <O>
NULL_TAG or tag of path
*/
);
/******************************************************************************
Adds the directories of one path to another path.
Environment: Internal and External
See Also: UF_DIRPATH_append_from_dirs
UF_DIRPATH_append_from_env
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_append(
tag_t self ,/* <I>
Original path which will be augmented.
*/
const tag_t append /* <I>
Path to append from.
*/
);
/******************************************************************************
Adds directories represented by environment variable strings to a path.
Environment: Internal and External
See Also: UF_DIRPATH_append
UF_DIRPATH_append_from_dirs
Please refer to the example
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_append_from_env(
tag_t self ,/* <I>
Original path / augumented path.
*/
const char * env /* <I>
Name of environment variable.
*/
);
/******************************************************************************
adds directories represented by strings to a path.
Environment: Internal and External
See Also: UF_DIRPATH_append
UF_DIRPATH_append_from_env
Please refer to the example
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_append_from_dirs(
tag_t self ,/* <I>
Original path / augmented path.
*/
const int count ,/* <I>
Number of directories to be appended.
*/
const char ** dirs /* <I>
Directories
*/
);
/******************************************************************************
Extracts the directories from a path.
Environment: Internal and External
See Also:
Please refer to example
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_dirs(
tag_t self ,/* <I>
Path
*/
int * count ,/* <O>
Number of directories
*/
char *** dirs /* <OF>
Array of directories. This must be freed by the caller, using
UF_free.
*/
);
/******************************************************************************
Returns the number of directories in a path.
Return:
Number of directories
Environment: Internal and External
See Also:
Please refer to example
History:
***************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_dir_count(
tag_t self /* <I>
Path
*/
); /* */
/******************************************************************************
Returns the index of the current directory in a path.
It is best to use UF_DIRPATH_start_dir_iteration before ever using
UF_DIRPATH_ask_dir_index.
Return:
index of current directory
Environment: Internal and External
See Also: UF_DIRPATH_start_dir_iteration
Please refer to the example
History:
***************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_dir_index(
tag_t self /* <I>
path
*/
); /* */
/******************************************************************************
Gets the nth (as specified by index) directory from a path.
Environment: Internal and External
See Also: UF_DIRPATH_ask_prev_dir
UF_DIRPATH_ask_curr_dir
UF_DIRPATH_ask_next_dir
Please refer to the example
History:
***************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_nth_dir(
tag_t self ,/* <I>
Path
*/
const int index ,/* <I>
>=0 : Index of directory to locate in path
*/
char ** dir /* <OF>
nth directory. This is dynamically allocated, and must be
freed by the calling routine using UF_free.
*/
);
/******************************************************************************
Finds the first file with a specific name in a path.
Environment: Internal and External
See Also:
Please refer to example
History:
***************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_find_file(
tag_t self ,/* <I>
Path
*/
char * name ,/* <I>
Name of file to find
*/
char ** fpath /* <OF>
Path of file to find. If the file is not found, then NULL is
returned. If the path is non-NULL, then the calling program
must free this by calling UF_free.
*/
);
/******************************************************************************
This function is used to prepare to index through each directory in a path.
NOTE: This function should be called before using UF_DIRPATH_ask_next_dir,
UF_DIRPATH_ask_prev_dir, or UF_DIRPATH_ask_curr_dir.
Environment: Internal and External
See Also: UF_DIRPATH_ask_dir_index
History:
***************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_start_dir_iteration(
tag_t self /* <I>
path
*/
);
/******************************************************************************
Retrieves the name of the next directory (with respect to an internal
index) in a path. You must call UF_DIRPATH_start_dir_iteration prior to
calling this routine.
Environment: Internal and External
See Also: UF_DIRPATH_ask_prev_dir
UF_DIRPATH_start_dir_iteration
UF_DIRPATH_ask_curr_dir
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_next_dir(
tag_t self ,/* <I>
Path
*/
char ** dir /* <OF>
Next directory. This must be freed by the calling program using
UF_free.
*/
);
/******************************************************************************
Retrieves the name of the previous directory (with respect to an internal
index) in a path. You must call UF_DIRPATH_start_dir_iteration prior to
calling this routine.
Environment: Internal and External
See Also: UF_DIRPATH_ask_curr_dir
UF_DIRPATH_ask_next_dir
UF_DIRPATH_start_dir_iteration
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_prev_dir(
tag_t self ,/* <I>
Path
*/
char ** dir /* <OF>
Previous directory. This must be freed by the caller using
UF_free.
*/
);
/******************************************************************************
Retrieves the name of the current directory (with respect to an internal
index) in a path. You must call UF_DIRPATH_start_dir_iteration prior to
calling this routine.
Environment: Internal and External
See Also: UF_DIRPATH_ask_prev_dir
UF_DIRPATH_ask_next_dir
UF_DIRPATH_start_dir_iteration
History:
******************************************************************************/
extern UFUNEXPORT int UF_DIRPATH_ask_curr_dir(
tag_t self ,/* <I>
path
*/
char ** dir /* <OF>
current directory. This must be freed by the calling program
using UF_free.
*/
);
#undef EXPORTLIBRARY
#endif /* UF_DIRPATH_H_INCLUDED */