Rewritten posix_openpt manual that doesn't include any of the POSIX

text.  OK deraadt@

src/lib/libc/stdlib/posix_openpt.3

@@ -1,50 +1,25 @@
-.\"     $OpenBSD: posix_openpt.3,v 1.1 2012/12/03 20:08:33 millert Exp $
+.\"     $OpenBSD: posix_openpt.3,v 1.2 2012/12/04 18:53:45 millert Exp $
 .\"
-.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
-.\" All rights reserved.
+.\" Copyright (c) 2012 Todd C. Miller <Todd.Miller@courtesan.com>
 .\"
-.\" Portions of this software were developed under sponsorship from Snow
-.\" B.V., the Netherlands.
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
-.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
-.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
-.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
-.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
-.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
-.\" SUCH DAMAGE.
-.\"
-.\" Portions of this text are reprinted and reproduced in electronic form
-.\" from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology --
-.\" Portable Operating System Interface (POSIX), The Open Group Base
-.\" Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of
-.\" Electrical and Electronics Engineers, Inc and The Open Group.  In the
-.\" event of any discrepancy between this version and the original IEEE and
-.\" The Open Group Standard, the original IEEE and The Open Group Standard is
-.\" the referee document.  The original Standard can be obtained online at
-.\"	http://www.opengroup.org/unix/online.html.
-.\"
-.\" $FreeBSD: head/lib/libc/sys/posix_openpt.2 181905 2008-08-20 08:31:58Z ed $
-.\"
-.Dd $Mdocdate: December 3 2012 $
+.Dd $Mdocdate: December 4 2012 $
 .Dt POSIX_OPENPT 3
 .Os
 .Sh NAME
 .Nm posix_openpt
-.Nd "open a pseudo-terminal device"
+.Nd open a pseudo-terminal device
 .Sh SYNOPSIS
 .In stdlib.h
 .In fcntl.h
@@ -53,48 +28,55 @@
 .Sh DESCRIPTION
 The
 .Fn posix_openpt
-function allocates a new pseudo-terminal and establishes a connection
-with its master device.
-After the pseudo-terminal has been allocated, the slave device should
-have the proper permissions before it can be used (see
-.Xr grantpt 3 ) .
-The name of the slave device can be determined by calling
-.Xr ptsname 3 .
+function finds the next available pseudo-terminal and returns an open
+file descriptor for its master device.
+The path name of the slave device may be determined via the
+.Fn ptsname
+function.
+Note that the
+.Fn unlockpt
+and
+.Fn grantpt
+functions should be called before opening the slave device.
 .Pp
-The file status flags and file access modes of the open file description
-shall be set according to the value of
-.Fa oflag .
-Values for
-.Fa oflag
-are constructed by a bitwise-inclusive OR of flags from the following
-list, defined in
+The
+.Ar oflag
+argument is formed by bitwise-inclusive
+.Tn OR Ns 'ing
+the following values defined in
 .In fcntl.h :
-.Bl -tag -width ".Dv O_NOCTTY"
+.Pp
+.Bl -tag -width O_NOCTTY -offset indent
 .It Dv O_RDWR
 Open for reading and writing.
 .It Dv O_NOCTTY
-If set
-.Fn posix_openpt
-shall not cause the terminal device to become the controlling terminal
-for the process.
+Prevent the device from being made the controlling terminal for the session.
+This flag has no effect on
+.Ox
+and is included for compatibility with other systems.
 .El
 .Pp
 The
-.Fn posix_openpt
-function shall fail when
+.Dv O_RDWR
+flag must be specified in
+.Fa oflag .
+If
 .Fa oflag
-contains other values.
+contains values other than those listed above,
+.Fn posix_openpt
+will return an error.
 .Sh RETURN VALUES
-Upon successful completion, the
+If successful,
 .Fn posix_openpt
-function shall allocate a new pseudo-terminal device and return a
-non-negative integer representing a file descriptor, which is connected
-to its master device.
-Otherwise, -1 shall be returned and errno set to indicate the error.
+returns a non-negative integer, the file descriptor for the
+pseudo-terminal master device.
+Otherwise, a value of \-1 is returned and
+.Va errno
+is set to indicate the error.
 .Sh ERRORS
 The
 .Fn posix_openpt
-function shall fail if:
+function will fail if:
 .Bl -tag -width Er
 .It Bq Er EMFILE
 The per-process descriptor table is full.
@@ -119,10 +101,3 @@ The
 .Fn posix_openpt
 function appeared in
 .Ox 5.3 .
-.Sh CAVEATS
-The flag
-.Dv O_NOCTTY
-is included for compatibility; in
-.Ox ,
-opening a terminal does not cause it to become a process's controlling
-terminal.