# Files

Functions for working with files and directories are described here.

* [AppendFile( str filename, buf | str data )](/stdlib/file.md#appendfile-str-filename-buf-or-str-data)
* [ChDir( str dirname )](/stdlib/file.md#chdir-str-dirname)
* [ChMode( str name, int mode )](/stdlib/file.md#chmode-str-name-int-mode)
* [CloseFile( file f )](/stdlib/file.md#closefile-file-f)
* [CopyFile( str src, str dest ) int](/stdlib/file.md#copyfile-str-src-str-dest-int)
* [CreateDir( str dirname )](/stdlib/file.md#createdir-str-dirname)
* [CreateFile( str name, bool trunc )](/stdlib/file.md#createfile-str-name-bool-trunc)
* [ExistFile( str name ) bool](/stdlib/file.md#existfile-str-name-bool)
* [FileInfo( file f ) finfo](/stdlib/file.md#fileinfo-file-f-finfo)
* [FileInfo( str name ) finfo](/stdlib/file.md#fileinfo-str-name-finfo)
* [FileMode( str name ) int](/stdlib/file.md#filemode-str-name-int)
* [GetCurDir() str](/stdlib/file.md#getcurdir-str)
* [IsEmptyDir( str path ) bool](/stdlib/file.md#isemptydir-str-path-bool)
* [Md5File( str filename ) str](/stdlib/file.md#md-5-file-str-filename-str)
* [obj( finfo fi ) obj](/stdlib/file.md#obj-finfo-fi-obj)
* [OpenFile( str filename, int flags ) file](/stdlib/file.md#openfile-str-filename-int-flags-file)
* [Read( file f, int size ) buf](/stdlib/file.md#read-file-f-int-size-buf)
* [ReadDir( str dirname ) arr.finfo](/stdlib/file.md#readdir-str-dirname-arr-finfo)
* [ReadDir( str dirname, int flags, str pattern ) arr.finfo](/stdlib/file.md#readdir-str-dirname-int-flags-str-pattern-arr-finfo)
* [ReadDir( str dirname, int flags, arr.str patterns, arr.str ignore ) arr.finfo](/stdlib/file.md#readdir-str-dirname-int-flags-arr-str-patterns-arr-str-ignore-arr-finfo)
* [ReadFile( str filename ) str](/stdlib/file.md#readfile-str-filename-str)
* [ReadFile( str filename, buf out ) buf](/stdlib/file.md#readfile-str-filename-buf-out-buf)
* [ReadFile( str filename, int offset, int length ) buf](/stdlib/file.md#readfile-str-filename-int-offset-int-length-buf)
* [Remove( str name )](/stdlib/file.md#remove-str-name)
* [RemoveDir( str dirname )](/stdlib/file.md#removedir-str-dirname)
* [Rename( str oldpath, str newpath )](/stdlib/file.md#rename-str-oldpath-str-newpath)
* [SetFileTime( str name, time modtime )](/stdlib/file.md#setfiletime-str-name-time-modtime)
* [SetPos( file f, int off, int whence ) int](/stdlib/file.md#setpos-file-f-int-off-int-whence-int)
* [Sha256File( str filename ) str](/stdlib/file.md#sha-256-file-str-filename-str)
* [TempDir() str](/stdlib/file.md#tempdir-str)
* [TempDir( str path, str prefix ) str](/stdlib/file.md#tempdir-str-path-str-prefix-str)
* [Write( file f, buf b ) file](/stdlib/file.md#write-file-f-buf-b-file)
* [WriteFile( str filename, buf | str data )](/stdlib/file.md#writefile-str-filename-buf-or-str-data)

## Types

### finfo

The *finfo* is used for getting information about a file and has the following fields:

* **str Name** - base name of the file
* **int Size** - length in bytes for regular files
* **int Mode** - file's mode and permission bits
* **time Time** - last modification time
* **bool IsDir** - true if it is a directory
* **str Dir** - directory where the file is located. This field is only filled when calling the function [ReadDir(str, int, str)](/stdlib/file.md#readdir-str-dirname-int-flags-str-pattern-arr-finfo)

### file

The *file* type is used in functions that work with the open file descriptor.

## Functions

### AppendFile(str filename, buf|str data)

The *AppendFile* function appends data of *buf* variable or a string to a file named by *filename*. If the file does not exist, *AppendFile* creates it with 0644 permissions.

### ChDir(str dirname)

The *ChDir* function changes the current directory.

### ChMode(str name, int mode)

The *ChMode* function changes the attributes of the file.

### CloseFile(file f)

The *CloseFile* function closes the file descriptor that was opened with the **OpenFile** function.

### CopyFile(str src, str dest) int

The *CopyFile* function copies *src* file to *dest* file. If *dest* file exists it is overwritten. The file attributes are preserved when copying. The function returns the number of copied bytes.

### CreateDir(str dirname)

The *CreateDir* function creates a directory named *dirname*, along with any necessary parents. If *dirname* is already a directory, *CreateDir* does nothing.

### CreateFile(str name, bool trunc)

The *CreateFile* function creates a file with the specified name. If the *trunc* parameter is *true* and the file already exists, its size becomes 0.

### ExistFile(str name) bool

The *ExistFile* function returns *true* if the specified file or directory exists. Otherwise, it returns *false*.

### FileInfo(file f) finfo

The *FileInfo* function receives information about the specified file and returns the *finfo* structure. The file must be opened using the **OpenFile** function.

### FileInfo(str name) finfo

The *FileInfo* function gets information about the named file and returns *finfo* structure.

### FileMode(str name) int

The *FileMode* function returns the file attributes.

### GetCurDir() str

The *GetCurDir* function returns the current directory.

### IsEmptyDir(str path) bool

The *IsEmptyDir* function returns *true* if the specified directory is empty. Otherwise, it returns *false*.

### Md5File(str filename) str

The *Md5File* function returns the MD5 hash of the specified file as a hex string.

### obj(finfo fi) obj

The *obj* function converts a variable of finfo type into an object. The resulting object has fields: *name, size, mode, time, isdir, dir*.

### OpenFile(str filename, int flags) file

The *OpenFile* function opens the specified file and returns a variable of *file* type with an open file descriptor. After working with the file, the open file descriptor must be closed using the **CloseFile** function. The *flags* parameter may be zero or a combination of the following flags:

* *CREATE* - if the file does not exist, it will be created.
* *TRUNC* - file will be truncated to zero length after opening.
* *READONLY* - the file will be open for reading only.

```go
    file f = OpenFile(fname, CREATE)
    Write(f, buf("some test string"))
    SetPos(f, -15, 1)
    buf b &= Read(f, 5)
    CloseFile(f)
```

### Read(file f, int size) buf

The *Read* function reads the *size* number of bytes from the current position in the file that was opened using the **OpenFile** function. The function returns a variable of the *buf* type, which contains the read data.

### ReadDir(str dirname) arr.finfo

The *ReadDir* function reads the directory named by dirname and returns a list of directories and files entries.

### ReadDir(str dirname, int flags, str pattern) arr.finfo

The *ReadDir* function reads the *dirname* directory with the specified name and returns the list of its subdirectories and files according to the specified parameters. The *flags* parameter can be a combination of the following flags:

* **RECURSIVE** - In this case there will be a recursive search for all subdirectories.
* **ONLYFILES** - The returned array will contain only files.
* **ONLYDIRS** - The returned array will contain only directories.
* **REGEXP** - The *pattern* parameter contains a regular expression for matching file names.

If you specify the **ONLYFILES** and **ONLYDIRS** flags at the same time, the files and directories will be searched.

The *pattern* parameter can contain a wildcard for files or a regular expression. In this case, the files and directories that match the specified pattern will be returned. The wildcard can contain the following characters:

* '\*' - matches any sequence of non-separator characters
* '?' - matches any single non-separator character

```go
for item in ReadDir(ftemp, RECURSIVE, `*fold*`) {
    ret += item.Name
}
for item in ReadDir(ftemp, RECURSIVE | ONLYFILES | REGEXP, `.*\.pdf`) {
    ret += item.Name
}
```

### ReadDir(str dirname, int flags, arr.str patterns, arr.str ignore) arr.finfo

The *ReadDir* function reads the *dirname* directory with the specified name and returns the list of its subdirectories and files according to the specified parameters. The parameter *flags* is described above. The *patterns* parameter is an array of strings and may contain file masks or regular expressions. The *ignore* parameter also contains file wildcards or regular expressions, but such files or directories will be skipped. If you want to specify a regular expression in these arrays, enclose it between **'/'** characters.

```go
arr.str aignore = {`/txt/`, `*.pak`}
arr.str amatch = {`/\d+/`, `*.p?`, `/di/`}.
for item in ReadDir(ftemp, RECURSIVE, amatch, aignore) {
    ret += item.Name
}
```

### ReadFile(str filename) str

The *ReadFile* function reads the specified file and returns the contents as a string.

### ReadFile(str filename, buf out) buf

The *ReadFile* function reads the file named by *filename* to the *buf* variable *out* and returns it.

### ReadFile(str filename, int offset, int length) buf

The *ReadFile* function reads data from the *filename* file starting at offset *offset* and length *length*. If *offset* is less than zero, then the offset is counted from the end to the beginning of the file.

### Remove(str name)

The *Remove* function removes a file or an empty directory.

### RemoveDir(str dirname)

The *RemoveDir* function removes *dirname* directory and any children it contains.

### Rename(str oldpath, str newpath)

The *Rename* function renames (moves) *oldpath* to *newpath*. If *newpath* already exists and is not a directory, *Rename* replaces it.

### SetFileTime(str name, time modtime)

The *SetFileTime* function changes the modification time of the named file.

### SetPos(file f, int off, int whence) int

The *SetPos* function sets the current position in the file for read or write operations. The file must be opened with the **OpenFile** function. The function returns the offset of the new position. The *whence* parameter can take the following values:

* *0* - the *off* offset is specified from the beginning of file.
* *1* - the *off* offset is specified from the current position.
* *2* - the *off* offset is specified from the end of a file.

### Sha256File(str filename) str

The *Sha256File* function returns the SHA256 hash of the specified file as a hex string.

### TempDir() str

The *TempDir* function returns the default temporary directory.

### TempDir(str path, str prefix) str

The *TempDir* function creates a new temporary directory in the directory *path* with a name beginning with *prefix* and returns the path of the new directory. If *path* is the empty string, *TempDir* uses the default temporary directory.

### Write(file f, buf b) file

The *Write* function writes data from a variable of the *buf* type to a file that was opened using the **OpenFile** function. The function returns the *f* parameter.

### WriteFile(str filename, buf|str data)

The *WriteFile* function writes data of *buf* variable or a string to a file named by *filename*. If the file does not exist, *WriteFile* creates it with 0777 permissions, otherwise the file is truncated before writing.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gentee.org/stdlib/file.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.