perliol - En ligne dans le Cloud

PROGRAMME:

Nom

perliol - API C pour l'implémentation de Perl d'IO dans Layers.

SYNOPSIS

/* Définition d'un calque... */
#comprendre

DESCRIPTION

Ce document décrit le comportement et l'implémentation de l'abstraction PerlIO
décrit dans perlapio lorsque "USE_PERLIO" est défini.

Historique et Information de Base:
L'abstraction PerlIO a été introduite dans perl5.003_02 mais n'était plus qu'un
abstraction jusqu'à perl5.7.0. Cependant, pendant ce temps, un certain nombre d'extensions perl ont basculé
à l'utiliser, donc l'API est principalement fixée pour maintenir la compatibilité (source).

L'objectif de l'implémentation est de fournir l'API PerlIO dans une plate-forme flexible et
manière neutre. C'est aussi un essai d'une approche "Object Oriented C, with vtables" qui
peut être appliqué à Perl 6.

Basic Structure
PerlIO est un empilement de couches.

Les bas niveaux de la pile fonctionnent avec les appels de bas niveau du système d'exploitation (fichier
descripteurs en C) entrant et sortant des octets, les couches supérieures du tampon de pile, filtre,
et autrement manipuler les E/S et renvoyer des caractères (ou octets) à Perl. termes au dessus de
et ci-dessous sont utilisés pour désigner le positionnement relatif des couches de la pile.

Une couche contient une "vtable", la table des opérations d'E/S (au niveau C une table de fonction
pointeurs) et les indicateurs d'état. Les fonctions de la vtable implémentent des opérations telles que
« ouvrir », « lire » et « écrire ».

Lorsque des E/S, par exemple "read", sont demandées, la demande part de Perl d'abord vers le bas le
pile en utilisant les fonctions "lecture" de chaque couche, puis en bas l'entrée est demandée à
les services du système d'exploitation, puis le résultat est renvoyé dans la pile, étant finalement
interprété comme des données Perl.

Les requêtes ne vont pas forcément toujours jusqu'au système d'exploitation : c'est
où la mise en mémoire tampon PerlIO entre en jeu.

Quand tu fais un ouvrir() et spécifiez des couches PerlIO supplémentaires à déployer, les couches que vous
spécifier sont "poussés" au-dessus de la pile par défaut déjà existante. Une façon de le voir est
que "le système d'exploitation est à gauche" et "Perl est à droite".

Les couches exactes de cette pile par défaut dépendent de beaucoup de choses : votre
système, version Perl, configuration de temps de compilation Perl et configuration d'exécution Perl.
Voir PerlIO, "PERLIO" dans perlrun, et ouvrez pour plus d'informations.

binmode() fonctionne de la même manière que ouvrir(): par défaut les calques spécifiés sont poussés vers le haut
de la pile existante.

Cependant, notez que même si les couches spécifiées sont "poussées vers le haut" pour ouvrir() et
binmode(), cela ne veut pas dire que les effets sont limités au "top": les couches PerlIO peuvent
être très « actif » et inspecter et affecter les couches également plus profondément dans la pile. Par exemple
il y a un calque appelé "raw" qui "pop" à plusieurs reprises des calques jusqu'à ce qu'il atteigne le premier
couche qui s'est déclarée capable de traiter des données binaires. Les couches "poussées" sont
traitées dans l'ordre de gauche à droite.

sysopen() fonctionne (sans surprise) à un niveau inférieur dans la pile que ouvrir(). For
exemple dans les systèmes Unix ou de type Unix sysopen() agit directement au niveau du fichier
descripteurs : au sens des couches PerlIO, il n'utilise que la couche "unix", qui est une
enveloppe plutôt mince au-dessus des descripteurs de fichiers Unix.

Couches vs Disciplines
La discussion initiale sur la possibilité de modifier le comportement des flux d'E/S a utilisé le terme
« discipline » pour les entités qui ont été ajoutées. Cela est venu (je crois) de l'utilisation de la
terme en « sfio », qui à son tour l'a emprunté aux « disciplines de ligne » sur les terminaux Unix.
Cependant, ce document (et le code C) utilise le terme « couche ».

C'est, je l'espère, un terme naturel étant donné la mise en œuvre, et devrait éviter les connotations
qui sont inhérents aux usages antérieurs de « discipline » pour des choses assez différentes.

Date Structure
La structure de données de base est un PerlIOl :

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

structure _PerlIO
{
PerlIOl * suivant ; /* Couche inférieure */
PerlIO_funcs * onglet ; /* Fonctions pour cette couche */
drapeaux U32 ; /* Divers drapeaux pour l'état */
};

Un "PerlIOl *" est un pointeur vers la structure, et le application le niveau "PerlIO *" est un
pointeur vers un "PerlIOl *" - c'est-à-dire un pointeur vers un pointeur vers la structure. Cela permet au
niveau d'application "PerlIO *" pour rester constant tandis que le réel "PerlIOl *" en dessous
changements. (Comparez le "SV *" de perl qui reste constant tandis que son champ "sv_any" change comme
le type du scalaire change.) Un flux IO est alors en général représenté comme un pointeur vers
cette liste chaînée de "couches".

A noter qu'en raison de la double indirection dans un "PerlIO*", un
"&(perlio->next)" "est" un "PerlIO *", et donc, dans une certaine mesure, au moins une couche peut utiliser le
API "standard" sur la couche suivante.

Une "couche" est composée de deux parties :

1. Les fonctions et attributs de la "classe de couche".

2. Les données par instance pour un descripteur particulier.

Les fonctions et Attributs
Les fonctions et attributs sont accessibles via le membre "tab" (pour table) de "PerlIOl".
Les fonctions (méthodes de la couche "classe") sont figées, et sont définies par le
Type "PerlIO_funcs". Elles sont globalement les mêmes que les fonctions publiques "PerlIO_":

structure _PerlIO_funcs
{
Taille_t fsize ;
caractère * nom ;
Taille_t taille ;
type IV;
IV (*Poussé)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab);
IV (*éclaté)(pTHX_PerlIO *f);
PerlIO * (*Ouvrir)(pTHX_ PerlIO_funcs *onglet,
PerlIO_list_t *couches, IV n,
caractère const * mode,
int fd, int imode, int perm,
PerlIO *ancien,
int narg, SV **args);
IV (*Binmode)(pTHX_PerlIO *f);
SV * (*Getarg)(pTHX_ PerlIO *f, CLONE_PARAMS *param, int indicateurs)
IV (*Fileno)(pTHX_PerlIO *f);
PerlIO * (*Dup)(pTHX_ PerlIO *f, PerlIO *o, CLONE_PARAMS *param, int indicateurs)
/* Fonctions de type Unix - cf disciplines de la ligne sfio */
SSize_t (*Read)(pTHX_PerlIO *f, void *vbuf, Size_t count);
SSize_t (*Non lu)(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 d'où);
Off_t (*Tell)(pTHX_PerlIO *f);
IV (*Fermer)(pTHX_PerlIO *f);
/* Fonctions d'E/S tamponnées de type Stdio */
IV (*Rincer)(pTHX_PerlIO *f);
IV (*Remplir)(pTHX_PerlIO *f);
IV (*Eof)(pTHX_PerlIO *f);
IV (*Erreur)(pTHX_PerlIO *f);
void (*Clearerr)(pTHX_PerlIO *f);
void (*Setlinebuf)(pTHX_PerlIO *f);
/* Fonctions de surveillance de Perl */
STDCHAR * (*Get_base)(pTHX_PerlIO *f);
Size_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,SSize_t cnt);
};

Les premiers membres de la structure donnent une taille de table de fonction pour le contrôle de compatibilité
"nom" pour la couche, la taille à "malloc" pour les données par instance et quelques indicateurs
qui sont des attributs de la classe dans son ensemble (comme s'il s'agit d'une couche tampon), alors
suivre les fonctions qui se répartissent en quatre groupes de base :

1. Fonctions d'ouverture et de configuration

2. Opérations d'E/S de base

3. Options de mise en mémoire tampon de la classe Stdio.

4. Fonctions pour prendre en charge l'accès "rapide" traditionnel de Perl au tampon.

Une couche n'a pas à implémenter toutes les fonctions, mais la table entière doit être
présent. Les slots non implémentés peuvent être NULL (ce qui entraînera une erreur lors de l'appel) ou
peut être rempli avec des stubs pour "hériter" du comportement d'une "classe de base". Cet "héritage"
est fixe pour toutes les instances de la couche, mais comme la couche choisit les stubs à remplir
la table, un "héritage multiple" limité est possible.

Par instance Date
Les données par instance sont conservées en mémoire au-delà de la structure de base PerlIOl, en faisant un
PerlIOl le premier membre de la structure de la couche ainsi :

structure typedef
{
struct _PerlIO base ; /* Informations "classe" de base */
STDCHAR * buf; /* Début du tampon */
STDCHAR * fin; /* Fin de la partie valide du tampon */
STDCHAR * ptr; /* Position actuelle dans le tampon */
Off_t posn; /* Décalage de buf dans le fichier */
Size_t bufsiz; /* Taille réelle du tampon */
IV un mot; /* Tampon d'urgence */
} PerlIOBuf;

De cette façon (comme pour les scalaires de Perl) un pointeur vers un PerlIOBuf peut être traité comme un pointeur
à un PerlIOl.

Couches in l'action.
tableau perlio unix
| |
+---------------+ +----------+ +-------------+
PerlIO ->| |--->| suivant |--->| NULL |
+---------------+ +----------+ +-------------+
| | | tampon | | fd |
+-----------+ | | +--------+
| | +----------+

Ce qui précède tente de montrer comment fonctionne le schéma de couches dans un cas simple. L'application
"PerlIO *" pointe vers une entrée dans le(s) tableau(s) représentant les handles ouverts (alloués). Pour
exemple, les trois premiers emplacements du tableau correspondent à "stdin", "stdout" et "stderr".
Le tableau à son tour pointe vers la couche "supérieure" actuelle pour la poignée - dans ce cas un
instance de la couche tampon générique "perlio". Cette couche à son tour pointe vers la suivante
couche vers le bas - dans ce cas, la couche "unix" de bas niveau.

Ce qui précède est à peu près équivalent à un flux tamponné "stdio", mais avec beaucoup plus
la flexibilité:

· Si le niveau Unix "read"/"write"/"lseek" n'est pas approprié pour (disons) les sockets, le
La couche "unix" peut être remplacée (à l'ouverture ou même dynamiquement) par une couche "socket".

· Différentes poignées peuvent avoir différents schémas de mise en mémoire tampon. La couche "supérieure" pourrait être la
Couche « mmap » si la lecture des fichiers du disque était plus rapide en utilisant « mmap » que « read ». Un
Le flux "sans tampon" peut être implémenté simplement en n'ayant pas de couche tampon.

· Des couches supplémentaires peuvent être insérées pour traiter les données au fur et à mesure qu'elles circulent. C'était le
besoin d'inclure le schéma dans perl 5.7.0+ - nous avions besoin d'un mécanisme pour permettre
données à traduire entre l'encodage interne de perl (conceptuellement au moins Unicode
comme UTF-8) et le format "natif" utilisé par le système. Ceci est fourni par le
Couche ":encoding(xxxx)" qui se situe généralement au-dessus de la couche tampon.

· Une couche peut être ajoutée qui fait "\n" à la traduction CRLF. Cette couche peut être utilisée sur n'importe quel
plate-forme, pas seulement ceux qui font normalement de telles choses.

Par instance drapeau les bits
Les bits de drapeau génériques sont un hybride de drapeaux de style "O_XXXXX" déduits de la chaîne de mode
passé à "PerlIO_open()", et les bits d'état pour les couches tampons typiques.

PERLIO_F_EOF
Fin de fichier.

PERLIO_F_CANWRITE
Les écritures sont autorisées, c'est-à-dire ouvertes comme "w" ou "r+" ou "a", etc.

PERLIO_F_CANREAD
Les lectures sont autorisées, c'est-à-dire ouvertes "r" ou "w+" (ou même "a+" - ick).

PERLIO_F_ERROR
Une erreur s'est produite (pour "PerlIO_error()").

PERLIO_F_TRUNCATE
Tronquer le fichier suggéré par le mode ouvert.

PERLIO_F_APPEND
Toutes les écritures doivent être ajoutées.

PERLIO_F_CRLF
La couche exécute "\n" de type Win32 mappé sur CR,LF pour la sortie et CR,LF mappé sur
"\n" pour la saisie. Normalement, la couche "crlf" fournie est la seule couche qui a besoin d'être dérangée
à propos de ça. "PerlIO_binmode()" dérangera avec ce drapeau plutôt que d'ajouter/supprimer des couches
si le bit "PERLIO_K_CANCRLF" est défini pour la classe de couches.

PERLIO_F_UTF8
Les données écrites dans cette couche doivent être encodées en UTF-8 ; les données fournies par cette couche doivent
être considéré comme codé en UTF-8. Peut être défini sur n'importe quel calque par le calque factice ":utf8". Également défini
sur la couche ":encoding".

PERLIO_F_UNBUF
La couche n'est pas tamponnée - c'est-à-dire que l'écriture sur la couche suivante doit se produire pour chaque écriture sur
cette couche.

PERLIO_F_WRBUF
Le tampon de cette couche contient actuellement des données écrites mais non envoyées au suivant
couche.

PERLIO_F_RDBUF
Le tampon de cette couche contient actuellement les données non consommées lues à partir de la couche inférieure.

PERLIO_F_LINEBUF
La couche est mise en mémoire tampon de ligne. Les données d'écriture doivent être transmises à la couche suivante chaque fois qu'un "\n"
est vu. Toutes les données au-delà du "\n" doivent alors être traitées.

PERLIO_F_TEMP
Le fichier a été "unlink ()"ed, ou doit être supprimé sur "close()".

PERLIO_F_OPEN
La poignée est ouverte.

PERLIO_F_FASTGETS
Cette instance de cette couche prend en charge l'interface "fast "gets"". Normalement défini en fonction
sur "PERLIO_K_FASTGETS" pour la classe et par l'existence de la ou des fonction(s) dans le
table. Cependant, une classe qui fournit normalement cette interface peut avoir besoin de l'éviter sur un
cas particulier. La couche "en attente" doit le faire lorsqu'elle est poussée au-dessus d'un
couche qui ne prend pas en charge l'interface. (Le "sv_gets()" de Perl n'attend pas le
diffuse rapidement le comportement « gets » pour changer au cours d'un « get ».)

Méthodologie in Détails
taille f
Taille_t fsize ;

Taille de la table des fonctions. Ceci est comparé à la valeur que le code PerlIO "connaît" comme
une vérification de compatibilité. Versions futures Au cours de cette réunion, Matthew a obtenu de précieux conseils et Linda lui a demandé de la tenir au courant de ses progrès. être capable de tolérer des couches compilées contre
une ancienne version des en-têtes.

prénom
caractère * nom ;

Le nom de la couche dont ouvrir() méthode que Perl doit invoquer sur ouvrir(). Par exemple
si la couche s'appelle APR, vous appellerez :

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

et Perl sait qu'il doit invoquer le PerlIOAPR_open() méthode mise en œuvre par le
Couche APR.

Taille
Taille_t taille ;

La taille de la structure de données par instance, par exemple :

taillede(PerlIOAPR)

Si ce champ est à zéro alors "PerlIO_pushed" ne malloce rien et suppose
la fonction Pushed du calque effectuera toute manipulation de pile de calques requise - utilisée pour éviter
malloc/overhead gratuit pour les couches factices. Si le champ n'est pas nul, il doit être au moins
la taille de "PerlIOl", "PerlIO_pushed" allouera de la mémoire pour les données de la couche
structures et lier une nouvelle couche sur la pile du flux. (Si la méthode Pushed du calque
renvoie une indication d'erreur indiquant que le calque est à nouveau affiché.)

mots
type IV;

· PERLIO_K_BUFFERED

La couche est tamponnée.

· PERLIO_K_RAW

La couche est acceptable dans une pile binmode (FH) - c'est-à-dire qu'elle n'a pas (ou
se configurer pour ne pas) transformer les octets qui le traversent.

· PERLIO_K_CANCRLF

La couche peut se traduire entre "\n" et les extrémités de ligne CRLF.

· PERLIO_K_FASTGETS

La couche permet l'espionnage de tampon.

· PERLIO_K_MULTIARG

Utilisé lorsque la couche est ouvrir() accepte plus d'arguments que d'habitude. L'extra
les arguments ne doivent pas être placés avant l'argument "MODE". Lorsque ce drapeau est utilisé, c'est
jusqu'à la couche pour valider les arguments.

Poussé
IV (*Poussé)(pTHX_ PerlIO *f,const char *mode, SV *arg);

La seule méthode absolument obligatoire. Appelé lorsque le calque est poussé sur la pile.
L'argument "mode" peut être NULL si cela se produit après l'ouverture. Le "arg" sera non-"NULL"
si une chaîne d'argument a été passée. Dans la plupart des cas, cela devrait appeler "PerlIOBase_pushed()"
pour convertir "mode" dans les drapeaux "PERLIO_F_XXXXX" appropriés en plus de n'importe quel
actions effectuées par la couche elle-même. Si une couche n'attend pas d'argument, elle a besoin
ni enregistrer celui qui lui a été passé, ni fournir "Getarg()" (il pourrait peut-être
"Perl_warn" que l'argument était inattendu).

Renvoie 0 en cas de succès. En cas d'échec, renvoie -1 et doit définir errno.

Sauté
IV (*éclaté)(pTHX_PerlIO *f);

Appelé lorsque le calque est extrait de la pile. Une couche sera normalement sautée après
"Fermer()" est appelé. Mais une couche peut être éclatée sans être fermée si le programme est
gestion dynamique des couches sur le flux. Dans de tels cas, "Popped()" devrait libérer tout
ressources (tampons, tables de traduction, ...) non contenues directement dans la structure de la couche.
Il doit également "Unread()" toutes les données non consommées qui ont été lues et mises en mémoire tampon à partir du
couche en dessous de cette couche, afin qu'elle puisse être re-fournie à ce qui est maintenant
au dessus.

Renvoie 0 en cas de réussite ou d'échec. Si "Popped()" retourne oui puis perlio.c suppose
que soit la couche s'est déclenchée, soit la couche est super spéciale et doit être
retenu pour d'autres raisons. Dans la plupart des cas, il devrait revenir non.

Open
PerlIO * (*Ouvrir)(...) ;

La méthode "Open()" a beaucoup d'arguments car elle combine les fonctions de perl
"open", "PerlIO_open", "sysopen" de perl, "PerlIO_fdopen" et "PerlIO_reopen". Les
le prototype complet est le suivant :

PerlIO * (*Ouvrir)(pTHX_ PerlIO_funcs *onglet,
PerlIO_list_t *couches, IV n,
caractère const * mode,
int fd, int imode, int perm,
PerlIO *ancien,
int narg, SV **args);

Open devrait (peut-être indirectement) appeler "PerlIO_allocate()" pour allouer un slot dans le
table et l'associer aux informations des couches du fichier ouvert, en appelant
"PerlIO_push". Les poules pondeuses est un tableau de toutes les couches destinées au "PerlIO*",
et tous les arguments qui leur sont transmis, n est l'indice dans ce tableau de la couche étant
appelé. La macro "PerlIOArg" renverra un (éventuellement "NULL") SV * pour l'argument
passé à la couche.

Le mode string est une chaîne de type ""fopen()"-like" qui correspondrait à l'expression régulière
"/^[I#]?[rwa]\+?[bt]?$/".

Le préfixe 'I' est utilisé lors de la création de "stdin".."stderr" via special
appels "PerlIO_fdopen" ; le préfixe '#' signifie qu'il s'agit de "sysopen" et que immode et
permanente doit être passé à "PerlLIO_open3" ; 'r' signifie read, 'w' signifie write et 'a'
veux dire apend. Le suffixe '+' signifie que la lecture et l'écriture/l'ajout sont
permis. Le suffixe « b » signifie que le fichier doit être binaire et « t » signifie qu'il s'agit de texte.
(Presque toutes les couches doivent effectuer les E/S en mode binaire et ignorer les bits b/t. Le
La couche ":crlf" doit être poussée pour gérer la distinction.)

If et les sites anciens n'est pas "NULL" alors il s'agit d'un "PerlIO_reopen". Perl lui-même n'utilise pas cela
(encore ?) et la sémantique est un peu vague.

If fd pas négatif alors c'est le descripteur de fichier numérique fd, qui sera ouvert dans un
manière compatible avec la chaîne de mode fournie, l'appel est donc équivalent à
"PerlIO_fdopen". Dans ce cas nargs sera nul.

If nargs est supérieur à zéro alors il donne le nombre d'arguments passés à "open",
sinon ce sera 1 si par exemple "PerlIO_open" a été appelé. Dans des cas simples
SvPV_nolen(*args) est le chemin d'accès à ouvrir.

Si un calque fournit "Open()", il devrait normalement appeler la méthode "Open()" du prochain calque
vers le bas (le cas échéant), puis se pousse vers le haut si cela réussit. "PerlIOBase_open" est
à condition de faire exactement cela, donc dans la plupart des cas, vous n'avez pas à écrire votre propre
Méthode "Ouvrir()". Si cette méthode n'est pas définie, d'autres couches peuvent avoir des difficultés
se poussant dessus pendant l'ouverture.

Si "PerlIO_push" a été exécuté et que l'ouverture a échoué, il doit "PerlIO_pop" lui-même, car
si ce n'est pas le cas, la couche ne sera pas supprimée et peut causer de graves problèmes.

Renvoie "NULL" en cas d'échec.

Mode bin
IV (*Binmode)(pTHX_PerlIO *f);

Optionnel. Utilisé lorsque le calque ":raw" est poussé (explicitement ou à la suite de binmode(FH)).
Si ce n'est pas le cas, la couche apparaîtra. S'il est présent, la couche doit être configurée en binaire (ou
pop lui-même) et renvoie 0. S'il renvoie -1 pour l'erreur, "binmode" échouera avec le calque
toujours sur la pile.

Getarg
SV * (*Getarg)(pTHX_PerlIO *f,
CLONE_PARAMS *param, int indicateurs);

Optionnel. S'il est présent, il doit renvoyer un SV * représentant l'argument de chaîne passé à
la couche lorsqu'elle a été poussée. par exemple ":encoding(ascii)" renverrait un SvPV avec une valeur
"ascii". (arrêter et drapeaux les arguments peuvent être ignorés dans la plupart des cas)

"Dup" utilise "Getarg" pour récupérer l'argument initialement passé à "Pushed", donc vous
doit implémenter cette fonction si votre couche a un argument supplémentaire à "Pushed" et
jamais être "dupé".

Fichierno
IV (*Fileno)(pTHX_PerlIO *f);

Renvoie le descripteur de fichier numérique Unix/Posix pour le handle. Normalement
"PerlIOBase_fileno()" (qui demande simplement la couche suivante vers le bas) suffira pour cela.

Renvoie -1 en cas d'erreur, ce qui est considéré comme incluant le cas où la couche ne peut pas
fournir un tel descripteur de fichier.

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

XXX : Besoin de plus de documents.

Utilisé dans le cadre du processus de "clonage" lorsqu'un thread est généré (auquel cas, param
être non NULL) et lorsqu'un flux est dupliqué via '&' dans le "open".

Similaire à "Open", renvoie PerlIO* en cas de succès, "NULL" en cas d'échec.

Lire
SSize_t (*Read)(pTHX_PerlIO *f, void *vbuf, Size_t count);

Opération de lecture de base.

Appelera généralement "Fill" et manipulera les pointeurs (éventuellement via l'API).
"PerlIOBuf_read()" peut convenir aux classes dérivées qui fournissent des "gets rapides"
méthodes.

Renvoie les octets réels lus, ou -1 en cas d'erreur.

Non lus
SSize_t (*Non lu)(pTHX_PerlIO *f,
const void *vbuf, Size_t count);

Un sur-ensemble de "ungetc()" de stdio. Devrait organiser des lectures futures pour voir les octets dans
"vbuf". S'il n'y a pas de meilleure implémentation, alors "PerlIOBase_unread()"
fournit la fonction en poussant une "fausse" couche "en attente" au-dessus de la couche appelante.

Renvoie le nombre de caractères non lus.

Écrire
SSize_t (*Write)(PerlIO *f, const void *vbuf, Size_t count);

Opération d'écriture de base.

Renvoie les octets écrits ou -1 en cas d'erreur.

Seek
IV (*Seek)(pTHX_PerlIO *f, Off_t offset, int d'où);

Positionnez le pointeur de fichier. Devrait normalement appeler sa propre méthode « Flush », puis le
Méthode de "recherche" de la couche suivante vers le bas.

Renvoie 0 en cas de succès, -1 en cas d'échec.

Avertir
Off_t (*Tell)(pTHX_PerlIO *f);

Renvoie le pointeur de fichier. Peut être basé sur le concept de position mis en cache par couches pour éviter
aérien.

Renvoie -1 en cas d'échec d'obtention du pointeur de fichier.

Fermer
IV (*Fermer)(pTHX_PerlIO *f);

Fermez le flux. Devrait normalement appeler "PerlIOBase_close()" pour se vider et se fermer
couches ci-dessous, puis désallouer toutes les structures de données (tampons, tables de traduction,
...) pas détenues directement dans la structure de données.

Renvoie 0 en cas de succès, -1 en cas d'échec.

Flush
IV (*Rincer)(pTHX_PerlIO *f);

Devrait rendre l'état du flux cohérent avec les couches ci-dessous. C'est-à-dire que toute écriture mise en mémoire tampon
les données doivent être écrites et la position du fichier des couches inférieures ajustée pour les données lues à partir de
ci-dessous mais pas réellement consommé. (Si peut-être "Unread()" de telles données vers le bas
couche.)

Renvoie 0 en cas de succès, -1 en cas d'échec.

Niveau de remplissage
IV (*Remplir)(pTHX_PerlIO *f);

Le tampon de cette couche doit être rempli (pour la lecture) à partir de la couche ci-dessous. Lorsque vous
couche PerlIOBuf "sous-classe", vous souhaitez utiliser sa _lire méthode et de fournir votre propre
fill, qui remplit le tampon de PerlIOBuf.

Renvoie 0 en cas de succès, -1 en cas d'échec.

Eof
IV (*Eof)(pTHX_PerlIO *f);

Renvoie l'indicateur de fin de fichier. "PerlIOBase_eof()" est normalement suffisant.

Renvoie 0 en fin de fichier, 1 sinon en fin de fichier, -1 en cas d'erreur.

Erreur
IV (*Erreur)(pTHX_PerlIO *f);

Indicateur d'erreur de retour. "PerlIOBase_error()" est normalement suffisant.

Renvoie 1 s'il y a une erreur (généralement lorsque "PERLIO_F_ERROR" est défini), 0 sinon.

plus clair
void (*Clearerr)(pTHX_PerlIO *f);

Effacer les indicateurs de fin de fichier et d'erreur. Devrait appeler "PerlIOBase_clearerr()" pour définir le
Les drapeaux "PERLIO_F_XXXXX", qui peuvent suffire.

Setlinebuf
void (*Setlinebuf)(pTHX_PerlIO *f);

Marquez le flux comme ligne tamponnée. "PerlIOBase_setlinebuf()" définit le PERLIO_F_LINEBUF
flag et est normalement suffisant.

Obtenir_base
STDCHAR * (*Get_base)(pTHX_PerlIO *f);

Allouez (si ce n'est déjà fait) le tampon de lecture pour cette couche et retournez le pointeur vers
ce. Renvoie NULL en cas d'échec.

Obtenir_bufsiz
Size_t (*Get_bufsiz)(pTHX_PerlIO *f);

Renvoie le nombre d'octets que le dernier "Fill()" a mis dans le tampon.

Get_ptr
STDCHAR * (*Get_ptr)(pTHX_PerlIO *f);

Renvoie le pointeur de lecture actuel relatif au tampon de cette couche.

Get_cnt
SSize_t (*Get_cnt)(pTHX_PerlIO *f);

Renvoie le nombre d'octets restant à lire dans le tampon courant.

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

Ajustez le pointeur de lecture et le nombre d'octets pour correspondre à "ptr" et/ou "cnt". Les
l'application (ou la couche ci-dessus) doit s'assurer qu'ils sont cohérents. (La vérification est autorisée par
le paranoïaque.)

Utilitaires
Pour demander la couche suivante, utilisez PerlIONext(PerlIO *f).

Pour vérifier qu'un PerlIO* est valide, utilisez PerlIOValid(PerlIO *f). (Tout ce que cela fait est vraiment
juste pour vérifier que le pointeur n'est pas NULL et que le pointeur derrière celui-ci n'est pas NULL.)

PerlIOBase(PerlIO *f) renvoie le pointeur "Base", ou en d'autres termes, le "PerlIOl*"
aiguille.

PerlIOSelf(PerlIO* f, type) renvoie le transtypage PerlIOBase en un type.

Perl_PerlIO_or_Base(PerlIO* f, callback, base, failure, args) appelle soit le rappeler
à partir des fonctions de la couche f (juste par le nom de la fonction IO, comme "Read") avec
le args, ou s'il n'y a pas de rappel, appelle le base version du rappel avec le
mêmes arguments, ou si le f n'est pas valide, définissez errno sur EBADF et retournez échec.

Perl_PerlIO_or_fail(PerlIO* f, callback, failure, args) appelle soit le rappeler du système
fonctions de la couche f couplé à args, ou s'il n'y a pas de rappel, définissez errno sur
EINVAL. Ou si le f n'est pas valide, définissez errno sur EBADF et retournez échec.

Perl_PerlIO_or_Base_void(PerlIO* f, callback, base, args) appelle soit le rappeler du système
fonctions de la couche f couplé à args, ou s'il n'y a pas de rappel, appelle le base
version du rappel avec les mêmes arguments, ou si le f n'est pas valide, définissez errno sur EBADF.

Perl_PerlIO_or_fail_void(PerlIO* f, callback, args) appelle soit le rappeler du système
fonctions de la couche f couplé à args, ou s'il n'y a pas de rappel, définissez errno sur
EINVAL. Ou si le f n'est pas valide, définissez errno sur EBADF.

Exécution PerlIO Couches
Si vous trouvez le document de mise en œuvre peu clair ou insuffisant, examinez les
Implémentations de la couche PerlIO, qui incluent :

· Implémentations C

Le perlio.c et perliol.h dans le noyau Perl implémenter "unix", "perlio", "stdio",
"crlf", "utf8", "byte", "raw", "pending", et aussi les "mmap" et "win32"
couches le cas échéant. (Le "win32" est actuellement inachevé et inutilisé, pour voir ce qui est
utilisé à la place dans Win32, voir « Interrogation des couches de descripteurs de fichiers » dans PerlIO .)

PerlIO::encoding, PerlIO::scalar, PerlIO::via dans le noyau Perl.

PerlIO::gzip et APR::PerlIO (mod_perl 2.0) sur CPAN.

· Implémentations Perl

PerlIO::via::QuotedPrint dans le noyau Perl et PerlIO::via::* sur CPAN.

Si vous créez une couche PerlIO, vous voudrez peut-être être paresseux, en d'autres termes, implémenter
uniquement les méthodes qui vous intéressent. Les autres méthodes que vous pouvez soit remplacer par le
méthodes "vierges"

PerlIOBase_noop_ok
PerlIOBase_noop_fail

(qui ne font rien et renvoient zéro et -1, respectivement) ou pour certaines méthodes, vous pouvez
assumer un comportement par défaut en utilisant une méthode NULL. La méthode Open recherche de l'aide dans le
couche « parent ». Le tableau suivant résume le comportement :

comportement de la méthode avec NULL

Clearerr PerlIOBase_clearerr
Fermer PerlIOBase_close
Dup PerlIOBase_dup
Eof PerlIOBase_eof
Erreur PerlIOBase_error
Fichierno PerlIOBase_fileno
Remplir ÉCHEC
Rincer le SUCCÈS
Getarg SUCCÈS
ÉCHEC de Get_base
ÉCHEC de Get_bufsiz
ÉCHEC Get_cnt
Get_ptr ÉCHEC
Ouvrir HÉRITÉ
Succès éclaté
SUCCÈS poussé
Lire PerlIOBase_read
Chercher l'ÉCHEC
ÉCHEC de Set_cnt
ÉCHEC de Set_ptrcnt
Setlinebuf PerlIOBase_setlinebuf
Dites ÉCHEC
PerlIOBase_unread non lu
Écrire ÉCHEC

FAILURE Définissez errno (sur EINVAL dans Unixish, sur LIB$_INVARG dans VMS) et
return -1 (pour les valeurs de retour numériques) ou NULL (pour les pointeurs)
HÉRITÉ Hérité de la couche ci-dessous
SUCCESS Return 0 (pour les valeurs de retour numériques) ou un pointeur

Core Couches
Le fichier "perlio.c" fournit les couches suivantes :

"unix"
Une couche basique non tamponnée qui appelle Unix/POSIX "read()", "write()", "lseek()",
"proche()". Pas de mise en mémoire tampon. Même sur les plateformes qui font la distinction entre O_TEXT et
O_BINARY cette couche est toujours O_BINARY.

"perlio"
Une couche tampon générique très complète qui fournit l'ensemble de l'API PerlIO. Il est
également destiné à être utilisé comme "classe de base" pour d'autres couches. (Par exemple son "Lire()"
est implémentée en termes de méthodes "Get_cnt()"/"Get_ptr()"/"Set_ptrcnt()").

"perlio" sur "unix" fournit un remplacement complet pour stdio comme on le voit via l'API PerlIO.
C'est la valeur par défaut pour USE_PERLIO lorsque le stdio du système n'autorise pas le "fast
obtient", et qui ne font pas la distinction entre "O_TEXT" et "O_BINARY".

"stdio"
Une couche qui fournit l'API PerlIO via le schéma de couches, mais l'implémente en
système d'appel stdio. C'est (actuellement) la valeur par défaut si stdio du système fournit
un accès suffisant pour permettre l'accès "fast get" de perl et qui ne distingue pas
entre "O_TEXT" et "O_BINARY".

"crlf"
Une couche dérivée en utilisant "perlio" comme classe de base. Il fournit "\n" de type Win32 à CR,LF
Traduction. Peut être appliqué au-dessus de "perlio" ou servir de couche tampon elle-même.
"crlf" sur "unix" est la valeur par défaut si le système fait la distinction entre "O_TEXT" et
"O_BINARY" s'ouvre. (À un moment donné, "unix" sera remplacé par une couche Win32 IO "native"
sur cette plate-forme, car la couche de lecture/écriture de Win32 présente divers inconvénients.) La couche "crlf"
est un modèle raisonnable pour une couche qui transforme les données d'une manière ou d'une autre.

"mmap"
Si Configure détecte des fonctions "mmap()", cette couche est fournie (avec "perlio" comme
"base") qui effectue des opérations de "lecture" en mmap()le fichier. L'amélioration des performances est
marginal sur les systèmes modernes, il est donc principalement là comme preuve de concept. Il est probable
être dégroupé du cœur à un moment donné. La couche "mmap" est un modèle raisonnable
pour une couche "dérivée" minimaliste.

"en attendant"
Un dérivé "interne" de "perlio" qui peut être utilisé pour fournir Non lu() fonction
pour les couches qui n'ont pas de tampon ou ne peuvent pas être dérangées. (Fondamentalement, cette couche est
"Remplir ()" se détache de la pile et reprend ainsi la lecture à partir de la couche ci-dessous.)

"cru"
Un calque factice qui n'existe jamais dans la pile de calques. Au lieu de cela, lorsqu'il est « poussé », il est en fait
fait éclater la pile en se supprimant, il appelle ensuite l'entrée de la table de fonction Binmode sur tous les
couches dans la pile - normalement cela (via PerlIOBase_binmode) supprime toutes les couches qui
n'ont pas le bit "PERLIO_K_RAW" défini. Les calques peuvent modifier ce comportement en définissant leur
propre entrée Binmode.

"utf8"
Une autre couche factice. Lorsqu'il est poussé, il s'affiche et définit le drapeau "PERLIO_F_UTF8" sur
la couche qui était (et est à nouveau) le sommet de la pile.

en outre perlio.c fournit également un certain nombre de fonctions "PerlIOBase_xxxx()" qui sont
destiné à être utilisé dans les emplacements de table des classes qui n'ont pas besoin de faire quoi que ce soit de spécial
pour une méthode particulière.

Extension Couches
Les couches peuvent être rendues disponibles par des modules d'extension. Lorsqu'une couche inconnue est rencontrée
le code PerlIO effectuera l'équivalent de :

utiliser la « couche » PerlIO ;

Où couche est la couche inconnue. PerlIO.pm tentera alors de :

nécessite PerlIO::layer;

Si après ce processus, la couche n'est toujours pas définie, l'"ouverture" échouera.

Les couches d'extension suivantes sont fournies avec perl :

":codage"
utiliser l'encodage ;

rend cette couche disponible, bien que PerlIO.pm "sait" où le trouver. C'est un
exemple d'une couche qui prend un argument comme on l'appelle ainsi :

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

":scalaire"
Prend en charge la lecture et l'écriture de données sur un scalaire.

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

Lorsqu'un handle est ainsi ouvert, lit alors les octets get à partir de la valeur de chaîne de $scalaire et
écrit changer la valeur. Dans les deux cas, la position en $scalaire commence par zéro mais peut
être modifié via « chercher » et déterminé via « dire ».

Veuillez noter que cette couche est implicite lors de l'appel ouvrir() Ainsi:

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

":passant par"
Fourni pour permettre aux couches d'être implémentées en tant que code Perl. Par exemple:

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

Voir PerlIO::via pour plus de détails.

TOUT

Ce qu'il faut faire pour améliorer ce document.

· Expliquer comment faire un fh valide sans passer par ouvrir()(c'est-à-dire appliquer une couche). Pour
exemple si le fichier n'est pas ouvert via perl, mais que nous voulons récupérer un fh, comme ça
a été ouvert par Perl.

Comment PerlIO_apply_layera s'intègre-t-il, où sa documentation a-t-elle été rendue publique ?

Actuellement, l'exemple pourrait être quelque chose comme ceci :

PerlIO *foo_to_PerlIO(pTHX_ char *mode, ...)
{
char *mode; /* "w", "r", etc */
const char *layers = ":APR"; /* le nom du calque */
PerlIO *f = PerlIO_allocate(aTHX);
si (!f) {
renvoie NULL ;
}

PerlIO_apply_layers(aTHX_f, mode, calques);

si (f) {
PerlIOAPR *st = PerlIOSoi(f, PerlIOAPR);
/* remplir la st struct, comme dans _open() */
st->fichier = fichier ;
PerlIOBase(f)->flags |= PERLIO_F_OPEN;

retour f;
}
renvoie NULL ;
}

· corriger/ajouter la documentation aux endroits marqués comme XXX.

· Le traitement des erreurs par la couche n'est pas précisé. par exemple quand $! devrait être réglé
explicitement, lorsque la gestion des erreurs doit être simplement déléguée à la couche supérieure.

Probablement donner quelques conseils sur l'utilisation SETERRNO() ou des pointeurs vers où ils peuvent être trouvés.

· Je pense qu'il serait utile de donner des exemples concrets pour faciliter la compréhension
l'API. Bien sûr, je suis d'accord pour dire que l'API doit être concise, mais comme il n'y a pas de
deuxième document qui est plus un guide, je pense que ça faciliterait le démarrage
avec la doc qui est une API, mais qui contient des exemples dans des endroits où les choses sont
pas clair, à une personne qui n'est pas (encore) un gourou de PerlIO.

Utilisez perliol en ligne en utilisant les services onworks.net