| blob | e64d8a642470e20386d26317beb04b0153b6a25b |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH TRUNCATE 3C "Apr 5, 2002"
48 .SH NAME
49 truncate, ftruncate \- set a file to a specified length
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <unistd.h>
55 \fBint\fR \fBtruncate\fR(\fBconst char *\fR\fIpath\fR, \fBoff_t\fR \fIlength\fR);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fBftruncate\fR(\fBint\fR \fIfildes\fR, \fBoff_t\fR \fIlength\fR);
61 .fi
63 .SH DESCRIPTION
64 .sp
65 .LP
66 The \fBtruncate()\fR function causes the regular file named by \fIpath\fR to
67 have a size equal to \fIlength\fR bytes.
68 .sp
69 .LP
70 If the file previously was larger than \fIlength\fR, the extra data is
71 discarded. If the file was previously shorter than length, its size is
72 increased, and the extended area appears as if it were zero-filled.
73 .sp
74 .LP
75 The application must ensure that the process has write permission for the file.
76 .sp
77 .LP
78 This function does not modify the file offset for any open file descriptions
79 associated with the file.
80 .sp
81 .LP
82 The \fBftruncate()\fR function causes the regular file referenced by
83 \fIfildes\fR to be truncated to \fIlength\fR. If the size of the file
84 previously exceeded \fIlength\fR, the extra data is no longer available to
85 reads on the file. If the file previously was smaller than this size,
86 \fBftruncate()\fR increases the size of the file with the extended area
87 appearing as if it were zero-filled. The value of the seek pointer is not
88 modified by a call to \fBftruncate()\fR.
89 .sp
90 .LP
91 The \fBftruncate()\fR function works only with regular files and shared memory.
92 If \fIfildes\fR refers to a shared memory object, \fBftruncate()\fR sets the
93 size of the shared memory object to \fIlength\fR. If \fIfildes\fR refers to a
94 directory or is not a valid file descriptor open for writing, \fBftruncate()\fR
95 fails.
96 .sp
97 .LP
98 If the effect of \fBftruncate()\fR is to decrease the size of a shared memory
99 object or memory mapped file and whole pages beyond the new end were previously
100 mapped, then the whole pages beyond the new end shall be discarded.
101 .sp
102 .LP
103 If the effect of \fBftruncate()\fR is to increase the size of a shared memory
104 object, it is unspecified if the contents of any mapped pages between the old
105 end-of-file and the new are flushed to the underlying object.
106 .sp
107 .LP
108 These functions do not modify the file offset for any open file descriptions
109 associated with the file. On successful completion, if the file size is
110 changed, these functions will mark for update the \fBst_ctime\fR and
111 \fBst_mtime\fR fields of the file, and if the file is a regular file, the
112 \fBS_ISUID\fR and \fBS_ISGID\fR bits of the file mode are left unchanged.
113 .sp
114 .LP
115 If the request would cause the file size to exceed the soft file size limit for
116 the process, the request will fail and a \fBSIGXFSZ\fR signal will be generated
117 for the process.
118 .SH RETURN VALUES
119 .sp
120 .LP
121 Upon successful completion, \fBftruncate()\fR and \fBtruncate()\fR return
122 \fB0\fR. Otherwise, \fB\(mi1\fR is returned and \fBerrno\fR is set to indicate
123 the error.
124 .SH ERRORS
125 .sp
126 .LP
127 The \fBftruncate()\fR and \fBtruncate()\fR functions will fail if:
128 .sp
129 .ne 2
130 .na
131 \fB\fBEINTR\fR\fR
132 .ad
133 .RS 19n
134 A signal was caught during execution.
135 .RE
137 .sp
138 .ne 2
139 .na
140 \fB\fBEINVAL\fR\fR
141 .ad
142 .RS 19n
143 The \fIlength\fR argument was less than 0.
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fBEFBIG\fR or \fBEINVAL\fR\fR
150 .ad
151 .RS 19n
152 The \fIlength\fR argument was greater than the maximum file size.
153 .RE
155 .sp
156 .ne 2
157 .na
158 \fB\fBEIO\fR\fR
159 .ad
160 .RS 19n
161 An I/O error occurred while reading from or writing to a file system.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBEROFS\fR\fR
168 .ad
169 .RS 19n
170 The named file resides on a read-only file system.
171 .RE
173 .sp
174 .LP
175 The \fBtruncate()\fR function will fail if:
176 .sp
177 .ne 2
178 .na
179 \fB\fBEACCES\fR\fR
180 .ad
181 .RS 16n
182 A component of the path prefix denies search permission, or write permission is
183 denied on the file.
184 .RE
186 .sp
187 .ne 2
188 .na
189 \fB\fBEFAULT\fR\fR
190 .ad
191 .RS 16n
192 The \fIpath\fR argument points outside the process' allocated address space.
193 .RE
195 .sp
196 .ne 2
197 .na
198 \fB\fBEINVAL\fR\fR
199 .ad
200 .RS 16n
201 The \fIpath\fR argument is not an ordinary file.
202 .RE
204 .sp
205 .ne 2
206 .na
207 \fB\fBEISDIR\fR\fR
208 .ad
209 .RS 16n
210 The named file is a directory.
211 .RE
213 .sp
214 .ne 2
215 .na
216 \fB\fBELOOP\fR\fR
217 .ad
218 .RS 16n
219 Too many symbolic links were encountered in resolving \fIpath\fR.
220 .RE
222 .sp
223 .ne 2
224 .na
225 \fB\fBEMFILE\fR\fR
226 .ad
227 .RS 16n
228 The maximum number of file descriptors available to the process has been
229 reached.
230 .RE
232 .sp
233 .ne 2
234 .na
235 \fB\fBENAMETOOLONG\fR\fR
236 .ad
237 .RS 16n
238 The length of the specified pathname exceeds {\fBPATH_MAX\fR} bytes, or the
239 length of a component of the pathname exceeds {\fBNAME_MAX\fR} bytes.
240 .RE
242 .sp
243 .ne 2
244 .na
245 \fB\fBENOENT\fR\fR
246 .ad
247 .RS 16n
248 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
249 empty string.
250 .RE
252 .sp
253 .ne 2
254 .na
255 \fB\fBENFILE\fR\fR
256 .ad
257 .RS 16n
258 Additional space could not be allocated for the system file table.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fB\fBENOTDIR\fR\fR
265 .ad
266 .RS 16n
267 A component of the path prefix of \fIpath\fR is not a directory.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fB\fBENOLINK\fR\fR
274 .ad
275 .RS 16n
276 The \fIpath\fR argument points to a remote machine and the link to that machine
277 is no longer active.
278 .RE
280 .sp
281 .LP
282 The \fBftruncate()\fR function will fail if:
283 .sp
284 .ne 2
285 .na
286 \fB\fBEAGAIN\fR\fR
287 .ad
288 .RS 19n
289 The file exists, mandatory file/record locking is set, and there are
290 outstanding record locks on the file (see \fBchmod\fR(2)).
291 .RE
293 .sp
294 .ne 2
295 .na
296 \fB\fBEBADF\fR or \fBEINVAL\fR\fR
297 .ad
298 .RS 19n
299 The \fIfildes\fR argument is not a file descriptor open for writing.
300 .RE
302 .sp
303 .ne 2
304 .na
305 \fB\fBEFBIG\fR\fR
306 .ad
307 .RS 19n
308 The file is a regular file and \fIlength\fR is greater than the offset maximum
309 established in the open file description associated with \fIfildes\fR.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fBEINVAL\fR\fR
316 .ad
317 .RS 19n
318 The \fIfildes\fR argument references a file that was opened without write
319 permission.
320 .RE
322 .sp
323 .ne 2
324 .na
325 \fB\fBEINVAL\fR\fR
326 .ad
327 .RS 19n
328 The \fIfildes\fR argument does not correspond to an ordinary file.
329 .RE
331 .sp
332 .ne 2
333 .na
334 \fB\fBENOLINK\fR\fR
335 .ad
336 .RS 19n
337 The \fIfildes\fR argument points to a remote machine and the link to that
338 machine is no longer active.
339 .RE
341 .sp
342 .LP
343 The \fBtruncate()\fR function may fail if:
344 .sp
345 .ne 2
346 .na
347 \fB\fBENAMETOOLONG\fR\fR
348 .ad
349 .RS 16n
350 Pathname resolution of a symbolic link produced an intermediate result whose
351 length exceeds {\fBPATH_MAX\fR}.
352 .RE
354 .SH ATTRIBUTES
355 .sp
356 .LP
357 See \fBattributes\fR(5) for descriptions of the following attributes:
358 .sp
360 .sp
361 .TS
362 box;
363 c | c
364 l | l .
365 ATTRIBUTE TYPE ATTRIBUTE VALUE
366 _
367 Interface Stability Standard
368 _
369 MT-Level MT-Safe
370 .TE
372 .SH SEE ALSO
373 .sp
374 .LP
375 \fBchmod\fR(2), \fBfcntl\fR(2), \fBopen\fR(2), \fBattributes\fR(5),
376 \fBstandards\fR(5)