molib documentation

Languages Available: français español

CLASS

moFile

NAME

Contructors - create a new file object

VERSION

Version: 1.2.0

SYNOPSIS

moFile(void);
moFile(const char *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF8);
moFile(const mowc::mc_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UCS2_INTERNAL);
moFile(const mowc::wc_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UCS4_INTERNAL);
moFile(const wchar_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ);
moFile(const moWCString& filename, mo_file_mode_t mode = MO_FILE_MODE_READ);

PARAMETERS

filename - the name of the file to be opened
mode - the mode used to open the file, for reading by default
encoding - the encoding the the filename string

DESCRIPTION

The file object can be used to read, write, update, create files.

The default constructor, when no parameters are used, creates an inactive file object. This means the object has no file descriptor attached to it and therefore instructions such as Read() and Write() can't be used until a file is attached to this object or a file is opened with the Open() instruction.

ERRORS

In the constructors, when the file can't be opened an error is thrown. Use the Open() function member instead if you mind the throw.

SEE ALSO

Open, Close, Attach, Read, Write

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

LastErrno - return the last error number
ClearError - read the current error and return the previous value

VERSION

Version: 1.2.0

SYNOPSIS

int LastErrno(void) const;
void ClearError(void);

DESCRIPTION

LastErrno() can be used to know about the last I/O error.

ClearError() will return the current error and reset it.

RETURN VALUE

Either function returns the last error number.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

WCFilename - return the name of this file

VERSION

Version: 1.2.0

SYNOPSIS

const moWCString& WCFilename(void) const;

DESCRIPTION

This function returns the name of this file. The file has a filename only if it was opened with the Open() member function (or an equivalent constructor). Files which are attached to the moFile object don't have a name.

An moFile object without a name will return an empty string.

SEE ALSO

Open, Attach

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

NewFD - signal that a new file descriptor is available

VERSION

Version: 1.2.0

SYNOPSIS

protected:
virtual void OnNewFD(int fd);

DESCRIPTION

The OnNewFD() is called any time the f_fd field is set to a valid file descriptor or -1 (closed/detached).

This function is used to signal derived classes.

SEE ALSO

Open, Close, Attach

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

private:
Init - initialize a file object

VERSION

Version: 1.2.0

SYNOPSIS

void Init(const moWCString& filename, mo_file_mode_t mode);

PARAMETERS

filename - a name of a file to open
mode - a set of modes to open the file

DESCRIPTION

This internal function will be called any time a file is created. It is possible that the filename will be empty.

ERRORS

In the constructors, when the file can't be opened an error is thrown. Use the Open() function member instead if you mind the throw.

SEE ALSO

Open, Close, Attach, Read, Write

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Stat - read stat about a file

VERSION

Version: 1.2.0

SYNOPSIS

bool Stat(struct stat& st) const;

PARAMETERS

st - a stat structure

DESCRIPTION

This function calls the stat(2) function.

If the stat(2) succeeds, then this function returns true and fills the user supplied 'st' structure.

RETURN VALUE

true when the call succeeds

SEE ALSO

Size

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Size - return the size of the file in bytes

VERSION

Version: 1.2.0

SYNOPSIS

size_t Size(void) const;

DESCRIPTION

This function returns the size of the file in bytes.

It uses the Stat() call to determine the size from these information instead of using the usual seek to the end and ftell().

RETURN VALUE

the size of the file

SEE ALSO

Stat

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

SetFilename -- defines the name of the attached file
VOpen -- search for a file and open it
Open -- open a file
IsOpen -- check whether this moFile is attached to a file

VERSION

Version: 1.2.0

SYNOPSIS

void SetFilename(const moWCString& filename);
bool VOpen(const moListBase& paths, const moWCString& parent, const moWCString& filename, const moWCString& extension, bool direct = true);
bool Open(const char *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF8);
bool Open(const mowc::mc_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF16_INTERNAL);
bool Open(const mowc::wc_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ, mowc::encoding_t encoding = mowc::MO_ENCODING_UTF32_INTERNAL);
bool Open(const wchar_t *filename, mo_file_mode_t mode = MO_FILE_MODE_READ);
bool Open(const moWCString& filename, mo_file_mode_t mode = MO_FILE_MODE_READ);
bool IsOpen(void) const;

PARAMETERS

filename - name of the file to be opened
pahts - a list of moWCString's which are paths to try with to open the file
parent - the file which is including filename
extension - an extension to append to try loading the filename
direct - whether the VOpen() function should try opening the file in the current directory
mode - the mode in which the file will be opened
encoding - the name of the encoding for the input string filename
(WARNING: this is NOT the encoding the data in the input file)

DESCRIPTION

The SetFilename() function can be used in conjunction with the Attach() instructions to define the name of the file being attached (be it just "stdin" or some other virtual name). The Open() instructions will similarly name the moFile object.

The VOpen() and Open() functions try to open a file. It returns true when it succeeds. The filename is kept in the moFile object.

The Open() function expects one filename and tries to open that file. The VOpen() function accepts a list of paths, a parent filename (as if filename was being opened from a #include instruction), a filename to search for, an extension to try with if the filename by itself isn't found and a flag, named direct, to know whether the file should be searched in the current directory as well.

If the filename parameter to the VOpen() function doesn't represent an absolute path, then the function tries to open the file as follow:

1. if parent isn't an empty filename, use the path of that filename and try with that path prepend to the filename;

2. if direct is true, try to load the file from the current directory;

3. if paths isn't an empty list, try with each one of them to see if it is possible to open the file in any directory; the paths are checked one after another in the order there are defined in the list;

Each time a file is checked by VOpen(), it is checked first without the extension, and then with the extension. Note that the extension is used only if it isn't empty and if the filename doesn't already include an extension.

The VOpen() function will usually be used when you need to load an object in a compiler which has a list of paths (as a C preprocessor which uses -I options on the command line).

By default a file is opened for reading. For the Open() functions, the mode flags can be changed as required for reading or writing capabilities. The VOpen() function assumes that you want to read the file being searched. The available flags are as follow:

MO_FILE_MODE_READ reading mode

MO_FILE_MODE_WRITE writing mode; note that by default the existing file is truncated; use APPEND or UPDATE to keep the current data

MO_FILE_MODE_APPEND append anything written to the file; this flag requires the WRITE and CREATE modes and can't be used with UPDATE

MO_FILE_MODE_CREATE create the file if it doesn't exists; this flag requires the WRITE mode;

MO_FILE_MODE_EXCLUSIVE create a file only if it doesn't exists this flag requires the WRITE and CREATE modes; WARNING: flag is not currently implemented

MO_FILE_MODE_UPDATE open the file for update, don't delete the current contents; this flag requires the WRITE mode and can't be used with APPEND

MO_FILE_MODE_ISATTY prevent Seek() from working

MO_FILE_MODE_CREATEDIR try to open the file as is, if it fails, attempt creating missing directories and try opening the file again (see the CreateDir() function for more info); this flag is accepted only if the MO_FILE_MODE_CREATE is also set

An moFile object may or not be attached to a file on the disk. If it is attached, then the IsOpen() function will return true.

RETURN VALUE

VOpen() and Open(): true when a system file is succesfully
attached to this moFile object

IsOpen(): true when the moFile is attached to a system file

ERRORS

if the filename is invalid (i.e. empty) or if the mode is not workable then an error is thrown

SEE ALSO

Close, Constructors, SystemMode, CreateDir

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Close - close a file

VERSION

Version: 1.2.0

SYNOPSIS

void Close(void);

DESCRIPTION

This function closes the current file. This function can be called as many times as you want. Yet, after the first call the file can't be accessed anymore.

SEE ALSO

Close, Constructors

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

private:
SystemMode - open a file

VERSION

Version: 1.2.0

SYNOPSIS

static const char *SystemMode(mo_file_mode_t mode);

PARAMETERS

mode - a set of mo_file_mode_t flags

DESCRIPTION

This function transforms an moFile mode into a string mode understood by fopen(3).

NOTES

The file will always be opened in binary mode.

RETURN VALUE

This function will always return a static string. Writing
in this string will make the following behave improperly.
One of the following will be returned:

"rb", "rb+", "wb", "wb+", "ab", "ab+"

ERRORS

Any invalid mode will generate a throw moError().

SEE ALSO

Open

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

SetBuffer - close a file

VERSION

Version: 1.2.0

SYNOPSIS

void SetBuffer(void *buffer, size_t size);

PARAMETERS

buffer - a user buffer pointer or 0
size - the size of the buffer in bytes or zero for no buffer

DESCRIPTION

This function allocates a buffer of the given size for this file.

The buffer pointer can be set to NULL in which case the buffer is automatically allocated by this function.

If the size is set to zero and there is buffer, it is freed and the file will not be bufferized.

There is only one buffer for input and output so it is easy to manage (in the event the read and write pointers are given similar offsets).

This function is automatically called whenever a file is opened and no buffer is defined.

NOTES

Too small a size will be considered as no bufferization. This size limit will always be smaller or equal to BUFSIZ.

ERRORS

When there is not enough memory for the buffer to be allocated, then a memory error is generated (std::bad_alloc).

SEE ALSO

Open

BUGS

moFile never deletes a buffer that you pass to the SetBuffer() function. So you must ensure that the buffer is being deleted at some point, and you must ensure that happens after the moFile was destroyed.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Flush - flush the buffer to the file

VERSION

Version: 1.2.0

SYNOPSIS

virtual int Flush(void);

DESCRIPTION

This function ensures that anything saved in the buffer only will be flushed to disk. It is necessary to call this function if one writes to the file and the data is bufferized and the data is necessary within the output file.

This function is automatically called when the file is closed.

RETURN VALUE

0 when no error occurs
a non zero value if an error occurs

SEE ALSO

SetBuffer, Write

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Read - read data from the file

VERSION

Version: 1.2.0

SYNOPSIS

int Read(void *buffer, size_t length);

private:
int DirectRead(size_t position, const void *buffer, size_t length);
int InternalRead(const char *buffer, size_t length);

PARAMETERS

buffer - the buffer where the data is read
length - the number of bytes which need to be read

DESCRIPTION

This function reads 'length' bytes from the current file and writes them in 'buffer'.

If the end of the file is reached before 'length' bytes are read, then the function stops and returns the number of bytes already read.

The DirectRead() internal function is used to physically read the data from the file. The InternalRead() manages the buffers when the file object has one.

RETURN VALUE

This function returns the number of bytes read when no
error is encountered.

It returns -1 if an error is encountered and unrecoverable
and nothing was read. One can test the error code with the
use of the LastErrno() or ClearError() functions.

SEE ALSO

Write, ClearError, LastErrno

BUGS

'buffer' needs to be at least 'length' bytes long otherwise this function will write after the limit and generate bugs.

If errors occur while reading the data then 'buffer' may be partially modified.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Write - write data to the file

VERSION

Version: 1.2.0

SYNOPSIS

int Write(void *buffer, size_t length);

private:
int DirectWrite(size_t position, const void *buffer, size_t length);
int InternalWrite(const char *buffer, size_t length);

PARAMETERS

buffer - the buffer the data is written
length - the number of bytes which need to be written

DESCRIPTION

This function writes 'length' bytes from the specified 'buffer' to the current file.

If the end of the file is reached before 'length' bytes are written, then the file is enlarged if possible, otherwise the function blocks until it can write the extra bytes or fails.

The DirectWrite() private function physically writes the data in the file. The InternalWrite() private function manages the bufferized writes.

NOTES

When the function returns a value different than 'length' and the SetWritePosition() was used before this call then there is no way to know which bytes have already been written into the file if the file uses a buffer.

RETURN VALUE

This function returns the number of bytes written when no
error is encountered.

It returns -1 if an error is encountered and unrecoverable
and nothing was written. One can test the error code with the
use of the LastErrno() or ClearError() functions.

SEE ALSO

Read, ClearError, LastErrno

BUGS

'buffer' needs to be at least 'length' bytes long otherwise this function will read after the limit and possibly generate bugs.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Attach - attach a file descriptor to this file

VERSION

Version: 1.2.0

SYNOPSIS

bool moFile::Attach(int fd);
bool moFile::Attach(const iostream& stream);
bool moFile::Attach(const istream& stream);
bool moFile::Attach(const ostream& stream);
bool moFile::Attach(FILE *file);

PARAMETERS

fd - a file descriptor
stream - a C++ iostream object
file - a standard C file

DESCRIPTION

This function attaches the specified file to this moFile object.

The file descriptor is duplicated with the fdopen(3) function call. It is therefore the caller responsability to close the file attached on his end.

Any previous file attached to this file will be closed. Note that on a failure the previous file will be still closed.

RETURN VALUE

These functions return true when they succeed.

SEE ALSO

Read, ClearError, LastErrno

BUGS

The attached files will be managed by the moFile. If accessed from their file descriptor from outside the moFile, the behavior is unknown.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

FindFile - search for a file within a path and specified flags

VERSION

Version: 1.2.0

SYNOPSIS

static moWCString FindExec(const moWCString& path,
const moWCString& filename,
mo_access_t mode = MO_ACCESS_DEFAULT,
const moWCString& separators = "");

PARAMETERS

path - a list of directory names
filename - the name of the file to search for
mode - the access mode the file needs to have
separators - the characters used to separate the directory names in path

DESCRIPTION

This function is used to search for a file within a list of paths.

The path is defined as the PATH variable. That's a list of directories separated by a colon (Unix) or semi-colons (Win32) by default. You can also specify your own separators. These are the same as what the moWord takes as the character separators.

When a file is found, the function checks the access mode to make sure that the file is valid. For instance, you may just want the file to exist (MO_ACCESS_EXIST), you may want to have read permission (MO_ACCESS_READ) or execution permission (MO_ACCESS_EXECUTE.) The access is checked using the Access() function.

The search goes in the order the path is defined. The first match is the only one returned.

If no file is found, the function returns an empty string, otherwise it returns the concatenation of the path and filename.

RETURN VALUE

the path of the first file found to match the given access mode

SEE ALSO

Access, moWord class

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

FullPath - change a relative filename to an absolute filename

VERSION

Version: 1.2.0

SYNOPSIS

static moWCString FullPath(const moWCString& filename, bool real_path = false);

PARAMETERS

filename - a relative or absolute filename
real_path - also transform soft links in their real counter part

DESCRIPTION

This function checks out a filename and changes it to an absolute filename.

When the flag real_path is set to true, the realpath(3) function is used to also resolve soft links thus the new absolute path is a path with only "real" directories and two different paths pointing at the same file using soft links within themselves will be viewed as being equal after a call to this function with real_path set to true.

NOTE (1): some systems will return the real path when the getcwd(3) is used and thus simulate the realpath(3) call even when the flag is kept set to false.

NOTE (2): if the real path is longer than PATH_MAX then the function may return the non-real path.

This function is a utility function (declared static) and thus it can be used without having to create an moFile object.

RETURN VALUE

always an absolute path

SEE ALSO

Attach

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

CreateDir - create a directory

VERSION

Version: 1.2.0

SYNOPSIS

static bool CreateDir(const moWCString& path, mode_t perms = 0777);

PARAMETERS

path - the path of the directory to be created
perms - a set of Unix permissions

DESCRIPTION

The CreateDir() function will check the specified path and create all the missing directories.

By default, the new directories receive a mode (set of permission flags) of 0777 & ~umask.

This function will recursively create all the missing directories within the given path.

An error can occur if the directory already exists, one of the filenames specified is in fact not a directory or when you don't have permissions. For more information, please look at the man pages of the mkdir(2) function.

This function is automatically called by the Open() function when the MO_FILE_MODE_CREATEDIR is set and the opening of the file fails the first time. The opening of the file will be attempted again if the directory creation succeeds.

Once created, it is possible to remove a directory simply by calling the Remove() function with the proper mode (ie. at least MO_REMOVE_MODE_DIRECTORY).

RETURN VALUE

true when the directory was successfully created

SEE ALSO

Open, MO_FILE_MODE_CREATEDIR, Remove

BUGS

At this time, if some directories are created, but the full path fails to be created, then the newly created directories are not automatically removed.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

CopyFile - copy a file in another

VERSION

Version: 1.2.0

SYNOPSIS

static bool CopyFile(const moWCString& source, const moWCString& destination);

PARAMETERS

source - the source file to copy
destination - where the source file will be copied

DESCRIPTION

The CopyFile() function proceeds as follow: 1) try to open the source file for reading; if it fails, the function returns at once

2) try to open the destination file for reading; if it succeeds, compare the source and destination files; if they are the same, the function fails and returns [the current test for MS-Windows is weak!]

3) try to open the destination file for writing; if it fails, the function returns

Note: the function will set the CREATEDIR flag of the Open() function and thus you will get new directories automatically if necessary

4) read the source file by blocks (64Kb) and write these blocks in the destination file; if one of these operations fail, the destination file is deleted and the function returns

5) close the files; return true; the copy succeeded

Note that the function will overwrite an existing file. If you want to know whether the file exists, use the Access() function first.

RETURN VALUE

true when the source was successfully written to the destination

SEE ALSO

Access, Remove

BUGS

The test to know whether the source and destination is not perfect.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Remove - remove a file and/or directory

VERSION

Version: 1.2.0

SYNOPSIS

static bool Remove(const moWCString& path, mo_remove_mode_t mode = MO_REMOVE_MODE_DEFAULT);

PARAMETERS

path - the path to the file or directory to be unlinked
mode - what type of a file, whether we have access, etc.
as defined by the set of the following flags
(OR them together as required)

MO_REMOVE_MODE_PLAIN
remove only plain file (this is the
default)

MO_REMOVE_MODE_DIRECTORY
remove directories; if the recursive
flag isn't set then the directory needs
to be empty

MO_REMOVE_MODE_RECURSIVE
remove directories even if not empty

MO_REMOVE_MODE_DEVICE
accept to remove a device

MO_REMOVE_MODE_FIFO
accept to remove a FIFO

MO_REMOVE_MODE_SOCKET
accept to remove a socket

MO_REMOVE_MODE_ACCESS
delete the file system object only if
the real user ID and group ID allow
for remove (ie. write permissions)

MO_REMOVE_MODE_DEFAULT
the default mode in case you don't modify
it; at this time the default is to allow
deleting if possible (ie. access isn't
tested) of a plain file (ie. any special
file or directories can't be deleted by
default)

DESCRIPTION

The Remove() function is used to delete an object from the file system. By default it can be used to delete a plain file. By default, soft links are taken as plain files. However, if the soft link points to a particular type of file, then the corresponding remove mode needs to be set to be able to remove that file. Note that a dangling soft link (a link which doesn't point anywhere) is automatically taken as a plain file and removed.

When the path points to a directory, then nothing is removed unless the MO_REMOVE_MODE_DIRECTORY flag is set. Also, if the directory isn't empty, it won't be removed unless the MO_REMOVE_MODE_RECURSIVE is also set. In this event, you don't need to set MO_REMOVE_MODE_PLAIN to have plain files removed from within the directory, however you will need to set the MO_REMOVE_MODE_DEVICE if any device exist within the directory.

NOTE: a soft link which points to a directory is taken as a directory when MO_REMOVE_MODE_DIRECTORY is set, however it isn't followed and is always considered empty. Thus the MO_REMOVE_MODE_RECURSIVE flag has no effect on soft links.

If you set the MO_REMOVE_MODE_ACCESS flag, then a test to see if the real uid/gid of the process give permission for the user to delete the object. If the real user doesn't have permission, then Remove() fails even thought the process could currently be able to remove the said object.

NOTES

If path is empty, is equal to "." or ".." then nothing happens and the function returns false, in effect preventing a process to delete these special files.

RETURN VALUE

true when all the files were removed

true if the file doesn't exist

false if the file couldn't be removed (in case of a directory
with the RECURSIVE flag set, many of the files within the
sub-directories may have been deleted even when the function
returns false)

SEE ALSO

CreateDir

BUGS

The MO_REMOVE_MODE_RECURSIVE is implemented recursively which means deleting a directory with many sub-directories could take a lot of stack. Since the soft links are never followed, these won't cause any infinite loops.

Also, the MO_REMOVE_RECURSIVE doesn't first check to see if the entire sub-directories can be fully removed before to remove files from them. In other words, even if a call to this function with the MO_REMOVE_MODE_DIRECTORY and MO_REMOVE_MODE_RECURSIVE flags set returns false, some files may have been deleted.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

Access - access a file and/or directory

VERSION

Version: 1.2.0

SYNOPSIS

static bool Access(const moWCString& path, mo_access_t mode = MO_ACCESS_DEFAULT);

PARAMETERS

path - the path to the file or directory to be checked
mode - what type of permissions we want to check
as defined by the set of the following flags
(OR them together as required)

MO_ACCESS_READ
check for read permissions

MO_ACCESS_WRITE
check for write permissions

MO_ACCESS_EXECUTE
check for execution flags

MO_ACCESS_DELETE
check whether we can delete the file

MO_ACCESS_EXIST
check for existance only

MO_ACCESS_DEFAULT
the default flag is currently set to
MO_ACCESS_EXIST turning the Access()
function to a function used to check
whether a file exists

DESCRIPTION

The Access() function will be used to test whether a file can be read, writting, executed or simply whether it exists.

The flags can be or-ed together in which case the result is true only if the test succeeds for all the flags.

NOTES

On some systems, some of the tests will either always fail (unlikely) or always succeed. Also, some system may implement some of the flags as similar (i.e. Unix sees the DELETE and WRITE as the same).

RETURN VALUE

true all the flags checks pass

false if any of the flags checks fail

SEE ALSO

Remove

BUGS

It may be considered a bug to have a result of true when checking whether you can delete a directory though you may not be able to remove the directory especially if there are files inside it which are not deletable by the caller. However, it would take a long time to test all the files within a directory before to return a valid (true) result.

This function can generate a race condition since between the time you call it and the time you access the file (for reading or otherwise) another user may change its permissions.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moFile

NAME

TemporaryFilename -- generates a temporary filename which is unique

VERSION

Version: 1.2.0

SYNOPSIS

static moWCString TemporaryFilename(const moWCString& path, const moWCString& extension);

PARAMETERS

path - the path to the temporary directory to be used
extension - an extension to append to the filename

DESCRIPTION

The TemporaryFilename() function generates a filename which points to a file that doesn't yet exist.

RETURN VALUE

the name of the temporary file if the function succeeds
an empty string if the function fails

SEE ALSO

FullPath

BUGS

The filename will really be unique within a single computer. If multiple computers use the same directory on the same hard disk the creation of the file may succeed on two computers simultaneously.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moStdIn

NAME

moStdIn - create an input moFile attached to a standard C file
~moStdIn - disconnect the filter

VERSION

Version: 1.2.0

SYNOPSIS

moStdIn(FILE *file, const char *input_encoding = "UTF-8",
const char *output_encoding = "UTF-32");

PARAMETERS

file - a standard C file
input_encoding - the name of the input encoding in ASCII (default UTF-8)
output_encoding - the name of the output encoding in ASCII (default UTF-32)

DESCRIPTION

This function creates a stream which will read anything from a standard file (usually stdin).

Because our streams are usually used with UTF-32 characters, by default, this object ensures that the input is converted to UTF-32.

SEE ALSO

moFile::Attach

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moStdOut

NAME

moStdOut - create an output moFile attached to a standard C file
~moStdOut - disconnect the filter

VERSION

Version: 1.2.0

SYNOPSIS

moStdOut(FILE *file, const char *input_encoding = "*",
const char *output_encoding = "UTF-32");

PARAMETERS

file - a standard C file
input_encoding - the name of the input encoding in ASCII (default any)
output_encoding - the name of the output encoding in ASCII (default UTF-32)

DESCRIPTION

This function creates a stream which will print everything in a standard file (usually stdout or stderr).

Because our streams are usually used with UTF-32 characters, this object can be used to ensure that all of the UTF-32 characters are converted to UTF-8 or some other encoding for different terminal compatibility.

SEE ALSO

moFile::Attach

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moAutoDelete

NAME

Constructor -- initialize an auto-delete object
Destructor -- delete the specified file

VERSION

Version: 1.2.0

SYNOPSIS

AutoDelete(const char *filename, moFile::mo_remove_mode_t mode = moFile::MO_REMOVE_MODE_DEFAULT);
~AutoDelete();

PARAMETERS

filename - the name of a file to automatically delete
mode - how to delete the specified file

DESCRIPTION

The moAutoDelete object can be used in other classes and on the stack to automatically have a file deleted when the object is deleted or the stack is being unfolded.

The destructor will delete the file or directory which name was specified on construction.

If necessary, you can call the NoDelete() function to avoid the deletion.

This is quite useful if you run a function with many return statements. This ensures that the file will be deleted no matter what return you enter.

It is not an error to pass an empty string as the filename in the constructor. However, it is not possible (at this time) to change the filename on the fly and thus it will simply have no effect.

NOTES

This class isn't derived from the moBase class. This is mainly because it isn't expected to be used as a dynamic object. Most of the time, it will be on the stack.

SEE ALSO

NoDelete()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moAutoDelete

NAME

NoDelete -- clears the filename

VERSION

Version: 1.2.0

SYNOPSIS

void NoDelete(void);

DESCRIPTION

The NoDelete() function clears the name of the file to be deleted. This means the destructor of the moAutoDelete object will have no effect.

This is useful if you have a long function which creates a file, try to work with it, and keep it only if the function succeeds. This means you will have the following code:

void foo() { filename = ...; ... moAutoDelete auto_delete(filename); ... if(error) { // the file will be deleted return; } ... auto_delete.NoDelete(); // now the file is safe }

NOTES

This only works with files which aren't directories.

SEE ALSO

NoDelete()

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox