octave: Filesystem Utilities
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.
-- : movefile (F1)
-- : movefile (F1, F2)
-- : movefile (F1, F2, 'f')
-- : [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 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 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 XREFrename, copyfile XREFcopyfile,
DONTPRINTYET unlink XREFunlink, delete XREFdelete, *noteglob:
DONTPRINTYET unlink XREFunlink, delete XREFdelete, glob
XREFglob.
-- : rename OLD NEW
-- : [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.
DONTPRINTYET See also: movefile XREFmovefile, *notecopyfile:
DONTPRINTYET See also: movefile XREFmovefile, copyfile
XREFcopyfile, ls XREFls, dir XREFdir.
-- : [STATUS, MSG, MSGID] = copyfile (F1, F2)
-- : [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 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 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 XREFmovefile, rename XREFrename,
DONTPRINTYET unlink XREFunlink, delete XREFdelete, *noteglob:
DONTPRINTYET unlink XREFunlink, delete XREFdelete, glob
XREFglob.
-- : [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 XREFdelete, rmdir XREFrmdir.
-- : link OLD NEW
-- : [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 XREFsymlink, unlink XREFunlink,
readlink XREFreadlink, lstat XREFlstat.
-- : symlink OLD NEW
-- : [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.
DONTPRINTYET See also: link XREFlink, unlink XREFunlink, *noteDONTPRINTYET See also: link XREFlink, unlink XREFunlink,
readlink XREFreadlink, lstat XREFlstat.
-- : 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.
DONTPRINTYET See also: lstat XREFlstat, symlink XREFsymlink, *noteDONTPRINTYET See also: lstat XREFlstat, symlink XREFsymlink,
link XREFlink, unlink XREFunlink, delete XREFdelete.
-- : mkdir DIR
-- : mkdir (PARENT, DIR)
-- : [STATUS, MSG, MSGID] = mkdir (...)
Create a directory named DIR in the directory PARENT, creating any
intermediate directories if necessary.
If DIR is a relative path and no PARENT directory is specified then
the present working directory is used.
If successful, STATUS is 1, and MSG and MSGID are empty 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’.
DONTPRINTYET See also: rmdir XREFrmdir, pwd XREFpwd, *notecd:
DONTPRINTYET See also: rmdir XREFrmdir, pwd XREFpwd, cd
XREFcd, umask XREFumask.
-- : rmdir DIR
-- : rmdir (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 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.
DONTPRINTYET See also: mkdir XREFmkdir, *noteconfirm_recursive_rmdir:
DONTPRINTYET See also: mkdir XREFmkdir, confirm_recursive_rmdir
XREFconfirm_recursive_rmdir, pwd XREFpwd.
-- : VAL = confirm_recursive_rmdir ()
-- : OLD_VAL = confirm_recursive_rmdir (NEW_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 XREFrmdir.
-- : ERR = mkfifo (NAME, MODE)
-- : [ERR, 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, ERR is 0 and MSG is an empty string. Otherwise, ERR
is nonzero and MSG contains a system-dependent error message.
See also: pipe XREFpipe, umask XREFumask.
-- : 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’.
DONTPRINTYET See also: fopen XREFfopen, mkdir XREFmkdir, *noteDONTPRINTYET See also: fopen XREFfopen, mkdir XREFmkdir,
mkfifo XREFmkfifo.
-- : [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.
‘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’. Timing Utilities.
‘mtime’
Time of last modification in the same form as time values
returned from ‘time’. Timing Utilities.
‘ctime’
Time of last file status change in the same form as time
values returned from ‘time’. 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 =
DONTPRINTYET See also: lstat XREFlstat, ls XREFls, *notedir:
DONTPRINTYET See also: lstat XREFlstat, ls XREFls, dir
XREFdir.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : 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 XREFstat, lstat XREFlstat.
-- : fileattrib (FILE)
-- : fileattrib ()
-- : [STATUS, MSG, MSGID] = fileattrib (...)
Return information about FILE.
If successful, STATUS is 1 and MSG is 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.
If ‘attrib’ fails, MSG is a non-empty string containing an error
message and MSG_ID is the non-empty string "fileattrib".
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 XREFglob.
-- : isdir (F)
Return true if F is a directory.
DONTPRINTYET See also: exist XREFexist, stat XREFstat, *noteDONTPRINTYET DONTPRINTYET See also: exist XREFexist, stat XREFstat,
is_absolute_filename XREFis_absolute_filename, *noteDONTPRINTYET DONTPRINTYET See also: exist XREFexist, stat XREFstat,
is_absolute_filename XREFis_absolute_filename,
is_rooted_relative_filename XREFis_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.
DONTPRINTYET See also: ls XREFls, dir XREFdir, *noteglob:
DONTPRINTYET See also: ls XREFls, dir XREFdir, glob
XREFglob, what XREFwhat.
-- : 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
}
DONTPRINTYET See also: ls XREFls, dir XREFdir, *notereaddir:
DONTPRINTYET See also: ls XREFls, dir XREFdir, readdir
XREFreaddir, what XREFwhat.
-- : file_in_path (PATH, FILE)
-- : 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.
DONTPRINTYET See also: file_in_loadpath XREFfile_in_loadpath, *noteDONTPRINTYET See also: file_in_loadpath XREFfile_in_loadpath,
dir_in_loadpath XREFdir_in_loadpath, path XREFpath.
-- : filesep ()
-- : 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 XREFpathsep.
-- : VAL = filemarker ()
-- : OLD_VAL = filemarker (NEW_VAL)
-- : 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.
-- : [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 XREFfullfile, filesep XREFfilesep.
-- : FILENAME = fullfile (DIR1, DIR2, ..., 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.
Note: ‘fullfile’ does not perform any validation of the resulting
full filename.
DONTPRINTYET See also: fileparts XREFfileparts, *notefilesep:
DONTPRINTYET See also: fileparts XREFfileparts, filesep
XREFfilesep.
-- : tilde_expand (STRING)
-- : 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.
See also: make_absolute_filename XREFmake_absolute_filename,
DONTPRINTYET is_absolute_filename XREFis_absolute_filename, *noteDONTPRINTYET is_absolute_filename XREFis_absolute_filename,
is_rooted_relative_filename XREFis_rooted_relative_filename.
-- : 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 XREFcanonicalize_file_name,
DONTPRINTYET is_absolute_filename XREFis_absolute_filename, *noteDONTPRINTYET DONTPRINTYET is_absolute_filename XREFis_absolute_filename,
is_rooted_relative_filename XREFis_rooted_relative_filename, *noteDONTPRINTYET DONTPRINTYET is_absolute_filename XREFis_absolute_filename,
is_rooted_relative_filename XREFis_rooted_relative_filename,
isdir XREFisdir.
-- : is_absolute_filename (FILE)
Return true if FILE is an absolute filename.
DONTPRINTYET See also: is_rooted_relative_filename
XREFis_rooted_relative_filename, *notemake_absolute_filename:
DONTPRINTYET See also: is_rooted_relative_filename
XREFis_rooted_relative_filename, make_absolute_filename
XREFmake_absolute_filename, isdir XREFisdir.
-- : is_rooted_relative_filename (FILE)
Return true if FILE is a rooted-relative filename.
See also: is_absolute_filename XREFis_absolute_filename,
DONTPRINTYET make_absolute_filename XREFmake_absolute_filename, *noteDONTPRINTYET make_absolute_filename XREFmake_absolute_filename,
isdir XREFisdir.
-- : CURRENT_STATE = recycle ()
-- : 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 XREFdelete, rmdir XREFrmdir.
Info Catalog
octave: Timing Utilities
octave: System Utilities
octave: File Archiving Utilities