CoreComponents 3.0.0
A Modern C++ Toolkit
Loading...
Searching...
No Matches
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 >
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 IoStreaminput ()
 Standard input stream.
 
static IoStreamoutput ()
 Standard output stream.
 
static IoStreamerror ()
 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)
 
Stateme ()
 
const Stateme () const
 
- Protected Member Functions inherited from Object
template<class 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)
 
Objectoperator= (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< Stateme
 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
pathFile path
flagsFile open flags
modeFile 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
pathFile path of new file
fileModeInitial file permissions
dirModeInitial directory permissions

◆ createUnique()

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

Create a uniquely named file.

Parameters
pathFile path pattern
modeInitial file permissions
placeHolderPlace 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
modeInitial 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
pathPath 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
fileNameName or relative path of the file
dirsList of directories search in
accessFlagsFile 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
pathFile path
lastAccessLast time when file was accessed
lastModifiedLast time when file was modified
followSymlinkResolve 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
pathFile path
fileFile object is returned on success
flagsFile open flags
modeFile 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
distanceRelative distance to move the file offset
whenceFrom 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.