grantpt() and unlockpt() using /dev/ptm. Man pages from FreeBSD. OK kettenis@ deraadt@ beck@ ajacoutot@ naddy@OPENBSD_5_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. |
@ -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; | |||
} |
@ -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 . |