.Dt TRUNCATE 2
.Os BSD 4.2
.Sh NAME
-.Nm truncate ,
-.Nm ftruncate
+.Nm ftruncate ,
+.Nm truncate
.Nd truncate or extend a file to a specified length
.Sh SYNOPSIS
.Fd #include <unistd.h>
.Ft int
-.Fn truncate "const char *path" "off_t length"
+.Fo ftruncate
+.Fa "int fildes"
+.Fa "off_t length"
+.Fc
.Ft int
-.Fn ftruncate "int fd" "off_t length"
+.Fo truncate
+.Fa "const char *path"
+.Fa "off_t length"
+.Fc
.Sh DESCRIPTION
-.Fn Truncate
-causes the file named by
-.Fa path
+.Fn ftruncate
+and
+.Fn truncate
+cause the file named by
+.Fa path ,
or referenced by
-.Fa fd
-to be truncated or extended to
+.Fa fildes ,
+to be truncated (or extended) to
.Fa length
-bytes in size. If the file previously
-was larger than this size, the extra data
-is lost. If the file was smaller than this size, it will be extended as
-if by writing bytes with the value zero.
-With
-.Fn ftruncate ,
-the file must be open for writing.
+bytes in size. If the file size exceeds
+.Fa length ,
+any extra data is discarded. If the file size is smaller than
+.Fa length ,
+the file is extended and filled with zeros to the indicated length.
+The
+.Fn ftruncate
+form requires the file to be open for writing.
+.Pp
+Note:
+.Fn ftruncate
+and
+.Fn truncate
+do not modify the current file offset for any open file descriptions associated with the file.
.Sh RETURN VALUES
A value of 0 is returned if the call succeeds. If the call
fails a -1 is returned, and the global variable
.Va errno
specifies the error.
.Sh ERRORS
-.Fn Truncate
-succeeds unless:
+.Pp
+The
+.Fn ftruncate
+system call will fail if:
.Bl -tag -width Er
-.It Bq Er ENOTDIR
-A component of the path prefix is not a directory.
-.It Bq Er ENAMETOOLONG
-A component of a pathname exceeded
-.Dv {NAME_MAX}
-characters, or an entire path name exceeded
-.Dv {PATH_MAX}
-characters.
-.It Bq Er ENOENT
-The named file does not exist.
+.\" ===========
+.It Bq Er EBADF
+.Fa fildes
+is not a valid descriptor open for writing.
+.\" ===========
+.It Bq Er EFBIG
+The file is a regular file and
+.Fa length
+is greater than the offset maximum established
+in the open file description associated with
+.Fa fildes .
+.\" ===========
+.It Bq Er EINVAL
+.Fa fildes
+references a socket, not a file.
+.\" ===========
+.It Bq Er EINVAL
+.Fa fildes
+is not open for writing.
+.\" ===========
+.It Bq Er EROFS
+The named file resides on a read-only file system.
+.El
+.Pp
+The
+.Fn truncate
+system call will fail if:
+.Bl -tag -width Er
+.\" ===========
.It Bq Er EACCES
Search permission is denied for a component of the path prefix.
+.\" ===========
.It Bq Er EACCES
The named file is not writable by the user.
-.It Bq Er ELOOP
-Too many symbolic links were encountered in translating the pathname.
+.\" ===========
+.It Bq Er EFAULT
+.Fa Path
+points outside the process's allocated address space.
+.\" ===========
.It Bq Er EISDIR
The named file is a directory.
+.\" ===========
+.It Bq Er ELOOP
+Too many symbolic links are encountered in translating the pathname.
+This is taken to be indicative of a looping symbolic link.
+.\" ===========
+.It Bq Er ENAMETOOLONG
+A component of a pathname exceeds
+.Dv {NAME_MAX}
+characters, or an entire path name exceeds
+.Dv {PATH_MAX}
+characters.
+.\" ===========
+.It Bq Er ENOENT
+The named file does not exist.
+.\" ===========
+.It Bq Er ENOTDIR
+A component of the path prefix is not a directory.
+.\" ===========
.It Bq Er EROFS
The named file resides on a read-only file system.
+.\" ===========
.It Bq Er ETXTBSY
The file is a pure procedure (shared text) file that is being executed.
-.It Bq Er EIO
-An I/O error occurred updating the inode.
-.It Bq Er EFAULT
-.Fa Path
-points outside the process's allocated address space.
.El
.Pp
-.Fn Ftruncate
-succeeds unless:
-.Bl -tag -width Er
-.It Bq Er EBADF
-The
-.Fa fd
-is not a valid descriptor.
-.It Bq Er EINVAL
The
-.Fa fd
-references a socket, not a file.
+.Fn ftruncate
+and
+.Fn truncate
+system calls will fail if:
+.Bl -tag -width Er
+.\" ===========
+.It Bq Er EFBIG
+The length argument was greater than the maximum file size.
+.\" ===========
+.It Bq Er EINTR
+A signal is caught during execution.
+.\" ===========
.It Bq Er EINVAL
The
-.Fa fd
-is not open for writing.
+.Fa length
+argument is less than 0.
+.\" ===========
+.It Bq Er EIO
+An I/O error occurred while reading from or writing to a file system.
.El
.Sh SEE ALSO
.Xr open 2
projects / apple / xnu.git / blobdiff