GETTY(1m)

NAME
getty - sets terminal mode, speed, and line discipline

SYNOPSIS
/etc/getty [-d defaults_file] [-a] [-h] [-r delay] [-t timeout] [-w waitfor] line [speed [type [lined]]]
/etc/getty -c gettydefs_file

DESCRIPTION
Getty is the second of the three programs (init(1m), getty(1m), and login(1m)), used by the system to allow users to login. Getty is invoked by init(1m) to:

1.  Open tty lines and set their modes.

2.  Print the login prompt, and get the user's name.

3.  Initiate a login process for the user.

The actual procedure that getty follows is described below: Initially, getty parses its command line. If no errors are found, getty scans the defaults file (normally /etc/default/getty) to determine certain runtime values. The values in the defaults file (whose compiled-in name can be altered with the optional -d defaults_file argument) take precedence to those on the command line. Getty then opens the line for reading and writing, and disables stdio buffering. If an initialization was specified, it is performed (see LINE INITIALIZATION).

After the initialization, the line is closed and reopened. This time, however, the line is opened in blocking mode so that the device is not tied up. Detection of the carrier signal will allow the line to be opened.

Next, getty types the issue (or login banner, usually from /etc/issue) and login prompt. Finally, getty reads the user's login name and invokes login(1m) with the user's name as an argument. While reading the name, getty attempts to adapt the system to the speed of the terminal being used, and also sets certain terminal parameters (see termio(7)) to conform with the user's login procedure.

The tty device used by getty is determined by the line argument. Getty uses the string /dev/line as the name of the device to attach itself to. Unless getty is invoked with the -h flag (or HANGUP=NO is specified in the defaults file), it will force a hangup on the line by setting the speed to zero. Giving -r delay on the command line (or using WAITCHAR=YES and DELAY=delay in the defaults file) will cause getty to wait for a single character from the line, and then to wait delay seconds before continuing. If no delay is desired, use -r0. Giving -w waitfor on the command line (or using WAITFOR=waitfor in the defaults file) will cause getty to wait for the specified string of characters from the line before continuing. Giving -t timeout on the command line (or using TIMEOUT=timeout in the defaults file) will cause getty to exit if no user name is accepted within timeout seconds after the login prompt is typed.

The speed argument is a label to a entry in the /etc/gettydefs file (see gettydefs(4)). This entry defines to getty the initial speed (baud rate) and tty settings, the login prompt to be used, the final speed and tty settings, and a pointer to another entry to try should the user indicate that the speed is not correct. This is done by sending a <break> character (actually sequence). Under certain conditions, a carriage-return will perform the same function. This is usually the case when getty is set to a higher speed than the modem or terminal. Getty scans the gettydefs file sequentially looking for a matching entry. If no speed was given or the entry cannot be found, the first entry in the /etc/gettydefs file is used as a default. In the event that the gettydefs file cannot be accessed, there is a compiled-in default entry that is used.

The type argument is a string which names the type of terminal attached to the line. The type should be a valid terminal name listed in the termcap(7) database. Getty uses this value to determine how to clear the video display. It also sets the environment variable TERM to the contents of this value.

The lined argument is a string describing the line discipline to use on the line. The default is LDISC0.

As mentioned, getty types the login prompt and then reads the user's login name. If a null character is received, it is assumed to be the result of the user pressing the <break> key or the carriage-return key to indicate the speed is wrong. This causes getty to locate the next speed in the series (defined in /etc/gettydefs).

The user's name is terminated by a new-line or carriage-return character. A carriage-return results in the system being set to map those to new-lines (see ioctl(2)).

The user's name is scanned to see if it contains only upper-case characters. If so, the system is set to map any future upper-case characters into lower-case.

A check option is provided for testing the gettydefs file. When getty is invoked with the -cgettydefs option, it scans the named gettydefs file and prints out (to the standard output) the values it sees. If any parsing errors occur (due to errors in the syntax of the gettydefs file), they are reported.

DEFAULTS FILE
During its startup, getty looks for the file /etc/default/getty.line, (or, if it cannot find that file, then /etc/default/getty), and if found, reads the contents for lines of the form
NAME=value
This allows getty to have certain features configurable at runtime, without recompiling. The recognized NAME strings, and their corresponding values, follows:

SYSTEM=name
    Sets the nodename value (displayed by @S -- see PROMPT SUBSTITUTIONS) to name. The default is the nodename value returned by the uname(3) call. On XENIX systems, if the value of nodename is a zero-length string, the file /etc/systemid is examined to get the nodename. Note that some sites may have elected to compile the nodename value into getty.

VERSION=string
    Sets the value that is displayed by the @V parameter (see PROMPT SUBSTITUTIONS) to string. There is no default value. If string begins with a '/' character, it is assumed to be the full pathname of a file, and @V is set to be the contents of that file.

LOGIN=name
    Sets the name of the login program to name. The default is /bin/login (see login(1m)). If used, name must be the full pathname of the program that getty will execute instead of /bin/login. Note that this program is called, as is /bin/login, the with the user's name as its only argument.

INIT=string
    If defined, string is an expect/send sequence that is used to initialize the line before getty attempts to use it. This string is in a form resembling that used in the L.sys file of uucp(1). For more details, see LINE INITIALIZATION. By default, no initialization is done.

ISSUE=string
    During startup, getty defaults to displaying, as an issue or login banner, the contents of the /etc/issue file. If ISSUE is defined to a string, that string is typed instead. If string begins with a '/' character, it is assumed to be the full pathname of a file, and that file is used instead of /etc/issue.

CLEAR=value
    If value is NO, then getty will not attempt to clear the video screen before typing the issue or login prompts. The default is to clear the screen.

HANGUP=value
    If value is NO, then getty will NOT hangup the line during its startup. This is analogus to giving the -h argument on the command line.

WAITCHAR=value
    If value is YES, then getty will wait for a single character from it's line before continuing. This is useful for modem connections where the modem has CD forced high at all times, to keep getty from endlessly chatting with the modem.

DELAY=seconds
    Used in conjunction with WAITCHAR, this adds a time delay of seconds after the character is accepted before allowing getty to continue. Both WAITCHAR and DELAY have the same effect as specifying -rdelay on the command line. If WAITCHAR is given without a DELAY, the result is equal to having said -r0 on the command line. The default is to not wait for a character.

TIMEOUT=number
    As with the -t timeout command line argument, tells getty to exit if no user name is accepted before the number of seconds elapse after the login prompt is typed. The default is to wait indefinetly for the user name.

CONNECT=string
    If defined, string should be an expect/send sequence (like that for INIT) to direct getty in establishing the connection. String may be defined as DEFAULT, which will substitute the built-in string:
    CONNECT\s\A\r\n
    The \A escape marks the place where the digits showing the speed will be seen. See CONNECTION AND AUTOBAUDING for more details. The default is to not perform a connection chat sequence.

WAITFOR=string
    This parameter is similar to WAITCHAR, but defines a string of characters to be waited for. Getty will wait until string is received before issuing the login prompt. This parameter is best used when combined with CONNECT, as in this example:
    WAITFOR=RING
    CONNECT="" ATA\r CONNECT\s\A
    This would cause getty to wait for the string RING, then expect nothing, send ATA followed by a carriage-return, and then wait for a string such as CONNECT 2400, in which case, getty would set itself to 2400 baud. The default is not to wait for any string of characters.

ALTLOCK=line
    Uugetty uses this parameter to lock an alternate device, in addition to the one it is attached to. This is for those systems that have two different device names that refer to the same physical port; e.g. /dev/tty1A vs. /dev/tty1a, where one uses modem control and the other doesn't. See the section on UUGETTY for more details. The default is to have no alternate lockfile.

ALTLINE=line
    Getty uses this parameter to specify a different device to use for handling modem initialization. If the WAITFOR option is being used, WAITFOR will be done on this line also. This is necessary for systems that exercise locking between two lines.

RINGBACK=value
    If value is YES ringback callin is enabled. This is used in conjunction with WAITFOR and CONNECT to negotiate incoming calls. The default action is to connect only if the line rings one to three times, is hung up, and is called back within 60 seconds of the first call. MINRBTIME and MAKRBTIME specify the minimum and maximum time for the second call. INTERRING specifies the maximum time between two successive rings in the same call. MINRINGS and MAXRINGS specify the minimum and maximum number of rings for the first call.

SCHED=range1 range2 range3 ...
    Getty uses this line to schedule times to allow logins. Each range has the form DOW:HR:MIN-DOW:HR:MIN. DOW is the day of the week. 0 = Sunday, 1 = Monday, ... 6 = Saturday. HR is the hour, and MIN is the minute. If the current time falls into one of these ranges, the INIT sequence (if any) is sent and getty continues to run until the off time. Otherwise, the OFF sequence is sent, and getty sleeps until the off time.

OFF=string
    This line is identical to the INIT line, except it is only sent when the line is scheduled to be OFF.

The name of the defaults file can be changed by specifying -d defaults_file on the command line. If defaults_file begins with a slash, it is assumed to be a complete pathname of the defaults file to be used. Otherwise, it is assumed to be a regular filename, causing getty to use the pathname /etc/default/defaults_file.

PROMPT SUBSTITUTIONS
When getty is typing the issue or login banner (ususally /etc/issue), or the login-prompt, it recognizes several escape (quoted) characters. When one of these quoted characters is found, its value is substituted in the output produced by getty. Recognized escape characters are:

\\  Backslash (\).

\b  Backspace (^H).

\c  Placed at the end of a string, this prevents a new-line from being typed after the string.

\f  Formfeed (^L).

\n  New-line (^J).

\r  Carriage-return (^M).

\s  A single space (' ').

\t  Horizontal tab (^I).

\nnn
    Outputs the ASCII character whose decimal value is nnn. If nnn begins with 0, the value is taken to be in octal. If it begins with 0x, the value is taken to be in hexidecimal.

In addition, a single backslash at the end of a line causes the immediately following new-line to be ignored, allowing continuation lines.

Also, certain @char parameters are recognized. Those parameters, and the value that is substituted for them are:

@B  The current (evaluated at the time the @B is seen) baud rate.

@D  The current date, in MM/DD/YY .

@L  The line to which getty is attached.

@S  The system node 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 '@@'.

LINE INITIALIZATION
One of the greatest benefits (in the author's opinion, at least) is the ability of getty to initialize its line before use. This will most likely be done on lines with modems, not terminals, although initializing terminals is not out of the question.

Line initialization is performed just after the line is opened and prior to handling the WAITCHAR and/or WAITFOR options. Initialization is accomplished by placing an
INIT=string
line in the defaults file. String is a series of one or more fields in the form
expect [ send [ expect [ send ] ] ... ]
This resembles the expect/send sequences used in the UUCP L.sys file, with the following exception: A carriage return is NOT appended automatically to sequences that are 'sent.' If you want a carriage-return sent, you must explicitly show it, with '\r'.

Getty supports subfields in the expect field of the form
expect[-send-expect]...
as with UUCP. All the escape characters (those beginning with a '\' character) listed in the PROMPT SUBSTITUTIONS section are valid in the send and expect fields. In addition, the following escape characters are recognized:

\p  Inserts a 1-second delay.

\d  Inserts a 2-second delay.

\K  Sends a .25-second Break.

\Tnnn
    Modifies the default timeout (usually 30 seconds) to the value indicated by nnn. The value nnn may be decimal, octal, or hexidecimal; see the usage of \nnn in PROMPT SUBSTITUTIONS.

Note that for these additional escape characters, no actual character is sent.

CONNECTION AND AUTOBAUDING
Getty will perform a chat sequence establish a proper connection. The best use of this feature is to look for the CONNECT message sent by a modem and set the line speed to the number given in that message (e.g. CONNECT 2400).

The for the connect chat script is exactly the same as that for the INIT script (see LINE INITIALIZATION), with the following addition:

\A  Marks the spot where the baud rate will be seen. This mark will match any and all digits 0-9 at that location in the script, and set it's speed to that value, if possible.

Autobauding, therefore, is enabled by placing the \A mark in the chat script. For example, the definition:
CONNECT=CONNECT\s\A
would match the string CONNECT 1200 and cause getty to set it's baud rate to 1200, using the following steps:

1.  Having matched the value 1200, getty will attempt to find an entry with the label 1200 in the gettydefs file. If a matching gettydefs entry is found, those values are used. If there is no match, then

2.  The gettydefs values currently in use are modified to use the matched speed (e.g. 1200). However, if the matched speed is invalid, then

3.  Getty logs a warning message and resumes normal operation. This allows the practice of toggling through linked entries in the gettydefs file to behave as expected.

UUGETTY
Uugetty has identical behavior to getty, except that uugetty is designed to create and use the lock files maintained by the UUCP family (uucp(1), cu(1) and others). This prevents two or more processes from having conficting use of a tty line.

When uugetty starts up, if it sees a lock file on the line it intends to use, it will use the pid in the lock file to see if there is an active process holding the lock. If not, uugetty will remove the lock file and continue. If a valid process is found, uugetty will sleep until that process releases the lock and then it will exit, forcing init(1m) to spawn a new uugetty. Once no conflicting process is found, uugetty grabs the line by creating the lock file itself before issuing the login prompt. This prevents other processes from using the line.

Uugetty will normally only lock the name of the line it is running on. On systems where there are two device names referring to the same port (as is the case where one device uses modem control while the other doesn't), place a line of the form
ALTLOCK=line
line in the defaults file. For instance, if uugetty is on /dev/tty1a, and you want to have it lock /dev/tty1A also, use the line ALTLOCK=tty1A in the defaults file.

While waiting for carrier detect, Uugetty will check for lockfiles every 30 seconds. If lockfiles are found, uugetty will exit, and init will respawn another getty. This allows the modem to be reinitialized after another process has used the modem.

FILES

/usr/adm/getty.log
    The file to which errors are logged.

/etc/default/getty[.line]
    Contains the runtime configuration. Note that uugetty uses /etc/default/uugetty[.line].

/etc/gettydefs
    Contains speed and tty settings to be used by getty.

/etc/issue
    The default issue (or login banner).

/bin/login
    The default login program called after the user's name is entered.

SEE ALSO
init(1m), login(1m), uucp(1), ioctl(2), uname(3), gettydefs(5), utmp(5), termio(7)

AUTHOR
Paul Sutcliffe, Jr.  <paul@devon.lns.pa.us>
UUCP: ...!rutgers!devon!paul
Autobauding routines adapted from code submitted by
Mark Keating <...!utzoo!censor!markk>