truncate, truncate64, ftruncate, or ftruncate64 Subroutine

Edit online

Purpose

Changes the length of regular files or shared memory object.

Library

Standard C Library (libc.a)

Syntax

#include <unistd.h>
int truncate ( Path,  Length)
const   char *Path;
off_t Length;
int ftruncate ( FileDescriptor, Length)
int FileDescriptor;
off_t Length;
int truncate64 ( Path,  Length)
const   char *Path;
off64_t Length;
int ftruncate64 ( FileDescriptor, Length)
int FileDescriptor;
off64_t Length;

Description

The truncate and ftruncate subroutines change the length of regular files or shared memory object.

The Path parameter must point to a regular file for which the calling process has write permission. The Length parameter specifies the wanted length of the new file in bytes.

The Length parameter measures the specified file in bytes from the beginning of the file. If the new length is less than the previous length, all data between the new length and the previous end of file is removed. If the new length in the specified file is greater than the previous length, data between the old and new lengths is read as zeros. Full blocks are returned to the file system so that they can be used again, and the file size is changed to the value of the Length parameter.

If the file designated in the Path parameter names a symbolic link, the link is traversed and path name resolution continues.

These subroutines do not modify the seek pointer of the file.

These subroutines cannot be applied to a file that a process has open with the O_DEFER flag.

Successful completion of the truncate or ftruncate subroutine updates the st_ctime and st_mtime fields of the file. Successful completion also clears the SetUserID bit (S_ISUID) of the file if any of the following are true:

  • The calling process does not have root user authority.
  • The effective user ID of the calling process does not match the user ID of the file.
  • The file is executable by the group (S_IXGRP) or others (S_IXOTH).

These subroutines also clear the SetGroupID bit (S_ISGID) if the following conditions are true:

  • The file does not match the effective group ID or one of the supplementary group IDs of the process
  • OR
  • The file is executable by the owner (S_IXUSR) or others (S_IXOTH).
    Note: Clearing of the SetUserID and SetGroupID bits can occur even if the subroutine fails because the data in the file was modified before the error was detected.

truncate and ftruncate can be used to specify any size up to OFF_MAX. truncate64 and ftruncate64 can be used to specify any length up to the maximum file size for the file.

In the large file enabled programming environment, truncate is redefined to be truncate64 and ftruncate is redefined to be ftruncate64.

Parameters

Item Description
Path Specifies the name of a file that is opened, truncated, and then closed.
FileDescriptor Specifies the descriptor of a file or shared memory object that must be open for writing.
Length Specifies the new length of the truncated file in bytes.

Return Values

Upon successful completion, a value of 0 is returned. If the truncate or ftruncate subroutine is unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the nature of the error.

Error Codes

The truncate and ftruncate subroutines fail if the following is true:

Item Description
EROFS An attempt was made to truncate a file that occupies a read-only file system.
Note: In addition, the truncate subroutine can return the same errors as the open subroutine if a problem occurs while the file is being opened.

The truncate and ftruncate subroutines fail if one of the following is true:

Item Description
EAGAIN The truncation operation fails when an enforced write lock on a portion of the file that is being truncated. Because the target file was opened with the O_NONBLOCK or O_NDELAY flags set, the subroutine fails immediately rather than wait for a release.
EDQUOT New disk blocks cannot be allocated for the truncated file. The quota of the user's or group's allotted disk blocks was exhausted on the target file system.
EFBIG An attempt was made to write a file that exceeds the process' file size limit or the maximum file size. If the user environment variable XPG_SUS_ENV=ON is set before execution of the process, then the SIGXFSZ signal is posted to the process when it exceeds the process' file size limit.
EFBIG The file is a regular file and length is greater than the offset maximum established in the open file description that is associated with fildes.
EINVAL The file is not a regular file.
EINVAL The Length parameter was less than zero.
EISDIR The named file is a directory.
EINTR A signal was caught during execution.
EIO An I/O error occurred while reading from or writing to the file system.
EMFILE The file is open with O_DEFER by one or more processes.
ENOSPC New disk blocks cannot be allocated for the truncated file. There is no free space on the file system that contains the file.
ETXTBSY The file is part of a process that is running.
EROFS The named file occupies a read-only file system.
Note:
  1. The truncate subroutine can also be unsuccessful for other reasons. For a list of more errors, see Base Operating System error codes for services that require path-name resolution.
  2. The truncate subroutine can return the same errors as the open subroutine if a problem occurs while the file is being opened.

The ftruncate subroutine fails if the following is true:

Item Description
EBADF The FileDescriptor parameter is not a valid file descriptor open for writing.
EINVAL The FileDescriptor argument references a file that was opened without write permission.

The truncate function fails if the following conditions are true:

Item Description
EACCES A component of the path prefix denies search permission, or write permission is denied on the file.
EISDIR The named file is a directory.
ELOOP Too many symbolic links were encountered in resolving path.
ENAMETOOLONG The length of the specified path name exceeds PATH_MAX bytes, or the length of a component of the path name exceeds NAME_MAX bytes.
ENOENT A component of path does not name an existing file or path is an empty string.
ENTDIR A component of the path prefix of path is not a directory.
EROFS The named file occupies a read-only file system.  

The truncate function fails if the following is true:

Item Description
ENAMETOOLONG Path name resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.