diff options
Diffstat (limited to 'lib/libutil/pty.3')
-rw-r--r-- | lib/libutil/pty.3 | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/lib/libutil/pty.3 b/lib/libutil/pty.3 new file mode 100644 index 0000000..4af344d --- /dev/null +++ b/lib/libutil/pty.3 @@ -0,0 +1,143 @@ +.\" +.\" Copyright (c) 1996 Joerg Wunsch +.\" +.\" All rights reserved. +.\" +.\" 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 DEVELOPERS ``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 DEVELOPERS 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. +.\" +.\" $Id$ +.\" " +.Dd December 29, 1996 +.Os +.Dt PTY 3 +.Sh NAME +.Nm openpty, forkpty +.Nd auxiliary functions to obtain a pseudo-terminal +.Sh SYNOPSIS +.Fd #include <sys/types.h> +.Fd #include <sys/ioctl.h> +.Fd #include <termios.h> +.Fd #include <libutil.h> +.Ft int +.Fn openpty "int *amaster" "int *aslave" "char *name" "struct termios *termp" "struct winsize *winp" +.Ft int +.Fn forkpty "int *amaster" "char *name" "struct termios *termp" "struct winsize *winp" +.Pp +Link with +.Va -lutil +on the +.Xr cc 1 +command line. +.Sh DESCRIPTION +The function +.Nm openpty +attempts to obtain the next available pseudo-terminal from the system (see +.Xr pty 4 ) . +If it successfully found one, it subsequently tries to change the +ownership of the slave device to the real UID of the current process, +the group membership to the group +.Dq tty +(if such a group exists in the system), the access permissions for +reading and writing by the owner, and for writing by the group, and to +invalidate any current use of the line by calling +.Xr revoke 2 . +.Pp +If the argument +.Ar name +is not +.Dv NULL , +.Nm openpty +copies the pathname of the slave pty to this area. The caller is +responsible to allocate the required space in this array. +.Pp +If the arguments +.Ar termp +or +.Ar winp +are not +.Dv NULL , +.Nm openpty +initializes the termios and window size settings from the structures +these argument point to, respectively. +.Pp +Upon return, the open filedescriptors for the master and slave side +of the pty are returned in the locations pointed to by +.Ar amaster +and +.Ar aslave , +respectively. +.Pp +.Nm Forkpty +first calls +.Xr openpty 3 +to obtain the next available pseudo-terminal from the system. Upon success, +it forks off a new process. In the child process, it closes the descriptor +for the master side of the pty, and calls +.Xr login_tty 3 +for the slave pty. In the parent process, it closes the descriptor for the +slave side of the pty. The arguments +.Ar amaster , +.Ar name , +.Ar termp , +and +.Ar winp +have the same meaning as described for +.Nm openpty . +.Sh RETURN VALUES +.Nm Openpty +returns 0 on success, or -1 on failure. +.Pp +.Nm Forkpty +returns -1 on failure, 0 in the slave process, and the process ID of the +slave process in the parent process. +.Sh ERRORS +On failure, +.Nm openpty +will set the global variable +.Dv errno +to +.Er ENOENT . +.Pp +In addition to this, +.Nm forkpty +may set it to any value as described for +.Xr fork 2 . +.Sh SEE ALSO +.Xr chmod 2 , +.Xr chown 2 , +.Xr fork 2 , +.Xr getuid 2 , +.Xr open 2 , +.Xr revoke 2 , +.Xr login_tty 3 , +.Xr termios 3 , +.Xr pty 4 , +.Xr group 5 +.Sh BUGS +The calling process must have an effective UID of super-user in order +to perform all the intended actions. No notification will occur if +.Nm openpty +or +.Nm forkpty +failed to proceed with one of the described steps, as long as they could +at least allocate the pty at all (and create the new process in the case +of +.Nm forkpty ) . |