Change the size of a file

In some situations it is useful to explicitly determine the size of a file. Since the 4.2BSD days there is a function to truncate a file to at most a given number of bytes and POSIX defines one additional function. The prototypes for these functions are in `unistd.h'.

Function: int truncate (const char *name, off_t length)

The truncation function truncates the file named by name to at most length bytes. I.e., if the file was larger before the extra bytes are stripped of. If the file was small or equal to length in size before nothing is done. The file must be writable by the user to perform this operation.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the truncate function is in fact truncate64 and the type off_t has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length.

The return value is zero is everything went ok. Otherwise the return value is @math{-1} and the global variable errno is set to:

EACCES

The file is not accessible to the user.

EINVAL

The length value is illegal.

EISDIR

The object named by name is a directory.

ENOENT

The file named by name does not exist.

ENOTDIR

One part of the name is not a directory.

This function was introduced in 4.2BSD but also was available in later System V systems. It is not added to POSIX since the authors felt it is only of marginally additional utility. See below.

Function: int truncate64 (const char *name, off64_t length)

This function is similar to the truncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines which allows to handle file with a size up to @math{2^63} bytes.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name truncate and so transparently replaces the 32 bits interface.

Function: int ftruncate (int fd, off_t length)

The ftruncate function is similar to the truncate function. The main difference is that it takes a descriptor for an opened file instead of a file name to identify the object. The file must be opened for writing to successfully carry out the operation.

The POSIX standard leaves it implementation defined what happens if the specified new length of the file is bigger than the original size. The ftruncate function might simply leave the file alone and do nothing or it can increase the size to the desired size. In this later case the extended area should be zero-filled. So using ftruncate is no reliable way to increase the file size but if it is possible it is probably the fastest way. The function also operates on POSIX shared memory segments if these are implemented by the system.

When the source file is compiled with _FILE_OFFSET_BITS == 64 the ftruncate function is in fact ftruncate64 and the type off_t has 64 bits which makes it possible to handle files up to @math{2^63} bytes in length.

On success the function returns zero. Otherwise it returns @math{-1} and set errno to one of these values:

EBADF

fd is no valid file descriptor or is not opened for writing.

EINVAL

The object referred to by fd does not permit this operation.

EROFS

The file is on a read-only file system.

Function: int ftruncate64 (int id, off64_t length)

This function is similar to the ftruncate function. The difference is that the length argument is 64 bits wide even on 32 bits machines which allows to handle file with a size up to @math{2^63} bytes.

When the source file is compiled with _FILE_OFFSET_BITS == 64 on a 32 bits machine this function is actually available under the name ftruncate and so transparently replaces the 32 bits interface.

Go to the first, previous, next, last section, table of contents.