perliol - Online nel cloud

PROGRAMMA:

NOME

perliol - API C per l'implementazione Perl di IO in Layers.

SINOSSI

/* Definizione di un livello... */
#includere

DESCRIZIONE

Questo documento descrive il comportamento e l'implementazione dell'astrazione PerlIO
descritto in perlapio quando è definito "USE_PERLIO".

Storia e a sfondo
L'astrazione PerlIO è stata introdotta in perl5.003_02 ma languiva come un semplice
astrazione fino a perl5.7.0. Tuttavia durante quel periodo un certo numero di estensioni perl cambiarono
per usarlo, quindi l'API è per lo più fissata per mantenere la compatibilità (sorgente).

L'obiettivo dell'implementazione è fornire l'API PerlIO in una piattaforma flessibile e
maniera neutra. È anche una prova di un approccio "C orientato agli oggetti, con vtables" che
può essere applicato a Perl 6.

Basic Structure
PerlIO è una pila di livelli.

I livelli bassi dello stack funzionano con le chiamate del sistema operativo di basso livello (file
descrittori in C) ottenere byte in entrata e in uscita, i livelli superiori del buffer dello stack, filtro,
e manipolare in altro modo l'I/O e restituire caratteri (o byte) a Perl. Termini sopra
e a sotto sono usati per riferirsi al posizionamento relativo degli strati di pila.

Un livello contiene una "vtable", la tabella delle operazioni di I/O (a livello C una tabella delle funzioni
puntatori) e flag di stato. Le funzioni nel vtable implementano operazioni come
"apri", "leggi" e "scrivi".

Quando viene richiesto l'I/O, ad esempio "read", la richiesta va da Perl prima giù per il
stack utilizzando le funzioni di "lettura" di ogni livello, quindi in basso viene richiesto l'input da
i servizi del sistema operativo, quindi il risultato viene restituito nello stack, infine essere
interpretati come dati Perl.

Le richieste non vanno necessariamente sempre fino al sistema operativo: ecco
dove entra in gioco il buffering di PerlIO.

Quando fai un Aperto() e specifica i livelli PerlIO extra da distribuire, i livelli che vuoi
specificare sono "spinti" in cima allo stack predefinito già esistente. Un modo per vederlo è
che "il sistema operativo è a sinistra" e "Perl è a destra".

Quali livelli esatti ci sono in questo stack predefinito dipende da molte cose: il tuo funzionamento
sistema, versione Perl, configurazione del tempo di compilazione Perl e configurazione del runtime Perl.
Vedi PerlIO, "PERLIO" in perlrun e apri per maggiori informazioni.

modalità bin() funziona in modo simile a Aperto(): per impostazione predefinita i livelli specificati vengono spostati in alto
della pila esistente.

Tuttavia, tieni presente che anche se i livelli specificati vengono "spinti in alto" per Aperto() e a
modalità bin(), questo non significa che gli effetti siano limitati al "top": i livelli PerlIO possono
essere molto "attivo" e ispezionare e influenzare i livelli anche più in profondità nello stack. Come esempio
c'è un livello chiamato "grezzo" che "fa scoppiare" ripetutamente i livelli fino a raggiungere il primo
layer che si è dichiarato in grado di gestire dati binari. Gli strati "spinti" sono
elaborati nell'ordine da sinistra a destra.

sysopen() opera (non sorprende) a un livello inferiore nello stack rispetto a Aperto(). For
esempio in Unix o sistemi simili a Unix sysopen() opera direttamente a livello di file
descrittori: in termini di livelli PerlIO, utilizza solo il livello "unix", che è a
wrapper piuttosto sottile sopra i descrittori di file Unix.

Livelli vs Discipline
La discussione iniziale sulla capacità di modificare il comportamento dei flussi di I/O ha utilizzato il termine
"disciplina" per gli enti che sono stati aggiunti. Questo è venuto (credo) dall'uso del
termine in "sfio", che a sua volta lo prese in prestito dalle "line discipline" sui terminali Unix.
Tuttavia, questo documento (e il codice C) utilizza il termine "livello".

Questo è, spero, un termine naturale data l'implementazione, e dovrebbe evitare connotazioni
che sono inerenti agli usi precedenti di "disciplina" per cose che sono piuttosto diverse.

Dati Strutture
La struttura dati di base è un PerlIOl:

typedef struct _PerlIO PerlIOl;
typedef struct _PerlIO_funcs PerlIO_funcs;
typedef PerlIOl *PerlIO;

struttura _PerlIO
{
PerlIOl * successivo; /* Strato inferiore */
PerlIO_funcs * scheda; /* Funzioni per questo livello */
bandiere U32; /* Vari flag per stato */
};

Un "PerlIOl *" è un puntatore alla struttura e il applicazione il livello "PerlIO *" è un
puntatore a un "PerlIOl *" - cioè un puntatore a un puntatore alla struttura. Questo permette al
livello di applicazione "PerlIO *" per rimanere costante mentre l'effettivo "PerlIOl *" sotto
i cambiamenti. (Confronta "SV *" di perl che rimane costante mentre il suo campo "sv_any" cambia come
il tipo dello scalare cambia.) Un flusso IO è quindi in generale rappresentato come un puntatore a
questa lista collegata di "livelli".

Va notato che a causa della doppia indiretto in un "PerlIO *", a
"&(perlio->next)" "è" un "PerlIO *", e quindi in una certa misura almeno un livello può usare il
API "standard" sul livello successivo.

Uno "strato" è composto da due parti:

1. Le funzioni e gli attributi della "classe layer".

2. I dati per istanza per un particolare handle.

funzioni e a Attributi
Le funzioni e gli attributi sono accessibili tramite il membro "tab" (per la tabella) di "PerlIOl".
Le funzioni (metodi del livello "classe") sono fisse, e sono definite dal
Tipo "PerlIO_funcs". Sono sostanzialmente le stesse delle funzioni pubbliche "PerlIO_":

struttura _PerlIO_funcs
{
Dimensione_t dimensione;
nome del personaggio;
Taglia_t taglia;
IV tipo;
IV (*Push)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab);
IV (*Spuntato)(pTHX_ PerlIO *f);
PerlIO * (*Aperto)(pTHX_ PerlIO_funcs *scheda,
PerlIO_list_t *strati, IV n,
const char *modalità,
int fd, int imode, int perm,
Perlio *vecchio,
int narg, SV **args);
IV (*Binmode)(pTHX_ PerlIO *f);
SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, flag int)
IV (*Fileno)(pTHX_ PerlIO *f);
PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int flag)
/* Funzioni simili a Unix - cf discipline della linea sfio */
SSize_t (*Leggi)(pTHX_ PerlIO *f, void *vbuf, Size_t conteggio);
SSize_t (*Non letto)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
SSize_t (*Write)(pTHX_ PerlIO *f, const void *vbuf, Size_t count);
IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int da dove);
Off_t (*Tell)(pTHX_ PerlIO *f);
IV (*Chiudi)(pTHX_ PerlIO *f);
/* Funzioni IO bufferizzate simili a Stdio */
IV (*Flush)(pTHX_ PerlIO *f);
IV (*Riempi)(pTHX_ PerlIO *f);
IV(*Eof)(pTHX_ PerlIO *f);
IV (*Errore)(pTHX_ PerlIO *f);
void (*Clearrr)(pTHX_ PerlIO *f);
void (*Setlinebuf)(pTHX_ PerlIO *f);
/* Le funzioni di spionaggio di Perl */
STDCHAR * (*Get_base)(pTHX_ PerlIO *f);
Dimensione_t (*Get_bufsiz)(pTHX_ PerlIO *f);
STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);
SSize_t (*Get_cnt)(pTHX_ PerlIO *f);
void (*Set_ptrcnt)(pTHX_ PerlIO *f,STDCHAR *ptr,SIze_t cnt);
};

I primi membri della struttura forniscono una dimensione della tabella delle funzioni per il controllo della compatibilità
"nome" per il livello, la dimensione in "malloc" per i dati per istanza e alcuni flag
che sono attributi della classe nel suo insieme (ad esempio se si tratta di un livello di buffer), quindi
seguono le funzioni che si dividono in quattro gruppi fondamentali:

1. Funzioni di apertura e configurazione

2. Operazioni IO di base

3. Opzioni di buffering della classe Stdio.

4. Funzioni per supportare il tradizionale accesso "veloce" di Perl al buffer.

Un livello non deve implementare tutte le funzioni, ma l'intera tabella deve essere
regalo. Gli slot non implementati possono essere NULL (che risulterà in un errore quando viene chiamato) o
può essere compilato con stub per "ereditare" il comportamento da una "classe base". Questa "eredità"
è fisso per tutte le istanze del livello, ma poiché il livello sceglie quali stub popolare
la tabella, è possibile "ereditarietà multipla" limitata.

Per istanza Dati
I dati per istanza vengono mantenuti in memoria oltre la struttura PerlIOl di base, facendo a
PerlIOl il primo membro della struttura del livello così:

struttura typedef
{
struct _PerlIO base; /* Informazioni sulla "classe" di base */
STDCHAR * buf; /* Inizio del buffer */
STDCAR * fine; /* Fine della parte valida del buffer */
STDCHAR * ptr; /* Posizione attuale nel buffer */
Off_t posizione; /* Offset di buf nel file */
Size_t bufsiz; /* Dimensione reale del buffer */
IV una parola; /* Buffer di emergenza */
} PerlIOBuf;

In questo modo (come per gli scalari di perl) un puntatore a un PerlIOBuf può essere trattato come un puntatore
a un PerlIOl.

Livelli in azione.
tavolo perlio unix
| |
+-----------+ +----------+ +--------+
Perlio ->| |--->| successivo |--->| NULL |
+-----------+ +----------+ +--------+
| | | tampone | | fd |
+-----------+ | | +--------+
| | +----------+

Quanto sopra tenta di mostrare come funziona lo schema dei livelli in un caso semplice. L'applicazione
"PerlIO *" punta a una voce nella tabella(e) che rappresenta gli handle aperti (allocati). Per
esempio i primi tre slot della tabella corrispondono a "stdin","stdout" e "stderr".
La tabella a sua volta punta al livello "superiore" corrente per la maniglia - in questo caso an
istanza del livello di buffering generico "perlio". Quel livello a sua volta punta al successivo
layer down - in questo caso il livello "unix" di basso livello.

Quanto sopra è approssimativamente equivalente a un flusso bufferizzato "stdio", ma con molto di più
flessibilità:

· Se il livello Unix "read"/"write"/"lseek" non è appropriato per (diciamo) socket allora il
Il livello "unix" può essere sostituito (a tempo aperto o anche dinamicamente) con un livello "socket".

· Differenti handle possono avere differenti schemi di buffering. Il livello "superiore" potrebbe essere il
livello "mmap" se la lettura dei file su disco era più rapida utilizzando "mmap" rispetto a "leggi". Un
Il flusso "senza buffer" può essere implementato semplicemente non avendo un livello di buffer.

· È possibile inserire livelli aggiuntivi per elaborare i dati durante il flusso. Questo era il
necessità trainante di includere lo schema in perl 5.7.0+ - avevamo bisogno di un meccanismo per consentire
dati da tradurre tra la codifica interna di perl (concettualmente almeno Unicode
come UTF-8) e il formato "nativo" utilizzato dal sistema. Questo è fornito da
Livello ":encoding(xxxx)" che in genere si trova sopra il livello di buffering.

· È possibile aggiungere un livello che esegue la traduzione di "\n" in CRLF. Questo livello può essere utilizzato su qualsiasi
piattaforma, non solo quelli che normalmente fanno queste cose.

Per istanza bandiera bit
I bit di flag generici sono un ibrido di flag di stile "O_XXXXX" dedotti dalla stringa di modalità
passato a "PerlIO_open()" e bit di stato per i livelli di buffer tipici.

PERLIO_F_EOF
Fine del file.

PERLIO_F_CANWRITE
Le scritture sono consentite, ad esempio aperte come "w" o "r+" o "a", ecc.

PERLIO_F_CANREAD
Le letture sono consentite, ad esempio "r" o "w+" aperti (o anche "a+" - ick).

PERLIO_F_ERRORE
Si è verificato un errore (per "PerlIO_error()").

PERLIO_F_TRUNCATE
Tronca il file suggerito dalla modalità aperta.

PERLIO_F_APPEND
Tutte le scritture dovrebbero essere append.

PERLIO_F_CRLF
Il livello esegue "\n" simile a Win32 mappato su CR,LF per l'output e CR,LF mappato su
"\n" per l'input. Normalmente il livello "crlf" fornito è l'unico livello che necessita di fastidio
a questo proposito. "PerlIO_binmode()" rovinerà questo flag piuttosto che aggiungere/rimuovere livelli
se il bit "PERLIO_K_CANCRLF" è impostato per la classe layer.

PERLIO_F_UTF8
I dati scritti su questo livello dovrebbero essere codificati in UTF-8; i dati forniti da questo livello dovrebbero
essere considerato codificato UTF-8. Può essere impostato su qualsiasi livello dal livello fittizio ":utf8". anche impostato
sul livello ":encoding".

PERLIO_F_UNBUF
Il livello non è bufferizzato, ovvero la scrittura sul livello successivo dovrebbe verificarsi per ogni scrittura su
questo strato.

PERLIO_F_WRBUF
Il buffer per questo livello attualmente contiene i dati scritti ma non inviati al successivo
strato.

PERLIO_F_RDBUF
Il buffer per questo livello attualmente contiene i dati non consumati letti dal livello sottostante.

PERLIO_F_LINEBUF
Il livello è bufferizzato. I dati di scrittura devono essere passati al livello successivo ogni volta che viene visualizzato un "\n"
è visto. Tutti i dati oltre "\n" dovrebbero quindi essere elaborati.

PERLIO_F_TEMP
Il file è stato "unlink()"ed, o dovrebbe essere cancellato su "close()".

PERLIO_F_APERTO
La maniglia è aperta.

PERLIO_F_FASTGETS
Questa istanza di questo livello supporta l'interfaccia "ottieni" veloce. Normalmente impostato basato
su "PERLIO_K_FASTGETS" per la classe e dall'esistenza della(e) funzione(i) nel
tavolo. Tuttavia una classe che normalmente fornisce quell'interfaccia potrebbe aver bisogno di evitarla su a
istanza particolare. Il livello "in sospeso" deve farlo quando viene spinto sopra a
layer che non supporta l'interfaccia. (Perl "sv_gets()" non si aspetta il
trasmette il comportamento "ottene" veloce per cambiare durante un "ottenere".)

Metodi in Dettagli
dimensione
Dimensione_t dimensione;

Dimensione della tabella delle funzioni. Questo viene confrontato con il valore che il codice PerlIO "sa" come
un controllo di compatibilità. Versioni future può essere in grado di tollerare i livelli compilati contro
una vecchia versione delle intestazioni.

Nome
nome del personaggio;

Il nome del livello il cui Aperto() metodo Perl dovrebbe invocare su Aperto(). Per esempio
se il livello si chiama APR, chiamerai:

apri $fh, ">:APR", ...

e Perl sa che deve invocare il PerlIOAPR_open() metodo implementato dal
strato APR.

Taglia
Taglia_t taglia;

La dimensione della struttura dati per istanza, ad esempio:

dimensionedi(PerlIOAPR)

Se questo campo è zero, allora "PerlIO_pusshed" non esegue malloc nulla e presuppone
la funzione Pushed del livello eseguirà qualsiasi manipolazione richiesta dello stack di livelli, utilizzata per evitare
malloc/overhead gratuito per strati fittizi. Se il campo è diverso da zero deve essere almeno
la dimensione di "PerlIOl", "PerlIO_pusshed" allocherà memoria per i dati del livello
strutture e collegare il nuovo livello allo stack del flusso. (Se il metodo Spinto del livello
restituisce un'indicazione di errore che il livello è stato estratto di nuovo.)

tipo
IV tipo;

· PERLIO_K_BUFFERATO

Lo strato è tamponato.

· PERLIO_K_RAW

Il livello è accettabile in uno stack binmode(FH), ovvero non lo fa (o lo farà
configurarsi per non) trasformare i byte che lo attraversano.

· PERLIO_K_CANCRLF

Il livello può tradurre tra "\n" e le estremità della riga CRLF.

· PERLIO_K_FASTGETS

Il livello consente lo snooping del buffer.

· PERLIO_K_MULTIARG

Usato quando il livello è Aperto() accetta più argomenti del solito. L'extra
gli argomenti non dovrebbero precedere l'argomento "MODE". Quando viene utilizzato questo flag è
fino al livello per convalidare gli argomenti.

Spinto
IV (*Push)(pTHX_ PerlIO *f,const char *mode, SV *arg);

L'unico metodo assolutamente obbligatorio. Chiamato quando il livello viene inserito nello stack.
L'argomento "mode" può essere NULL se ciò si verifica dopo l'apertura. L'"arg" sarà diverso da "NULL"
se è stata passata una stringa di argomento. Nella maggior parte dei casi questo dovrebbe chiamare "PerlIOBase_pused()"
per convertire "mode" negli appropriati flag "PERLIO_F_XXXXX" oltre a qualsiasi
azioni che il livello stesso esegue. Se un livello non si aspetta un argomento, ne ha bisogno
né salvare quello passato, né fornire "Getarg()" (potrebbe forse
"Perl_warn" che l'argomento non era previsto).

Restituisce 0 in caso di successo. In caso di errore restituisce -1 e dovrebbe impostare errno.

È scoppiato
IV (*Spuntato)(pTHX_ PerlIO *f);

Chiamato quando il livello viene estratto dalla pila. Un livello verrà normalmente spuntato dopo
Viene chiamato "Chiudi()". Ma un livello può essere estratto senza essere chiuso se il programma lo è
gestire dinamicamente i livelli sullo stream. In tali casi "Popped()" dovrebbe liberare qualsiasi
risorse (buffer, tabelle di traduzione, ...) non contenute direttamente nella struttura del livello.
Dovrebbe anche "Unread()" tutti i dati non consumati che sono stati letti e memorizzati nel buffer dal
strato sottostante torna a quello strato, in modo che possa essere rifornito a ciò che mai è ora
sopra.

Restituisce 0 in caso di successo e fallimento. Se "Popped()" ritorna vero poi perlio.c assume
che o lo strato è saltato da solo, o lo strato è super speciale e deve esserlo
trattenuto per altri motivi. Nella maggior parte dei casi dovrebbe tornare falso.

Apri
PerlIO * (*Apri)(...);

Il metodo "Open()" ha molti argomenti perché combina le funzioni di perl's
"open", "PerlIO_open", "sysopen" di perl, "PerlIO_fdopen" e "PerlIO_reopen". Il
prototipo completo è il seguente:

PerlIO * (*Aperto)(pTHX_ PerlIO_funcs *scheda,
PerlIO_list_t *strati, IV n,
const char *modalità,
int fd, int imode, int perm,
Perlio *vecchio,
int narg, SV **args);

Open dovrebbe (forse indirettamente) chiamare "PerlIO_allocate()" per allocare uno slot nel
tabella e associarla alle informazioni sui livelli per il file aperto, chiamando
"PerlIO_push". Il galline ovaiole è un array di tutti i livelli destinati al "PerlIO *",
e tutti gli argomenti passati loro, n è l'indice in quell'array del livello essendo
chiamato. La macro "PerlIOArg" restituirà un (possibilmente "NULL") SV * per l'argomento
passato allo strato.

Le modo string è una stringa simile a ""fopen()"" che corrisponderebbe all'espressione regolare
"/^[I#]?[rwa]\+?[bt]?$/".

Il prefisso 'I' viene utilizzato durante la creazione di "stdin".."stderr" tramite special
chiamate "PerlIO_fdopen"; il prefisso '#' significa che questo è "sysopen" e che imode e a
permanente dovrebbe essere passato a "PerlLIO_open3"; 'r' significa read, 'w' significa writo e 'a'
si intende apendi. Il suffisso '+' significa che sia la lettura che la scrittura/aggiunta sono
permesso. Il suffisso 'b' significa che il file dovrebbe essere binario e 't' significa che è testo.
(Quasi tutti i livelli dovrebbero eseguire l'IO in modalità binaria e ignorare i bit b/t
Il livello ":crlf" dovrebbe essere spinto per gestire la distinzione.)

If vecchio non è "NULL", allora questo è un "PerlIO_reopen". Perl stesso non lo usa
(ancora?) e la semantica sono un po' vaghi.

If fd non negativo allora è il descrittore di file numerico fd, che sarà aperto in a
modo compatibile con la stringa di modalità fornita, la chiamata è quindi equivalente a
"PerlIO_fdopen". In questo caso narghilè sarà zero.

If narghilè è maggiore di zero, quindi fornisce il numero di argomenti passati a "open",
altrimenti sarà 1 se ad esempio è stato chiamato "PerlIO_open". In casi semplici
SvPV_nolen(*args) è il percorso da aprire.

Se un livello fornisce "Open()" dovrebbe normalmente chiamare il metodo "Open()" del livello successivo
giù (se presente) e poi spingersi in alto se ciò ha successo. "PerlIOBase_open" è
fornito per fare esattamente questo, quindi nella maggior parte dei casi non devi scrivere il tuo
Metodo "Apri()". Se questo metodo non è definito, altri livelli potrebbero avere difficoltà
spingendosi sopra di esso durante l'apertura.

Se è stato eseguito "PerlIO_push" e l'apertura non è riuscita, deve "PerlIO_pop" stesso, poiché
in caso contrario, il livello non verrà rimosso e potrebbe causare gravi problemi.

Restituisce "NULL" in caso di errore.

Binmode
IV (*Binmode)(pTHX_ PerlIO *f);

Opzionale. Usato quando viene premuto il livello ":raw" (esplicitamente o come risultato di binmode(FH)).
Se non è presente, il livello verrà estratto. Se presente dovrebbe configurare il livello come binario (o
pop stesso) e restituisce 0. Se restituisce -1 per errore "binmode" fallirà con layer
ancora in pila.

Getarg
SV * (*Getarg)(pTHX_ PerlIO *f,
CLONE_PARAMS *param, flag int);

Opzionale. Se presente dovrebbe restituire un SV * che rappresenta l'argomento stringa passato a
lo strato quando è stato spinto. ad esempio ":encoding(ascii)" restituirebbe un SvPV con valore
"asci". (param e a bandiere gli argomenti possono essere ignorati nella maggior parte dei casi)

"Dup" usa "Getarg" per recuperare l'argomento originariamente passato a "Pushed", quindi tu
devi implementare questa funzione se il tuo livello ha un argomento in più su "Pushed" e lo farà
mai essere "Dup" ed.

Nessun file
IV (*Fileno)(pTHX_ PerlIO *f);

Restituisce il descrittore di file numerico Unix/Posix per l'handle. Normalmente
"PerlIOBase_fileno()" (che chiede solo il livello successivo) sarà sufficiente per questo.

Restituisce -1 in caso di errore, che è considerato includere il caso in cui il livello non può
fornire un tale descrittore di file.

Dup
PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o,
CLONE_PARAMS *param, flag int);

XXX: Ha bisogno di più documenti.

Usato come parte del processo "clone" quando viene generato un thread (nel qual caso param sarà
essere non NULL) e quando un flusso viene duplicato tramite '&' in "open".

Simile a "Apri", restituisce PerlIO* in caso di successo, "NULL" in caso di errore.

Leggi
SSize_t (*Leggi)(pTHX_ PerlIO *f, void *vbuf, Size_t conteggio);

Operazione di lettura di base.

In genere chiamerà "Riempi" e manipolerà i puntatori (possibilmente tramite l'API).
"PerlIOBuf_read()" può essere adatto per classi derivate che forniscono "ottenimenti veloci"
metodi.

Restituisce i byte effettivi letti o -1 in caso di errore.

Non letto
Ssize_t (*Non letto)(pTHX_ PerlIO *f,
const void *vbuf, conteggio Size_t);

Un superset di "ungetc()" di stdio. Dovrebbe organizzare letture future per vedere i byte in
"vbu". Se non c'è un'implementazione ovviamente migliore, allora "PerlIOBase_unread()"
fornisce la funzione spingendo un "falso" livello "in attesa" sopra il livello chiamante.

Restituisce il numero di caratteri non letti.

Scrivi
SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t conteggio);

Operazione di scrittura di base.

Restituisce i byte scritti o -1 in caso di errore.

Cercare
IV (*Seek)(pTHX_ PerlIO *f, Off_t offset, int da dove);

Posiziona il puntatore del file. Dovrebbe normalmente chiamare il proprio metodo "Flush" e quindi il
Metodo "Cerca" del livello successivo verso il basso.

Restituisce 0 in caso di successo, -1 in caso di fallimento.

Dire
Off_t (*Tell)(pTHX_ PerlIO *f);

Restituisce il puntatore del file. Può essere basato sul concetto di posizione memorizzato nella cache dei livelli da evitare
in testa.

Restituisce -1 in caso di errore nell'ottenere il puntatore del file.

Chiudi
IV (*Chiudi)(pTHX_ PerlIO *f);

Chiudi il flusso. Dovrebbe normalmente chiamare "PerlIOBase_close()" per svuotarsi e chiudersi
livelli sottostanti, quindi deallocare qualsiasi struttura di dati (buffer, tabelle di traduzione,
...) non detenuti direttamente nella struttura dati.

Restituisce 0 in caso di successo, -1 in caso di fallimento.

Lavare
IV (*Flush)(pTHX_ PerlIO *f);

Dovrebbe rendere lo stato del flusso coerente con i livelli sottostanti. Cioè, qualsiasi scrittura bufferizzata
i dati dovrebbero essere scritti e la posizione del file dei livelli inferiori regolata per i dati letti da
sotto ma non effettivamente consumato. (Dovrebbe forse "Non letto ()" tali dati in basso
strato.)

Restituisce 0 in caso di successo, -1 in caso di fallimento.

Riempire
IV (*Riempi)(pTHX_ PerlIO *f);

Il buffer per questo livello dovrebbe essere riempito (per la lettura) dal livello sottostante. Quando tu
layer PerlIOBuf "sottoclasse", si desidera utilizzare il suo _read metodo e per fornire il proprio
fill, che riempie il buffer di PerlIOBuf.

Restituisce 0 in caso di successo, -1 in caso di fallimento.

eof
IV(*Eof)(pTHX_ PerlIO *f);

Indicatore di fine file di ritorno. Normalmente è sufficiente "PerlIOBase_eof()".

Restituisce 0 alla fine del file, 1 se non alla fine del file, -1 in caso di errore.

Errore
IV (*Errore)(pTHX_ PerlIO *f);

Indicatore di errore di ritorno. Normalmente è sufficiente "PerlIOBase_error()".

Restituisce 1 se c'è un errore (di solito quando è impostato "PERLIO_F_ERROR"), 0 altrimenti.

Più chiaro
void (*Clearrr)(pTHX_ PerlIO *f);

Indicatori chiari di fine file e di errore. Dovrebbe chiamare "PerlIOBase_clearerr()" per impostare il
Flag "PERLIO_F_XXXXX", che possono essere sufficienti.

Setlinebuff
void (*Setlinebuf)(pTHX_ PerlIO *f);

Contrassegna il flusso come buffer di riga. "PerlIOBase_setlinebuf()" imposta il PERLIO_F_LINEBUF
flag ed è normalmente sufficiente.

Ottieni_base
STDCHAR * (*Get_base)(pTHX_ PerlIO *f);

Assegna (se non lo hai già fatto) il buffer di lettura per questo livello e restituisci il puntatore a
esso. Restituisce NULL in caso di errore.

Get_buffsiz
Dimensione_t (*Get_bufsiz)(pTHX_ PerlIO *f);

Restituisce il numero di byte che l'ultimo "Fill()" ha inserito nel buffer.

Ottieni_ptr
STDCHAR * (*Get_ptr)(pTHX_ PerlIO *f);

Restituisce il puntatore di lettura corrente relativo al buffer di questo livello.

Ottieni_cnt
SSize_t (*Get_cnt)(pTHX_ PerlIO *f);

Restituisce il numero di byte rimasti da leggere nel buffer corrente.

Set_ptrcnt
void (*Set_ptrcnt)(pTHX_ PerlIO *f,
STDCHAR *ptr, SSize_t cnt);

Regola il puntatore di lettura e il conteggio dei byte in modo che corrisponda a "ptr" e/o "cnt". Il
l'applicazione (o il livello superiore) deve garantire che siano coerenti. (Il controllo è consentito da
il paranoico.)

Elettricita, Gas Ed Acqua
Per richiedere il livello successivo, utilizzare PerlIONext(PerlIO *f).

Per verificare che un PerlIO* sia valido, utilizzare PerlIOValid(PerlIO *f). (Tutto ciò che fa è davvero
solo per verificare che il puntatore non sia NULL e che il puntatore dietro non sia NULL.)

PerlIOBase(PerlIO *f) restituisce il puntatore "Base", o in altre parole, il "PerlIOl*"
puntatore.

PerlIOSelf(PerlIO* f, type) restituisce il cast PerlIOBase a un tipo.

Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) chiama il richiama
dalle funzioni del livello f (solo con il nome della funzione IO, come "Leggi") con
, il args, o se non c'è tale richiamata, chiama il base versione del callback con il
stessi argomenti, o se la f non è valida, imposta errno su EBADF e ritorna fallimento.

Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) chiama il richiama di
funzioni dello strato f con la args, o se non c'è tale callback, impostare errno su
EINVAL. Oppure se la f non è valida, imposta errno su EBADF e ritorna fallimento.

Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) chiama il richiama di
funzioni dello strato f con la args, o se non c'è tale richiamata, chiama il base
versione del callback con gli stessi argomenti, o se la f non è valida, imposta errno su EBADF.

Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) chiama il richiama di
funzioni dello strato f con la args, o se non c'è tale callback, impostare errno su
EINVAL. Oppure se la f non è valida, imposta errno su EBADF.

Implementazione PerlIO Livelli
Se trovi il documento di attuazione poco chiaro o non sufficiente, guarda l'esistente
Implementazioni del livello PerlIO, che includono:

· Implementazioni C

Le perlio.c e a perliol.h nel core Perl implementano "unix", "perlio", "stdio",
layer "crlf", "utf8", "byte", "raw", "pending" e anche "mmap" e "win32"
strati, se applicabile. (Il "win32" è attualmente incompiuto e inutilizzato, per vedere cos'è
utilizzato invece in Win32, vedere "Interrogazione dei livelli di filehandle" in PerlIO .)

PerlIO::encoding, PerlIO::scalar, PerlIO::via nel core Perl.

PerlIO::gzip e APR::PerlIO (mod_perl 2.0) su CPAN.

· Implementazioni Perl

PerlIO::via::QuotedPrint nel core Perl e PerlIO::via::* su CPAN.

Se stai creando un livello PerlIO, potresti voler essere pigro, in altre parole, implementare
solo i metodi che ti interessano. Gli altri metodi che puoi sostituire con il
metodi "vuoti"

PerlIOBase_noop_ok
PerlIOBase_noop_fail

(che non fanno nulla e restituiscono rispettivamente zero e -1) o per alcuni metodi potresti
assumere un comportamento predefinito utilizzando un metodo NULL. Il metodo Open cerca aiuto nel
strato "genitore". La tabella seguente riassume il comportamento:

comportamento del metodo con NULL

Clearerr PerlIOBase_clearerr
Chiudi PerlIOBase_close
Duplica PerlIOBase_dup
Eof PerlIOBase_eof
Errore PerlIOBase_error
Fileno PerlIOBase_fileno
FALLIMENTO di riempimento
SUCCESSO a filo
Ottieni SUCCESSO
Get_base GUASTO
Get_bufsiz GUASTO
Get_cnt GUASTO
Get_ptr GUASTO
Apri EREDITATO
SUCCESSO scoppiato
SUCCESSO spinto
Leggi PerlIOBase_read
Cerca il FALLIMENTO
Set_cnt ERRORE
Set_ptrcnt ERRORE
Setlinebuf PerlIOBase_setlinebuf
Dillo FALLIMENTO
Non letto PerlIOBase_unread
Scrivi FALLIMENTO

FAILURE Imposta errno (su EINVAL in Unixish, su LIB$_INVARG in VMS) e
return -1 (per valori restituiti numerici) o NULL (per puntatori)
EREDITATO Ereditato dal livello sottostante
SUCCESS Restituisce 0 (per valori restituiti numerici) o un puntatore

Nucleo Livelli
Il file "perlio.c" fornisce i seguenti livelli:

"unix"
Un livello di base senza buffer che chiama Unix/POSIX "read()", "write()", "lseek()",
"chiudere()". Nessun buffering. Anche su piattaforme che distinguono tra O_TEXT e
O_BINARY questo livello è sempre O_BINARY.

"perlio"
Un livello di buffering generico molto completo che fornisce l'intera API PerlIO. è
destinato anche ad essere utilizzato come "classe di base" per altri livelli. (Ad esempio è "Leggi ()"
è implementato nei termini dei metodi "Get_cnt()"/"Get_ptr()"/"Set_ptrcnt()").

"perlio" su "unix" fornisce un sostituto completo per stdio come visto tramite l'API PerlIO.
Questa è l'impostazione predefinita per USE_PERLIO quando lo stdio di sistema non consente "fast" di perl
ottiene" l'accesso e che non distinguono tra "O_TEXT" e "O_BINARY".

"stdio"
Un livello che fornisce l'API PerlIO tramite lo schema del livello, ma lo implementa con
chiamando lo stdio del sistema. Questo è (attualmente) l'impostazione predefinita se lo stdio del sistema lo fornisce
accesso sufficiente per consentire l'accesso "fast get" di perl e che non distinguono
tra "O_TEXT" e "O_BINARY".

"crlf"
Un livello derivato usando "perlio" come classe base. Fornisce "\n" simile a Win32 a CR,LF
traduzione. Può essere applicato sopra "perlio" o fungere da strato tampone stesso.
"crlf" su "unix" è l'impostazione predefinita se il sistema distingue tra "O_TEXT" e
Si apre "O_BINARY". (Ad un certo punto "unix" verrà sostituito da un layer IO Win32 "nativo"
su quella piattaforma, poiché il livello di lettura/scrittura di Win32 presenta vari inconvenienti.) Il livello "crlf"
è un modello ragionevole per un livello che trasforma i dati in qualche modo.

"mappa"
Se Configura rileva le funzioni "mmap()" questo livello viene fornito (con "perlio" come a
"base") che esegue operazioni di "lettura" di mmp()ing il file. Il miglioramento delle prestazioni è
marginale sui sistemi moderni, quindi è principalmente lì come prova di concetto. È probabile
da separare dal nucleo ad un certo punto. Il livello "mmap" è un modello ragionevole
per uno strato "derivato" minimalista.

"in sospeso"
Un derivato "interno" di "perlio" che può essere utilizzato per fornire Non letto() funzione
per strati che non hanno buffer o che non possono essere disturbati. (Fondamentalmente questo livello è
"Fill()" si apre dalla pila e riprende la lettura dal livello sottostante.)

"crudo"
Un livello fittizio che non esiste mai nella pila di livelli. Invece quando "spinto" in realtà
apre lo stack rimuovendo se stesso, quindi chiama la voce della tabella delle funzioni Binmode su tutti i
layer nello stack - normalmente questo (tramite PerlIOBase_binmode) rimuove tutti i layer che
non hanno il bit "PERLIO_K_RAW" impostato. I livelli possono modificare quel comportamento definendo il loro
propria voce Binmode.

"utf8"
Un altro strato fittizio. Quando viene premuto si apre da solo e attiva il flag "PERLIO_F_UTF8"
il livello che era (e ora è ancora una volta) in cima alla pila.

Inoltre perlio.c fornisce anche una serie di funzioni "PerlIOBase_xxxx()" che sono
destinato ad essere utilizzato negli slot dei tavoli delle classi che non hanno bisogno di fare nulla di speciale
per un metodo particolare.

Estensione Livelli
I livelli possono essere resi disponibili da moduli di estensione. Quando si incontra un livello sconosciuto
il codice PerlIO eseguirà l'equivalente di:

usa PerlIO 'livello';

Dove strato è lo strato sconosciuto. PerlIO.pm tenterà quindi di:

richiedono PerlIO::layer;

Se dopo tale processo il livello non è ancora definito, "open" fallirà.

I seguenti livelli di estensione sono in bundle con perl:

":codifica"
utilizzare la codifica;

rende disponibile questo livello, sebbene PerlIO.pm "sa" dove trovarlo. È un
esempio di un layer che accetta un argomento come viene chiamato così:

open( $fh, "<:encoding(iso-8859-7)", $percorso );

":scalare"
Fornisce supporto per la lettura e la scrittura di dati da uno scalare.

open( $fh, "+<:scalare", \$scalare);

Quando un handle è così aperto, legge get byte dal valore della stringa di $scalare e
scrive modificare il valore. In entrambi i casi la posizione in $scalare inizia da zero ma può
essere alterato tramite "cerca" e determinato tramite "racconta".

Si prega di notare che questo livello è implicito quando si chiama Aperto() in tal modo:

open( $fh, "+<", \$scalare);

":attraverso"
Fornito per consentire l'implementazione dei livelli come codice Perl. Ad esempio:

usa PerlIO::via::StripHTML;
open( my $fh, "<:via(StripHTML)", "index.html" );

Vedere PerlIO::via per i dettagli.

TUTTO

Cose che devono essere fatte per migliorare questo documento.

· Spiega come fare un fh valido senza passare attraverso Aperto()(cioè applicare uno strato). Per
esempio se il file non viene aperto tramite perl, ma vogliamo ottenere un fh, come questo
è stato aperto da Perl.

Come si inserisce PerlIO_apply_layera, dove sono stati resi pubblici i suoi documenti?

Attualmente l'esempio potrebbe essere qualcosa del genere:

PerlIO *foo_to_PerlIO(pTHX_ char *modalità, ...)
{
char *modalità; /* "w", "r", ecc */
const char *layers = ":APR"; /* il nome del livello */
PerlIO *f = PerlIO_allocate(aTHX);
se (!f) {
restituisce NULL;
}

PerlIO_apply_layers(aTHX_ f, modalità, livelli);

se (f) {
PerlIOAPR *st = PerlIOAPR(f, PerlIOAPR);
/* compila la struttura st, come in _open() */
st->file = file;
PerlIOBase(f)->flag |= PERLIO_F_OPEN;

ritorno f;
}
restituisce NULL;
}

· correggere/aggiungere la documentazione nei punti contrassegnati come XXX.

· La gestione degli errori da parte del livello non è specificata. ad es. quando $! dovrebbe essere impostato
esplicitamente, quando la gestione degli errori dovrebbe essere semplicemente delegata al livello superiore.

Probabilmente dare alcuni suggerimenti sull'uso SETERNO() o indicazioni su dove possono essere trovati.

· Penso che sarebbe utile fornire alcuni esempi concreti per renderlo più facile da capire
l'API. Ovviamente sono d'accordo che l'API deve essere concisa, ma dal momento che non c'è
secondo documento che è più di una guida, penso che renderebbe più facile iniziare
con il documento che è un'API, ma contiene esempi in luoghi in cui si trovano le cose
poco chiaro, a una persona che non è (ancora) un guru di PerlIO.

Usa perliol online utilizzando i servizi onworks.net