1FTRUNCATE(P)               POSIX Programmer's Manual              FTRUNCATE(P)
2
3
4

NAME

6       ftruncate - truncate a file to a specified length
7

SYNOPSIS

9       #include <unistd.h>
10
11       int ftruncate(int fildes, off_t length);
12
13

DESCRIPTION

15       If  fildes  is not a valid file descriptor open for writing, the ftrun‐
16       cate() function shall fail.
17
18       If fildes refers to a regular  file,  the  ftruncate()  function  shall
19       cause  the  size  of the file to be truncated to length. If the size of
20       the file previously exceeded length, the extra data shall no longer  be
21       available to reads on the file. If the file previously was smaller than
22       this size, ftruncate() shall either increase the size of  the  file  or
23       fail.   XSI-conformant systems shall increase the size of the file.  If
24       the file size is increased, the extended area shall  appear  as  if  it
25       were  zero-filled.  The value of the seek pointer shall not be modified
26       by a call to ftruncate().
27
28       Upon successful completion, if fildes refers to  a  regular  file,  the
29       ftruncate()  function  shall  mark for update the st_ctime and st_mtime
30       fields of the file and the S_ISUID and S_ISGID bits of  the  file  mode
31       may  be  cleared. If the ftruncate() function is unsuccessful, the file
32       is unaffected.
33
34       If the request would cause the file size to exceed the soft  file  size
35       limit  for  the  process, the request shall fail and the implementation
36       shall generate the SIGXFSZ signal for the thread.
37
38       If fildes refers to a directory, ftruncate() shall fail.
39
40       If fildes refers to any other file type, except a shared memory object,
41       the result is unspecified.
42
43       If  fildes  refers to a shared memory object, ftruncate() shall set the
44       size of the shared memory object to length.
45
46       If the effect of ftruncate() is to decrease the size of a shared memory
47       object  or  memory  mapped file and whole pages beyond the new end were
48       previously mapped, then the whole pages beyond the  new  end  shall  be
49       discarded.
50
51       If  the  Memory Protection option is supported, references to discarded
52       pages shall result in the generation of a SIGBUS signal; otherwise, the
53       result of such references is undefined.
54
55       If the effect of ftruncate() is to increase the size of a shared memory
56       object, it is unspecified whether the  contents  of  any  mapped  pages
57       between  the  old end-of-file and the new are flushed to the underlying
58       object.
59

RETURN VALUE

61       Upon successful completion, ftruncate() shall return 0;  otherwise,  -1
62       shall be returned and errno set to indicate the error.
63

ERRORS

65       The ftruncate() function shall fail if:
66
67       EINTR  A signal was caught during execution.
68
69       EINVAL The length argument was less than 0.
70
71       EFBIG or EINVAL
72
73              The length argument was greater than the maximum file size.
74
75       EFBIG  The file is a regular file and length is greater than the offset
76              maximum established in the open file description associated with
77              fildes.
78
79       EIO    An  I/O  error  occurred while reading from or writing to a file
80              system.
81
82       EBADF or EINVAL
83
84              The fildes argument is not a file descriptor open for writing.
85
86       EINVAL The fildes argument references a file that  was  opened  without
87              write permission.
88
89       EROFS  The named file resides on a read-only file system.
90
91
92       The following sections are informative.
93

EXAMPLES

95       None.
96

APPLICATION USAGE

98       None.
99

RATIONALE

101       The  ftruncate()  function  is  part  of IEEE Std 1003.1-2001 as it was
102       deemed to be more useful than truncate(). The  truncate()  function  is
103       provided as an XSI extension.
104

FUTURE DIRECTIONS

106       None.
107

SEE ALSO

109       open()    ,    truncate()    ,   the   Base   Definitions   volume   of
110       IEEE Std 1003.1-2001, <unistd.h>
111

113       Portions of this text are reprinted and reproduced in  electronic  form
114       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
115       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
116       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
117       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
118       event of any discrepancy between this version and the original IEEE and
119       The Open Group Standard, the original IEEE and The Open Group  Standard
120       is  the  referee document. The original Standard can be obtained online
121       at http://www.opengroup.org/unix/online.html .
122
123
124
125IEEE/The Open Group                  2003                         FTRUNCATE(P)
Impressum