man ftruncate (2): обрезает файл до заданного размера

Other Alias

truncate

ОБЗОР

#include <unistd.h>
#include <sys/types.h>

int truncate(const char *path, off_t length);
int ftruncate(int fd, off_t length);

Требования макроса тестирования свойств для glibc (см. feature_test_macros(7)):

truncate():

: _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* начиная с glibc 2.12: */ _POSIX_C_SOURCE >= 200809L

ftruncate():

: _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
|| /* начиная с glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L

ОПИСАНИЕ

Функции truncate() и ftruncate() обрезают обычный файл, указанный по имени path или ссылке fd, до размера, указанного в length (в байтах).

Если до этого файл был больше указанного размера, все лишние данные будут утеряны. Если файл был меньше, он будет увеличен, а дополнительная часть будет заполнена нулевыми байтами («\0»).

Смещение файла не изменяется.

Если размер изменился, поля st_ctime и st_mtime (время последнего изменения состояния и время последнего изменения, соответственно; смотрите stat(2)) файла будут обновлены, а биты режимов set-user-ID и set-group-ID могут быть сброшены.

Для ftruncate() файл должен быть открыт на запись; для truncate() файл должен быть доступен на запись.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

При успешном выполнении возвращается 0. В случае ошибки возвращается -1, а errno устанавливается в соответствующее значение.

ОШИБКИ

Для truncate():

EACCES: В одном из каталогов префикса не разрешен поиск, либо указанный файл не доступен на запись для пользователя (смотрите также path_resolution(7)).
EFAULT: Значение path указывает за пределы адресного пространства, выделенного процессу.
EFBIG: Аргумент length больше максимально допустимого размера файла (XSI).
EINTR: При блокирующем ожидании завершения вызов был прерван обработчиком сигналов; смотрите fcntl(2) и signal(7).
EINVAL: Аргумент length является отрицательным или больше максимально допустимого размера файла.
EIO: Во время обновления индексного дескриптора (inode) возникла ошибка ввода/вывода.
EISDIR: Указанный файл является каталогом.
ELOOP: Во время определения pathname встретилось слишком много символьных ссылок.
ENAMETOOLONG: Компонент имени пути содержит более 255 символов, или весь путь содержит более 1023 символов.
ENOENT: Указанный файл не существует.
ENOTDIR: Компонент в префиксе пути не является каталогом.
EPERM: Используемая файловая система не поддерживает расширение файла больше его текущего размера.
EPERM: Выполнение операции предотвращено опечатыванием (file seal); смотрите fcntl(2).
EROFS: Указанный файл находится на файловой системе, смонтированной только для чтения.
ETXTBSY: Файл является исполняемым файлом, который в данный момент исполняется.

Для ftruncate() действуют те же ошибки, за исключением того, что вместо ошибок, связанных с неправильным path, появляются ошибки, связанные с файловым дескриптором fd:

EBADF: Значение fd не является правильным файловым дескриптором.
EBADF или EINVAL: Дескриптор fd не открыт для записи.
EINVAL: Дескриптор fd не указывает на обычный файл.
EINVAL или EBADF: Файловый дескриптор fd не открыт на запись. В POSIX это допускается и переносимые приложения должны обрабатывать любую ошибку для этого случая (Linux возвращает EINVAL).

СООТВЕТСТВИЕ СТАНДАРТАМ

POSIX.1-2001, POSIX.1-2008, 4.4BSD, SVr4 (данные вызовы впервые появились в 4.2BSD).

ЗАМЕЧАНИЯ

В ОПИСАНИИ приведена информация для XSI-совместимых систем. Для не XSI-совместимых систем в стандарте POSIX описано два поведения ftruncate(), когда length превышает длину файла (заметим, что truncate() не обязательно быть во всех таких окружениях): или вернуть ошибку, или расширить файл. Подобно большинству реализаций UNIX, Linux соответствует требованию XSI, когда работает с родными файловыми системами. Однако, в некоторых неродных файловых системах не разрешается использовать truncate() и ftruncate() для расширения файла больше его текущей длины: например, в Linux это касается VFAT.

Первоначальные версии системных вызовов truncate() и ftruncate() в Linux не умели работать с большими файловыми смещениями. Позднее, в Linux 2.4 были добавлены системные вызовы truncate64() и ftruncate64() для работы с большими файлами. Однако это различие может игнорироваться приложениями, которые используют glibc, так как имеющиеся в ней обёрточные функции самостоятельно задействуют более новый системный вызов, если он доступен.

На некоторых 32-битных архитектурах интерфейс этих системных вызовов отличается от описанного выше по причинам, указанным в syscall(2).

ДЕФЕКТЫ

Из-за ошибки в заголовочном файле glibc 2.12 минимальное значение _POSIX_C_SOURCE, требуемое для объявления декларации ftruncate(), было равно 200809L вместо 200112L. В последующих версиях glibc эта ошибка была исправлена.