From: Nick Ing-Simmons Date: Mon, 29 Jan 2001 21:55:10 +0000 (+0000) Subject: PerlIO doc tweaks from Craig A. Berry X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=3039a93d20f525d68a979d28a46c6bc76a0d463e;p=p5sagit%2Fp5-mst-13.2.git PerlIO doc tweaks from Craig A. Berry p4raw-id: //depot/perlio@8590 --- diff --git a/pod/perlapio.pod b/pod/perlapio.pod index 88a509c..6f0c96c 100644 --- a/pod/perlapio.pod +++ b/pod/perlapio.pod @@ -4,7 +4,7 @@ perlapio - perl's IO abstraction interface. =head1 SYNOPSIS - #define PERLIO_NOT_STDIO 0 /* For co-existance with stdio only */ + #define PERLIO_NOT_STDIO 0 /* For co-existence with stdio only */ #include /* Usually via #include */ PerlIO *PerlIO_stdin(void); @@ -112,10 +112,10 @@ The USE_PERLIO implementation is described in L. =back Because "perlio.h" is a thing layer (for efficiency) the semantics of these functions are -somewhat dependant on the the underlying implementation. Where these variations are +somewhat dependent on the the underlying implementation. Where these variations are understood they are noted below. -Unless otherwise noted functions returns 0 on sucess, or a negative value (usually +Unless otherwise noted, functions return 0 on success, or a negative value (usually C which is usually -1) and set C on error. =over 4 @@ -130,11 +130,11 @@ values. =item B, B -These correspond to fopen()/fdopen() arguments are the same. -Returns C and sets C if there is an error. -There may be implementation limit on number of open handles, which may +These correspond to fopen()/fdopen() and the arguments are the same. +Return C and set C if there is an error. +There may be an implementation limit on the number of open handles, which may be lower than the limit on the number of open files - C may -not be when C is returned if this limnit is exceeded. +not be set when C is returned if this limnit is exceeded. =item B) on error. +Returns the character read or -1 (C) on error. =item B @@ -204,7 +204,7 @@ Returns a true/false indication of whether there has been an IO error on the han =item B This corresponds to fileno(), note that on some platforms, -the meaning of "fileno" may not match Unix. Returns -1 if the handle has not +the meaning of "fileno" may not match Unix. Returns -1 if the handle has no open descriptor associated with it. =item B @@ -235,7 +235,7 @@ as stdio's C. This corresponds to ftell(). Returns the current file position, or (Off_t) -1 on error. May just return value system "knows" without making a system call or checking -the underlying file descriptior (so use on shared file descriptors is not +the underlying file descriptor (so use on shared file descriptors is not safe without a PerlIO_seek()). Return value is of type C which is a perl Configure value which may not be same as stdio's C. @@ -243,7 +243,7 @@ value which may not be same as stdio's C. These correspond (loosely) to fgetpos() and fsetpos(). Rather than stdio's Fpos_t they expect a "Perl Scalar Value" to be passed. What is stored there should -be considered opaque. They layout of the data may vary from handle to handle. +be considered opaque. The layout of the data may vary from handle to handle. When not using stdio or if platform does not have the stdio calls then they are implemented in terms of PerlIO_tell() and PerlIO_seek(). @@ -259,7 +259,7 @@ This corresponds to rewind(). It is usually defined as being This corresponds to tmpfile(), i.e., returns an anonymous PerlIO or NULL on error. -The system will attempt to automatically be delete then file when closed. +The system will attempt to automatically delete the file when closed. On Unix the file is usually C-ed just after it is created so it does not matter how it gets closed. On other systems the file may only be deleted if closed via PerlIO_close() and/or the program exits via C. @@ -271,7 +271,7 @@ than ad. hoc. schemes. This corresponds to setlinebuf(). Does not return a value. What constitutes a "line" is implementation -dependant but usually means that writing "\n" flushes the buffer. +dependent but usually means that writing "\n" flushes the buffer. What happens with things like "this\nthat" is uncertain. (Perl core uses it I when "dumping"; it has nothing to do with $| auto-flush.) @@ -293,7 +293,7 @@ default at some point). That prevents "perlio.h" from attempting to #define stdio functions onto PerlIO functions. XS code is probably better using "typemap" if it expects FILE * arguments. -The standard typemap will be adjusted to comprehend and changes in this area. +The standard typemap will be adjusted to comprehend any changes in this area. =over 4 @@ -308,7 +308,7 @@ as in fopen/freopen. =item B -Given an PerlIO * return a 'native' FILE * suitable for +Given a PerlIO * return a 'native' FILE * suitable for passing to code expecting to be compiled and linked with ANSI C I. @@ -378,7 +378,7 @@ Set pointer into buffer, and a count of bytes still in the buffer. Should be used only to set pointer to within range implied by previous calls to C and C. The two values I be consistent -with each other (implementartion may only use one or the other or may require both). +with each other (implementation may only use one or the other or may require both). =item B @@ -452,7 +452,7 @@ Portable cases are: and PerlIO_binmode(f,ptype,O_TEXT,":crlf"); -On Unix these calls probably haver no effect what so ever. +On Unix these calls probably have no effect whatsoever. Elsewhere they alter "\n" to CR,LF translation and possibly cause a special text "end of file" indicator to be written or honoured on read. The effect of making the call after doing any IO to the handle depends on the implementation. (It may be diff --git a/pod/perliol.pod b/pod/perliol.pod index 6169d43..34a5fb2 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -11,14 +11,14 @@ perliol - C API for Perl's implementation of IO in Layers. =head1 DESCRIPTION -This document describes the behavior and implementation of the PerlIO abstraction +This document describes the behaviour and implementation of the PerlIO abstraction described in L when C is defined (and C is not). =head2 History and Background The PerlIO abstraction was introduced in perl5.003_02 but languished as just -an abstraction until perl5.7.0. However during that time a number of perl extenstions -switch to using it, so the API is mostly fixed to maintain (source) compatibility. +an abstraction until perl5.7.0. However during that time a number of perl extensions +switched to using it, so the API is mostly fixed to maintain (source) compatibility. The aim of the implementation is to provide the PerlIO API in a flexible and platform neutral manner. It is also a trial of an "Object Oriented C, with vtables" @@ -30,7 +30,7 @@ Initial discussion of the ability to modify IO streams behaviour used the term "discipline" for the entities which were added. This came (I believe) from the use of the term in "sfio", which in turn borowed it from "line disciplines" on Unix terminals. However, this document (and the C code) uses the term "layer". -This is I hope a natural term given the implementation, and should avoid conotations +This is I hope a natural term given the implementation, and should avoid connotations that are inherent in earlier uses of "discipline" for things which are rather different. =head2 Data Structures @@ -165,7 +165,7 @@ as a pointer to a PerlIOl. The above attempts to show how the layer scheme works in a simple case. -The applications PerlIO * points to an entry in the table(s) representing open +The application's PerlIO * points to an entry in the table(s) representing open (allocated) handles. For example the first three slots in the table correspond to C,C and C. The table in turn points to the current "top" layer for the handle - in this case an instance of the generic buffering @@ -220,15 +220,15 @@ End of file. =item PERLIO_F_CANWRITE -Writes are permited i.e. opened as "w" or "r+" or "a". etc. +Writes are permitted, i.e. opened as "w" or "r+" or "a", etc. =item PERLIO_F_CANREAD -Reads are permited i.e. opened "r" or "w+" (or even "a+" - ick). +Reads are permitted i.e. opened "r" or "w+" (or even "a+" - ick). =item PERLIO_F_ERROR -An error has occured (for PerlIO_error()) +An error has occurred (for PerlIO_error()) =item PERLIO_F_TRUNCATE @@ -247,7 +247,7 @@ if the PERLIO_K_CANCRLF bit is set for the layers class. =item PERLIO_F_UTF8 -Data for this written to this layer should be UTF-8 encoded, data provided +Data written to this layer should be UTF-8 encoded; data provided by this layer should be considered UTF-8 encoded. Can be set on any layer by ":utf8" dummy layer. Also set on ":encoding" layer. @@ -283,11 +283,11 @@ Handle is open. This instance of this layer supports the "fast gets" interface. Normally set based on PERLIO_K_FASTGETS for the class and by the -existance of the function(s) in the table. However a class that +existence of the function(s) in the table. However a class that normally provides that interface may need to avoid it on a particular instance. The "pending" layer needs to do this when -it is pushed above an layer which does not support the interface. -(Perls sv_gets() does not expect the steams fast gets behaviour +it is pushed above a layer which does not support the interface. +(Perls sv_gets() does not expect the stream's fast gets behaviour to change during one "get".) =back @@ -322,7 +322,7 @@ Perl does not use this and L marks it as subject to change. Called when the layer is pushed onto the stack. The C argument may be NULL if this occurs post-open. The C and C will be present if an argument string was -passed. In most cases this should call PerlIOBase_pushed() to conver C into +passed. In most cases this should call PerlIOBase_pushed() to convert C into the appropriate PERLIO_F_XXXXX flags in addition to any actions the layer itself takes. =item IV (*Popped)(PerlIO *f); @@ -369,7 +369,7 @@ tables, ...) not held directly in the data structure. Should make streams state consistent with layers below. That is any buffered write data should be written, and file position of lower layer -adjusted for data read fron below but not actually consumed. +adjusted for data read from below but not actually consumed. =item IV (*Fill)(PerlIO *f); @@ -403,7 +403,7 @@ Return the number of bytes that last Fill() put in the buffer. =item STDCHAR * (*Get_ptr)(PerlIO *f); -Return the current read pointer relative to this layers buffer. +Return the current read pointer relative to this layer's buffer. =item SSize_t (*Get_cnt)(PerlIO *f);