3.2.36. LINEOUT([streamid][,[string][,line]])

Returns the number of lines remaining after having positioned the
stream streamid to the start of line line and written out string
as a line of text. If streamid is omitted, the default output
stream is used. If line (which must be a positive whole number) is
omitted, the stream will not be repositioned before the write. If
string is omitted, nothing is written to the stream.  If string is
specified, a system-specific action is taken after it has been
written to stream, to mark a new line.

The format and contents of the first parameter will depend upon
the implementation and how it names streams. Consult
implementation-specific documentation for more information.

If string is specified, but not line, the effect is to write
string to the stream, starting at the current write position. If
line is specified, but not string, the effect is only to position
the stream at the new position. Note that the line parameter is
only legal if the stream is persistent; you can not position the
current write position for transient streams.

If neither line nor string is specified, the standard requires
that the current write position is set the end of the stream, and
implementation specific side-effects may occur. In practice, this
means that an implementation can use this situation to do things
like closing the stream, or flushing the output. Consult the
implementation specific documentation for more information.

Also note that the return value of this functions may be of little
or no value, If just a half line is written, 1 may still be
returned, and there are no way of finding out how much (if any) of
string was written. If string is not specified, the return value
will always be 0, even if LINEOUT() was not able to correctly
position the stream.

If it is impossible to correctly write string to the stream, the
NOTREADY flag will be raised. It is not defined whether or not the
NOTREADY flag is raised when LINEOUT() is used for positioning,
and this is not possible.

Note that if you write string to a line in the middle of the
stream (i.e. line is less than the total number of lines in the
stream), then the behavior is system and implementation specific.
Some systems will truncate the stream after the newly written
line, other will only truncate if the newly written line has a
different length than the old line which it replaced, and yet
other systems will overwrite and never truncate.

In general, consult your system and implementation specific
documentation for more information about this function. You can
safely assume very little about how it behaves.

     LINEOUT(, ‘First line’)                 –>   ‘1’
     LINEOUT(‘/tmp/file’, ‘Second line’, 2)  –>   ‘1’
     LINEOUT(‘/tmp/file’, ‘Third line’)      –>   ‘1’
     LINEOUT(‘/tmp/file’, ‘Fourth line’, 4)  –>   ‘0’


 PREV   NEXT