diff --git a/src/lib/libc/stdlib/posix_openpt.3 b/src/lib/libc/stdlib/posix_openpt.3 index d292ac0a..20b1c417 100644 --- a/src/lib/libc/stdlib/posix_openpt.3 +++ b/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 -.\" All rights reserved. +.\" Copyright (c) 2012 Todd C. Miller .\" -.\" 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.