usr.bin/truncate/truncate.1

   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 .Dd August 19, 2021
  31 .Dt TRUNCATE 1
  32 .Os
  33 .Sh NAME
  34 .Nm truncate
  35 .Nd truncate, extend the length of files, or perform space management in files
  36 .Sh SYNOPSIS
  37 .Nm
  38 .Op Fl c
  39 .Bk -words
  40 .Fl s Xo
  41 .Sm off
  42 .Op Cm + | - | % | /
  43 .Ar size
  44 .Op Cm SUFFIX
  45 .Sm on
  46 .Xc
  47 .Ek
  48 .Ar
  49 .Nm
  50 .Op Fl c
  51 .Bk -words
  52 .Fl r Ar rfile
  53 .Ek
  54 .Ar
  55 .Nm
  56 .Op Fl c
  57 .Bk -words
  58 .Fl d
  59 .Oo
  60 .Fl o Xo
  61 .Sm off
  62 .Ar offset
  63 .Op Cm SUFFIX
  64 .Sm on
  65 .Xc
  66 .Oc
  67 .Fl l Xo
  68 .Sm off
  69 .Ar length
  70 .Op Cm SUFFIX
  71 .Sm on
  72 .Xc
  73 .Ek
  74 .Ar
  75 .Sh DESCRIPTION
  76 The
  77 .Nm
  78 utility adjusts the length of each regular file given on the command-line, or
  79 performs space management with the given offset and the length over a regular
  80 file given on the command-line.
  81 .Pp
  82 The following options are available:
  83 .Bl -tag -width indent
  84 .It Fl c
  85 Do not create files if they do not exist.
  86 The
  87 .Nm
  88 utility does not treat this as an error.
  89 No error messages are displayed
  90 and the exit value is not affected.
  91 .It Fl r Ar rfile
  92 Truncate or extend files to the length of the file
  93 .Ar rfile .
  94 .It Fl s Xo
  95 .Sm off
  96 .Op Cm + | - | % | /
  97 .Ar size
  98 .Op Cm SUFFIX
  99 .Sm on
 100 .Xc
 101 If the
 102 .Ar size
 103 argument is preceded by a plus sign
 104 .Pq Cm + ,
 105 files will be extended by this number of bytes.
 106 If the
 107 .Ar size
 108 argument is preceded by a dash
 109 .Pq Cm - ,
 110 file lengths will be reduced by no more than this number of bytes,
 111 to a minimum length of zero bytes.
 112 If the
 113 .Ar size
 114 argument is preceded by a percent sign
 115 .Pq Cm % ,
 116 files will be round up to a multiple of this number of bytes.
 117 If the
 118 .Ar size
 119 argument is preceded by a slash sign
 120 .Pq Cm / ,
 121 files will be round down to a multiple of this number of bytes,
 122 to a minimum length of zero bytes.
 123 Otherwise, the
 124 .Ar size
 125 argument specifies an absolute length to which all files
 126 should be extended or reduced as appropriate.
 127 .It Fl d
 128 Zero a region in the specified file.
 129 If the underlying file system of the given file supports hole-punching,
 130 file system space deallocation may be performed in the operation region.
 131 .It Fl o Ar offset
 132 The space management operation is performed at the given
 133 .Ar offset
 134 bytes in the file.
 135 If this option is not specified, the operation is performed at the beginning of the file.
 136 .It Fl l Ar length
 137 The length of the operation range in bytes.
 138 This option must always be specified if option
 139 .Fl d
 140 is specified, and must be greater than 0.
 141 .El
 142 .Pp
 143 The
 144 .Ar size ,
 145 .Ar offset
 146 and
 147 .Ar length
 148 arguments may be suffixed with one of
 149 .Cm K ,
 150 .Cm M ,
 151 .Cm G
 152 or
 153 .Cm T
 154 (either upper or lower case) to indicate a multiple of
 155 Kilobytes, Megabytes, Gigabytes or Terabytes
 156 respectively.
 157 .Pp
 158 Exactly one of the
 159 .Fl r ,
 160 .Fl s
 161 and
 162 .Fl d
 163 options must be specified.
 164 .Pp
 165 If a file is made smaller, its extra data is lost.
 166 If a file is made larger,
 167 it will be extended as if by writing bytes with the value zero.
 168 If the file does not exist,
 169 it is created unless the
 170 .Fl c
 171 option is specified.
 172 .Pp
 173 Note that,
 174 while truncating a file causes space on disk to be freed,
 175 extending a file does not cause space to be allocated.
 176 To extend a file and actually allocate the space,
 177 it is necessary to explicitly write data to it,
 178 using (for example) the shell's
 179 .Ql >>
 180 redirection syntax, or
 181 .Xr dd 1 .
 182 .Sh EXIT STATUS
 183 .Ex -std
 184 If the operation fails for an argument,
 185 .Nm
 186 will issue a diagnostic
 187 and continue processing the remaining arguments.
 188 .Sh EXAMPLES
 189 Adjust the size of the file
 190 .Pa test_file
 191 to 10 Megabytes but do not create it if it does not exist:
 192 .Bd -literal -offset indent
 193 truncate -c -s +10M test_file
 194 .Ed
 195 .Pp
 196 Same as above but create the file if it does not exist:
 197 .Bd -literal -offset indent
 198 truncate -s +10M test_file
 199 ls -l test_file
 200 -rw-r--r--  1 root  wheel  10485760 Jul 22 18:48 test_file
 201 .Ed
 202 .Pp
 203 Adjust the size of
 204 .Pa test_file
 205 to the size of the kernel and create another file
 206 .Pa test_file2
 207 with the same size:
 208 .Bd -literal -offset indent
 209 truncate -r /boot/kernel/kernel test_file test_file2
 210 ls -l /boot/kernel/kernel test_file*
 211 -r-xr-xr-x  1 root  wheel    31352552 May 15 14:18 /boot/kernel/kernel*
 212 -rw-r--r--  1 root  wheel    31352552 Jul 22 19:15 test_file
 213 -rw-r--r--  1 root  wheel    31352552 Jul 22 19:15 test_file2
 214 .Ed
 215 .Pp
 216 Downsize
 217 .Pa test_file
 218 in 5 Megabytes:
 219 .Bd -literal -offset indent
 220 # truncate -s -5M test_file
 221 ls -l test_file*
 222 -rw-r--r--  1 root  wheel    26109672 Jul 22 19:17 test_file
 223 -rw-r--r--  1 root  wheel    31352552 Jul 22 19:15 test_file2
 224 .Ed
 225 .Sh SEE ALSO
 226 .Xr dd 1 ,
 227 .Xr touch 1 ,
 228 .Xr fspacectl 2 ,
 229 .Xr truncate 2
 230 .Sh STANDARDS
 231 The
 232 .Nm
 233 utility conforms to no known standards.
 234 .Sh HISTORY
 235 The
 236 .Nm
 237 utility first appeared in
 238 .Fx 4.2 .
 239 .Sh AUTHORS
 240 The
 241 .Nm
 242 utility was written by
 243 .An Sheldon Hearn Aq Mt sheldonh@starjuice.net .
 244 Hole-punching support of this
 245 utility was developed by
 246 .An Ka Ho Ng Aq Mt khng@FreeBSD.org .