Initial commit

1 files changed, 57 insertions, 0 deletions

diff --git a/unix/os/doc/zgettx.hlp b/unix/os/doc/zgettx.hlp
new file mode 100644
index 00000000..2a5b6bb6
--- /dev/null
+++ b/unix/os/doc/zgettx.hlp
@@ -0,0 +1,57 @@
+.help zgettx May84 "System Interface"
+.ih
+NAME
+zgettx -- get next line from a text file
+.ih
+SYNOPSIS
+.nf
+zgettx (chan, text, maxch, status)
+
+int	chan			# OS channel of file
+char	text[maxch]		# output record buffer
+int	maxch			# capacity of buffer
+int	status
+.fi
+.ih
+DESCRIPTION
+At most \fImaxch\fR chars are read from the next line of the text file
+connected to channel \fIchan\fR into the buffer \fItext\fR.
+A line of text is a sequence of zero or more characters terminated by the
+\fBnewline\fR character (normally linefeed).  If \fImaxch\fR is less than
+the length of the line the next read will return the remainder of the line
+or \fImaxch\fR characters, whichever is smaller.  The newline character
+counts as one character and is returned as the final character in \fItext\fR
+when end of line is reached.  The \fBzgettx\fR primitive always returns ASCII
+character data unpacked into the SPP char array \fItext\fR.  The \fItext\fR
+array is not EOS delimited.
+.ih
+RETURN VALUE
+ERR is returned for a read error or for an illegal call.  If the read is
+successful the number of characters read (including the newline) is returned
+in \fIstatus\fR.  When EOF is reached successive reads will return nothing,
+i.e., the number of characters read will be zero.
+.ih
+NOTES
+There is no fixed upper limit on the length of a line.  In normal usage FIO
+calls \fBzputtx\fR to write out the internal FIO fixed size line buffer
+whenever it sees a newline in the output.  If an applications program writes
+a very long line, the line buffer in FIO will overflow and \fBzputtx\fR will
+be called to write out the contents of the buffer without a newline terminator.
+FIO will also write out a partial line when the output is explicitly flushed.
+On input FIO uses the same fixed size line buffer, and several calls to
+\fBzgettx\fR may be required to read a full line.
+
+If the host system does not use the ASCII character set \fBzgettx\fR will
+convert characters to ASCII upon input.  The full ASCII character set is
+permitted, i.e., control characters may be embedded in the text.
+.ih
+BUGS
+Individual IRAF and host system utilities may place their own limits on the
+maximum length of a line of text.  The lower bound on the size of a line
+of text in IRAF programs is globally defined by the parameter SZ_LINE in
+\fBiraf.h\fR and may easily be adjusted by the system installer.  A sysgen
+of the entire system is required as SZ_LINE is used everywhere.
+.ih
+SEE ALSO
+zfiotx, zputtx
+.endhelp