All rights reserved. The Berkeley software License Agreement
specifies the terms and conditions for redistribution.
@(#)ch5.n 4.1 (Berkeley) 04/29/86
." @(#)ch5.n 34.2 7/9/81 .Lc Input/Output 5 The following functions are used to read and write to and from external devices and programs (through pipes). All I/O goes through the lisp data type called the port. A port may be open for either reading or writing but not both simultaneously. There are only a limited number of ports (20) and they will not be reclaimed unless you .i close them. All ports are reclaimed by a .i resetio call but this drastic step won't be necessary if the program closes what it uses. If you don't supply a port argument to a function which requires one or if you supply a bad port argument (such as nil) then .Fr will use the default port according to this scheme. If you are reading then the default port is the value of the symbol .i piport and if you are writing it is the value of the symbol .i poport . Furthermore if the value of piport or poport is not a valid port then the standard input or standard output will be used, respectively. The standard input and standard output are usually the keyboard and terminal display unless your job is running in the background and its input or output is connected to a pipe. All output which goes to the standard output will also go to the port .i ptport if it is a valid port. Output destined for the standard output will not reach it if the symbol .i ^w is non nil (although it will still go to .i ptport if .i ptport is a valid port). .Lf cfasl "'st_file 'st_entry 's_funcname ['st_disc ['st_library]]" .Re t .Se This is use to load in a foreign function (see \(sc8.4). The object file st_file is loaded into the lisp system. St_entry should be an entry point in the file just loaded. The function binding of the symbol s_funcname will be set to point to st_entry, so that when the lisp function s_funcname is called, st_entry will be run. st_disc is the discipline to be given to s_funcname. st_disc defaults to "subroutine" if it is not given or if it is given as nil. If st_library is non nil, then after st_file is loaded, the libraries given in st_library will be searched to resolve external references. The form of st_library should be something like "-lS -lm". The c library (" -lc " ) is always searched so when loading in a C file you probably won't need to specify a library. For Fortran files, you should specify "-lF77" and if you are doing any I/O that should be "-lF77 -lIf77". For Pascal files "-lpc" is required. .No This function may be used to load the output of the assembler, C compiler, Fortran compiler, and Pascal compiler but NOT the lisp compiler (use .i fasl for that). If a file has more than one entry point, then use .i getaddress to locate and setup other foreign functions.
It is an error to load in a file which has a global entry point of the same name as a global entry point in the running lisp. As soon as you load in a file with .i cfasl , its global entry points become part of the lisp's entry points. Thus you cannot .i cfasl in the same file twice unless you use .i removeaddress to change certain global entry points to local entry points. .Lf close "'p_port" .Re t .Se the specified port is drained and closed, releasing the port. .No The standard defaults are not used in this case since you probably never want to close the standard output or standard input. .Lf cprintf "'st_format 'xfst_val ['p_port]" .Re xfst_val .Se The UNIX formatted output function printf is called with arguments st_format and xfst_val. If xfst_val is a symbol then its print name is passed to printf. The format string may contain characters which are just printed literally and it may contain special formatting commands preceded by a percent sign. The complete set of formatting characters is described in the UNIX manual. Some useful ones are %d for printing a fixnum in decimal, %f or %e for printing a flonum, and %s for printing a character string (or print name of a symbol). .Ex (cprintf "Pi equals %f" 3.14159) prints `Pi equals 3.14159' .Lf drain "['p_port]" .Re nil .Se If this is an output port then the characters in the output buffer are all sent to the device. If this is an input port then all pending characters are flushed. The default port for this function is the default output port. .Lf fasl "'st_name ['st_mapf ['g_warn]]" .Wh st_mapf and g_warn default to nil. .Re t if the function succeeded, nil otherwise. .Se this function is designed to load in an object file generated by the lisp compiler Liszt. File names for object files usually end in `.o', so .i fasl will append `.o' to st_name (if it is not already present). If st_mapf is non nil, then it is the name of the map file to create. .i Fasl writes in the map file the names and addresses of the functions it loads and defines. Normally the map file is created (i.e. truncated if it exists), but if (sstatus appendmap t) is done then the map file will be appended. If g_warn is non nil and if a function is loaded from the file which is already defined, then a warning message will be printed. .Lf ffasl "'st_file 'st_entry 'st_funcname ['st_discipline]" .Re the binary object created. .Se the fortran object file st_file is loaded into the lisp system. St_entry should be an entry point in the file just loaded. A binary object will be created and its entry field will be set to point to st_entry. The discipline field of the binary will be set to st_discipline or "subroutine" by default. After st_file is loaded, the standard fortran libraries will be searched to resolve external references. .No in F77 on Unix, the entry point for the fortran function foo is named `_foo_'. .Lf flatc "'g_form ['x_max]" .Re the number of characters required to print g_form using patom. If x_max is given, and the flatc determines that it will return a value greater than x_max, then it gives up and returns the current value it has computed. This is useful if you just want to see if an expression is larger than a certain size. .Lf flatsize "'g_form ['x_max]" .Re the number of characters required to print g_form using print. The meaning of x_max is the same as for flatc. .No Currently this just .i explode 's g_form and checks its length. .Lf fseek "'p_port 'x_offset 'x_flag" .Re the position in the file after the function is performed. .Se this function position the read/write pointer before a certain byte in the file. If x_flag is 0 then the pointer is set to x_offset bytes from the beginning of the file. If x_flag is 1 then the pointer is set to x_offset bytes from the current location in the file. If x_flag is 2 then the pointer is set to x_offset bytes from the end of the file (the bytes between the end of the file and the new position will be filled with zeroes). .Lf infile "'s_filename" .Re a port ready to read s_filename. .Se this tries to open s_filename and if it cannot or if there are no ports available it gives an error message. .No to allow your program to continue on a file not found error you can use something like:
(cond ((null (setq myport (car (errset (infile name) nil))))
(patom '"couldn't open the file")))
which will set myport to the port to read from if the file exists
or will print a message if it couldn't open it and also set myport to nil.
.Lf load "'s_filename ['st_map ['g_warn]]"
.Re
t
.No
The function of
.i load
has changed since previous releases of
.Fr
and the following description should be read carefully.
.Se
.i load
now serves the function of both
.i fasl
and the old
.i load .
.i Load
will search a user defined search path for a lisp source or object file
with the filename s_filename (with the extension .l or .o added as
appropriate).
The search path which
.i load
uses is the value of (status load-search-path).
The default is (|.| /usr/lib/lisp) which means look in the current
directory first and then /usr/lib/lisp.
The file which
.i load
looks for depends on the last two characters of s_filename.
If s_filename ends with ".l" then
.i load
will only look for a file name
s_filename and will assume that this is a
.Fr
source file.
If s_filename ends with ".o" then
.i load
will only look for a file named s_filename and will assume that this is
a
.Fr
object file to be
.i fasl ed
in.
Otherwise,
.i load
will first look for s_filename.o, then s_filename.l and finally
s_filename itself.
If it finds s_filename.o it will assume that this is an object file,
otherwise it will assume that it is a source file.
An object file is loaded using
.i fasl
and a source file is loaded by reading and evaluating each form in the
file.
The optional arguments st_map and g_warn are passed to
.i fasl
should
.i fasl
be called.
.No
load requires a port to open the file s_filename.
It then lambda binds the symbol piport to this port and reads and
evaluates the forms.
.Lf makereadtable "['s_flag]"
.Wh
if s_flag is not present it is assumed to be nil.
.Re
a readtable equal to the original readtable if s_flag is non nil, or else
equal to the current readtable.
See chapter 7 for a description of readtables and their uses.
.Lf nwritn "['p_port]"
.Re
the number of characters in the buffer
of the given port but not yet written out to the file or device.
The buffer is flushed
automatically after the buffer (of 512 characters) is filled
or when
.i terpr
is called.
.Lf outfile "'s_filename"
.Re
a port or nil
.Se
this opens a port to write s_filename.
The file opened is truncated by the outfile if it existed beforehand.
If there are no free ports, outfile returns nil.
.pg
.Lf patom "'g_exp ['p_port]"
.Re
g_exp
.Se
g_exp is printed to the given port or the default port.
If g_exp is a symbol then the print name is printed without
any escape characters around special characters in the print name.
If g_exp is a list then patom has the same effect as print.
.Lf pntlen "'xfs_arg"
.Wh
xfs_arg is a fixnum, flonum or symbol.
.Re
the number of characters needed to print xfs_arg.
.Lf portp "'g_arg"
.Re
t iff g_arg is a port.
.Lf pp "[l_option] s_name1 ..."
.Re
t
.Se
If s_namei has a function binding, it is pretty printed,
otherwise if s_namei has a value then that is pretty printed.
Normally the output of the pretty printer goes to the standard
output port poport.
The options allow you to redirect it.
The option (F filename) causes output to go to the file
filename.
The option (P portname) causes output to go to the port portname
which should have been opened previously.
.Lf princ "'g_arg ['p_port]"
.Eq
patom.
.Lf print "'g_arg ['p_port]"
.Re
nil
.Se
prints g_arg on the port p_port or the default port.
.Lf probef "'st_file"
.Re
t iff the file st_file exists.
.No
Just because it exists doesn't mean you can read it.
.Lf ratom "['p_port ['g_eof]]"
.Re
the next atom read from the given or default port.
On end of file, g_eof (default nil) is returned.
.Lf read "['p_port ['g_eof]]"
.Re
the next lisp expression read from the given or default port.
On end of file, g_eof (default nil) is returned.
.Lf readc "['p_port ['g_eof]]"
.Re
the next character read from the given or default port.
On end of file, g_eof (default nil) is returned.
.Lf readlist "'l_arg"
.Re
the lisp expression read from the list of characters in l_arg.
.Lf resetio
.Re
nil
.Se
all ports except the standard input, output and error
are closed.
.Lf setsyntax "'s_symbol 'sx_code ['ls_func]"
.Re
t
.Se
this sets the code for s_symbol to sx_code in the current readtable.
If sx_code is
.i macro
or
.i splicing
then ls_func is the associated function.
See section \(sc7 on the reader for more details.
.Lf terpr "['p_port]"
.Re
nil
.Se
a terminate line character sequence
is sent to the given port or the default port.
This will also flush the buffer.
.Lf terpri "['p_port]"
.Eq
terpr.
.Lf tyi "['p_port]"
.Re
the fixnum representation of the next character read.
On end of file, -1 is returned.
.Lf tyipeek "['p_port]"
.Re
the fixnum representation of the next character to be read.
.No
This does not actually read the character, it just peeks at it.
.Lf tyo "'x_char ['p_port]"
.Re
x_char.
.Se
the fixnum representation of a character, x_code, is printed as a
character on the given output port or the default output port.
.Lf zapline
.Re
nil
.Se
all characters up to and including the line termination character
are read and discarded from the last port used
for input.
.No
this is used as the macro function for the semicolon character when
it acts as a comment character.