| Version: 3.3.1

Macros | Typedefs | Enumerations | Functions | Variables
Files and Directories
Functions and Macros by Category

## Detailed Description

These functions provide a platform-independent API for common file and directory functionality.

Related class group: File Handling

## Macros
#define | wxCHANGE_UMASK(mask)
| Under Unix this macro changes the current process umask to the given value, unless it is equal to -1 in which case nothing is done, and restores it to the original value on scope exit. More...

## Typedefs
typedef off_t | wxFileOffset
| The type used to store and provide byte offsets or byte sizes for files or streams. More...

## Enumerations
enum | wxPosixPermissions { wxS_IRUSR = 00400 , wxS_IWUSR = 00200 , wxS_IXUSR = 00100 , wxS_IRGRP = 00040 , wxS_IWGRP = 00020 , wxS_IXGRP = 00010 , wxS_IROTH = 00004 , wxS_IWOTH = 00002 , wxS_IXOTH = 00001 , wxPOSIX_USER_READ = wxS_IRUSR , wxPOSIX_USER_WRITE = wxS_IWUSR , wxPOSIX_USER_EXECUTE = wxS_IXUSR , wxPOSIX_GROUP_READ = wxS_IRGRP , wxPOSIX_GROUP_WRITE = wxS_IWGRP , wxPOSIX_GROUP_EXECUTE = wxS_IXGRP , wxPOSIX_OTHERS_READ = wxS_IROTH , wxPOSIX_OTHERS_WRITE = wxS_IWOTH , wxPOSIX_OTHERS_EXECUTE = wxS_IXOTH , wxS_DEFAULT , wxS_DIR_DEFAULT }
| File permission bit names. More...
enum | wxSeekMode { wxFromStart , wxFromCurrent , wxFromEnd }
| Parameter indicating how file offset should be interpreted. More...
enum | wxFileKind { wxFILE_KIND_UNKNOWN , wxFILE_KIND_DISK , wxFILE_KIND_TERMINAL , wxFILE_KIND_PIPE }
| File kind enumerations returned from wxGetFileKind(). More...

## Functions
bool | wxTransferFileToStream (const wxString &filename, ostream &stream)
| Copies the given file to stream. More...
bool | wxTransferStreamToFile (istream &stream, const wxString &filename)
| Copies the given stream to the file filename. More...
wxString | wxGetOSDirectory ()
| Returns the Windows directory under Windows; other platforms return an empty string. More...
int | wxParseCommonDialogsFilter (const wxString &wildCard, wxArrayString &descriptions, wxArrayString &filters)
| Parses the wildCard, returning the number of filters. More...
void | wxDos2UnixFilename (wxChar *s)
| Converts a DOS to a Unix filename by replacing backslashes with forward slashes. More...
void | wxUnix2DosFilename (wxChar *s)
| Converts a Unix to a DOS filename by replacing forward slashes with backslashes. More...
bool | wxDirExists (const wxString &dirname)
| Returns true if dirname exists and is a directory. More...
void | wxSplitPath (const wxString &fullname, wxString *path, wxString *name, wxString *ext)
time_t | wxFileModificationTime (const wxString &filename)
| Returns time of last modification of given file. More...
bool | wxRenameFile (const wxString &oldpath, const wxString &newpath, bool overwrite=true)
| Renames oldpath to newpath, returning true if successful. More...
bool | wxCopyFile (const wxString &src, const wxString &dest, bool overwrite=true)
| Copies src to dest, returning true if successful. More...
bool | wxFileExists (const wxString &filename)
| Returns true if the file exists and is a plain file. More...
bool | wxMatchWild (const wxString &pattern, const wxString &text, bool dot_special)
| Returns true if the pattern matches the text; if dot_special is true, filenames beginning with a dot are not matched with wildcard characters. More...
wxString | wxGetWorkingDirectory (char *buf=nullptr, int sz=1000)
wxString | wxPathOnly (const wxString &path)
| Returns the directory part of the filename. More...
bool | wxIsWild (const wxString &pattern)
| Returns true if the pattern contains wildcards. More...
bool | wxIsAbsolutePath (const wxString &filename)
| Returns true if the argument is an absolute filename, i.e. with a slash or drive name at the beginning. More...
wxString | wxGetCwd ()
| Returns a string containing the current (or working) directory. More...
bool | wxSetWorkingDirectory (const wxString &dir)
| Sets the current working directory, returning true if the operation succeeded. More...
bool | wxConcatFiles (const wxString &src1, const wxString &src2, const wxString &dest)
| Concatenates src1 and src2 to dest, returning true if successful. More...
bool | wxRemoveFile (const wxString &file)
| Removes file, returning true if successful. More...
bool | wxMkdir (const wxString &dir, int perm=wxS_DIR_DEFAULT)
| Makes the directory dir, returning true if successful. More...
bool | wxRmdir (const wxString &dir, int flags=0)
| Removes the directory dir, returning true if successful. More...
wxString | wxFindNextFile ()
| Returns the next file that matches the path passed to wxFindFirstFile(). More...
wxString | wxFindFirstFile (const wxString &spec, int flags=0)
| This function does directory searching; returns the first file that matches the path spec, or the empty string. More...
wxFileKind | wxGetFileKind (int fd)
| Returns the type of an open file. More...
wxFileKind | wxGetFileKind (FILE *fp)
wxString | wxFileNameFromPath (const wxString &path)
char * | wxFileNameFromPath (char *path)
char * | wxGetTempFileName (const wxString &prefix, char *buf=nullptr)
bool | wxGetTempFileName (const wxString &prefix, wxString &buf)

## Variables
const int | wxInvalidOffset = -1
| A special return value of many wxWidgets classes to indicate that an invalid offset was given. More...

## Macro Definition Documentation

## ◆ wxCHANGE_UMASK

#define wxCHANGE_UMASK | ( |  | mask | ) |

Under Unix this macro changes the current process umask to the given value, unless it is equal to -1 in which case nothing is done, and restores it to the original value on scope exit.

It works by declaring a variable which sets umask to mask in its constructor and restores it in its destructor. Under other platforms this macro expands to nothing.

Include file:

    #include <wx/filefn.h>

## Typedef Documentation

## ◆ wxFileOffset

typedef off_t wxFileOffset

The type used to store and provide byte offsets or byte sizes for files or streams.

This type is usually just a synonym for `off_t` but can be defined as `wxLongLong_t` if `wxHAS_HUGE_FILES` is defined but `off_t` is only 32 bits.

## Enumeration Type Documentation

## ◆ wxFileKind

enum wxFileKind

File kind enumerations returned from wxGetFileKind().

Also used by wxFFile::GetKind() and wxFile::GetKind().

Include file:

    #include <wx/filefn.h>

Enumerator
wxFILE_KIND_UNKNOWN | Unknown file kind, or unable to determine.
wxFILE_KIND_DISK | A file supporting seeking to arbitrary offsets.
wxFILE_KIND_TERMINAL | A tty.
wxFILE_KIND_PIPE | A pipe.

## ◆ wxPosixPermissions

enum wxPosixPermissions

File permission bit names.

We define these constants in wxWidgets because S_IREAD &c are not standard. However, we do assume that the values correspond to the Unix umask bits.

Enumerator
wxS_IRUSR | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IWUSR | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IXUSR | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IRGRP | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IWGRP | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IXGRP | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IROTH | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IWOTH | Standard POSIX names for these permission flags with "wx" prefix.
wxS_IXOTH | Standard POSIX names for these permission flags with "wx" prefix.
wxPOSIX_USER_READ | Longer but more readable synonyms for the constants above.
wxPOSIX_USER_WRITE | Longer but more readable synonyms for the constants above.
wxPOSIX_USER_EXECUTE | Longer but more readable synonyms for the constants above.
wxPOSIX_GROUP_READ | Longer but more readable synonyms for the constants above.
wxPOSIX_GROUP_WRITE | Longer but more readable synonyms for the constants above.
wxPOSIX_GROUP_EXECUTE | Longer but more readable synonyms for the constants above.
wxPOSIX_OTHERS_READ | Longer but more readable synonyms for the constants above.
wxPOSIX_OTHERS_WRITE | Longer but more readable synonyms for the constants above.
wxPOSIX_OTHERS_EXECUTE | Longer but more readable synonyms for the constants above.
wxS_DEFAULT | Default mode for the new files: allow reading/writing them to everybody but the effective file mode will be set after ANDing this value with umask and so won't include wxS_IW{GRP,OTH} for the default 022 umask value.
wxS_DIR_DEFAULT | Default mode for the new directories (see wxFileName::Mkdir): allow reading/writing/executing them to everybody, but just like wxS_DEFAULT the effective directory mode will be set after ANDing this value with umask.

## ◆ wxSeekMode

enum wxSeekMode

Parameter indicating how file offset should be interpreted.

This is used by wxFFile::Seek() and wxFile::Seek().

Include file:

    #include <wx/filefn.h>

Enumerator
wxFromStart | Seek from the file beginning.
wxFromCurrent | Seek from the current position.
wxFromEnd | Seek from end of the file.

## Function Documentation

## ◆ wxConcatFiles()

bool wxConcatFiles | ( | const wxString & | src1,
|  | const wxString & | src2,
|  | const wxString & | dest
| ) |  |

Concatenates src1 and src2 to dest, returning true if successful.

Include file:

    #include <wx/filefn.h>

## ◆ wxCopyFile()

bool wxCopyFile | ( | const wxString & | src,
|  | const wxString & | dest,
|  | bool | overwrite = `true`
| ) |  |

Copies src to dest, returning true if successful.

If overwrite parameter is true (default), the destination file is overwritten if it exists, but if overwrite is false, the functions fails in this case.

This function supports resources forks under Mac OS.

Include file:

    #include <wx/filefn.h>

## ◆ wxDirExists()

bool wxDirExists | ( | const wxString & | dirname | ) |

Returns true if dirname exists and is a directory.

Include file:

    #include <wx/filefn.h>

## ◆ wxDos2UnixFilename()

void wxDos2UnixFilename | ( | wxChar * | s | ) |

Converts a DOS to a Unix filename by replacing backslashes with forward slashes.

Deprecated:
  Construct a wxFileName with wxPATH_DOS and then use wxFileName::GetFullPath(wxPATH_UNIX) instead.

Include file:

    #include <wx/filefn.h>

## ◆ wxFileExists()

bool wxFileExists | ( | const wxString & | filename | ) |

Returns true if the file exists and is a plain file.

Include file:

    #include <wx/filefn.h>

## ◆ wxFileModificationTime()

time_t wxFileModificationTime | ( | const wxString & | filename | ) |

Returns time of last modification of given file.

The function returns `(time_t)-1` if an error occurred (e.g. file not found).

Include file:

    #include <wx/filefn.h>

## ◆ wxFileNameFromPath() [1/2]

char* wxFileNameFromPath | ( | char * | path | ) |

## ◆ wxFileNameFromPath() [2/2]

wxString wxFileNameFromPath | ( | const wxString & | path | ) |

Deprecated:
  This function is obsolete, please use wxFileName::SplitPath() instead.

Returns the filename for a full path. The second form returns a pointer to temporary storage that should not be deallocated.

Include file:

    #include <wx/filefn.h>

## ◆ wxFindFirstFile()

wxString wxFindFirstFile | ( | const wxString & | spec,
|  | int | flags = `0`
| ) |  |

This function does directory searching; returns the first file that matches the path spec, or the empty string.

Use wxFindNextFile() to get the next matching file. Neither will report the current directory "." or the parent directory "..".

Warning
  As of 2.5.2, these functions are not thread-safe! (they use static variables). You probably want to use wxDir::GetFirst() or wxDirTraverser instead.

spec may contain wildcards.

flags may be wxDIR for restricting the query to directories, wxFILE for files or zero for either.

For example:

wxString f = wxFindFirstFile("/home/project/*.*");
while ( !f.empty() )
{
...
f = wxFindNextFile();
}
wxString
String class for passing textual data to or receiving it from wxWidgets.
Definition: string.h:372
wxString::empty
bool empty() const
wxFindFirstFile
wxString wxFindFirstFile(const wxString &spec, int flags=0)
This function does directory searching; returns the first file that matches the path spec,...
wxFindNextFile
wxString wxFindNextFile()
Returns the next file that matches the path passed to wxFindFirstFile().

Include file:

    #include <wx/filefn.h>

## ◆ wxFindNextFile()

wxString wxFindNextFile | ( |  | ) |

Returns the next file that matches the path passed to wxFindFirstFile().

See wxFindFirstFile() for an example.

Include file:

    #include <wx/filefn.h>

## ◆ wxGetCwd()

wxString wxGetCwd | ( |  | ) |

Returns a string containing the current (or working) directory.

Include file:

    #include <wx/filefn.h>

## ◆ wxGetFileKind() [1/2]

wxFileKind wxGetFileKind | ( | FILE * | fp | ) |

## ◆ wxGetFileKind() [2/2]

wxFileKind wxGetFileKind | ( | int | fd | ) |

Returns the type of an open file.

Possible return values are enumerations of wxFileKind.

Include file:

    #include <wx/filefn.h>

## ◆ wxGetOSDirectory()

wxString wxGetOSDirectory | ( |  | ) |

Returns the Windows directory under Windows; other platforms return an empty string.

Include file:

    #include <wx/filefn.h>

## ◆ wxGetTempFileName() [1/2]

char* wxGetTempFileName | ( | const wxString & | prefix,
|  | char * | buf = `nullptr`
| ) |  |

Deprecated:
  This function is obsolete, please use wxFileName::CreateTempFileName() instead.

Include file:

    #include <wx/filefn.h>

## ◆ wxGetTempFileName() [2/2]

bool wxGetTempFileName | ( | const wxString & | prefix,
|  | wxString & | buf
| ) |  |

## ◆ wxGetWorkingDirectory()

wxString wxGetWorkingDirectory | ( | char * | buf = `nullptr`,
|  | int | sz = `1000`
| ) |  |

Deprecated:
  This function is deprecated, use wxGetCwd() instead.

Copies the current working directory into the buffer if supplied, or copies the working directory into new storage (which you must delete yourself) if the buffer is nullptr.

sz is the size of the buffer if supplied.

Include file:

    #include <wx/filefn.h>

## ◆ wxIsAbsolutePath()

bool wxIsAbsolutePath | ( | const wxString & | filename | ) |

Returns true if the argument is an absolute filename, i.e. with a slash or drive name at the beginning.

Include file:

    #include <wx/filefn.h>

## ◆ wxIsWild()

bool wxIsWild | ( | const wxString & | pattern | ) |

Returns true if the pattern contains wildcards.

See also
  wxMatchWild()

Include file:

    #include <wx/filefn.h>

## ◆ wxMatchWild()

bool wxMatchWild | ( | const wxString & | pattern,
|  | const wxString & | text,
|  | bool | dot_special
| ) |  |

Returns true if the pattern matches the text; if dot_special is true, filenames beginning with a dot are not matched with wildcard characters.

Note
  Matching is always case-sensitive, even on platforms where paths are generally treated as case-insensitive.

See also
  wxIsWild()

Include file:

    #include <wx/filefn.h>

## ◆ wxMkdir()

bool wxMkdir | ( | const wxString & | dir,
|  | int | perm = `wxS_DIR_DEFAULT`
| ) |  |

Makes the directory dir, returning true if successful.

perm is the access mask for the directory for the systems on which it is supported (Unix) and doesn't have any effect on the other ones.

Include file:

    #include <wx/filefn.h>

## ◆ wxParseCommonDialogsFilter()

int wxParseCommonDialogsFilter | ( | const wxString & | wildCard,
|  | wxArrayString & | descriptions,
|  | wxArrayString & | filters
| ) |  |

Parses the wildCard, returning the number of filters.

Returns 0 if none or if there's a problem.

The arrays will contain an equal number of items found before the error. On platforms where native dialogs handle only one filter per entry, entries in arrays are automatically adjusted. wildCard is in the form:

"All files (*)|*|Image Files (*.jpeg *.png)|*.jpg;*.png"

Include file:

    #include <wx/filefn.h>

## ◆ wxPathOnly()

wxString wxPathOnly | ( | const wxString & | path | ) |

Returns the directory part of the filename.

Include file:

    #include <wx/filefn.h>

## ◆ wxRemoveFile()

bool wxRemoveFile | ( | const wxString & | file | ) |

Removes file, returning true if successful.

Include file:

    #include <wx/filefn.h>

## ◆ wxRenameFile()

bool wxRenameFile | ( | const wxString & | oldpath,
|  | const wxString & | newpath,
|  | bool | overwrite = `true`
| ) |  |

Renames oldpath to newpath, returning true if successful.

If newpath is a directory, oldpath is moved into it (overwrite is ignored in this case). Otherwise, if newpath is an existing file, it is overwritten if overwrite is true (default) and the function fails if overwrite is false.

Since wxWidgets 3.3.0, if overwrite is true `ReplaceFile()` function is used under MSW which allows to preserve the file attributes while replacing its contents.

Include file:

    #include <wx/filefn.h>

## ◆ wxRmdir()

bool wxRmdir | ( | const wxString & | dir,
|  | int | flags = `0`
| ) |  |

Removes the directory dir, returning true if successful.

Does not work under VMS.

The flags parameter is reserved for future use.

Note
  There is also a wxRmDir() function which simply wraps the standard POSIX `rmdir()` function and so return an integer error code instead of a boolean value (but otherwise is currently identical to wxRmdir()), don't confuse these two functions.

Include file:

    #include <wx/filefn.h>

## ◆ wxSetWorkingDirectory()

bool wxSetWorkingDirectory | ( | const wxString & | dir | ) |

Sets the current working directory, returning true if the operation succeeded.

Under MS Windows, the current drive is also changed if dir contains a drive specification.

Include file:

    #include <wx/filefn.h>

## ◆ wxSplitPath()

void wxSplitPath | ( | const wxString & | fullname,
|  | wxString * | path,
|  | wxString * | name,
|  | wxString * | ext
| ) |  |

Deprecated:
  This function is obsolete, please use wxFileName::SplitPath() instead.

This function splits a full file name into components: the path (including possible disk/drive specification under Windows), the base name, and the extension. Any of the output parameters (path, name or ext) may be nullptr if you are not interested in the value of a particular component.

wxSplitPath() will correctly handle filenames with both DOS and Unix path separators under Windows, however it will not consider backslashes as path separators under Unix (where backslash is a valid character in a filename).

On entry, fullname should be non-null (it may be empty though).

On return, path contains the file path (without the trailing separator), name contains the file name and `ext` contains the file extension without leading dot. All three of them may be empty if the corresponding component is. The old contents of the strings pointed to by these parameters will be overwritten in any case (if the pointers are not nullptr).

Include file:

    #include <wx/filefn.h>

## ◆ wxTransferFileToStream()

bool wxTransferFileToStream | ( | const wxString & | filename,
|  | ostream & | stream
| ) |  |

Copies the given file to stream.

Useful when converting an old application to use streams (within the document/view framework, for example).

Include file:

    #include <wx/docview.h>

## ◆ wxTransferStreamToFile()

bool wxTransferStreamToFile | ( | istream & | stream,
|  | const wxString & | filename
| ) |  |

Copies the given stream to the file filename.

Useful when converting an old application to use streams (within the document/view framework, for example).

Include file:

    #include <wx/docview.h>

## ◆ wxUnix2DosFilename()

void wxUnix2DosFilename | ( | wxChar * | s | ) |

Converts a Unix to a DOS filename by replacing forward slashes with backslashes.

Deprecated:
  Construct a wxFileName with wxPATH_UNIX and then use wxFileName::GetFullPath(wxPATH_DOS) instead.

Include file:

    #include <wx/filefn.h>

## Variable Documentation

## ◆ wxInvalidOffset

const int wxInvalidOffset = -1

A special return value of many wxWidgets classes to indicate that an invalid offset was given.