xnu-4903.270.47.tar.gz

[apple/xnu.git] / bsd / man / man2 / truncate.2

diff --git a/bsd/man/man2/truncate.2 b/bsd/man/man2/truncate.2
index d54ad08971f77bca9a0f4f2f8d021d35db159099..b82853d56289673e662941e88d52b15210e77c56 100644 (file)
--- a/bsd/man/man2/truncate.2
+++ b/bsd/man/man2/truncate.2
@@ -37,83 +37,142 @@
 .Dt TRUNCATE 2
 .Os BSD 4.2
 .Sh NAME
 .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
 .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
 .Ft int

-.Fn ftruncate "int fd" "off_t length"
+.Fo truncate
+.Fa "const char *path"
+.Fa "off_t length"
+.Fc

 .Sh DESCRIPTION
 .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
 or referenced by

-.Fa fd
-to be truncated or extended to
+.Fa fildes ,
+to be truncated (or extended) to

 .Fa length
 .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
 .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
 .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
 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 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 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 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 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
 .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
 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
 .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
 .El
 .Sh SEE ALSO
 .Xr open 2