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.
f1 ¶f1 f2 ¶f1 f2 f ¶(f1) ¶(f1, f2) ¶(f1, f2, 'f') ¶[status] = movefile (…) ¶[status, msg] = movefile (…) ¶[status, msg, msgid] = movefile (…) ¶Move the source file or directory f1 to the destination f2.
The name f1 may contain globbing patterns, or may be a cell array of strings. If f1 expands to multiple filenames, f2 must be a directory.
If no destination f2 is specified then the destination is the present working directory. If f2 is a filename 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 logical 1, and msg, msgid are
empty character strings (""). Otherwise, status is logical 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.
old new ¶[status, msg] = rename (old, new) ¶Change the name of file old to new.
If successful, status is 0 and msg is an empty string. Otherwise, status is -1 and msg contains a system-dependent error message.
f1 f2 ¶f1 f2 f ¶(f1, f2) ¶(f1, f2, 'f') ¶[status, msg, msgid] = copyfile (…) ¶Copy the source file(s) or directory f1 to the destination f2.
The name f1 may contain globbing patterns, or may be a cell array of strings. If f1 expands to multiple filenames, f2 must be a directory.
When the force flag 'f' is given any existing files will be
overwritten without prompting.
If successful, status is logical 1, and msg, msgid are
empty character strings (""). Otherwise, status is logical 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.
(file) ¶[status, msg] = unlink (file) ¶Delete the file named file.
If successful, status is 0 and msg is an empty string. Otherwise, status is -1 and msg contains a system-dependent error message.
old new ¶[status, msg] = link (old, new) ¶Create a new link (also known as a hard link) to an existing file.
If successful, status is 0 and msg is an empty string. Otherwise, status is -1 and msg contains a system-dependent error message.
old new ¶[status, msg] = symlink (old, new) ¶Create a symbolic link new which contains the string old.
If successful, status is 0 and msg is an empty string. Otherwise, status is -1 and msg contains a system-dependent error message.
result = readlink symlink ¶[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.
dirname ¶parent dirname ¶(dirname) ¶(parent, dirname) ¶[status, msg, msgid] = mkdir (…) ¶Create a directory named dirname in the directory parent, creating any intermediate directories if necessary.
If dirname is a relative path, and no parent directory is specified, then the present working directory is used.
If successful, status is logical 1, and msg, msgid are
empty character strings (""). Otherwise, status is logical 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.
When creating a directory permissions will be set to
0777 - UMASK.
dir ¶(dir, "s") ¶[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 logical 1, and msg, msgid are empty character strings (""). Otherwise, status is logical 0, msg contains a system-dependent error message, and msgid contains a unique message identifier.
See also: mkdir, confirm_recursive_rmdir, pwd.
val = confirm_recursive_rmdir () ¶old_val = confirm_recursive_rmdir (new_val) ¶old_val = 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.
(name, mode) ¶[status, msg] = mkfifo (name, mode) ¶Create a FIFO special file named name with file mode mode.
mode is interpreted as an octal number and is subject to umask
processing. The final calculated mode is mode - umask.
If successful, status is 0 and msg is an empty string. Otherwise, status is -1 and msg contains a system-dependent error message.
oldmask = 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.
[info, err, msg] = stat (file) ¶[info, err, msg] = stat (fid) ¶[info, err, msg] = lstat (file) ¶[info, err, msg] = lstat (fid) ¶Return a structure info containing the following information about file or file identifier fid.
devID of device containing a directory entry for this file.
inoFile number of the file.
modeFile 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.
modestrFile mode, as a string of ten letters or dashes as would be returned by ls -l.
nlinkNumber of links.
uidUser ID of file’s owner.
gidGroup ID of file’s group.
rdevID of device for block or character special files.
sizeSize in bytes.
atimeTime of last access in the same form as time values returned from
time. See Timing Utilities.
mtimeTime of last modification in the same form as time values returned from
time. See Timing Utilities.
ctimeTime of last file status change in the same form as time values
returned from time. See Timing Utilities.
blksizeSize of blocks in the file.
blocksNumber 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 =
tf = 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.
tf = 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.
tf = 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.
tf = 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.
tf = 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.
tf = 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.
tf = 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.
file ¶(file) ¶[status, attrib] = fileattrib (…) ¶[status, msg, msgid] = fileattrib (…) ¶Report attribute information about file.
If no file or directory is specified, report information about the present working directory.
If successful, the output is a structure with the following fields:
NameFull name of file.
archiveTrue if file is an archive (Windows).
systemTrue if file is a system file (Windows).
hiddenTrue if file is a hidden file (Windows).
directoryTrue if file is a directory.
UserReadGroupReadOtherReadTrue if the user (group; other users) has read permission for file.
UserWriteGroupWriteOtherWriteTrue if the user (group; other users) has write permission for file.
UserExecuteGroupExecuteOtherExecuteTrue if the user (group; other users) has execute permission for file.
If an attribute does not apply (e.g., archive on a Unix system) then the field is set to NaN.
If file contains globbing characters, information about all matching files is returned in a structure array.
If outputs are requested, the first is status which takes the value 1 when the operation was successful, and 0 otherwise. The second output contains the structure described above (attrib) if the operation was successful; otherwise, the second output is a system-dependent error message (msg). The third output is an empty string ("") when the operation was successful, or a unique message identifier (msgid) in the case of failure.
tf = isfile (f) ¶Return true if f is a regular file and false otherwise.
If f is a cell array of strings, tf is a logical array of the same size.
See also: isfolder, exist, stat, is_absolute_filename, is_rooted_relative_filename.
tf = isdir (f) ¶This function is not recommended. Use isfolder or
file_in_loadpath instead.
Return true if f is a directory and false otherwise.
Compatibility Note: The MATLAB function of the same name will also search for f in the load path directories. To emulate this behavior use
tf = ! isempty (file_in_loadpath (f))
See also: isfolder, file_in_loadpath, exist, stat, is_absolute_filename, is_rooted_relative_filename.
tf = isfolder (f) ¶Return true if f is a directory and false otherwise.
If f is a cell array of strings, tf is a logical array of the same size.
See also: isfile, exist, stat, is_absolute_filename, is_rooted_relative_filename.
files = readdir (dir) ¶[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.
cstr = glob (pattern) ¶Given an array of pattern strings (as a char array or a cell array) in pattern, return a cell array of filenames 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 filenames. 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
}
Note: On Windows, patterns that contain non-ASCII characters are not supported.
fname = file_in_path (path, file) ¶fname = 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.
sep = 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.
[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.
filename = fullfile (dir1, dir2, …, file) ¶Build complete filename from separate parts.
The function joins any number of path components intelligently. The return value is the concatenation of each component with exactly one file separator between each part of the path and at most one leading and/or trailing file separator.
The input arguments might be strings or cell strings. Any input arguments that are cell strings must contain one single string or must be equal in size. In that case, the function returns a cell string of filepaths of the same dimensions as the input cell strings, e.g.:
fullfile ("/home/username", "data", {"f1.csv", "f2.csv", "f3.csv"})
⇒
{
[1,1] = /home/username/data/f1.csv
[1,2] = /home/username/data/f2.csv
[1,3] = /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.
Note: fullfile does not perform any validation of the resulting full
filename.
newstr = tilde_expand (string) ¶newcstr = tilde_expand (cellstr) ¶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.
If the input is a cell array of strings cellstr then tilde expansion is performed on each string element.
Examples:
tilde_expand ("~joeuser/bin")
⇒ "/home/joeuser/bin"
tilde_expand ("~/bin")
⇒ "/home/jwe/bin"
[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. No tilde expansion of fname is performed.
See also: make_absolute_filename, is_absolute_filename, is_rooted_relative_filename, is_same_file, tilde_expand.
abs_fname = 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. No tilde expansion of file is performed.
See also: canonicalize_file_name, is_absolute_filename, is_rooted_relative_filename, isfolder, tilde_expand.
tf = is_absolute_filename (file) ¶Return true if file is an absolute filename.
See also: is_rooted_relative_filename, make_absolute_filename, isfolder.
same = is_same_file (filepath1, filepath2) ¶Return true if filepath1 and filepath2 refer to the same file.
If either filepath1 or filepath2 is a cell array of strings, then an array of the same size is returned, containing the values described above for every member of the cell array. The other argument may also be a cell array of strings (of the same size) or a string.
Programming Notes: Depending on the operating system and file system, the same file or folder can be referred to with different paths. In particular, paths on the Windows platform may differ in case (file1 vs. FILE1), file separator (‘\’ vs. ‘/’), and format (A~spaces.txt (8.3 convention) vs. A filename with spaces.txt). This function returns true if the paths in filepath1 and filepath2 actually refer to the same file or folder, and false otherwise.
Note that unlike strcmp, this function requires that filepath1
and filepath2 exist, as well as point to the same location, in order to
return true.
See also: canonicalize_file_name, strcmp.
tf = is_rooted_relative_filename (file) ¶Return true if file is a rooted-relative filename.
See also: is_absolute_filename, make_absolute_filename, isfolder.
val = recycle () ¶old_val = recycle (new_val) ¶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.