EXPath File Module 4.0

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

All file paths are specified as strings, and are resolved against the current working directory. The current working directory is implementation-defined: For example, it can be the file system directory from which a query processor was started.

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-dependent^FO representation (which usually is the representation of the underlying operating system).

It is implementation-dependent^FO as to whether the error [file:invalid-path] is raised if a path is invalid.

Whenever a function returns a string that refers to a directory, it is 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:

let $filename := "input.txt"
let $path := file:resolve-path($filename, file:base-dir())
return file:read-text($path)

1.3 Function Execution

Most functions are marked as nondeterministic^FO, 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 Conformance^FO

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 descriptions^FO. 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.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 deterministic^FO, context-independent^FO, and focus-independent^FO.

Rules

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

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

2.3 file:size

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

If $path points to a regular 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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

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

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

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

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Returns true if $path points to a regular file. Otherwise, if it points to a directory or if the file does not exist, it returns false.

2.7 file:is-link

Summary

Tests if $path points to a symbolic link.

Signature

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

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Returns true if $path points to a symbolic link. Otherwise, if it points to a directory or if the file does not exist, it returns false.

2.8 file:is-absolute

Summary

Tests if $path is absolute.

Signature

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

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

3.2 file:create-dir

Summary

Creates a directory.

Signature

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

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Creates a directory, or does nothing if the directory 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.

3.3 file:create-temp-dir

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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 system-dependent 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.

3.4 file:create-temp-file

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Creates a 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 system-dependent 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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

4.1 file:append

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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:serialize^FO. 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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

4.4 file:append-text-lines

Summary

Appends a sequence of strings to a file, each followed by the system-dependent 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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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.

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.

4.5 file:read-binary

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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.

4.6 file:read-text

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

4.7 file:read-text-lines

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

The newline handling is the same as for Section 14.6.6 fn:unparsed-text-lines^FO.

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.

4.8 file:write

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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:serialize^FO. 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 numbers to a specified file).
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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Writes strings to a file, each followed by the system-dependent 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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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:	file:children('path/to/media/')[matches(., '\.(avi|mpg|mp4)$', 'i')]
Result:	( Returns the paths to large videos located in a specific directory. ).

5.3 file:descendants

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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:	file:children('data/')[file:is-dir(.)]
Result:	( Returns the paths to all subdirectories located in a specific directory. ).

5.4 file:list

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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:	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 located in a specific directory and its subdirectories.)

5.5 file:list-roots

Summary

Lists all root directories of the file system.

Signature

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

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

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.

5.6 file:resolve-path

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Transforms a relative path into an absolute operating system path by resolving it against the current working directory. If the path is relative, and if an absolute $base path is specified, it will be resolved against this path.

If the resulting path points to a directory, it will be suffixed with the system-specific directory separator.

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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.

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.

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 deterministic^FO, context-independent^FO, and focus-independent^FO.

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

6.1 file:dir-separator

Summary

Returns the directory separator.

Signature

file:dir-separator() as xs:string

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

6.2 file:line-separator

Summary

Returns the line separator.

Signature

file:line-separator() as xs:string

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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.

6.3 file:path-separator

Summary

Returns the path separator.

Signature

file:path-separator() as xs:string

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

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 nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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

6.5 file:base-dir

Summary

Returns the parent directory of the static base URI.

Signature

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

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

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()).

6.6 file:current-dir

Summary

Returns the current working directory.

Signature

file:current-dir() as xs:string

Properties

This function is nondeterministic^FO, context-dependent^FO, and focus-independent^FO.

Rules

Returns the current working directory.

Formal Equivalent

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

file:resolve-path('.')