# Файлы

Ниже описаны функции для работы с файлами и директориями.

* [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)

## Типы

### finfo

Тип *finfo* используется для получения информации о файле и имеет следующие поля:

* **str Name** - имя файла
* **int Size** - размер файла в байтах
* **int Mode** - флаги файла и разрешения
* **time Time** - время последнего изменения
* **bool IsDir** - true, если это директория
* **str Dir** - директория, где расположен файл. Данное поле заполняется только при вызове функции [ReadDir(str, int, str)](/stdlib/file.md#readdir-str-dirname-int-flags-str-pattern-arr-finfo).

### file

Тип *file* используется в функциях, которые работают с дескриптором открытого файла.

## Функции

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

Функция *AppendFile* добавляет данные переменной типа *buf* или *str* в конец файла *filename*. Если файл не существует, то *AppendFile* создает его с правами 0644.

### ChDir(str dirname)

Функция *ChDir* изменяет текущую директорию.

### ChMode(str name, int mode)

Функция *ChMode* изменяет атрибуты файла.

### CloseFile(file f)

Функция *CloseFile* закрывает дескриптор файла, который был открыт с помощью функции **OpenFile**.

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

Функция *CopyFile* копирует файл *src* в файл *dest*. Если файл *dest* существует, то он будет перезаписан. При копировании сохраняются атрибуты файла. Функция возвращает количество скопированных байт.

### CreateDir(str dirname)

Функция *CreateDir* создает директорию с именем *dirname*, включая все необходимые родительские директории. Если *dirname* уже существующая директория, то *CreateDir* ничего не делает.

### CreateFile(str name, bool trunc)

Функция *CreateFile* создает файл с указанным именем. Если параметр *trunc* равен *true* и файл уже существует, то в этом случае его размер станет 0.

### ExistFile(str name) bool

Функция *ExistFile* возвращает *true*, если указанный файл или директория существует. В противном случае, возвращается *false*.

### FileInfo(file f) finfo

Функция *FileInfo* получает информацию об указанном файле и возвращает структуру *finfo*. Файл должен быть октрыт с помощью функции **OpenFile**.

### FileInfo(str name) finfo

Функция *FileInfo* получает информацию об указанном файле и возвращает структуру *finfo*.

### FileMode(str name) int

Функция *FileMode* возвращает атрибуты файла.

### GetCurDir() str

Функция *GetCurDir* возвращает текущую директорию.

### IsEmptyDir(str path) bool

Функция *IsEmptyDir* возвращает *true*, если указанная директория пустая. В противном случае, возвращается *false*.

### Md5File(str filename) str

Функция *Md5File* возвращает MD5 хэш указанного файла в виде шестнадцатеричной строки.

### obj(finfo fi) obj

Функция *obj* конвертирует переменную типа finfo в объект. Полученный объект имеет поля: *name, size, mode, time, isdir, dir*.

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

Функция *OpenFile* открывает указанный файл и возвращает переменную типа *file* с дескриптором открытого файла. После работы с файлом дескриптор открытого файла должен быть закрыт с помощью функции **CloseFile**. Параметр *flags* может быть нулем или комбинацией следующих флагов:

* *CREATE* - если файл не существует, то он будет создан.
* *TRUNC* - файл будет обрезан до нулевой длины после открытия.
* *READONLY* - файл будет открыт только для чтения.

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

Функция *Read* читает *size* количество байт с текущей позиции в файле, который был открыт с помощью функции **OpenFile**. Функция возвращает переменную типа *buf*, которая содержит прочитанные данные.

### ReadDir(str dirname) arr.finfo

Функция *ReadDir* читает директорию с указанным именем и возвращает список её поддиректорий и файлов.

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

Функция *ReadDir* читает директорию *dirname* с указанным именем и возвращает список её поддиректорий и файлов в соотвествии с указанными параметрами. Параметр *flags* может быть комбинацией следующих флагов:

* **RECURSIVE** - В этом случае будет рекурсивный поиск по всем поддиректориям.
* **ONLYFILES** - Возвращаемый массив будет содержать только файлы.
* **ONLYDIRS** - Возвращаемый массив будет содержать только директории.
* **REGEXP** - Параметр *pattern* содержит регулярное выражения для сравнения имён файлов.

Если вы укажете одновременно флаги **ONLYFILES** и **ONLYDIRS**, то будут искаться файлы и директории.

Параметр *pattern* может содержать маску для файлов или регулярное выражение. В этом случае, будут возвращаться файлы и директории, которые соответствуют указанному шаблону. Маска может содержать следующие символы:

* '\*' - любая последовательность, кроме символа разделителя
* '?' - любой одиночный символ, кроме символа разделителя

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

Функция *ReadDir* читает директорию *dirname* с указанным именем и возвращает список её поддиректорий и файлов в соотвествии с указанными параметрами. Параметр *flags* описан выше. Параметр *patterns* является массивом строк и может содержать маски для файлов или регулярные выражения. Параметр *ignore* также содержит маски для файлов или регулярные выражения, но такие файлы или директории будут пропускаться. Если вы хотите указать в этих массивах регулярное выражение, то заключите его между символами **'/'**.

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

Функция *ReadFile* читает указанный файл и возвращает его содержимое в виде строки.

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

Функция *ReadFile* читает файл *filename* в переменную *out* типа *buf* и возвращает эту переменную.

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

Функция *ReadFile* читает данные из файла *filename* начиная со смещения *offset* и длиной *length*. Если *offset* меньше нуля, то смещение считается от конца к началу файла.

### Remove(str name)

Функция *Remove* удаляет файл или пустую директорию.

### RemoveDir(str dirname)

Функция *RemoveDir* удаляет директорию *dirname* включая всё её содержимое.

### Rename(str oldpath, str newpath)

Функция *Rename* переименовывает (переносит) *oldpath* в *newpath*. Если *newpath* уже существует и является файлом, то *Rename* заменяет его.

### SetFileTime(str name, time modtime)

Функция *SetFileTime* изменяет время последней записи у указанного файла.

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

Функция *SetPos* устанавливает в файле текущую позицию для операций чтения или записи. Файл должен быть открыт с помощью функции **OpenFile**. Функция возвращает смещение новой позиции. Параметр *whence* может принимать следующие значения:

* *0* - смещение *off* указано от начало файла.
* *1* - смещение *off* указано от текущей позиции.
* *2* - смещение *off* указано от конца файла.

### Sha256File(str filename) str

Функция *Sha256File* возвращает SHA256 хэш указанного файла в виде шестнадцатеричной строки.

### TempDir() str

Функция *TempDir* возвращает временную директорию по умолчанию.

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

Функция *TempDir* создает новую временную директорию в директории *path* с именем, начинающемся на *prefix* и возвращает полное имя этой новой директории. Если *path* пустая строка, *TempDir* использует временную директорию по умолчанию.

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

Функция *Write* записывает данные из переменной типа *buf* в файл, который был открыт с помощью функции **OpenFile**. Функция возвращает параметр *f*.

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

Функция *WriteFile* записывает данные из переменной типа *buf* или строки в файл *filename*. Если файл не существует, то он будет создан с разрешениями 0777, в противном случае, файл будет перезаписан заново.


---

# 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://ru.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.