E-MailRelay
Classes | Public Types | Static Public Member Functions | List of all members
G::File Class Reference

A simple static class for dealing with files. More...

#include <gfile.h>

Classes

class  Append
 An overload discriminator for G::File::open(). More...
 
struct  CreateExclusive
 An overload discriminator for G::File::open(). More...
 
struct  Stat
 A portable 'struct stat'. More...
 
class  Text
 An overload discriminator for G::File::open(). More...
 

Public Types

enum class  InOut { In , Out }
 
enum class  InOutAppend { In , Out , Append }
 
enum class  Seek { Start , Current , End }
 

Static Public Member Functions

static bool remove (const Path &path, std::nothrow_t) noexcept
 Deletes the file or directory. Returns false on error. More...
 
static void remove (const Path &path)
 Deletes the file or directory. Throws an exception on error. More...
 
static bool rename (const Path &from, const Path &to, std::nothrow_t) noexcept
 Renames the file. More...
 
static void rename (const Path &from, const Path &to, bool ignore_missing=false)
 Renames the file. More...
 
static bool renameOnto (const Path &from, const Path &to, std::nothrow_t) noexcept
 Renames the file, deleting 'to' first if necessary. More...
 
static bool copy (const Path &from, const Path &to, std::nothrow_t)
 Copies a file. Returns false on error. More...
 
static void copy (const Path &from, const Path &to)
 Copies a file. More...
 
static void copy (std::istream &from, std::ostream &to, std::streamsize limit=0U, std::size_t block=0U)
 Copies a stream with an optional size limit. More...
 
static bool copyInto (const Path &from, const Path &to_dir, std::nothrow_t)
 Copies a file into a directory and does a chmodx() if necessary. More...
 
static bool mkdirs (const Path &dir, std::nothrow_t, int=100)
 Creates a directory and all necessary parents. More...
 
static void mkdirs (const Path &dir, int=100)
 Creates a directory and all necessary parents. More...
 
static bool mkdir (const Path &dir, std::nothrow_t)
 Creates a directory. More...
 
static void mkdir (const Path &dir)
 Creates a directory. More...
 
static bool isEmpty (const Path &file, std::nothrow_t)
 Returns true if the file size is zero. More...
 
static std::string sizeString (const Path &file)
 Returns the file's size in string format. More...
 
static bool exists (const Path &file)
 Returns true if the file (directory, device etc.) exists. More...
 
static bool exists (const Path &file, std::nothrow_t)
 Returns true if the file (directory, device etc.) exists. More...
 
static bool isExecutable (const Path &, std::nothrow_t)
 Returns true if the path is probably executable by the calling process. More...
 
static bool isLink (const Path &path, std::nothrow_t)
 Returns true if the path is an existing symlink. More...
 
static bool isDirectory (const Path &path, std::nothrow_t)
 Returns true if the path exists() and is a directory. More...
 
static Stat stat (const Path &path, bool read_symlink=false)
 Returns a file status structure. More...
 
static SystemTime time (const Path &file)
 Returns the file's timestamp. Throws on error. More...
 
static SystemTime time (const Path &file, std::nothrow_t)
 Returns the file's timestamp. More...
 
static void chmodx (const Path &file)
 Makes the file executable. Throws on error. More...
 
static bool chmodx (const Path &file, std::nothrow_t)
 Makes the file executable. More...
 
static void chmod (const Path &file, const std::string &spec)
 Sets the file permissions. More...
 
static void chgrp (const Path &file, const std::string &group)
 Sets the file group ownership. Throws on error. More...
 
static bool chgrp (const Path &file, const std::string &group, std::nothrow_t)
 Sets the file group ownership. Returns false on error. More...
 
static bool chgrp (const Path &file, gid_t group_id, std::nothrow_t)
 Sets the file group ownership. Returns false on error. More...
 
static G::Path readlink (const Path &link)
 Reads a symlink. Throws on error. More...
 
static G::Path readlink (const Path &link, std::nothrow_t)
 Reads a symlink. Returns the empty path on error. More...
 
static void link (const Path &target, const Path &new_link)
 Creates a symlink. More...
 
static bool link (const Path &target, const Path &new_link, std::nothrow_t)
 Creates a symlink. Returns false on error. More...
 
static bool hardlink (const Path &src, const Path &dst, std::nothrow_t)
 Creates a hard link. More...
 
static void create (const Path &)
 Creates the file if it does not exist. More...
 
static int compare (const Path &, const Path &, bool ignore_whitespace=false)
 Compares the contents of the two files. Returns 0, 1 or -1. More...
 
static void open (std::ofstream &, const Path &)
 Calls open() on the given output file stream. More...
 
static void open (std::ofstream &, const Path &, Append)
 Calls open() on the given output file stream. More...
 
static void open (std::ofstream &, const Path &, Text)
 Calls open() on the given output file stream. More...
 
static void open (std::ifstream &, const Path &)
 Calls open() on the given input file stream. More...
 
static void open (std::ifstream &, const Path &, Text)
 Calls open() on the given input file stream. More...
 
static std::filebuf * open (std::filebuf &, const Path &, InOut)
 Calls open() on the given filebuf. More...
 
static int open (const char *, InOutAppend) noexcept
 Opens a file descriptor. More...
 
static int open (const char *, CreateExclusive) noexcept
 Creates a file and returns a writable file descriptor. More...
 
static std::FILE * fopen (const char *, const char *mode) noexcept
 Calls std::fopen(). More...
 
static bool probe (const char *) noexcept
 Creates and deletes a temporary probe file. More...
 
static ssize_t read (int fd, char *, std::size_t) noexcept
 Calls ::read() or equivalent. More...
 
static ssize_t write (int fd, const char *, std::size_t) noexcept
 Calls ::write() or equivalent. More...
 
static void close (int fd) noexcept
 Calls ::close() or equivalent. More...
 
static std::streamoff seek (int fd, std::streamoff offset, Seek) noexcept
 Does ::lseek() or equivalent. More...
 
static void setNonBlocking (int fd) noexcept
 Sets the file descriptor to non-blocking mode. More...
 

Detailed Description

A simple static class for dealing with files.

See also
G::Path, G::FileSystem, G::Directory

Definition at line 42 of file gfile.h.

Member Enumeration Documentation

◆ InOut

enum class G::File::InOut
strong

Definition at line 57 of file gfile.h.

◆ InOutAppend

enum class G::File::InOutAppend
strong

Definition at line 58 of file gfile.h.

◆ Seek

enum class G::File::Seek
strong

Definition at line 59 of file gfile.h.

Member Function Documentation

◆ chgrp() [1/3]

void G::File::chgrp ( const Path file,
const std::string &  group 
)
static

Sets the file group ownership. Throws on error.

Definition at line 330 of file gfile_unix.cpp.

◆ chgrp() [2/3]

bool G::File::chgrp ( const Path file,
const std::string &  group,
std::nothrow_t   
)
static

Sets the file group ownership. Returns false on error.

Definition at line 339 of file gfile_unix.cpp.

◆ chgrp() [3/3]

bool G::File::chgrp ( const Path file,
gid_t  group_id,
std::nothrow_t   
)
static

Sets the file group ownership. Returns false on error.

Definition at line 345 of file gfile_unix.cpp.

◆ chmod()

void G::File::chmod ( const Path file,
const std::string &  spec 
)
static

Sets the file permissions.

Throws on error. The spec is a simplified sub-set of the /bin/chmod command syntax. The umask is ignored.

Definition at line 232 of file gfile_unix.cpp.

◆ chmodx() [1/2]

void G::File::chmodx ( const Path file)
static

Makes the file executable. Throws on error.

Definition at line 239 of file gfile.cpp.

◆ chmodx() [2/2]

bool G::File::chmodx ( const Path file,
std::nothrow_t   
)
static

Makes the file executable.

Definition at line 233 of file gfile.cpp.

◆ close()

void G::File::close ( int  fd)
staticnoexcept

Calls ::close() or equivalent.

Definition at line 149 of file gfile_unix.cpp.

◆ compare()

int G::File::compare ( const Path path_1,
const Path path_2,
bool  ignore_whitespace = false 
)
static

Compares the contents of the two files. Returns 0, 1 or -1.

Definition at line 301 of file gfile.cpp.

◆ copy() [1/3]

void G::File::copy ( const Path from,
const Path to 
)
static

Copies a file.

Definition at line 71 of file gfile.cpp.

◆ copy() [2/3]

bool G::File::copy ( const Path from,
const Path to,
std::nothrow_t   
)
static

Copies a file. Returns false on error.

Definition at line 79 of file gfile.cpp.

◆ copy() [3/3]

void G::File::copy ( std::istream &  from,
std::ostream &  to,
std::streamsize  limit = 0U,
std::size_t  block = 0U 
)
static

Copies a stream with an optional size limit.

Definition at line 122 of file gfile.cpp.

◆ copyInto()

bool G::File::copyInto ( const Path from,
const Path to_dir,
std::nothrow_t   
)
static

Copies a file into a directory and does a chmodx() if necessary.

Returns false on error.

Definition at line 85 of file gfile.cpp.

◆ create()

void G::File::create ( const Path path)
static

Creates the file if it does not exist.

Leaves it alone if it does. Throws on error.

Definition at line 125 of file gfile_unix.cpp.

◆ exists() [1/2]

bool G::File::exists ( const Path file)
static

Returns true if the file (directory, device etc.) exists.

Symlinks are followed. Throws an exception if permission denied or too many symlinks etc.

Definition at line 148 of file gfile.cpp.

◆ exists() [2/2]

bool G::File::exists ( const Path file,
std::nothrow_t   
)
static

Returns true if the file (directory, device etc.) exists.

Symlinks are followed. Returns false on error.

Definition at line 153 of file gfile.cpp.

◆ fopen()

std::FILE * G::File::fopen ( const char *  path,
const char *  mode 
)
staticnoexcept

Calls std::fopen().

Definition at line 108 of file gfile_unix.cpp.

◆ hardlink()

bool G::File::hardlink ( const Path src,
const Path dst,
std::nothrow_t   
)
static

Creates a hard link.

Returns false on error or if not implemented.

Definition at line 350 of file gfile_unix.cpp.

◆ isDirectory()

bool G::File::isDirectory ( const Path path,
std::nothrow_t   
)
static

Returns true if the path exists() and is a directory.

Symlinks are followed. Returns false on error.

Definition at line 189 of file gfile.cpp.

◆ isEmpty()

bool G::File::isEmpty ( const Path file,
std::nothrow_t   
)
static

Returns true if the file size is zero.

Returns false on error.

Definition at line 202 of file gfile.cpp.

◆ isExecutable()

bool G::File::isExecutable ( const Path path,
std::nothrow_t   
)
static

Returns true if the path is probably executable by the calling process.

Because of portability and implementation difficulties this does not return a definitive result so it should only used for generating warnings on a false return. Returns false on error.

Definition at line 195 of file gfile.cpp.

◆ isLink()

bool G::File::isLink ( const Path path,
std::nothrow_t   
)
static

Returns true if the path is an existing symlink.

Returns false on error.

Definition at line 178 of file gfile.cpp.

◆ link() [1/2]

void G::File::link ( const Path target,
const Path new_link 
)
static

Creates a symlink.

If the link already exists but is not not pointing at the correct target then the link is deleted and recreated. Throws on error.

Definition at line 356 of file gfile_unix.cpp.

◆ link() [2/2]

bool G::File::link ( const Path target,
const Path new_link,
std::nothrow_t   
)
static

Creates a symlink. Returns false on error.

Definition at line 376 of file gfile_unix.cpp.

◆ mkdir() [1/2]

void G::File::mkdir ( const Path dir)
static

Creates a directory.

Throws on error (including EEXIST).

Definition at line 251 of file gfile.cpp.

◆ mkdir() [2/2]

bool G::File::mkdir ( const Path dir,
std::nothrow_t   
)
static

Creates a directory.

Returns false on error (including EEXIST).

Definition at line 245 of file gfile.cpp.

◆ mkdirs() [1/2]

void G::File::mkdirs ( const Path dir,
int  limit = 100 
)
static

Creates a directory and all necessary parents.

Throws on error, but EEXIST is not an error.

Definition at line 292 of file gfile.cpp.

◆ mkdirs() [2/2]

bool G::File::mkdirs ( const Path dir,
std::nothrow_t  ,
int  limit = 100 
)
static

Creates a directory and all necessary parents.

Returns false on error, but EEXIST is not an error and chmod errors are also ignored.

Note that the EEXIST result is ignored even if the target path already exists as a non-directory. This is a feature not a bug because it can avoid races.

Definition at line 284 of file gfile.cpp.

◆ open() [1/8]

int G::File::open ( const char *  path,
CreateExclusive   
)
staticnoexcept

Creates a file and returns a writable file descriptor.

Fails if the file already exists. Returns -1 on error. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 101 of file gfile_unix.cpp.

◆ open() [2/8]

int G::File::open ( const char *  path,
InOutAppend  mode 
)
staticnoexcept

Opens a file descriptor.

Returns -1 on error. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 90 of file gfile_unix.cpp.

◆ open() [3/8]

std::filebuf * G::File::open ( std::filebuf &  fb,
const Path path,
InOut  inout 
)
static

Calls open() on the given filebuf.

Returns the address of the given filebuf, or nullptr on failure. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 82 of file gfile_unix.cpp.

◆ open() [4/8]

void G::File::open ( std::ifstream &  ifstream,
const Path path 
)
static

Calls open() on the given input file stream.

Uses SH_DENYNO and O_BINARY on windows.

Definition at line 70 of file gfile_unix.cpp.

◆ open() [5/8]

void G::File::open ( std::ifstream &  ifstream,
const Path path,
Text   
)
static

Calls open() on the given input file stream.

This overload is for native end-of-line conversion. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 76 of file gfile_unix.cpp.

◆ open() [6/8]

void G::File::open ( std::ofstream &  ofstream,
const Path path 
)
static

Calls open() on the given output file stream.

Uses SH_DENYNO and O_BINARY on windows.

Definition at line 55 of file gfile_unix.cpp.

◆ open() [7/8]

void G::File::open ( std::ofstream &  ofstream,
const Path path,
Append   
)
static

Calls open() on the given output file stream.

This overload is for append-on-every-write mode. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 65 of file gfile_unix.cpp.

◆ open() [8/8]

void G::File::open ( std::ofstream &  ofstream,
const Path path,
Text   
)
static

Calls open() on the given output file stream.

This overload is for native end-of-line conversion. Uses SH_DENYNO and O_BINARY on windows.

Definition at line 60 of file gfile_unix.cpp.

◆ probe()

bool G::File::probe ( const char *  path)
staticnoexcept

Creates and deletes a temporary probe file.

Fails if the file already exists. Returns false on error.

Definition at line 114 of file gfile_unix.cpp.

◆ read()

ssize_t G::File::read ( int  fd,
char *  p,
std::size_t  n 
)
staticnoexcept

Calls ::read() or equivalent.

Definition at line 139 of file gfile_unix.cpp.

◆ readlink() [1/2]

G::Path G::File::readlink ( const Path link)
static

Reads a symlink. Throws on error.

Definition at line 396 of file gfile_unix.cpp.

◆ readlink() [2/2]

G::Path G::File::readlink ( const Path link,
std::nothrow_t   
)
static

Reads a symlink. Returns the empty path on error.

Definition at line 405 of file gfile_unix.cpp.

◆ remove() [1/2]

void G::File::remove ( const Path path)
static

Deletes the file or directory. Throws an exception on error.

Definition at line 35 of file gfile.cpp.

◆ remove() [2/2]

bool G::File::remove ( const Path path,
std::nothrow_t   
)
staticnoexcept

Deletes the file or directory. Returns false on error.

Definition at line 29 of file gfile.cpp.

◆ rename() [1/2]

void G::File::rename ( const Path from,
const Path to,
bool  ignore_missing = false 
)
static

Renames the file.

Throws on error, but optionally ignores errors caused by a missing 'from' file or missing 'to' directory component.

Definition at line 51 of file gfile.cpp.

◆ rename() [2/2]

bool G::File::rename ( const Path from,
const Path to,
std::nothrow_t   
)
staticnoexcept

Renames the file.

Whether it fails if 'to' already exists depends on the o/s (see also renameOnto()). Returns false on error.

Definition at line 46 of file gfile.cpp.

◆ renameOnto()

bool G::File::renameOnto ( const Path from,
const Path to,
std::nothrow_t   
)
staticnoexcept

Renames the file, deleting 'to' first if necessary.

Returns false on error.

Definition at line 134 of file gfile_unix.cpp.

◆ seek()

std::streamoff G::File::seek ( int  fd,
std::streamoff  offset,
Seek  origin 
)
staticnoexcept

Does ::lseek() or equivalent.

Definition at line 432 of file gfile_unix.cpp.

◆ setNonBlocking()

void G::File::setNonBlocking ( int  fd)
staticnoexcept

Sets the file descriptor to non-blocking mode.

Definition at line 440 of file gfile_unix.cpp.

◆ sizeString()

std::string G::File::sizeString ( const Path file)
static

Returns the file's size in string format.

Returns the empty string on error.

Definition at line 209 of file gfile.cpp.

◆ stat()

G::File::Stat G::File::stat ( const Path path,
bool  read_symlink = false 
)
static

Returns a file status structure.

Returns with the 'error' field set on error. Always fails if 'read-link' on Windows.

Definition at line 184 of file gfile.cpp.

◆ time() [1/2]

G::SystemTime G::File::time ( const Path file)
static

Returns the file's timestamp. Throws on error.

Definition at line 215 of file gfile.cpp.

◆ time() [2/2]

G::SystemTime G::File::time ( const Path file,
std::nothrow_t   
)
static

Returns the file's timestamp.

Returns SystemTime(0) on error.

Definition at line 224 of file gfile.cpp.

◆ write()

ssize_t G::File::write ( int  fd,
const char *  p,
std::size_t  n 
)
staticnoexcept

Calls ::write() or equivalent.

Definition at line 144 of file gfile_unix.cpp.


The documentation for this class was generated from the following files: