util.h File Reference

#include "platform.h"
#include <stddef.h>
#include <sys/types.h>
#include <sys/stat.h>
#include "../lib/common/mem.h"
#include <libgen.h>

Go to the source code of this file.

Data Structures
struct	UTIL_HumanReadableSize_t
struct	FileNamesTable

Macros
#define	UTIL_fseek   fseek
#define	UTIL_sleep(s)
#define	UTIL_sleepMilli(milli)
#define	SET_REALTIME_PRIORITY   /* disabled */
#define	UTIL_STATIC   static /* this version may generate warnings for unused static functions; disable the relevant warning */
#define	PATH_SEP   '/'
#define	STRDUP(s)
#define	UTIL_FILESIZE_UNKNOWN   ((U64)(-1))

Functions
int	UTIL_requireUserConfirmation (const char *prompt, const char *abortMsg, const char *acceptableLetters, int hasStdinInput)
int	UTIL_stat (const char *filename, stat_t *statbuf)
int	UTIL_fstat (const int fd, const char *filename, stat_t *statbuf)
int	UTIL_setFileStat (const char *filename, const stat_t *statbuf)
int	UTIL_setFDStat (const int fd, const char *filename, const stat_t *statbuf)
int	UTIL_utime (const char *filename, const stat_t *statbuf)
int	UTIL_isRegularFileStat (const stat_t *statbuf)
int	UTIL_isDirectoryStat (const stat_t *statbuf)
int	UTIL_isFIFOStat (const stat_t *statbuf)
int	UTIL_isBlockDevStat (const stat_t *statbuf)
U64	UTIL_getFileSizeStat (const stat_t *statbuf)
int	UTIL_chmod (char const *filename, const stat_t *statbuf, mode_t permissions)
int	UTIL_fchmod (const int fd, char const *filename, const stat_t *statbuf, mode_t permissions)
int	UTIL_isRegularFile (const char *infilename)
int	UTIL_isDirectory (const char *infilename)
int	UTIL_isSameFile (const char *file1, const char *file2)
int	UTIL_isSameFileStat (const char *file1, const char *file2, const stat_t *file1Stat, const stat_t *file2Stat)
int	UTIL_isCompressedFile (const char *infilename, const char *extensionList[])
int	UTIL_isLink (const char *infilename)
int	UTIL_isFIFO (const char *infilename)
int	UTIL_isConsole (FILE *file)
void	UTIL_fakeStdinIsConsole (void)
void	UTIL_fakeStdoutIsConsole (void)
void	UTIL_fakeStderrIsConsole (void)
void	UTIL_traceFileStat (void)
U64	UTIL_getFileSize (const char *infilename)
U64	UTIL_getTotalFileSize (const char *const *fileNamesTable, unsigned nbFiles)
UTIL_HumanReadableSize_t	UTIL_makeHumanReadableSize (U64 size)
int	UTIL_compareStr (const void *p1, const void *p2)
const char *	UTIL_getFileExtension (const char *infilename)
void	UTIL_mirrorSourceFilesDirectories (const char **fileNamesTable, unsigned int nbFiles, const char *outDirName)
char *	UTIL_createMirroredDestDirName (const char *srcFileName, const char *outDirRootName)
FileNamesTable *	UTIL_createFileNamesTable_fromFileName (const char *inputFileName)
FileNamesTable *	UTIL_assembleFileNamesTable (const char **filenames, size_t tableSize, char *buf)
void	UTIL_freeFileNamesTable (FileNamesTable *table)
FileNamesTable *	UTIL_mergeFileNamesTable (FileNamesTable *table1, FileNamesTable *table2)
void	UTIL_expandFNT (FileNamesTable **fnt, int followLinks)
FileNamesTable *	UTIL_createFNT_fromROTable (const char **filenames, size_t nbFilenames)
FileNamesTable *	UTIL_allocateFileNamesTable (size_t tableSize)
int	UTIL_searchFileNamesTable (FileNamesTable *table, char const *name)
void	UTIL_refFilename (FileNamesTable *fnt, const char *filename)
FileNamesTable *	UTIL_createExpandedFNT (const char *const *filenames, size_t nbFilenames, int followLinks)
int	UTIL_countCores (int logical)
int	UTIL_countPhysicalCores (void)
int	UTIL_countLogicalCores (void)

Variables
int	g_utilDisplayLevel

Macro Definition Documentation

PATH_SEP

#define PATH_SEP   '/'

SET_REALTIME_PRIORITY

#define SET_REALTIME_PRIORITY   /* disabled */

STRDUP

#define STRDUP

(

s

)

Value:

strdup(s)

UTIL_FILESIZE_UNKNOWN

#define UTIL_FILESIZE_UNKNOWN   ((U64)(-1))

UTIL_fseek

#define UTIL_fseek   fseek

UTIL_sleep

#define UTIL_sleep

(

s

)

Value:

/* disabled */

UTIL_sleepMilli

#define UTIL_sleepMilli

(

milli

)

Value:

/* disabled */

UTIL_STATIC

#define UTIL_STATIC   static /* this version may generate warnings for unused static functions; disable the relevant warning */

Function Documentation

UTIL_allocateFileNamesTable()

FileNamesTable * UTIL_allocateFileNamesTable

(

size_t

tableSize

)

UTIL_allocateFileNamesTable() : Allocates a table of const char*, to insert read-only names later on. The created FileNamesTable* doesn't hold a buffer.

Returns

: FileNamesTable*, or NULL, if allocation fails.

UTIL_assembleFileNamesTable()

FileNamesTable * UTIL_assembleFileNamesTable	(	const char **	filenames,
		size_t	tableSize,
		char *	buf )

UTIL_assembleFileNamesTable() : This function takes ownership of its arguments, @filenames and @buf, and store them inside the created object. note : this function never fails, it will rather exit() the program if internal allocation fails.

Returns

: resulting FileNamesTable* object.

UTIL_chmod()

int UTIL_chmod	(	char const *	filename,
		const stat_t *	statbuf,
		mode_t	permissions )

Like chmod(), but only modifies regular files. Provided statbuf may be NULL, in which case this function will stat() the file internally, in order to check whether it should be modified.

If fd is -1, fd is ignored and the filename is used.

Like chmod(), but only modifies regular files. Provided statbuf may be NULL, in which case this function will stat() the file internally, in order to check whether it should be modified.

UTIL_compareStr()

int UTIL_compareStr	(	const void *	p1,
		const void *	p2 )

UTIL_countCores()

int UTIL_countCores

(

int

logical

)

UTIL_countLogicalCores()

int UTIL_countLogicalCores

(

void

)

UTIL_countPhysicalCores()

int UTIL_countPhysicalCores

(

void

)

UTIL_createExpandedFNT()

FileNamesTable * UTIL_createExpandedFNT	(	const char *const *	filenames,
		size_t	nbFilenames,
		int	followLinks )

UTIL_createExpandedFNT() : read names from @filenames, and expand those corresponding to directories. links are followed or not depending on @followLinks directive.

Returns

: an expanded FileNamesTable*, where each name is a file or NULL in case of error

UTIL_createFileNamesTable_fromFileName()

FileNamesTable * UTIL_createFileNamesTable_fromFileName

(

const char *

inputFileName

)

UTIL_createFileNamesTable_fromFileName() : read filenames from @inputFileName, and store them into returned object.

Returns

: a FileNamesTable*, or NULL in case of error (ex: @inputFileName doesn't exist). Note: inputFileSize must be less than 50MB

UTIL_createFNT_fromROTable()

FileNamesTable * UTIL_createFNT_fromROTable	(	const char **	filenames,
		size_t	nbFilenames )

UTIL_createFNT_fromROTable() : copy the @filenames pointer table inside the returned object. The names themselves are still stored in their original buffer, which must outlive the object.

Returns

: a FileNamesTable* object, or NULL in case of error

UTIL_createMirroredDestDirName()

char * UTIL_createMirroredDestDirName	(	const char *	srcFileName,
		const char *	outDirRootName )

UTIL_expandFNT()

void UTIL_expandFNT	(	FileNamesTable **	fnt,
		int	followLinks )

UTIL_expandFNT() : read names from @fnt, and expand those corresponding to directories update @fnt, now containing only file names, note : in case of error, @fnt[0] is NULL

UTIL_expandFNT() : read names from @fnt, and expand those corresponding to directories update @fnt, now containing only file names,

Returns

: 0 in case of success, 1 if error note : in case of error, @fnt[0] is NULL

UTIL_fakeStderrIsConsole()

void UTIL_fakeStderrIsConsole

(

void

)

UTIL_fakeStdinIsConsole()

void UTIL_fakeStdinIsConsole

(

void

)

Pretends that stdin/stdout/stderr is a console for testing.

UTIL_fakeStdoutIsConsole()

void UTIL_fakeStdoutIsConsole

(

void

)

UTIL_fchmod()

int UTIL_fchmod	(	const int	fd,
		char const *	filename,
		const stat_t *	statbuf,
		mode_t	permissions )

UTIL_freeFileNamesTable()

void UTIL_freeFileNamesTable

(

FileNamesTable *

table

)

UTIL_freeFileNamesTable() : This function is compatible with NULL argument and never fails.

UTIL_fstat()

int UTIL_fstat	(	const int	fd,
		const char *	filename,
		stat_t *	statbuf )

UTIL_getFileExtension()

const char * UTIL_getFileExtension

(

const char *

infilename

)

UTIL_getFileSize()

U64 UTIL_getFileSize

(

const char *

infilename

)

UTIL_getFileSizeStat()

U64 UTIL_getFileSizeStat

(

const stat_t *

statbuf

)

UTIL_getTotalFileSize()

U64 UTIL_getTotalFileSize	(	const char *const *	fileNamesTable,
		unsigned	nbFiles )

UTIL_isBlockDevStat()

int UTIL_isBlockDevStat

(

const stat_t *

statbuf

)

UTIL_isCompressedFile()

int UTIL_isCompressedFile	(	const char *	infilename,
		const char *	extensionList[] )

UTIL_isConsole()

int UTIL_isConsole

(

FILE *

file

)

Returns with the given file descriptor is a console. Allows faking whether stdin/stdout/stderr is a console using UTIL_fake*IsConsole().

UTIL_isDirectory()

int UTIL_isDirectory

(

const char *

infilename

)

UTIL_isDirectoryStat()

int UTIL_isDirectoryStat

(

const stat_t *

statbuf

)

UTIL_isFIFO()

int UTIL_isFIFO

(

const char *

infilename

)

UTIL_isFIFOStat()

int UTIL_isFIFOStat

(

const stat_t *

statbuf

)

UTIL_isLink()

int UTIL_isLink

(

const char *

infilename

)

UTIL_isRegularFile()

int UTIL_isRegularFile

(

const char *

infilename

)

UTIL_isRegularFileStat()

int UTIL_isRegularFileStat

(

const stat_t *

statbuf

)

UTIL_isSameFile()

int UTIL_isSameFile	(	const char *	file1,
		const char *	file2 )

UTIL_isSameFileStat()

int UTIL_isSameFileStat	(	const char *	file1,
		const char *	file2,
		const stat_t *	file1Stat,
		const stat_t *	file2Stat )

UTIL_makeHumanReadableSize()

UTIL_HumanReadableSize_t UTIL_makeHumanReadableSize

(

U64

size

)

UTIL_mergeFileNamesTable()

FileNamesTable * UTIL_mergeFileNamesTable	(	FileNamesTable *	table1,
		FileNamesTable *	table2 )

UTIL_mergeFileNamesTable():

Returns

: FileNamesTable*, concatenation of @table1 and @table2 note: @table1 and @table2 are consumed (freed) by this operation

UTIL_mirrorSourceFilesDirectories()

void UTIL_mirrorSourceFilesDirectories	(	const char **	fileNamesTable,
		unsigned int	nbFiles,
		const char *	outDirName )

UTIL_refFilename()

void UTIL_refFilename	(	FileNamesTable *	fnt,
		const char *	filename )

UTIL_refFilename() : Add a reference to read-only name into @fnt table. As @filename is only referenced, its lifetime must outlive @fnt. Internal table must be large enough to reference a new member, otherwise its UB (protected by an assert()).

UTIL_requireUserConfirmation()

int UTIL_requireUserConfirmation	(	const char *	prompt,
		const char *	abortMsg,
		const char *	acceptableLetters,
		int	hasStdinInput )

Displays a message prompt and returns success (0) if first character from stdin matches any from acceptableLetters. Otherwise, returns failure (1) and displays abortMsg. If any of the inputs are stdin itself, then automatically return failure (1).

UTIL_searchFileNamesTable()

int UTIL_searchFileNamesTable	(	FileNamesTable *	table,
		char const *	name )

UTIL_searchFileNamesTable() : Searched through entries in FileNamesTable for a specific name.

Returns

: index of entry if found or -1 if not found

UTIL_setFDStat()

int UTIL_setFDStat	(	const int	fd,
		const char *	filename,
		const stat_t *	statbuf )

UTIL_setFileStat()

int UTIL_setFileStat	(	const char *	filename,
		const stat_t *	statbuf )

Instead of getting a file's stats, this updates them with the info in the provided stat_t. Currently sets owner, group, atime, and mtime. Will only update this info for regular files.

UTIL_setFDStat() also takes an fd, and will preferentially use that to indicate which file to modify, If fd is -1, it will fall back to using the filename.

Instead of getting a file's stats, this updates them with the info in the provided stat_t. Currently sets owner, group, atime, and mtime. Will only update this info for regular files.

UTIL_stat()

int UTIL_stat	(	const char *	filename,
		stat_t *	statbuf )

Calls platform's equivalent of stat() on filename and writes info to statbuf. Returns success (1) or failure (0).

UTIL_fstat() is like UTIL_stat() but takes an optional fd that refers to the file in question. It turns out that this can be meaningfully faster. If fd is -1, behaves just like UTIL_stat() (i.e., falls back to using the filename).

Calls platform's equivalent of stat() on filename and writes info to statbuf. Returns success (1) or failure (0).

UTIL_traceFileStat()

void UTIL_traceFileStat

(

void

)

Emit traces for functions that read, or modify file metadata.

UTIL_utime()

int UTIL_utime	(	const char *	filename,
		const stat_t *	statbuf )

Set atime to now and mtime to the st_mtim in statbuf.

Directly wraps utime() or utimensat(). Returns -1 on error. Does not validate filename is valid.

Variable Documentation

g_utilDisplayLevel

int g_utilDisplayLevel

extern