]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/truncate.2
xnu-1228.7.58.tar.gz
[apple/xnu.git] / bsd / man / man2 / truncate.2
CommitLineData
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
2d21ac55
A
40.Nm ftruncate ,
41.Nm truncate
9bccf70c
A
42.Nd truncate or extend a file to a specified length
43.Sh SYNOPSIS
44.Fd #include <unistd.h>
45.Ft int
2d21ac55
A
46.Fo ftruncate
47.Fa "int fildes"
48.Fa "off_t length"
49.Fc
9bccf70c 50.Ft int
2d21ac55
A
51.Fo truncate
52.Fa "const char *path"
53.Fa "off_t length"
54.Fc
9bccf70c
A
55.Sh DESCRIPTION
56.Fn Truncate
57causes the file named by
58.Fa path
59or referenced by
2d21ac55 60.Fa fildes
9bccf70c
A
61to be truncated or extended to
62.Fa length
63bytes in size. If the file previously
64was larger than this size, the extra data
65is lost. If the file was smaller than this size, it will be extended as
66if by writing bytes with the value zero.
67With
68.Fn ftruncate ,
69the file must be open for writing.
70.Sh RETURN VALUES
71A value of 0 is returned if the call succeeds. If the call
72fails a -1 is returned, and the global variable
73.Va errno
74specifies the error.
75.Sh ERRORS
2d21ac55
A
76.Pp
77The
78.Fn ftruncate
79system call will fail if:
9bccf70c 80.Bl -tag -width Er
2d21ac55
A
81.\" ===========
82.It Bq Er EBADF
83.Fa fildes
84is not a valid descriptor open for writing.
85.\" ===========
86.It Bq Er EFBIG
87The file is a regular file and
88.Fa length
89is greater than the offset maximum established
90in the open file description associated with
91.Fa fildes .
92.\" ===========
93.It Bq Er EINVAL
94.Fa fildes
95references a socket, not a file.
96.\" ===========
97.It Bq Er EINVAL
98.Fa fildes
99is not open for writing.
100.\" ===========
101.It Bq Er EROFS
102The named file resides on a read-only file system.
103.El
104.Pp
105The
106.Fn truncate
107system call will fail if:
108.Bl -tag -width Er
109.\" ===========
9bccf70c
A
110.It Bq Er EACCES
111Search permission is denied for a component of the path prefix.
2d21ac55 112.\" ===========
9bccf70c
A
113.It Bq Er EACCES
114The named file is not writable by the user.
2d21ac55
A
115.\" ===========
116.It Bq Er EFAULT
117.Fa Path
118points outside the process's allocated address space.
119.\" ===========
9bccf70c
A
120.It Bq Er EISDIR
121The named file is a directory.
2d21ac55
A
122.\" ===========
123.It Bq Er ELOOP
124Too many symbolic links are encountered in translating the pathname.
125This is taken to be indicative of a looping symbolic link.
126.\" ===========
127.It Bq Er ENAMETOOLONG
128A component of a pathname exceeds
129.Dv {NAME_MAX}
130characters, or an entire path name exceeds
131.Dv {PATH_MAX}
132characters.
133.\" ===========
134.It Bq Er ENOENT
135The named file does not exist.
136.\" ===========
137.It Bq Er ENOTDIR
138A component of the path prefix is not a directory.
139.\" ===========
9bccf70c
A
140.It Bq Er EROFS
141The named file resides on a read-only file system.
2d21ac55 142.\" ===========
9bccf70c
A
143.It Bq Er ETXTBSY
144The file is a pure procedure (shared text) file that is being executed.
9bccf70c
A
145.El
146.Pp
9bccf70c 147The
2d21ac55
A
148.Fn ftruncate
149and
150.Fn truncate
151system calls will fail if:
152.Bl -tag -width Er
153.\" ===========
154.It Bq Er EFBIG
155The length argument was greater than the maximum file size.
156.\" ===========
157.It Bq Er EINTR
158A signal is caught during execution.
159.\" ===========
9bccf70c
A
160.It Bq Er EINVAL
161The
2d21ac55
A
162.Fa length
163argument is less than 0.
164.\" ===========
165.It Bq Er EIO
166An I/O error occurred while reading from or writing to a file system.
9bccf70c
A
167.El
168.Sh SEE ALSO
169.Xr open 2
170.Sh BUGS
171These calls should be generalized to allow ranges
172of bytes in a file to be discarded.
173.Pp
174Use of
175.Fn truncate
176to extend a file is not portable.
177.Sh HISTORY
178The
179.Fn truncate
180and
181.Fn ftruncate
182function calls appeared in
183.Bx 4.2 .