---
name: "read"
section: "n"
platform: "macos"
package: "tcl"
version: "152"
release: "macOS 26.5"
platforms: ["linux", "macos"]
url: "https://new.carta.tech/read/n"
---

# read(n)

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(n)](/file/n.md), [eof(n)](/eof/n.md), [fblocked(n)](/fblocked/n.md), [fconfigure(n)](/fconfigure/n.md), [Tcl\_StandardChannels(3)](/Tcl_StandardChannels/3.md)

## KEYWORDS

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