The term "tty" is a contraction of Teletype, maker of such famous icons as the Model 37 terminal. Printing noisily on paper, with margin bell and optional paper tape punch, it was a multimedia device in its own right. Historians can review its output in the early service of UNIX at http://cm.bell-labs.com/cm/cs/who/dmr/1stEdman.html

The standard configuration in those days was

shell—tty driver == tty

where "--" indicates a user/kernel space interface, and "==" is a serial cable. Hard copy terminals were replaced in time by "glass" ttys, and ttys were replaced altogether by the PC (running a terminal emulator program):

shell—tty driver == tty driver—tty emulator

As the PC gained CPU power and OS sophistication, there was no need for the command line (shell) to reside on a distant, and expensive, mini-computer or mainframe. This has resulted in entirely local plumbing like so:

shell—pty driver—tty emulator

In essence, the pseudo-tty, or pty, driver acts as a tty driver with serial line looped back. This concept was pioneered by the Berkeley version of Unix, and is now universally available on UNIX and UNIX-like systems.

Two distinct, but related, reasons for using the pty driver are to direct interactive programs, and to provide tty services for them. These reasons apply to command line programs only; BeOS apps that function graphically are not going to be interested.

An interactive program tends to write stdout unbuffered or line-by-line. This is less efficient, but operates sensibly with alternating prompts and user input. The user can better see realtime progress, too. Posix libraries determine whether the output is a "terminal" and, if not, buffer output fully. Unfortunately, this means that running an interactive program through a pipe doesn't work well:

(sleep 1; echo bc; echo 1; echo '2^99999/2^99998') | sh
(sleep 1; echo bc; echo 1; echo '2^99999/2^99998') | sh | cat

In the first case, the shell is instructed to start the desk calculator bc, which evaluates arithmetic expressions. Since the output is a terminal, we see each result as it's ready. In the second case, bc is writing to a pipe, and all results are buffered until it exits.

Some programs behave even more radically when the output is a terminal. Compare

ls /bin
ls /bin | cat

The general desire in all these cases is to control the shell and its subprocesses with our own program, while appearing to be a terminal at the far end of a serial line.

The second reason for using the pty driver is to provide tty services, which includes input echoing, character erase (ctrl+H), signals (ctrl+C), etc. The services in BeOS are a subset of the Posix "termios" standard. As an example, the Backspace key (ctrl+H) erases the last character on the current line of input; a program like bc will see the fully formed line only when you hit Return.

Current BeOS clients of the pty driver include "telnetd" (incoming telnet connections), /bin/getty (shell session on serial port), Terminal, and Pavel's Eddie (C++ development environment).

The remainder of this article documents the code for a useful app called "script." Modeled after the similarly named UNIX utility, it starts an interactive subshell such that all I/O activity is recorded verbatim to a log file, called "typescript." The code consists of two parts: first, a reusable class called PTY and second, the particular use of this code for "script."

Here is the declaration for the PTY class, which conveniently wraps the pty driver. A program like "script" has quite a few chores, but these are handled almost entirely by PTY. To use, you must derive your own class from PTY, and define the hook functions GetData(), PutData(), and Done(). Their purpose is described later.

#include        <Application.h>
#include        <signal.h>
#include        <stdlib.h>
#include        <stdio.h>
#include        <string.h>
#include        <termios.h>
#include        <dirent.h>

#define ctrl( c)        ((c) - 0100)

struct PTY {
                     PTY( );
                     ~PTY( );
     bool            Init( char *[]);
     virtual int     GetData( uchar [], uint)        = 0;
     virtual int     PutData( uchar [], uint)        = 0;
     virtual void    Done( )                         = 0;
     private:
     bool            ptyinit( );
     static int32    feeder( PTY *),
                     drainer( PTY *);
     struct termios  tsaved;
     int             ptyfd,
                     ttyfd;
     thread_id       fid,
                     did;
     char            tty[40];
};

A pair of devices are employed in a pty connection: master and slave. If the master is /dev/pt/p0, then the slave will be /dev/tt/p0. The shell will inherit file descriptors to the slave, while "script" directs through the master side. Finding an available pair uses the traditional (ok, baroque) method: try to open each master device until one succeeds. That master device is now yours exclusively. Here is the code:

bool PTY::ptyinit( )
{
   DIR *dd = opendir( "/dev/pt");
   while (dirent *d = readdir( dd))
      if (d->d_name[0] != '.') {
         sprintf( tty, "/dev/pt/%s", d->d_name);
         ptyfd = open( tty, O_RDWR);
         if (ptyfd > 0) {
             sprintf( tty, "/dev/tt/%s", d->d_name);
             ttyfd = open( tty, O_RDWR);
             if (ttyfd > 0) {
                     closedir( dd);
                     return (TRUE);
             }
             close( ptyfd);
         }
       }
   closedir( dd);
   return (FALSE);
}

The "." and ".." directory entries need to be skipped.

script must maintain two data paths. The first comes from the stdin of script, goes through the pty driver from master side to slave side, and finally to the shell's stdin. The second path originates from the shell's stdout, goes through the pty driver from slave side to master side, and finally to the stdout of script. It is that stdout which is cloned off to the log file, typescript. Each data path has a dedicated BeOS thread, using the following code:

int32 PTY::feeder( PTY *pty)
{
    uchar   data[1000];
    int     i;

    while ((i = pty->GetData( data, sizeof data)) > 0)
            write( pty->ptyfd, data, i);
    pty->Done( );
}

int32 PTY::drainer( PTY *pty)
{
    uchar   data[1000];
    int     i;

    while ((i = read( pty->ptyfd, data, sizeof data)) > 0)
            pty->PutData( data, i);
    pty->Done( );
}

The read and write system calls typically block until data is available, which is why we need the dedicated threads. This also ensures the desired data flow control. In the idle state of script, the feeder thread is blocked in a read of stdin, while the drainer thread is blocked in a read of the master side pty. Meanwhile, the team's main thread can service BApplication.

The constructor/destructor code saves and restores the tty mode of script stdio. The destructor must kill the feeder and drainer threads, since they are most likely blocked where polite methods, like semaphores, cannot help.

PTY::PTY( )
{
    fid = did = -1;
    tcgetattr( 0, &tsaved);
}

PTY::~PTY( )
{
    tcsetattr( 0, TCSANOW, &tsaved);
    if (did > 0)
        kill_thread( did);
    if (fid > 0)
        kill_thread( fid);
}

Take a deep breath! This code exercises both BeOS and Posix functions, and is where the bureaucratic details are hiding. Our pty connection consists of slave side file descriptor "ttyfd" and master side "ptyfd". The slave side tty mode is set to something human friendly. Between the fork() and the execv(), we have a chance to customize the execution environment of the subshell. This includes its stdin, stdout, stderr, name of controlling tty device, and its own process group for signals. The subshell will have no knowledge of "ptyfd", or the execution environment of "script." If the subshell exits, "script" will get master side i/o errors; if script exits, the entire subshell session will get a hangup signal (SIGHUP).

bool PTY::Init( char *com[])
{
   if ( ! ptyinit( )) {
       fprintf( stderr, "no available pty\n");
       return (FALSE);
   }
   struct termios t;
   struct winsize w;
   memset( &t, 0, sizeof(t));
   t.c_iflag = ICRNL;
   t.c_oflag = OPOST | ONLCR;
   t.c_cflag = B19200 | CS8 | CREAD | HUPCL;
   t.c_lflag = ISIG | ICANON | ECHO | ECHOE | ECHONL;
   t.c_cc[VINTR] = ctrl( 'C');
   t.c_cc[VQUIT] = ctrl( '\\');
   t.c_cc[VERASE] = ctrl( 'H');
   t.c_cc[VKILL] = ctrl( 'U');
   t.c_cc[VEOF] = ctrl( 'D');
   tcsetattr( ptyfd, TCSANOW, &t);
   if (ioctl( 0, TIOCGWINSZ, &w) == 0)
       ioctl( ptyfd, TIOCSWINSZ, &w);

   switch (pid_t pid = fork( )) {
   case -1:
       fprintf( stderr, "system too busy\n");
       return (FALSE);
   case 0:
       char te[30];
       pid = getpid( );
       setpgid( pid, pid);
       ioctl( ttyfd, 'pgid', pid);
       signal( SIGHUP, SIG_DFL);
       sprintf( te, "TTY=%s", tty);
       putenv( te);
       close( 0);
       close( 1);
       close( 2);
       dup( ttyfd);
       dup( ttyfd);
       dup( ttyfd);
       close( ptyfd);
       close( ttyfd);
       execv( com[0], com);
       fprintf( stderr, "cannot exec %s\n", com[0]);
        exit( 0);
   }
   close( ttyfd);

   t = tsaved;
   t.c_iflag &= ~ ICRNL;
   t.c_oflag &= ~ ONLCR;
   t.c_lflag &= ~ (ISIG|ICANON|ECHO|ECHOE|ECHONL);
   t.c_cc[VMIN] = 1;
   t.c_cc[VTIME] = 0;
   tcsetattr( 0, TCSANOW, &t);

   fid = spawn_thread(feeder, "f", B_NORMAL_PRIORITY,
                      this);
   did = spawn_thread(drainer, "d", B_NORMAL_PRIORITY,
                      this);
   if (fid < 0 || did < 0) {
       fprintf( stderr, "cannot spawn a thread\n");
       return (FALSE);
   }
   resume_thread( fid);
   resume_thread( did);
   return (TRUE);
}

With the subshell launched, script must complete its own initialization. Its own tty mode is set to "no echo" and "raw" (no interpretation). This gives complete control of tty services to the remote shell and its minions ("stty," text editors, etc). Finally, the feeder and drainer threads are started.

That concludes the PTY class. With so much work already done, the "script" app is almost a footnote. The boffo Script class, below, is compactly defined with multiple inheritance.

struct Script: BApplication, PTY
{
    Script(char *sig, char *c[], char *log): BApplication(sig)
    {
        com = c;
        logfd = creat( log, 0666);
        Run( );
    }

    void ReadyToRun()
    {
        if (logfd < 0)
            fprintf( stderr, "cannot create logfile\n");
        else if (!Init(com))
            Quit();
    }

    void Done()
    {
        mLock();
        Quit();
        Unlock( );
    }

    int GetData(uchar data[], uint n)
    {
        return (read(0, data, n));
    }

    int PutData(uchar data[], uint n)
    {
        write( logfd, data, n);
        return (write( 1, data, n));
    }

    char **com;
    int logfd;
};

main()
{
    static char *com[] = { "/bin/sh", 0 };
    Script s( "application/script", com, "typescript");

    return (0);
}

The GetData() hook is called by PTY to get more data for the slave side. The PutData() hook is called when data from the slave side has arrived. The Done() hook is called when PTY has detected that the subshell has exited. The Be app can initiate a shutdown at any time by inducing a PTY destructor call.

To compile script, clip out the code to script.cpp, and type

gcc script.cpp -lbe

$ script
sh-2.02# date
Fri Apr 16 02:01:26 CDT 1999
sh-2.02# exit
$ cat typescript
sh-2.02# date
Fri Apr 16 02:01:26 CDT 1999
sh-2.02# exit
$

Terminal script

(sleep 1; echo bc; echo 1; echo '2^99999/2^99998'; sleep 60)
| script

The content of "typescript" is a chronological record of all output, both from programs and your own echoed input. It will likely contain ASCII Return (octal 015), Bell (007), Backspace (010), Tab (011), and any ANSI escape sequences. All these effects are faithfully reproduced with

cat typescript

You can see the uninterpreted stream by using a text editor or with

od -c typescript

"typescript" is quite different from Terminal copy-n-paste, where you are selecting inert glyphs—different tools for different purposes.

The BNetEndpoint class abstracts network communication endpoints—think of it as a "socket object." BNetEndpoint takes care of all the necessary initialization in its constructor; it makes creating network connections very simple:

int32 send_data(const char *host, short port,
const void*data, int32 datalen)
{
    BNetEndpoint comm(SOCK_STREAM);
    int32 rc = -1;


    if(comm.InitCheck() == B_NO_ERROR)
    {
        if(comm.Connect(host, port) == B_NO_ERROR)
        {
            rc = comm.Send(data, datalen);
        }
    }
    return rc;
}

The above code creates a TCP connection to the specified hostname and port, sends the data passed in, and automatically closes the connection, returning the amount of data sent, or -1 on failure. As you can see, much of the setup and housekeeping typically required when doing network programming is taken care of by the BNetEndpoint object.

Many BNetEndpoint member functions map orthogonally to the BSD sockets API; it's also possible to get the socket descriptor out of a BNetEndpoint for use with the standard sockets API. See NetEndpoint.h for details.

Just as you can think of BNetEndpoint as a class that encapsulates the BSD sockets API, BNetAddress is a class that encapsulates the functionality found in netdb.h. BNetAddress is a convenient way to store, resolve, and manipulate network addresses.

BNetAddress is used to represent network addresses, and provide useful access to a network address in a variety of formats. BNetAddress provides various ways to get and set a network address, converting to or from the chosen representation into a generic internal one.

BNetAddress::SetTo() is used to set the object to refer to the address passed in, which can be specified in a variety of formats (omitting InitCheck()ing):

void addrs()
{
    BNetAddress addr;
    struct sockaddr_in sa;
    in_addr ia;

    addr.SetTo("www.be.com", 80);
    addr.SetTo("www.be.com", "tcp", "http");

    // www.be.com == 207.126.103.9
    ia.s_addr = inet_addr("207.126.103.9");
    addr.SetTo(ia, 80);

    sa.sin_family = AF_INET;
    sa.sin_port = htons(80);
    sa.sin_addr = inet_addr("207.126.103.9");
    addr.SetTo(sa);
}

All calls to addr.SetTo in the above example are equivalent.

Similarly, BNetAddress::GetAddr() returns the address referred to by the BNetAddress object in a variety of formats. For example, the following code converts sockaddr_in structures into human-readable hostnames:

void sin_convert(const struct sockaddr_in &sa)
{
    BNetAddress addr(sa);
    char host[256];
    unsigned short port;

    addr.GetAddr(host, port);

    cout << "Host: " << host << "Port: " << port << endl;
}

Likewise, to resolve a host name into a sockaddr_in:

struct sockaddr_in resolve(const char *host)
{
    BNetAddress addr(host);
    struct sockaddr_in sa;

    addr.GetAddr(sa);

    return sa;
}

As you can see from these examples, BNetAddress has a number of constructors that mirror its SetTo() member functions. BNetAddress also takes care of any byte order conversion that's necessary with network addresses.

BNetEndpoint is designed to work closely with BNetAddress; any addresses it expects can be represented by a BNetAddress, such as in BNetEndpoint::SendTo().

Unlike BNetAddress and BNetEndpoint, BNetBuffer has no analog in the BSD sockets API. BNetBuffer is a convenient way to manage network data that is to be sent across the wire, including mundane tasks such as byte order conversion. BNetBuffer is a network data container class. As I mention in NetBuffer.h: BNetBuffer is a dynamic buffer useful for storing data to be sent across the network. Data is inserted into and removed from the object using one of the many Append() and Remove() member functions. Access to the raw stored data is possible. The BNetEndpoint class has a Send() and Receive() function for use with BNetBuffer. Network byte order conversion is done automatically for all appropriate integral types in the Append() and Remove() functions for that type.

BNetBuffer is best illustrated by an example. Suppose you have a transaction protocol between a network client and a server application which specifies that whenever the client receives a BMessage, it forwards it to the server over the network connection, along with a client timestamp and a transaction ID, which is a monotonically increasing uint32. It could be coded thusly:

static uint32 gTransID = 0;

[...]

int32 forwardBMessageToServer(const BMessage &msg,
BNetEndpoint &serverConn)
{
    BNetBuffer packet, sizepack;
    bigtime_t timestamp;
    uint32 trans_id, size;

    timestamp = system_time();
    trans_id = atomic_add(&gTransID, 1);

    packet.AppendUInt32(trans_id);
    packet.AppendUInt64(timestamp);
    packet.AppendMessage(msg);

    size = packet.Size();
    sizepack.AppendUInt32(size);

    serverConn.Send(sizepack);
    return serverConn.Send(packet);
}

Voila! Networked BMessages. BNetBuffer does all the necessary byte order conversion, so the server simply needs to call the matching Remove() member functions to get at the data the client was sending.

Astute readers of the header files will have noticed by now that the C++ Networking API classes are all derived from BArchivable. In the case of BNetAddress and BNetBuffer, the archived data is just what you would expect; a byte-gender-neutral archive of the address info or network data, respectively.

For BNetEndpoint, it goes one step further—network connections are archived. For example, if you're connected to a host and port when you archive the BNetEndpoint object, later instantiation of that archive returns a BNetEndpoint that is connected to the same host and port.

There's also a class called BNetDebug, which provides (surprise!) some debugging functionality. Calling BNetDebug::Enable(true) turns Net API debugging on; you can then call BNetDebug::Dump() with buffers of data for a nice hd-like output when you run your program from the Terminal. Many BNetEndpoint calls generate debugging output when debugging is enabled; play around and you'll see what I mean. The debug messages are printed to stderr.

This overview should be enough to get you started with the new C++ networking API. But what would a newsletter article be without some sample code for you to play with? You can find the source code for a simple FTP client I wrote using the new networking API at: ftp://ftp.be.com/pub/samples/network kit/FtpClient.zip