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

.\"	$NetBSD: truncate.2,v 1.7 1995/02/27 12:39:00 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)truncate.2	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt TRUNCATE 2
.Os BSD 4.2
.Sh NAME
.Nm truncate ,
.Nm ftruncate
.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"
.Ft int
.Fn ftruncate "int fd" "off_t length"
.Sh DESCRIPTION
.Fn Truncate
causes the file named by
.Fa path
or referenced by
.Fa fd
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.
.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:
.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 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 EISDIR
The named file is 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.
.It Bq Er EINVAL
The
.Fa fd
is not open for writing.
.El
.Sh SEE ALSO
.Xr open 2
.Sh BUGS
These calls should be generalized to allow ranges
of bytes in a file to be discarded.
.Pp
Use of
.Fn truncate
to extend a file is not portable.
.Sh HISTORY
The
.Fn truncate
and
.Fn ftruncate
function calls appeared in
.Bx 4.2 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: truncate.2,v 1.7 1995/02/27 12:39:00 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1983, 1991, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)truncate.2 8.1 (Berkeley) 6/4/93
	35	.\"
	36	.Dd June 4, 1993
	37	.Dt TRUNCATE 2
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm truncate ,
	41	.Nm ftruncate
	42	.Nd truncate or extend a file to a specified length
	43	.Sh SYNOPSIS
	44	.Fd #include <unistd.h>
	45	.Ft int
	46	.Fn truncate "const char *path" "off_t length"
	47	.Ft int
	48	.Fn ftruncate "int fd" "off_t length"
	49	.Sh DESCRIPTION
	50	.Fn Truncate
	51	causes the file named by
	52	.Fa path
	53	or referenced by
	54	.Fa fd
	55	to be truncated or extended to
	56	.Fa length
	57	bytes in size. If the file previously
	58	was larger than this size, the extra data
	59	is lost. If the file was smaller than this size, it will be extended as
	60	if by writing bytes with the value zero.
	61	With
	62	.Fn ftruncate ,
	63	the file must be open for writing.
	64	.Sh RETURN VALUES
65	A value of 0 is returned if the call succeeds. If the call
66	fails a -1 is returned, and the global variable
67	.Va errno
68	specifies the error.
69	.Sh ERRORS
70	.Fn Truncate
71	succeeds unless:
72	.Bl -tag -width Er
73	.It Bq Er ENOTDIR
74	A component of the path prefix is not a directory.
75	.It Bq Er ENAMETOOLONG
76	A component of a pathname exceeded
77	.Dv {NAME_MAX}
78	characters, or an entire path name exceeded
79	.Dv {PATH_MAX}
80	characters.
81	.It Bq Er ENOENT
82	The named file does not exist.
83	.It Bq Er EACCES
84	Search permission is denied for a component of the path prefix.
85	.It Bq Er EACCES
86	The named file is not writable by the user.
87	.It Bq Er ELOOP
88	Too many symbolic links were encountered in translating the pathname.
89	.It Bq Er EISDIR
90	The named file is a directory.
91	.It Bq Er EROFS
92	The named file resides on a read-only file system.
93	.It Bq Er ETXTBSY
94	The file is a pure procedure (shared text) file that is being executed.
95	.It Bq Er EIO
96	An I/O error occurred updating the inode.
97	.It Bq Er EFAULT
98	.Fa Path
99	points outside the process's allocated address space.
100	.El
101	.Pp
102	.Fn Ftruncate
103	succeeds unless:
104	.Bl -tag -width Er
105	.It Bq Er EBADF
106	The
107	.Fa fd
108	is not a valid descriptor.
109	.It Bq Er EINVAL
110	The
111	.Fa fd
112	references a socket, not a file.
113	.It Bq Er EINVAL
114	The
115	.Fa fd
116	is not open for writing.
117	.El
118	.Sh SEE ALSO
119	.Xr open 2
120	.Sh BUGS
121	These calls should be generalized to allow ranges
122	of bytes in a file to be discarded.
123	.Pp
124	Use of
125	.Fn truncate
126	to extend a file is not portable.
127	.Sh HISTORY
128	The
129	.Fn truncate
130	and
131	.Fn ftruncate
132	function calls appeared in
133	.Bx 4.2 .