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 3, 2021 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 ftruncate 57and 58.Fn truncate 59cause the file named by 60.Fa path , 61or referenced by 62.Fa fildes , 63to be truncated (or extended) to 64.Fa length 65bytes in size. If the file size exceeds 66.Fa length , 67any extra data is discarded. If the file size is smaller than 68.Fa length , 69the file is extended and filled with zeros to the indicated length. 70The 71.Fn ftruncate 72form requires the file to be open for writing. 73.Pp 74Note: 75.Fn ftruncate 76and 77.Fn truncate 78do not modify the current file offset for any open file descriptions associated with the file. 79.Sh RETURN VALUES 80A value of 0 is returned if the call succeeds. If the call 81fails a -1 is returned, and the global variable 82.Va errno 83specifies the error. 84.Sh ERRORS 85.Pp 86The 87.Fn ftruncate 88system call will fail if: 89.Bl -tag -width Er 90.\" =========== 91.It Bq Er EBADF 92.Fa fildes 93is not a valid descriptor open for writing. 94.\" =========== 95.It Bq Er EFBIG 96The file is a regular file and 97.Fa length 98is greater than the offset maximum established 99in the open file description associated with 100.Fa fildes . 101.\" =========== 102.It Bq Er EINVAL 103.Fa fildes 104references a socket, not a file. 105.\" =========== 106.It Bq Er EINVAL 107.Fa fildes 108is not open for writing. 109.\" =========== 110.It Bq Er EPERM 111The named file has its append-only flag set, see the 112.Xr chflags 2 113manual page for more information. 114.\" ========== 115.It Bq Er EROFS 116The named file resides on a read-only file system. 117.El 118.Pp 119The 120.Fn truncate 121system call will fail if: 122.Bl -tag -width Er 123.\" =========== 124.It Bq Er EACCES 125Search permission is denied for a component of the path prefix. 126.\" =========== 127.It Bq Er EACCES 128The named file is not writable by the user. 129.\" =========== 130.It Bq Er EFAULT 131.Fa Path 132points outside the process's allocated address space. 133.\" =========== 134.It Bq Er EISDIR 135The named file is a directory. 136.\" =========== 137.It Bq Er ELOOP 138Too many symbolic links are encountered in translating the pathname. 139This is taken to be indicative of a looping symbolic link. 140.\" =========== 141.It Bq Er ENAMETOOLONG 142A component of a pathname exceeds 143.Dv {NAME_MAX} 144characters, or an entire path name exceeds 145.Dv {PATH_MAX} 146characters. 147.\" =========== 148.It Bq Er ENOENT 149The named file does not exist. 150.\" =========== 151.It Bq Er ENOTDIR 152A component of the path prefix is not a directory. 153.\" =========== 154.It Bq Er EDEADLK 155A component of the pathname refers to a 156.Dq dataless 157directory that requires materialization and the I/O policy of the current 158thread or process disallows dataless directory materialization 159.Po see 160.Xr getiopolicy_np 3 161.Pc . 162.\" =========== 163.It Bq Er EROFS 164The named file resides on a read-only file system. 165.\" =========== 166.It Bq Er ETXTBSY 167The file is a pure procedure (shared text) file that is being executed. 168.El 169.Pp 170The 171.Fn ftruncate 172and 173.Fn truncate 174system calls will fail if: 175.Bl -tag -width Er 176.\" =========== 177.It Bq Er EFBIG 178The length argument was greater than the maximum file size. 179.\" =========== 180.It Bq Er EINTR 181A signal is caught during execution. 182.\" =========== 183.It Bq Er EINVAL 184The 185.Fa length 186argument is less than 0. 187.\" =========== 188.It Bq Er EIO 189An I/O error occurred while reading from or writing to a file system. 190.\" =========== 191.It Bq Er EDEADLK 192The file is a 193.Dq dataless 194file that requires materialization and the I/O policy of the current thread 195or process disallows dataless file materialization 196.Po see 197.Xr getiopolicy_np 3 198.Pc . 199.El 200.Sh SEE ALSO 201.Xr open 2 202.Sh BUGS 203These calls should be generalized to allow ranges 204of bytes in a file to be discarded. 205.Pp 206Use of 207.Fn truncate 208to extend a file is not portable. 209.Sh HISTORY 210The 211.Fn truncate 212and 213.Fn ftruncate 214function calls appeared in 215.Bx 4.2 . 216