irix-657m-src/eoe/man/man2/truncate.2

'\"macro stdmacro
.if n .pH 3c/gen/truncate @(#)truncate	43.5 of 8/4/92
.\" Copyright 1992, 1991 UNIX System Laboratories, Inc.
.\" Copyright 1990, 1989 AT&T
.TH TRUNCATE 2
.SH NAME
.Op c p a
.B \f4truncate\f1, \f4ftruncate\f1, \f4truncate64\f1, \f4ftruncate64\f1
\- set a file to a specified length
.br
.Op
.Op f
.B \f4truncate\f1, \f4truncate64\f1
\- set a file to a specified length
.Op
.Op c p a
.SH C SYNOPSIS
\f4#include <unistd.h>\f1
.PP
\f4int truncate (const char \(**\f2path\fP, off_t \f2length\fP);\f1
.PP
\f4int ftruncate (int \f2fildes\fP, off_t \f2length\fP);\f1
.PP
\f4int truncate64 (const char \(**\f2path\fP, off64_t \f2length\fP);\f1
.PP
\f4int ftruncate64 (int \f2fildes\fP, off64_t \f2length\fP);\f1
.Op
.Op f
.SH FORTRAN SYNOPSIS
\f4integer\(**4 truncate (\f2path\fP, \f2length\fP);\f1
.br
\f4integer\(**4 truncate64 (\f2path\fP, \f2length64\fP);\f1
.br
.B "character * (*) path"
.br
.B "integer\(**4 length"
.br
.B "integer\(**8 length64"
.Op
.SH DESCRIPTION
The file whose name is given by \f2path\f1
.Op c p a
or referenced by the
descriptor \f2fildes\f1
.Op
has its size set to \f2length\f1
.Op f
(or length64)
.Op
bytes.
.P
If the file was previously longer than \f2length\f1,
bytes past \f2length\f1 will no longer be accessible.
If it was shorter, bytes from the
.SM EOF
before the call to the
.SM EOF
after the call will be read in as zeros.
The effective user
.SM ID
of the process must have write permission for
the file, and
for \f4ftruncate\f1 and \f4ftruncate64\f1 the file must be open for writing.
.P
The only difference between the regular routines and the \(**64 routines
is that \f2length\f1 is a 64-bit value for the \(**64 routines, 
allowing files longer than 2 gigabytes in size to be truncated.
This is relevant only on certain filesystem types.
.P
\f4truncate\f1 and \f4truncate64\f1 fail
if one or more of the following are true:
.TP 18
\f4EACCES\fP
Search permission is denied on a component of the path prefix.
.TP
\f4EACCES\fP
Write permission is denied for the file referred to by
.IR path .
.TP 18
\f4EAGAIN\fP
The file exists, mandatory file/record locking is set, and there are
outstanding record locks on the file [see \f4chmod\fP(2)].
.\" SGI - we don't do this in 5.0
This restriction is not currently enforced.
.TP
\f4EFAULT\fP
.I path
points outside the process's allocated address space.
.TP
\f4EFBIG\fP
An attempt is made to write a file that exceeds the
process's file size limit or the maximum file size
[see
\f4getrlimit\fP(2)
and
\f4ulimit\fP(2)].
.TP
\f4EINTR\fP
A signal was caught during execution of the \f4truncate\f1 or
\f4truncate64\f1 routine.
.TP
\f4EINVAL\fP
.I path
is not an ordinary file.
.TP
\f4EINVAL\fP
\f2length\fP is less than zero.
.TP
\f4EIO\fP
An I/O error occurred while reading from or writing to the file system.
.TP
\f4EISDIR\fP
The file referred to by
.I path
is a directory.
.TP
\f4ELOOP\fP
Too many symbolic links were encountered in translating
.IR path .
.\".TP
.\"\f4EMFILE\fP
.\"The maximum number of file descriptors available to the process has been
.\"reached.
.\".TP
.\"\f4EMULTIHOP\fP
.\"Components of
.\".I path
.\"require hopping to multiple remote machines
.\"and file system type does not allow it.
.TP
\f4ENAMETOOLONG\fP
The length of a \f2path\f1 component
exceeds {NAME_MAX} characters,
or the length of
.I path
exceeds {PATH_MAX} characters.
.\".TP
.\"\f4ENFILE\fP
.\"Could not allocate any more space for the system file table.
.TP
\f4ENOENT\fP
Either a component of the path prefix or the file referred to by
.I path
does not exist.
.\".TP
.\"\f4ENOLINK\fP
.\".I path
.\"points to a remote machine and the link to that machine is no longer
.\"active.
.TP
\f4ENOTDIR\fP
A component of the path prefix of
.I path
is not a directory.
.TP
\f4EROFS\fP
The file referred to by
.I path
resides on a read-only file system.
.TP
\f4ETIMEDOUT\fP
The object of the write is located on a remote system which is not available [see \f4intro\fP(2)].
.\".TP
.\"\f4ETXTBSY\fP
.\"The file referred to by
.\".I path
.\"is a pure procedure (shared text) file that is being executed.
.P
\f4ftruncate\fP and \f4ftruncate64\fP
fail if one or more of the following are true:
.TP 18
\f4EAGAIN\fP
The file exists, mandatory file/record locking is set, and there are
outstanding record locks on the file [see \f4chmod\fP(2)].
.\" SGI - we don't do this in 5.0
This restriction is not currently enforced.
.TP
\f4EBADF\fP
.I fildes
is not a file descriptor open for writing.
.TP
\f4EFBIG\fP
An attempt is made to write a file that exceeds the
process's file size limit or the maximum file size
[see
\f4getrlimit\fP(2)
and
\f4ulimit\fP(2)].
.TP
\f4EINTR\fP
A signal was caught during execution of the \f4ftruncate\f1 or
\f4ftruncate64\f1 routine.
.TP
\f4EINVAL\fP
\f2length\fP is less than zero.
.TP
\f4EINVAL\fP
.I fildes
does not correspond to an ordinary file.
.TP
\f4EIO\fP
An I/O error occurred while reading from or writing to the file system.
.\".TP
.\"\f4ENOLINK\fP
.\".I fildes
.\"points to a remote machine and the link to that machine is no longer
.\"active.
.TP
\f4ETIMEDOUT\fP
The object of the write is located on a remote system which is not available [see \f4intro\fP(2)].
.SH "SEE ALSO"
\f4fcntl\fP(2),
\f4getrlimit\fP(2),
\f4open\fP(2)
.SH DIAGNOSTICS
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and
\f4errno\fP
is set to indicate the error.
.SH BUGS
Partial blocks discarded as the result of truncation
are not zero filled; this can result in holes in files
which do not read as zero.
.PP
These calls should be generalized to allow ranges
of bytes in a file to be discarded.