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