File Class Reference

File I/O streams More...

#include <cc/File>

Inheritance diagram for File:

Public Member Functions
	File ()=default
	Create a null file.
	File (const String &path, FileOpen flags=FileOpen::ReadOnly, FileMode mode=FileMode::Default)
	Open file.
bool	tryOpen (const String &path, Out< File > file, FileOpen flags=FileOpen::ReadOnly, FileMode mode=FileMode::Default)
	Try to open/create a file.
String	path () const
	File path this file was opened from
void	truncate (off_t length)
	Truncate or extend file to length bytes.
off_t	seek (off_t distance, Seek whence=Seek::Begin)
	Move the current file offset.
bool	isSeekable () const
	Check if this file is seekable (e.g.
off_t	currentOffset () const
	Get current file offset.
void	sync ()
	Synchronise the files's state with the underlying storage device.
void	dataSync ()
	Synchronise the files's content with the underlying storage device.
String	readAll ()
	Read the file's entire contents.
String	map ()
	Map the file's entire contents into memory
String	map (off_t i0, off_t i1)
	Map the file's contents in range [i0, i1) into memory
void	close ()
	Close file.
Public Member Functions inherited from IoStream
	IoStream ()=default
	Create a null I/O stream.
	IoStream (int fd)
	Create an I/O stream for file descriptor fd.
int	fd () const
	File descriptor
void	close ()
	Manually close this I/O stream.
void	shutdown (IoShutdown mode=IoShutdown::Full)
	Manually shutdown this I/O stream.
void	duplicateTo (IoStream &other)
	Duplicate this I/O stream.
IoStream	duplicate () const
	Duplicate I/O stream other.
bool	isInteractive () const
	Check if this is a teletype (e.g.
void	echo (bool on)
	Set echo mode of this I/O stream to on
int	ioctl (int request, void *arg)
	Issue an device control request.
long	scatterLimit () const
	I/O scatter limit (in bytes)
void	setScatterLimit (long newLimit)
	Set the I/O scatter limit (in bytes)
Public Member Functions inherited from Stream
	Stream ()=default
	Create a null stream.
bool	waitEstablished (int timeout=-1)
	Wait until the connection is fully established.
bool	wait (IoEvent event, int timeout=-1)
	Wait for an I/O event.
long	read (Out< Bytes > buffer, long maxFill=-1)
	Read available bytes into buffer and return number of bytes read.
void	write (const Bytes &buffer, long fill=-1)
	Write fill bytes from buffer (if fill < 0 write all bytes from buffer)
void	write (const List< Bytes > &buffers)
	Write the contents of buffers in one go.
void	write (const List< String > &parts)
	Convenience method, equivalent to 'write(parts.join())'.
void	write (const struct iovec *iov, int iovcnt)
	Write the contents of the iov buffers in one go.
void	write (const char *s)
	Write C-string s.
bool	isDiscarding () const
	Return true if this stream is discarding all writes
long long	transferTo (const Stream &sink, long long count, const Bytes &buffer)
	Transfer a span of bytes.
long long	transferTo (const Stream &sink, long long count=-1)
	Transfer a span of bytes.
long	defaultTransferUnit () const
	Default I/O buffer size.
long long	skip (long long count)
	Read and discard count bytes.
void	drain (const Bytes &auxBuffer=Bytes{})
	Read everything that is left.
long	readSpan (Out< Bytes > buffer)
	Read fixed number of bytes.
String	readSpan (long count)
	Read a fixed number of bytes.
String	readAll ()
	Read the entire stream.
Public Member Functions inherited from Object
	Object ()=default
	Create a null object.
	operator bool () const
	Check if this is a non-null object.
bool	isNull () const
	Check if this is a null object.
template<class T >
bool	is () const
	Check if this object is of type T.
template<class T >
T	as () const
	Cast this object to type T.
bool	isWeak () const
	Check if the underlying object reference is weak.
bool	operator== (const Object &other) const
	Equality operator.
std::strong_ordering	operator<=> (const Object &other) const
	Ordering operator.
long	useCount () const
	Reference count.

Static Public Member Functions
static bool	access (const String &path, FileAccess mode)
	Check if file under path is accessible with mode.
static bool	exists (const String &path)
	Check if a file under path exists.
static void	create (const String &path, FileMode mode=FileMode::Default)
	Create a new file under path with initial permissions mode.
static void	establish (const String &path, FileMode fileMode=FileMode::Default, FileMode dirMode=FileMode::DirDefault)
	Establish a new file path.
static String	createUnique (const String &path, FileMode mode=FileMode::Default, char placeHolder='#')
	Create a uniquely named file.
static String	createTemp (FileMode mode=FileMode::Default)
	Create a temporary file and return its path.
static void	chown (const String &path, uid_t ownerId, gid_t groupId)
	Change ownership of file under path to ownerId : groupId.
static void	rename (const String &oldPath, const String &newPath)
	Rename file under oldPath to newPath (moving it within the filesystem if required)
static void	link (const String &oldPath, const String &newPath)
	Create a new name newPath for the file under oldPath.
static void	unlink (const String &path)
	Delete the name path.
static void	symlink (const String &oldPath, const String &newPath)
	Create a symbolic link under newPath pointing to oldPath.
static String	readlink (const String &path)
	Read the symbolic link under path.
static void	clean (const String &path)
	Remove files recursively.
static String	locate (const String &fileName, const List< String > &dirs, FileAccess accessFlags=FileAccess::Exists)
	Search for a file in a list of directories.
static String	load (const String &path)
	Load contents of file under path.
static void	save (const String &path, const String &text)
	Replace contents of file under path by text.
static void	setTimes (const String &path, double lastAccess, double lastModified, bool followSymlink=true)
	Set the file times
Static Public Member Functions inherited from IoStream
static IoStream &	input ()
	Standard input stream.
static IoStream &	output ()
	Standard output stream.
static IoStream &	error ()
	Standard error stream.
static void	pair (Out< IoStream > a, Out< IoStream > b)
	Establish a full-duplex communication channel between a and b.

Additional Inherited Members
Protected Member Functions inherited from IoStream
	IoStream (State *newState)
State &	me ()
const State &	me () const
Protected Member Functions inherited from Stream
	Stream (State *newState)
State &	me ()
const State &	me () const
Protected Member Functions inherited from Object
template<class T >
T	weak () const
template<class T >
void	initOnce ()
	Create the object state when called the first time.
template<class T >
void	initOncePerThread ()
	Create a distinct object state for each thread when called the first time in that thread.
	Object (State *newState)
	Initialize object with newState.
	Object (State *state, Alias)
	Object (State *state, Weak)
Object &	operator= (std::nullptr_t)
Static Protected Member Functions inherited from Object
template<class T >
static T	alias (const State *state)
	Create an alias object for the given state.
template<class T >
static T	weak (const State *state)
Protected Attributes inherited from Object
Handle< State >	me
	Internal object state

Detailed Description

File I/O streams

Constructor & Destructor Documentation

File() [1/2]

File ( )

default

Create a null file.

File() [2/2]

File ( const String & path, FileOpen flags = FileOpen::ReadOnly, FileMode mode = FileMode::Default )

explicit

Open file.

Parameters

path	File path
flags	File open flags
mode	File permissions for new file (optional)

See also

tryOpen()

Exceptions

SystemError

Member Function Documentation

access()

bool access ( const String & path, FileAccess mode )

static

Check if file under path is accessible with mode.

exists()

bool exists ( const String & path )

static

Check if a file under path exists.

create()

void create ( const String & path, FileMode mode = FileMode::Default )

static

Create a new file under path with initial permissions mode.

establish()

void establish ( const String & path, FileMode fileMode = FileMode::Default, FileMode dirMode = FileMode::DirDefault )

static

Establish a new file path.

Parameters

path	File path of new file
fileMode	Initial file permissions
dirMode	Initial directory permissions

createUnique()

String createUnique ( const String & path, FileMode mode = FileMode::Default, char placeHolder = '#' )

static

Create a uniquely named file.

Parameters

path	File path pattern
mode	Initial file permissions
placeHolder	Place holder character in path to be replaced with random characters

Returns

File path to the newly created file

createTemp()

String createTemp ( FileMode mode = FileMode::Default )

static

Create a temporary file and return its path.

Parameters

mode	Initial file permissions

Returns

File path of the newly created file

chown()

void chown ( const String & path, uid_t ownerId, gid_t groupId )

static

Change ownership of file under path to ownerId : groupId.

rename()

void rename ( const String & oldPath, const String & newPath )

static

Rename file under oldPath to newPath (moving it within the filesystem if required)

Warning

An exiting file under newPath will be automatically deleted.

link()

void link ( const String & oldPath, const String & newPath )

static

Create a new name newPath for the file under oldPath.

unlink()

void unlink ( const String & path )

static

Delete the name path.

symlink()

void symlink ( const String & oldPath, const String & newPath )

static

Create a symbolic link under newPath pointing to oldPath.

readlink()

String readlink ( const String & path )

static

Read the symbolic link under path.

clean()

void clean ( const String & path )

static

Remove files recursively.

Parameters

path	Path to directory or file

Cleans up the given path recursively deleting all files and directories in the process.

locate()

String locate ( const String & fileName, const List< String > & dirs, FileAccess accessFlags = FileAccess::Exists )

static

Search for a file in a list of directories.

Parameters

fileName	Name or relative path of the file
dirs	List of directories search in
accessFlags	File access flags to check

Returns

File path if file was found

load()

String load ( const String & path )

static

Load contents of file under path.

save()

void save ( const String & path, const String & text )

static

Replace contents of file under path by text.

setTimes()

void setTimes ( const String & path, double lastAccess, double lastModified, bool followSymlink = true )

static

Set the file times

Parameters

path	File path
lastAccess	Last time when file was accessed
lastModified	Last time when file was modified
followSymlink	Resolve path if it points to a symlink

tryOpen()

bool tryOpen	(	const String &	path,
		Out< File >	file,
		FileOpen	flags = FileOpen::ReadOnly,
		FileMode	mode = FileMode::Default )

Try to open/create a file.

Parameters

path	File path
file	File object is returned on success
flags	File open flags
mode	File permissions for new file (optional)

Returns

True if successful

path()

String path

(

)

const

File path this file was opened from

truncate()

void truncate

(

off_t

length

)

Truncate or extend file to length bytes.

seek()

off_t seek	(	off_t	distance,
		Seek	whence = Seek::Begin )

Move the current file offset.

Parameters

distance	Relative distance to move the file offset
whence	From which point to apply the seek distance

Returns

New file offset

isSeekable()

bool isSeekable

(

)

const

Check if this file is seekable (e.g.

character devices aren't seekable)

currentOffset()

off_t currentOffset

(

)

const

Get current file offset.

sync()

void sync

(

)

Synchronise the files's state with the underlying storage device.

dataSync()

void dataSync

(

)

Synchronise the files's content with the underlying storage device.

readAll()

String readAll

(

)

Read the file's entire contents.

map() [1/2]

String map

(

)

Map the file's entire contents into memory

map() [2/2]

String map	(	off_t	i0,
		off_t	i1 )

Map the file's contents in range [i0, i1) into memory

close()

void close

(

)

Close file.