lib/libc/sys/truncate.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)truncate.2  8.1 (Berkeley) 6/4/93
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 4, 2015
  32 .Dt TRUNCATE 2
  33 .Os
  34 .Sh NAME
  35 .Nm truncate ,
  36 .Nm ftruncate
  37 .Nd truncate or extend a file to a specified length
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In unistd.h
  42 .Ft int
  43 .Fn truncate "const char *path" "off_t length"
  44 .Ft int
  45 .Fn ftruncate "int fd" "off_t length"
  46 .Sh DESCRIPTION
  47 The
  48 .Fn truncate
  49 system call
  50 causes the file named by
  51 .Fa path
  52 or referenced by
  53 .Fa fd
  54 to be truncated or extended to
  55 .Fa length
  56 bytes in size.
  57 If the file
  58 was larger than this size, the extra data
  59 is lost.
  60 If the file was smaller than this size,
  61 it will be extended as if by writing bytes
  62 with the value zero.
  63 .Pp
  64 The
  65 .Fn ftruncate
  66 system call causes the file or shared memory object backing the file descriptor
  67 .Fa fd
  68 to be truncated or extended to
  69 .Fa length
  70 bytes in size.
  71 The file descriptor must be a valid file descriptor open for writing.
  72 The file position pointer associated with the file descriptor
  73 .Fa fd
  74 will not be modified.
  75 .Sh RETURN VALUES
  76 .Rv -std
  77 If the file to be modified is not a directory or
  78 a regular file, the
  79 .Fn truncate
  80 call has no effect and returns the value 0.
  81 .Sh ERRORS
  82 The
  83 .Fn truncate
  84 system call
  85 succeeds unless:
  86 .Bl -tag -width Er
  87 .It Bq Er ENOTDIR
  88 A component of the path prefix is not a directory.
  89 .It Bq Er ENAMETOOLONG
  90 A component of a pathname exceeded 255 characters,
  91 or an entire path name exceeded 1023 characters.
  92 .It Bq Er ENOENT
  93 The named file does not exist.
  94 .It Bq Er EACCES
  95 Search permission is denied for a component of the path prefix.
  96 .It Bq Er EACCES
  97 The named file is not writable by the user.
  98 .It Bq Er ELOOP
  99 Too many symbolic links were encountered in translating the pathname.
 100 .It Bq Er EPERM
 101 The named file has its immutable or append-only flag set, see the
 102 .Xr chflags 2
 103 manual page for more information.
 104 .It Bq Er EISDIR
 105 The named file is a directory.
 106 .It Bq Er EROFS
 107 The named file resides on a read-only file system.
 108 .It Bq Er ETXTBSY
 109 The file is a pure procedure (shared text) file that is being executed.
 110 .It Bq Er EFBIG
 111 The
 112 .Fa length
 113 argument was greater than the maximum file size.
 114 .It Bq Er EINVAL
 115 The
 116 .Fa length
 117 argument was less than 0.
 118 .It Bq Er EIO
 119 An I/O error occurred updating the inode.
 120 .It Bq Er EFAULT
 121 The
 122 .Fa path
 123 argument
 124 points outside the process's allocated address space.
 125 .El
 126 .Pp
 127 The
 128 .Fn ftruncate
 129 system call
 130 succeeds unless:
 131 .Bl -tag -width Er
 132 .It Bq Er EBADF
 133 The
 134 .Fa fd
 135 argument
 136 is not a valid descriptor.
 137 .It Bq Er EINVAL
 138 The
 139 .Fa fd
 140 argument
 141 references a file descriptor that is not a regular file or shared memory object.
 142 .It Bq Er EINVAL
 143 The
 144 .Fa fd
 145 descriptor
 146 is not open for writing.
 147 .El
 148 .Sh SEE ALSO
 149 .Xr chflags 2 ,
 150 .Xr open 2 ,
 151 .Xr shm_open 2
 152 .Sh HISTORY
 153 The
 154 .Fn truncate
 155 and
 156 .Fn ftruncate
 157 system calls appeared in
 158 .Bx 4.2 .
 159 .Sh BUGS
 160 These calls should be generalized to allow ranges
 161 of bytes in a file to be discarded.
 162 .Pp
 163 Use of
 164 .Fn truncate
 165 to extend a file is not portable.