OpenEuphoria: Euphoria v4.0

Current platform's possible path separators. This is slightly different in that on Windows the path separators variable contains \\ as well as : and / as newer Windows versions support / as a path separator. On Unix systems, it only contains /.

8.5.1.3 EOLSEP

public constant EOLSEP

Current platform's newline string: "\n" on Unix, else "\r\n".

8.5.1.4 EOL

public constant EOL

All platform's newline character: '\n'. When text lines are read the native platform's EOLSEP string is replaced by a single character EOL.

8.5.1.5 PATHSEP

public constant PATHSEP

Current platform's path separator character: : on Unix, else ;.

8.5.1.6 NULLDEVICE

public constant NULLDEVICE

Current platform's null device path: /dev/null on Unix, else NUL:.

8.5.1.7 SHARED_LIB_EXT

public constant SHARED_LIB_EXT

Current platform's shared library extension. For instance it can be dll, so or dylib depending on the platform.

8.5.2 Directory Handling

8.5.2.1 D_NAME

include std/filesys.e
namespace filesys
public enum D_NAME

8.5.2.2 D_ATTRIBUTES

include std/filesys.e
namespace filesys
public enum D_ATTRIBUTES

8.5.2.3 D_SIZE

include std/filesys.e
namespace filesys
public enum D_SIZE

8.5.2.4 D_YEAR

include std/filesys.e
namespace filesys
public enum D_YEAR

8.5.2.5 D_MONTH

include std/filesys.e
namespace filesys
public enum D_MONTH

8.5.2.6 D_DAY

include std/filesys.e
namespace filesys
public enum D_DAY

8.5.2.7 D_HOUR

include std/filesys.e
namespace filesys
public enum D_HOUR

8.5.2.8 D_MINUTE

include std/filesys.e
namespace filesys
public enum D_MINUTE

8.5.2.9 D_SECOND

include std/filesys.e
namespace filesys
public enum D_SECOND

8.5.2.10 D_MILLISECOND

include std/filesys.e
namespace filesys
public enum D_MILLISECOND

8.5.2.11 D_ALTNAME

include std/filesys.e
namespace filesys
public enum D_ALTNAME

8.5.2.12 W_BAD_PATH

include std/filesys.e
namespace filesys
public constant W_BAD_PATH

Bad path error code. See walk_dir

8.5.2.13 dir

include std/filesys.e
namespace filesys
public function dir(sequence name)

Return directory information for the specified file or directory.

Parameters:

name : a sequence, the name to be looked up in the file system.

Returns:

An object, -1 if no match found, else a sequence of sequence entries

Errors:

The length of name should not exceed 1,024 characters.

Comments:

name can also contain * and ? wildcards to select multiple files.

The returned information is similar to what you would get from the DIR command. A sequence is returned where each element is a sequence that describes one file or subdirectory.

If name refers to a directory you may have entries for "." and "..", just as with the DIR command. If it refers to an existing file, and has no wildcards, then the returned sequence will have just one entry, i.e. its length will be 1. If name contains wildcards you may have multiple entries.

Each entry contains the name, attributes and file size as well as the time of the last modification.

You can refer to the elements of an entry with the following constants:

public constant
    -- File Attributes
    D_NAME       = 1,
    D_ATTRIBUTES = 2,
    D_SIZE       = 3,
    D_YEAR       = 4,
    D_MONTH      = 5,
    D_DAY        = 6,
    D_HOUR       = 7,
    D_MINUTE     = 8,
    D_SECOND     = 9,
    D_MILLISECOND = 10,
    D_ALTNAME    = 11

The attributes element is a string sequence containing characters chosen from:

Attribute	Description
'd'	directory
'r'	read only file
'h'	hidden file
's'	system file
'v'	volume-id entry
'a'	archive file
'c'	compressed file
'e'	encrypted file
'N'	not indexed
'D'	a device name
'O'	offline
'R'	reparse point or symbolic link
'S'	sparse file
'T'	temporary file
'V'	virtual file

A normal file without special attributes would just have an empty string, "", in this field.

The top level directory, e.g. c:\ does not have "." or ".." entries.

This function is often used just to test if a file or directory exists.

Under WINDOWS, the argument can have a long file or directory name anywhere in the path.

Under Unix, the only attribute currently available is 'd' and the milliseconds are always zero.

WINDOWS: The file name returned in [D_NAME] will be a long file name. If [D_ALTNAME] is not zero, it contains the 'short' name of the file.

Example 1:

d = dir(current_dir())

-- d might have:
--  {
--    {".",    "d",     0  1994, 1, 18,  9, 30, 02},
--    {"..",   "d",     0  1994, 1, 18,  9, 20, 14},
--    {"fred", "ra", 2350, 1994, 1, 22, 17, 22, 40},
--    {"sub",  "d" ,    0, 1993, 9, 20,  8, 50, 12}
--  }

d[3][D_NAME] would be "fred"

8.5.2.14 current_dir

include std/filesys.e
namespace filesys
public function current_dir()

Return the name of the current working directory.

Returns:

A sequence, the name of the current working directory

Comments:

There will be no slash or backslash on the end of the current directory, except under Windows, at the top-level of a drive, e.g. C:\

Example 1:

sequence s
s = current_dir()
-- s would have "C:\EUPHORIA\DOC" if you were in that directory

8.5.2.15 chdir

include std/filesys.e
namespace filesys
public function chdir(sequence newdir)

Set a new value for the current directory

Parameters:

newdir : a sequence, the name for the new working directory.

Returns:

An integer, 0 on failure, 1 on success.

Comments:

By setting the current directory, you can refer to files in that directory using just the file name.

The current_dir() function will return the name of the current directory.

On Windows the current directory is a public property shared by all the processes running under one shell. On Unix a subprocess can change the current directory for itself, but this won't affect the current directory of its parent process.

Example 1:

if chdir("c:\\euphoria") then
    f = open("readme.doc", "r")
else
    puts(STDERR, "Error: No euphoria directory?\n")
end if

8.5.2.16 my_dir

include std/filesys.e
namespace filesys
public integer my_dir

Deprecated, so therefore not documented.

8.5.2.17 walk_dir

include std/filesys.e
namespace filesys
public function walk_dir(sequence path_name, object your_function,
        integer scan_subdirs = types :FALSE,
        object dir_source = types :NO_ROUTINE_ID)

Generalized Directory Walker

Parameters:

path_name : a sequence, the name of the directory to walk through
your_function : the routine id of a function that will receive each path returned from the result of dir_source, one at a time.
scan_subdirs : an optional integer, 1 to also walk though subfolders, 0 (the default) to skip them all.
dir_source : an optional integer. A routine_id of a user-defined routine that returns the list of paths to pass to your_function. If omitted, the dir() function is used.

Returns:

An object,

0 on success
W_BAD_PATH: an error occurred
anything else: the custom function returned something to stop walk_dir().

Comments:

This routine will "walk" through a directory named path_name. For each entry in the directory, it will call a function, whose routine_id is your_function. If scan_subdirs is non-zero (TRUE), then the subdirectories in path_name will be walked through recursively in the very same way.

The routine that you supply should accept two sequences, the path name and dir() entry for each file and subdirectory. It should return 0 to keep going, or non-zero to stop walk_dir(). Returning W_BAD_PATH is taken as denoting some error.

This mechanism allows you to write a simple function that handles one file at a time, while walk_dir() handles the process of walking through all the files and subdirectories.

By default, the files and subdirectories will be visited in alphabetical order. To use a different order, use the dir_source to pass the routine_id of your own modified dir function that sorts the directory entries differently.

The path that you supply to walk_dir() must not contain wildcards (* or ?). Only a single directory (and its subdirectories) can be searched at one time.

For non-unix systems, any '/' characters in path_name are replaced with '\'.

All trailing slash and whitespace characters are removed from path_name.

Example 1:

function look_at(sequence path_name, sequence item)
-- this function accepts two sequences as arguments
-- it displays all C/C++ source files and their sizes
    if find('d', item[D_ATTRIBUTES]) then
        return 0 -- Ignore directories
    end if
    if not find(fileext(item[D_NAME]), {"c","h","cpp","hpp","cp"}) then
        return 0 -- ignore non-C/C++ files
    end if
    printf(STDOUT, "%s%s%s: %d\n",
           {path_name, {SLASH}, item[D_NAME], item[D_SIZE]})
    return 0 -- keep going
end function

function mysort(sequence path)
	object d
	
	d = dir(path)
	if atom(d) then
		return d
	end if
	-- Sort in descending file size.
 return sort_columns(d, {-D_SIZE})
end function

exit_code = walk_dir("C:\\MYFILES\\", routine_id("look_at"), TRUE, 
                                                        routine_id("mysort"))

8.5.2.18 create_directory

include std/filesys.e
namespace filesys
public function create_directory(sequence name, integer mode = 448, integer mkparent = 1)

Create a new directory.

Parameters:

name : a sequence, the name of the new directory to create
mode : on Unix systems, permissions for the new directory. Default is 448 (all rights for owner, none for others).
mkparent : If true (default) the parent directories are also created if needed.

Returns:

An integer, 0 on failure, 1 on success.

Comments:

mode is ignored on non-Unix platforms.

Example 1:

if not create_directory("the_new_folder") then
	crash("Filesystem problem - could not create the new folder")
end if

-- This example will also create "myapp/" and "myapp/interface/" 
-- if they don't exist.
if not create_directory("myapp/interface/letters") then
	crash("Filesystem problem - could not create the new folder")
end if

-- This example will NOT create "myapp/" and "myapp/interface/" 
-- if they don't exist.
if not create_directory("myapp/interface/letters",,0) then
	crash("Filesystem problem - could not create the new folder")
end if

8.5.2.19 create_file

include std/filesys.e
namespace filesys
public function create_file(sequence name)

Create a new file.

Parameters:

name : a sequence, the name of the new file to create

Returns:

An integer, 0 on failure, 1 on success.

Comments:

The created file will be empty, that is it has a length of zero.
The created file will not be open when this returns.

Example 1:

if not create_file("the_new_file") then
	crash("Filesystem problem - could not create the new file")
end if

8.5.2.20 delete_file

include std/filesys.e
namespace filesys
public function delete_file(sequence name)

Delete a file.

Parameters:

name : a sequence, the name of the file to delete.

Returns:

An integer, 0 on failure, 1 on success.

8.5.2.21 curdir

include std/filesys.e
namespace filesys
public function curdir(integer drive_id = 0)

Returns the current directory, with a trailing SLASH

Parameters:

drive_id : For non-Unix systems only. This is the Drive letter to to get the current directory of. If omitted, the current drive is used.

Returns:

A sequence, the current directory.

Comment:

Windows maintain a current directory for each disk drive. You would use this routine if you wanted the current directory for a drive that may not be the current drive.

For Unix systems, this is simply ignored because there is only one current directory at any time on Unix.

Note:

This always ensures that the returned value has a trailing SLASH character.

Example 1:

res = curdir('D') -- Find the current directory on the D: drive.
-- res might be "D:\backup\music\"
res = curdir()    -- Find the current directory on the current drive.
-- res might be "C:\myapp\work\"

8.5.2.22 init_curdir

include std/filesys.e
namespace filesys
public function init_curdir()

Returns the original current directory

Parameters:

None.

Returns:

A sequence, the current directory at the time the program started running.

Comment:

You would use this if the program might change the current directory during its processing and you wanted to return to the original directory.

Note:

This always ensures that the returned value has a trailing SLASH character.

Example 1:

res = init_curdir() -- Find the original current directory.

8.5.2.23 clear_directory

include std/filesys.e
namespace filesys
public function clear_directory(sequence path, integer recurse = 1)

Clear (delete) a directory of all files, but retaining sub-directories.

Parameters:

name : a sequence, the name of the directory whose files you want to remove.
recurse : an integer, whether or not to remove files in the directory's sub-directories. If 0 then this function is identical to remove_directory(). If 1, then we recursively delete the directory and its contents. Defaults to 1.

Returns:

An integer, 0 on failure, otherwise the number of files plus 1.

Comment:

This never removes a directory. It only ever removes files. It is used to clear a directory structure of all existing files, leaving the structure intact.

Example 1:

integer cnt = clear_directory("the_old_folder")
if cnt = 0 then
	crash("Filesystem problem - could not remove one or more of the files.")
end if
printf(1, "Number of files removed: %d\n", cnt - 1)

8.5.2.24 remove_directory

include std/filesys.e
namespace filesys
public function remove_directory(sequence dir_name, integer force = 0)

Remove a directory.

Parameters:

name : a sequence, the name of the directory to remove.
force : an integer, if 1 this will also remove files and sub-directories in the directory. The default is 0, which means that it will only remove the directory if it is already empty.

Returns:

An integer, 0 on failure, 1 on success.

Example 1:

if not remove_directory("the_old_folder") then
	crash("Filesystem problem - could not remove the old folder")
end if

8.5.3 File name parsing

8.5.3.1 PATH_DIR

include std/filesys.e
namespace filesys
public enum PATH_DIR

8.5.3.2 PATH_FILENAME

include std/filesys.e
namespace filesys
public enum PATH_FILENAME

8.5.3.3 PATH_BASENAME

include std/filesys.e
namespace filesys
public enum PATH_BASENAME

8.5.3.4 PATH_FILEEXT

include std/filesys.e
namespace filesys
public enum PATH_FILEEXT

8.5.3.5 PATH_DRIVEID

include std/filesys.e
namespace filesys
public enum PATH_DRIVEID

8.5.3.6 pathinfo

include std/filesys.e
namespace filesys
public function pathinfo(sequence path, integer std_slash = 0)

Parse a fully qualified pathname.

Parameters:

path : a sequence, the path to parse

Returns:

A sequence, of length 5. Each of these elements is a string:

The path name
The full unqualified file name
the file name, without extension
the file extension
the drive id

Comments:

The host operating system path separator is used in the parsing.

Example 1:

-- WINDOWS
info = pathinfo("C:\\euphoria\\docs\\readme.txt")
-- info is {"C:\\euphoria\\docs", "readme.txt", "readme", "txt", "C"}

Example 2:

-- Unix variants
info = pathinfo("/opt/euphoria/docs/readme.txt")
-- info is {"/opt/euphoria/docs", "readme.txt", "readme", "txt", ""}

Example 3:

-- no extension
info = pathinfo("/opt/euphoria/docs/readme")
-- info is {"/opt/euphoria/docs", "readme", "readme", "", ""}

8.5.3.7 dirname

include std/filesys.e
namespace filesys
public function dirname(sequence path, integer pcd = 0)

Return the directory name of a fully qualified filename

Parameters:

path : the path from which to extract information
pcd : If not zero and there is no directory name in path then "." is returned. The default (0) will just return any directory name in path.

Returns:

A sequence, the full file name part of path.

Comments:

The host operating system path separator is used.

Example 1:

fname = dirname("/opt/euphoria/docs/readme.txt")
-- fname is "/opt/euphoria/docs"

8.5.3.8 pathname

include std/filesys.e
namespace filesys
public function pathname(sequence path)

Return the directory name of a fully qualified filename

Parameters:

path : the path from which to extract information
pcd : If not zero and there is no directory name in path then "." is returned. The default (0) will just return any directory name in path.

Returns:

A sequence, the full file name part of path.

Comments:

The host operating system path separator is used.

Example 1:

fname = dirname("/opt/euphoria/docs/readme.txt")
-- fname is "/opt/euphoria/docs"

8.5.3.9 filename

include std/filesys.e
namespace filesys
public function filename(sequence path)

Return the file name portion of a fully qualified filename

Parameters:

path : the path from which to extract information

Returns:

A sequence, the file name part of path.

Comments:

The host operating system path separator is used.

Example 1:

fname = filename("/opt/euphoria/docs/readme.txt")
-- fname is "readme.txt"

8.5.3.10 filebase

include std/filesys.e
namespace filesys
public function filebase(sequence path)

Return the base filename of path.

Parameters:

path : the path from which to extract information

Returns:

A sequence, the base file name part of path.

TODO: Test

Example 1:

base = filebase("/opt/euphoria/readme.txt")
-- base is "readme"

8.5.3.11 fileext

include std/filesys.e
namespace filesys
public function fileext(sequence path)

Return the file extension of a fully qualified filename

Parameters:

path : the path from which to extract information

Returns:

A sequence, the file extension part of path.

Comments:

The host operating system path separator is used.

Example 1:

fname = fileext("/opt/euphoria/docs/readme.txt")
-- fname is "txt"

8.5.3.12 driveid

include std/filesys.e
namespace filesys
public function driveid(sequence path)

Return the drive letter of the path on WINDOWS platforms.

Parameters:

path : the path from which to extract information

Returns:

A sequence, the file extension part of path.

TODO: Test

Example:

letter = driveid("C:\\EUPHORIA\\Readme.txt")
-- letter is "C"

8.5.3.13 defaultext

include std/filesys.e
namespace filesys
public function defaultext(sequence path, sequence defext)

Returns the supplied filepath with the supplied extension, if the filepath does not have an extension already.

Parameters:

path : the path to check for an extension.
defext : the extension to add if path does not have one.

Returns:

A sequence, the path with an extension.

Example:

-- ensure that the supplied path has an extension,
 -- but if it doesn't use "tmp".
theFile = defaultext(UserFileName, "tmp")

8.5.3.14 absolute_path

include std/filesys.e
namespace filesys
public function absolute_path(sequence filename)

Determine if the supplied string is an absolute path or a relative path.

Parameters:

filename : a sequence, the name of the file path

Returns:

An integer, 0 if filename is a relative path or 1 otherwise.

Comment:

A relative path is one which is relative to the current directory and an absolute path is one that doesn't need to know the current directory to find the file.

Example 1:

? absolute_path("") -- returns 0
? absolute_path("/usr/bin/abc") -- returns 1
? absolute_path("\\temp\\somefile.doc") -- returns 1
? absolute_path("../abc") -- returns 0
? absolute_path("local/abc.txt") -- returns 0
? absolute_path("abc.txt") -- returns 0
? absolute_path("c:..\\abc") -- returns 0

-- The next two examples return 
-- 0 on Unix platforms and 
-- 1 on Microsoft platforms
? absolute_path("c:\\windows\\system32\\abc")
? absolute_path("c:/windows/system32/abc")

8.5.3.15 AS_IS

include std/filesys.e
namespace filesys
public enum AS_IS

8.5.3.16 TO_LOWER

include std/filesys.e
namespace filesys
public enum TO_LOWER

8.5.3.17 CORRECT

include std/filesys.e
namespace filesys
public enum CORRECT

8.5.3.18 TO_SHORT

include std/filesys.e
namespace filesys
public enum TO_SHORT

8.5.3.19 case_flagset_type

include std/filesys.e
namespace filesys
public type case_flagset_type(integer x)

8.5.3.20 canonical_path

include std/filesys.e
namespace filesys
public function canonical_path(sequence path_in, integer directory_given = 0,
        case_flagset_type case_flags = AS_IS)

Returns the full path and file name of the supplied file name.

Parameters:

path_in : A sequence. This is the file name whose full path you want.
directory_given : An integer. This is zero if path_in is to be interpreted as a file specification otherwise it is assumed to be a directory specification. The default is zero.
case_flags : An integer. This is a combination of flags. AS_IS = Includes no flags TO_LOWER = If passed will convert the part of the path not affected by other case flags to lowercase. CORRECT = If passed will correct the parts of the filepath that exist in the current filesystem in parts of the filesystem that is case insensitive. This should work on WINDOWS or SMB mounted volumes on UNIX and all Mac OS filesystems.

TO_LOWER = If passed alone the entire path is converted to lowercase. or_bits(TO_LOWER,CORRECT) = If these flags are passed together the the part that exists has the case of that of the filesystem. The part that doesn't is converted to lower case. TO_SHORT = If passed the elements of the path that exist are also converted to their WINDOWS short names if avaliable.

Returns:

A sequence, the full path and file name.

Comment:

The supplied file/directory does not have to actually exist.
path_in can be enclosed in quotes, which will be stripped off.
If path_in begins with a tilde '~' then that is replaced by the contents of $HOME in unix platforms and %HOMEDRIVE%%HOMEPATH% in Windows.
In Windows, all '/' characters are replaced by '\' characters.
Does not (yet) handle UNC paths or unix links.

Example 1:

-- Assuming the current directory is "/usr/foo/bar"
res = canonical_path("../abc.def")
-- res is now "/usr/foo/abc.def"

Example 2:

-- res is "C:\Program Files" on systems that have that directory.
res = canonical_path(
-- on Windows Vista this would be "c:\Program Files" for Vista uses lowercase for its drives.

8.5.3.21 abbreviate_path

include std/filesys.e
namespace filesys
public function abbreviate_path(sequence orig_path, sequence base_paths = {})

Returns a path string to the supplied file which is shorter than the given path string.

Parameters:

orig_path : A sequence. This is the path to a file.
base_paths : A sequence. This is an optional list of paths that may prefix the original path. The default is an empty list.

Returns:

A sequence, an equivalent path to orig_path which is shorter than the supplied path. If a shorter one cannot be formed, then the original path is returned.

Comment:

This function is primarily used to get the shortest form of a file path for output to a file or screen.
It works by first trying to find if the orig_path begins with any of the base_paths. If so it returns the parameter minus the base path prefix.
Next it checks if the orig_path begins with the current directory path. If so it returns the parameter minus the current directory path.
Next it checks if it can form a relative path from the current directory to the supplied file which is shorter than the parameter string.
Failing all of that, it returns the original parameter.
In Windows, the shorter result has all '/' characters are replaced by '\' characters.
The supplied path does not have to actually exist.
orig_path can be enclosed in quotes, which will be stripped off.
If orig_path begins with a tilde '~' then that is replaced by the contents of $HOME in unix platforms and %HOMEDRIVE%%HOMEPATH% in Windows.

Example 1:

-- Assuming the current directory is "/usr/foo/bar"
res = abbreviate_path("/usr/foo/abc.def")
-- res is now "../abc.def"
res = abbreviate_path("/usr/foo/bar/inc/abc.def")
-- res is now "inc/abc.def"
res = abbreviate_path("abc.def", {"/usr/foo"})
-- res is now "bar/abc.def"

8.5.3.22 split_path

include std/filesys.e
namespace filesys
public function split_path(sequence fname)

Split a filename into path segments

Parameters:

fname - Filename to split

Returns:

A sequence of strings representing each path element found in fname.

Example 1:

sequence path_elements = split_path("/usr/home/john/hello.txt")
-- path_elements would be { "usr", "home", "john", "hello.txt" }

Versioning:

Added in 4.0.1

8.5.3.23 join_path

include std/filesys.e
namespace filesys
public function join_path(sequence path_elements)

Join multiple path segments into a single path/filename

Parameters:

path_elements - Sequence of path elements

Returns:

A string representing the path elements on the given platform

Example 1:

sequence fname = join_path({ "usr", "home", "john", "hello.txt" })
-- fname would be "/usr/home/john/hello.txt" on Unix
-- fname would be "\\usr\\home\\john\\hello.txt" on Windows

Versioning:

Added in 4.0.1

8.5.4 File Types

8.5.4.1 FILETYPE_UNDEFINED

include std/filesys.e
namespace filesys
public enum FILETYPE_UNDEFINED

8.5.4.2 FILETYPE_NOT_FOUND

include std/filesys.e
namespace filesys
public enum FILETYPE_NOT_FOUND

8.5.4.3 FILETYPE_FILE

include std/filesys.e
namespace filesys
public enum FILETYPE_FILE

8.5.4.4 FILETYPE_DIRECTORY

include std/filesys.e
namespace filesys
public enum FILETYPE_DIRECTORY

8.5.4.5 file_type

include std/filesys.e
namespace filesys
public function file_type(sequence filename)

Get the type of a file.

Parameters:

filename : the name of the file to query. It must not have wildcards.

Returns:

An integer,

-1 if file could be multiply defined
0 if filename does not exist
1 if filename is a file
2 if filename is a directory

8.5.5 File Handling

8.5.5.1 SECTORS_PER_CLUSTER

include std/filesys.e
namespace filesys
public enum SECTORS_PER_CLUSTER

8.5.5.2 BYTES_PER_SECTOR

include std/filesys.e
namespace filesys
public enum BYTES_PER_SECTOR

8.5.5.3 NUMBER_OF_FREE_CLUSTERS

include std/filesys.e
namespace filesys
public enum NUMBER_OF_FREE_CLUSTERS

8.5.5.4 TOTAL_NUMBER_OF_CLUSTERS

include std/filesys.e
namespace filesys
public enum TOTAL_NUMBER_OF_CLUSTERS

8.5.5.5 TOTAL_BYTES

include std/filesys.e
namespace filesys
public enum TOTAL_BYTES

8.5.5.6 FREE_BYTES

include std/filesys.e
namespace filesys
public enum FREE_BYTES

8.5.5.7 USED_BYTES

include std/filesys.e
namespace filesys
public enum USED_BYTES

8.5.5.8 COUNT_DIRS

include std/filesys.e
namespace filesys
public enum COUNT_DIRS

8.5.5.9 COUNT_FILES

include std/filesys.e
namespace filesys
public enum COUNT_FILES

8.5.5.10 COUNT_SIZE

include std/filesys.e
namespace filesys
public enum COUNT_SIZE

8.5.5.11 COUNT_TYPES

include std/filesys.e
namespace filesys
public enum COUNT_TYPES

8.5.5.12 EXT_NAME

include std/filesys.e
namespace filesys
public enum EXT_NAME

8.5.5.13 EXT_COUNT

include std/filesys.e
namespace filesys
public enum EXT_COUNT

8.5.5.14 EXT_SIZE

include std/filesys.e
namespace filesys
public enum EXT_SIZE

8.5.5.15 file_exists

include std/filesys.e
namespace filesys
public function file_exists(object name)

Check to see if a file exists

Parameters:

name : filename to check existence of

Returns:

An integer, 1 on yes, 0 on no

Example 1:

if file_exists("abc.e") then
    puts(1, "abc.e exists already\n")
end if

8.5.5.16 file_timestamp

include std/filesys.e
namespace filesys
public function file_timestamp(sequence fname)

Get the timestamp of the file

Parameters:

name : the filename to get the date of

Returns:

A valid datetime type, representing the files date and time or -1 if the file's date and time could not be read.

8.5.5.17 copy_file

include std/filesys.e
namespace filesys
public function copy_file(sequence src, sequence dest, integer overwrite = 0)

Copy a file.

Parameters:

src : a sequence, the name of the file or directory to copy
dest : a sequence, the new name or location of the file
overwrite : an integer; 0 (the default) will prevent an existing destination file from being overwritten. Non-zero will overwrite the destination file.

Returns:

An integer, 0 on failure, 1 on success.

Comments:

If overwrite is true, and if dest file already exists, the function overwrites the existing file and succeeds.

8.5.5.18 rename_file

include std/filesys.e
namespace filesys
public function rename_file(sequence old_name, sequence new_name, integer overwrite = 0)

Rename a file.

Parameters:

old_name : a sequence, the name of the file or directory to rename.
new_name : a sequence, the new name for the renamed file
overwrite : an integer, 0 (the default) to prevent renaming if destination file exists, 1 to delete existing destination file first

Returns:

An integer, 0 on failure, 1 on success.

Comments:

If new_name contains a path specification, this is equivalent to moving the file, as well as possibly changing its name. However, the path must be on the same drive for this to work.
If overwrite was requested but the rename fails, any existing destination file is preserved.

8.5.5.19 move_file

include std/filesys.e
namespace filesys
public function move_file(sequence src, sequence dest, integer overwrite = 0)

Move a file to another location.

Parameters:

src : a sequence, the name of the file or directory to move
dest : a sequence, the new location for the file
overwrite : an integer, 0 (the default) to prevent overwriting an existing destination file, 1 to overwrite existing destination file

Returns:

An integer, 0 on failure, 1 on success.

Comments:

If overwrite was requested but the move fails, any existing destination file is preserved.

8.5.5.20 file_length

include std/filesys.e
namespace filesys
public function file_length(sequence filename)

Return the size of a file.

Parameters:

filename : the name of the queried file

Returns:

An atom, the file size, or -1 if file is not found.

Comments:

This function does not compute the total size for a directory, and returns 0 instead.

8.5.5.21 locate_file

include std/filesys.e
namespace filesys
public function locate_file(sequence filename, sequence search_list = {},
        sequence subdir = {})

Locates a file by looking in a set of directories for it.

Parameters:

filename : a sequence, the name of the file to search for.
search_list : a sequence, the list of directories to look in. By default this is "", meaning that a predefined set of directories is scanned. See comments below.
subdir : a sequence, the sub directory within the search directories to check. This is optional.

Returns:

A sequence, the located file path if found, else the original file name.

Comments:

If filename is an absolute path, it is just returned and no searching takes place.

If filename is located, the full path of the file is returned.

If search_list is supplied, it can be either a sequence of directory names, of a string of directory names delimited by ':' in UNIX and ';' in Windows.

If the search_list is omitted or "", this will look in the following places...

The current directory
The directory that the program is run from.
The directory in $HOME ($HOMEDRIVE & $HOMEPATH in Windows)
The parent directory of the current directory
The directories returned by include_paths()
$EUDIR/bin
$EUDIR/docs
$EUDIST/
$EUDIST/etc
$EUDIST/data
The directories listed in $USERPATH
The directories listed in $PATH

If the subdir is supplied, the function looks in this sub directory for each of the directories in the search list.

Example 1:

res = locate_file("abc.def", {"/usr/bin", "/u2/someapp", "/etc"})
 res = locate_file("abc.def", "/usr/bin:/u2/someapp:/etc")
 res = locate_file("abc.def") 
       -- Scan default locations.
 res = locate_file("abc.def", , "app") 
       -- Scan the 'app' sub directory in the default locations.

8.5.5.22 disk_metrics

include std/filesys.e
namespace filesys
public function disk_metrics(object disk_path)

Returns some information about a disk drive.

Parameters:

disk_path : A sequence. This is the path that identifies the disk to inquire upon.

Returns:

A sequence, containing SECTORS_PER_CLUSTER, BYTES_PER_SECTOR, NUMBER_OF_FREE_CLUSTERS, and TOTAL_NUMBER_OF_CLUSTERS

Example 1:

res = disk_metrics("C:\\")
min_file_size = res[SECTORS_PER_CLUSTER] * res[BYTES_PER_SECTOR]

8.5.5.23 disk_size

include std/filesys.e
namespace filesys
public function disk_size(object disk_path)

Returns the amount of space for a disk drive.

Parameters:

disk_path : A sequence. This is the path that identifies the disk to inquire upon.

Returns:

A sequence, containing TOTAL_BYTES, USED_BYTES, FREE_BYTES, and a string which represents the filesystem name

Example 1:

res = disk_size("C:\\")
printf(1, "Drive %s has %3.2f%% free space\n", { 
    "C:", res[FREE_BYTES] / res[TOTAL_BYTES]
})

8.5.5.24 dir_size

include std/filesys.e
namespace filesys
public function dir_size(sequence dir_path, integer count_all = 0)

Returns the amount of space used by a directory.

Parameters:

dir_path : A sequence. This is the path that identifies the directory to inquire upon.
count_all : An integer. Used by Windows systems. If zero (the default) it will not include system or hidden files in the count, otherwise they are included.

Returns:

A sequence, containing four elements; the number of sub-directories [COUNT_DIRS], the number of files [COUNT_FILES], the total space used by the directory [COUNT_SIZE], and breakdown of the file contents by file extension [COUNT_TYPES].

Comments:

The total space used by the directory does not include space used by any sub-directories.
The file breakdown is a sequence of three-element sub-sequences. Each sub-sequence contains the extension [EXT_NAME], the number of files of this extension [EXT_COUNT], and the space used by these files [EXT_SIZE]. The sub-sequences are presented in extension name order. On Windows the extensions are all in lowercase.

Example 1:

res = dir_size("/usr/localbin")
printf(1, "Directory %s contains %d files\n", {
        "/usr/localbin", res[COUNT_FILES]
    })
for i = 1 to length(res[COUNT_TYPES]) do
    printf(1, "Type: %s (%d files %d bytes)\n", {
        res[COUNT_TYPES][i][EXT_NAME],
        res[COUNT_TYPES][i][EXT_COUNT],
        res[COUNT_TYPES][i][EXT_SIZE]
    })
end for

8.5.5.25 temp_file

include std/filesys.e
namespace filesys
public function temp_file(sequence temp_location = "", sequence temp_prefix = "",
        sequence temp_extn = "_T_", integer reserve_temp = 0)

Returns a file name that can be used as a temporary file.

Parameters:

temp_location : A sequence. A directory where the temporary file is expected to be created.
- If omitted (the default) the 'temporary' directory will be used. The temporary directory is defined in the "TEMP" environment symbol, or failing that the "TMP" symbol and failing that "C:\TEMP\" is used in non-Unix systems and "/tmp/" is used in Unix systems.
- If temp_location was supplied,
  - If it is an existing file, that file's directory is used.
  - If it is an existing directory, it is used.
  - If it doesn't exist, the directory name portion is used.
temp_prefix : A sequence: The is prepended to the start of the generated file name. The default is "".
temp_extn : A sequence: The is a file extention used in the generated file. The default is "_T_".
reserve_temp : An integer: If not zero an empty file is created using the generated name. The default is not to reserve (create) the file.

Returns:

A sequence, A generated file name.

Example 1:

temp_file("/usr/space", "myapp", "tmp") --> /usr/space/myapp736321.tmp
temp_file() --> /tmp/277382._T_
temp_file("/users/me/abc.exw") --> /users/me/992831._T_

8.5.5.26 checksum

include std/filesys.e
namespace filesys
public function checksum(sequence filename, integer size = 4, integer usename = 0,
        integer return_text = 0)

Returns a checksum value for the specified file.

Parameters:

filename : A sequence. The name of the file whose checksum you want.
size : An integer. The number of atoms to return. Default is 4
usename: An integer. If not zero then the actual text of filename will affect the resulting checksum. The default (0) will not use the name of the file.
return_text: An integer. If not zero, the check sum is returned as a text string of hexadecimal digits otherwise (the default) the check sum is returned as a sequence of size atoms.

Returns:

A sequence containing size atoms.

Comments:

The larger the size value, the more unique will the checksum be. For most files and uses, a single atom will be sufficient as this gives a 32-bit file signature. However, if you require better proof that the content of two files are different then use higher values for size. For example, size = 8 gives you 256 bits of file signature.
If size is zero or negative, an empty sequence is returned.
All files of zero length will return the same checksum value when usename is zero.

Example 1:

-- Example values. The exact values depend on the contents of the file.
 include std/console.e
 display( checksum("myfile", 1) ) --> {92837498}
 display( checksum("myfile", 2) ) --> {1238176, 87192873}
 display( checksum("myfile", 2,,1)) --> "0012E480 05327529"
 display( checksum("myfile", 4) ) --> {23448, 239807, 79283749, 427370}
 display( checksum("myfile") )    --> {23448, 239807, 79283749, 427370} -- default

	Up					TOC	Index
<< 7 Included Tools			< 8.4 Date/Time	Up: 8 API Reference	8.6 I/O >	9 Release Notes >>

OpenEuphoria

Euphoria v4.0

8.5 File System

8.5.1 Constants

8.5.1.1 SLASH

Comments:

8.5.1.2 SLASHES

8.5.1.3 EOLSEP

8.5.1.4 EOL

8.5.1.5 PATHSEP

8.5.1.6 NULLDEVICE

8.5.1.7 SHARED_LIB_EXT

8.5.2 Directory Handling

8.5.2.1 D_NAME

8.5.2.2 D_ATTRIBUTES

8.5.2.3 D_SIZE

8.5.2.4 D_YEAR

8.5.2.5 D_MONTH

8.5.2.6 D_DAY

8.5.2.7 D_HOUR

8.5.2.8 D_MINUTE

8.5.2.9 D_SECOND

8.5.2.10 D_MILLISECOND

8.5.2.11 D_ALTNAME

8.5.2.12 W_BAD_PATH

8.5.2.13 dir

Parameters:

Returns:

Errors:

Comments:

You can refer to the elements of an entry with the following constants:

The attributes element is a string sequence containing characters chosen from:

Example 1:

See Also:

8.5.2.14 current_dir

Returns:

Comments:

Example 1:

See Also:

8.5.2.15 chdir

Parameters:

Returns:

Comments:

Example 1:

See Also:

8.5.2.16 my_dir

8.5.2.17 walk_dir

Parameters:

Returns:

Comments:

Example 1:

See Also:

8.5.2.18 create_directory

Parameters:

Returns:

Comments:

Example 1:

See Also:

8.5.2.19 create_file

Parameters:

Returns:

Comments:

Example 1:

See Also:

8.5.2.20 delete_file

Parameters:

Returns:

8.5.2.21 curdir

Parameters:

Returns:

Comment:

Note:

Example 1:

8.5.2.22 init_curdir

Parameters:

Returns:

Comment:

Note:

Example 1:

8.5.2.23 clear_directory