svn commit: r283916 - in stable: 10/lib/libc/sys 8/lib/libc/sys 9/lib/libc/sys

[John Baldwin]

Author: jhb
Date: Tue Jun  2 15:12:33 2015
New Revision: 283916
URL: https://svnweb.freebsd.org/changeset/base/283916

Log:
  MFC 282417:
  Various updates to the ftruncate(2) documentation:
  - Note that ftruncate(2) can operate on shared memory objects and cross
    reference shm_open(2).
  - Note that ftruncate(2) does not change the file position pointer (aka
    seek pointer) of the file descriptor.
  - ftruncate(2) will fail with EINVAL for all sorts of other fd types than
    just sockets, so instead note that it fails for all but regular files and
    shared memory objects.
  - Note that ftruncate(2) also appeared in 4.2BSD along with truncate(2).
    (Or at least the manpage for both appeared in 4.2, I did not check the
    kernel code itself to see if either predated 4.2.)
  
  PR:		199472

Modified:
  stable/8/lib/libc/sys/truncate.2
Directory Properties:
  stable/8/lib/libc/   (props changed)
  stable/8/lib/libc/sys/   (props changed)

Changes in other areas also in this revision:
Modified:
  stable/10/lib/libc/sys/truncate.2
  stable/9/lib/libc/sys/truncate.2
Directory Properties:
  stable/10/   (props changed)
  stable/9/lib/libc/   (props changed)
  stable/9/lib/libc/sys/   (props changed)

Modified: stable/8/lib/libc/sys/truncate.2
==============================================================================
--- stable/8/lib/libc/sys/truncate.2	Tue Jun  2 15:09:33 2015	(r283915)
+++ stable/8/lib/libc/sys/truncate.2	Tue Jun  2 15:12:33 2015	(r283916)
@@ -28,7 +28,7 @@
 .\"     @(#)truncate.2	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd December 13, 2006
+.Dd May 4, 2015
 .Dt TRUNCATE 2
 .Os
 .Sh NAME
@@ -60,9 +60,18 @@ is lost.
 If the file was smaller than this size,
 it will be extended as if by writing bytes
 with the value zero.
-With
-.Fn ftruncate ,
-the file must be open for writing.
+.Pp
+The
+.Fn ftruncate
+system call causes the file or shared memory object backing the file descriptor
+.Fa fd
+to be truncated or extended to
+.Fa length
+bytes in size.
+The file descriptor must be a valid file descriptor open for writing.
+The file position pointer associated with the file descriptor
+.Fa fd
+will not be modified.
 .Sh RETURN VALUES
 .Rv -std
 If the file to be modified is not a directory or
@@ -129,7 +138,7 @@ is not a valid descriptor.
 The
 .Fa fd
 argument
-references a socket, not a file.
+references a file descriptor that is not a regular file or shared memory object.
 .It Bq Er EINVAL
 The
 .Fa fd
@@ -138,11 +147,14 @@ is not open for writing.
 .El
 .Sh SEE ALSO
 .Xr chflags 2 ,
-.Xr open 2
+.Xr open 2 ,
+.Xr shm_open 2
 .Sh HISTORY
 The
 .Fn truncate
-system call appeared in
+and
+.Fn ftruncate
+system calls appeared in
 .Bx 4.2 .
 .Sh BUGS
 These calls should be generalized to allow ranges