diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/ftruncate.3p')
-rw-r--r-- | man-pages-posix-2003/man3p/ftruncate.3p | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/ftruncate.3p b/man-pages-posix-2003/man3p/ftruncate.3p new file mode 100644 index 0000000..0a2f410 --- /dev/null +++ b/man-pages-posix-2003/man3p/ftruncate.3p @@ -0,0 +1,135 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "FTRUNCATE" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" ftruncate +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +ftruncate \- truncate a file to a specified length +.SH SYNOPSIS +.LP +\fB#include <unistd.h> +.br +.sp +int ftruncate(int\fP \fIfildes\fP\fB, off_t\fP \fIlength\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +If \fIfildes\fP is not a valid file descriptor open for writing, the +\fIftruncate\fP() function shall fail. +.LP +If \fIfildes\fP refers to a regular file, the \fIftruncate\fP() function +shall cause the size of the file to be truncated to +\fIlength\fP. If the size of the file previously exceeded \fIlength\fP, +the extra data shall no longer be available to reads on +the file. If the file previously was smaller than this size, \fIftruncate\fP() +shall either increase the size of the file or fail. +\ XSI-conformant systems shall increase the size of the file. +If the file size is increased, the extended area shall appear as if +it were zero-filled. The value of the seek pointer shall not be +modified by a call to \fIftruncate\fP(). +.LP +Upon successful completion, if \fIfildes\fP refers to a regular file, +the \fIftruncate\fP() function shall mark for update the +\fIst_ctime\fP and \fIst_mtime\fP fields of the file and the S_ISUID +and S_ISGID bits of the file mode may be cleared. If the +\fIftruncate\fP() function is unsuccessful, the file is unaffected. +.LP +If the request would cause the file size to exceed the soft file size +limit for the process, the request shall fail and the +implementation shall generate the SIGXFSZ signal for the thread. +.LP +If \fIfildes\fP refers to a directory, \fIftruncate\fP() shall fail. +.LP +If \fIfildes\fP refers to any other file type, except a shared memory +object, the result is unspecified. +.LP +If \fIfildes\fP refers to a shared memory object, \fIftruncate\fP() +shall set the size of the shared memory object to +\fIlength\fP. +.LP +If the effect of \fIftruncate\fP() is to decrease the size of a shared +memory object or memory mapped file and whole pages beyond +the new end were previously mapped, then the whole pages beyond the +new end shall be discarded. +.LP +If the Memory Protection option is supported, references to discarded +pages shall result in the generation of a SIGBUS signal; +otherwise, the result of such references is undefined. +.LP +If the effect of \fIftruncate\fP() is to increase the size of a shared +memory object, it is unspecified whether the contents of +any mapped pages between the old end-of-file and the new are flushed +to the underlying object. +.SH RETURN VALUE +.LP +Upon successful completion, \fIftruncate\fP() shall return 0; otherwise, +-1 shall be returned and \fIerrno\fP set to indicate +the error. +.SH ERRORS +.LP +The \fIftruncate\fP() function shall fail if: +.TP 7 +.B EINTR +A signal was caught during execution. +.TP 7 +.B EINVAL +The \fIlength\fP argument was less than 0. +.TP 7 +.B EFBIG \fRor\fP EINVAL +.sp +The \fIlength\fP argument was greater than the maximum file size. +.TP 7 +.B EFBIG +The file is a regular file and \fIlength\fP is greater than the offset +maximum established in the open file description associated +with \fIfildes\fP. +.TP 7 +.B EIO +An I/O error occurred while reading from or writing to a file system. +.TP 7 +.B EBADF \fRor\fP EINVAL +.sp +The \fIfildes\fP argument is not a file descriptor open for writing. +.TP 7 +.B EINVAL +The \fIfildes\fP argument references a file that was opened without +write permission. +.TP 7 +.B EROFS +The named file resides on a read-only file system. +.sp +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +None. +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fIftruncate\fP() function is part of IEEE\ Std\ 1003.1-2001 as +it was deemed to be more useful than \fItruncate\fP(). The \fItruncate\fP() +function is +provided as an XSI extension. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIopen\fP(), \fItruncate\fP(), the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, \fI<unistd.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |