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 ) .