- Generated by
1.9.8
|
BDE 4.14.0 Production release
|
Provide methods for filesystem access with multi-language names.
This component provides a platform-independent interface to filesystem utility methods, supporting multi-language file and path names. Each method in the bdls::FilesystemUtil namespace is a thin wrapper on top of the operating system's own filesystem access functions, providing a consistent and unambiguous interface for handling files on all supported platforms.
Methods in this component can be used to manipulate files with any name in any language on all supported platforms. To provide such support, the following restrictions are applied to file names and patterns passed to methods of this component: On Windows, all file names and patterns must be passed as UTF-8-encoded strings; file search results will similarly be encoded as UTF-8. On Posix, file names and patterns may be passed in any encoding, but all processes accessing a given file must encode its name in the same encoding. On modern Posix installations, this effectively means that file names and patterns should be encoded in UTF-8, just as on Windows. See the section "Platform-Specific File Name Encoding Caveats" below.
The behavior of the open method is governed by three sets of enumerations:
bdls::FilesystemUtil::FileOpenPolicy governs whether open creates a new file or opens an existing one. The following values are possible:
e_OPEN Open an existing file.
e_CREATE Create a new file.
e_CREATE_PRIVATE Create a new file, with limited permissions where that is supported (e.g. not necessarily Microsoft Windows).
e_OPEN_OR_CREATE Open a file if it exists, and create a new file otherwise.
bdls::FilesystemUtil::FileIOPolicy governs what Input/Output operations are allowed on a file after it is opened. The following values are possible:
e_READ_ONLY Allow reading only.
e_WRITE_ONLY Allow writing only.
e_READ_WRITE Allow both reading and writing.
e_APPEND_ONLY Allow appending to end-of-file only.
e_READ_APPEND Allow both reading and appending to end-of-file.
bdls::FilesystemUtil::FileTruncatePolicy governs whether open deletes the existing contents of a file when it is opened. The following values are possible:
e_TRUNCATE Delete the file's contents.
e_KEEP Keep the file's contents.
The behavior of the seek method is governed by an enumeration that determines the point from which the seek operation starts:
e_SEEK_FROM_BEGINNING Seek from the beginning of the file.
e_SEEK_FROM_CURRENT Seek from the current position in the file.
e_SEEK_FROM_END Seek from the end of the file.
Locking has the following caveats for the following operating systems:
The bdls::FilesystemUtil::read and bdls::FilesystemUtil::write methods add no atomicity guarantees for reading and writing to those provided (if any) by the underlying platform's methods for reading and writing (see http://lwn.net/articles/180387/).
File-name encodings have the following caveats for the following operating systems:
bdls::FilesystemUtil that take a file or directory name or pattern as a char* or bsl::string type assume that the name is encoded in UTF-8. The routines attempt to convert the name to a UTF-16 wchar_t string via bdlde::CharConvertUtf16::utf8ToUtf16, and if the conversion succeeds, call the Windows wide-character W APIs with the UTF-16 name. If the conversion fails, the method fails. Similarly, file searches returning file names call the Windows wide-character W APIs and convert the resulting UTF-16 names to UTF-8.utf8ToUtf16 nor the Windows W APIs do any normalization of the UTF-16 strings resulting from UTF-8 conversion, and it is therefore possible to have sets of file names that have the same visual representation but are treated as different names by the filesystem.bdls::FilesystemUtil as a char* or bsl::string type is passed unchanged to the underlying system file APIs. Because the file names and patterns are passed unchanged, bdls::FilesystemUtil methods will work correctly on Posix with any encoding, but will interoperate only with processes that use the same encoding as the current process.In order to provide consistent behavior across both Posix and Windows platforms, when the open method is called, file truncation is allowed only if the client requests an openPolicy containing the word CREATE and/or an ioPolicy containing the word WRITE.
This section illustrates intended use of this component.
In this example, we start with a (relative) native path to a directory containing log files:
Suppose that we want to separate files into "old" and "new" subdirectories on the basis of modification time. We will provide paths representing these locations, and create the directories if they do not exist:
We know that all of our log files match the pattern "*.log", so let's search for all such files in the log directory:
Now for each of these files, we will get the modification time. Files that are older than 2 days will be moved to "old", and the rest will be moved to "new":
bdls::FilesystemUtil::visitPaths enables clients to define a function object to operate on file paths that match a specified pattern. In this example, we create a function that can be used to filter out files that have a last modified time within a particular time frame.
First we define our filtering function:
Then, with the help of bdls::FilesystemUtil::visitPaths and bdlf::BindUtil::bind, we create a function for finding all file paths that match a specified pattern and have a last modified time within a specified start and end time (both specified as a bdlt::Datetime):
1.9.8