14. Computer Set-Up (Configure) Details

There are various files to edit to set up the computer for terminals. If you're lucky, you'll only need to edit /etc/inittab. One does this by editing at the console (or from any working terminal).

14.1 Getty (in /etc/inittab)

Introduction to Getty

In order to have a login process run on a serial port (and the terminal connected to it) when the computer starts up (or switches run levels) a getty command must be put into the /etc/inittab file. Running getty from the command line may cause problems (see If getty run from command line: Programs get stopped to see why ). Getty GETs a TTY (a terminal) going. Each terminal needs its own getty command. There is also at least one getty command for the console in every /etc/inittab file. Find this and put the getty commands for the real terminals next to it. This file may contain sample getty lines for text terminals that are commented out so that all you need to do is to uncomment them (remove the leading #) and change a few arguments.

The arguments which are permitted depend on which getty you use:
Two gettys best for directly connected terminals are:

1. agetty (sometimes just called getty): Very easy to set up. No config files. See agetty
2. getty (part of getty_ps)

1. mgetty: the best one for modems; works for terminals too but inferior
2. uugetty: for modems only; part of the getty_ps package

1. mingetty
2. fbgetty

Your Linux distribution should come with either ps_getty or agetty for text-terminals. Unfortunately, they often just call it "getty" so you may need to determine which one you have since the arguments you put after it in /etc/inittab differ. Debian uses agetty (in the util-linux package). RedHat uses ps_getty. As a last resort you might check the source code (usually in /sbin). ps_getty has /etc/gettydefs embedded in the source code. To search for it, go to /sbin and type:
strings getty | grep getty
If getty is actually agetty the above will result in nothing. However if you have agetty typing:
getty -h
should show the options [-hiLmw].

If you don't have the getty you want check other distributions and the alien program to convert between RPM and Debian packages. The source code may be downloaded from Getty Software.

If you are not using modem control lines (for example if you only use the minimum number of 3 conductors: transmit, receive, and common signal ground) you should let getty know this by using a "local" flag. The format of this depends on which getty you use.

Getty exits after login (and can respawn)

After you log in you will notice (by using "top" or "ps -ax") that the getty process is no longer running. What happened to it? Why does getty restart again if your shell is killed? Here's why.

After you type in your user name, getty takes it and calls the login program telling it your user name. The getty process is replaced by the login process. The login process asks for your password, checks it and starts whatever process is specified in your password file. This process is often the bash shell. If so, bash starts and replaces the login process. Note that one process replaces another and that the bash shell process originally started as the getty process. The implications of this will be explained below.

Now in the /etc/inittab file getty is supposed to respawn (restart) if killed. It says so on the line that calls getty. But if the bash shell (or the login process) is killed, getty respawns (restarts). Why? Well, both the login process and bash are replacements for getty and inherit the signal connections establish by their predecessors. In fact if you observe the details you will notice that the replacement process will have the same process ID as the original process. Thus bash is sort of getty in disguise with the same process ID number. If bash is killed it is just like getty was killed (even though getty isn't running anymore). This results in getty respawning.

When one logs out, all the processes on that serial port are killed including the bash shell. This may also happen (if enabled) if a hangup signal is sent to the serial port by a drop of DCD voltage by the modem. Either the logout or drop in DCD will result in getty respawning. One may force getty to respawn by manually killing bash (or login) either by hitting the k key, etc. while in "top" or with the "kill" command. You will likely need to kill it with signal 9 (which can't be ignored).

If getty run from command line: Programs get stopped

You should normally run getty from inside /etc/inittab and not from the command line or else some programs running on the terminal may be unexpectedly suspended (stopped). Here's why (skip to the next section if the why is not important to you). If you start getty for say ttyS1 from the command line of another terminal, say tty1, then it will have tty1 as its "controlling terminal" even though the actual terminal it runs on is ttyS1. Thus it has the wrong controlling terminal. But if it's started inside the inittab file then it will have ttyS1 as the controlling terminal (correct).

Even though the controlling terminal is wrong, the login at ttyS1 works fine (since you gave ttyS1 as an argument to getty). The standard input and output are set to ttyS1 even though the controlling terminal remains tty11. Other programs run at ttyS1 may inherit this standard input/output (which is connected to ttyS1) and everything is OK. But some programs may make the mistake of trying to read from their controlling terminal (tty1) which is wrong. Now tty1 may think that these programs are being run in the background by tty1 so an attempt to read from tty1 (it should have been ttyS1) results in stopping the process that attempted to read. (A background process is not allowed to read from its controlling terminal.). You may see a message something like: "[1]+ Stopped" on the screen. At this point you are stuck since you can't interact with a process which is trying to communicate with you via the wrong terminal. Of course to escape from this you can go to another terminal and kill the process, etc.

agetty (may be named getty)

An example line in /etc/inittab:

S1:23:respawn:/sbin/getty -L 19200 ttyS1 vt102

Agetty's auto-detection of parity problems

The agetty program will attempt to auto-detect the parity set inside the terminal (including no parity). It doesn't support 8-bit data bytes plus 1-bit parity. See 8-bit data bytes (plus parity) If you use stty to set parity, agetty will automatically unset it since it initially wants the parity bit to come thru as if it was a data bit. This is because it needs to get the last bit (possibly a parity bit) as you type your login-name so that it can auto-detect parity. Thus if you use parity, enable it only inside the text-terminal and let agetty auto-detect it and set it at the computer. If your terminal supports received parity, the login prompt will look garbled until you type something so that getty can detect the parity. The garbled prompt will deter visitors, etc. from trying to login. That could be just what you want.

There is sometimes a problem with auto detection of parity. This happens because after you first type your login name, agetty starts the login program to finish logging you in. Unfortunately, the login program can't detect parity so if the getty program failed to determine the parity then login will not be able to determine it either. If the first login attempt fails, login will let you try again, etc. (all with the parity set wrong). Eventually, after a number of failed attempts to login (or after a timeout) agetty will start up again and start the login seqeunces all over again. Once getty is running again, it may be able to detect the parity on the second try so everything may then work OK.

With wrong parity, the login program can't correctly read what you type and you can't log in. If your terminal supports received parity, you will continue to see a garbled screen. If getty fails to detect partity an /etc/issue file is usually dumped to the screen just before the before the prompt, so more grabled words may appear on the screen.

Why can't agetty detect parity by the first letter typed? Here's an example: Suppose it detects an 8-bit byte with its parity bit 0 (high-order bit) and with an odd number of 1-bits. What parity is it? Well, the odd number of 1 bits implies that it's odd partiy. But it could also just be an 8-bit character with no parity. There's no way so far to determine which. But so far we have eliminated the possibility of even parity. The detection of parity thus proceeds by a process of elimination.

If the next byte typed is similar to the first one and also only eliminates the possibility of even parity, it's still impossible to determine parity. This situation can continue indefinitly and in rare cases login will fail until you change your login-name. If agetty finds a parity bit of 1 it will assume that this is a parity bit and not a high-order bit of an 8-bit character. It thus assumes that you don't use meta-characters (high bit set) in your user name (i.e that your name is in ASCII).

One may get into a "login loop" in various ways. Suppose you only type a single letter or two for your login name and then hit return. If these letters are not sufficient for parity detection, then login runs before parity has been detected. Sometimes this problem happens if you don't have the terminal on and/or connected when agetty first starts up.

If you get stuck in this "login loop" a way out of it is to hit the return key several times until you get the getty login prompt. Another way is to just wait a minute or so for a timeout. Then the getty login prompt will be put on the screen by the getty program and you may try again to log in.

8-bit data bytes (plus parity)

Unfortunately, agetty can't detect this parity. As of late 1999 it has no option for disabling the auto-detection of parity and thus will detect incorrect parity. The result is that the login process will be garbled and parity will be set wrong. Thus it doesn't seem feasible to try to use 8-bit data bytes with parity.

getty (part of getty_ps)

(Most of this is from the old Serial-HOWTO by Greg Hankins)
For this getty one needs to both put entries in a configuration file and add an entry in /etc/inittab. Here are some example entries to use for your terminal that you put into the configuration file /etc/gettydefs.

# 38400 bps Dumb Terminal entry
DT38400# B38400 CS8 CLOCAL # B38400 SANE -ISTRIP CLOCAL #@S @L login: #DT38400

# 19200 bps Dumb Terminal entry
DT19200# B19200 CS8 CLOCAL # B19200 SANE -ISTRIP CLOCAL #@S @L login: #DT19200

# 9600 bps Dumb Terminal entry
DT9600# B9600 CS8 CLOCAL # B9600 SANE -ISTRIP CLOCAL #@S @L login: #DT9600

Note that the DT38400, DT19200, etc. are just labels and must be the same that you use in /etc/inittab.

If you want, you can make getty print interesting things in the login banner. In my examples, I have the system name and the serial line printed. You can add other things:

@B    The current (evaluated at the time the @B is seen) bps rate.
@D    The current date, in MM/DD/YY.
@L    The serial line to which getty is attached.
@S    The system name.
@T    The current time, in HH:MM:SS (24-hour).
@U    The number of currently signed-on users.  This is  a
      count of the number of entries in the /etc/utmp file
      that have a non-null ut_name field.
@V    The value of VERSION, as given in the defaults file.
To display a single '@' character, use either '\@' or '@@'.

When you are done editing /etc/gettydefs, you can verify that the syntax is correct by doing:

linux# getty -c /etc/gettydefs

Make sure there is no other getty or uugetty config file for the serial port that your terminal is attached to such as (/etc/default/{uu}getty.ttySN or /etc/conf.{uu}getty.ttySN), as this will probably interfere with running getty on a terminal. Remove such conflicting files if they exits.

Edit your /etc/inittab file to run getty on the serial port (substituting in the correct information for your environment - port, speed, and default terminal type):

S1:23:respawn:/sbin/getty ttyS1 DT9600 vt100

linux# init q 

At this point, you should see a login prompt on your terminal. You may have to hit return to get the terminal's attention.

mgetty

The "m" stands for modem. This program is primarily for modems and as of mid 2000 it will require recompiling to use it for text-terminals (unless you use hardware flow control --and that usually requires a hand-made cable). For the documentation for directly connected terminals see the "Direct" section of the manual: mgetty.texi.

Look at the last lines of /etc/mgetty/mgetty.config for an example of configuring it for a terminal. Unless you say "toggle-dtr no" it will think that you have a modem and drop (negate) the DTR pin at the PC in a vain attempt to reset the non-existent modem. In contrast to other gettys, mgetty will not attach itself to a terminal until someone hits any key of that terminal so you'll see a ? for the terminal in top or ps until this happens. The logs in /var/log/mgetty/ may show a few warning messages which are only applicable to modems which you may ignore.

Here's an example of the simple line you put in /etc/inittab:

s1:23:respawn:/sbin/mgetty -r ttyS1

14.2 Stty & Setserial

There is both a "stty" command and a "setserial" command for setting up the serial ports. Some (or all) of the needed stty settings can be done via getty and there may be no need to use setserial so you may not need to use either command. These two commands (stty and setserial) set up different aspects of the serial port. Stty does the most while setserial configures the low-level stuff such as interrupts and port addresses. To "save" the settings, these commands must be written in certain files (shell scripts) which run each time the computer starts up. Distributions of Linux often supply a shell script which runs setserial but seldom supply one which runs stty since on seldom need it.

14.3 Setserial

This part is in 3 HOWTOs: Modem, Serial, and Text-Terminal. There are some minor differences, depending on which HOWTO it appears in.

Introduction

If you have a Laptop (PCMCIA) don't use setserial until you read Laptops: PCMCIA. setserial is a program which allows you to tell the device driver software the I/O address of the serial port, which interrupt (IRQ) is set in the port's hardware, what type of UART you have, etc. Since theres a good chance that the serial ports will be automatically detected and set, many people never need to use setserial. In any case setserial will not work without either serial support built into the kernel or loaded as a module. The module may get loaded automatically if you (or a script) tries to use setserial.

Setserial can also show how the driver is currently set. In addition, it can be made to probe the hardware and try to determine the UART type and IRQ, but this has severe limitations. See Probing. Note that it can't set the IRQ or the port address in the hardware of PnP serial ports (but the plug-and-play features of the serial driver may do this).

If you only have one or two built-in serial ports, they will usually get set up correctly without using setserial. Otherwise, if you add more serial ports (such as a modem card) you will likely need to deal with setserial. Besides the man page for setserial, check out info in /usr/doc/setserial.../ or /usr/share/doc/setserial. It should tell you how setserial is handled in your distribution of Linux.

Setserial is often run automatically at boot-time by a start-up shell-script for the purpose of assigning IRQs, etc. to the driver. Setserial will only work if the serial module is loaded (or if the equivalent was compiled into your kernel). If the serial module gets unloaded later on, the changes previously made by setserial will be forgotten by the kernel. But recent (2000) distributions may contain scripts that save and restore this. If not, then setserial must be run again to reestablish them. In addition to running via a start-up script, something akin to setserial also runs earlier when the serial module is loaded (or the like). Thus when you watch the start-up messages on the screen it may look like it ran twice, and in fact it has.

Setserial can set the time that the port will keep operating after it's closed (in order to output any characters still in its buffer in main RAM). This is needed at slow baud rates of 1200 or lower. It's also needed at higher speeds if there are a lot of "flow control" waits. See "closing_wait" in the setserial man page. If your serial port is Plug-and-Play you may need to consult other HOWTOs such as Plug-and-Play or Serial.

Setserial does not set either IRQ's nor I/O addresses in the serial port hardware itself. That is done either by jumpers or by plug-and-play. You must tell setserial the identical values that have been set in the hardware. Do not just invent some values that you think would be nice to use and then tell them to setserial. However, if you know the I/O address but don't know the IRQ you may command setserial to attempt to determine the IRQ.

You can see a list of possible commands by just typing setserial with no arguments. This fails to show you the one-letter options such as -v for verbose which you should normally use when troubleshooting. Note that setserial calls an IO address a "port". If you type:

setserial -g /dev/ttyS*

If you add -a to the option -g you will see more info although few people need to deal with (or understand) this additional info since the default settings you see usually work fine. In normal cases the hardware is set up the same way as "setserial" reports, but if you are having problems there is a good chance that "setserial" has it wrong. In fact, you can run "setserial" and assign a purely fictitious I/O port address, any IRQ, and whatever uart type you would like to have. Then the next time you type "setserial ..." it will display these bogus values without complaint. They will also be officially registered with the kernel as displayed (at the top of the screen) by the "scanport" command. Of course the serial port driver will not work correctly (if at all) if you attempt to use such a port. Thus when giving parameters to "setserial" anything goes. Well almost. If you assign one port a base address that is already assigned (such as 3e8) it will not accept it. But if you use 3e9 it will accept it. Unfortunately 3e9 is already assigned since it is within the range starting at base address 3e8. Thus the moral of the story is to make sure your data is correct before assigning resources with setserial.

While assignments made by setserial are lost when the PC is powered off, a configuration file may restore them (or a previous configuration) when the PC is started up again. In newer versions, what you change by setserial may get automatically saved to a configuration file. In older versions, the configuration file only changes if you edit it manually so the configuration always remains the same from boot to boot. See Configuration Scripts/Files

Probing

Prior to probing with "setserial", one may run the "scanport" command to check all possible ports in one scan. It makes crude guesses as to what is on some ports but doesn't determine the IRQ. But it's a fast first start. It may hang your PC but so far it's worked fine for me.

With appropriate options, setserial can probe (at a given I/O address) for a serial port but you must guess the I/O address. If you ask it to probe for /dev/ttyS2 for example, it will only probe at the address it thinks ttyS2 is at (2F8). If you tell setserial that ttyS2 is at a different address, then it will probe at that address, etc. See Probing

The purpose of this is to see if there is a uart there, and if so, what its IRQ is. Use "setserial" mainly as a last resort as there are faster ways to attempt it such as wvdialconf to detect modems, looking at very early boot-time messages, or using pnpdump --dumpregs. To try to detect the physical hardware use for example :
setserial /dev/ttyS2 -v autoconfig
If the resulting message shows a uart type such as 16550A, then you're OK. If instead it shows "unknown" for the uart type, then there is supposedly no serial port at all at that I/O address. Some cheap serial ports don't identify themselves correctly so if you see "unknown" you still might have a serial port there.

Besides auto-probing for a uart type, setserial can auto-probe for IRQ's but this doesn't always work right either. In one case it first gave the wrong irq but when the command was repeated it found the correct irq. In versions of setserial >= 2.15, the results of your last probe test could be automatically saved and put into the configuration file /etc/serial.conf which will be used next time you start Linux. At boot-time when the serial module loads (or the like), a probe for UARTs is made automatically and reported on the screen. But the IRQs shown may be wrong. The second report of the same is the result of a script which usually does no probing and thus provides no reliable information as to how the hardware is actually set. It only shows configuration data someone wrote into the script or data that got saved in /etc/serial.conf.

It may be that two serial ports both have the same IO address set in the hardware. Of course this is not permitted but it sometimes happens anyway. Probing detects one serial port when actually there are two. However if they have different IRQs, then the probe for IRQs may show IRQ = 0. For me it only did this if I first used setserial to give the IRQ a ficticious value.

Boot-time Configuration

When the kernel loads the serial module (or if the "module equivalent" is built into the kernel) then only ttyS{0-3} are auto-detected and the driver is set to use only IRQs 4 and 3 (regardless of what IRQs are actually set in the hardware). You see this as a boot-time message just like as if setserial had been run.

To correct possible errors in IRQs (or for other reasons) there may be a file somewhere that runs setserial again. Unfortunately, if this file has some IRQs wrong, the kernel will still have incorrect info about the IRQs. This file should run early at boot-time before any process uses the serial port. In fact, your distribution may have set things up so that the setserial program runs automatically from a start-up script at boot-time. More info about how to handle this situation for your particular distribution might be found in file named "setserial..." or the like located in directory /usr/doc/ or /usr/share/doc/.

Before modifying a configuration file, you can test out a "proposed" setserial command by just typing it on the command line. In some cases the results of this use of setserial will automatically get saved in /etc/serial.conf when you shutdown. So if it worked OK (and solved your problem) then there's no need to modify any configuration file. See New configuration method using /etc/serial.conf.

Configuration Scripts/Files

Your objective is to modify (or create) a script file in the /etc tree that runs setserial at boot-time. Most distributions provide such a file (but it may not initially reside in the /etc tree). In addition, setserial 2.15 and higher often have an /etc/serial.conf file that is used by the above script so that you don't need to directly edit the script that runs setserial. In addition just using setserial on the command line (2.15+) may ultimately alter this configuration file.

So prior to version 2.15 all you do is edit a script. After 2.15 you may need to either do one of three things: 1. edit a script. 2. edit /etc/serial.conf or 3. run "setserial" on the command line which may result in /etc/serial.conf automatically being edited. Which one of these you need to do depends on both your particular distribution, and how you have set it up.

Edit a script (required prior to version 2.15)

Prior to setserial 2.15 (1999) there was no /etc/serial.conf file to configure setserial. Thus you need to find the file that runs "setserial" at boot time and edit it. If it doesn't exist, you need to create one (or place the commands in a file that runs early at boot-time). If such a file is currently being used it's likely somewhere in the /etc directory-tree. But Redhat <6.0 has supplied it in /usr/doc/setserial/ but you need to move it to the /etc tree before using it. You might use "locate" to try to find such a file. For example, you could type: locate "*serial*".

The script /etc/rc.d/rc.serial was commonly used in the past. The Debian distribution used /etc/rc.boot/0setserial. Another file once used was /etc/rc.d/rc.local but it's not a good idea to use this since it may not be run early enough. It's been reported that other processes may try to open the serial port before rc.local runs resulting in serial communication failure. Today it's most likely in /etc/init.d/ but it isn't normally intended to be edited.

If such a file is supplied, it should contain a number of commented-out examples. By uncommenting some of these and/or modifying them, you should be able to set things up correctly. Make sure that you are using a valid path for setserial, and a valid device name. You could do a test by executing this file manually (just type its name as the super-user) to see if it works right. Testing like this is a lot faster than doing repeated reboots to get it right.

For versions >= 2.15 (provided your distribution implemented the change, Redhat didn't) it may be more tricky to do since the file that runs setserial on startup, /etc/init.d/setserial or the like was not intended to be edited by the user. See New configuration method using /etc/serial.conf.

If you want setserial to automatically determine the uart and the IRQ for ttyS3 you would add something like:

/sbin/setserial  /dev/ttyS3 auto_irq skip_test autoconfig

/sbin/setserial /dev/ttyS3 irq 5 uart 16550A  skip_test 

New configuration method using /etc/serial.conf

Prior to setserial version 2.15, the way to configure setserial was to manually edit the shell-script that ran setserial at boot-time. See Edit a script (after version 2.15: perhaps not). Starting with version 2.15 (1999) of setserial this shell-script is not edited but instead gets its data from a configuration file: /etc/serial.conf. Furthermore you may not even need to edit serial.conf because using the "setserial" command on the command line may automatically cause serial.conf to be edited appropriately.

This was intended so that you don't need to edit any file in order to set up (or change) what setserial does each time that Linux is booted. But there are serious pitfalls because it's not really "setserial" that edits serial.conf. Confusion is compounded because different distributions handle this differently. In addition, you may modify it so that it works differently.

What often happens is this: When you shut down your PC the script that runs "setserial" at boot-time is run again, but this time it only does what the part for the "stop" case says to do: It uses "setserial" to find out what the current state of "setserial" is, and it puts that info into the serial.conf file. Thus when you run "setserial" to change the serial.conf file, it doesn't get changed immediately but only when and if you shut down normally.

Now you can perhaps guess what problems might occur. Suppose you don't shut down normally (someone turns the power off, etc.) and the changes don't get saved. Suppose you experiment with "setserial" and forget to run it a final time to restore the original state (or make a mistake in restoring the original state). Then your "experimental" settings are saved.

If you manually edit serial.conf, then your editing is destroyed when you shut down because it gets changed back to the state of setserial at shutdown. There is a way to disable the changing of serial.conf at shutdown and that is to remove "###AUTOSAVE###" or the like from first line of serial.conf. In at least one distribution, the removal of "###AUTOSAVE###" from the first line is automatically done after the first time you shutdown just after installation. The serial.conf file should contain some comments to explain this.

The file most commonly used to run setserial at boot-time (in conformance with the configuration file) is now /etc/init.d/setserial (Debian) or /etc/init.d/serial (Redhat), or etc., but it should not normally be edited. For 2.15, Redhat 6.0 just had a file /usr/doc/setserial-2.15/rc.serial which you have to move to /etc/init.d/ if you want setserial to run at boot-time.

To disable a port, use setserial to set it to "uart none". The format of /etc/serial.conf appears to be just like that of the parameters placed after "setserial" on the command line with one line for each port. If you don't use autosave, you may edit /etc/serial.conf manually.

BUG: As of July 1999 there is a bug/problem since with ###AUTOSAVE### only the setserial parameters displayed by "setserial -Gg /dev/ttyS*" get saved but the other parameters don't get saved. Use the -a flag to "setserial" to see all parameters. This will only affect a small minority of users since the defaults for the parameters not saved are usually OK for most situations. It's been reported as a bug and may be fixed by now.

In order to force the current settings set by setserial to be saved to the configuration file (serial.conf) without shutting down, do what normally happens when you shutdown: Run the shell-script /etc/init.d/{set}serial stop. The "stop" command will save the current configuration but the serial ports still keep working OK.

In some cases you may wind up with both the old and new configuration methods installed but hopefully only one of them runs at boot-time. Debian labeled obsolete files with "...pre-2.15".

IRQs

By default, both ttyS0 and ttyS2 will share IRQ 4, while ttyS1 and ttyS3 share IRQ 3. But actually sharing serial interrupts (using them in running programs) is not permitted unless you: 1. have kernel 2.2 or better, and 2. you've complied in support for this, and 3. your serial hardware supports it. See Serial-HOWTO: Interrupt sharing and Kernels 2.2+.

If you only have two serial ports, ttyS0 and ttyS1, you're still OK since IRQ sharing conflicts don't exist for non-existent devices.

If you add an internal modem and retain ttyS0 and ttyS1, then you should attempt to find an unused IRQ and set it both on your serial port (or modem card) and then use setserial to assign it to your device driver. If IRQ 5 is not being used for a sound card, this may be one you can use for a modem. To set the IRQ in hardware you may need to use isapnp, a PnP BIOS, or patch Linux to make it PnP. To help you determine which spare IRQ's you might have, type "man setserial" and search for say: "IRQ 11".

Laptops: PCMCIA

If you have a Laptop, read PCMCIA-HOWTO for info on the serial configuration. For serial ports on the motherboard, setserial is used just like it is for a desktop. But for PCMCIA cards (such as a modem) it's a different story. The configuring of the PCMCIA system should automatically run setserial so you shouldn't need to run it. If you you do run it (by a script file or by /etc/serial.conf) it might be different and cause trouble. The autosave feature for serial.conf shouldn't save anything for PCMCIA cards (but Debian did until 2.15-7). Of course, it's always OK to use setserial to find out how the driver is configured for PCMCIA cards.

14.4 Stty

Introduction

stty does much of the configuration of the serial port but since application programs (and the getty program) often handle it, you may not need to use it much. It's handy if your having problems or want to see how the port is set up. Try typing ``stty -a'' at your terminal/console to see how it's now set. Also try typing it without the -a (all) for a short listing which shows how it's set different than normal. Don't try to learn all the setting unless you want to become a serial guru. Most of the defaults should work OK and some of the settings are needed only for certain obsolete dumb terminals made in the 1970's.

stty is documented in the man pages with a more detailed account in the info pages. Type "man stty" or "info stty".

Whereas setserial only deals with actual serial ports, stty is used both for serial ports and for virtual terminals such as the standard Linux text interface at a PC monitor. For the PC monitor, many of the stty settings are meaningless. Changing the baud rate, etc. doesn't appear to actually do anything.

Here are some of the items stty configures: speed (bits/sec), parity, bits/byte, # of stop bits, strip 8th bit?, modem control signals, flow control, break signal, end-of-line markers, change case, padding, beep if buffer overrun?, echo what you type to the screen, allow background tasks to write to terminal?, define special (control) characters (such as what key to press for interrupt). See the stty man or info page for more details. Also see the man page: termios which covers the same options set by stty but (as of mid 1999) covers features which the stty man page fails to mention.

With some implementations of getty (getty_ps package), the commands that one would normally give to stty are typed into a getty configuration file: /etc/gettydefs. Even without this configuration file, the getty command line may be sufficient to set things up so that you don't need stty."')

One may write C programs which change the stty configuration, etc. Looking at some of the documentation for this may help one better understand the use of the stty command (and its many possible arguments). Serial-Programming-HOWTO is useful. The manual page: termios contains a description of the C-language structure (of type termios) which stores the stty configuration in computer memory. Many of the flag names in this C-structure are almost the same (and do the same thing) as the arguments to the stty command.

Flow control options

To set hardware flow control use "crtscts". For software flow control there are 3 settings: ixon, ixoff, and ixany.

ixany: Mainly for terminals. Hitting any key will restarts the flow after a flow-control stop. If you stop scrolling with the "stop scroll" key (or the like) then hitting any key will resume scrolling. It's seldom needed since hitting the "scroll lock" key again will do the same thing.

ixon: Enables the port to listen for Xoff and to stop transmitting when it gets an Xoff. Likewise, it will resume transmitting if it gets an Xon.

ixoff: enables the port to send the Xoff signal out the transmit line when its buffers in main memory are nearly full. It protects the device where the port is located from being overrun.

For a slow dumb terminal (or other slow device) connected to a fast PC, it's unlikely the the PC's port will be overrun. So you seldom actually need to enable ixoff. But it's often enabled "just in case".

Using stty at a "foreign" terminal

Using stty to configure the terminal that you are currently using is easy. Doing it for a different (foreign) terminal or serial port may be impossible. For example, let's say you are at the PC monitor (tty1) and want to use stty to deal with the serial port ttyS2. Prior to about 2000 you needed to use the redirection operator "<". After 2000 (provided your version of setserial is >= 1.17 and stty >= 2.0) there is a better method using the -F option. This will work when the old redirection method fails. Even with the latest versions be warned that if there is a terminal on ttyS2 and a shell is running on that terminal, then what you see will likely be deceptive and trying to set it will not work. See Two interfaces at a terminal to understand it.

The new method is ``stty -F /dev/ttyS2 ...'' (or --file instead of F). If ... is -a it displays all the stty settings. The old redirection method (which still works in later versions) is to type ``stty ... </dev/ttyS2''. If the new method works but the old one hangs, it implies that the port is hung due to a modem control line not being asserted. Thus the old method is still useful for troubleshooting. See the following subsection for details.

Old redirection method

Here's a problem with the old redirection operator (which doesn't happen if you use the newer -F option instead). Sometimes when trying to use stty, the command hangs and nothing happens (you don't get a prompt for a next command even after hitting <return>). This is likely due to the port being stuck because it's waiting for one of the modem control lines to be asserted. For example, unless you've set "clocal" to ignore modem control lines, then if no CD signal is asserted the port will not open and stty will not work for it (unless you use the newer -F option). A similar situation seems to exist for hardware flow control. If the cable for the port doesn't even have a conductor for the pin that needs to be asserted then there is no easy way to stop the hang.

One way to try to get out of the above hang is to use the newer -F option and set "clocal" and/or "crtscts" as needed. If you don't have the -F option then you may try to run some program (such a minicom) on the port that will force it to operate even if the control lines say not to. Then hopefully this program might set the port so it doesn't need the control signal in the future in order to open: clocal or -crtscts. To use "minicom" to do this you likely will have to reconfigure minicom and then exit it and restart it. Instead of all this bother, it may be simpler to just reboot the PC.

The old redirection method makes ttyS2 the standard input to stty. This gives the stty program a link to the "file" ttyS2 so that it may "read" it. But instead of reading the bytes sent to ttyS2 as one might expect, it uses the link to find the configuration settings of the port so that it may read or change them. Some people tried to use ``stty ... > /dev/ttyS2'' to set the terminal. This will not do it. Instead, it takes the message normal displayed by the stty command for the terminal you are on (say tty1) and sends this message to ttyS2. But it doesn't change any settings for ttyS2.

Two interfaces at a terminal

When using a shell (such as bash) with command-line-editing enabled there are two different terminal interfaces (what you see when you type stty -a). When you type in modern shells at the command line you have a temporary "raw" interface (or raw mode) where each character is read by the command-line-editor as you type it. Once you hit the <return> key, the command-line-editor is exited and the terminal interface is changed to the nominal "cooked" interface (cooked mode) for the terminal. This cooked mode lasts until the next prompt is sent to the terminal (which is only a small fraction of a second). Note that one never gets to type anything to this cooked mode but what was typed in raw mode gets executed while in cooked mode.

When a prompt is sent to the terminal, the terminal goes from "cooked" to "raw" mode (just like it does when you start an editor since you are starting the command-line editor). The settings for the "raw" mode are based only on the basic settings taken from the "cooked" mode. Raw mode keeps these setting but changes several other settings in order to change the mode to "raw". It is not at all based on the settings used in the previous "raw" mode. Thus if one uses stty to change settings for the raw mode, such settings will be permanently lost as soon as one hits the <return> key at the terminal that has supposedly been "set".

Now when one types stty to look at the terminal interface, one may either get a view of the cooked mode or the raw mode. You need to figure out which one you're looking at. It you use stty from another (foreign) terminal then you will see the raw mode settings. Any changes made will only be made to the raw mode and will be lost when someone presses <return> at the terminal you tried to "set". But if you type a stty command at your terminal (without the -F option or redirection) and then hit <return> it's a different story. The <return> puts the terminal in cooked mode. Your changes are saved and will still be there when the terminal goes back into raw mode (unless of course it's a setting not allowed in raw mode).

This situation can create problems. For example, suppose you corrupt your terminal interface. To restore it you go to another terminal and "stty -F dev/ttyS1 sane" (or the like). It will not work! Of course you can try to type "stty sane ..." at the terminal that is corrupted but you can't see what you typed. All the above not only applies to dumb terminals but to virtual terminals used on a PC Monitor as well as to the terminal windows in X. In other words, it applies to almost everyone who uses Linux.

Luckily, when you start up Linux, any file that runs stty at boot-time will likely deal with a terminal (or serial port with no terminal) that has no shell running on it so there's no problem for this special case.

Where to put the stty command ?

Should you need to have stty set up the serial interface each time the computer starts up then you need to put the stty command in a file that will be executed each time the computer is started up (Linux boots). It should be run before the serial port is used (including running getty on the port). There are many possible places to put it. If it gets put in more than one place and you only know about (or remember) one of those places, then a conflict is likely. So make sure to document what you do.

One place to put it would be in the same file that runs setserial when the system is booted. The location is distribution and version dependent. It would seem best to put it after the setserial command so that the low level stuff is done first. If you have directories in the /etc tree where every file in them is executed at boot-time (System V Init) then you could create a file named "stty" for this purpose.

14.5 Terminfo & Termcap (brief)

See Terminfo and Termcap (detailed) for a more detailed discussion of termcap. Many application programs that you run use the terminfo (formerly termcap) data base. This has an entry (or file) for each model or type (such as vt100) of terminal and tells what the terminal can do, what codes to send for various actions, and what codes to send to the terminal to initialize it.

Since many terminals (and PC's also) can emulate other terminals and have various "modes" of operation, there may be several terminfo entries from which to choose for a given physical terminal. They usually will have similar names. The last parameter of getty (for both agetty and getty_ps) should be the terminfo name of the terminal (or terminal emulation) that you are using (such as vt100).

The terminfo does more than just specify what the terminal is capable of doing and disclose what codes to send to the terminal to get it to do those things. It also specifies what "bold" will look like (will it be reverse video or will it be high intensity, etc.), what the cursor will look like, if the letters will be black, white, or some other color, etc. In PC terminology these are called "preferences". It also specifies initialization codes to send to the terminal (analogous to the init strings sent to modems). Such strings are not automatically sent to the terminal by Linux. See Init String. If you don't like the way the display on the screen looks and behaves you may need to edit (and then update) the terminfo (or termcap) file. See Terminfo Compiler (tic) for how to update.

14.6 Setting TERM and TERMINFO

These are two environment variables for terminals: TERM and TERMINFO, but you may not need to do anything about them. TERM must always be set to the type of the terminal you are using (such as vt100). If you don't know the type (name) see What is the terminfo name of my terminal ?. TERMINFO contains the path to the terminfo data base, but may not be needed if the database is in a default location (or TERMINFO could be set automatically by a file that comes with your distribution of Linux). You may want to look at Compiled database locations.

Fortunately, the getty program usually sets TERM for you just before login. It just uses the terminal type that was specified on getty's command line (in /etc/inittab). This permits application programs to find the name of your terminal and then look up the terminal capabilities in the terminfo data base. See TERM Variable for more details on TERM.

If your terminfo data base can't be found you may see an error message about it on your terminal. If this happens it's time to check out where terminfo resides and set TERMINFO if needed. You may find out where the terminfo database is by searching for a common terminfo file such as "vt100" using the "locate" command. Make sure that your terminal is in this database. An example of setting TERMINFO is: export TERMINFO=/usr/share/terminfo (put this in /etc/profile or the like). If the data for your terminal in this data base is not to your liking, you may need to edit it. See Terminfo & Termcap (brief).

What is the terminfo name of my terminal ?

You need the exact name in order to set the TERM environment variable or to give to getty. The same name should be used by both the termcap and terminfo databases so you only need to find it once. A terminal usually has alias names but if more than one name is shown, use the first one.

To find it, try looking at the /etc/termcap... file (if you have it). If not, then either look at the terminfo trees (see Compiled database locations) or try to find the terminfo source code file (see Source-code database locations.

14.7 Rarely Needed /etc/ttytype File

The configuration file /etc/ttytype is used to map /dev/ttySn's to terminal names per terminfo. tset uses it, but if the TERM environment variable is already set correctly, then this file is not needed. Since the Linux getty sets TERM for each tty, you don't need this file. In other Unix-like systems such as FreeBSD, the file /etc/ttys maps ttys to much more, such as the appropriate getty command, and the category of connection (such as "dialup"). An example line of Linux ttytype: vt220 ttyS1

14.8 Login Restrictions

By default, the root user may not login from a terminal. To permit this you must create (or edit) the file /etc/securetty per the manual page "securetty". To restrict logins of certain users and/or certain terminals, etc. edit /etc/login.access (this replaces the old /etc/usertty file ??). /etc/login.def determines if /etc/securetty is to be used and could be edited so as to make /etc/securetty not needed (or not used). /etc/porttime restricts the times at which certain ttys and users may use the computer. If there are too many failed login attempt by a user, that user may be prohibited from ever logging in again. See the man page "faillog" for how to control this.

14.9 Run Command Only If TERM=my_term_type

Sometimes there are commands that one wants to execute at start-up only for a certain type of terminal. To do this for the stty command is no problem since one uses the redirection operator < to specify which terminal the command is for. But what about shell aliases or functions? You may want to make a function for the ls command so it will color-code the listing of directories only on color terminals or consoles. For monochrome terminals you want the same function name (but a different function body) which will use symbols as a substitute for color-coding. Where to put such function definitions that are to be different for different terminals?

You may put them inside an "if" statement in /etc/profile which runs at startup each time one logs on. The conditional "if" statement defines certain functions, etc. only if the terminal is of a specified type.

Example for ls Function

While much of what this if statement does could be done in the configuration file for dircolors, here's an example for the case of the bash shell:

if [ "$TERM" = linux ]; then
    eval `dircolors`;
elif [ "$TERM" = vt220 ]; then
    ls () { command ls -F $* ; }# to export the function ls():
    declare -xf ls
else echo "From /etc/profile: Unknown terminal type $TERM"
fi

14.10 Character Mapping: mapchan

There is a program named "mapchan" which will map characters (bytes) typed at a terminal keyboard (input) into different characters per a user-supplied mapping table. It can also map characters which are sent to the screen (output). This is nice for remapping the keyboard for foreign language alphabets. Most distributions don't seem to supply it (let me know if any do). Source code by Yura Kalinichenko (Ukraine) is at http://www.kron.vinnica.ua/free/download/