Sometimes you do not know whether a file descriptor corresponds to a tty. This is most commonly the case for the standard output file descriptor. Programs that output text to standard output often format differently when they are writing to a pipe than when they are displaying information for human consumption. For example, when you use ls to list files, it will print multiple columns when you simply run it (most convenient for a human to read), but when you pipe it to another program, it will print one file per line (most convenient for a program to read). Run ls and ls | cat and see the difference.

You can determine whether a file descriptor corresponds to a tty by using the isatty() function, which takes a file descriptor as its argument and returns 1 if the descriptor corresponds to a tty, and 0 otherwise.

#include <unistd.h>

int isatty(int fd);

The ttyname() function provides a canonical name for the terminal (if any) associated with a file descriptor. It takes as its argument any file descriptor, and returns a pointer to a character string.

#include <unistd.h>

char *ttyname(int fd);

Because that character string is (the standard says “may be", but we all know better) in static space, you need to make a copy of the returned string before calling ttyname() again; it is not re-entrant. ttyname() returns NULL on any error, including if it is passed a file descriptor that is not associated with a tty.

Every session (see Chapter 10) is tied to a terminal from which processes in the session get their input and to which they send their output. That terminal may be the machine’s local console, a terminal connected over a serial line, or a pseudo terminal that maps to an X window or across a network (see page 389 later in this chapter for more on pseudo terminals). The terminal to which a session is related is called the controlling terminal (or controlling tty) of the session. A terminal can be the controlling terminal for only one session at a time.

Normal processes cannot change their controlling terminal; only a session leader can do that. Under Linux, a change in the session leader’s controlling terminal is not propagated to other processes in that session. Session leaders almost always set a controlling terminal when they initially start running, before they create any child processes, in order to ensure that all the processes in the session share a common controlling terminal.

There are two interfaces for changing a session group leader’s controlling tty. The first is through the normal open() and close() system calls:

The other method involves ioctl()s on separate file descriptors that reference the old and the new terminal devices:

A terminal that is being used by a session keeps track of which process group is considered the foreground process group. Processes in that process group are allowed to read from and write to the terminal, whereas processes in other process groups are not (see Chapter 15 for details on what happens when background processes try to read and write from the controlling terminal). The tcsetpgrp() function allows a process running on a terminal to change the foreground process group for that terminal.^[2]

int tcsetpgrp(int ttyfd, pid_t pgrp);

The first parameter specifies the tty whose controlling process group is being changed, and pgrp is the process group that should be moved to the foreground. Processes may change the foreground process group only for their controlling terminal. If the process making the change is not in the foreground process group on that terminal, a SIGTTOU is generated, unless that signal is being ignored or is blocked.^[3]

There are two system databases used to keep track of logged-in users; utmp is used specifically for currently logged-in users, and wtmp is a record of all previous logins since the file was created. The who command uses the utmp database to print out its list of logged-in users, and the last command uses the wtmp database to print out its list of users who have logged into the system since the wtmp database was regenerated. On Linux systems, the utmp database is stored in the file /var/run/utmp, and the wtmp database is stored in the file /var/log/wtmp.

Programs that use ttys for user login sessions (whether or not they are associated with a graphical login) should update the two system databases, unless the user explicitly requests otherwise; for example, some users do not want every shell session they are running in a terminal emulator under the X Window System to be listed as a login process. Only add interactive sessions, because utmp and wtmp are not meant for logging automated programs. Any tty that is not a controlling terminal should normally not be added to the utmp and wtmp databases.

Applications that use ptys and that are written with security in mind rarely have sufficient permissions to modify the database files. These applications should provide the option to use a simple helper program that is available on most Linux systems and some other systems, but is not standardized: the utempter utility. The utempter utility is setgid (or setuid if necessary) with sufficient permissions to modify the utmp and wtmp databases, and it is accessed through a simple library. The utempter utility checks to make sure that the process owns the tty that it is trying to log into the utmp database before allowing the operation. utempter is meant to be used only for ptys; other ttys are generally opened by daemons with sufficient permissions to modify the system database files.

#include <utempter.h>

void addToUtmp(const char *pty, const char *hostname, int ptyfd);
void removeLineFromUtmp(const char *pty, int ptyfd);
void removeFromUtmp(void);

The addToUtmp() function takes three arguments. The first, pty, is the full path to the pty being added. The second, hostname, may be NULL; if not, it is the network name of the system from which a network connection using this pty originated (this sets ut_host, as documented on page 343). The third, ptyfd, must be an open file descriptor referencing the pty device named in the pty argument.

The removeLineFromUtmp() function takes two arguments; they are defined exactly like the arguments of the same name passed to the addToUtmp() function.

Some existing applications are written with a structure that makes it difficult to keep the name and file descriptor around to clean up the utmp entry. Because of this, the utempter library keeps a cache of the more recent device name and file descriptor passed to addToUtmp() and a convenience function removeFromUtmp() that takes no arguments and acts like removeLineFromUtmp() on the information it has cached. This works only for applications that add only one utmp entry; more complex applications that use more than one pty must use removeLineFromUtmp() instead.

The area of utmp and wtmp handling is one of those inconsistent areas where mechanisms have differed between systems and changed over the years; even the definition of what information is available in utmp and wtmp still differs between systems. Originally, utmp and wtmp were essentially just arrays of structures written to disk; over time, APIs were created to handle the records reliably.

At least two such interfaces have been officially standardized; the original utmp interface (specified in XSI, XPG2, and SVID2) and the extended utmpx interface (specified in XPG4.2 and in recent editions of POSIX). Conveniently, both interfaces (utmp and utmpx) are available on Linux. The utmp interface, which varies widely between machines, has a set of defines to make it possible to write portable code that take advantage of the extensions that glibc provides. The utmpx interface, which is more strictly standardized, does not (currently) provide those defines but still provides the extensions.

The Linux utmp interface was originally constructed as a superset of other existing utmp interfaces, and utmpx was standardized as a superset of other existing utmp interfaces; happily, the two supersets are essentially the same, so on Linux, the difference between the utmp and utmpx data structures is the letter x.

If you do not wish to use any extensions, we recommend that you use the utmpx interface, because as long as you are using no extensions, it is the most portable; it is strictly standardized.

If you do wish to use extensions, however, we recommend that you use the utmp interface, because glibc provides defines that let you write portable code that takes advantage of the extensions.

There is also a hybrid approach—include both header files and use the defines that glibc provides for the utmp interface to decide whether to use extensions in the utmpx interface. We recommend against this because there is no guarantee that the utmp.h and utmpx.h header files will not conflict on non-Linux systems. If you want both maximum portability and maximum functionality, this is one of those areas where you may have to write some code twice—one version using utmpx for easy portability to new systems, and then one version with #ifdefs for maximum functionality on each new system you port to.

We document here only the most commonly used extensions; the glibc documentation covers all the extensions that it supports. The utmp functions operate in terms of struct utmp; we ignore some of the extensions. The utmpx structure and functions operate exactly the same as the utmp structure and functions, and so we do not document them separately. Note that the same structure is used for both utmp and wtmp, because the two databases are so similar.

struct utmp {
    short int ut_type;          /* type of login */
    pid_t ut_pid;               /* process id of login process */
    char ut_line[UT_LINESIZE];  /* 32 characters */
    char ut_id[4];              /* inittab id */
    char ut_user[UT_NAMESIZE];  /* 32 characters */
    char ut_host[UT_HOSTSIZE];  /* 256 characters */
    struct timeval ut_tv;
    struct exit_status ut_exit; /* status of dead processes */
    long ut_session;
    int32_t ut_addr_v6[4];
};

Many of the same members are part of struct utmpx by the same name. The members that are not required to be members of struct utmpx are annotated as “not standardized by POSIX” (none of them are standardized as part of struct utmp since struct utmp is itself not standardized).

The character array members are not necessarily NULL-terminated strings. Use sizeof() or other size limitations judiciously.

The ut_type member defines how all the rest of the members are defined. Some ut_type values are reserved for recording system information; these are useful only for specialized system programs. We do not document these fully.

The interfaces defined by XPG2, SVID 2, and FSSTND 1.2 are:

#include <utmp.h>

int utmpname(char *file);
struct utmp *getutent(void);
struct utmp *getutid(const struct utmp *id);
struct utmp *getutline(const struct utmp *line);
struct utmp *pututline(const struct utmp *ut);
void setutent(void);
void endutent(void);
void updwtmp(const char *file, const struct utmp *ut);
void logwtmp(const char *line, const char *name, const char *host);

Each record in a utmp or wtmp database is called a line. All the functions that return a pointer to a struct utmp return a pointer to static data on success, and a NULL pointer on failure. Note that the static data is overwritten by every new call to any function that returns a struct utmp. Also, the POSIX standard (for utmpx) requires that the static data be cleared by the application before some searches.

The utmpx versions of these functions take struct utmpx instead of struct utmp, require including utmpx.h, and are named getutxent, getutxid, getutxline, pututxline, setutxent, and endutxent, but are otherwise identical to the utmp versions of these functions on Linux. There is no utmpxname() function defined by POSIX, although some platforms may choose to define it anyway (as does glibc).

The utmpname() function is used to determine which database you are looking at. The default database is the utmp database, but you can use this function to point to wtmp instead. Two predefined names are _PATH_UTMP for the utmp file and _PATH_WTMP for the wtmp file; for testing you might choose instead to point to a local copy. The utmpname() function returns zero on success, nonzero on failure, but success may simply mean that it was able to copy a filename into the library; it does not mean that a database actually exists at the path you have provided to it!

The getutent() function simply returns the next line from the database. If the database has not been opened yet, it returns the contents of the first line. If no more lines are available, it returns NULL.

The getutid() function takes a struct utmp and looks only at one or two members. If the ut_type is BOOT_TIME, OLD_TIME, or NEW_TIME, then it returns the next line of that type. If the ut_type is any of INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, then getutid() returns the next line matching any of those types that also has a ut_id value matching the ut_id value in the struct utmp passed to getutid(). You must clear the data in the struct utmp returned by getutid() before calling it again; otherwise, it is allowed by POSIX to return the same line as the previous invocation. If no matching lines are available, it returns NULL.

The getutline() function returns the next line with ut_id set to LOGIN_PROCESS or USER_PROCESS that also has a ut_line value matching the ut_line value in the struct utmp passed to getutline(). Like getutid(), you must clear the data in the struct utmp returned by getutline() before calling it again; otherwise, it is allowed by POSIX to return the same line as the previous invocation. If no matching lines are available, it returns NULL.

The pututline() function modifies (or adds, if necessary) the database record matching the ut_line member of its struct utmp argument. It does this only if the process has sufficient permissions to modify the database. If it succeeds in modifying the database, it returns a struct utmp that matches the data it wrote to the database. Otherwise, it returns NULL. The pututline() function is not portably applicable to the wtmp database. To modify the wtmp database, use updwtmp() or logwtmp() instead.

The setutent() function rewinds the database to the beginning.

The endutent() function closes the database. This closes the file descriptor and frees any associated data. Call endutent() before using utmpname() to access a different utmp file, as well as after you are done accessing utmp data.

BSD defined two functions that are also available as part of glibc, which are the most robust way to modify the wtmp database.

The updwtmp() function takes the filename of the wtmp database (normally _PATH_WTMP) and a filled-in struct utmp, and attempts to append the entry to the wtmp file. Failure is not reported.

The logwtmp() function is a convenience function that fills in a struct utmp and calls updwtmp() with it. The line argument is copied to ut_line, name is copied to ut_user, host is copied to ut_host, ut_tv is filled in from the current time, and ut_pid is filled in from the current process id. Like updwtmp(), it does not report failure.

The utmp program demonstrates several methods of reading utmp and wtmp databases:

  1: /* utmp.c */
  2:
  3: #include <stdio.h>
  4: #include <unistd.h>
  5: #include <string.h>
  6: #include <time.h>
  7: #include <sys/time.h>
  8: #include <sys/types.h>
  9: #include <sys/socket.h>
 10: #include <netinet/in.h>
 11: #include <arpa/inet.h>
 12: #include <utmp.h>
 13: #include <popt.h>
 14:
 15: void print_utmp_entry(struct utmp *u) {
 16:     struct tm *tp;
 17:     char *type;
 18:     char addrtext[INET6_ADDRSTRLEN];
 19:
 20:     switch (u->ut_type) {
 21:         case EMPTY: type = "EMPTY"; break;
 22:         case RUN_LVL: type = "RUN_LVL"; break;
 23:         case BOOT_TIME: type = "BOOT_TIME"; break;
 24:         case NEW_TIME: type = "NEW_TIME"; break;
 25:         case OLD_TIME: type = "OLD_TIME"; break;
 26:         case INIT_PROCESS: type = "INIT_PROCESS"; break;
 27:         case LOGIN_PROCESS: type = "LOGIN_PROCESS"; break;
 28:         case USER_PROCESS: type = "USER_PROCESS"; break;
 29:         case DEAD_PROCESS: type = "DEAD_PROCESS"; break;
 30:         case ACCOUNTING: type = "ACCOUNTING"; break;
 31:     }
 32:     printf("%-13s:", type);
 33:     switch (u->ut_type) {
 34:         case LOGIN_PROCESS:
 35:         case USER_PROCESS:
 36:         case DEAD_PROCESS:
 37:             printf(" line: %s", u->ut_line);
 38:             /* fall through */
 39:         case INIT_PROCESS:
 40:             printf("
 pid: %6d id: %4.4s", u->ut_pid, u->ut_id);
 41:     }
 42:     printf("
");
 43:     tp = gmtime(&u->ut_tv.tv_sec);
 44:     printf("  time: %24.24s.%lu
", asctime(tp), u->ut_tv.tv_usec);
 45:     switch (u->ut_type) {
 46:         case USER_PROCESS:
 47:         case LOGIN_PROCESS:
 48:         case RUN_LVL:
 49:         case BOOT_TIME:
 50:             printf("  user: %s
", u->ut_user);
 51:     }
 52:     if (u->ut_type == USER_PROCESS) {
 53:         if (u->ut_session)
 54:             printf("  sess: %lu
", u->ut_session);
 55:         if (u->ut_host)
 56:             printf("  host: %s
", u->ut_host);
 57:         if (u->ut_addr_v6[0]) {
 58:             if (!(u->ut_addr_v6[1] |
 59:                   u->ut_addr_v6[2] |
 60:                   u->ut_addr_v6[3])) {
 61:                /* only first quad filled in implies IPV4 address */
 62:                 inet_ntop(AF_INET, u->ut_addr_v6,
 63:                           addrtext, sizeof(addrtext));
 64:                 printf("  IPV4: %s
", addrtext);
 65:             } else {
 66:                 inet_ntop(AF_INET6, u->ut_addr_v6,
 67:                           addrtext, sizeof(addrtext));
 68:                 printf("  IPV6: %s
", addrtext);
 69:             }
 70:         }
 71:     }
 72:     if (u->ut_type == DEAD_PROCESS) {
 73:            printf("  exit: %u:%u
",
 74:                   u->ut_exit.e_termination,
 75:                   u->ut_exit.e_exit);
 76:     }
 77:     printf("
");
 78: }
 79:
 80: struct utmp * get_next_line(char *id, char *line) {
 81:     struct utmp request;
 82:
 83:     if (!id && !line)
 84:         return getutent();
 85:
 86:     memset(&request, 0, sizeof(request));
 87:
 88:     if (line) {
 89:         strncpy(&request.ut_line[0], line, UT_LINESIZE);
 90:         return getutline(&request);
 91:     }
 92:
 93:     request.ut_type = INIT_PROCESS;
 94:     strncpy(&request.ut_id[0], id, 4);
 95:     return getutid(&request);
 96: }
 97:
 98: void print_file(char * name, char *id, char *line) {
 99:     struct utmp *u;
100:
101:     if (utmpname(name)) {
102:         fprintf(stderr, "utmp database %s open failed
", name);
103:         return;
104:     }
105:     setutent();
106:     printf("%s:
====================
", name);
107:     while ((u=get_next_line(id, line))) {
108:         print_utmp_entry(u);
109:         /* POSIX requires us to clear the static data before
110:          * calling getutline or getutid again
111:          */
112:         memset(u, 0, sizeof(struct utmp));
113:     }
114:     endutent();
115: }
116:
117: int main(int argc, const char **argv) {
118:     char *id = NULL, *line = NULL;
119:     int show_utmp = 1, show_wtmp = 0;
120:     int c;
121:     poptContext optCon;
122:     struct poptOption optionsTable[] = {
123:         { "utmp", 'u', POPT_ARG_NONE|POPT_ARGFLAG_XOR,
124:            &show_utmp, 0,
125:           "toggle showing contents of utmp file", NULL },
126:         { "wtmp", 'w', POPT_ARG_NONE|POPT_ARGFLAG_XOR,
127:           &show_wtmp, 0,
128:           "toggle showing contents of wtmp file", NULL },
129:         { "id", 'i', POPT_ARG_STRING, &id, 0,
130:           "show process entries for specified inittab id",
131:           "<inittab id>" },
132:         { "line", 'l', POPT_ARG_STRING, &line, 0,
133:           "show process entries for specified device line",
134:           "<line>" },
135:         POPT_AUTOHELP
136:         POPT_TABLEEND
137:     };
138:
139:     optCon = poptGetContext("utmp", argc, argv, optionsTable, 0);
140:     if ((c = poptGetNextOpt(optCon)) < -1) {
141:         fprintf(stderr, "%s: %s
",
142:             poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
143:             poptStrerror(c));
144:         return 1;
145:     }
146:     poptFreeContext(optCon);
147:
148:     if (id && line)
149:         fprintf(stderr, "Cannot choose both by id and line, "
150:                         "choosing by line
");
151:
152:     if (show_utmp)
153:         print_file(_PATH_UTMP, id, line);
154:     if (show_utmp && show_wtmp)
155:         printf("


");
156:     if (show_wtmp)
157:         print_file(_PATH_WTMP, id, line);
158:
159:     return 0;
160: }

One common reason to modify termios settings is to read a password without echoing characters. To do this, you want to turn off local echo while reading the password. Your code should look like this:

struct termios ts, ots;

One structure keeps the original termios settings so that you can restore them, and the other one is a copy to modify.

tcgetattr(STDIN_FILENO, &ts);

Generally, you read passwords from standard input.

ots = ts;

Keep a copy of the original termios settings to restore later.

ts.c_lflag &= ~ECHO;
ts.c_lflag |= ECHONL;
tcsetattr(STDIN_FILENO, TCSAFLUSH, &ts);

Turn off echoing characters except newlines, after all currently pending output is completed. (The first l in c_lflag stands for local processing.)

read_password();

Here, you read the password. This may be as simple as a single fgets() or read() call, or it may include more complex processing, depending on whether the tty is in raw mode or cooked mode, and depending on the requirements of your program.

tcsetattr(STDIN_FILENO, TCSANOW, &ots);

This restores the original termios settings and does so immediately. (We explain other options later, in the reference section on page 371.)

A full example program, readpass, looks like this:

 1: /* readpass.c */
 2:
 3: #include <stdio.h>
 4: #include <stdlib.h>
 5: #include <termios.h>
 6: #include <unistd.h>
 7:
 8: int main(void) {
 9:     struct termios ts, ots;
10:     char passbuf[1024];
11:
12:     /* get and save current termios settings */
13:     tcgetattr(STDIN_FILENO, &ts);
14:     ots = ts;
15:
16:     /* change and set new termios settings */
17:     ts.c_lflag &= ~ECHO;
18:     ts.c_lflag |= ECHONL;
19:     tcsetattr(STDIN_FILENO, TCSAFLUSH, &ts);
20:
21:     /* paranoia: check that the settings took effect */
22:     tcgetattr(STDIN_FILENO, &ts);
23:     if (ts.c_lflag & ECHO) {
24:         fprintf(stderr, "Failed to turn off echo
");
25:         tcsetattr(STDIN_FILENO, TCSANOW, &ots);
26:         exit(1);
27:     }
28:
29:     /* get and print the password */
30:     printf("enter password: ");
31:     fflush(stdout);
32:     fgets(passbuf, 1024, stdin);
33:     printf("read password: %s", passbuf);
34:     /* there was a terminating 
 in passbuf */
35:
36:     /* restore old termios settings */
37:     tcsetattr(STDIN_FILENO, TCSANOW, &ots);
38:
39:     exit(0);
40: }

As an example of programming both ends of a tty, here is a program that connects the current terminal to a serial port. On one tty, the program, called robin, is talking to you as you type. On another tty, it is communicating with the serial port. In order to multiplex input to and output from the local tty and the serial port, the program uses the poll() system call described on page 245.

Here is robin.c in its entirety, followed by an explanation:

  1: /* robin.c */
  2:
  3: #include <sys/poll.h>
  4: #include <errno.h>
  5: #include <fcntl.h>
  6: #include <popt.h>
  7: #include <stdio.h>
  8: #include <stdlib.h>
  9: #include <signal.h>
 10: #include <string.h>             /* for strerror() */
 11: #include <termios.h>
 12: #include <unistd.h>
 13:
 14: void die(int exitcode, const char *error, const char *addl) {
 15:     if (error) fprintf(stderr, "%s: %s
", error, addl);
 16:     exit(exitcode);
 17: }
 18:
 19: speed_t symbolic_speed(int speednum) {
 20:     if (speednum >= 460800) return B460800;
 21:     if (speednum >= 230400) return B230400;
 22:     if (speednum >= 115200) return B115200;
 23:     if (speednum >= 57600) return B57600;
 24:     if (speednum >= 38400) return B38400;
 25:     if (speednum >= 19200) return B19200;
 26:     if (speednum >= 9600) return B9600;
 27:     if (speednum >= 4800) return B4800;
 28:     if (speednum >= 2400) return B2400;
 29:     if (speednum >= 1800) return B1800;
 30:     if (speednum >= 1200) return B1200;
 31:     if (speednum >= 600) return B600;
 32:     if (speednum >= 300) return B300;
 33:     if (speednum >= 200) return B200;
 34:     if (speednum >= 150) return B150;
 35:     if (speednum >= 134) return B134;
 36:     if (speednum >= 110) return B110;
 37:     if (speednum >= 75) return B75;
 38:     return B50;
 39: }
 40:
 41: /* These need to have file scope so that we can use them in
 42:  * signal handlers */
 43: /* old port termios settings to restore */
 44: static struct termios pots;
 45: /* old stdout/in termios settings to restore */
 46: static struct termios sots;
 47: /* port file descriptor */
 48: int    pf;
 49:
 50: /* restore original terminal settings on exit */
 51: void cleanup_termios(int signal) {
 52:     tcsetattr(pf, TCSANOW, &pots);
 53:     tcsetattr(STDIN_FILENO, TCSANOW, &sots);
 54:     exit(0);
 55: }
 56:
 57: /* handle a single escape character */
 58: void send_escape(int fd, char c) {
 59:     switch (c) {
 60:     case 'q':
 61:         /* restore termios settings and exit */
 62:         cleanup_termios(0);
 63:         break;
 64:     case 'b':
 65:         /* send a break */
 66:         tcsendbreak(fd, 0);
 67:         break;
 68:     default:
 69:         /* pass the character through */
 70:         /* "C- C-" sends "C-" */
 71:         write(fd, &c, 1);
 72:         break;
 73:     }
 74:     return;
 75: }
 76:
 77: /* handle escape characters, writing to output */
 78: void cook_buf(int fd, char *buf, int num) {
 79:     int current = 0;
 80:     static int in_escape = 0;
 81:
 82:     if (in_escape) {
 83:         /* cook_buf last called with an incomplete escape
 84:            sequence */
 85:         send_escape(fd, buf[0]);
 86:         num--;
 87:         buf++;
 88:         in_escape = 0;
 89:     }
 90:     while (current < num) {
 91: #       define CTRLCHAR(c) ((c)-0x40)
 92:         while ((current < num) && (buf[current] != CTRLCHAR('')))
 93:             current++;
 94:         if (current) write (fd, buf, current);
 95:         if (current < num) {
 96:             /* found an escape character */
 97:             current++;
 98:             if (current >= num) {
 99:                 /* interpret first character of next sequence */
100:                 in_escape = 1;
101:                 return;
102:             }
103:             send_escape(fd, buf[current]);
104:         }
105:         num -= current;
106:         buf += current;
107:         current = 0;
108:     }
109:     return;
110: }
111:
112: int main(int argc, const char *argv[]) {
113:     char    c;            /* used for argument parsing */
114:     struct  termios pts;  /* termios settings on port */
115:     struct  termios sts;  /* termios settings on stdout/in */
116:     const char   *portname;
117:     int     speed = 0;     /* used in argument parsing for speed */
118:     struct  sigaction sact;/* used to initialize signal handler */
119:     struct  pollfd ufds[2]; /* communicate with poll() */
120:     int     raw = 0;      /* raw mode? */
121:     int     flow = 0;     /* type of flow control, if any */
122:     int     crnl = 0;     /* send carriage return with newline? */
123:     int     i = 0;        /* used in the multiplex loop */
124:     int     done = 0;
125: #   define BUFSIZE 1024
126:     char    buf[BUFSIZE];
127:     poptContext optCon;   /* context for command-line options */
128:     struct poptOption optionsTable[] = {
129:              { "bps", 'b', POPT_ARG_INT, &speed, 0,
130:                "signaling rate for current maching in bps",
131:                "<BPS>" },
132:              { "crnl", 'c', POPT_ARG_VAL, &crnl, 'c',
133:                "send carriage return with each newline", NULL },
134:              { "hwflow", 'h', POPT_ARG_VAL, &flow, 'h',
135:                "use hardware flow control", NULL },
136:              { "swflow", 's', POPT_ARG_VAL, &flow, 's',
137:                "use software flow control", NULL },
138:              { "noflow", 'n', POPT_ARG_VAL, &flow, 'n',
139:                "disable flow control", NULL },
140:              { "raw", 'r', POPT_ARG_VAL, &raw, 1,
141:                "enable raw mode", NULL },
142:              POPT_AUTOHELP
143:              { NULL, '', 0, NULL, '', NULL, NULL }
144:     };
145:
146: #ifdef DSLEEP
147:     /* wait 10 minutes so we can attach a debugger */
148:     sleep(600);
149: #endif
150:
151:     optCon = poptGetContext("robin", argc, argv, optionsTable, 0);
152:     poptSetOtherOptionHelp(optCon, "<port>");
153:
154:     if (argc < 2) {
155:         poptPrintUsage(optCon, stderr, 0);
156:         die(1, "Not enough arguments", "");
157:     }
158:
159:     if ((c = poptGetNextOpt(optCon)) < -1) {
160:         /* an error occurred during option processing */
161:         fprintf(stderr, "%s: %s
",
162:                 poptBadOption(optCon, POPT_BADOPTION_NOALIAS),
163:                 poptStrerror(c));
164:         return 1;
165:     }
166:     portname = poptGetArg(optCon);
167:     if (!portname) {
168:         poptPrintUsage(optCon, stderr, 0);
169:         die(1, "No port name specified", "");
170:     }
171:
172:     pf = open(portname, O_RDWR);
173:     if (pf < 0) {
174:         poptPrintUsage(optCon, stderr, 0);
175:         die(1, strerror(errno), portname);
176:     }
177:     poptFreeContext(optCon);
178:
179:     /* modify the port configuration */
180:     tcgetattr(pf, &pts);
181:     pots = pts;
182:     /* some things we want to set arbitrarily */
183:     pts.c_lflag &= ~ICANON;
184:     pts.c_lflag &= ~(ECHO | ECHOCTL | ECHONL);
185:     pts.c_cflag |= HUPCL;
186:     pts.c_cc[VMIN] = 1;
187:     pts.c_cc[VTIME] = 0;
188:
189:     /* Standard CR/LF handling: this is a dumb terminal.
190:      * Do no translation:
191:      * no NL ->  CR/NL mapping on output, and
192:      * no CR ->  NL mapping on input.
193:      */
194:     pts.c_oflag &= ~ONLCR;
195:     pts.c_iflag &= ~ICRNL;
196:
197:     /* Now deal with the local terminal side */
198:     tcgetattr(STDIN_FILENO, &sts);
199:     sots = sts;
200:     /* again, some arbitrary things */
201:     sts.c_iflag &= ~(BRKINT | ICRNL);
202:     sts.c_iflag |= IGNBRK;
203:     sts.c_lflag &= ~ISIG;
204:     sts.c_cc[VMIN] = 1;
205:     sts.c_cc[VTIME] = 0;
206:     sts.c_lflag &= ~ICANON;
207:     /* no local echo: allow the other end to do the echoing */
208:     sts.c_lflag &= ~(ECHO | ECHOCTL | ECHONL);
209:
210:     /* option handling will now modify pts and sts */
211:     switch (flow) {
212:     case 'h':
213:         /* hardware flow control */
214:         pts.c_cflag |= CRTSCTS;
215:         pts.c_iflag &= ~(IXON | IXOFF | IXANY);
216:         break;
217:     case 's':
218:         /* software flow control */
219:         pts.c_cflag &= ~CRTSCTS;
220:         pts.c_iflag |= IXON | IXOFF | IXANY;
221:         break;
222:     case 'n':
223:         /* no flow control */
224:         pts.c_cflag &= ~CRTSCTS;
225:         pts.c_iflag &= ~(IXON | IXOFF | IXANY);
226:         break;
227:     }
228:     if (crnl) {
229:         /* send CR with NL */
230:         pts.c_oflag |= ONLCR;
231:     }
232:
233:     /* speed is not modified unless -b is specified */
234:     if (speed) {
235:         cfsetospeed(&pts, symbolic_speed(speed));
236:         cfsetispeed(&pts, symbolic_speed(speed));
237:     }
238:
239:     /* set the signal handler to restore the old
240:      * termios handler */
241:     sact.sa_handler = cleanup_termios;
242:     sigaction(SIGHUP, &sact, NULL);
243:     sigaction(SIGINT, &sact, NULL);
244:     sigaction(SIGPIPE, &sact, NULL);
245:     sigaction(SIGTERM, &sact, NULL);
246:
247:     /* Now set the modified termios settings */
248:     tcsetattr(pf, TCSANOW, &pts);
249:     tcsetattr(STDIN_FILENO, TCSANOW, &sts);
250:
251:     ufds[0].fd = STDIN_FILENO;
252:     ufds[0].events = POLLIN;
253:     ufds[1].fd = pf;
254:     ufds[1].events = POLLIN;
255:
256:     do {
257:         int r;
258:
259:         r = poll(ufds, 2, -1);
260:         if ((r < 0) && (errno != EINTR))
261:             die(1, "poll failed unexpectedly", "");
262:
263:         /* First check for an opportunity to exit */
264:         if ((ufds[0].revents | ufds[1].revents) &
265:             (POLLERR | POLLHUP | POLLNVAL)) {
266:             done = 1;
267:             break;
268:         }
269:
270:         if (ufds[1].revents & POLLIN) {
271:             /* pf has characters for us */
272:             i = read(pf, buf, BUFSIZE);
273:             if (i >= 1) {
274:                 write(STDOUT_FILENO, buf, i);
275:             } else {
276:                 done = 1;
277:             }
278:         }
279:         if (ufds[0].revents & POLLIN) {
280:             /* standard input has characters for us */
281:             i = read(STDIN_FILENO, buf, BUFSIZE);
282:             if (i >= 1) {
283:                 if (raw) {
284:                     write(pf, buf, i);
285:                 } else {
286:                     cook_buf(pf, buf, i);
287:                 }
288:             } else {
289:                 done = 1;
290:         }
291:     }
292:     } while (!done);
293:
294:     /* restore original terminal settings and exit */
295:     tcsetattr(pf, TCSANOW, &pots);
296:     tcsetattr(STDIN_FILENO, TCSANOW, &sots);
297:     exit(0);
298: }

robin.c starts out by including a few header files (read the man page for each system call and library function to see which include files you need to include, as usual), then defines a few useful functions.

The symbolic_speed() function at line 19 converts an integer speed into a symbolic speed that termios can handle. Unfortunately, termios is not designed to handle arbitrary speeds, so each speed you wish to use must be part of the user-kernel interface.^[4]

Note that it includes some rather high speeds. Not all serial ports support speeds as high as 230,400 or 460,800 bps; the POSIX standard defines speeds only up to 38,400 bps. To make this program portable, each line above the one that sets the speed to 38,400 bps would have to be expanded to three lines, like this:

#  ifdef B460800
    if (speednum >= 460800) return B460800;
#  endif

That still allows users to specify speeds beyond what the serial ports may be able to handle, but the source code will now compile on any system with POSIX termios. (As discussed on page 352 and page 371, any serial port has the option of refusing to honor any termios setting it is incapable of handling, and that includes speed settings. So just because B460800 is defined does not mean you can set the port speed to 460,800 bits per second.)

Next, on lines 44 through 55, we see a few global variables for communicating some variables to a signal handler, and the signal handler itself. The signal handler is designed to restore termios settings on both tty interfaces when a signal is delivered, so it needs to be able to access the structures containing the old termios settings. It also needs to know the file descriptor of the serial port (the file descriptor for standard input does not change, so it is compiled into the binary). The code is identical to that in the normal exit path, which is described later. The signal handler is later attached to signals that would terminate the process if they were ignored.

The send_escape() and cook_buf() functions are discussed later. They are used as part of the input processing in the I/O loop at the end of the main() function.

The conditionally compiled sleep(600) at the beginning of the main() function is there for debugging. In order to debug programs that modify termios settings for standard input or standard output, it is best to attach to the process from a different window or terminal session. However, that means that you cannot just set a breakpoint on the main function and step into the process one instruction at a time. You have to start the program running, find its pid, and attach to it from within the debugger. This process is described in more detail on page 370.

Therefore, if we are debugging and need to debug code that runs before the program waits for input, we need the program to sleep for a while to give us time to attach. Once we attach, we interrupt the sleep, so there is no harm in using a long sleep time. Compile robin.c with -DDSLEEP in order to activate this feature.

Ignoring debugging, we first parse the options using the popt library described in Chapter 26, and then open the serial port to which we will talk.

Next, we use the tcgetattr() function to get the existing termios configuration of the serial port, then we save a copy in pots so that we can restore it when we are through.

Starting with line 183, we modify settings for the serial port:

183:     pts.c_lflag &= ~ICANON;

This line turns off canonicalization in the serial port driver—that is, puts it in raw mode. In this mode, no characters are special—not newlines, not control characters:

184:     pts.c_lflag &= ~(ECHO | ECHOCTL | ECHONL);

This turns off all local echoing on the serial port:

185:     pts.c_cflag |= HUPCL;

If there is a modem connected, HUPCL arranges for it to be told to hang up when the final program closes the device:

186:     pts.c_cc[VMIN] = 1;
187:     pts.c_cc[VTIME] = 0;

When a tty is in raw mode, these two settings determine the read() system call’s behavior. This particular setting says that when we call read(), we want read() to wait to return until one or more bytes have been read. We never call read() unless we know that there is at least one byte to read, so this is functionally equivalent to a nonblocking read(). The definition of VMIN and VTIME is complex, as we demonstrate on page 387.

The default termios settings include some end-of-line character translation. That is okay for dial-in lines and for terminal sessions, but when we are connecting two ttys, we do not want the translation to happen twice. We do not want to map newline characters to a carriage return/newline pair on output, and we do not want to map a received carriage return to a newline on input, because we are already receiving carriage return/newline pairs from the remote system:

194:     pts.c_oflag &= ~ONLCR;
195:     pts.c_iflag &= ~ICRNL;

Without these two lines, using robin to connect to another Linux or Unix computer would result in the remote system seeing you press Return twice each time you press it once, and each time it tries to display a new line on your screen, you will see two lines. So each time you press Return (assuming you manage to log in with these terminal settings), you will see two prompts echoed back to you, and if you run vi, you will see ~ characters on every other line rather than on every line.

At this point, we have made all the changes to the serial port’s termios settings that we know we need to make before we process the command-line arguments. We now turn to modifying the settings for the tty that gives us standard input and output. Since it is one tty, we need to deal with only one file descriptor of the pair. We have chosen standard input, following the convention set by the stty program. We start out, again, by getting and saving attributes.

Then we modify some flags:

201:     sts.c_iflag &= ~(BRKINT | ICRNL);
202:     sts.c_iflag |= IGNBRK;
203:     sts.c_lflag &= ~ISIG;

Turning off BRKINT makes a difference only if robin is being called from a login session attached to another serial port on which a break can be received. Turning it off means that the tty driver does not send a SIGINT to robin when a break condition occurs on robin’s standard input, since robin does not have anything useful to do when it receives a break. Turning off ICRNL prevents any received carriage-return (' ') characters from being reported to robin as newline (' ')characters. Like turning off BRKINT, this applies only when the login session is attached to another serial port. In addition, it applies only if carriage-return characters are not being ignored (that is, if the IGNCR flag is not set).

The IGNBRK function tells the tty driver to ignore breaks. Turning on IGNBRK is actually redundant here. If IGNBRK is set, then BRKINT is ignored. But it does not hurt to set both.

Those are input processing flags. We also modify a local processing flag: We turn off ISIG. This keeps the tty driver from sending SIGINT, SIGQUIT, and SIGTSTP when the respective character (INTR, QUIT, or SUSP) is received. We do this because we want those characters to be sent to the remote system (or whatever is connected to the serial port) for processing there.

Next comes option handling. In some cases, the default modifications we made to the termios settings might not be sufficient, or they might be too much. In these cases, we provide some command-line options to modify the termios options.

By default, we leave the serial port in whatever flow-control state we find it in. However, at line 212, there are options to do hardware flow control (which uses the CTS and RTS flow-control wires), software flow control (reserving ^S and ^Q for STOP and START, respectively), and explicitly disable flow control entirely:

212:     case 'h':
213:         /* hardware flow control */
214:         pts.c_cflag |= CRTSCTS;
215:         pts.c_iflag &= ~(IXON | IXOFF | IXANY);
216:         break;
217:     case 's':
218:         /* software flow control */
219:         pts.c_cflag &= ~CRTSCTS;
220:         pts.c_iflag |= IXON | IXOFF | IXANY;
221:         break;
222:     case 'n':
223:         /* no flow control */
224:         pts.c_cflag &= ~CRTSCTS;
225:         pts.c_iflag &= ~(IXON | IXOFF | IXANY);
226:         break;

Note that software flow control involves three flags:

When robin is being used as a helper program by another program, doing any special character processing (robin usually interprets a control- character specially) may get in the way, so we provide raw mode to sidestep all such processing. On line 120, we provide a variable that determines whether raw mode is enabled; the default is not to enable raw mode. On line 140, we tell popt how to inform us that the -r or --raw option was given on the command line, enabling raw mode.

Some systems require that you send them a carriage-return character to represent a newline. The word systems should be taken broadly here; as an example, this is true of many smart peripherals, such as UPSs, that have serial ports, because they were designed to function in the DOS world, where a carriage return/newline pair is always used to denote a new line. Line 228 allows us to specify this DOS-oriented behavior:

228:     if (crnl) {
229:         /* send CR with NL */
230:         pts.c_oflag |= ONLCR;
231:     }

The final bit of option handling controls the bits per second^[5] rate. Rather than include a large nested switch statement here, we call symbolic_speed(), already described, to get a speed_t that termios understands, as shown on line 233.

233:     /* speed is not modified unless -b is specified */
234:     if (speed) {
235:         cfsetospeed(&pts, symbolic_speed(speed));
236:         cfsetispeed(&pts, symbolic_speed(speed));
237:     }

Having determined the actual speed and gotten the symbolic value that represents it, we need to put that speed into the termios structure for the serial port. Since the termios structure supports asynchronous devices that can have different input and output speeds, we need to set both speeds to the same value here.

Before committing the changes we have made in our copies of the termios structures to the devices, on line 241 we register signal handlers for important signals that might otherwise kill us, causing us to leave the ttys in their raw state. For more information on signal handlers, see Chapter 12.

241:     sact.sa_handler = cleanup_termios;
242:     sigaction(SIGHUP, &sact, NULL);
243:     sigaction(SIGINT, &sact, NULL);
244:     sigaction(SIGPIPE, &sact, NULL);
245:     sigaction(SIGTERM, &sact, NULL);

Once the signal handler is in place to restore the old termios settings if robin is killed, we can safely put the new termios settings in place:

248:     tcsetattr(pf, TCSANOW, &pts);
249:     tcsetattr(STDIN_FILENO, TCSANOW, &sts);

Note that we use the TCSANOW option when setting these options, indicating that we want them to take effect immediately. Sometimes, it is appropriate to use other options; they are covered later in the reference section.

At this point, robin is ready to read and write characters. robin has two file descriptors to read from: data coming from the serial port and data coming from the keyboard. We use poll() to multiplex I/O between the four file descriptors, as described on page 245.

The poll() loop makes the simplifying assumption that it can always write as much as it was able to read. This is almost always true and does not cause problems in practice, because blocking for short periods is not noticeable in normal circumstances. The loop never reads from a file descriptor unless poll() has already said that that file descriptor has data waiting to be read, so we know that we do not block while reading.

For data coming from the keyboard, we may need to process escape sequences before writing, if the user did not select raw mode when running robin. Rather than include that code in the middle of this loop, we call cook_buf() (line 78), which calls send_escape() (line 58) when necessary. Both of these functions are simple. The only tricks are that cook_buf() may be called once with the escape character, then a second time with the character to interpret, and that it is optimized to call the write() function as little as is reasonably possible.

cook_buf() calls the send_escape() function once for every character that is preceded by an unescaped control- character. A q character restores the original termios settings and quits by calling the signal handler (with a bogus signal number of 0), which restores the termios settings appropriately before exiting. A b character generates a break condition, which is a long string of continuous 0 bits. Any other character, including a second control- character, is passed through to the serial port verbatim.

If either input file descriptor returns an end-of-file condition, robin exits the poll() loop and falls through to the exit processing, which is the same as the signal handler: It restores the old termios settings on both input file descriptors and exits. In raw mode, the only ways to get robin to quit are to close one of the file descriptors or to send it a signal.

The termios interface defines several functions, all of which are declared in <termios.h>. Four of them are convenience functions for manipulating a struct termios in a portable way; the rest are system calls. Those that start with cf are convenience functions; those functions that start with tc are terminal control system calls. All of the terminal control system calls generate SIGTTOU if the process is currently running in the background and tries to manipulate its controlling terminal (see Chapter 15).

Except as noted, these functions return 0 to indicate success and -1 to indicate failure. The function calls you may use for terminal control are:

int tcgetattr(int fd, struct termios *t);

int tcsetattr(int fd, int options, struct termios *t);

The options argument determines when the change takes effect.

If the system cannot handle some settings, such as data rate, it is allowed to ignore those settings silently without returning any error. The only way to see whether the settings were accepted is to use tcgetattr() and compare the contents of the structure it returns to the one you passed to tcsetattr().

Thus, most portable applications use code something like this:

#include <termios.h>

struct termios save;
struct termios set;
struct termios new;
int fd;
...
tcgetattr(fd, &save);
set = save;
cfsetospeed(&set, B2400);
cfsetispeed(&set, B2400);
tcsetattr(fd, &set);
tcgetattr(fd, &new);
if ((cfgetospeed(&set) != B2400) ||
    (cfgetispeed(&set) != B2400)) {
  /* complain */
}

speed_t cfgetospeed(struct termios *t);
speed_t cfgetispeed(struct termios *t);

int cfsetospeed(struct termios *t, speed_t speed);
int cfsetispeed(struct termios *t, speed_t speed);

int tcsendbreak(int fd, int duration)

int tcdrain(int fd)

int tcflush(int fd, int queue_selector)

int tcflow(int fd, int action)

There are two ioctl() requests that, unfortunately, were not codified as part of the termios interface, although they should have been. The size of the tty, measured in rows and columns, ought to be managed with tcgetwinsize() and tcsetwinsize(), but as they do not exist, you must use ioctl() instead. For both requesting the current size and setting a new size, use a struct winsize:

#include <termios.h>

struct winsize {
    unsigned short ws_row;      /* number of rows */
    unsigned short ws_col;      /* number of columns */
    unsigned short ws_xpixel;   /* unused */
    unsigned short ws_ypixel;   /* unused */
};

To request the current size, use

struct winsize ws;

 ioctl(fd, TIOCGWINSZ, &ws);

To set a new size, fill in a struct winsize and call

ioctl(fd, TIOCSWINSZ, &ws);

See page 389 for an example of the conditions in which you would want to set a new window size.

When the window size changes, the signal SIGWINCH is sent to the foreground process group leader on that tty. Your code can catch this signal; use TIOCGWINSZ to query the new size and make any appropriate changes within your program.

The four flag variables, c_iflag, c_oflag, c_cflag, and c_lflag, hold flags that control various characteristics. The <termios.h> header file provides symbolic constant bitmasks that represent those flags. Set them with |= and unset them with &= ~, like this:

t.c_iflag |= BRKINT;
t.c_iflag &= ~IGNBRK;

A few of these symbolic defines are actually bitmasks that cover several related constants. They are used to extract parts of the structure for comparison:

if ((t.c_cflag & CSIZE) == CS7)
  character_size = 7;

The set of flags differs from system to system. The most important flags are specified by POSIX, but Linux follows System V in including several useful flags that POSIX does not define. This documentation is not complete; Linux supports some flags that you will probably never need. We cover the flags that you might possibly have a reason to use and refrain from confusing you with the rest.

In order to enable you to write portable software, we have labelled every flag that is not specified by the POSIX standard. For those flags, you should write code like this:

#ifdef IUCLC
    t.c_iflag |= IUCLC;
#endif

Also, some areas that present particular portability problems are mentioned, and we even break our rule of not confusing you with details from other implementations by presenting a few details about what other systems do.

The input mode flags affect input processing even though they sometimes have an effect on output. The flags that operate on c_iflag are as follows:

The output mode flags modify output processing only if OPOST is set. None of these flags are portable, because POSIX defines only OPOST and calls it “implementation defined.” However, you will find that real terminal-handling applications often do need output processing, and the output flags available under Linux are generally available on most Unix systems, including SVR4.

The terminal code keeps track of the current column, which allows it to suppress extra carriage-return characters (' ') and to convert tabs to spaces when appropriate. This current column is zero-based; the first column is column zero. The current column is set to zero whenever a carriage return (' ')is sent or implied, as it may be by a newline character (' ') when ONLRET or ONLCR is set, or when the current column is set to one and a backspace character ('') is sent.

The flags that operate on c_oflag are as follows:

In addition, there are delay flags that you never need to set; they are designed to compensate for old, badly designed, and, by now, mercifully rare hardware. The termcap and terminfo libraries are responsible for managing delay flags, which means that you should never have to modify them. termcap & terminfo [Strang, 1991B], which documents them, describes them as obsolete. The Linux kernel does not currently implement them, and as there has been no demand for this feature, they likely will never be implemented.

The control mode flags affect protocol parameters, such as parity and flow control.^[8] The flags that operate on c_cflag are as follows:

Control characters are characters that have special meanings that may differ depending on whether the terminal is in canonical input mode or raw input mode and on the settings of various control flags. Each offset (except for VMIN and VTIME) in the c_cc array designates an action and holds the character code that is assigned that action. For example, set the interrupt character to Control-C with code like this:

ts.c_cc[VINTR] = CTRLCHAR('C'),

CTRLCHAR() is a macro defined as

#define CTRLCHAR(ch) ((ch)&0x1F)

Some systems have a CTRL() macro defined in <termios.h>, but it is not defined on all systems, so defining our own version is more portable.

We use the ^C notation to designate Control-C.

The character positions that are not specified by POSIX are active only if the IEXTEN local control (c_lflag) flag is set.

The control characters that you can use as subscripts to the c_cc array are:

To disable any control character position, set its value to _POSIX_VDISABLE. This only works if _POSIX_VDISABLE is defined, and is defined as something other than -1. _POSIX_VDISABLE works on Linux, but a portable program will, unfortunately, not be able to depend on disabling control character positions on all systems.

The local mode flags affect local processing, which (roughly) refers to how characters are collected before they are output. When the device is in canonical (cooked) mode, characters are echoed locally without being sent to the remote system until a newline character is encountered. At that point, the whole line is sent, and the remote end processes it without echoing it again. In raw mode, each character is sent to the remote system as it is received. Sometimes the character is echoed only by the remote system; sometimes only by the local system; and sometimes, such as when reading a password, it is not echoed at all.

Some flags may act differently, depending on whether the terminal is in canonical mode or raw mode. Those that act differently in canonical and raw mode are marked.

The flags that operate on c_lflag are as follows:

Two elements in the c_cc array are not control characters and are relevant only in raw mode: VTIME and VMIN. In raw mode only, these determine when read() returns. In canonical mode, read() returns only when lines have been assembled or end-of-file is reached, unless the O_NONBLOCK option is set.

In raw mode, it would not be efficient to read one byte at a time, and it is also inefficient to poll the port by reading in nonblocking mode. This leaves two complementary methods of reading efficiently.

The first is to use poll(), as documented in Chapter 13 and demonstrated in robin.c. If poll() says that a file descriptor is ready to read, you know that you can read() some number of bytes immediately. However, combining poll() with the second method can make your code even more efficient by making it possible to read more bytes at a time.

The VTIME and VMIN “control characters” have a complex relationship. VTIME specifies an amount of time to wait in tenths of seconds (which cannot be larger than a cc_t, usually an 8-bit unsigned char), which may be zero. VMIN specifies the minimum number of bytes to wait for (not to read—read()’s third argument specifies the maximum number of bytes to read), which may also be zero.

There are broad categories of ways to open pseudo ttys: The way everyone actually does it (in Linux, at least), the more or less standard-compliant way based on SysV, and the mostly abandoned way based on old BSD practice. The most common method among Linux system programmers is a set of BSD extensions that also have been implemented as part of glibc. The less common method is documented as part of the 1998 Unix98 standard, and documented differently in the 2000 revision of the Unix98 standard.

Historically, there have been two different methods of opening pseudo ttys on Unix and Unix-like systems. Linux originally followed the BSD model, even though it is more complex to use, because the SysV model is explicitly written in terms of STREAMS, and Linux does not implement STREAMS. The BSD model, however, requires that each application search for an unused pty master by knowing about many specific device names. Between 64 and 256 pty devices are normally available, and to find the first open device, programs search through the devices in order by minor number. They do this by searching in the peculiar lexicographic manner demonstrated in the ptypair program included in this section.

The BSD model presents several problems:

Because the SysV model is explicitly written in terms of STREAMS, and requires using STREAMS ioctl() calls to set up the slave devices, the SysV model was not really an option for Linux. However, the Unix98 interface does not specify the STREAMS-specific functionality, and in 1998 Linux added support for Unix98-style pseudo ttys.

The Linux kernel can be compiled without support for the Unix98 interface, and you may encounter older systems without Unix98-style pseudo ttys, so we present code that attempts to open Unix98-style pseudo ttys, but is also able to fall back to the BSD interface. (We do not document the STREAMS-specific parts of the SysV model; see [Stevens, 1992] for details on the STREAMS interface specifics. You should not normally need the STREAMS-specific code; the Unix98 specification does not require it.)

In the libutil library, glibc provides openpty() and forkpty(), two functions which do nearly all the work of pseudo tty handling for you.

#include <pty.h>

int openpty(int *masterfd, int *slavefd, char *name,
            struct termios *term, struct winsize *winp);
int forkpty(int *masterfd, char *name,
            struct termios *term, struct winsize *winp);

openpty() opens a set of master and slave pseudo ttys, and optionally uses struct termios and struct winsize structures passed in as options to set up the slave pseudo tty, returning 0 to indicate success and -1 to indicate failure. The master and slave file descriptors are passed back in the masterfd and slavefd arguments, respectively. The term and winp arguments may be NULL, in which case they are ignored and no setup is done.

forkpty() works the same way as openpty(), but instead of returning the slave file descriptor, it forks and sets up the slave pseudo tty as the controlling terminal on stdin, stdout, and stderr for the child process, and then, like fork(), returns the pid of the child in the parent and 0 in the child, or -1 to indicate failure.

Even these convenient interfaces have a major problem: the name argument was originally intended to pass the name of the pseudo tty device back to the calling code, but it cannot be used in a safe fashion, because openpty() and forkpty() have no way of knowing how large the buffer is. Always pass NULL as the name argument. Use the ttyname() function, described on page 337, to get the pathname of the pseudo tty device file.

The normally preferred way of working with struct termios is to use a read-modify-write cycle, but that does not apply here, for two reasons: You can pass NULL and take the default values, which should be sufficient for most cases; and when you do want to provide termios settings, you often are borrowing settings from another tty, or know exactly what the settings should be for some other reason (for example, the SCSI serial port concentrator described earlier in this chapter). Ignoring errors for clarity:

tcgetattr(STDIN_FILENO, &term);
ioctl(STDIN_FILENO, TIOCGWINSZ, &ws);
pid = forkpty(&masterfd, NULL, &term, &ws);

The Unix98 interface for allocating a pseudo tty pair is a set of functions:

#define _XOPEN_SOURCE 600
#include <stdlib.h>
#include <fcntl.h>

int posix_openpt(int oflag);
int grantpt(int fildes);
int unlockpt(int fildes);
char *ptsname(int fildes);

The posix_openpt() function is the same as opening the /dev/ptmx device but is theoretically more portable (once it is accepted everywhere). We recommend using open(“/dev/ptmx", oflag) at this time for maximum practical portability. You want one or two open() or posix_openpt() flags: Use O_RDWR normally; if you are not opening the controlling tty for the process, instead use O_RDWR|O_NOCTTY.open() or posix_openpt() returns an open file descriptor for the master pseudo tty. You then call grantpt() with the master pseudo tty file descriptor returned from posix_openpt() to change the mode and ownership of the slave pseudo tty, and then unlockpt() to make the slave pseudo tty available to be opened. The Unix98 interface for opening the slave pseudo tty is simply to open the name returned by ptsname(). These functions all return -1 on error, except for ptsname(), which returns NULL on error.

The functions in ptypair.c allocate a matched pair of pty devices. The example get_master_pty() function on line 22 of ptypair.c opens a master pty and returns the file descriptor to the parent, and also provides the name of the corresponding slave pty to open. It first tries the Unix98 interface for allocating a master pty, and if that does not work (for example, if the kernel has been compiled without Unix98 pty support, a possibility for embedded systems), it falls back to the old BSD-style interface. The corresponding get_slave_pty() function on line 87 can be used after a fork() to open the corresponding slave pty device:

  1: /* ptypair.c */
  2:
  3: #define _XOPEN_SOURCE 600
  4: #include <errno.h>
  5: #include <fcntl.h>
  6: #include <grp.h>
  7: #include <stdlib.h>
  8: #include <string.h>
  9: #include <sys/types.h>
 10: #include <sys/stat.h>
 11: #include <unistd.h>
 12:
 13:
 14: /* get_master_pty() takes a double-indirect character pointer in
 15:  * which to put a slave name, and returns an integer file
 16:  * descriptor. If it returns < 0, an error has occurred. Otherwise,
 17:  * it has returned the master pty file descriptor, and fills in
 18:  * *name with the name of the corresponding slave pty. Once the
 19:  * slave pty has been opened, you are responsible to free *name.
 20:  */
 21:
 22: int get_master_pty(char **name) {
 23:     int i, j;
 24:     /* default to returning error */
 25:     int master = -1;
 26:     char *slavename;
 27:
 28:     master = open("/dev/ptmx", O_RDWR);
 29:     /* This is equivalent to, though more widely implemented but
 30:      * theoretically less portable than:
 31:      * master = posix_openpt(O_RDWR);
 32:      */
 33:
 34:     if (master >= 0 && grantpt (master) >= 0 &&
 35:                        unlockpt (master) >= 0) {
 36:         slavename = ptsname(master);
 37:         if (!slavename) {
 38:             close(master);
 39:             master = -1;
 40:             /* fall through to fallback */
 41:         } else {
 42:             *name = strdup(slavename);
 43:             return master;
 44:         }
 45:     }
 46:
 47:     /* The rest of this function is a fallback for older systems */
 48:
 49:     /* create a dummy name to fill in */
 50:     *name = strdup("/dev/ptyXX");
 51:
 52:     /* search for an unused pty */
 53:     for (i=0; i<16 && master <= 0; i++) {
 54:         for (j=0; j<16 && master <= 0; j++) {
 55:             (*name)[8] = "pqrstuvwxyzPQRST"[i];
 56:             (*name)[9] = "0123456789abcdef"[j];
 57:             /* open the master pty */
 58:             if ((master = open(*name, O_RDWR)) < 0) {
 59:                 if (errno == ENOENT) {
 60:                     /* we are out of pty devices */
 61:                     free (*name);
 62:                     return (master);
 63:                 }
 64:             }
 65:         }
 66:     }
 67:
 68:     if ((master < 0) && (i == 16) && (j == 16)) {
 69:         /* must have tried every pty unsuccessfully */
 70:         free (*name);
 71:         return (master);
 72:     }
 73:
 74:     /* By substituting a letter, we change the master pty
 75:      * name into the slave pty name.
 76:      */
 77:     (*name)[5] = 't';
 78:
 79:     return (master);
 80: }
 81:
 82: /* get_slave_pty() returns an integer file descriptor.
 83:  * If it returns < 0, an error has occurred.
 84:  * Otherwise, it has returned the slave file descriptor.
 85:  */
 86:
 87: int get_slave_pty(char *name) {
 88:     struct group *gptr;
 89:     gid_t gid;
 90:     int slave = -1;
 91:
 92:     if (strcmp(name, "/dev/pts/")) {
 93:         /* The Unix98 interface has not been used, special
 94:          * permission or ownership handling is necessary.
 95:          *
 96:          * chown/chmod the corresponding pty, if possible.
 97:          * This will work only if the process has root permissions.
 98:          * Alternatively, write and exec a small setuid program
 99:          * that does just this.
100:          *
101:          * Alternatively, just ignore this and use only the Unix98
102:          * interface.
103:          */
104:         if ((gptr = getgrnam("tty")) != 0) {
105:             gid = gptr->gr_gid;
106:         } else {
107:             /* if the tty group does not exist, don't change the
108:              * group on the slave pty, only the owner
109:              */
110:             gid = -1;
111:         }
112:
113:         /* Note that we do not check for errors here.  If this is
114:          * code where these actions are critical, check for errors!
115:          */
116:         chown(name, getuid(), gid);
117:
118:         /* This code makes the slave read/writeable only for the
119:          * user. If this is for an interactive shell that will
120:          * want to receive "write" and "wall" messages, OR S_IWGRP
121:          * into the second argument below.  In that case, you will
122:          * want to move this line outside the if() clause so that
123:          * it is run for * both BSD-style and Unix98-style
124:          * interfaces.
125:          */
126:         chmod(name, S_IRUSR|S_IWUSR);
127:     }
128:
129:     /* open the corresponding slave pty */
130:     slave = open(name, O_RDWR);
131:
132:     return (slave);
133: }

The get_slave_pty() function does nothing new. Every function in it is described elsewhere in this book, so we do not explain it here.

Perhaps one of the simplest programs that can be written to use ptys is a program that opens a pty pair and runs a shell on the slave pty, connecting it to the master pty. Having written that program, you can expand it in any way that you wish. forkptytest.c is an example using the forkpty() function; ptytest.c is an example that uses the functions defined in ptypair.c, and it is by necessity more complicated.

  1: /* forkptytest.c */
  2:
  3: #include <errno.h>
  4: #include <signal.h>
  5: #include <stdio.h>
  6: #include <stdlib.h>
  7: #include <sys/ioctl.h>
  8: #include <sys/poll.h>
  9: #include <termios.h>
 10: #include <unistd.h>
 11: #include <pty.h>
 12:
 13:
 14: volatile int propagate_sigwinch = 0;
 15:
 16: /* sigwinch_handler
 17:  * propagate window size changes from input file descriptor to
 18:  * master side of pty.
 19:  */
 20: void sigwinch_handler(int signal) {
 21:     propagate_sigwinch = 1;
 22: }
 23:
 24:
 25: /* forkptytest tries to open a pty pair with a shell running
 26:  * underneath the slave pty.
 27:  */
 28: int main (void) {
 29:     int master;
 30:     int pid;
 31:     struct pollfd ufds[2];
 32:     int i;
 33: #define BUFSIZE 1024
 34:     char buf[1024];
 35:     struct termios ot, t;
 36:     struct winsize ws;
 37:     int done = 0;
 38:     struct sigaction act;
 39:
 40:     if (ioctl(STDIN_FILENO, TIOCGWINSZ, &ws) < 0) {
 41::        perror("ptypair: could not get window size");
 42:         exit(1);
 43:     }
 44:
 45:     if ((pid = forkpty(&master, NULL, NULL, &ws)) < 0) {
 46:         perror("ptypair");
 47:         exit(1);
 48:     }
 49:
 50:     if (pid == 0) {
 51:         /* start the shell */
 52:         execl("/bin/sh", "/bin/sh", 0);
 53:
 54:         /* should never be reached */
 55:         exit(1);
 56:     }
 57:
 58:     /* parent */
 59:     /* set up SIGWINCH handler */
 60:     act.sa_handler = sigwinch_handler;
 61:     sigemptyset(&(act.sa_mask));
 62:     act.sa_flags = 0;
 63:     if (sigaction(SIGWINCH, &act, NULL) < 0) {
 64:         perror("ptypair: could not handle SIGWINCH ");
 65:         exit(1);
 66:     }
 67:
 68:     /* Note that we only set termios settings for standard input;
 69:      * the master side of a pty is NOT a tty.
 70:      */
 71:     tcgetattr(STDIN_FILENO, &ot);
 72:     t = ot;
 73:     t.c_lflag &= ~(ICANON | ISIG | ECHO | ECHOCTL | ECHOE | 
 74:                    ECHOK | ECHOKE | ECHONL | ECHOPRT );
 75:     t.c_iflag |= IGNBRK;
 76:     t.c_cc[VMIN] = 1;
 77:     t.c_cc[VTIME] = 0;
 78:     tcsetattr(STDIN_FILENO, TCSANOW, &t);
 79:
 80:     /* This code comes nearly verbatim from robin.c
 81:      * If the child exits, reading master will return -1
 82:      * and we exit.
 83:      */
 84:     ufds[0].fd = STDIN_FILENO;
 85:     ufds[0].events = POLLIN;
 86:     ufds[1].fd = master;
 87:     ufds[1].events = POLLIN;
 88:
 89:     do {
 90:         int r;
 91:
 92:         r = poll(ufds, 2, -1);
 93:         if ((r < 0) && (errno != EINTR)) {
 94:             done = 1;
 95:             break;
 96:         }
 97:
 98:         /* First check for an opportunity to exit */
 99:         if ((ufds[0].revents | ufds[1].revents) &
100:             (POLLERR | POLLHUP | POLLNVAL)) {
101:             done = 1;
102:             break;
103:         }
104:
105:         if (propagate_sigwinch) {
106:             /* signal handler has asked for SIGWINCH propagation */
107:             if (ioctl(STDIN_FILENO, TIOCGWINSZ, &ws) < 0) {
108:                 perror("ptypair: could not get window size");
109:             }
110:             if (ioctl(master, TIOCSWINSZ, &ws) < 0) {
111:                 perror("could not restore window size");
112:             }
113:
114:             /* now do not do this again until next SIGWINCH */
115:             propagate_sigwinch = 0;
116:
117:             /* poll may have been interrupted by SIGWINCH,
118:              * so try again.
119:              */
120:             continue;
121:         }
122:
123:         if (ufds[1].revents & POLLIN) {
124:             i = read(master, buf, BUFSIZE);
125:             if (i >= 1) {
126:                 write(STDOUT_FILENO, buf, i);
127:             } else {
128:                 done = 1;
129:             }
130:         }
131:
132:         if (ufds[0].revents & POLLIN) {
133:             i = read(STDIN_FILENO, buf, BUFSIZE);
134:             if (i >= 1) {
135:                 write(master, buf, i);
136:             } else {
137:                 done = 1;
138:             }
139:         }
140:
141:     } while (!done);
142:
143:     tcsetattr(STDIN_FILENO, TCSANOW, &ot);
144:     exit(0);
145: }

forkptytest.c does very little that we have not seen before. Signal handling is described in Chapter 12, and the poll() loop is almost exactly straight from robin.c on page 355 (minus the escape-character processing), as is the code modifying termios settings.

This leaves propagating window-size changes to be explained here.

On line 105, after poll() exits, we check to see if the reason that poll() exited was the SIGWINCH signal being delivered to the sigwinch_handler function on line 20. If it was, we need to get the new current window size from standard input and propagate it to the slave’s pty. By setting the window size, SIGWINCH is sent automatically to the process running on the pty; we should not explicitly send a SIGWINCH to that process.

Now, by contrast, see how much more complicated this code is when you have to use the functions we have defined in ptypair.c:

  1: /* ptytest.c */
  2:
  3: #include <errno.h>
  4: #include <fcntl.h>
  5: #include <signal.h>
  6: #include <stdio.h>
  7: #include <stdlib.h>
  8: #include <string.h>
  9: #include <sys/ioctl.h>
 10: #include <sys/poll.h>
 11: #include <sys/stat.h>
 12: #include <termios.h>
 13: #include <unistd.h>
 14: #include "ptypair.h"
 15:
 16:
 17: volatile int propagate_sigwinch = 0;
 18:
 19: /* sigwinch_handler
 20:  * propagate window size changes from input file descriptor to
 21:  * master side of pty.
 22:  */
 23: void sigwinch_handler(int signal) {
 24:     propagate_sigwinch = 1;
 25: }
 26:
 27:
 28: /* ptytest tries to open a pty pair with a shell running
 29:  * underneath the slave pty.
 30:  */
 31: int main (void) {
 32:     int master;
 33:     int pid;
 34:     char *name;
 35:     struct pollfd ufds[2];
 36:     int i;
 37: #define BUFSIZE 1024
 38:     char buf[1024];
 39:     struct termios ot, t;
 40:     struct winsize ws;
 41:     int done = 0;
 42:     struct sigaction act;
 43:
 44:     if ((master = get_master_pty(&name)) < 0) {
 45:         perror("ptypair: could not open master pty");
 46:         exit(1);
 47:     }
 48:
 49:     /* set up SIGWINCH handler */
 50:     act.sa_handler = sigwinch_handler;
 51:     sigemptyset(&(act.sa_mask));
 52:     act.sa_flags = 0;
 53:     if (sigaction(SIGWINCH, &act, NULL) < 0) {
 54:         perror("ptypair: could not handle SIGWINCH ");
 55:         exit(1);
 56:     }
 57:
 58:     if (ioctl(STDIN_FILENO, TIOCGWINSZ, &ws) < 0) {
 59:         perror("ptypair: could not get window size");
 60:         exit(1);
 61:     }
 62:
 63:     if ((pid = fork()) < 0) {
 64:         perror("ptypair");
 65:         exit(1);
 66:     }
 67:
 68:     if (pid == 0) {
 69:         int slave; /* file descriptor for slave pty */
 70:
 71:         /* We are in the child process */
 72:         close(master);
 73:
 74:         if ((slave = get_slave_pty(name)) < 0) {
 75:             perror("ptypair: could not open slave pty");
 76:             exit(1);
 77:         }
 78:         free(name);
 79:
 80:         /* We need to make this process a session group leader,
 81:          * because it is on a new PTY, and things like job control
 82:          * simply will not work correctly unless there is a session
 83:          * group leader and process group leader (which a session
 84:          * group leader automatically is). This also disassociates
 85:          * us from our old controlling tty.
 86:          */
 87:         if (setsid() < 0) {
 88:             perror("could not set session leader");
 89:         }
 90:
 91:         /* Tie us to our new controlling tty. */
 92:         if (ioctl(slave, TIOCSCTTY, NULL)) {
 93:             perror("could not set new controlling tty");
 94:         }
 95:
 96:         /* make slave pty be standard in, out, and error */
 97:         dup2(slave, STDIN_FILENO);
 98:         dup2(slave, STDOUT_FILENO);
 99:         dup2(slave, STDERR_FILENO);
100:
101:         /* at this point the slave pty should be standard input */
102:         if (slave > 2) {
103:             close(slave);
104:         }
105:
106:         /* Try to restore window size; failure isn't critical */
107:         if (ioctl(STDOUT_FILENO, TIOCSWINSZ, &ws) < 0) {
108:             perror("could not restore window size");
109:         }
110:
111:         /* now start the shell */
112:         execl("/bin/sh", "/bin/sh", 0);
113:
114:         /* should never be reached */
115:         exit(1);
116:     }
117:
118:     /* parent */
119:     free(name);
120:
121:     /* Note that we only set termios settings for standard input;
122:      * the master side of a pty is NOT a tty.
123:      */
124:     tcgetattr(STDIN_FILENO, &ot);
125:     t = ot;
126:     t.c_lflag &= ~(ICANON | ISIG | ECHO | ECHOCTL | ECHOE | 
127:                    ECHOK | ECHOKE | ECHONL | ECHOPRT);
128:     t.c_iflag |= IGNBRK;
129:     t.c_cc[VMIN] = 1;
130:     t.c_cc[VTIME] = 0;
131:     tcsetattr(STDIN_FILENO, TCSANOW, &t);
132:
133:     /* This code comes nearly verbatim from robin.c
134:      * If the child exits, reading master will return -1 and
135:      * we exit.
136:      */
137:     ufds[0].fd = STDIN_FILENO;
138:     ufds[0].events = POLLIN;
139:     ufds[1].fd = master;
140:     ufds[1].events = POLLIN;
141:
142:     do {
143:         int r;
144:
145:         r = poll(ufds, 2, -1);
146:         if ((r < 0) && (errno != EINTR)) {
147:             done = 1;
148:             break;
149:         }
150:
151:         /* First check for an opportunity to exit */
152:         if ((ufds[0].revents | ufds[1].revents) &
153:             (POLLERR | POLLHUP | POLLNVAL)) {
154:             done = 1;
155:             break;
156:         }
157:
158:         if (propagate_sigwinch) {
159:             /* signal handler has asked for SIGWINCH propagation */
160:             if (ioctl(STDIN_FILENO, TIOCGWINSZ, &ws) < 0) {
161:                 perror("ptypair: could not get window size");
162:             }
163:             if (ioctl(master, TIOCSWINSZ, &ws) < 0) {
164:                 perror("could not restore window size");
165:             }
166:
167:             /* now do not do this again until next SIGWINCH */
168:             propagate_sigwinch = 0;
169:
170:             /* poll may have been interrupted by SIGWINCH,
171:              * so try again. */
172:             continue;
173:         }
174:
175:         if (ufds[1].revents & POLLIN) {
176:             i = read(master, buf, BUFSIZE);
177:             if (i >= 1) {
178:                 write(STDOUT_FILENO, buf, i);
179:             } else {
180:                 done = 1;
181:             }
182:         }
183:
184:         if (ufds[0].revents & POLLIN) {
185:             i = read(STDIN_FILENO, buf, BUFSIZE);
186:             if (i >= 1) {
187:                 write(master, buf, i);
188:             } else {
189:                 done = 1;
190:             }
191:         }
192:     } while (!done);
193:
194:     tcsetattr(STDIN_FILENO, TCSANOW, &ot);
195:     exit(0);
196: }

All the added complexity of ptytest.c beyond forkptytest.c is to handle the complexity of the old interface. This has been described in this chapter, except for starting a child process, which is introduced in Chapter 10.