diff options
Diffstat (limited to 'upstream/debian-bookworm/man2/truncate.2')
| -rw-r--r-- | upstream/debian-bookworm/man2/truncate.2 | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/upstream/debian-bookworm/man2/truncate.2 b/upstream/debian-bookworm/man2/truncate.2 new file mode 100644 index 00000000..5488e810 --- /dev/null +++ b/upstream/debian-bookworm/man2/truncate.2 @@ -0,0 +1,249 @@ +.\" Copyright (c) 1983, 1991 The Regents of the University of California. +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-4-Clause-UC +.\" +.\" @(#)truncate.2 6.9 (Berkeley) 3/10/91 +.\" +.\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu> +.\" Modified 1996-10-22 by Eric S. Raymond <esr@thyrsus.com> +.\" Modified 1998-12-21 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 2002-01-07 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" Modified 2002-04-06 by Andries Brouwer <aeb@cwi.nl> +.\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH truncate 2 2023-02-05 "Linux man-pages 6.03" +.SH NAME +truncate, ftruncate \- truncate a file to a specified length +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <unistd.h> +.PP +.BI "int truncate(const char *" path ", off_t " length ); +.BI "int ftruncate(int " fd ", off_t " length ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR truncate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.12: */ _POSIX_C_SOURCE >= 200809L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.PP +.BR ftruncate (): +.nf + _XOPEN_SOURCE >= 500 +.\" || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED + || /* Since glibc 2.3.5: */ _POSIX_C_SOURCE >= 200112L + || /* glibc <= 2.19: */ _BSD_SOURCE +.fi +.SH DESCRIPTION +The +.BR truncate () +and +.BR ftruncate () +functions cause the regular file named by +.I path +or referenced by +.I fd +to be truncated to a size of precisely +.I length +bytes. +.PP +If the file previously was larger than this size, the extra data is lost. +If the file previously was shorter, it is extended, and +the extended part reads as null bytes (\[aq]\e0\[aq]). +.PP +The file offset is not changed. +.PP +If the size changed, then the st_ctime and st_mtime fields +(respectively, time of last status change and +time of last modification; see +.BR inode (7)) +for the file are updated, +and the set-user-ID and set-group-ID mode bits may be cleared. +.PP +With +.BR ftruncate (), +the file must be open for writing; with +.BR truncate (), +the file must be writable. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +For +.BR truncate (): +.TP +.B EACCES +Search permission is denied for a component of the path prefix, +or the named file is not writable by the user. +(See also +.BR path_resolution (7).) +.TP +.B EFAULT +The argument +.I path +points outside the process's allocated address space. +.TP +.B EFBIG +The argument +.I length +is larger than the maximum file size. (XSI) +.TP +.B EINTR +While blocked waiting to complete, +the call was interrupted by a signal handler; see +.BR fcntl (2) +and +.BR signal (7). +.TP +.B EINVAL +The argument +.I length +is negative or larger than the maximum file size. +.TP +.B EIO +An I/O error occurred updating the inode. +.TP +.B EISDIR +The named file is a directory. +.TP +.B ELOOP +Too many symbolic links were encountered in translating the pathname. +.TP +.B ENAMETOOLONG +A component of a pathname exceeded 255 characters, +or an entire pathname exceeded 1023 characters. +.TP +.B ENOENT +The named file does not exist. +.TP +.B ENOTDIR +A component of the path prefix is not a directory. +.TP +.B EPERM +.\" This happens for at least MSDOS and VFAT filesystems +.\" on kernel 2.6.13 +The underlying filesystem does not support extending +a file beyond its current size. +.TP +.B EPERM +The operation was prevented by a file seal; see +.BR fcntl (2). +.TP +.B EROFS +The named file resides on a read-only filesystem. +.TP +.B ETXTBSY +The file is an executable file that is being executed. +.PP +For +.BR ftruncate () +the same errors apply, but instead of things that can be wrong with +.IR path , +we now have things that can be wrong with the file descriptor, +.IR fd : +.TP +.B EBADF +.I fd +is not a valid file descriptor. +.TP +.BR EBADF " or " EINVAL +.I fd +is not open for writing. +.TP +.B EINVAL +.I fd +does not reference a regular file or a POSIX shared memory object. +.TP +.BR EINVAL " or " EBADF +The file descriptor +.I fd +is not open for writing. +POSIX permits, and portable applications should handle, +either error for this case. +(Linux produces +.BR EINVAL .) +.SH STANDARDS +POSIX.1-2001, POSIX.1-2008, +4.4BSD, SVr4 (these calls first appeared in 4.2BSD). +.\" POSIX.1-1996 has +.\" .BR ftruncate (). +.\" POSIX.1-2001 also has +.\" .BR truncate (), +.\" as an XSI extension. +.\" .LP +.\" SVr4 documents additional +.\" .BR truncate () +.\" error conditions EMFILE, EMULTIHP, ENFILE, ENOLINK. SVr4 documents for +.\" .BR ftruncate () +.\" an additional EAGAIN error condition. +.SH NOTES +.BR ftruncate () +can also be used to set the size of a POSIX shared memory object; see +.BR shm_open (3). +.PP +The details in DESCRIPTION are for XSI-compliant systems. +For non-XSI-compliant systems, the POSIX standard allows +two behaviors for +.BR ftruncate () +when +.I length +exceeds the file length +(note that +.BR truncate () +is not specified at all in such an environment): +either returning an error, or extending the file. +Like most UNIX implementations, Linux follows the XSI requirement +when dealing with native filesystems. +However, some nonnative filesystems do not permit +.BR truncate () +and +.BR ftruncate () +to be used to extend a file beyond its current length: +a notable example on Linux is VFAT. +.\" At the very least: OSF/1, Solaris 7, and FreeBSD conform, mtk, Jan 2002 +.PP +The original Linux +.BR truncate () +and +.BR ftruncate () +system calls were not designed to handle large file offsets. +Consequently, Linux 2.4 added +.BR truncate64 () +and +.BR ftruncate64 () +system calls that handle large files. +However, these details can be ignored by applications using glibc, whose +wrapper functions transparently employ the more recent system calls +where they are available. +.PP +On some 32-bit architectures, +the calling signature for these system calls differ, +for the reasons described in +.BR syscall (2). +.SH BUGS +A header file bug in glibc 2.12 meant that the minimum value of +.\" http://sourceware.org/bugzilla/show_bug.cgi?id=12037 +.B _POSIX_C_SOURCE +required to expose the declaration of +.BR ftruncate () +was 200809L instead of 200112L. +This has been fixed in later glibc versions. +.SH SEE ALSO +.BR truncate (1), +.BR open (2), +.BR stat (2), +.BR path_resolution (7) |