This document defines a file system API for XPath 4.0. It defines extension functions to perform file system related operations such as listing, reading, or writing files or directories.
The document is an update of the original
The principal semantic alteration is use of functional argument defaults available in XPath 4.0.
These functions are defined for use in
A summary of changes since published version 1.0 (the XPath 2.0 version) is provided
at
This version of the specification is work in progress. It is produced by the QT4
Working Group, officially the W3C XSLT 4.0 Extensions Community Group. Individual
functions specified in the document may be at different stages of review, reflected
in their
The publications of this community group
The purpose of this document is to define functions to manipulate files within a local filesystem and their representations inclusion in XPath 4.0, XQuery 4.0, and XSLT 4.0.
The exact syntax used to call these functions and operators is specified in
This document defines several classes of functions:
Functions to examine the properties of files, such as size and modification dates.
Functions to perform basic operations on files as entities, such as copying, deletion, creating directories and establishment of temporary files.
Functions to read and write to and from files in various formats.
Functions to manipulate file paths.
Functions to examine properties of the underlying file system and current context, such as establishing the current working directory or the characters used for various separators within paths or files.
References to specific sections of some other specifications are indicated by
cross-document links in this document. Each such link consists of a pointer to a
specific section followed a superscript specifying the linked document. The
superscripts have the following meanings: FO40
Error conditions are identified by a code (a QName.) When such an
error condition is reached in the evaluation of an expression, a dynamic error
is thrown, with the corresponding error code (as if the standard XPath function
error() had been called.)
In this specification these codes use the http://expath.org/ns/file
namespace and a 'descriptive string' local part, e.g. http://www.w3.org/2005/xqt-errors namespace and alpha-numeric local
part, e.g. err:FOCH0004, used in
All file paths are specified as strings, and are resolved against the current working directory. The current working directory is implementation-defined: It can e. g. be the file system directory from which a query processor was started.
An implementation
C:\Test Dir\my file.xml: An absolute path on Windows
platforms.
/Test Dir/my file.xml: An absolute path on UNIX-based
platforms.
C:\\\Test Dir//\\my file.xml: An absolute path on Windows
platforms that tolerates an arbitrary number of slashes and
backslashes.
my file.xml: A relative path, pointing to a file in the
current working directory.
file:///C:/Test%20Dir/my%20file.xml: An absolute file URI on
Windows platforms.
file:///Test%20Dir/my%20file.xml: An absolute path on
UNIX-based platforms.
Before further processing, all paths are normalized to an
It is
If a function returns a string that refers to a directory, it will always be suffixed with the system-specific directory separator.
The function file:base-dir can be used to resolve file operations
against the directory of the base URI:
Almost all of these functions are marked as
A suite of test-cases for all the functions defined in this module, in
This specification follows the general remarks on and terminology for conformance
given in
In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.
The functions defined in this document are contained exclusively in the namespace
http://expath.org/ns/file and referenced using a
xs:QName binding to that namespace.
This document uses the prefix file to refer to this namespace.
User-written applications can choose a different prefix to refer to the
namespace, so long as it is bound to the correct URI. In accordance with current
practice, it is recommended that the prefix file be reserved for
use with this namespace.
Each function (or group of functions having the same name) is defined in this
specification using a standard proforma, full details of which can be found in
Tests if a file or directory exists.
This function is
Returns true if $path points to a file or directory,
false otherwise.
On UNIX-based systems the root and the volume roots are considered directories.
Tests if $path points to a directory.
This function is
Returns true if $path points to a directory,
false otherwise.
On UNIX-based systems the root and the volume roots are considered directories.
Tests if $path points to a file.
This function is
Returns true if $path points to a existing file.
Returns false if $path points to a existing directory.
Otherwise returns false
Returns the last modification time of a file or directory.
This function is
Returns the last modification time of a file or directory.
$path does not
exist.
Returns the byte size of a file, or the value 0 for directories.
This function is
Returns 0 if $file points to a directory.
Returns the byte size of the file $file, if it exists.
$path does not
exist.
Copies a file or a directory given a source and a target path/URI.
This function is
Copies a file or a directory given a source and a target path/URI. The following
cases may occur if $source points to a file:
if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that
directory with the name of the source file. If a file already exists, it
will be overwritten.
The following cases may occur if $source points to a directory:
if $target does not exist, it will be created as directory, and
all files of the source directory are copied to this directory with their
existing local names.
if $target is a directory, the source directory with all its
files will be copied into the target directory. At each level, if a file
already exists in the target with the same name as in the source, it is
overwritten. If a directory already exists in the target with the same name
as in the source, it is not removed, it is recursed in place (if it does not
exist, it is created before recursing).
Other cases will raise one of the errors listed below.
The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible
$source path
does not exist.
$source points to a
directory and $target points to an existing file.
$source does not exist.
$source points to a
file and $target points to a directory, in which a subdirectory exists
with the name of the source file.
Creates a directory if it does not already exist.
This function is
Creates a directory, or does nothing if the directory already exists. The operation will create all non-existing parent directories.
The function returns the empty sequence if the operation is successful.
Creates a temporary directory.
This function is
Creates a temporary directory and all non-existing parent directories and returns the full path to the created directory.
The temporary directory will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.
If $dir is omitted or an empty sequence, the directory will be created
inside the system-dependent default temporary-file directory.
Creates a temporary file.
This function is
Creates a temporary file and all non-existing parent directories and returns the full path to the created file.
The temporary file will not be automatically deleted after query execution. It is guaranteed to not already exist when the function is called.
If $dir is omitted or an empty sequence, the file will be created inside
the system-dependent default temporary-file directory.
Deletes a file or a directory from the file system.
This function is
Deletes a file or a directory from the file system.
If the optional parameter $recursive is true,
sub-directories will be deleted as well.
The function returns the empty sequence if the operation is successful.
$path does not
exist.
$file points to a
non-empty directory.
Lists all files and directories in a given directory.
This function is
Lists all files and directories in a given directory. The order of the items in the
resulting sequence is not defined. The "." and ".." items are never returned. The
returned paths are relative to the provided directory $dir.
If the optional parameter $recursive is true, all
directories and files will be returned that are found while recursively traversing
the given directory. If $recursive is omitted or an empty sequence or
false only the contents of the specified directory will be returned.
The optional $pattern parameter defines a name pattern in the glob
syntax. If this is provided and is not an empty sequence, only the paths of the
files and directories whose names are matching the pattern will be returned.
An implementation must support at least the following glob syntax for the pattern:
* for matching any number of unknown characters
and? for matching one unknown character.
A related function is file:children.
$dir does not point
to an existing directory.
Moves a file or a directory.
This function is
Moves a file or a directory given a source and a target path/URI. The following cases
may occur if $source points to a file:
if $target does not exist, it will be created.
if $target is a file, it will be overwritten.
if $target is a directory, the file will be created in that
directory with the name of the source file. If a file already exists, it
will be overwritten.
The following cases may occur if $source points to a directory:
if $target does not exist, it will be created as directory, and
all files of the source directory are moved to this directory with their
existing local names.
if $target is a directory, the source directory with all its
files will be moved into the target directory. If the target directory
contains a directory with the same name as the source, the error
Other cases will raise one of the errors listed below.
The function returns the empty sequence if the operation is successful. If an error occurs during the operation, no rollback to the original state will be possible
$source path
does not exist.
$source points to a
directory and $target points to an existing file.
$source does not exist.
$target points to a
directory, in which a subdirectory exists with the name of the source.
Appends a sequence of items to a file. If the file pointed by $file does
not exist, a new file will be created.
This function is
Appends a sequence of items to a file.
If the file pointed by $file does not exist, a new file will be
created.
$params, if not an empty sequence, controls the way the
$items items are serialized. The semantics of $params are
those of the same argument of output:serialization-parameters element whose format
is defined in fn:serialize, the
encoding stage will not be skipped by this function.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
Appends a Base64 item as binary data to a file.
This function is
Appends a Base64 item as binary data to a file.
If the file pointed to by $file does not exist, a new file will be
created.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
Appends a string to a file.
This function is
Appends a string to the file $file.
If the file pointed to by $file does not exist, a new file will be
created.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
Appends a sequence of strings to a file, each followed by the system-dependent newline character.
This function is
Appends a sequence of strings to a file, each followed by the system-dependent newline character.
If the file pointed to by $file does not exist, a new file will be
created.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
Returns the content of a file in its Base64 representation.
This function is
Returns the content of a file in its Base64 representation.
The optional parameters $offset and $length can be used to
read chunks of a file.
$file does not
exist.
$file points to a
directory.
$offset or
$length is negative, or if the chosen values would exceed the file
bounds.
Returns the content of a file in its string representation.
This function is
Returns the content of a file in its string representation.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
$file does not
exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
Returns the contents of a file as a sequence of strings, separated at newline boundaries.
This function is
Returns the contents of a file as a sequence of strings, separated at newline boundaries.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
The newline handling is the same as for
$file does not
exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
Writes a sequence of items to a file.
This function is
Writes a sequence of items to a file.
If $file already exists, it will be overwritten; otherwise, it will be
created.
$params, if not an empty sequence, controls the way the
$items items are serialized. The semantics of $params are
those of the same argument of output:serialization-parameters element whose format
is defined in fn:serialize, the encoding stage will not
be skipped by this function.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
Writes a Base64 item as binary to a file.
This function is
Writes a Base64 item as binary to a file.
If $file already exists, it will be overwritten; otherwise, it will be
created.
If the optional parameter $offset is specified and not set to an empty
sequence, data will be written starting at this file position. An existing file may
be resized by such an operation.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
$offset is
negative, or if it exceeds the current file size.
Writes a string to a file.
This function is
Writes a strings to a file.
If $file already exists, it will be overwritten.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
Writes a sequence of strings to a file, each followed by the system-dependent newline character.
This function is
Writes a sequence of strings to a file, each followed by the system-dependent newline character.
If $file already exists, it will be overwritten; otherwise, it will be
created.
The optional parameter $encoding, if omitted or an empty sequence, is
considered to be UTF-8.
The function returns the empty sequence if the operation is successful.
$file does not exist.
$file points to a
directory.
$encoding
is invalid or not supported by the implementation.
None of the functions in this section performs any check regarding the existence of the received or returned paths.
Returns the name of a file or directory.
This function is
Returns the name of a file or directory.
An empty string is returned if the path points to the root directory, or if it contains no directory separators.
This function is
Returns the parent directory of a given path.
This function is
Transforms the given path into an absolute path, as specified by
The inverse function is
An empty sequence is returned if the path points to a root directory.
Returns the paths of all files and directories that are located in the given directory.
This function is
Returns the paths of all files and directories that are located in the given directory. The order of the items in the resulting sequence is not defined. The "." and ".." items are never returned.
The inverse function is
$path does not
point to an existing directory.
Transforms a URI, an absolute path, or relative path to a canonical, system-dependent path representation.
This function is
Transforms a URI, an absolute path, or relative path to a canonical, system-dependent path representation. A canonical path is both absolute and unique and thus contains no redirections such as references to parent directories or symbolic links.
If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.
$path does not
exist.
Transforms a file system path into a URI.
This function is
Transforms a file system path into a URI with the file:// scheme. If the
path is relative, it is first resolved against the current working directory.
This function is
Transforms a relative path into an absolute operating system path.
This function is
Transforms a relative path into an absolute operating system path by resolving it against the current working directory.
If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.
Returns the value of the operating system-specific directory separator.
This function is
Returns the value of the operating system-specific directory separator, which usually
is / on UNIX-based systems and \ on Windows systems.
Returns the value of the operating system-specific line separator.
This function is
Returns the value of the operating system-specific line separator, which usually is
on UNIX-based systems, on
Windows systems and on Mac systems.
Returns the value of the operating system-specific path separator.
This function is
Returns the value of the operating system-specific path separator, which usually is
: on UNIX-based systems and ; on Windows systems.
Returns the path to the default temporary-file directory of an operating system.
This function is
Returns the path to the default temporary-file directory of an operating system.
Returns the parent directory of the static base URI.
This function is
Returns the parent directory of the static base URI.
If the Base URI property is undefined, the empty sequence is returned.
If a static base URI exists, and if points to a local file path, this function
returns the same result as the expression
file:parent(static-base-uri()).
Returns the current working directory.
This function is
Returns the current working directory.
The effect of the function is equivalent to the result of the following XPath expression.
The error text provided with these errors is non-normative.
The specified path does not exist.
The specified path is invalid.
The specified path already exists.
The specified path does not point to a directory.
The specified path points to a directory.
The specified encoding is not supported.
The specified offset or length is negative, or the chosen values would exceed the file bounds.
A generic file system error occurred.
This Appendix describes some sources of functions or operators that fall outside the scope of the function library defined in this specification. It includes both function specifications and function implementations. Inclusion of a function in this appendix does not constitute any kind of recommendation or endorsement; neither is omission from this appendix to be construed negatively. This Appendix does not attempt to give any information about licensing arrangements for these function specifications or implementations.
A number of W3C Recommendations make use of XPath, and in some cases such Recommmendations define additional functions to be made available when XPath is used in a specific host language.
The function signatures of all the specified signatures now use the 'optional argument' syntax of XPath 4.0 where appropriate, rather than giving several signatures of differing arity. Other than that, no intended change to the semantics of the functions are assumed.
These changes are not highlighted in the change-marked version of the specification.
This section summarizes the extent to which this specification is compatible with previous versions.
Version 4.0 of this function library is fully backwards compatible with version 1.0, except as noted below:
The use of optional arguments in the function signatures means that minor alterations to possible function calls, which would be invalid in 1.0, are now supported. For example:
would be invalid in 1.0, as the third argument $pattern is
defined to be of type xs:string. It is valid for 4.0 as the
empty sequence denotes default behaviour, that is all files are listed.
The functions file:append, file:append-text, file:append-text-lines
file:create-temp-dir, file:create-temp-file,
file:delete, file:read-binary,
file:read-text, file:read-text-lines,
file:write, file:write-binary,
file:write-text and file:write-text-lines all have
similar incompatibilities.