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 .\" $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
  78 The
  79 .Nm
  80 utility adjusts the length of each regular file given on the command-line, or
  81 performs space management with the given offset and the length over a regular
  82 file given on the command-line.
  83 .Pp
  84 The following options are available:
  85 .Bl -tag -width indent
  86 .It Fl c
  87 Do not create files if they do not exist.
  88 The
  89 .Nm
  90 utility does not treat this as an error.
  91 No error messages are displayed
  92 and the exit value is not affected.
  93 .It Fl r Ar rfile
  94 Truncate 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
 103 If the
 104 .Ar size
 105 argument is preceded by a plus sign
 106 .Pq Cm + ,
 107 files will be extended by this number of bytes.
 108 If the
 109 .Ar size
 110 argument is preceded by a dash
 111 .Pq Cm - ,
 112 file lengths will be reduced by no more than this number of bytes,
 113 to a minimum length of zero bytes.
 114 If the
 115 .Ar size
 116 argument is preceded by a percent sign
 117 .Pq Cm % ,
 118 files will be round up to a multiple of this number of bytes.
 119 If the
 120 .Ar size
 121 argument is preceded by a slash sign
 122 .Pq Cm / ,
 123 files will be round down to a multiple of this number of bytes,
 124 to a minimum length of zero bytes.
 125 Otherwise, the
 126 .Ar size
 127 argument specifies an absolute length to which all files
 128 should be extended or reduced as appropriate.
 129 .It Fl d
 130 Zero a region in the specified file.
 131 If the underlying file system of the given file supports hole-punching,
 132 file system space deallocation may be performed in the operation region.
 133 .It Fl o Ar offset
 134 The space management operation is performed at the given
 135 .Ar offset
 136 bytes in the file.
 137 If this option is not specified, the operation is performed at the beginning of the file.
 138 .It Fl l Ar length
 139 The length of the operation range in bytes.
 140 This option must always be specified if option
 141 .Fl d
 142 is specified, and must be greater than 0.
 143 .El
 144 .Pp
 145 The
 146 .Ar size ,
 147 .Ar offset
 148 and
 149 .Ar length
 150 arguments may be suffixed with one of
 151 .Cm K ,
 152 .Cm M ,
 153 .Cm G
 154 or
 155 .Cm T
 156 (either upper or lower case) to indicate a multiple of
 157 Kilobytes, Megabytes, Gigabytes or Terabytes
 158 respectively.
 159 .Pp
 160 Exactly one of the
 161 .Fl r ,
 162 .Fl s
 163 and
 164 .Fl d
 165 options must be specified.
 166 .Pp
 167 If a file is made smaller, its extra data is lost.
 168 If a file is made larger,
 169 it will be extended as if by writing bytes with the value zero.
 170 If the file does not exist,
 171 it is created unless the
 172 .Fl c
 173 option is specified.
 174 .Pp
 175 Note that,
 176 while truncating a file causes space on disk to be freed,
 177 extending a file does not cause space to be allocated.
 178 To extend a file and actually allocate the space,
 179 it is necessary to explicitly write data to it,
 180 using (for example) the shell's
 181 .Ql >>
 182 redirection syntax, or
 183 .Xr dd 1 .
 184 .Sh EXIT STATUS
 185 .Ex -std
 186 If the operation fails for an argument,
 187 .Nm
 188 will issue a diagnostic
 189 and continue processing the remaining arguments.
 190 .Sh EXAMPLES
 191 Adjust the size of the file
 192 .Pa test_file
 193 to 10 Megabytes but do not create it if it does not exist:
 194 .Bd -literal -offset indent
 195 truncate -c -s +10M test_file
 196 .Ed
 197 .Pp
 198 Same as above but create the file if it does not exist:
 199 .Bd -literal -offset indent
 200 truncate -s +10M test_file
 201 ls -l test_file
 202 -rw-r--r--  1 root  wheel  10485760 Jul 22 18:48 test_file
 203 .Ed
 204 .Pp
 205 Adjust the size of
 206 .Pa test_file
 207 to the size of the kernel and create another file
 208 .Pa test_file2
 209 with the same size:
 210 .Bd -literal -offset indent
 211 truncate -r /boot/kernel/kernel test_file test_file2
 212 ls -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
 218 Downsize
 219 .Pa test_file
 220 in 5 Megabytes:
 221 .Bd -literal -offset indent
 222 # truncate -s -5M test_file
 223 ls -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
 233 The
 234 .Nm
 235 utility conforms to no known standards.
 236 .Sh HISTORY
 237 The
 238 .Nm
 239 utility first appeared in
 240 .Fx 4.2 .
 241 .Sh AUTHORS
 242 The
 243 .Nm
 244 utility was written by
 245 .An Sheldon Hearn Aq Mt sheldonh@starjuice.net .
 246 Hole-punching support of this
 247 utility was developed by
 248 .An Ka Ho Ng Aq Mt khng@FreeBSD.org .