36.2 Filesystem Utilities

Octave includes many utility functions for copying, moving, renaming, and deleting files; for creating, reading, and deleting directories; for retrieving status information on files; and for manipulating file and path names.

Function File: movefile (f1)

Function File: movefile (f1, f2)

Function File: movefile (f1, f2, 'f')

Function File: [status, msg, msgid] = movefile (…)

Move the source files or directories f1 to the destination f2.

The name f1 may contain globbing patterns. If f1 expands to multiple file names, f2 must be a directory. If no destination f2 is specified then the destination is the present working directory. If f2 is a file name then f1 is renamed to f2.

When the force flag 'f' is given any existing files will be overwritten without prompting.

If successful, status is 1, and msg, msgid are empty character strings (""). Otherwise, status is 0, msg contains a system-dependent error message, and msgid contains a unique message identifier. Note that the status code is exactly opposite that of the system command.

See also: rename, copyfile, unlink, delete, glob.

Built-in Function: rename old new

Built-in Function: [err, msg] = rename (old, new)

Change the name of file old to new.

If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: movefile, copyfile, ls, dir.

Function File: [status, msg, msgid] = copyfile (f1, f2)

Function File: [status, msg, msgid] = copyfile (f1, f2, 'f')

Copy the source files or directories f1 to the destination f2.

The name f1 may contain globbing patterns. If f1 expands to multiple file names, f2 must be a directory.

When the force flag 'f' is given any existing files will be overwritten without prompting.

If successful, status is 1, and msg, msgid are empty character strings (""). Otherwise, status is 0, msg contains a system-dependent error message, and msgid contains a unique message identifier. Note that the status code is exactly opposite that of the system command.

See also: movefile, rename, unlink, delete, glob.

Built-in Function: [err, msg] = unlink (file)

Delete the file named file.

If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: delete, rmdir.

Built-in Function: link old new

Built-in Function: [err, msg] = link (old, new)

Create a new link (also known as a hard link) to an existing file.

If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: symlink, unlink, readlink, lstat.

Built-in Function: symlink old new

Built-in Function: [err, msg] = symlink (old, new)

Create a symbolic link new which contains the string old.

If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: link, unlink, readlink, lstat.

Built-in Function: readlink symlink

Built-in Function: [result, err, msg] = readlink (symlink)

Read the value of the symbolic link symlink.

If successful, result contains the contents of the symbolic link symlink, err is 0, and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: lstat, symlink, link, unlink, delete.

Built-in Function: mkdir dir

Built-in Function: mkdir (parent, dir)

Built-in Function: [status, msg, msgid] = mkdir (…)

Create a directory named dir in the directory parent.

If no parent directory is specified the present working directory is used.

If successful, status is 1, and msg, msgid are empty character strings (""). Otherwise, status is 0, msg contains a system-dependent error message, and msgid contains a unique message identifier.

When creating a directory permissions will be set to 0777 - umask.

See also: rmdir, pwd, cd, umask.

Built-in Function: rmdir dir

Built-in Function: rmdir (dir, "s")

Built-in Function: [status, msg, msgid] = rmdir (…)

Remove the directory named dir.

If the optional second parameter is supplied with value "s", recursively remove all subdirectories as well.

If successful, status is 1, and msg, msgid are empty character strings (""). Otherwise, status is 0, msg contains a system-dependent error message, and msgid contains a unique message identifier.

See also: mkdir, confirm_recursive_rmdir, pwd.

Built-in Function: val = confirm_recursive_rmdir ()

Built-in Function: old_val = confirm_recursive_rmdir (new_val)

Built-in Function: confirm_recursive_rmdir (new_val, "local")

Query or set the internal variable that controls whether Octave will ask for confirmation before recursively removing a directory tree.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

See also: rmdir.

Built-in Function: err = mkfifo (name, mode)

Built-in Function: [err, msg] = mkfifo (name, mode)

Create a FIFO special file named name with file mode mode.

mode is interpreted as a decimal number (not octal) and is subject to umask processing. The final calculated mode is mode - umask.

If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: pipe, umask.

Built-in Function: umask (mask)

Set the permission mask for file creation.

The parameter mask is an integer, interpreted as an octal number.

If successful, returns the previous value of the mask (as an integer to be interpreted as an octal number); otherwise an error message is printed.

The permission mask is a UNIX concept used when creating new objects on a file system such as files, directories, or named FIFOs. The object to be created has base permissions in an octal number mode which are modified according to the octal value of mask. The final permissions for the new object are mode - mask.

See also: fopen, mkdir, mkfifo.

Built-in Function: [info, err, msg] = stat (file)

Built-in Function: [info, err, msg] = stat (fid)

Built-in Function: [info, err, msg] = lstat (file)

Built-in Function: [info, err, msg] = lstat (fid)

Return a structure info containing the following information about file or file identifier fid.

dev

ID of device containing a directory entry for this file.

ino

File number of the file.

mode

File mode, as an integer. Use the functions S_ISREG, S_ISDIR, S_ISCHR, S_ISBLK, S_ISFIFO, S_ISLNK, or S_ISSOCK to extract information from this value.

modestr

File mode, as a string of ten letters or dashes as would be returned by ls -l.

nlink

Number of links.

uid

User ID of file’s owner.

gid

Group ID of file’s group.

rdev

ID of device for block or character special files.

size

Size in bytes.

atime

Time of last access in the same form as time values returned from time. See Timing Utilities.

mtime

Time of last modification in the same form as time values returned from time. See Timing Utilities.

ctime

Time of last file status change in the same form as time values returned from time. See Timing Utilities.

blksize

Size of blocks in the file.

blocks

Number of blocks allocated for file.

If the call is successful err is 0 and msg is an empty string. If the file does not exist, or some other error occurs, info is an empty matrix, err is -1, and msg contains the corresponding system error message.

If file is a symbolic link, stat will return information about the actual file that is referenced by the link. Use lstat if you want information about the symbolic link itself.

For example:

[info, err, msg] = stat ("/vmlinuz")
  ⇒ info =
     {
       atime = 855399756
       rdev = 0
       ctime = 847219094
       uid = 0
       size = 389218
       blksize = 4096
       mtime = 847219094
       gid = 6
       nlink = 1
       blocks = 768
       mode = -rw-r--r--
       modestr = -rw-r--r--
       ino = 9316
       dev = 2049
     }
  ⇒ err = 0
  ⇒ msg =

See also: lstat, ls, dir.

Built-in Function: S_ISBLK (mode)

Return true if mode corresponds to a block device.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISCHR (mode)

Return true if mode corresponds to a character device.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISDIR (mode)

Return true if mode corresponds to a directory.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISFIFO (mode)

Return true if mode corresponds to a fifo.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISLNK (mode)

Return true if mode corresponds to a symbolic link.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISREG (mode)

Return true if mode corresponds to a regular file.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Built-in Function: S_ISSOCK (mode)

Return true if mode corresponds to a socket.

The value of mode is assumed to be returned from a call to stat.

See also: stat, lstat.

Function File: [status, result, msgid] = fileattrib (file)

Return information about file.

If successful, status is 1, with result containing a structure with the following fields:

Name

Full name of file.

archive

True if file is an archive (Windows).

system

True if file is a system file (Windows).

hidden

True if file is a hidden file (Windows).

directory

True if file is a directory.

UserRead

GroupRead

OtherRead

True if the user (group; other users) has read permission for file.

UserWrite

GroupWrite

OtherWrite

True if the user (group; other users) has write permission for file.

UserExecute

GroupExecute

OtherExecute

True if the user (group; other users) has execute permission for file.

If an attribute does not apply (i.e., archive on a Unix system) then the field is set to NaN.

With no input arguments, return information about the current directory.

If file contains globbing characters, return information about all the matching files.

See also: glob.

Function File: isdir (f)

Return true if f is a directory.

See also: exist, stat, is_absolute_filename, is_rooted_relative_filename.

Built-in Function: files = readdir (dir)

Built-in Function: [files, err, msg] = readdir (dir)

Return the names of files in the directory dir as a cell array of strings.

If an error occurs, return an empty cell array in files. If successful, err is 0 and msg is an empty string. Otherwise, err is nonzero and msg contains a system-dependent error message.

See also: ls, dir, glob, what.

Built-in Function: glob (pattern)

Given an array of pattern strings (as a char array or a cell array) in pattern, return a cell array of file names that match any of them, or an empty cell array if no patterns match.

The pattern strings are interpreted as filename globbing patterns (as they are used by Unix shells).

Within a pattern

*

matches any string, including the null string,

?

matches any single character, and

[…]

matches any of the enclosed characters.

Tilde expansion is performed on each of the patterns before looking for matching file names. For example:

ls
   ⇒
      file1  file2  file3  myfile1 myfile1b
glob ("*file1")
   ⇒
      {
        [1,1] = file1
        [2,1] = myfile1
      }
glob ("myfile?")
   ⇒
      {
        [1,1] = myfile1
      }
glob ("file[12]")
   ⇒
      {
        [1,1] = file1
        [2,1] = file2
      }

See also: ls, dir, readdir, what.

Built-in Function: file_in_path (path, file)

Built-in Function: file_in_path (path, file, "all")

Return the absolute name of file if it can be found in path.

The value of path should be a colon-separated list of directories in the format described for path. If no file is found, return an empty character string. For example:

file_in_path (EXEC_PATH, "sh")
     ⇒ "/bin/sh"

If the second argument is a cell array of strings, search each directory of the path for element of the cell array and return the first that matches.

If the third optional argument "all" is supplied, return a cell array containing the list of all files that have the same name in the path. If no files are found, return an empty cell array.

See also: file_in_loadpath, dir_in_loadpath, path.

Built-in Function: filesep ()

Built-in Function: filesep ("all")

Return the system-dependent character used to separate directory names.

If "all" is given, the function returns all valid file separators in the form of a string. The list of file separators is system-dependent. It is ‘/’ (forward slash) under UNIX or Mac OS X, ‘/’ and ‘\’ (forward and backward slashes) under Windows.

See also: pathsep.

Built-in Function: val = filemarker ()

Built-in Function: old_val = filemarker (new_val)

Built-in Function: filemarker (new_val, "local")

Query or set the character used to separate the filename from the subfunction names contained within the file.

By default this is the character ‘>’. This can be used in a generic manner to interact with subfunctions. For example,

help (["myfunc", filemarker, "mysubfunc"])

returns the help string associated with the subfunction mysubfunc located in the file myfunc.m.

filemarker is also useful during debugging for placing breakpoints within subfunctions or nested functions. For example,

dbstop (["myfunc", filemarker, "mysubfunc"])

will set a breakpoint at the first line of the subfunction mysubfunc.

When called from inside a function with the "local" option, the variable is changed locally for the function and any subroutines it calls. The original variable value is restored when exiting the function.

Function File: [dir, name, ext] = fileparts (filename)

Return the directory, name, and extension components of filename.

The input filename is a string which is parsed. There is no attempt to check whether the filename or directory specified actually exists.

See also: fullfile, filesep.

Function File: filename = fullfile (dir1, dir2, …, file)

Function File: filenames = fullfile (…, files)

Build complete filename from separate parts.

Joins any number of path components intelligently. The return value is the concatenation of each component with exactly one file separator between each non empty part and at most one leading and/or trailing file separator.

If the last component part is a cell array, returns a cell array of filepaths, one for each element in the last component, e.g.:

fullfile ("/home/username", "data", {"f1.csv", "f2.csv", "f3.csv"})
⇒  /home/username/data/f1.csv
    /home/username/data/f2.csv
    /home/username/data/f3.csv

On Windows systems, while forward slash file separators do work, they are replaced by backslashes; in addition drive letters are stripped of leading file separators to obtain a valid file path.

See also: fileparts, filesep.

Built-in Function: tilde_expand (string)

Perform tilde expansion on string.

If string begins with a tilde character, (‘~’), all of the characters preceding the first slash (or all characters, if there is no slash) are treated as a possible user name, and the tilde and the following characters up to the slash are replaced by the home directory of the named user. If the tilde is followed immediately by a slash, the tilde is replaced by the home directory of the user running Octave.

For example:

tilde_expand ("~joeuser/bin")
     ⇒ "/home/joeuser/bin"
tilde_expand ("~/bin")
     ⇒ "/home/jwe/bin"

Built-in Function: [cname, status, msg] = canonicalize_file_name (fname)

Return the canonical name of file fname.

If the file does not exist the empty string ("") is returned.

See also: make_absolute_filename, is_absolute_filename, is_rooted_relative_filename.

Built-in Function: make_absolute_filename (file)

Return the full name of file beginning from the root of the file system.

No check is done for the existence of file.

See also: canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isdir.

Built-in Function: is_absolute_filename (file)

Return true if file is an absolute filename.

See also: is_rooted_relative_filename, make_absolute_filename, isdir.

Built-in Function: is_rooted_relative_filename (file)

Return true if file is a rooted-relative filename.

See also: is_absolute_filename, make_absolute_filename, isdir.

Function File: current_state = recycle ()

Function File: old_state = recycle (new_state)

Query or set the preference for recycling deleted files.

When recycling is enabled, commands which would permanently erase files instead move them to a temporary location (such as the directory labeled Trash).

Programming Note: This function is provided for MATLAB compatibility, but recycling is not implemented in Octave. To help avoid accidental data loss an error will be raised if an attempt is made to enable file recycling.

See also: delete, rmdir.