The BlitzMax filesystem module contains commands to perform operations on the computer's
files and directories.
OpenFile, ReadFile and WriteFile return a stream object for reading and or writing data
to files.
Directories can be examined file by file using a combination of the
ReadDir, NextFile and CloseDir commands, or LoadDir can be used to read the file names
of a directory into a string array.
File properties can be examined with the FileType, FileTime, FileSize and FileMode commands.
Files and directories (folders) can be created and deleted with the CreateFile, CreateDir
DeleteFile and DeleteDir commands.
Finally, the FileSystem module contains various utility functions for handling file paths
in a system independent manner. These commands include RealPath, StripDir, StripExt,
StripAll, ExtractDir and ExtractExt.
Functions
Function reference
Function StripDir$( path$ ) |
Description | Strip directory from a file path |
Example | ' stripdir.bmx
print stripdir("mypath/myfile.bmx") 'prints myfile.bmx
|
Function StripExt$( path$ ) |
Description | Strip extension from a file path |
Example | ' stripext.bmx
print stripext("mypath/myfile.bmx") 'prints mypath/myfile
|
Function StripAll$( path$ ) |
Description | Strip directory and extension from a file path |
Example | ' stripall.bmx
print stripall("mypath/myfile.bmx") 'prints myfile
|
Function StripSlash$( path$ ) |
Description | Strip trailing slash from a file path |
Information |
StripSlash will not remove the trailing slash from a 'root' path. For example, "/"
or (on Win32 only) "C:/".
|
Example | ' stripslash.bmx
print stripslash("mypath/") 'prints mypath
|
Function ExtractDir$( path$ ) |
Description | Extract directory from a file path |
Example | ' extractdir.bmx
print extractdir("mypath/myfile.bmx") 'prints mypath
|
Function ExtractExt$( path$ ) |
Description | Extract extension from a file path |
Example | ' extractext.bmx
print extractext("mypath/myfile.bmx") 'prints bmx
|
Function CurrentDir$() |
Returns | The current directory
|
Description | Get Current Directory |
Example | ' currentdir.bmx
cd$=currentdir()
print "CurrentDir()="+cd$
|
Function RealPath$( path$ ) |
Description | Get real, absolute path of a file path |
Example | ' realpath.bmx
print realpath("realpath.bmx") 'prints full path of this source
print realpath("..") 'prints full path of parent directory
|
Function FileType( path$ ) |
Returns | 0 if file at path doesn't exist, FILETYPE_FILE (1) if the file is a plain file or FILETYPE_DIR (2) if the file is a directory
|
Description | Get file type |
Example | ' filetype.bmx
print filetype(".") 'prints 2 for directory type
print filetype("filetype.bmx") 'prints 1 for file type
print filetype("notfound.file") 'prints 0 for doesn't exist
|
Function FileTime( path$ ) |
Returns | The time the file at path was last modified
|
Description | Get file time |
Example | ' filetime.bmx
print filetime("filetime.bmx")
|
Function FileSize( path$ ) |
Returns | Size, in bytes, of the file at path, or -1 if the file does not exist
|
Description | Get file size |
Example | ' filesize.bmx
' the following prints the size of this source file in bytes
print filesize("filesize.bmx")
|
Function FileMode( path$ ) |
Returns | file mode flags
|
Description | Get file mode |
Example | ' filemode.bmx
' the following function converts the file mode to
' the standard unix permission bits string
Function Permissions$(mode)
local testbit,pos
local p$="rwxrwxrwx"
testbit=%100000000
pos=1
while (testbit)
if mode & testbit res$:+mid$(p$,pos,1) else res$:+"-"
testbit=testbit shr 1
pos:+1
wend
return res
End Function
print Permissions$(filemode("filemode.bmx"))
|
Function SetFileMode( path$,mode ) |
Description | Set file mode |
Example | ' setfilemode.bmx
' the following makes this source file readonly
writebits=%010010010
' read the file mode
mode=filemode("setfilemode.bmx")
'mask out the write bits to make readonly
mode=mode & ~writebits
'set the new file mode
setfilemode("setfilemode.bmx",mode)
|
Function CreateFile( path$ ) |
Returns | True if successful
|
Description | Create a file |
Example | ' createfile.bmx
success=createfile("myfile")
if not success runtimeerror "error creating file"
|
Function CreateDir( path$,recurse=False ) |
Returns | True if successful
|
Description | Create a directory |
Information |
If recurse is true, any required subdirectories are also created.
|
Example | ' createdir.bmx
success=createdir("myfolder")
if not success runtimeerror "error creating directory"
|
Function DeleteFile( path$ ) |
Returns | True if successful
|
Description | Delete a file |
Example | ' deletefile.bmx
success=deletefile("myfile")
if not success runtimeerror "error deleting file"
|
Function RenameFile( oldpath$,newpath$ ) |
Returns | True if successful
|
Description | Renames a file |
Function CopyFile( src$,dst$ ) |
Returns | True if successful
|
Description | Copy a file |
Function CopyDir( src$,dst$ ) |
Returns | True if successful
|
Description | Copy a directory |
Function DeleteDir( path$,recurse=False ) |
Returns | True if successful
|
Description | Delete a directory |
Information | Set recurse to true to delete all subdirectories and files recursively -
but be careful!
|
Example | ' deletedir.bmx
success=deletedir("myfolder")
if not success runtimeerror "error deleting directory"
|
Function ChangeDir( path$ ) |
Returns | True if successful
|
Description | Change current directory |
Example | ' changedir.bmx
print "CurrentDir()="+currentdir()
' change current folder to the parent folder
changedir ".."
' print new CurrentDir()
print "CurrentDir()="+currentdir()
|
Function ReadDir( path$ ) |
Returns | An integer directory handle, or 0 if the directory does not exist
|
Description | Open a directory |
Example | ' readdir.bmx
dir=ReadDir(CurrentDir())
If Not dir RuntimeError "failed to read current directory"
Repeat
t$=NextFile( dir )
If t="" Exit
If t="." Or t=".." Continue
Print t
Forever
CloseDir dir
|
Function NextFile$( dir ) |
Returns | File name of next file in directory opened using ReadDir, or an empty string if there are no more files to read.
|
Description | Return next file in a directory |
Function CloseDir( dir ) |
Description | Close a directory |
Function LoadDir$[]( dir$,skip_dots=True ) |
Returns | A string array containing contents of dir
|
Description | Load a directory |
Information | The skip_dots parameter, if true, removes the '.' (current) and '..'
(parent) directories from the returned array.
|
Example | ' loaddir.bmx
' declare a string array
local files$[]
files=loaddir(currentdir())
for t$=eachin files
print t
next
|
Function OpenFile:TStream( url:Object,readable=True,writeable=True ) |
Description | Open a file for input and/or output. |
Information |
This command is similar to the OpenStream command but will attempt
to cache the contents of the file to ensure serial streams such as
http: based url's are seekable. Use the CloseStream command when
finished reading and or writing to a Stream returned by OpenFile.
|
Example | ' openfile.bmx
' the following prints the contents of this source file
file=openfile("openfile.bmx")
if not file runtimeerror "could not open file openfile.bmx"
while not eof(file)
print readline(file)
wend
closestream file
|
Function ReadFile:TStream( url:Object ) |
Description | Open a file for input. |
Information |
This command is similar to the ReadStream command but will attempt
to cache the contents of the file to ensure serial streams such as
http: based url's are seekable. Use the CloseStream command when
finished reading and or writing to a Stream returned by OpenFile.
|
Example | ' readfile.bmx
' the following prints the contents of this source file
file=readfile("readfile.bmx")
if not file runtimeerror "could not open file openfile.bmx"
while not eof(file)
print readline(file)
wend
closestream file
|
Function WriteFile:TStream( url:Object ) |
Description | Open a file for output. |
Information |
This command is identical to the WriteStream command.
|
Example | ' writefile.bmx
file=writefile("test.txt")
if not file runtimeerror "failed to open test.txt file"
writeline file,"hello world"
closestream file
|
Function CloseFile( stream:TStream ) |
Description | Closes a file stream. |
Information |
After performing file operations on an open file make sure to
close the file stream with either CloseFile or the identical
CloseStream command.
|