truncate(S)

truncate, truncate64, ftruncate, ftruncate64 -- set a file to a specified length

Synopsis

   #include <unistd.h>
   
   int truncate (const char path, off_t length);
   

   int truncate64 (const char path, off64_t length);
   

   int ftruncate (int fildes, off_t length);
   

   int ftruncate64 (int fildes, off64_t length);

Description

The file whose name is given by path or referenced by the descriptor fildes has its size set to length bytes.

If the file was previously longer than length, bytes past length will no longer be accessible. If it was shorter, bytes from the EOF before the call to the EOF after the call will be read in as zeros. The effective user ID of the process must have write permission for the file, and for ftruncate the file must be open for writing.

Return values

Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 is returned and errno is set to indicate the error.

truncate and truncate64 fail if one or more of the following are true:

EACCES: Search permission is denied on a component of the path prefix.
EACCES: Write permission is denied for the file referred to by path.
EFAULT: path points outside the process's allocated address space.
EFBIG: An attempt is made to write a file that exceeds the process's file size limit or the maximum file size (see getrlimit(S) and ulimit(S)).
EINTR: A signal was caught during execution of the truncate or truncate64 routines.
EINVAL: path is not an ordinary file.
EIO: An I/O error occurred while reading from or writing to the file system.
EISDIR: The file referred to by path is a directory.
ELOOP: Too many symbolic links were encountered in translating path.
EMFILE: The maximum number of file descriptors available to the process has been reached.
EMULTIHOP: Components of path require hopping to multiple remote machines and file system type does not allow it.
ENAMETOOLONG: The length of a path component exceeds {NAME_MAX} characters, or the length of path exceeds {PATH_MAX} characters.
ENFILE: Could not allocate any more space for the system file table.
ENOENT: Either a component of the path prefix or the file referred to by path does not exist.
ENOLINK: path points to a remote machine and the link to that machine is no longer active.
ENOTDIR: A component of the path prefix of path is not a directory.
EROFS: The file referred to by path resides on a read-only file system.
ETXTBSY: The file referred to by path is a pure procedure (shared text) file that is being executed.

ftruncate fails if the following is true:

EFBIG: The file is a regular file and length is greater than the offset maximum established in the open file descriptor associated with fildes.

ftruncate and ftruncate64 fail if one or more of the following are true:

EAGAIN: The file exists, mandatory file/record locking is set, and there are outstanding record locks on the file (see chmod(S)).
EBADF: fildes is not a file descriptor open for writing.
EINTR: A signal was caught during execution of the ftruncate or ftruncate64 routines.
EIO: An I/O error occurred while reading from or writing to the file system.
ENOLINK: fildes points to a remote machine and the link to that machine is no longer active.
EINVAL: fildes does not correspond to an ordinary file.

In general, the system supports blocking truncates, as described in fcntl(S), which may result in EDEADLK being set.

References

fcntl(S), intro(S), open(S)

Notices

Considerations for large file support

truncate64 and ftruncate64 support large files, but are otherwise identical to truncate and ftruncate, respectively. For details on programming for large file capable applications, see ``Large File Support'' on intro(S).