GETSTR - read a string from an input unit.

Alternate entries: GET.ST

Usage:

B:
   string = getstr( [unit, ] string [, length] );
C:
   int getstr([FILE *unit,] char *string [, int length] );

Where:

unit

is the number of an open input unit. If "unit" is not specified, the current read unit is assumed.

string

points to a vector which is long enough to hold the input line which GETSTR obtains. GETSTR places the line in this vector.

length

specifies the maximum number of characters which may be read. "length" must be greater than zero or it will be ignored. If "length" is not specified, there is no maximum.

Description:

GETSTR reads characters from "unit" and places them in the area of memory pointed to by "string". It stops collecting characters when it encounters a '*n' or '*0', or when it has read "length" letters, whichever comes first. If the reading stops at a '*n' or '*0', the character is discarded. When GETSTR has finished reading, it terminates "string" with a '*0'. GETSTR returns a pointer to "string", unless "unit" is at end-of-file; in this case, GETSTR returns a zero.

If "length" is given, and there are "length" or more characters before the next '*n' or '*0', only the first "length" characters are read. Later input calls will retrieve these remaining characters. Note specifically that if the string returned has "length" characters in it, the '*n' has not been read and the rest of the line may be discarded by a call to FLUSH.

Notes:

The C function "fgets" is similar to GETSTR. However, "fgets" may return a '*0' embedded in the data returned.

See Also:

expl b lib getline

Copyright © 2000, Thinkage Ltd.