[unix-history] / usr / src / lib / libc / sys / truncate.2

.\" Copyright (c) 1983 Regents of the University of California.
.\" All rights reserved.  The Berkeley software License Agreement
.\" specifies the terms and conditions for redistribution.
.\"
.\"	@(#)truncate.2	6.3 (Berkeley) %G%
.\"
.TH TRUNCATE 2 ""
.UC 5
.SH NAME
truncate \- truncate a file to a specified length
.SH SYNOPSIS
.nf
.ft B
truncate(path, length)
char *path;
int length;
.PP
.ft B
ftruncate(fd, length)
int fd, length;
.fi
.SH DESCRIPTION
.I Truncate
causes the file named by
.I path
or referenced by
.I fd
to be truncated to at most
.I length
bytes in size.  If the file previously
was larger than this size, the extra data
is lost.
With
.IR ftruncate ,
the file must be open for writing.
.SH "RETURN VALUES
A value of 0 is returned if the call succeeds.  If the call
fails a \-1 is returned, and the global variable \fIerrno\fP
specifies the error.
.SH "ERRORS
.I Truncate
succeeds unless:
.TP 15
[ENOTDIR]
A component of the path prefix is not a directory.
.TP 15
[EINVAL]
The pathname contains a character with the high-order bit set.
.TP 15
[ENAMETOOLONG]
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.TP 15
[ENOENT]
The named file does not exist.
.TP 15
[EACCES]
Search permission is denied for a component of the path prefix.
.TP 15
[ELOOP]
Too many symbolic links were encountered in translating the pathname.
.TP 15
[EISDIR]
The named file is a directory.
.TP 15
[EROFS]
The named file resides on a read-only file system.
.TP 15
[ETXTBSY]
The file is a pure procedure (shared text) file that is being executed.
.TP 15
[EIO]
An I/O error occurred updating the inode.
.TP 15
[EFAULT]
.I Name
points outside the process's allocated address space.
.PP
.I Ftruncate
succeeds unless:
.TP 15
[EBADF]
The
.I fd
is not a valid descriptor.
.TP 15
[EINVAL]
The
.I fd
references a socket, not a file.
.SH "SEE ALSO"
open(2)
.SH BUGS
Partial blocks discarded as the result of truncation
are not zero filled; this can result in holes in files
that do not read as zero.
.PP
These calls should be generalized to allow ranges
of bytes in a file to be discarded.
Commit	Line	Data
813c5fba KM	1	.\" Copyright (c) 1983 Regents of the University of California.
	2	.\" All rights reserved. The Berkeley software License Agreement
	3	.\" specifies the terms and conditions for redistribution.
	4	.\"
eff6446c	5	.\" @(#)truncate.2 6.3 (Berkeley) %G%
813c5fba	6	.\"
19d481fa	7	.TH TRUNCATE 2 ""
813c5fba KM	8	.UC 5
	9	.SH NAME
	10	truncate \- truncate a file to a specified length
	11	.SH SYNOPSIS
	12	.nf
	13	.ft B
	14	truncate(path, length)
	15	char *path;
	16	int length;
	17	.PP
	18	.ft B
	19	ftruncate(fd, length)
	20	int fd, length;
	21	.fi
	22	.SH DESCRIPTION
	23	.I Truncate
	24	causes the file named by
	25	.I path
	26	or referenced by
	27	.I fd
	28	to be truncated to at most
	29	.I length
	30	bytes in size. If the file previously
	31	was larger than this size, the extra data
	32	is lost.
	33	With
	34	.IR ftruncate ,
	35	the file must be open for writing.
	36	.SH "RETURN VALUES
	37	A value of 0 is returned if the call succeeds. If the call
	38	fails a \-1 is returned, and the global variable \fIerrno\fP
	39	specifies the error.
	40	.SH "ERRORS
	41	.I Truncate
	42	succeeds unless:
	43	.TP 15
b5984ffe KM	44	[ENOTDIR]
b5984ffe KM	45	A component of the path prefix is not a directory.
813c5fba	46	.TP 15
b5984ffe KM	47	[EINVAL]
b5984ffe KM	48	The pathname contains a character with the high-order bit set.
813c5fba	49	.TP 15
b5984ffe KM	50	[ENAMETOOLONG]
	51	A component of a pathname exceeded 255 characters,
	52	or an entire path name exceeded 1023 characters.
813c5fba KM	53	.TP 15
	54	[ENOENT]
	55	The named file does not exist.
	56	.TP 15
	57	[EACCES]
b5984ffe KM	58	Search permission is denied for a component of the path prefix.
	59	.TP 15
	60	[ELOOP]
	61	Too many symbolic links were encountered in translating the pathname.
813c5fba KM	62	.TP 15
	63	[EISDIR]
	64	The named file is a directory.
	65	.TP 15
	66	[EROFS]
	67	The named file resides on a read-only file system.
	68	.TP 15
	69	[ETXTBSY]
	70	The file is a pure procedure (shared text) file that is being executed.
	71	.TP 15
b5984ffe KM	72	[EIO]
	73	An I/O error occurred updating the inode.
	74	.TP 15
813c5fba KM	75	[EFAULT]
	76	.I Name
	77	points outside the process's allocated address space.
	78	.PP
	79	.I Ftruncate
	80	succeeds unless:
	81	.TP 15
	82	[EBADF]
	83	The
	84	.I fd
	85	is not a valid descriptor.
	86	.TP 15
	87	[EINVAL]
	88	The
	89	.I fd
	90	references a socket, not a file.
	91	.SH "SEE ALSO"
	92	open(2)
	93	.SH BUGS
	94	Partial blocks discarded as the result of truncation
	95	are not zero filled; this can result in holes in files
eff6446c	96	that do not read as zero.
813c5fba KM	97	.PP
	98	These calls should be generalized to allow ranges
	99	of bytes in a file to be discarded.