# GET
> [HTML Version](get_sbr.htm)
_Updated March 2024; see History_
**xcall GET, buffer \{,chan, bytes'req, bytes'rcvd, timeout, flags\}**
GET is useful for simple or sophisticated input of raw characters from the keyboard or a file. Under Unix/Linux, it may also be used for [Inputting from a serial device](inputtingfromaserialdevice.htm.md). See [COMIO](comiosbr.htm.md) for serial I/O under Windows.
**Parameters**
_buffer _ ([String](string.htm.md), may be dynamic) \[out\]
receives the byte(s) input. Note that no trailing null byte is added by the subroutine, so you may want to pre-clear this variable before calling GET. In the simplest case of GET where no parameters beyond _buffer _are specified, it will input a single character from the keyboard, waiting as long as necessary.
_chan _([Num](num.htm.md)) \[in\] (optional)
File channel number of a file that has been opened for input, and from which the character(s) are to be read. If not specified, or zero, input is from the keyboard.
_bytes’requested _([Num](num.htm.md)) \[in\] (optional)
Number of bytes to input. If not specified, default is 1. You can specify 0 in conjunction with the timeout feature if you just want to know if a character is available without actually inputting it. Two special values are supported: -1 requests a line of input terminating with LF (and ignoring CR); -2 requests a line of input terminating with CR (and ignoring LF). Note that for the special values -1 and -2, the terminating CR and/or LF will not be included in _buffer_, but will be included in the count in _bytes'received_.
_bytes’ received _([Num](num.htm.md)) \[out\] (optional)
Returns the number of bytes that were actually input (and returned into the Buffer parameter). Normally this will be the same as _bytes’requested_, except in the following circumstances:
If _bytes’requested _was 0, then _bytes’received_ will be 1 if there was one or more characters available to be input, or 0 to indicate no characters available.
If we hit the end of the input file, or the _timeout _period expires before reading the number of requested bytes, then _bytes’received_ will be less than _bytes’requested_.
If an I/O error occurs, or if a _timeout_ period is specified and no characters are input because the file was already at the end-of-file mark, _bytes’received_ will be set to -1. This distinguishes the case of end-of-file from timeout.
When _bytes'requested_ is set to -1 or -2, _bytes'received_ will be set to the total number of bytes received, including the terminating character(s). However, the terminating characters (CR and/or LF) are not returned in _buffer_.
_timeout _([Num](num.htm.md)) \[in\] (optional)
Number of milliseconds to wait for input before aborting. If set to 0 or not specified, there is no timeout. Note that the actual elapsed time may be substantially longer that the specified period. This is both because of CPU time dedicated to other processes and because the total timeout period is actually divided into slices equal to the number of characters to be input, with each slice being used up only if no characters are available.
For example, if you have a 5000 millisecond (5 second) _timeout_ and are requesting 5 characters, then you will actually be allotted 5 one-second timeout periods, and each period is only spent if no characters are input during that period. If exactly one character arrived every 0.75 seconds, then you would still have five unused seconds after four characters had be input, even though three seconds had actually elapsed. This scheme may seem a bit strange, but is actually a reasonable compromise between the two extreme approaches of treating the timeout period as an absolute maximum or of resetting it entirely after each character.
**Note:** In order for the timeout to be reliable when inputting from a device such as a serial port, you must first disable buffering on the input channel (see [MX\_NOBUF](mx_no_flush_buf.htm.md)). Failure to do so could result in apparently flaky behavior, since the timeout mechanism may not be aware of buffered characters, thus leading to false timeouts.
_flags _([Num](num.htm.md)) \[in\] (optional)
| **Value** | **Description** |
|------|------|
| \&h01 | Raw mode. See notes below. |
| \&h02 | Convert CRLF to CR. |
Raw mode eliminates all input processing and filtering such as function key support, terminal driver input translations, and adds the ability to input null bytes. Otherwise, null bytes are stripped out of the input stream before your application gets a chance to see them. Note the following restrictions on the _flags _parameter:
• Under Unix, setting _flags_=1 and _bytes'req_=0 (in order to check if any characters are available without inputting anything) will properly return _bytes'rcvd_=1 if anything is available to input, but if the first byte available is a null, it will be lost. So it is best to just set _bytes'req_ to the number of bytes you want, and use timeout to avoid getting stuck in an input wait.
• Under Windows, input processing occurs asynchronously as characters arrive, not as they are requested by the application. So the _raw flag_ will only be useful if the XCALL GET occurs before the characters in question arrive.
**Comments**
• When inputting from the keyboard, NOECHO will be set automatically and left that way on exit.
• Function key translations are not processed by GET. Use [GETX](getx_sbr.htm.md) or [ACCEPT](acceptsbr.htm.md)[XS](keyword-types.htm.md) if you need that feature.
• GET may also be used to check if a character is available without waiting and without actually inputting the character, by setting _bytes’requested _and _timeout _to zero. This is equivalent to GETKEY(-2).
**See Also**
• [Accept, Accepn](acceptsbr.htm.md)[XS](keyword-types.htm.md)
• [GET](get_sbr.htm.md)[XS](keyword-types.htm.md) (keyboard or file input)
• Getkey[XS](keyword-types.htm.md)
• [Tinkey](tinkey_sbr.htm.md)[XS](keyword-types.htm.md)
**History**
2024 March, A-Shell 7.0.1757: Add _flags_ value \&h02.