---
name: "read"
section: "3tcl"
platform: "linux"
package: "tcl8.6-doc"
version: "8.6.16+dfsg-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/read/3tcl"
---

# read(3tcl)

Read from a channel

```

```

## NAME

read - Read from a channel

## SYNOPSIS

**read** ?**-nonewline**? *channelId*

**read** *channelId numChars*

```

```

## DESCRIPTION

In the first form, the **read** command reads all of the data from *channelId* up to the end of the file.  If the **-nonewline** switch is specified then the last character of the file is discarded if it is a newline.  In the second form, the extra argument specifies how many characters to read.  Exactly that many characters will be read and returned, unless there are fewer than *numChars* left in the file; in this case all the remaining characters are returned.  If the channel is configured to use a multi-byte encoding, then the number of characters read may not be the same as the number of bytes read.

*ChannelId* must be an identifier for an open channel such as the Tcl standard input channel (**stdin**), the return value from an invocation of **open** or **socket**, or the result of a channel creation command provided by a Tcl extension. The channel must have been opened for input.

If *channelId* is in nonblocking mode, the command may not read as many characters as requested: once all available input has been read, the command will return the data that is available rather than blocking for more input.  If the channel is configured to use a multi-byte encoding, then there may actually be some bytes remaining in the internal buffers that do not form a complete character.  These bytes will not be returned until a complete character is available or end-of-file is reached.  The **-nonewline** switch is ignored if the command returns before reaching the end of the file.

**Read** translates end-of-line sequences in the input into newline characters according to the **-translation** option for the channel. See the **fconfigure** manual entry for a discussion on ways in which **fconfigure** will alter input.

## USE WITH SERIAL PORTS

For most applications a channel connected to a serial port should be configured to be nonblocking: **fconfigure** *channelId* **-blocking** *0*.  Then **read** behaves much like described above.  Care must be taken when using **read** on blocking serial ports:

- **read** *channelId numChars*

  In this form **read** blocks until *numChars* have been received from the serial port.

- **read** *channelId*

  In this form **read** blocks until the reception of the end-of-file character, see **fconfigure** **-eofchar**. If there no end-of-file character has been configured for the channel, then **read** will block forever.

## EXAMPLE

This example code reads a file all at once, and splits it into a list, with each line in the file corresponding to an element in the list:

```
set fl [open /proc/meminfo]
set data [read $fl]
close $fl
set lines [split $data \n]
```

## SEE ALSO

[file(3tcl)](/file/3tcl.md), [eof(3tcl)](/eof/3tcl.md), [fblocked(3tcl)](/fblocked/3tcl.md), [fconfigure(3tcl)](/fconfigure/3tcl.md), [Tcl\_StandardChannels(3tcl)](/Tcl_StandardChannels/3tcl.md)

## KEYWORDS

blocking, channel, end of line, end of file, nonblocking, read, translation, encoding