pts(7)                                                               pts(7)




 NAME    [Toc]    [Back]
      pts - STREAMS slave pty (pseudo-terminal) driver

 SYNOPSIS    [Toc]    [Back]
      #include <sys/stropts.h>
      #include <sys/termios.h>
      #include <sys/strtio.h>

      int open("/dev/pts/N", O_RDWR);

 DESCRIPTION    [Toc]    [Back]
      A pseudo-terminal (pty) consists of a tightly-coupled pair of
      character devices, called the master device and slave device.  The pty
      master and slave device drivers work together to simulate a terminal
      connection where the master provides a connection to the pseudo
      terminal server process and the slave provides a terminal device
      special file access for the terminal application processes, as
      depicted below:

                             ----------------
                            | pty functions  |
           Application <--> |----------------| <--> Server
            Processes       | Slave | Master |       Process
                            | (pts) | (ptm)  |
                             ----------------

      The slave driver, pts with ptem (STREAMS pty emulation module) and
      ldterm (STREAMS line discipline module) pushed on top (not shown for
      simplicity), provides a terminal interface as described in termio(7).
      Whereas devices that provide the terminal interface described in
      termio(7) have a hardware device behind them; in contrast, the slave
      device has another process manipulating it through the master side of
      the pty.  Data written on the master device is given to the slave
      device as input and data written on the slave device is presented as
      input on the master device.

      In order to use the STREAMS pty subsystem, a node for the master pty
      driver /dev/ptmx and N number of slave pty devices must be installed
      (see ptm(7) for more details on master pty).  When the master device
      is opened, the corresponding slave device is automatically locked out.
      No user can open that slave device until its permissions are changed
      (via the grantpt() function) and the device is unlocked (via the
      unlockpt() function).  The user then call the ptsname() function to
      obtain the name of the slave device and invoke the open() system call
      to open the slave device.  Although only one open is allowed on a
      master device, multiple opens are allowed on the slave device.  After
      both the master and slave have been opened, the user has two file
      descriptors which represent the end points of a full duplex connection
      composed of two streams that are automatically connected by the master
      and slave devices when they are opened.  The user may then push the
      desired modules (for example, ptem and ldterm, on pts for terminal



 Hewlett-Packard Company            - 1 -   HP-UX 11i Version 2: August 2003






 pts(7)                                                               pts(7)




      semantics and pckt on ptm for Packet Mode feature).

      The master and slave drivers pass all STREAMS messages to their
      adjacent drivers.  Only the M_FLUSH message needs some special
      processing because the read queue of the master is connected to the
      write queue of the slave and vice versa.  For example, the FLUSHR flag
      is changed to FLUSHW flag and vice versa whenever a M_FLUSH message
      travels across the master-slave link.  When the master device is
      closed, an M_HANGUP message is sent to the corresponding slave device
      which will render that slave device unusable.  The process on the
      slave side gets the errno [ENXIO] when attempting a write() system
      call to the slave device file but it will be able to read any data
      remaining in the slave stream.  Finally, when all the data has been
      read, the read() system call will return 0, indicating that the slave
      can no longer be used.  On the last close of the slave device, a
      zero-length M_DATA message is sent to the corresponding master device.
      When the application on the master side issues a read(2) or getmsg(2)
      system calls, a 0 (zero) is returned.  The user of the master device
      may decide to close the master device file, which dismantles the
      stream on the master side.  If the master device remains opened, the
      corresponding slave device can be opened and used again by another
      user.

 EXAMPLES    [Toc]    [Back]
      The following example shows how a STREAMS pty master and slave devices
      are typically opened.

           int fd_master, fd_slave;
           char *slave;
              ...

                fd_master = open("/dev/ptmx", O_RDWR);
                grantpt(fd_master);
                unlockpt(fd_master);
                slave = ptsname(fd_master);
                fd_slave = open(slave, O_RDWR);
                ioctl(fd_slave, I_PUSH, "ptem");
                ioctl(fd_slave, I_PUSH, "ldterm");

 AUTHOR    [Toc]    [Back]
      pts was developed by HP and OSF.

 FILES    [Toc]    [Back]
      /dev/ptmx         Streams pty master clone device
      /dev/pts/N        Streams pty slave devices (0 <= N < NSTRPTY), where
                        NSTRPTY is a kernel tunable parameter which can be
                        changed via SAM (see sam(1M)).

 SEE ALSO    [Toc]    [Back]
      insf(1M), sam(1M), getmsg(2), ioctl(2), open(2), read(2), write(2),
      grantpt(3C), ptsname(3C), unlockpt(3C), ldterm(7), ptem(7), ptm(7),



 Hewlett-Packard Company            - 2 -   HP-UX 11i Version 2: August 2003






 pts(7)                                                               pts(7)




      streamio(7), termio(7).


 Hewlett-Packard Company            - 3 -   HP-UX 11i Version 2: August 2003