[packages/man-pages.git] / truncate.2

.\" Copyright (c) 1983, 1991 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	6.9 (Berkeley) 3/10/91
.\"
.\" Modified Sat Jul 24 12:46:33 1993 by Rik Faith <faith@cs.unc.edu>
.\" Modified Tue Oct 22 22:36:33 1996 by Eric S. Raymond <esr@thyrsus.com>
.\" Modified Mon Dec 21 13:37:05 1998 by Andries Brouwer <aeb@cwi.nl>
.\" Modified 7 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
.\"
.TH TRUNCATE 2 1998-12-21 "" "Linux Programmer's Manual"
.SH NAME
truncate, ftruncate \- truncate a file to a specified length
.SH SYNOPSIS
.B #include <unistd.h>
.sp
.BI "int truncate(const char *" path ", off_t " length );
.br
.BI "int ftruncate(int " fd ", off_t " length );
.SH DESCRIPTION
The
.B truncate
and
.B ftruncate
functions cause the regular file named by
.I path
or referenced by
.I fd
to be truncated to a size of precisely
.I length
bytes.
.LP
If the file previously was larger than this size, the extra data is lost. 
If the file previously was shorter, it is extended, and
the extended part reads as zero bytes.
.LP
The file pointer is not changed.
.LP
With
.BR ftruncate ,
the file must be open for writing; with
.BR truncate ,
the file must be writable.
.SH "RETURN VALUE"
On success, zero is returned.  On error, \-1 is returned, and
.I errno
is set appropriately.
.SH ERRORS
For
.BR truncate :
.TP
.B EACCES
Search permission is denied for a component of the path prefix,
or the named file is not writable by the user.
.TP
.B EFAULT
.I Path
points outside the process's allocated address space.
.TP
.B EFBIG
The argument
.I length
is larger than the maximum file size. (XSI)
.TP
.B EINTR
A signal was caught during execution.
.TP
.B EINVAL
The argument
.I length
is negative or larger than the maximum file size.
.TP
.B EIO
An I/O error occurred updating the inode.
.TP
.B EISDIR
The named file is a directory.
.TP
.B ELOOP
Too many symbolic links were encountered in translating the pathname.
.TP
.B ENAMETOOLONG
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.TP
.B ENOENT
The named file does not exist.
.TP
.B ENOTDIR
A component of the path prefix is not a directory.
.TP
.B EROFS
The named file resides on a read-only file system.
.TP
.B ETXTBSY
The file is a pure procedure (shared text) file that is being executed.
.PP
For
.B ftruncate
the same errors apply, but instead of things that can be wrong with
.IR path ,
we now have things that can be wrong with
.IR fd :
.TP
.B EBADF
The
.I fd
is not a valid descriptor.
.TP
.BR EBADF " or " EINVAL
The
.I fd
is not open for writing.
.TP
.B EINVAL
The
.I fd
does not reference a regular file.
.SH "CONFORMING TO"
4.4BSD, SVr4 (these function calls first appeared in BSD 4.2).
POSIX 1003.1-1996 has
.BR ftruncate .
POSIX 1003.1-2001 also has
.IR truncate ,
as an XSI extension.
.LP
SVr4 documents additional
.B truncate
error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK.  SVr4 documents for
.B ftruncate
an additional EAGAIN error condition.
.SH NOTES
The above description is for XSI-compliant systems.
For non-XSI-compliant systems, the POSIX standard allows
two behaviours for
.B ftruncate
when
.I length
exceeds the file length
(note that
.B truncate
is not specified at all in such an environment):
either returning an error, or extending the file.
(Most Unices follow the XSI requirement.)
.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
.SH "SEE ALSO"
.BR open (2)
Commit	Line	Data
24b7bc57	1	.\" Copyright (c) 1983, 1991 The Regents of the University of California.
	2	.\" All rights reserved.
	3	.\"
	4	.\" Redistribution and use in source and binary forms, with or without
	5	.\" modification, are permitted provided that the following conditions
	6	.\" are met:
	7	.\" 1. Redistributions of source code must retain the above copyright
	8	.\" notice, this list of conditions and the following disclaimer.
	9	.\" 2. Redistributions in binary form must reproduce the above copyright
	10	.\" notice, this list of conditions and the following disclaimer in the
	11	.\" documentation and/or other materials provided with the distribution.
	12	.\" 3. All advertising materials mentioning features or use of this software
	13	.\" must display the following acknowledgement:
	14	.\" This product includes software developed by the University of
	15	.\" California, Berkeley and its contributors.
	16	.\" 4. Neither the name of the University nor the names of its contributors
	17	.\" may be used to endorse or promote products derived from this software
	18	.\" without specific prior written permission.
	19	.\"
	20	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	21	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	22	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	23	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	24	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	25	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	26	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	27	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	28	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	29	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	30	.\" SUCH DAMAGE.
	31	.\"
	32	.\" @(#)truncate.2 6.9 (Berkeley) 3/10/91
	33	.\"
	34	.\" Modified Sat Jul 24 12:46:33 1993 by Rik Faith <faith@cs.unc.edu>
	35	.\" Modified Tue Oct 22 22:36:33 1996 by Eric S. Raymond <esr@thyrsus.com>
	36	.\" Modified Mon Dec 21 13:37:05 1998 by Andries Brouwer <aeb@cwi.nl>
	37	.\" Modified 7 Jan 2002, Michael Kerrisk <mtk16@ext.canterbury.ac.nz>
	38	.\"
	39	.TH TRUNCATE 2 1998-12-21 "" "Linux Programmer's Manual"
	40	.SH NAME
	41	truncate, ftruncate \- truncate a file to a specified length
	42	.SH SYNOPSIS
	43	.B #include <unistd.h>
	44	.sp
	45	.BI "int truncate(const char *" path ", off_t " length );
	46	.br
	47	.BI "int ftruncate(int " fd ", off_t " length );
	48	.SH DESCRIPTION
	49	The
	50	.B truncate
	51	and
	52	.B ftruncate
	53	functions cause the regular file named by
	54	.I path
	55	or referenced by
	56	.I fd
	57	to be truncated to a size of precisely
	58	.I length
	59	bytes.
	60	.LP
	61	If the file previously was larger than this size, the extra data is lost.
	62	If the file previously was shorter, it is extended, and
	63	the extended part reads as zero bytes.
	64	.LP
65	The file pointer is not changed.
66	.LP
67	With
68	.BR ftruncate ,
69	the file must be open for writing; with
70	.BR truncate ,
71	the file must be writable.
72	.SH "RETURN VALUE"
73	On success, zero is returned. On error, \-1 is returned, and
74	.I errno
75	is set appropriately.
76	.SH ERRORS
77	For
78	.BR truncate :
79	.TP
80	.B EACCES
81	Search permission is denied for a component of the path prefix,
82	or the named file is not writable by the user.
83	.TP
84	.B EFAULT
85	.I Path
86	points outside the process's allocated address space.
87	.TP
88	.B EFBIG
89	The argument
90	.I length
91	is larger than the maximum file size. (XSI)
92	.TP
93	.B EINTR
94	A signal was caught during execution.
95	.TP
96	.B EINVAL
97	The argument
98	.I length
99	is negative or larger than the maximum file size.
100	.TP
101	.B EIO
102	An I/O error occurred updating the inode.
103	.TP
104	.B EISDIR
105	The named file is a directory.
106	.TP
107	.B ELOOP
108	Too many symbolic links were encountered in translating the pathname.
109	.TP
110	.B ENAMETOOLONG
111	A component of a pathname exceeded 255 characters,
112	or an entire path name exceeded 1023 characters.
113	.TP
114	.B ENOENT
115	The named file does not exist.
116	.TP
117	.B ENOTDIR
118	A component of the path prefix is not a directory.
119	.TP
120	.B EROFS
121	The named file resides on a read-only file system.
122	.TP
123	.B ETXTBSY
124	The file is a pure procedure (shared text) file that is being executed.
125	.PP
126	For
127	.B ftruncate
128	the same errors apply, but instead of things that can be wrong with
129	.IR path ,
130	we now have things that can be wrong with
131	.IR fd :
132	.TP
133	.B EBADF
134	The
135	.I fd
136	is not a valid descriptor.
137	.TP
138	.BR EBADF " or " EINVAL
139	The
140	.I fd
141	is not open for writing.
142	.TP
143	.B EINVAL
144	The
145	.I fd
146	does not reference a regular file.
147	.SH "CONFORMING TO"
148	4.4BSD, SVr4 (these function calls first appeared in BSD 4.2).
149	POSIX 1003.1-1996 has
150	.BR ftruncate .
151	POSIX 1003.1-2001 also has
152	.IR truncate ,
153	as an XSI extension.
154	.LP
155	SVr4 documents additional
156	.B truncate
157	error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for
158	.B ftruncate
159	an additional EAGAIN error condition.
160	.SH NOTES
161	The above description is for XSI-compliant systems.
162	For non-XSI-compliant systems, the POSIX standard allows
163	two behaviours for
164	.B ftruncate
165	when
166	.I length
167	exceeds the file length
168	(note that
169	.B truncate
170	is not specified at all in such an environment):
171	either returning an error, or extending the file.
172	(Most Unices follow the XSI requirement.)
173	.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002
174	.SH "SEE ALSO"
175	.BR open (2)