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, for 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 access and 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 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: FO
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
File paths are specified as strings.
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
Whenever a
Many 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
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.
This function is
| Expression | Result |
|---|---|
file:name('') |
|
file:name('/') |
|
file:name('hello.txt') |
|
file:name('dir/') |
|
file:name('dir/file.txt') |
|
file:name('dir/..') |
|
file:name('file:///tmp/001.bin') |
|
Returns the last modification time of a file or directory.
This function is
Returns an xs:dateTime item representing the last modification of
a file or directory.
| Expression | Result |
|---|---|
file:last-modified('.') | Returns the last modification time of the
|
file:last-modified(file:base-dir()) | Returns the last modification time of the
|
$recursive parameter added.Returns the size of a file or directory.
This function is
If $path points to a file, returns the byte size of this file.
Otherwise, if it points to a directory, returns either 0 or,
if $recursive is true, the aggregated size of all files and
subdirectories.
| Expression | Result |
|---|---|
file:size('.') |
|
file:size('/') |
|
Tests if a file or directory exists.
This function is
Returns true if $path points to an existing file or directory,
false otherwise.
On a UNIX-based system, the root and the volume roots are considered directories.
| Expression | Result |
|---|---|
file:exists('.') |
|
file:exists('/') |
|
Tests if $path points to a directory.
This function is
Returns true if $path points to an existing directory
as defined in false.
On a UNIX-based system, the root and the volume roots are considered directories.
| Expression | Result |
|---|---|
file:is-dir('.') |
|
file:is-dir('/') |
|
Tests if $path points to a regular file.
This function is
Returns true if $path points to an existing regular file
as defined in false.
| Expression | Result |
|---|---|
file:is-file('.') |
|
file:is-file('/') |
|
Tests if $path is absolute.
This function is
Returns true if $path is absolute,
false otherwise.
A path is absolute if it contains all the components necessary to identify a file location, without reference to a current drive or a current working directory.
All UNC file names are absolute.
The function may return a different result for the same path on a Windows and a UNIX-based system.
| Expression | Result |
|---|---|
file:is-absolute('abc') |
|
file:is-absolute('/') | Returns |
Copies a file or a directory.
This function is
Copies a file or a directory given a source and a target path/URI.
The following rules apply 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.
Otherwise, 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 result in one of the errors listed below.
The function returns the empty sequence if the operation is successful. No rollback to the original state will be possible if an error occurs during the operation.
| Expression | Result |
|---|---|
file:copy('a.txt', 'b.txt') | Creates a copy of the file |
file:copy('a.txt', '../') | Creates a copy of the file |
file:copy('dir/', 'dir2/') | Creates a recursive copy of the directory |
Creates a directory.
This function is
Creates a directory unless it already exists. The operation will also create non-existing parent directories.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:create-dir('examples') | Creates a directory named |
file:create-dir('/') | Does nothing, as the root directory already exists. |
Creates a temporary directory.
This function is
Creates a temporary directory with an optional $prefix and
$suffix in the filename, and returns the full path to the created directory.
The path will point to a directory that did not exist before the function was called.
If $dir is omitted or an empty sequence, the directory will be created
inside the operating-system specific default temporary-file directory.
The created directory will not be deleted automatically after query execution.
| Expression: |
|
|---|---|
| Result: |
|
| Expression: | |
| Result: | Creates a temporary directory in the |
| Expression: | |
| Result: | Creates a temporary directory, writes a file into that directory, and deletes it again. |
Creates a temporary file.
This function is
Creates an empty temporary file with an optional $prefix and
$suffix in the filename, and returns the full path to the created file.
The path will point to a file that did not exist before the function was called.
If $dir is omitted or an empty sequence, the file will be created inside
the operating-system specific default temporary-file directory.
The created file will not be deleted automatically after query execution.
| Expression | Result |
|---|---|
file:create-temp-file(suffix := '.txt') | Creates a file with the suffix |
Deletes a file or a directory.
This function is
Deletes a file or a directory from the file system if it exists:
If $path points to a file, the file is deleted.
Otherwise, if $path points to a directory, then:
if it is non-empty and $recursive is false,
an error is raised.
Otherwise, the directory and all its contents are deleted recursively.
Otherwise, nothing happens.
The function returns the empty sequence if the operation is successful.
No rollback to the original state will be possible if an error occurs during the operation.
| Expression | Result |
|---|---|
file:delete('list.txt') | Deletes the file |
file:delete('examples', true()) | Deletes the file or 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 rules apply 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.
Otherwise, 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 result in one of the errors listed below.
The function returns the empty sequence if the operation is successful. No rollback to the original state will be possible if an error occurs during the operation.
| Expression | Result |
|---|---|
file:move('a.txt', 'b.txt') | Renames |
file:move('a.txt', '../') | Moves the file |
file:move('dir/', 'dir2/') | Renames |
$options can now be a map, in alignment with fn:serialize.Appends a serialized value to a file.
This function is
Serializes a value and appends the resulting string to a file.
If the file pointed to by $file does not exist,
a new file will be created.
The $options argument controls the way how $value is serialized.
The semantics are the same as for fn:serialize, the encoding stage will not be skipped by
this function.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:append('fragments.xml', <fragment/>) | Appends a serialized element node to the file
|
file:append('snippets.json', { 'one': 1 }, { 'method': 'json' }) | Serializes a map as JSON and appends the resulting string to the file
|
Appends binary data to a file.
This function is
Appends the binary data of an xs:base64Binary item 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.
| Expression | Result |
|---|---|
file:append-binary('data.bin', xs:hexBinary('414243')) | Appends the bytes |
Appends a string to a file.
This function is
Appends a string to a file.
If the file pointed to by $file does not exist, a new file will be
created.
If no encoding is supplied, UTF-8 is used as output encoding.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:append-text('todos.txt', 'clean up') | Appends a string to the file |
Appends a sequence of strings to a file, each followed by the operating-system specific newline character.
This function is
Appends a sequence of strings to a file, each followed by the operating-system specific
newline character.
If the file pointed to by $file does not exist, a new file will be created.
If no encoding is supplied, UTF-8 is used as output encoding.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:append-text-lines('numbers.txt', (1 to 5) ! string()) | Appends the string representation of the integers 1 to 5 to the file
|
$length can now be supplied without supplying $offset.Returns the binary content of a file.
This function is
Returns the content of a file as an xs:base64Binary item.
Chunks of a file can be read by supplying $offset and $length.
If no value is supplied for $length, all remaining bytes will be read.
If only $length is specified, the offset is 0.
| Expression | Result |
|---|---|
file:read-binary('data.bin') eq xs:hexBinary('41') | Returns |
file:read-binary('data.bin', file:size($path) - 1, 1) | Returns the last byte of the file |
$options parameter added.Returns the content of a file as a string.
This function is
Returns the content of a file in its string representation.
Newlines are normalized: Any
The $options argument, for backwards compatibility reasons, may be supplied
either as a map, or as a string. Supplying a value $S that is not a map
is equivalent to supplying the map { "encoding": $S }.
After that substitution, the
The entries that may appear in the $options map are as follows:
| Key | Meaning |
|---|---|
| Defines the encoding of the resource, as described below.
|
|
If $fallback is true, any character that
cannot be decoded or that is not a
|
| Expression: |
|
|---|---|
| Result: | Returns |
| Expression: | |
| Result: |
$fallback parameter added.$fallback parameter has been integrated into the options map.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.
Any of the character sequences
The $options argument, for backwards compatibility reasons, may be supplied
either as a map, or as a string. Supplying a value $S that is not a map
is equivalent to supplying the map { "encoding": $S }.
After that substitution, the
The entries that may appear in the $options map are as follows:
| Key | Meaning |
|---|---|
| Defines the encoding of the resource, as described below.
|
|
If $fallback is true, any character that
cannot be decoded or that is not a
|
| Expression: | |
|---|---|
| Result: |
$options can now be a map, in alignment with fn:serialize.Writes a serialized value to a file.
This function is
Serializes a value and appends the resulting string to a file.
If the file pointed to by $file already exists, it will be overwritten;
otherwise, it will be created.
The $options argument controls the way how $value is serialized.
The semantics are the same as for fn:serialize, the encoding stage will not be skipped by
this function.
The function returns the empty sequence if the operation is successful.
| Expression: |
|
|---|---|
| Result: | Writes 10 numbers to the file |
| Expression: | |
| Result: | Serializes an indented element node as |
| Expression: | |
| Result: | Writes a map, serialized as JSON, to a specified file. |
Writes binary data to a file.
This function is
Writes the binary data of an xs:base64Binary item to a file.
If the file pointed to by $file already exists, it will be overwritten;
otherwise, it will be created.
If $offset is specified and not an empty sequence, data will be written
starting at this file position, and existing bytes will be overwritten.
The operation may resize the existing file.
The function returns the empty sequence if the operation is successful.
Supplying an offset makes sense only if the file already exists.
| Expression | Result |
|---|---|
file:write-binary('data.bin', xs:hexBinary('414243')) | Writes the bytes |
file:write-binary('data.bin', xs:hexBinary('44', 2)) | If this expression is called after the previous one, overwrites the last
byte with |
Writes a string to a file.
This function is
Writes a string to a file.
If the file pointed to by $file already exists, it will be overwritten.
If no encoding is supplied, UTF-8 is used as output encoding.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:write-text('todos.txt', 'get organized') | Writes a string to the file |
Writes strings to a file.
This function is
Writes strings to a file, each followed by the operating-system specific newline character.
If the file pointed to by $file already exists, it will be overwritten;
otherwise, it will be created.
If no encoding is supplied, UTF-8 is used as output encoding.
The function returns the empty sequence if the operation is successful.
| Expression | Result |
|---|---|
file:write-text-lines('numbers.txt', (1 to 5) ! string()) | Writes the string representation of the integers 1 to 5 to the file
|
Returns the path to the parent directory of a given path.
This function is
Transforms the given path into an absolute path, as specified by
An empty sequence is returned if the path points to a root directory.
The inverse function is
| Expression | Result |
|---|---|
file:parent('/') |
|
file:current-dir() = file:parent('abc') |
|
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 references to the specified directory and its parent directory
(. and ..) are not returned.
The inverse function is
| Expression: | |
|---|---|
| Result: | Counts the files and directories in the |
| Expression: |
|
| Result: | Returns the paths to large videos found in a specific directory. |
Returns the paths of all files and directories that are located in the given directory and its subdirectories.
This function is
Returns the paths of all files and directories that are located in the given
directory and its subdirectories. The order of the items in the resulting sequence
is not defined.
The references to the specified directory and its parent directory
(. and ..) are not returned.
| Expression: |
|
|---|---|
| Result: | Counts the subdirectories in the |
| Expression: | |
| Result: | Returns the paths to all files that have been modified in the last hour. |
$pattern can now be supplied without supplying $recursive.Lists all files and directories in a given directory.
This function is
Lists all files and directories in a given directory.
In contrast to is $dir.
The order of the items in the resulting sequence is not defined.
The references to the specified directory and its parent directory
(. and ..) are not returned.
If $recursive is true, all directories and files will be returned
that are found while recursively traversing the given directory.
Otherwise, only the contents of the specified directory will be returned.
The $pattern argument is used to define a name pattern in the glob syntax.
If supplied, 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 characters:
* for matching any number of unknown characters and
? for matching one unknown character.
A related function is
| Expression: |
|
|---|---|
| Result: | Returns the names of all files in the
|
| Expression: |
|
| Result: | Returns the names of archive files in the
|
| Expression: | |
| Result: | Returns the contents of large text files found in a specific directory and its subdirectories. |
Lists all root directories of the file system.
This function is
Lists all root directories of the file system:
On a Windows system, root directories are usually the letters of the
currently available drives, followed by a colon and a backslash
(for example, C:\ and D:\).
On a UNIX-based system, it is usually a single slash, denoting the root directory.
Dynamically available UNC file names are not returned by this function.
| Expression | Result |
|---|---|
file:list-roots('/') | A single slash as result indicates a UNIX-based system. |
$base parameter added.Transforms a relative path into an absolute operating system path.
This function is
Transforms a relative path into an absolute operating system path. The following rules apply in order:
If $path is an absolute path, it is not changed.
Otherwise, if $base is the empty sequence, $path is
resolved against the
Otherwise, it is resolved against the supplied base path or, if the base path does not point to a directory, to its parent directory. An error is raised if the base is a relative path.
If the resulting path points to a directory, it will be suffixed with the operating-system specific directory separator.
| Expression | Result |
|---|---|
file:resolve-path('INF', 'C:/Windows/') |
|
file:resolve-path('data.bin', 'C:/Temp') |
|
file:resolve-path('hilda/notes.txt', '/home/') |
|
Transforms a path to a canonical representation.
This function is
Transforms a URI, an absolute path, or relative path to a canonical, operating-system specific 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 operating-system specific directory separator.
| Expression | Result |
|---|---|
file:path-to-native('/') | Returns |
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
This function is
| Expression | Result |
|---|---|
file:path-to-uri('/temp') | Returns |
contains(file:path-to-uri('a b'), '%20') |
|
Returns the 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.
| Expression | Result |
|---|---|
file:dir-separator() = ('/', '\') |
|
Returns the 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 old Mac systems.
| Expression | Result |
|---|---|
matches(file:line-separator(), '^(\n|\r\n|\r)$') |
|
Returns the 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.
| Expression | Result |
|---|---|
file:dir-separator() = (':', ';') |
|
Returns the path to the temporary-file directory.
This function is
Returns the path to the default temporary-file directory of an operating system.
| Expression | Result |
|---|---|
file:write-text(file:temp-dir() || 'todos.txt', 'get on going') | Write a text string to a file in the temporary-file directory. |
Returns the base directory.
This function is
Returns the file:parent(static-base-uri()). Otherwise, it returns an empty sequence
| Expression: | |
|---|---|
| Result: | Writes |
Returns the current working directory.
This function is
Returns the
The effect of the function is equivalent to the result of the following XPath expression.
| Expression: | |
|---|---|
| Result: |
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 path is relative.
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 behavior of listing all files.
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.