logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

ftruncate.3p (4458B)

    

  1. '\" et
  2. .TH FTRUNCATE "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. ftruncate
  12. \(em truncate a file to a specified length
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <unistd.h>
  17. .P
  18. int ftruncate(int \fIfildes\fP, off_t \fIlength\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. If
  22. .IR fildes
  23. is not a valid file descriptor open for writing, the
  24. \fIftruncate\fR()
  25. function shall fail.
  26. .P
  27. If
  28. .IR fildes
  29. refers to a regular file, the
  30. \fIftruncate\fR()
  31. function shall cause the size of the file to be truncated to
  32. .IR length .
  33. If the size of the file previously exceeded
  34. .IR length ,
  35. the extra data shall no longer be available to reads on the file. If
  36. the file previously was smaller than this size,
  37. \fIftruncate\fR()
  38. shall increase the size of the file. If the file size is increased,
  39. the extended area shall appear as if it were zero-filled. The value of
  40. the seek pointer shall not be modified by a call to
  41. \fIftruncate\fR().
  42. .P
  43. Upon successful completion, if
  44. .IR fildes
  45. refers to a regular file,
  46. \fIftruncate\fR()
  47. shall mark for update the last data modification and last file
  48. status change timestamps of the file and the S_ISUID and S_ISGID bits
  49. of the file mode may be cleared. If the
  50. \fIftruncate\fR()
  51. function is unsuccessful, the file is unaffected.
  52. .P
  53. If the request would cause the file size to exceed the soft file size
  54. limit for the process, the request shall fail and the implementation
  55. shall generate the SIGXFSZ signal for the thread.
  56. .P
  57. If
  58. .IR fildes
  59. refers to a directory,
  60. \fIftruncate\fR()
  61. shall fail.
  62. .P
  63. If
  64. .IR fildes
  65. refers to any other file type, except a shared memory object, the
  66. result is unspecified.
  67. .P
  68. If
  69. .IR fildes
  70. refers to a shared memory object,
  71. \fIftruncate\fR()
  72. shall set the size of the shared memory object to
  73. .IR length .
  74. .P
  75. If the effect of
  76. \fIftruncate\fR()
  77. is to decrease the size of a memory mapped file
  78. or a shared memory object
  79. and whole pages beyond the new end were previously mapped, then the
  80. whole pages beyond the new end shall be discarded.
  81. .P
  82. References to discarded pages shall result in the generation of a
  83. SIGBUS signal.
  84. .P
  85. If the effect of
  86. \fIftruncate\fR()
  87. is to increase the size of a memory object, it is unspecified
  88. whether the contents of any mapped pages between the old end-of-file
  89. and the new are flushed to the underlying object.
  90. .SH "RETURN VALUE"
  91. Upon successful completion,
  92. \fIftruncate\fR()
  93. shall return 0; otherwise, \-1 shall be returned and
  94. .IR errno
  95. set to indicate the error.
  96. .SH ERRORS
  97. The
  98. \fIftruncate\fR()
  99. function shall fail if:
  100. .TP
  101. .BR EINTR
  102. A signal was caught during execution.
  103. .TP
  104. .BR EINVAL
  105. The
  106. .IR length
  107. argument was less than 0.
  108. .TP
  109. .BR EFBIG " or " EINVAL
  110. .br
  111. The
  112. .IR length
  113. argument was greater than the maximum file size.
  114. .TP
  115. .BR EFBIG
  116. The file is a regular file and
  117. .IR length
  118. is greater than the offset maximum established in the open file
  119. description associated with
  120. .IR fildes .
  121. .TP
  122. .BR EIO
  123. An I/O error occurred while reading from or writing to a file system.
  124. .TP
  125. .BR EBADF " or " EINVAL
  126. .br
  127. The
  128. .IR fildes
  129. argument is not a file descriptor open for writing.
  130. .LP
  131. .IR "The following sections are informative."
  132. .SH EXAMPLES
  133. None.
  134. .SH "APPLICATION USAGE"
  135. None.
  136. .SH RATIONALE
  137. None.
  138. .SH "FUTURE DIRECTIONS"
  139. None.
  140. .SH "SEE ALSO"
  141. .IR "\fIopen\fR\^(\|)",
  142. .IR "\fItruncate\fR\^(\|)"
  143. .P
  144. The Base Definitions volume of POSIX.1\(hy2017,
  145. .IR "\fB<unistd.h>\fP"
  146. .\"
  147. .SH COPYRIGHT
  148. Portions of this text are reprinted and reproduced in electronic form
  149. from IEEE Std 1003.1-2017, Standard for Information Technology
  150. -- Portable Operating System Interface (POSIX), The Open Group Base
  151. Specifications Issue 7, 2018 Edition,
  152. Copyright (C) 2018 by the Institute of
  153. Electrical and Electronics Engineers, Inc and The Open Group.
  154. In the event of any discrepancy between this version and the original IEEE and
  155. The Open Group Standard, the original IEEE and The Open Group Standard
  156. is the referee document. The original Standard can be obtained online at
  157. http://www.opengroup.org/unix/online.html .
  158. .PP
  159. Any typographical or formatting errors that appear
  160. in this page are most likely
  161. to have been introduced during the conversion of the source files to
  162. man page format. To report such errors, see
  163. https://www.kernel.org/doc/man-pages/reporting_bugs.html .