OpenEuphoria: Euphoria v4.1

# OpenEuphoria Manual

## Euphoria v4.1

routine or constant name search

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

## 8.5 File System

Cross platform file operations for Euphoria

### 8.5.1 Constants

#### 8.5.1.1 SLASH

    public constant SLASH

Current platform's path separator character

##### Comments:

When on Windows, `'\\'`. When on Unix, `'/'`.

#### 8.5.1.2 SLASHES

    public constant SLASHES

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

    public constant W_BAD_PATH

Bad path error code. See walk_dir

#### 8.5.2.13 W_SKIP_DIRECTORY

    public constant W_SKIP_DIRECTORY

#### 8.5.2.14 dir

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

returns directory information for the specified file or directory.

##### Parameters:

1. `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 (that is 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 ( therefore 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"

##### See Also:

walk_dir

#### 8.5.2.15 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 (such as `C:\`).

##### Example 1:

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

##### See Also:

dir, chdir

#### 8.5.2.16 chdir

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

sets 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 will not 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

##### See Also:

current_dir, dir

#### 8.5.2.17 my_dir

    include std/filesys.e
    namespace filesys
    public integer my_dir

Deprecated, so therefore not documented.

#### 8.5.2.18 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:

1. `path_name` : a sequence, the name of the directory to walk through
2. `your_function` : the routine id of a function that will receive each path returned from the result of `dir_source`, one at a time. Optionally, to include extra data for your function, `your_function` can be a 2 element sequence, with the routine_id as the first element and other data as the second element.
3. `scan_subdirs` : an optional integer, `1` to also walk though subfolders, `0` (the default) to skip them all.
4. `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. If your routine requires an extra parameter, `dir_source` may be a 2 element sequence where the first element is the routine id and the second is the extra data to be passed as the second parameter to your function.

##### 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, `W_SKIP_DIRECTORY` to avoid scan the contents of the supplied path name (if a directory), 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 Windows 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
            -- Ignore directories
            if find('s', item[D_ATTRIBUTES]) then
               return W_SKIP_DIRECTORY -- Don't recurse a system directory
            else
               return 0 -- Keep processing as normal
            end if
        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"))

##### See Also:

dir, sort, sort_columns

#### 8.5.2.19 create_directory

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

creates a new directory.

##### Parameters:

1. `name` : a sequence, the name of the new directory to create
2. `mode` : on Unix systems, permissions for the new directory. Default is `448` (all rights for owner, none for others).
3. `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 Windows 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

##### See Also:

remove_directory, chdir

#### 8.5.2.20 create_file

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

Create a new file.

##### Parameters:

1. `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

##### See Also:

create_directory

#### 8.5.2.21 delete_file

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

deletes a file.

##### Parameters:

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

##### Returns:

An integer, `0` on failure, `1` on success.

#### 8.5.2.22 curdir

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

Returns the current directory, with a trailing SLASH

##### Parameters:

1. `drive_id` : For Windows 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.

##### Comments:

Windows maintains 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.23 init_curdir

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

returns the original current directory.

##### Parameters:

1. None.

##### Returns:

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

##### Comments:

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.24 clear_directory

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

clears (deletes) a directory of all files, but retaining sub-directories.

##### Parameters:

1. `name` : a sequence, the name of the directory whose files you want to remove.
2. `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` .

##### Comments:

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)

##### See Also:

remove_directory, delete_file

#### 8.5.2.25 remove_directory

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

removes a directory.

##### Parameters:

1. `name` : a sequence, the name of the directory to remove.
2. `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

##### See Also:

create_directory, chdir, clear_directory

### 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)

parses a fully qualified pathname.

##### Parameters:

1. `path` : a sequence, the path to parse

##### Returns:

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

- The path name. For Windows this excludes the drive id.
- 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", "", ""}

##### See Also:

driveid, dirname, filename, fileext, PATH_BASENAME, PATH_DIR, PATH_DRIVEID, PATH_FILEEXT, PATH_FILENAME

#### 8.5.3.7 dirname

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

returns the directory name of a fully qualified filename.

##### Parameters:

1. `path` : the path from which to extract information
2. `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"

##### See Also:

driveid, filename, pathinfo

#### 8.5.3.8 pathname

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

returns the directory name of a fully qualified filename.

##### Parameters:

1. `path` : the path from which to extract information
2. `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"

##### See Also:

driveid, filename, pathinfo

#### 8.5.3.9 filename

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

returns the file name portion of a fully qualified filename.

##### Parameters:

1. `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"

##### See Also:

pathinfo, filebase, fileext

#### 8.5.3.10 filebase

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

returns the base filename of path.

##### Parameters:

1. `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"

##### See Also:

pathinfo, filename, fileext

#### 8.5.3.11 fileext

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

returns the file extension of a fully qualified filename.

##### Parameters:

1. `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"

##### See Also:

pathinfo, filename, filebase

#### 8.5.3.12 driveid

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

returns the drive letter of the path on Windows platforms.

##### Parameters:

1. `path` : the path from which to extract information

##### Returns:

A sequence, the file extension part of `path`.

TODO: Test

##### Example 1:

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

##### See Also:

pathinfo, dirname, filename

#### 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:

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

##### Returns:

A sequence, the path with an extension.

##### Example 1:

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

##### See Also:

pathinfo

#### 8.5.3.14 absolute_path

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

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

##### Parameters:

1. `filename` : a sequence, the name of the file path

##### Returns:

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

##### Comments:

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:

1. `path_in` : A sequence. This is the file name whose full path you want.
2. `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.
3. `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 OS X 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 does not 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.

##### Comments:

- 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("c:\pRoGrAm FiLeS", CORRECT)
    -- 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:

1. `orig_path` : A sequence. This is the path to a file.
2. `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.

##### Comments:

- 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

##### See Also:

join_path

#### 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

##### See Also:

split_path

### 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)

gets the type of a file.

##### Parameters:

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

##### Returns:

An integer,

- FILETYPE_UNDEFINED (-1) if file could be multiply defined (i.e., contains any wildcards - '*' or '?')
- FILETYPE_NOT_FOUND (0) if filename does not exist
- FILETYPE_FILE (1) if filename is a file
- FILETYPE_DIRECTORY (2) if filename is a directory

##### See Also:

dir, FILETYPE_DIRECTORY, FILETYPE_FILE, FILETYPE_NOT_FOUND, FILETYPE_UNDEFINED

### 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)

checks to see if a file exists.

##### Parameters:

1. `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)

gets the timestamp of the file.

##### Parameters:

1. `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)

copies a file.

##### Parameters:

1. `src` : a sequence, the name of the file or directory to copy
2. `dest` : a sequence, the new name or location of the file
3. `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.

##### See Also:

move_file, rename_file

#### 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:

1. `old_name` : a sequence, the name of the file or directory to rename.
2. `new_name` : a sequence, the new name for the renamed file
3. `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.

##### See Also:

move_file, copy_file

#### 8.5.5.19 move_file

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

moves a file to another location.

##### Parameters:

1. `src` : a sequence, the name of the file or directory to move
2. `dest` : a sequence, the new location for the file
3. `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.

##### See Also:

rename_file, copy_file

#### 8.5.5.20 file_length

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

returns the size of a file.

##### Parameters:

1. `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.

##### See Also:

dir

#### 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:

1. `filename` : a sequence, the name of the file to search for.
2. `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.
3. `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:

1. `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:

1. `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:

1. `dir_path` : A sequence. This is the path that identifies the directory to inquire upon.
2. `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:

1. `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 on Windows systems and "/tmp/" is used on 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.
2. `temp_prefix` : A sequence: The is prepended to the start of the generated file name. The default is `""` .
3. `temp_extn` : A sequence: The is a file extention used in the generated file. The default is `"_T_"` .
4. `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:

1. `filename` : A sequence. The name of the file whose checksum you want.
2. `size` : An integer. The number of atoms to return. Default is 4
3. `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.
4. `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 and Time | Up: 8 API Reference | 8.6 I/O > | 9 Release Notes >>