19 |
@node Ports |
@node Ports |
20 |
@section Ports |
@section Ports |
21 |
|
|
|
[Concept of the port abstraction.] |
|
|
|
|
22 |
Sequential input/output in Scheme is represented by operations on a |
Sequential input/output in Scheme is represented by operations on a |
23 |
@dfn{port}. Characters can be read from an input port and |
@dfn{port}. This chapter explains the operations that Guile provides |
24 |
written to an output port. This chapter explains the operations |
for working with ports. |
25 |
that Guile provides for working with ports. |
|
26 |
|
Ports are created by opening, for instance @code{open-file} for a file |
27 |
|
(@pxref{File Ports}). Characters can be read from an input port and |
28 |
|
written to an output port, or both on an input/output port. A port |
29 |
|
can be closed (@pxref{Closing}) when no longer required, after which |
30 |
|
any attempt to read or write is an error. |
31 |
|
|
32 |
The formal definition of a port is very generic: an input port is |
The formal definition of a port is very generic: an input port is |
33 |
simply ``an object which can deliver characters on command,'' and |
simply ``an object which can deliver characters on demand,'' and an |
34 |
an output port is ``an object which can accept characters.'' |
output port is ``an object which can accept characters.'' Because |
35 |
Because this definition is so loose, it is easy to write functions |
this definition is so loose, it is easy to write functions that |
36 |
that simulate ports in software. @dfn{Soft ports} and @dfn{string |
simulate ports in software. @dfn{Soft ports} and @dfn{string ports} |
37 |
ports} are two interesting and powerful examples of this technique. |
are two interesting and powerful examples of this technique. |
38 |
|
(@pxref{Soft Ports}, and @ref{String Ports}.) |
39 |
|
|
40 |
|
Ports are garbage collected in the usual way (@pxref{Memory |
41 |
|
Management}), and will be closed at that time if not already closed. |
42 |
|
In this case any errors occuring in the close will not be reported. |
43 |
|
Usually a program will want to explicitly close so as to be sure all |
44 |
|
its operations have been successful. Of course if a program has |
45 |
|
abandoned something due to an error or other condition then closing |
46 |
|
problems are probably not of interest. |
47 |
|
|
48 |
|
It is strongly recommended that file ports be closed explicitly when |
49 |
|
no longer required. Most systems have limits on how many files can be |
50 |
|
open, both on a per-process and a system-wide basis. A program that |
51 |
|
uses many files should take care not to hit those limits. The same |
52 |
|
applies to similar system resources such as pipes and sockets. |
53 |
|
|
54 |
|
Note that automatic garbage collection is triggered only by memory |
55 |
|
consumption, not by file or other resource usage, so a program cannot |
56 |
|
rely on that to keep it away from system limits. An explicit call to |
57 |
|
@code{gc} can of course be relied on to pick up unreferenced ports. |
58 |
|
If program flow makes it hard to be certain when to close then this |
59 |
|
may be an acceptable way to control resource usage. |
60 |
|
|
61 |
@rnindex input-port? |
@rnindex input-port? |
62 |
@deffn {Scheme Procedure} input-port? x |
@deffn {Scheme Procedure} input-port? x |
648 |
See also @ref{Ports and File Descriptors, open}, for an interface |
See also @ref{Ports and File Descriptors, open}, for an interface |
649 |
to the Unix @code{open} system call. |
to the Unix @code{open} system call. |
650 |
|
|
651 |
|
Most systems have limits on how many files can be open, so it's |
652 |
|
strongly recommended that file ports be closed explicitly when no |
653 |
|
longer required (@pxref{Ports}). |
654 |
|
|
655 |
@deffn {Scheme Procedure} open-file filename mode |
@deffn {Scheme Procedure} open-file filename mode |
656 |
@deffnx {C Function} scm_open_file (filename, mode) |
@deffnx {C Function} scm_open_file (filename, mode) |
657 |
Open the file whose name is @var{filename}, and return a port |
Open the file whose name is @var{filename}, and return a port |