From owner-svn-src-all@FreeBSD.ORG  Thu Jul  5 17:02:21 2012
Return-Path: <owner-svn-src-all@FreeBSD.ORG>
Delivered-To: svn-src-all@freebsd.org
Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:4f8:fff6::34])
	by hub.freebsd.org (Postfix) with ESMTP id 4DC2C1065670;
	Thu,  5 Jul 2012 17:02:21 +0000 (UTC)
	(envelope-from brooks@FreeBSD.org)
Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c])
	by mx1.freebsd.org (Postfix) with ESMTP id 364CD8FC12;
	Thu,  5 Jul 2012 17:02:21 +0000 (UTC)
Received: from svn.freebsd.org (localhost [127.0.0.1])
	by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q65H2LGH086701;
	Thu, 5 Jul 2012 17:02:21 GMT (envelope-from brooks@svn.freebsd.org)
Received: (from brooks@localhost)
	by svn.freebsd.org (8.14.4/8.14.4/Submit) id q65H2LxM086699;
	Thu, 5 Jul 2012 17:02:21 GMT (envelope-from brooks@svn.freebsd.org)
Message-Id: <201207051702.q65H2LxM086699@svn.freebsd.org>
From: Brooks Davis <brooks@FreeBSD.org>
Date: Thu, 5 Jul 2012 17:02:20 +0000 (UTC)
To: src-committers@freebsd.org, svn-src-all@freebsd.org,
	svn-src-head@freebsd.org
X-SVN-Group: head
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Cc: 
Subject: svn commit: r238141 - head/lib/libc/gen
X-BeenThere: svn-src-all@freebsd.org
X-Mailman-Version: 2.1.5
Precedence: list
List-Id: "SVN commit messages for the entire src tree \(except for &quot;
	user&quot; and &quot; projects&quot; \)" <svn-src-all.freebsd.org>
List-Unsubscribe: <http://lists.freebsd.org/mailman/listinfo/svn-src-all>,
	<mailto:svn-src-all-request@freebsd.org?subject=unsubscribe>
List-Archive: <http://lists.freebsd.org/pipermail/svn-src-all>
List-Post: <mailto:svn-src-all@freebsd.org>
List-Help: <mailto:svn-src-all-request@freebsd.org?subject=help>
List-Subscribe: <http://lists.freebsd.org/mailman/listinfo/svn-src-all>,
	<mailto:svn-src-all-request@freebsd.org?subject=subscribe>
X-List-Received-Date: Thu, 05 Jul 2012 17:02:21 -0000

Author: brooks
Date: Thu Jul  5 17:02:20 2012
New Revision: 238141
URL: http://svn.freebsd.org/changeset/base/238141

Log:
  Document the behavior (from 4.4-lite) that tokens returned by telldir() are
  single use.
  
  Sponsored by:	DARPA, AFRL
  MFC after:	3 days

Modified:
  head/lib/libc/gen/directory.3

Modified: head/lib/libc/gen/directory.3
==============================================================================
--- head/lib/libc/gen/directory.3	Thu Jul  5 16:02:14 2012	(r238140)
+++ head/lib/libc/gen/directory.3	Thu Jul  5 17:02:20 2012	(r238141)
@@ -28,7 +28,7 @@
 .\"     @(#)directory.3	8.1 (Berkeley) 6/4/93
 .\" $FreeBSD$
 .\"
-.Dd April 16, 2008
+.Dd July 5, 2012
 .Dt DIRECTORY 3
 .Os
 .Sh NAME
@@ -153,7 +153,7 @@ returns 0 on success or an error number 
 The
 .Fn telldir
 function
-returns the current location associated with the named
+returns a token representing the current location associated with the named
 .Em directory stream .
 Values returned by
 .Fn telldir
@@ -179,6 +179,13 @@ The new position reverts to the one asso
 when the
 .Fn telldir
 operation was performed.
+State associated with the token returned by
+.Fn telldir is freed when it is passed to
+.Fn seekdir .
+If you wish return to the same location again,
+then you must create a new token with another
+.Fn telldir
+call.
 .Pp
 The
 .Fn rewinddir
@@ -245,3 +252,9 @@ The
 .Fn fdopendir
 function appeared in
 .Fx 8.0 .
+.Sh BUGS
+The invalidation of
+.Fn telldir
+tokens when calling
+.Fn seekdir
+is non-standard.