File Processing

Routines for handling, inspecting, and comparing files and directories. More...

Collaboration diagram for File Processing:

Files
file	file.h

Functions
int	bu_file_exists (const char *path, int *fd)
int	bu_file_size (const char *path)
int	bu_file_same (const char *fn1, const char *fn2)
int	bu_file_readable (const char *path)
int	bu_file_writable (const char *path)
int	bu_file_executable (const char *path)
int	bu_file_directory (const char *path)
int	bu_file_symbolic (const char *path)
int	bu_file_delete (const char *path)
size_t	bu_file_list (const char *path, const char *pattern, char ***files)
char *	bu_file_realpath (const char *path, char *resolved_path)
int	bu_fseek (FILE *stream, b_off_t offset, int origin)
b_off_t	bu_lseek (int fd, b_off_t offset, int whence)
b_off_t	bu_ftell (FILE *stream)

Detailed Description

Routines for handling, inspecting, and comparing files and directories.

These routines involve filesystem interaction such as reporting whether a file exists or is of a particular type.

Function Documentation

bu_file_exists()

int bu_file_exists	(	const char *	path,
		int *	fd
	)

Returns truthfully whether the given file path exists or not. An empty or NULL path name is treated as a non-existent file and, as such, will return false. If fd is non-NULL, it will be set to a read-only open file descriptor for the provided path. If path is "-", fd is set to standard input's file descriptor if provided.

Returns

>0 The given filename exists.

0 The given filename does not exist.

bu_file_size()

int bu_file_size

(

const char *

path

)

Returns the size of the given file, or -1 if the size cannot be determined.

Returns

>=0 The given filename exists.

-1 The given filename does not exist or there was an error.

bu_file_same()

int bu_file_same	(	const char *	fn1,
		const char *	fn2
	)

Returns truthfully as to whether the two provided filenames are the same file. If either file does not exist, the result is false. If either filename is empty or NULL, it is treated as non-existent and, as such, will also return false.

bu_file_readable()

int bu_file_readable

(

const char *

path

)

returns truthfully if current user can read the specified file or directory.

bu_file_writable()

int bu_file_writable

(

const char *

path

)

returns truthfully if current user can write to the specified file or directory.

bu_file_executable()

int bu_file_executable

(

const char *

path

)

returns truthfully if current user can run the specified file or directory.

bu_file_directory()

int bu_file_directory

(

const char *

path

)

Returns truthfully whether the given file path is a directory. An empty or NULL path name is treated as a non-existent directory and, as such, will return false.

Returns

>0 The given filename is a directory

0 The given filename is not a directory.

bu_file_symbolic()

int bu_file_symbolic

(

const char *

path

)

Returns truthfully whether the given file path is a symbolic link. An empty or NULL path name is treated as a non-existent link and, as such, will return false.

Returns

>0 The given filename is a symbolic link

0 The given filename is not a symbolic link.

bu_file_delete()

int bu_file_delete

(

const char *

path

)

forcibly attempts to delete a specified file. if the file can be deleted by relaxing file permissions, they will be changed in order to delete the file.

returns truthfully if the specified file was deleted.

bu_file_list()

size_t bu_file_list	(	const char *	path,
		const char *	pattern,
		char ***	files
	)

Get a listing of files in a directory, optionally matching a pattern.

If the caller provides a pointer to an argv-style 'files' array, this function will dynamically allocate an array of strings, filled with the sorted listing of matching file(s). It is the caller's responsibility to free a non-NULL array with bu_argv_free().

If '*files' is NULL, the caller is expected to free the matches array with bu_argv_free(). If '*files' is non-NULL (i.e., array of string pointers is already allocated or on the stack), the caller is expected to ensure adequate entries are preallocated and to free all strings with bu_argv_free() or as otherwise necessary.

Example:

// This allocates an array for storing matches, filling in the
// array with all directory paths starting with 'a' through 'e' and
// ending with a '.c' in the src/libbu directory.
 
char **my_matches = NULL;
size_t count = bu_file_list("src/libbu", "[a-e]*.c", &my_matches);

Returns

the number of directory entries matching the provided pattern.

bu_file_realpath()

char * bu_file_realpath	(	const char *	path,
		char *	resolved_path
	)

This routine expands a path to a resolved canonical full path.

Returns a pointer to the canonical path. If resolved_path is NULL, caller is responsible for freeing the returned path via bu_free. If supplying a non-NULL resolved_path buffer, it must hold at least MAXPATHLEN characters.

bu_fseek()

int bu_fseek	(	FILE *	stream,
		b_off_t	offset,
		int	origin
	)

Windows corecrt_io.h defines an lseek and an _lseeki64, with different function signatures, that cause trouble when we try to simply define it à la:

 #define lseek _lseeki64.

Similarly, _ftelli64 has a problematic signature.

bu_lseek()

b_off_t bu_lseek	(	int	fd,
		b_off_t	offset,
		int	whence
	)

bu_ftell()

b_off_t bu_ftell

(

FILE *

stream

)