---
name: "receive"
section: "3tcl"
platform: "linux"
package: "tcllib"
version: "2.0+dfsg-4"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/receive/3tcl"
---

# receive(3tcl)

General input from terminals

```

```

## NAME

term::receive - General input from terminals

## SYNOPSIS

package require **Tcl 8.5 9**

package require **term::receive ?0.2?**

**::term::receive::getch** ?*chan*?

**::term::receive::listen** *cmd* ?*chan*?

*cmd* **process** *string*

*cmd* **eof**

**::term::receive::unlisten** ?*chan*?

```

```

## DESCRIPTION

This package provides the most primitive commands for receiving characters to a terminal. They are in essence convenient wrappers around the builtin commands **read** and **fileevent**.

- **::term::receive::getch** ?*chan*?

  This command reads a single character from the channel with handle *chan* and returns it as the result of the command.

  If not specified *chan* defaults to **stdin**.

  It is the responsibility of the caller to make sure that the channel can provide single characters. On unix this can be done, for example, by using the command of package **term::ansi::ctrl::unix**.

- **::term::receive::listen** *cmd* ?*chan*?

  This command sets up a filevent listener for the channel with handle *chan* and invokes the command prefix *cmd* whenever characters have been received, or EOF was reached.

  If not specified *chan* defaults to **stdin**.

  The signature of the command prefix is

  - *cmd* **process** *string*

    This method is invoked when characters were received, and *string* holds them for processing.

  - *cmd* **eof**

    This method is invoked when EOF was reached on the channel we listen on.  It will be the last call to be received by the callback.

- **::term::receive::unlisten** ?*chan*?

  This command disables the filevent listener for the channel with handle *chan*.

  If not specified *chan* defaults to **stdin**.

## BUGS, IDEAS, FEEDBACK

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category *term* of the *Tcllib Trackers* \[http://core.tcl.tk/tcllib/reportlist\]. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide *unified diffs*, i.e the output of **diff -u**.

Note further that *attachments* are strongly preferred over inlined patches. Attachments can be made by going to the **Edit** form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

## KEYWORDS

character input, control, get character, listener, receiver, terminal

## CATEGORY

Terminal control

## COPYRIGHT

```
Copyright (c) 2006 Andreas Kupries <andreas_kupries@users.sourceforge.net>
```