truncate(3c)

1truncate(3C)             Standard C Library Functions             truncate(3C)
2
3
4

NAME

6       truncate, ftruncate - set a file to a specified length
7

SYNOPSIS

9       #include <unistd.h>
10
11       int truncate(const char *path, off_t length);
12
13
14       int ftruncate(int fildes, off_t length);
15
16

DESCRIPTION

18       The truncate() function causes the regular file named by path to have a
19       size equal to length bytes.
20
21
22       If the file previously was larger than length, the extra data  is  dis‐
23       carded.  If  the  file  was previously shorter than length, its size is
24       increased, and the extended area appears as if it were zero-filled.
25
26
27       The application must ensure that the process has write  permission  for
28       the file.
29
30
31       This  function  does  not  modify  the  file  offset  for any open file
32       descriptions associated with the file.
33
34
35       The ftruncate() function causes the regular file referenced  by  fildes
36       to  be truncated to length. If the size of the file previously exceeded
37       length, the extra data is no longer available to reads on the file.  If
38       the  file  previously was smaller than this size, ftruncate() increases
39       the size of the file with the extended area appearing  as  if  it  were
40       zero-filled. The value of the seek pointer is not modified by a call to
41       ftruncate().
42
43
44       The ftruncate() function works only with regular files and shared  mem‐
45       ory.  If  fildes refers to a shared memory object, ftruncate() sets the
46       size of the shared memory object to  length.  If  fildes  refers  to  a
47       directory  or  is  not a valid file descriptor open for writing, ftrun‐
48       cate() fails.
49
50
51       If the effect of ftruncate() is to decrease the size of a shared memory
52       object  or  memory  mapped file and whole pages beyond the new end were
53       previously mapped, then the whole pages beyond the  new  end  shall  be
54       discarded.
55
56
57       If the effect of ftruncate() is to increase the size of a shared memory
58       object, it is unspecified if the contents of any mapped  pages  between
59       the old end-of-file and the new are flushed to the underlying object.
60
61
62       These  functions  do  not  modify  the  file  offset  for any open file
63       descriptions associated with the file.  On  successful  completion,  if
64       the  file  size  is  changed,  these functions will mark for update the
65       st_ctime and st_mtime fields of the file, and if the file is a  regular
66       file, the S_ISUID and S_ISGID bits of the file mode are left unchanged.
67
68
69       If  the  request would cause the file size to exceed the soft file size
70       limit for the process, the request will fail and a SIGXFSZ signal  will
71       be generated for the process.
72

RETURN VALUES

74       Upon successful completion, ftruncate() and truncate() return 0. Other‐
75       wise, −1 is returned and errno is set to indicate the error.
76

ERRORS

78       The ftruncate() and truncate() functions will fail if:
79
80       EINTR              A signal was caught during execution.
81
82
83       EINVAL             The length argument was less than 0.
84
85
86       EFBIG or EINVAL    The length argument was  greater  than  the  maximum
87                          file size.
88
89
90       EIO                An  I/O error occurred while reading from or writing
91                          to a file system.
92
93
94       EROFS              The named file resides on a read-only file system.
95
96
97
98       The truncate() function will fail if:
99
100       EACCES          A component of the path prefix  denies  search  permis‐
101                       sion, or write permission is denied on the file.
102
103
104       EFAULT          The path argument points outside the process' allocated
105                       address space.
106
107
108       EINVAL          The path argument is not an ordinary file.
109
110
111       EISDIR          The named file is a directory.
112
113
114       ELOOP           Too many symbolic links were encountered  in  resolving
115                       path.
116
117
118       EMFILE          The maximum number of file descriptors available to the
119                       process has been reached.
120
121
122       ENAMETOOLONG    The length of the specified pathname exceeds {PATH_MAX}
123                       bytes,  or  the  length  of a component of the pathname
124                       exceeds {NAME_MAX} bytes.
125
126
127       ENOENT          A component of path does not name an existing  file  or
128                       path is an empty string.
129
130
131       ENFILE          Additional  space could not be allocated for the system
132                       file table.
133
134
135       ENOTDIR         A component of the path prefix of path is not a  direc‐
136                       tory.
137
138
139       ENOLINK         The  path  argument  points to a remote machine and the
140                       link to that machine is no longer active.
141
142
143
144       The ftruncate() function will fail if:
145
146       EAGAIN             The file exists, mandatory  file/record  locking  is
147                          set,  and  there are outstanding record locks on the
148                          file (see chmod(2)).
149
150
151       EBADF or EINVAL    The fildes argument is not a  file  descriptor  open
152                          for writing.
153
154
155       EFBIG              The  file  is  a  regular file and length is greater
156                          than the offset maximum established in the open file
157                          description associated with fildes.
158
159
160       EINVAL             The  fildes  argument  references  a  file  that was
161                          opened without write permission.
162
163
164       EINVAL             The fildes argument does not correspond to an  ordi‐
165                          nary file.
166
167
168       ENOLINK            The  fildes  argument points to a remote machine and
169                          the link to that machine is no longer active.
170
171
172
173       The truncate() function may fail if:
174
175       ENAMETOOLONG    Pathname resolution of  a  symbolic  link  produced  an
176                       intermediate result whose length exceeds {PATH_MAX}.
177
178

USAGE

180       The  truncate()  and ftruncate() functions have transitional interfaces
181       for 64-bit file offsets.  See lf64(5).
182

ATTRIBUTES

184       See attributes(5) for descriptions of the following attributes:
185
186
187
188
189       ┌─────────────────────────────┬─────────────────────────────┐
190       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
191       ├─────────────────────────────┼─────────────────────────────┤
192       │Interface Stability          │Standard                     │
193       ├─────────────────────────────┼─────────────────────────────┤
194       │MT-Level                     │MT-Safe                      │
195       └─────────────────────────────┴─────────────────────────────┘
196