Bash manual read

Redirection on its own isn't very useful, so in this example, I also use the built-in echo command to print the results of the redirect:. For each line in the include. Piping it first to an appropriate parser is a common way to read data with Bash. For instance, assume for a moment that include.

You could obtain values with awk or even cut :. Whether you're storing data your user created with your application or just metadata about what the user did in an application for instance, game saves or recent songs played , there are many good reasons to store data for later use. In Bash, you can save data to files using common shell redirection.

Bash excels at being easy to learn because, with just a few basic concepts, you can build complex programs. For the full documentation, refer to the excellent Bash documentation on GNU. Read and write files with Bash Opensource. Learn the different ways Bash reads and writes data and when to use each method. Image by :. Get the highlights in your inbox every week. Install Bash Programming and development. Learn Bash by writing an interactive game. Programming a simple game is a great way to practice a new language and compare it against others you know.

Display current Readline see Command Line Editing key and function bindings, bind a key sequence to a Readline function or macro, or set a Readline variable. Each non-option argument is a command as it would appear in a Readline initialization file see Readline Init File , but each binding or command must be passed as a separate argument; e.

Use keymap as the keymap to be affected by the subsequent bindings. Acceptable keymap names are emacs , emacs-standard , emacs-meta , emacs-ctlx , vi , vi-move , vi-command , and vi-insert. Display Readline function names and bindings in such a way that they can be used as input or in a Readline initialization file.

Display Readline variable names and values in such a way that they can be used as input or in a Readline initialization file. Display Readline key sequences bound to macros and the strings they output in such a way that they can be used as input or in a Readline initialization file.

Cause shell-command to be executed whenever keyseq is entered. List all key sequences bound to shell commands and the associated commands in a format that can be reused as input. Run a shell builtin, passing it args , and return its exit status.

This is useful when defining a shell function with the same name as a shell builtin, retaining the functionality of the builtin within the function. The return status is non-zero if shell-builtin is not a shell builtin command.

Returns the context of any active subroutine call a shell function or a script executed with the. Without expr , caller displays the line number and source filename of the current subroutine call. If a non-negative integer is supplied as expr , caller displays the line number, subroutine name, and source file corresponding to that position in the current execution call stack.

This extra information may be used, for example, to print a stack trace. The current frame is frame 0. The return value is 0 unless the shell is not executing a subroutine call or expr does not correspond to a valid position in the call stack.

Runs command with arguments ignoring any shell function named command. Only shell builtin commands or commands found by searching the PATH are executed. The -p option means to use a default value for PATH that is guaranteed to find all of the standard utilities.

The return status in this case is if command cannot be found or an error occurred, and the exit status of command otherwise. If either the -V or -v option is supplied, a description of command is printed.

The -v option causes a single word indicating the command or file name used to invoke command to be displayed; the -V option produces a more verbose description. In this case, the return status is zero if command is found, and non-zero if not.

Declare variables and give them attributes. If no name s are given, then display the values of variables instead. The -p option will display the attributes and values of each name. When -p is used with name arguments, additional options, other than -f and -F , are ignored. When -p is supplied without name arguments, declare will display the attributes and values of all variables having the attributes specified by the additional options. If no other options are supplied with -p , declare will display the attributes and values of all shell variables.

The -f option will restrict the display to shell functions. The -F option inhibits the display of function definitions; only the function name and attributes are printed. If the extdebug shell option is enabled using shopt see The Shopt Builtin , the source file name and line number where each name is defined are displayed as well.

The -g option forces variables to be created or modified at the global scope, even when declare is executed in a shell function. It is ignored in all other cases. The -I option causes local variables to inherit the attributes except the nameref attribute and value of any existing variable with the same name at a surrounding scope. If there is no existing variable, the local variable is initially unset.

The following options can be used to restrict output to variables with the specified attributes or to give variables attributes:. The variable is to be treated as an integer; arithmetic evaluation see Shell Arithmetic is performed when the variable is assigned a value. When the variable is assigned a value, all upper-case characters are converted to lower-case. The upper-case attribute is disabled. Give each name the nameref attribute, making it a name reference to another variable. That other variable is defined by the value of name.

The nameref attribute cannot be applied to array variables. Make name s readonly. These names cannot then be assigned values by subsequent assignment statements or unset. Give each name the trace attribute. The trace attribute has no special meaning for variables. When the variable is assigned a value, all lower-case characters are converted to upper-case. The lower-case attribute is disabled. When used in a function, declare makes each name local, as with the local command, unless the -g option is used.

When using -a or -A and the compound assignment syntax to create array variables, additional attributes do not take effect until subsequent assignments. Output the arg s, separated by spaces, terminated with a newline. The return status is 0 unless a write error occurs.

If -n is specified, the trailing newline is suppressed. If the -e option is given, interpretation of the following backslash-escaped characters is enabled. The -E option disables the interpretation of these escape characters, even on systems where they are interpreted by default. Enable and disable builtin shell commands. Disabling a builtin allows a disk command which has the same name as a shell builtin to be executed without specifying a full pathname, even though the shell normally searches for builtins before disk commands.

If -n is used, the name s become disabled. Otherwise name s are enabled. If the -p option is supplied, or no name arguments appear, a list of shell builtins is printed. With no other arguments, the list consists of all enabled shell builtins. The -a option means to list each builtin with an indication of whether or not it is enabled. The -f option means to load the new builtin command name from shared object filename , on systems that support dynamic loading.

The -d option will delete a builtin loaded with -f. If there are no options, a list of the shell builtins is displayed. If -s is used with -f , the new builtin becomes a special builtin see Special Builtins. The return status is zero unless a name is not a shell builtin or there is an error loading a new builtin from a shared object. Display helpful information about builtin commands. If pattern is specified, help gives detailed help on all commands matching pattern , otherwise a list of the builtins is printed.

The let builtin allows arithmetic to be performed on shell variables. Each expression is evaluated according to the rules given below in Shell Arithmetic. If the last expression evaluates to 0, let returns 1; otherwise 0 is returned.

For each argument, a local variable named name is created, and assigned value. The option can be any of the options accepted by declare. The restore is effected as if a series of set commands were executed to restore the values that were in place before the function. The return status is zero unless local is used outside a function, an invalid name is supplied, or name is a readonly variable.

Read lines from the standard input into the indexed array variable array , or from file descriptor fd if the -u option is supplied. Options, if supplied, have the following meanings:. The first character of delim is used to terminate each input line, rather than newline. If delim is the empty string, mapfile will terminate a line when it reads a NUL character. Evaluate callback each time quantum lines are read.

The -c option specifies quantum. If -C is specified without -c , the default quantum is When callback is evaluated, it is supplied the index of the next array element to be assigned and the line to be assigned to that element as additional arguments. If not supplied with an explicit origin, mapfile will clear array before assigning to it. Write the formatted arguments to the standard output under the control of the format. The -v option causes the output to be assigned to the variable var rather than being printed to the standard output.

The format is a character string which contains three types of objects: plain characters, which are simply copied to standard output, character escape sequences, which are converted and copied to the standard output, and format specifications, each of which causes printing of the next successive argument. In addition to the standard printf 1 formats, printf interprets the following extensions:.

Causes printf to expand backslash escape sequences in the corresponding argument in the same way as echo -e see Bash Builtins. Causes printf to output the corresponding argument in a format that can be reused as shell input. Causes printf to output the date-time string resulting from using datefmt as a format string for strftime 3. The corresponding argument is an integer representing the number of seconds since the epoch. Two special argument values may be used: -1 represents the current time, and -2 represents the time the shell was invoked.

If no argument is specified, conversion behaves as if -1 had been given. This is an exception to the usual printf behavior. Arguments to non-string format specifiers are treated as C language constants, except that a leading plus or minus sign is allowed, and if the leading character is a single or double quote, the value is the ASCII value of the following character.

The format is reused as necessary to consume all of the arguments. If the format requires more arguments than are supplied, the extra format specifications behave as if a zero value or null string, as appropriate, had been supplied. The return value is zero on success, non-zero on failure. One line is read from the standard input, or from the file descriptor fd supplied as an argument to the -u option, split into words as described above in Word Splitting , and the first word is assigned to the first name , the second word to the second name , and so on.

If there are more words than names, the remaining words and their intervening delimiters are assigned to the last name. If there are fewer words read from the input stream than names, the remaining names are assigned empty values.

The characters in the value of the IFS variable are used to split the line into words using the same rules the shell uses for expansion described above in Word Splitting.

The words are assigned to sequential indices of the array variable aname , starting at 0. All elements are removed from aname before the assignment. Other name arguments are ignored. The first character of delim is used to terminate the input line, rather than newline.

If delim is the empty string, read will terminate a line when it reads a NUL character. Readline see Command Line Editing is used to obtain the line.

If Readline is being used to read the line, text is placed into the editing buffer before editing begins. Delimiter characters encountered in the input are not treated specially and do not cause read to return until nchars characters are read. The result is not split on the characters in IFS ; the intent is that the variable is assigned exactly the characters read with the exception of backslash; see the -r option below.

Display prompt , without a trailing newline, before attempting to read any input. The prompt is displayed only if input is coming from a terminal.

If this option is given, backslash does not act as an escape character. The backslash is considered to be part of the line. In particular, a backslash-newline pair may not then be used as a line continuation. Cause read to time out and return failure if a complete line of input or a specified number of characters is not read within timeout seconds.

This option is only effective if read is reading input from a terminal, pipe, or other special file; it has no effect when reading from regular files. If read times out, read saves any partial input read into the specified variable name. If timeout is 0, read returns immediately, without trying to read any data. The exit status is 0 if input is available on the specified file descriptor, non-zero otherwise. The exit status is greater than if the timeout is exceeded.

If no name s are supplied, the line read, without the ending delimiter but otherwise unmodified, is assigned to the variable REPLY. The exit status is zero, unless end-of-file is encountered, read times out in which case the status is greater than , a variable assignment error such as assigning to a readonly variable occurs, or an invalid file descriptor is supplied as the argument to -u. If the name is not found, then nothing is printed, and type returns a failure status. If the -a option is used, type returns all of the places that contain an executable named file.

This includes aliases and functions, if and only if the -p option is not also used. If the -f option is used, type does not attempt to find shell functions, as with the command builtin. The return status is zero if all of the names are found, non-zero if any are not found. The typeset command is supplied for compatibility with the Korn shell. It is a synonym for the declare builtin command. If an option is given, it is interpreted as follows:. The maximum amount of virtual memory available to the shell, and, on some systems, to its children.

If limit is given, and the -a option is not used, limit is the new value of the specified resource. The special limit values hard , soft , and unlimited stand for the current hard limit, the current soft limit, and no limit, respectively. A hard limit cannot be increased by a non-root user once it is set; a soft limit may be increased up to the value of the hard limit. Otherwise, the current value of the soft limit for the specified resource is printed, unless the -H option is supplied.

When more than one resource is specified, the limit name and unit, if appropriate, are printed before the value. When setting new limits, if neither -H nor -S is supplied, both the hard and soft limits are set.

If no option is given, then -f is assumed. Values are in byte increments, except for -t , which is in seconds; -R , which is in microseconds; -p , which is in units of byte blocks; -P , -T , -b , -k , -n and -u , which are unscaled values; and, when in POSIX Mode see Bash POSIX Mode , -c and -f , which are in byte increments. The return status is zero unless an invalid option or argument is supplied, or an error occurs while setting a new limit.

Remove each name from the list of aliases. If -a is supplied, all aliases are removed. This builtin is so complicated that it deserves its own section. If no options or arguments are supplied, set displays the names and values of all shell variables and functions, sorted according to the current locale, in a format that may be reused as input for setting or resetting the currently-set variables.

Read-only variables cannot be reset. When options are supplied, they set or unset shell attributes. Options, if specified, have the following meanings:. Each variable or function that is created or modified is given the export attribute and marked for export to the environment of subsequent commands. Cause the status of terminated background jobs to be reported immediately, rather than before printing the next primary prompt.

Exit immediately if a pipeline see Pipelines , which may consist of a single simple command see Simple Commands , a list see Lists , or a compound command see Compound Commands returns a non-zero status. If a compound command other than a subshell returns a non-zero status because a command failed while -e was being ignored, the shell does not exit. A trap on ERR , if set, is executed before the shell exits. This option applies to the shell environment and each subshell environment separately see Command Execution Environment , and may cause subshells to exit before executing all the commands in the subshell.

If a compound command or shell function executes in a context where -e is being ignored, none of the commands executed within the compound command or function body will be affected by the -e setting, even if -e is set and a command returns a failure status. If a compound command or shell function sets -e while executing in a context where -e is ignored, that setting will not have any effect until the compound command or the command containing the function call completes.

Locate and remember hash commands as they are looked up for execution. This option is enabled by default. All arguments in the form of assignment statements are placed in the environment for a command, not just those that precede the command name. Job control is enabled see Job Control. All processes run in a separate process group. When a background job completes, the shell prints a line containing its exit status. Read commands but do not execute them. This may be used to check a script for syntax errors.

This option is ignored by interactive shells. Use an emacs -style line editing interface see Command Line Editing. This also affects the editing interface used for read -e. Enable command history, as described in Bash History Facilities. This option is on by default in interactive shells. If set, the return value of a pipeline is the value of the last rightmost command to exit with a non-zero status, or zero if all commands in the pipeline exit successfully.

This option is disabled by default. This is intended to make Bash behave as a strict superset of that standard. Use a vi -style line editing interface. Turn on privileged mode. If the shell is started with the effective user group id not equal to the real user group id, and the -p option is not supplied, these actions are taken and the effective user id is set to the real user id. If the -p option is supplied at startup, the effective user id is not reset. Turning this option off causes the effective user and group ids to be set to the real user and group ids.

An error message will be written to the standard error, and a non-interactive shell will exit. Print a trace of simple commands, for commands, case commands, select commands, and arithmetic for commands and their arguments or associated word lists after they are expanded and before they are executed. The value of the PS4 variable is expanded and the resultant value is printed before the command and its expanded arguments. The shell will perform brace expansion see Brace Expansion. This option is on by default.

If set, any trap on ERR is inherited by shell functions, command substitutions, and commands executed in a subshell environment. The ERR trap is normally not inherited in such cases. This option is on by default for interactive shells.

If set, do not resolve symbolic links when performing commands such as cd which change the current directory. The physical directory is used instead. By default, Bash follows the logical chain of directories when performing commands which change the current directory.

If no arguments follow this option, then the positional parameters are unset. Signal the end of options, cause all remaining arguments to be assigned to the positional parameters. The -x and -v options are turned off. If there are no arguments, the positional parameters remain unchanged. The options can also be used upon invocation of the shell. The special parameter is set to N.

Toggle the values of settings controlling optional shell behavior. The settings can be either those listed below, or, if the -o option is used, those available with the -o option to the set builtin command see The Set Builtin.

With no options, or with the -p option, a list of all settable options is displayed, with an indication of whether or not each is set; if optnames are supplied, the output is restricted to those options. The -p option causes output to be displayed in a form that may be reused as input. Other options have the following meanings:. Suppresses normal output; the return status indicates whether the optname is set or unset.

If multiple optname arguments are given with -q , the return status is zero if all optnames are enabled; non-zero otherwise. Restricts the values of optname to be those defined for the -o option to the set builtin see The Set Builtin.

If either -s or -u is used with no optname arguments, shopt shows only those options which are set or unset, respectively. The return status when listing options is zero if all optnames are enabled, non-zero otherwise. When setting or unsetting options, the return status is zero unless an optname is not a valid shell option.

If set, the shell suppresses multiple evaluation of associative array subscripts during arithmetic expression evaluation, while executing builtins that can perform variable assignments, and while executing builtins that perform array dereferencing. If set, a command name that is the name of a directory is executed as if it were the argument to the cd command. This option is only used by interactive shells. If this is set, an argument to the cd builtin command that is not a directory is assumed to be the name of a variable whose value is the directory to change to.

If set, minor errors in the spelling of a directory component in a cd command will be corrected. The errors checked for are transposed characters, a missing character, and a character too many. If a correction is found, the corrected path is printed, and the command proceeds. If this is set, Bash checks that a command found in the hash table exists before trying to execute it.

If a hashed command no longer exists, a normal path search is performed. If set, Bash lists the status of any stopped and running jobs before exiting an interactive shell. If any jobs are running, this causes the exit to be deferred until a second exit is attempted without an intervening command see Job Control. The shell always postpones exiting if any jobs are stopped. If set, Bash attempts to save all lines of a multiple-line command in the same history entry.

This allows easy re-editing of multi-line commands. This option is enabled by default, but only has an effect if command history is enabled see Bash History Facilities. If set, Bash quotes all shell metacharacters in filenames and directory names when performing completion.

If not set, Bash removes metacharacters such as the dollar sign from the set of characters that will be quoted in completed filenames when these metacharacters appear in shell variable references in words to be completed. This means that dollar signs in variable names that expand to directories will not be quoted; however, any dollar signs appearing in filenames will not be quoted, either.

This is active only when bash is using backslashes to quote completed filenames. This variable is set by default, which is the default Bash behavior in versions through 4. If set, Bash replaces directory names with the results of word expansion when performing filename completion.

This changes the contents of the readline editing buffer. If not set, Bash attempts to preserve what the user typed. If set, Bash attempts spelling correction on directory names during word completion if the directory name initially supplied does not exist. If this is set, a non-interactive shell will not exit if it cannot execute the file specified as an argument to the exec builtin command. An interactive shell does not exit if exec fails. If set, aliases are expanded as described below under Aliases, Aliases.

This option is enabled by default for interactive shells. If set at shell invocation, or in a shell startup file, arrange to execute the debugger profile before the shell starts, identical to the --debugger option.

If set after invocation, behavior intended for use by debuggers is enabled:. If set, the extended pattern matching features described above see Pattern Matching are enabled. If set, patterns which fail to match filenames during filename expansion result in an expansion error. If set, the suffixes specified by the FIGNORE shell variable cause words to be ignored when performing word completion even if the ignored words are the only possible completions.

If set, range expressions used in pattern matching bracket expressions see Pattern Matching behave as if in the traditional C locale when performing comparisons. If set, shell error messages are written in the standard GNU error message format.

If set, and Readline is being used, a user is given the opportunity to re-edit a failed history substitution. If set, and Readline is being used, the results of history substitution are not immediately passed to the shell parser. Instead, the resulting line is loaded into the Readline editing buffer, allowing further modification.

If set, command substitution inherits the value of the errexit option, instead of unsetting it in the subshell environment. If set, and job control is not active, the shell runs the last command of a pipeline not executed in the background in the current shell environment.

If enabled, and the cmdhist option is enabled, multi-line commands are saved to the history with embedded newlines rather than using semicolon separators where possible.

If set, local variables inherit the value and attributes of a variable of the same name that exists at a previous scope before any new value is assigned.

The nameref attribute is not inherited. If set, calling unset on local variables in previous function scopes marks them so subsequent lookups find them unset until that function returns. This is identical to the behavior of unsetting local variables at the current function scope. The shell sets this option if it is started as a login shell see Invoking Bash. The value may not be changed. If set, and a file that Bash is checking for mail has been accessed since the last time it was checked, the message "The mail in mailfile has been read" is displayed.

If set, and Readline is being used, Bash will not attempt to search the PATH for possible completions when completion is attempted on an empty line. If set, Bash matches patterns in a case-insensitive fashion when performing matching while executing case or [[ conditional commands, when performing pattern substitution word expansions, or when filtering possible completions as part of programmable completion.

If set, Bash allows filename patterns which match no files to expand to a null string, rather than themselves. If set, the programmable completion facilities see Programmable Completion are enabled. If it has an alias, Bash attempts programmable completion using the command word resulting from the expanded alias. If set, prompt strings undergo parameter expansion, command substitution, arithmetic expansion, and quote removal after being expanded as described below see Controlling the Prompt.

The shell sets this option if it is started in restricted mode see The Restricted Shell. This is not reset when the startup files are executed, allowing the startup files to discover whether or not a shell is restricted. If this is set, the shift builtin prints an error message when the shift count exceeds the number of positional parameters.

If set, the source builtin uses the value of PATH to find the directory containing the file supplied as an argument. This chapter describes the shell variables that Bash uses.

Bash automatically assigns default values to a number of variables. Bash uses certain shell variables in the same way as the Bourne shell. In some cases, Bash assigns a default value to the variable. A colon-separated list of directories used as a search path for the cd builtin command. The value of this variable is also used by tilde expansion see Tilde Expansion. A list of characters that separate fields; used when the shell splits words as part of expansion.

If this parameter is set to a filename or directory name and the MAILPATH variable is not set, Bash informs the user of the arrival of mail in the specified file or Maildir-format directory. A colon-separated list of filenames which the shell periodically checks for new mail. A colon-separated list of directories in which the shell looks for commands. A zero-length null directory name in the value of PATH indicates the current directory. A null directory name may appear as two adjacent colons, or as an initial or trailing colon.

The primary prompt string. See Controlling the Prompt , for the complete list of escape sequences that are expanded before PS1 is displayed. The secondary prompt string. PS2 is expanded in the same way as PS1 before being displayed. A few variables used by Bash are described in different chapters: variables for controlling the job control facilities see Job Control Variables. At shell startup, set to the pathname used to invoke the shell or shell script being executed as passed in the environment or argument list.

Subsequently, expands to the last argument to the previous simple command executed in the foreground, after expansion. Also set to the full pathname used to invoke each command executed and placed in the environment exported to that command. When checking mail, this parameter holds the name of the mail file.

A colon-separated list of enabled shell options. Each word in the list is a valid argument for the -s option to the shopt builtin command see The Shopt Builtin. If this variable is in the environment when Bash starts up, each shell option in the list will be enabled before reading any startup files. This variable is readonly. Expands to the process ID of the current Bash process.

An associative array variable whose members correspond to the internal list of aliases as maintained by the alias builtin. Elements added to this array appear in the alias list; however, unsetting array elements currently does not cause aliases to be removed from the alias list.

An array variable whose values are the number of parameters in each frame of the current bash execution call stack. The number of parameters to the current subroutine shell function or script executed with. Setting extdebug after the shell has started to execute a script, or referencing this variable when extdebug is not set, may result in inconsistent values.

An array variable containing all of the parameters in the current bash execution call stack. The final parameter of the last subroutine call is at the top of the stack; the first parameter of the initial call is at the bottom. An associative array variable whose members correspond to the internal hash table of commands as maintained by the hash builtin see Bourne Shell Builtins. Elements added to this array appear in the hash table; however, unsetting array elements currently does not cause command names to be removed from the hash table.

The command currently being executed or about to be executed, unless the shell is executing a command as the result of a trap, in which case it is the command executing at the time of the trap. See Shell Compatibility Mode , for a description of the various compatibility levels and their effects. The value may be a decimal number e. The valid values correspond to the compatibility levels described below see Shell Compatibility Mode. For example, 4. The current version is also a valid value.

If this variable is set when Bash is invoked to execute a shell script, its value is expanded and used as the name of a startup file to read before executing the script. See Bash Startup Files. A colon-separated list of directories in which the shell looks for dynamically loadable builtins specified by the enable command. The element with index 0 is the portion of the string matching the entire regular expression. The element with index n is the portion of the string matching the n th parenthesized subexpression.

Incremented by one within each subshell or subshell environment when the shell begins executing in that environment. The initial value is 0. A readonly array variable see Arrays whose members hold version information for this instance of Bash. The values assigned to the array members are as follows:. This allows tracing output to be separated from diagnostic and error messages. Set the number of exited child status values for the shell to remember.

Bash will not allow this value to be decreased below a POSIX -mandated minimum, and there is a maximum value currently that this may not exceed. The minimum value is system-dependent. Used by the select command to determine the terminal width when printing selection lists. This variable is available only in shell functions invoked by the programmable completion facilities see Programmable Completion. The current command line. This variable is available only in shell functions and external commands invoked by the programmable completion facilities see Programmable Completion.

An escaped zero enclosed in single quotes, preceded by a dollar sign, is interpreted by bash as NULL. For more information, see: Expanding strings with interpreted escapes in the bash documentation. We're using NULL as the line delimiter because Linux file names can contain newlines, so we need to preserve them. This sounds awful, but yes, it happens. Luckily, find can use NULL to delimit its results, rather than a newline, if the -print0 option is specified:.

Here, find. When using -print0 , all other arguments and options must precede it, so make sure it's the last part of the command. Every iteration of the while loop, read reads one word a single file name and puts that value into the variable file , which we specified as the last argument of the read command. When there are no more file names to read, read returns false, which triggers the end of the while loop, and the command sequence terminates.

Store the words in an indexed array named array. Numbering of array elements starts at zero. Set the delimiter character to delim. This character signals the end of the line. If -d is not used, the default line delimiter is a newline.

Get a line of input from an interactive shell. The user manually inputs characters until the line delimiter is reached. When used in conjunction with -e and only if -s is not used , text is inserted as the initial text of the input line.

The user is permitted to edit text on the input line. Stop reading after an integer number nchars characters are read, if the line delimiter has not been reached.