/[guile]/guile/guile-core/doc/ref/scheme-io.texi
ViewVC logotype

Diff of /guile/guile-core/doc/ref/scheme-io.texi

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.11 by kryde, Fri May 30 00:17:01 2003 UTC revision 1.12 by kryde, Thu Jun 5 00:56:33 2003 UTC
# Line 19  Line 19 
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
# Line 623  The following procedures are used to ope Line 648  The following procedures are used to ope
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

Legend:
Removed from v.1.11  
changed lines
  Added in v.1.12

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26