Simple emulation of POSIX pty APIs posix_openpt(), ptsname(),

grantpt() and unlockpt() using /dev/ptm.  Man pages from FreeBSD.
OK kettenis@ deraadt@ beck@ ajacoutot@ naddy@

4 files changed, 414 insertions, 6 deletions

diff --git a/src/lib/libc/stdlib/Makefile.inc b/src/lib/libc/stdlib/Makefile.inc
index 652d6fb90f..5f3a142ec4 100644
--- a/src/lib/libc/stdlib/Makefile.inc
+++ b/src/lib/libc/stdlib/Makefile.inc
@@ -1,4 +1,4 @@
-#       $OpenBSD: Makefile.inc,v 1.46 2012/09/15 20:59:38 miod Exp $
+#       $OpenBSD: Makefile.inc,v 1.47 2012/12/03 20:08:33 millert Exp $
 
 # stdlib sources
 .PATH: ${LIBCSRCDIR}/arch/${MACHINE_CPU}/stdlib ${LIBCSRCDIR}/stdlib
@@ -6,8 +6,8 @@
 SRCS+=  a64l.c abort.c atexit.c atoi.c atof.c atol.c atoll.c bsearch.c \
         cfree.c exit.c ecvt.c gcvt.c getenv.c getopt_long.c \
         getsubopt.c hcreate.c heapsort.c imaxabs.c imaxdiv.c l64a.c llabs.c \
-        lldiv.c lsearch.c malloc.c merge.c qsort.c radixsort.c rand.c \
-        random.c realpath.c setenv.c strtoimax.c strtol.c \
+        lldiv.c lsearch.c malloc.c merge.c posix_pty.c qsort.c radixsort.c \
+        rand.c random.c realpath.c setenv.c strtoimax.c strtol.c \
         strtoll.c strtonum.c strtoul.c strtoull.c strtoumax.c system.c \
         tfind.c tsearch.c _rand48.c drand48.c erand48.c jrand48.c lcong48.c \
         lrand48.c mrand48.c nrand48.c seed48.c srand48.c qabs.c qdiv.c _Exit.c
@@ -34,9 +34,9 @@ SRCS+=	insque.c remque.c
 MAN+=   a64l.3 abort.3 abs.3 alloca.3 atexit.3 atof.3 atoi.3 atol.3 atoll.3 \
         bsearch.3 div.3 ecvt.3 exit.3 getenv.3 getopt.3 getopt_long.3 \
         getsubopt.3 hcreate.3 imaxabs.3 imaxdiv.3 insque.3 labs.3 ldiv.3 \
-        lldiv.3 lsearch.3 malloc.3 posix_memalign.3 qabs.3 qdiv.3 qsort.3 \
-        radixsort.3 rand48.3 rand.3 random.3 realpath.3 strtod.3 strtonum.3 \
-        strtol.3 strtoul.3 system.3 tsearch.3
+        lldiv.3 lsearch.3 malloc.3 posix_memalign.3 posix_openpt.3 ptsname.3 \
+        qabs.3 qdiv.3 qsort.3 radixsort.3 rand48.3 rand.3 random.3 realpath.3 \
+        strtod.3 strtonum.3 strtol.3 strtoul.3 system.3 tsearch.3
 
 MLINKS+=exit.3 _Exit.3
 MLINKS+=ecvt.3 fcvt.3 ecvt.3 gcvt.3
@@ -56,6 +56,7 @@ MLINKS+=random.3 srandom.3 random.3 srandomdev.3
 MLINKS+=rand48.3 drand48.3 rand48.3 erand48.3 rand48.3 lrand48.3
 MLINKS+=rand48.3 mrand48.3 rand48.3 nrand48.3 rand48.3 jrand48.3
 MLINKS+=rand48.3 srand48.3 rand48.3 seed48.3 rand48.3 lcong48.3
+MLINKS+=ptsname.3 grantpt.3 ptsname.3 unlockpt.3
 MLINKS+=strtod.3 strtof.3 strtod.3 strtold.3
 MLINKS+=strtol.3 strtoll.3 strtol.3 strtoq.3 strtol.3 strtoimax.3
 MLINKS+=strtoul.3 strtoull.3 strtoul.3 strtouq.3 strtoul.3 strtoumax.3
diff --git a/src/lib/libc/stdlib/posix_openpt.3 b/src/lib/libc/stdlib/posix_openpt.3
new file mode 100644
index 0000000000..d292ac0a5f
--- /dev/null
+++ b/src/lib/libc/stdlib/posix_openpt.3
@@ -0,0 +1,128 @@
+.\"     $OpenBSD: posix_openpt.3,v 1.1 2012/12/03 20:08:33 millert Exp $
+.\"
+.\" Copyright (c) 2008 Ed Schouten <ed@FreeBSD.org>
+.\" All rights reserved.
+.\"
+.\" Portions of this software were developed under sponsorship from Snow
+.\" B.V., the Netherlands.
+.\"
+.\" 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.
+.\"
+.\" 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 $
+.Dt POSIX_OPENPT 3
+.Os
+.Sh NAME
+.Nm posix_openpt
+.Nd "open a pseudo-terminal device"
+.Sh SYNOPSIS
+.In stdlib.h
+.In fcntl.h
+.Ft int
+.Fn posix_openpt "int oflag"
+.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 .
+.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
+.In fcntl.h :
+.Bl -tag -width ".Dv O_NOCTTY"
+.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.
+.El
+.Pp
+The
+.Fn posix_openpt
+function shall fail when
+.Fa oflag
+contains other values.
+.Sh RETURN VALUES
+Upon successful completion, the
+.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.
+.Sh ERRORS
+The
+.Fn posix_openpt
+function shall fail if:
+.Bl -tag -width Er
+.It Bq Er EMFILE
+The per-process descriptor table is full.
+.It Bq Er ENFILE
+The system file table is full.
+.It Bq Er EINVAL
+The value of
+.Fa oflag
+is not valid.
+.El
+.Sh SEE ALSO
+.Xr ptsname 3 ,
+.Xr pty 4 ,
+.Xr tty 4
+.Sh STANDARDS
+The
+.Fn posix_openpt
+function conforms to
+.St -p1003.1-2001 .
+.Sh HISTORY
+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.
diff --git a/src/lib/libc/stdlib/posix_pty.c b/src/lib/libc/stdlib/posix_pty.c
new file mode 100644
index 0000000000..a2025ddbb6
--- /dev/null
+++ b/src/lib/libc/stdlib/posix_pty.c
@@ -0,0 +1,119 @@
+/*      $OpenBSD: posix_pty.c,v 1.1 2012/12/03 20:08:33 millert Exp $   */
+
+/*
+ * Copyright (c) 2012 Todd C. Miller <Todd.Miller@courtesan.com>
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+#include <sys/types.h>
+#include <sys/ioctl.h>
+#include <sys/stat.h>
+#include <sys/tty.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <paths.h>
+#include <stddef.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+int
+posix_openpt(int oflag)
+{
+        struct ptmget ptm;
+        int fd, mfd = -1;
+
+        /* User must specify O_RDWR in oflag. */
+        if (!(oflag & O_RDWR)) {
+                errno = EINVAL;
+                return -1;
+        }
+
+        /* Get pty master and slave (this API only uses the master). */
+        fd = open(PATH_PTMDEV, O_RDWR);
+        if (fd != -1) {
+                if (ioctl(fd, PTMGET, &ptm) != -1) {
+                        close(ptm.sfd);
+                        mfd = ptm.cfd;
+                }
+                close(fd);
+        }
+
+        return mfd;
+}
+
+/*
+ * Look up the name of the specified pty master fd.
+ * Note that the name returned does *not* include the /dev/ prefix.
+ * Returns the name on success and NULL on error, setting errno.
+ */
+static const char *
+ptmname(int mfd)
+{
+        struct stat sb;
+        const char *name;
+
+        /* Make sure it is a pty master. */
+        if (fstat(mfd, &sb) != 0)
+                return NULL;
+        if (!S_ISCHR(sb.st_mode)) {
+                errno = EINVAL;
+                return NULL;
+        }
+        name = devname(sb.st_rdev, S_IFCHR);
+        if (strncmp(name, "pty", 3) != 0) {
+                errno = EINVAL;
+                return NULL;
+        }
+        return name;
+}
+
+/*
+ * The PTMGET ioctl handles the mode and owner for us.
+ */
+int
+grantpt(int mfd)
+{
+        return ptmname(mfd) ? 0 : -1;
+}
+
+/*
+ * The PTMGET ioctl unlocks the pty master and slave for us.
+ */
+int
+unlockpt(int mfd)
+{
+        return ptmname(mfd) ? 0 : -1;
+}
+
+/*
+ * Look up the path of the slave pty that corresponds to the master fd.
+ * Returns the path if successful or NULL on error.
+ */
+char *
+ptsname(int mfd)
+{
+        const char *master;
+        static char slave[sizeof(((struct ptmget *)NULL)->sn)];
+
+        if ((master = ptmname(mfd)) == NULL)
+                return NULL;
+
+        /* Add /dev/ prefix and convert "pty" to "tty". */
+        strlcpy(slave, _PATH_DEV, sizeof(slave));
+        strlcat(slave, master, sizeof(slave));
+        slave[sizeof(_PATH_DEV) - 1] = 't';
+
+        return slave;
+}
diff --git a/src/lib/libc/stdlib/ptsname.3 b/src/lib/libc/stdlib/ptsname.3
new file mode 100644
index 0000000000..3d7cd979d5
--- /dev/null
+++ b/src/lib/libc/stdlib/ptsname.3
@@ -0,0 +1,160 @@
+.\"     $OpenBSD: ptsname.3,v 1.1 2012/12/03 20:08:33 millert Exp $
+.\"
+.\" Copyright (c) 2002 The FreeBSD Project, Inc.
+.\" All rights reserved.
+.\"
+.\" This software includes code contributed to the FreeBSD Project
+.\" by Ryan Younce of North Carolina State University.
+.\"
+.\" 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.
+.\" 3. Neither the name of the FreeBSD Project nor the names of its
+.\"    contributors may be used to endorse or promote products derived from
+.\"    this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE FREEBSD PROJECT 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 FREEBSD PROJECT
+.\" OR ITS 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.
+.\"
+.\" $FreeBSD: head/lib/libc/stdlib/ptsname.3 240412 2012-09-12 17:54:09Z emaste $
+.\"
+.Dd $Mdocdate: December 3 2012 $
+.Dt PTSNAME 3
+.Os
+.Sh NAME
+.Nm grantpt ,
+.Nm ptsname ,
+.Nm unlockpt
+.Nd pseudo-terminal access functions
+.Sh SYNOPSIS
+.In stdlib.h
+.Ft int
+.Fn grantpt "int fildes"
+.Ft "char *"
+.Fn ptsname "int fildes"
+.Ft int
+.Fn unlockpt "int fildes"
+.Sh DESCRIPTION
+The
+.Fn grantpt ,
+.Fn ptsname ,
+and
+.Fn unlockpt
+functions allow access to pseudo-terminal devices.
+These three functions accept a file descriptor that references the
+master half of a pseudo-terminal pair.
+This file descriptor is created with
+.Xr posix_openpt 3 .
+.Pp
+The
+.Fn grantpt
+function is used to establish ownership and permissions
+of the slave device counterpart to the master device
+specified with
+.Fa fildes .
+The slave device's ownership is set to the real user ID
+of the calling process, and the permissions are set to
+user readable-writable and group writable.
+The group owner of the slave device is also set to the
+group
+.Dq Li tty .
+.Pp
+The
+.Fn ptsname
+function returns the full pathname of the slave device
+counterpart to the master device specified with
+.Fa fildes .
+This value can be used
+to subsequently open the appropriate slave after
+.Xr posix_openpt 3
+and
+.Fn grantpt
+have been called.
+.Pp
+The
+.Fn unlockpt
+function clears the lock held on the pseudo-terminal pair
+for the master device specified with
+.Fa fildes .
+.Sh RETURN VALUES
+.Rv -std grantpt unlockpt
+.Pp
+The
+.Fn ptsname
+function returns a pointer to the name
+of the slave device on success; otherwise a
+.Dv NULL
+pointer is returned.
+.Sh ERRORS
+The
+.Fn grantpt ,
+.Fn ptsname
+and
+.Fn unlockpt
+functions may fail and set
+.Va errno
+to:
+.Bl -tag -width Er
+.It Bq Er EBADF
+.Fa fildes
+is not a valid open file descriptor.
+.It Bq Er EINVAL
+.Fa fildes
+is not a master pseudo-terminal device.
+.El
+.Pp
+In addition, the
+.Fn grantpt
+function may set
+.Va errno
+to:
+.Bl -tag -width Er
+.It Bq Er EACCES
+The slave pseudo-terminal device could not be accessed.
+.El
+.Sh SEE ALSO
+.Xr posix_openpt 3 ,
+.Xr pty 4 ,
+.Xr tty 4
+.Sh STANDARDS
+The
+.Fn ptsname
+function conforms to
+.St -p1003.1-2008 .
+.Pp
+This implementation of
+.Fn grantpt
+and
+.Fn unlockpt
+does not conform to
+.St -p1003.1-2008 ,
+because it depends on
+.Xr posix_openpt 3
+to create the pseudo-terminal device with proper permissions in place.
+It only validates whether
+.Fa fildes
+is a valid pseudo-terminal master device.
+Future revisions of the specification will likely allow this behaviour,
+as stated by the Austin Group.
+.Sh HISTORY
+The
+.Fn grantpt ,
+.Fn ptsname
+and
+.Fn unlockpt
+functions appeared in
+.Ox 5.3 .