Filename(3) OCaml library Filename(3)

# [NAME](#NAME)

Filename - Operations on file names.

# [Module](#Module)

Module Filename

# [Documentation](#Documentation)

Module **Filename**  
: **sig end**

Operations on file names.

*val current\_dir\_name* : **string**

The conventional name for the current directory (e.g. **.** in Unix).

*val parent\_dir\_name* : **string**

The conventional name for the parent of the current directory (e.g. **..** in Unix).

*val dir\_sep* : **string**

The directory separator (e.g. **/** in Unix).

**Since** 3.11.2

*val concat* : **string -> string -> string**

**concat dir file** returns a file name that designates file **file** in directory **dir** .

*val is\_relative* : **string -> bool**

Return **true** if the file name is relative to the current directory, **false** if it is absolute (i.e. in Unix, starts with **/** ).

*val is\_implicit* : **string -> bool**

Return **true** if the file name is relative and does not start with an explicit reference to the current directory ( **./** or **../** in Unix), **false** if it starts with an explicit reference to the root directory or the current directory.

*val check\_suffix* : **string -> string -> bool**

**check\_suffix name suff** returns **true** if the filename **name** ends with the suffix **suff** .

Under Windows ports (including Cygwin), comparison is case-insensitive, relying on **String.lowercase\_ascii** . Note that this does not match exactly the interpretation of case-insensitive filename equivalence from Windows.

*val chop\_suffix* : **string -> string -> string**

**chop\_suffix name suff** removes the suffix **suff** from the filename **name** .

**Raises Invalid\_argument** if **name** does not end with the suffix **suff** .

*val chop\_suffix\_opt* : **suffix:string -> string -> string option**

**chop\_suffix\_opt ~suffix filename** removes the suffix from the **filename** if possible, or returns **None** if the filename does not end with the suffix.

Under Windows ports (including Cygwin), comparison is case-insensitive, relying on **String.lowercase\_ascii** . Note that this does not match exactly the interpretation of case-insensitive filename equivalence from Windows.

**Since** 4.08

*val extension* : **string -> string**

**extension name** is the shortest suffix **ext** of **name0** where:

\- **name0** is the longest suffix of **name** that does not contain a directory separator;

\- **ext** starts with a period;

\- **ext** is preceded by at least one non-period character in **name0** .

If such a suffix does not exist, **extension name** is the empty string.

**Since** 4.04

*val remove\_extension* : **string -> string**

Return the given file name without its extension, as defined in **Filename.extension** . If the extension is empty, the function returns the given file name.

The following invariant holds for any file name **s** :

**remove\_extension s ^ extension s = s**

**Since** 4.04

*val chop\_extension* : **string -> string**

Same as **Filename.remove\_extension** , but raise **Invalid\_argument** if the given name has an empty extension.

*val basename* : **string -> string**

Split a file name into directory name / base file name. If **name** is a valid file name, then **concat (dirname name) (basename name)** returns a file name which is equivalent to **name** . Moreover, after setting the current directory to **dirname name** (with **Sys.chdir** ), references to **basename name** (which is a relative file name) designate the same file as **name** before the call to **Sys.chdir** .

This function conforms to the specification of POSIX.1-2008 for the **basename** utility.

*val dirname* : **string -> string**

See **Filename.basename** . This function conforms to the specification of POSIX.1-2008 for the **dirname** utility.

*val null* : **string**

**null** is **"/dev/null"** on POSIX and **"NUL"** on Windows. It represents a file on the OS that discards all writes and returns end of file on reads.

**Since** 4.10

*val temp\_file* : **?temp\_dir:string -> string -> string -> string**

**temp\_file prefix suffix** returns the name of a fresh temporary file in the temporary directory. The base name of the temporary file is formed by concatenating **prefix** , then a suitably chosen integer number, then **suffix** . The optional argument **temp\_dir** indicates the temporary directory to use, defaulting to the current result of **Filename.get\_temp\_dir\_name** . The temporary file is created empty, with permissions **0o600** (readable and writable only by the file owner). The file is guaranteed to be different from any other file that existed when **temp\_file** was called.

**Before3.11.2** no ?temp\_dir optional argument

**Raises Sys\_error** if the file could not be created.

*val open\_temp\_file* : **?mode:open\_flag list ->** **?perms:int ->** **?temp\_dir:string -> string -> string -> string * out\_channel**

Same as **Filename.temp\_file** , but returns both the name of a fresh temporary file, and an output channel opened (atomically) on this file. This function is more secure than **temp\_file** : there is no risk that the temporary file will be modified (e.g. replaced by a symbolic link) before the program opens it. The optional argument **mode** is a list of additional flags to control the opening of the file. It can contain one or several of **Open\_append** , **Open\_binary** , and **Open\_text** . The default is **\[Open\_text]** (open in text mode). The file is created with permissions **perms** (defaults to readable and writable only by the file owner, **0o600** ).

**Before4.03** no ?perms optional argument

**Before3.11.2** no ?temp\_dir optional argument

**Raises Sys\_error** if the file could not be opened.

*val temp\_dir* : **?temp\_dir:string -> ?perms:int -> string -> string -> string**

**temp\_dir prefix suffix** creates and returns the name of a fresh temporary directory with permissions **perms** (defaults to 0o700) inside **temp\_dir** . The base name of the temporary directory is formed by concatenating **prefix** , then a suitably chosen integer number, then **suffix** . The optional argument **temp\_dir** indicates the temporary directory to use, defaulting to the current result of **Filename.get\_temp\_dir\_name** . The temporary directory is created empty, with permissions **0o700** (readable, writable, and searchable only by the file owner). The directory is guaranteed to be different from any other directory that existed when **temp\_dir** was called.

If temp\_dir does not exist, this function does not create it. Instead, it raises Sys\_error.

**Since** 5.1

**Raises Sys\_error** if the directory could not be created.

*val get\_temp\_dir\_name* : **unit -> string**

The name of the temporary directory: Under Unix, the value of the **TMPDIR** environment variable, or "/tmp" if the variable is not set.

Under Windows, the value returned by **GetTempPath2** (if available) or **GetTempPath** .

The temporary directory can be changed with **Filename.set\_temp\_dir\_name** .

Under Windows, before OCaml 5.4, it would return the value of the **TEMP** environment variable, or "." if the variable was not set.

**Since** 4.00

*val set\_temp\_dir\_name* : **string -> unit**

Change the temporary directory returned by **Filename.get\_temp\_dir\_name** and used by **Filename.temp\_file** and **Filename.open\_temp\_file** . The temporary directory is a domain-local value which is inherited by child domains.

**Since** 4.00

*val quote* : **string -> string**

Return a quoted version of a file name, suitable for use as one argument in a command line, escaping all meta-characters. Warning: under Windows, the output is only suitable for use with programs that follow the standard Windows quoting conventions.

*val quote\_command* : **string ->** **?stdin:string -> ?stdout:string -> ?stderr:string -> string list -> string**

**quote\_command cmd args** returns a quoted command line, suitable for use as an argument to **Sys.command** , **Unix.system** , and the **Unix.open\_process** functions.

The string **cmd** is the command to call. The list **args** is the list of arguments to pass to this command. It can be empty.

The optional arguments **?stdin** and **?stdout** and **?stderr** are file names used to redirect the standard input, the standard output, or the standard error of the command. If **~stdin:f** is given, a redirection **< f** is performed and the standard input of the command reads from file **f** . If **~stdout:f** is given, a redirection **> f** is performed and the standard output of the command is written to file **f** . If **~stderr:f** is given, a redirection **2> f** is performed and the standard error of the command is written to file **f** . If both **~stdout:f** and **~stderr:f** are given, with the exact same file name **f** , a **2>&1** redirection is performed so that the standard output and the standard error of the command are interleaved and redirected to the same file **f** .

Under Unix and Cygwin, the command, the arguments, and the redirections if any are quoted using **Filename.quote** , then concatenated. Under Win32, additional quoting is performed as required by the **cmd.exe** shell that is called by **Sys.command** .

**Since** 4.10

**Raises Failure** if the command cannot be escaped on the current platform.

2026-09-04 OCamldoc

---

Document: Filename(3o) from ocaml 5.5.1-r0 (Chainguard OS)
Source: https://github.com/ocaml/ocaml