1.\" 2.\" Copyright (c) 2000 Sheldon Hearn <sheldonh@FreeBSD.org>. 3.\" All rights reserved. 4.\" Copyright (c) 2021 The FreeBSD Foundation 5.\" 6.\" Portions of this manual page were written by Ka Ho Ng <khng@FreeBSD.org> 7.\" under sponsorship from the FreeBSD Foundation. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" $FreeBSD$ 31.\" 32.Dd August 19, 2021 33.Dt TRUNCATE 1 34.Os 35.Sh NAME 36.Nm truncate 37.Nd truncate, extend the length of files, or perform space management in files 38.Sh SYNOPSIS 39.Nm 40.Op Fl c 41.Bk -words 42.Fl s Xo 43.Sm off 44.Op Cm + | - | % | / 45.Ar size 46.Op Cm SUFFIX 47.Sm on 48.Xc 49.Ek 50.Ar 51.Nm 52.Op Fl c 53.Bk -words 54.Fl r Ar rfile 55.Ek 56.Ar 57.Nm 58.Op Fl c 59.Bk -words 60.Fl d 61.Oo 62.Fl o Xo 63.Sm off 64.Ar offset 65.Op Cm SUFFIX 66.Sm on 67.Xc 68.Oc 69.Fl l Xo 70.Sm off 71.Ar length 72.Op Cm SUFFIX 73.Sm on 74.Xc 75.Ek 76.Ar 77.Sh DESCRIPTION 78The 79.Nm 80utility adjusts the length of each regular file given on the command-line, or 81performs space management with the given offset and the length over a regular 82file given on the command-line. 83.Pp 84The following options are available: 85.Bl -tag -width indent 86.It Fl c 87Do not create files if they do not exist. 88The 89.Nm 90utility does not treat this as an error. 91No error messages are displayed 92and the exit value is not affected. 93.It Fl r Ar rfile 94Truncate or extend files to the length of the file 95.Ar rfile . 96.It Fl s Xo 97.Sm off 98.Op Cm + | - | % | / 99.Ar size 100.Op Cm SUFFIX 101.Sm on 102.Xc 103If the 104.Ar size 105argument is preceded by a plus sign 106.Pq Cm + , 107files will be extended by this number of bytes. 108If the 109.Ar size 110argument is preceded by a dash 111.Pq Cm - , 112file lengths will be reduced by no more than this number of bytes, 113to a minimum length of zero bytes. 114If the 115.Ar size 116argument is preceded by a percent sign 117.Pq Cm % , 118files will be round up to a multiple of this number of bytes. 119If the 120.Ar size 121argument is preceded by a slash sign 122.Pq Cm / , 123files will be round down to a multiple of this number of bytes, 124to a minimum length of zero bytes. 125Otherwise, the 126.Ar size 127argument specifies an absolute length to which all files 128should be extended or reduced as appropriate. 129.It Fl d 130Zero a region in the specified file. 131If the underlying file system of the given file supports hole-punching, 132file system space deallocation may be performed in the operation region. 133.It Fl o Ar offset 134The space management operation is performed at the given 135.Ar offset 136bytes in the file. 137If this option is not specified, the operation is performed at the beginning of the file. 138.It Fl l Ar length 139The length of the operation range in bytes. 140This option must always be specified if option 141.Fl d 142is specified, and must be greater than 0. 143.El 144.Pp 145The 146.Ar size , 147.Ar offset 148and 149.Ar length 150arguments may be suffixed with one of 151.Cm K , 152.Cm M , 153.Cm G 154or 155.Cm T 156(either upper or lower case) to indicate a multiple of 157Kilobytes, Megabytes, Gigabytes or Terabytes 158respectively. 159.Pp 160Exactly one of the 161.Fl r , 162.Fl s 163and 164.Fl d 165options must be specified. 166.Pp 167If a file is made smaller, its extra data is lost. 168If a file is made larger, 169it will be extended as if by writing bytes with the value zero. 170If the file does not exist, 171it is created unless the 172.Fl c 173option is specified. 174.Pp 175Note that, 176while truncating a file causes space on disk to be freed, 177extending a file does not cause space to be allocated. 178To extend a file and actually allocate the space, 179it is necessary to explicitly write data to it, 180using (for example) the shell's 181.Ql >> 182redirection syntax, or 183.Xr dd 1 . 184.Sh EXIT STATUS 185.Ex -std 186If the operation fails for an argument, 187.Nm 188will issue a diagnostic 189and continue processing the remaining arguments. 190.Sh EXAMPLES 191Adjust the size of the file 192.Pa test_file 193to 10 Megabytes but do not create it if it does not exist: 194.Bd -literal -offset indent 195truncate -c -s +10M test_file 196.Ed 197.Pp 198Same as above but create the file if it does not exist: 199.Bd -literal -offset indent 200truncate -s +10M test_file 201ls -l test_file 202-rw-r--r-- 1 root wheel 10485760 Jul 22 18:48 test_file 203.Ed 204.Pp 205Adjust the size of 206.Pa test_file 207to the size of the kernel and create another file 208.Pa test_file2 209with the same size: 210.Bd -literal -offset indent 211truncate -r /boot/kernel/kernel test_file test_file2 212ls -l /boot/kernel/kernel test_file* 213-r-xr-xr-x 1 root wheel 31352552 May 15 14:18 /boot/kernel/kernel* 214-rw-r--r-- 1 root wheel 31352552 Jul 22 19:15 test_file 215-rw-r--r-- 1 root wheel 31352552 Jul 22 19:15 test_file2 216.Ed 217.Pp 218Downsize 219.Pa test_file 220in 5 Megabytes: 221.Bd -literal -offset indent 222# truncate -s -5M test_file 223ls -l test_file* 224-rw-r--r-- 1 root wheel 26109672 Jul 22 19:17 test_file 225-rw-r--r-- 1 root wheel 31352552 Jul 22 19:15 test_file2 226.Ed 227.Sh SEE ALSO 228.Xr dd 1 , 229.Xr touch 1 , 230.Xr fspacectl 2 , 231.Xr truncate 2 232.Sh STANDARDS 233The 234.Nm 235utility conforms to no known standards. 236.Sh HISTORY 237The 238.Nm 239utility first appeared in 240.Fx 4.2 . 241.Sh AUTHORS 242The 243.Nm 244utility was written by 245.An Sheldon Hearn Aq Mt sheldonh@starjuice.net . 246Hole-punching support of this 247utility was developed by 248.An Ka Ho Ng Aq Mt khng@FreeBSD.org . 249