W3C

EXPath File Module 4.0

W3C Editor's Draft 7 July 2025

This version:
https://qt4cg.org/pr/2077/EXPath/file-40/
Latest version of EXPath File Module 4.0:
https://qt4cg.org/specifications/EXPath/file-40/
Most recent Recommendation of EXPath File Module:
http://expath.org/spec/file
Editor:
Christian Grün, BaseX GmbH

Please check the errata for any errors or issues reported since publication.

See also translations.

This document is also available in these non-normative formats: Specification in XML format and XML function catalog.

Copyright © 2000 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and document use rules apply.

Abstract

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 [EXPath File 1.0] specification, developed by the EXPath Community Group, defined for [XML Path Language (XPath) 2.0] and published in 2013.

The principal semantic alteration is use of functional argument defaults available in XPath 4.0.

These functions are defined for use in [XML Path Language (XPath) 4.0] and [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0] and other related XML standards. The signatures and summaries of functions defined in this document are available at: https://qt4cg.org/specifications/EXPath/file-40/.

A summary of changes since published version 1.0 (the XPath 2.0 version) is provided at F Changes since version 1.0.

Status of this Document

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 History notes. Comments are invited, in the form of GitHub issues at https://github.com/qt4cg/qtspecs.

Dedication

The publications of this community group are dedicated to our co-chair, Michael Sperberg-McQueen (1954–2024).

1 Introduction

Changes in 4.0 ⬇

  1. Use the arrows to browse significant changes since the 1.0 version of this specification.

  2. Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.

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 [XML Path Language (XPath) 4.0], [XQuery 4.1: An XML Query Language] and [XSL Transformations (XSLT) Version 4.0].

This document defines several classes of functions:

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 [XQuery and XPath Functions and Operators 4.0], SER30 [XSLT and XQuery Serialization 3.0] and XS2 [XML Schema Part 2: Datatypes Second Edition] .

1.1 Error management

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. [file:not-found], rather than the http://www.w3.org/2005/xqt-errors namespace and alpha-numeric local part, e.g. err:FOCH0004, used in [XQuery and XPath Functions and Operators 4.0]. These error codes were chosen originally in the 1.0 version of 2013.

1.2 File Paths

File paths are specified as strings.

[Definition] The current working directory is an absolute implementation-definedFO directory against which all relative file paths are resolved. For example, it can be the directory from which a query processor was started.

[Definition] If a Static Base URIXP exists, and if it points to a local file, the base directory points to the directory of this file. Otherwise, it is undefined. file:base-dir can be used to retrieve the directory. A file path can be resolved against this directory by simply appending it (if it is relative), or by calling file:resolve-path:

file:base-dir() || $path,
file:resolve-path($path, file:base-dir())

An implementation must accept absolute and relative UNIX/Linux and Windows paths as well as absolute file URIs. Some examples:

  • 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 implementation-dependentFO representation (which usually is the representation of the underlying operating system), which operating-system-specific directory separators.

It is implementation-dependentFO whether the error [file:invalid-path] is raised if a path is invalid, i.e., if it contains characters that are not allowed in a specific file system.

Whenever a nondeterministicFO function generates a path that is known to refer to a directory, it will be suffixed with the operating-system-specific directory separator.

1.3 Function Execution

Many functions are marked as nondeterministicFO, which means they are not guaranteed to perform the same operations and produce identical results when being called repeatedly. A processor must ensure that these functions are not relocated or pre-evaluated and that its results are not cached when compiling and evaluating the query and serializing its results.

1.4 Test suite

A suite of test-cases for all the functions defined in this module, in [QT3] format, is defined at [Test-suite].

1.5 Conformance

This specification follows the general remarks on and terminology for conformance given in Section 1.2 ConformanceFO

In this document, text labeled as an example or as a note is provided for explanatory purposes and is not normative.

1.6 Namespaces and prefixes

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.

1.7 Function signatures and descriptions

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 Section 1.5 Function signatures and descriptionsFO. In particular in this update (trailing) optional arguments for functions (introduced in XPath 4.0) are used where appropriate in the signatures, rather than multiple-arity signatures as previously.

2 File Properties

2.1 file:name

Summary

Returns the name of a file or directory.

Signature
file:name(
$path as xs:string
) as xs:string
Properties

This function is deterministicFO, context-independentFO, and focus-independentFO.

Rules

Returns the name of a file or directory. An empty string is returned if the path points to the root directory.

This function is deterministicFO: the path is neither checked for correctness nor looked up in the file system.

Examples
Expression Result 
file:name('')
 
''
 
file:name('/')
 
''
 
file:name('hello.txt')
 
'hello.txt'
 
file:name('dir/')
 
'dir'
 
file:name('dir/file.txt')
 
'file.txt'
 
file:name('dir/..')
 
'..'
 
file:name('file:///tmp/001.bin')
 
'001.bin'

2.2 file:last-modified

Summary

Returns the last modification time of a file or directory.

Signature
file:last-modified(
$path as xs:string
) as xs:dateTime
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns an xs:dateTime item representing the last modification of a file or directory.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:last-modified('.')
Result:

(Returns the last modification time of the current working directory.)
Expression:

file:last-modified(file:base-dir())
Result:

(Returns the last modification time of the base directory.)

2.3 file:size

Changes in 4.0 ⬇ ⬆

  1. $recursive parameter added.  [Issue 2016 PR 2077 7 July 2025]

Summary

Returns the size of a file or directory.

Signature
file:size(
$path as xs:string,
$recursive as xs:boolean? := false()
) as xs:integer
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:io-error] is raised if any other error occurs.

Examples
Expression Result 
file:size('.')
 
0
 
file:size('/')
 
0

2.4 file:exists

Summary

Tests if a file or directory exists.

Signature
file:exists(
$path as xs:string
) as xs:boolean
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns true if $path points to a file or a directory, false otherwise.

On a UNIX-based system, the root and the volume roots are considered directories.

Examples
Expression Result 
file:exists('.')
 
true()
 
file:exists('/')
 
true()

2.5 file:is-dir

Summary

Tests if $path points to a directory.

Signature
file:is-dir(
$path as xs:string
) as xs:boolean
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns true if $path points to an existing directory. Otherwise, if it points to a file that is no directory, or if the file does not exist, it returns false.

On a UNIX-based system, the root and the volume roots are considered directories.

Examples
Expression Result 
file:is-dir('.')
 
true()
 
file:is-dir('/')
 
true()

2.6 file:is-file

Summary

Tests if $path points to a regular file.

Signature
file:is-file(
$path as xs:string
) as xs:boolean
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns true if $path points to a regular file (no directory, no symbolic link, no other operating-system specific file type). Otherwise, if it points to a directory or if the file does not exist, it returns false.

Examples
Expression Result 
file:is-file('.')
 
false()
 
file:is-file('/')
 
false()

2.7 file:is-absolute

Changes in 4.0 ⬇ ⬆

  1. New in 4.0.  [Issue 2016 PR 2077 2 July 2024]

Summary

Tests if $path is absolute.

Signature
file:is-absolute(
$path as xs:string
) as xs:boolean
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns true if $path is absolute, false otherwise.

A path is absolute if it does not need to be combined with other path information, such as the current directory, to locate a file.

Note:

All UNC file names are absolute.

Examples
Expression Result 
file:is-absolute('/')
 
true()

3 Manipulation of Files as Entities

3.1 file:copy

Summary

Copies a file or a directory.

Signature
file:copy(
$source as xs:string,
$target as xs:string
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Copies a file or a directory given a source and a target path/URI. The following rules apply if $source points to a file:

  1. if $target does not exist, it will be created.

  2. if $target is a file, it will be overwritten.

  3. 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:

  1. 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.

  2. 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.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:exists] is raised if the specified source path points to a directory and target path points to an existing file.

[file:no-dir] is raised if the parent directory of the specified source path does not exist.

[file:is-dir] is raised if the specified source path points to a file and the target path points to a directory in which a subdirectory exists with the name of the source file.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:copy('a.txt', 'b.txt')
Result:

(Creates a copy of the file a.txt in the same directory, named b.txt.)
Expression:

file:copy('a.txt', '../')
Result:

(Creates a copy of the file a.txt with the same name in the parent directory.)
Expression:

file:copy('dir/', 'dir2/')
Result:

(Creates a recursive copy of the directory dir in the current working directory, named dir2. If dir2 already exists, the contents of dir will be copied into that directory.)

3.2 file:create-dir

Summary

Creates a directory.

Signature
file:create-dir(
$dir as xs:string
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:exists] is raised if the specified path, or any of its parent directories, points to an existing file.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:create-dir('examples')
Result:

(Creates a directory named examples in the current working directory.)
Expression:

file:create-dir('/')
Result:

(Will do nothing, as the root directory already exists.)

3.3 file:create-temp-dir

Changes in 4.0 ⬇ ⬆

  1. All parameters are optional now.  [Issue 2016 PR 2077 7 July 2025]

Summary

Creates a temporary directory.

Signature
file:create-temp-dir(
$prefix as xs:string? := (),
$suffix as xs:string? := (),
$dir as xs:string? := ()
) as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Note:

The created directory will not be deleted automatically after query execution.

Error Conditions

[file:no-dir] is raised if the specified directory does not exist or points to a file.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:parent(file:create-temp-dir()) = file:temp-dir()
Result: 
true()
Expression: 
file:create-temp-dir(dir := file:base-dir())
Result:

(Creates a temporary directory in the base directory or, if it is undefined, in the default temporary-file directory.)
Expression: 
let $dir := file:create-temp-dir()
return try {
  file:write($dir || 'tmp.data', 1 to 10)
} finally {
  file:delete($dir, true())
}
Result:

(Creates a temporary directory, writes a file into that directory, and deletes it again.)

3.4 file:create-temp-file

Changes in 4.0 ⬇ ⬆

  1. All parameters are optional now.  [Issue 2016 PR 2077 7 July 2025]

Summary

Creates a temporary file.

Signature
file:create-temp-file(
$prefix as xs:string? := (),
$suffix as xs:string? := (),
$dir as xs:string? := ()
) as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Note:

The created file will not be deleted automatically after query execution.

Error Conditions

[file:no-dir] is raised if the specified does not exist or points to a file.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:create-temp-file(suffix := '.txt')
Result:

(Creates a file with the suffix .txt in the temporary-file directory.)

3.5 file:delete

Summary

Deletes a file or a directory.

Signature
file:delete(
$path as xs:string,
$recursive as xs:boolean? := false()
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Deletes a file or a directory from the file system. If $recursive is true, subdirectories will be deleted as well.

The function returns the empty sequence if the operation is successful.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:is-dir] is raised if the specified path points to a non-empty directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:delete('list.txt')
Result:

(Deletes the file list.txt from the current working directory.)
Expression:

file:delete('examples', true())
Result:

(Deletes the file or directory example and (if available) all subdirectories.)

3.6 file:move

Summary

Moves a file or a directory.

Signature
file:move(
$source as xs:string,
$target as xs:string
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Moves a file or a directory given a source and a target path/URI. The following rules apply if $source points to a file:

  1. if $target does not exist, it will be created.

  2. if $target is a file, it will be overwritten.

  3. 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:

  1. 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.

  2. 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 [file:is-dir] is raised.

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.

Error Conditions

[file:not-found] is raised if the specified source path does not exist.

[file:exists] is raised if the specified source path points to a directory and target path points to an existing file.

[file:no-dir] is raised if the parent directory of the specified source path does not exist.

[file:is-dir] is raised if the specified target path points to a directory in which a subdirectory exists with the name of the source.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:move('a.txt', 'b.txt')
Result:

(Renames a.txt to b.txt.)
Expression:

file:move('a.txt', '../')
Result:

(Moves the file a.txt to the parent directory.)
Expression:

file:move('dir/', 'dir2/')
Result:

(Renames dir to dir2. If dir2 already exists, moves the source directory into that directory.)

4 Input/Output

4.1 file:append

Changes in 4.0 ⬇ ⬆

  1. $options can now be a map, in alignment with fn:serialize.  [Issue 2016 PR 2077 7 July 2025]

Summary

Appends a serialized value to a file.

Signature
file:append(
$file as xs:string,
$value as item()*,
$options as (element(output:serialization-parameters) | map(*))? := ()
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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 Section 15.1.3 fn:serializeFO. In contrast to fn:serialize, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified file does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:append('fragments.xml', <fragment/>)
Result:

(Appends a serialized element node to the file fragments.xml. The file is created if it does not already exist.)
Expression:

file:append('snippets.json', { 'one': 1 }, { 'method': 'json' })
Result:

(Serializes a map as JSON and appends the resulting string to the file snippets.json.)

4.2 file:append-binary

Summary

Appends binary data to a file.

Signature
file:append-binary(
$file as xs:string,
$value as xs:base64Binary
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:append-binary('data.bin', xs:hexBinary('414243'))
Result:

(Appends the bytes 0x44, 0x43 and 0x41 to the file data.bin. The file is created if it does not already exist.)

4.3 file:append-text

Summary

Appends a string to a file.

Signature
file:append-text(
$file as xs:string,
$value as xs:string,
$encoding as xs:string? := 'utf-8'
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:append-text('todos.txt', 'clean up')
Result:

(Appends a string to the file todos.txt. The file is created if it does not already exist.)

4.4 file:append-text-lines

Summary

Appends a sequence of strings to a file, each followed by the operating-system specific newline character.

Signature
file:append-text-lines(
$file as xs:string,
$lines as xs:string*,
$encoding as xs:string? := 'utf-8'
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:append-text-lines('numbers.txt', (1 to 5) ! string())
Result:

(Appends the string representation of the integers 1 to 5 to the file numbers.txt. The file is created if it does not already exist.)

4.5 file:read-binary

Changes in 4.0 ⬇ ⬆

  1. $length can now be supplied without supplying $offset.  [Issue 2016 PR 2077 7 July 2025]

Summary

Returns the binary content of a file.

Signature
file:read-binary(
$file as xs:string,
$offset as xs:integer? := 0,
$length as xs:integer? := ()
) as xs:base64Binary
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:out-of-range] is raised if the specified offset or length value is negative, or if the value would exceed the file bounds.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:read-binary('data.bin') eq xs:hexBinary('41')
Result:

(Returns true if the file data.bin contains the single byte 0x41.)
Expression:

file:read-binary('data.bin', file:size($path) - 1, 1)
Result:

(Returns the last byte of the file data.bin.)

4.6 file:read-text

Changes in 4.0 ⬇ ⬆

  1. $fallback parameter added.  [Issue 2016 PR 2077 2 July 2024]

  2. The normalization of newlines has been made explicit.  [Issue 2016 PR 2077 2 July 2024]

Summary

Returns the content of a file as a string.

Signature
file:read-text(
$file as xs:string,
$encoding as xs:string? := 'utf-8',
$fallback as xs:boolean? := false()
) as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the content of a file in its string representation. Newlines are normalized: Any U+000D (CARRIAGE RETURN) character, optionally followed by a U+000A (NEWLINE) character, is converted to a single U+000A (NEWLINE) character.

If no encoding is supplied, utf-8 is used as input encoding. By default, invalid XML characters will be rejected. If $fallback is true, the characters will be replaced with the Unicode replacement character U+FFFD (REPLACEMENT CHARACTER, �) .

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

contains(file:read-text('todos.txt'), 'push forward')
Result:

(Returns true if the file todos.txt contains the specified string.)
Expression: 
'test.bin'
=> file:write-binary(xs:hexBinary('00'))
=> file:read-text(fallback := true())
=> string-to-codepoints()
Result: 
65533

(Returns the codepoint value of the Unicode replacement character.)

4.7 file:read-text-lines

Changes in 4.0 ⬇ ⬆

  1. $fallback parameter added.  [Issue 2016 PR 2077 2 July 2024]

Summary

Returns the contents of a file as a sequence of strings, separated at newline boundaries.

Signature
file:read-text-lines(
$file as xs:string,
$encoding as xs:string? := 'utf-8',
$fallback as xs:boolean? := false()
) as xs:string*
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the contents of a file as a sequence of strings, separated at newline boundaries.

Any of the character sequences U+000A (NEWLINE) , U+000D (CARRIAGE RETURN) , or U+000D (CARRIAGE RETURN) followed by U+000A (NEWLINE) is interpreted as newline.

If no encoding is supplied, utf-8 is used as input encoding. By default, invalid XML characters will be rejected. If $fallback is enabled, the characters will be replaced with the Unicode replacement character U+FFFD (REPLACEMENT CHARACTER, �) .

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression: 
let $file := 'numbers.txt'
let $data := (1 to 5) ! string()
return (
  file:write-text-lines($file, $data),
  file:read-text-lines($file) => deep-equal($data)
)
Result: 
true()

(Can be used to prove that the written and read strings are equal.)

4.8 file:write

Changes in 4.0 ⬇ ⬆

  1. $options can now be a map, in alignment with fn:serialize.  [Issue 2016 PR 2077 7 July 2025]

Summary

Writes a serialized value to a file.

Signature
file:write(
$file as xs:string,
$value as item()*,
$options as (element(output:serialization-parameters) | map(*))? := ()
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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 Section 15.1.3 fn:serializeFO. In contrast to fn:serialize, the encoding stage will not be skipped by this function.

The function returns the empty sequence if the operation is successful.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:write('numbers.txt', 1 to 10)
Result:

(Writes 10 numbers to the file numbers.txt.)
Expression: 
file:write(
  'result.xml',
  <result><done/></result>,
  { 'encoding': 'us-ascii', 'indent': true() }
)
Result:

(Serializes an indented element node as US-ASCII and writes it to the file result.xml.)
Expression: 
file:write(
  'numbers.json',
  map:build(1 to 10, string#1),
  { 'method': 'json' }
)
Result:

(Writes a map, serialized as JSON, to a specified file.)

4.9 file:write-binary

Summary

Writes binary data to a file.

Signature
file:write-binary(
$file as xs:string,
$value as xs:base64Binary,
$offset as xs:integer? := 0
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Note:

Supplying an offset makes sense only if the file already exists.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:out-of-range] is raised if the specified offset is negative, or if it exceeds the current file size.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:write-binary('data.bin', xs:hexBinary('414243'))
Result:

(Writes the bytes 0x44, 0x43 and 0x41 to the file data.bin.)
Expression:

file:write-binary('data.bin', xs:hexBinary('44', 2))
Result:

(If this expression is called after the previous one, overwrites the last byte with 0x44.)

4.10 file:write-text

Summary

Writes a string to a file.

Signature
file:write-text(
$file as xs:string,
$value as xs:string,
$encoding as xs:string? := 'utf-8'
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:write-text('todos.txt', 'get organized')
Result:

(Writes a string to the file todos.txt. The file is created if it does not already exist.)

4.11 file:write-text-lines

Summary

Writes strings to a file.

Signature
file:write-text-lines(
$file as xs:string,
$values as xs:string*,
$encoding as xs:string? := 'utf-8'
) as empty-sequence()
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:no-dir] is raised if the parent directory of the specified path does not exist.

[file:is-dir] is raised if the specified path points to a directory.

[file:unknown-encoding] is raised if the specified encoding is invalid or not supported by the implementation.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:write-text-lines('numbers.txt', (1 to 5) ! string())
Result:

(Writes the string representation of the integers 1 to 5 to the file numbers.txt.)

5 Paths

5.1 file:parent

Summary

Returns the parent directory of a given path.

Signature
file:parent(
$path as xs:string
) as xs:string?
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Transforms the given path into an absolute path, as specified by file:resolve-path, and returns the parent directory.

An empty sequence is returned if the path points to a root directory.

Note:

The inverse function is file:children.

Examples
Expression Result 
file:parent('/')
 
()
 
file:current-dir() = file:parent('abc')
 
true()

5.2 file:children

Summary

Returns the paths of all files and directories that are located in the given directory.

Signature
file:children(
$path as xs:string
) as xs:string*
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Note:

The inverse function is file:parent; a related function is file:list.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:no-dir] is raised if the specified path does not point to an existing directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

count(file:children('.'))
Result:

( Counts the files and directories in the current working directory. ).
Expression:

file:children('path/to/media/')[matches(., '\.(avi|mpg|mp4)$', 'i')]

Result:

( Returns the paths to large videos found in a specific directory. ).

5.3 file:descendants

Changes in 4.0 ⬇ ⬆

  1. New in 4.0.  [Issue 2016 PR 2077 2 July 2024]

Summary

Returns the paths of all files and directories that are located in the given directory and its subdirectories.

Signature
file:descendants(
$path as xs:string
) as xs:string*
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:no-dir] is raised if the specified path does not point to an existing directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

count(file:descendants('.')[file:is-directory(.)])
Result:

( Counts the subdirectories in the current working directory. ).
Expression: 
for $file in file:descendants('.')
where file:last-modified($file) > current-dateTime() - xs:dayTimeDuration('PT1H')
return $file
Result:

( Returns the paths to all files that have been modified in the last hour. ).

5.4 file:list

Changes in 4.0 ⬇ ⬆

  1. $pattern can now be supplied without supplying $recursive.  [Issue 2016 PR 2077 7 July 2025]

Summary

Lists all files and directories in a given directory.

Signature
file:list(
$dir as xs:string,
$recursive as xs:boolean? := false(),
$pattern as xs:string? := ()
) as xs:string*
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Lists all files and directories in a given directory. In contrast to is file:children, the returned paths are relative to the supplied directory $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.

Note:

A related function is file:children.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:no-dir] is raised if the specified path does not point to an existing directory.

[file:io-error] is raised if any other error occurs.

Examples
Expression:

file:list('.')
Result:

(Returns the names of all files in the current working directory.)
Expression:

file:list('.', pattern := '*.zip')
Result:

(Returns the names of archive files in the current working directory.)
Expression: 
let $root := '/path/to/files/'
for $file in file:list($root, true(), '*.txt')
let $path := file:resolve-path($file, $root)
where file:size($path) > 1000000
return file:read-text($path)
Result:

(Returns the contents of large text files found in a specific directory and its subdirectories.)

5.5 file:list-roots

Changes in 4.0 ⬇ ⬆

  1. New in 4.0.  [Issue 2016 PR 2077 2 July 2024]

Summary

Lists all root directories of the file system.

Signature
file:list-roots() as xs:string*
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Note:

Dynamically available UNC file names are not returned by this function.

Examples
Expression:

file:list-roots('/')
Result:

(A single slash as result indicates a UNIX-based system.)

5.6 file:resolve-path

Changes in 4.0 ⬆

  1. $base parameter added.  [Issue 2016 PR 2077 2 July 2024]

Summary

Transforms a relative path into an absolute operating system path.

Signature
file:resolve-path(
$path as xs:string,
$base as xs:string? := ()
) as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Transforms a relative path into an absolute operating system path. The following rules apply in order:

  1. If $path is an absolute path, it is returned unchanged.

  2. Otherwise, if $base is the empty sequence, $path is resolved against the current working directory.

  3. 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.

Error Conditions

[file:is-relative] is raised if the specified base directory is relative.

Examples
Expression Result 
file:resolve-path('INF', 'C:/Windows/')
 
'C:/Windows/INF/'

(The result refers to a Windows system.)

 
file:resolve-path('data.bin', 'C:/Temp')
 
'C:/data.bin'

(The result refers to a Windows system.)

 
file:resolve-path('hilda/notes.txt', '/home/')
 
'/home/hilda/notes.txt'

(The result refers to a UNIX-based system.)

5.7 file:path-to-native

Summary

Transforms a path to a canonical representation.

Signature
file:path-to-native(
$path as xs:string
) as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

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.

Error Conditions

[file:not-found] is raised if the specified path does not exist.

[file:io-error] is raised if an error occurs while trying to generate the native path.

Examples
Expression:

file:path-to-native('/')
Result:

(Returns / on a UNIX-based system.)

5.8 file:path-to-uri

Summary

Transforms a file system path into a URI.

Signature
file:path-to-uri(
$path as xs:string
) as xs:anyURI
Properties

This function is deterministicFO, context-independentFO, and focus-independentFO.

Rules

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 deterministicFO: the path is neither checked for correctness nor looked up in the file system.

Examples
Expression Result 
file:path-to-uri('/temp')

(Returns file:///temp on a UNIX-based system).

 
contains(file:path-to-uri('a b'), '%20')
 
true()

(Space characters will be encoded to %20.)

6 System Properties

6.1 file:dir-separator

Summary

Returns the directory separator.

Signature
file:dir-separator() as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the value of the operating-system specific directory separator, which usually is / on UNIX-based systems and \ on Windows systems.

Examples
Expression Result 
file:dir-separator() = ('/', '\')
 
true()

6.2 file:line-separator

Summary

Returns the line separator.

Signature
file:line-separator() as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the value of the operating-system specific line separator, which usually is &#10; on UNIX-based systems, &#13;&#10; on Windows systems and &#13; on old Mac systems.

Examples
Expression Result 
matches(file:line-separator(), '^(\n|\r\n|\r)$')
 
true()

6.3 file:path-separator

Summary

Returns the path separator.

Signature
file:path-separator() as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the value of the operating-system specific path separator, which usually is : on UNIX-based systems and ; on Windows systems.

Examples
Expression Result 
file:dir-separator() = (':', ';')
 
true()

6.4 file:temp-dir

Summary

Returns the path to the temporary-file directory.

Signature
file:temp-dir() as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the path to the default temporary-file directory of an operating system.

Examples
Expression:

file:write-text(file:temp-dir() || 'todos.txt', 'get on going')
Result:

(Write a text string to a file in the temporary-file directory.)

6.5 file:base-dir

Summary

Returns the base directory.

Signature
file:base-dir() as xs:string?
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the base directory. If defined, the function returns the same result as the expression file:parent(static-base-uri()). Otherwise, it returns an empty sequence

Examples
Expression: 
let $dir := file:base-dir() otherwise file:create-temp-dir()
return file:write-text($dir || 'todos.txt', 'get up')
Result:

(Writes todos.txt to the base directory or, if it is not defined, to a temporary directory.)

6.6 file:current-dir

Summary

Returns the current working directory.

Signature
file:current-dir() as xs:string
Properties

This function is nondeterministicFO, context-dependentFO, and focus-independentFO.

Rules

Returns the current working directory. All relative file paths are resolved against this directory.

Formal Equivalent

The effect of the function is equivalent to the result of the following XPath expression.

file:resolve-path('.')
Examples
Expression: 
file:path-to-native('todos.txt') =
file:path-to-native(file:current-dir() || 'todos.txt')
Result: 
true()

(Both paths refer to the same file.)

A References

A.1 Normative references

EXPath File 1.0
File Module 1.0. Christian Grün, Matthias Brantner and Gabriel Petrovay, editors. EXPath Module 20 February 2015.
IEEE 754-1985
IEEE 754-2019
IEEE. IEEE Standard for Floating-Point Arithmetic.
XML Path Language (XPath) 2.0
XML Path Language (XPath) 2.0 (Second Edition), Don Chamberlin, Anders Berglund, Scott Boag, et. al., Editors. World Wide Web Consortium, 14 December 2010. This version is https://www.w3.org/TR/2010/REC-xpath20-20101214/. The latest version is available at https://www.w3.org/TR/xpath20/.
XQuery and XPath Functions and Operators 4.0
XQuery and XPath Functions and Operators 4.0, XSLT Extensions Community Group, World Wide Web Consortium.
XML Path Language (XPath) 4.0
XSL Transformations (XSLT) Version 4.0
CITATION: T.B.D.
XQuery and XPath Data Model (XDM) 4.0
XQuery and XPath Data Model (XDM) 4.0, XSLT Extensions Community Group, World Wide Web Consortium.
XSLT and XQuery Serialization 3.0
XSLT and XQuery Serialization 3.0. Henry Zongaro, et al. W3C Recommendation 08 April 2014.
XQuery and XPath Functions and Operators 3.0
XPath and XQuery Functions and Operators 3.0. Michael Kay. W3C Recommendation 08 April 2014.
XQuery 4.1: An XML Query Language
CITATION: T.B.D.
XML Schema Part 2: Datatypes Second Edition
XML Schema Part 2: Datatypes Second Edition, Oct. 28 2004. Available at: http://www.w3.org/TR/xmlschema-2/

A.2 Non-normative references

Test-suite
The test suite for this module, using QT3 format, is in the EXPath repository http://github.com/expath/expath-cg in the directory tests/qt3/file/
QT3
XML Query Test Suite. W3C 21 June 2013.
EXPath
EXPath: Collaboratively Defining Open Standards for Portable XPath Extensions. http://expath.org/.

B Error summary

The error text provided with these errors is non-normative.

file:exists

The specified path already exists.

file:invalid-path

The specified path is invalid.

file:io-error

A generic file system error occurred.

file:is-dir

The specified path points to a directory.

file:is-relative

The specified path is relative.

file:no-dir

The specified path does not point to a directory.

file:not-found

The specified path does not exist.

file:out-of-range

The specified offset or length is negative, or the chosen values would exceed the file bounds.

file:unknown-encoding

The specified encoding is not supported.

C Glossary (Non-Normative)

base directory

If a Static Base URIXP exists, and if it points to a local file, the base directory points to the directory of this file. Otherwise, it is undefined.

current working directory

The current working directory is an absolute implementation-definedFO directory against which all relative file paths are resolved.

D Other Functions (Non-Normative)

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.

D.1 XPath Functions and Operators Defined in Other W3C Recommendations

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.

D.1.1 Functions and Operators Defined in XPath and XQuery Functions and Operators

E Checklist of implementation-defined features (Non-Normative)

    F Changes since version 1.0 (Non-Normative)

    F.1 Summary of Changes

    1. Use the arrows to browse significant changes since the 1.0 version of this specification.

      See 1 Introduction

    2. Sections with significant changes are marked Δ in the table of contents. New functions introduced in this version are marked ➕ in the table of contents.

      See 1 Introduction

    3. PR 2077 

      $recursive parameter added.

      See 2.3 file:size

      New in 4.0.

      See 2.7 file:is-absolute

      All parameters are optional now.

      See 3.3 file:create-temp-dir

      See 3.4 file:create-temp-file

      $options can now be a map, in alignment with fn:serialize.

      See 4.1 file:append

      $length can now be supplied without supplying $offset.

      See 4.5 file:read-binary

      $fallback parameter added.

      See 4.6 file:read-text

      The normalization of newlines has been made explicit.

      See 4.6 file:read-text

      $fallback parameter added.

      See 4.7 file:read-text-lines

      $options can now be a map, in alignment with fn:serialize.

      See 4.8 file:write

      New in 4.0.

      See 5.3 file:descendants

      $pattern can now be supplied without supplying $recursive.

      See 5.4 file:list

      New in 4.0.

      See 5.5 file:list-roots

      $base parameter added.

      See 5.6 file:resolve-path

    F.2 Changes to Function Signatures

    1. 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.

    F.3 Editorial Changes

    These changes are not highlighted in the change-marked version of the specification.

    G Compatibility with Previous Versions (Non-Normative)

    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:

    1. 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:

      file:list($dir, false(), ())

      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.