CONTENU

  • NOM
  • SYNOPSIS
  • DESCRIPTION
    • Coexistence avec stdio
    • Fonctions de "Fast gets"
    • Autres fonctions

NOM

perlapio - interface d'abstraction d'entrée-sortie de perl.

SYNOPSIS

#define PERLIO_NOT_STDIO 0    /* For co-existence with stdio only */#include            /* Usually via #include  */

PerlIO *PerlIO_stdin(void);
PerlIO *PerlIO_stdout(void);
PerlIO *PerlIO_stderr(void);

PerlIO *PerlIO_open(const char *path,const char *mode);
PerlIO *PerlIO_fdopen(int fd, const char *mode);
PerlIO *PerlIO_reopen(const char *path,/* deprecated */
        const char *mode, PerlIO *old);
int     PerlIO_close(PerlIO *f);

int     PerlIO_stdoutf(const char *fmt,...)
int     PerlIO_puts(PerlIO *f,const char *string);
int     PerlIO_putc(PerlIO *f,int ch);
SSize_t PerlIO_write(PerlIO *f,const void *buf,size_t numbytes);
int     PerlIO_printf(PerlIO *f, const char *fmt,...);
int     PerlIO_vprintf(PerlIO *f, const char *fmt, va_list args);
int     PerlIO_flush(PerlIO *f);

int     PerlIO_eof(PerlIO *f);
int     PerlIO_error(PerlIO *f);
void    PerlIO_clearerr(PerlIO *f);

int     PerlIO_getc(PerlIO *d);
int     PerlIO_ungetc(PerlIO *f,int ch);
SSize_t PerlIO_read(PerlIO *f, void *buf, size_t numbytes);

int     PerlIO_fileno(PerlIO *f);

void    PerlIO_setlinebuf(PerlIO *f);

Off_t   PerlIO_tell(PerlIO *f);
int     PerlIO_seek(PerlIO *f, Off_t offset, int whence);
void    PerlIO_rewind(PerlIO *f);

int     PerlIO_getpos(PerlIO *f, SV *save);/* prototype changed */
int     PerlIO_setpos(PerlIO *f, SV *saved);/* prototype changed */

int     PerlIO_fast_gets(PerlIO *f);
int     PerlIO_has_cntptr(PerlIO *f);
SSize_t PerlIO_get_cnt(PerlIO *f);
char   *PerlIO_get_ptr(PerlIO *f);
void    PerlIO_set_ptrcnt(PerlIO *f, char *ptr, SSize_t count);

int     PerlIO_canset_cnt(PerlIO *f);/* deprecated */
void    PerlIO_set_cnt(PerlIO *f, int count);/* deprecated */

int     PerlIO_has_base(PerlIO *f);
char   *PerlIO_get_base(PerlIO *f);
SSize_t PerlIO_get_bufsiz(PerlIO *f);

PerlIO *PerlIO_importFILE(FILE *stdio, const char *mode);
FILE   *PerlIO_exportFILE(PerlIO *f, const char *mode);
FILE   *PerlIO_findFILE(PerlIO *f);
void    PerlIO_releaseFILE(PerlIO *f,FILE *stdio);

int     PerlIO_apply_layers(PerlIO *f, const char *mode,
                                                  const char *layers);
int     PerlIO_binmode(PerlIO *f, int ptype, int imode,
                                                  const char *layers);
void    PerlIO_debug(const char *fmt,...);

DESCRIPTION

Le code source de Perl, et les extensions qui veulent une portabilité maximale, doivent utiliser les fonctions ci-dessus au lieu de celles définies dans le code C ANSI. stdio.h. Les en-têtes de perl (en particulier "perlio.h") vont #define les au mécanisme d'entrée/sortie sélectionné au moment de Configure.

Les fonctions sont calquées sur celles de stdio.h, mais l'ordre des paramètres a été "toiletté un peu".

PerlIO * prend la place de FILE *. Comme FILE *, il devrait être traité comme opaque (il est probablement sûr de supposer que c'est un pointeur vers quelque chose).

Il existe actuellement deux implémentations :

1. USE_STDIO

Tous les éléments ci-dessus sont #définis aux fonctions stdio ou sont des fonctions d'enveloppe triviales qui appellent stdio. Dans ce cas seulement PerlIO * est un FILE *. C'est l'implémentation par défaut depuis que l'abstraction a été introduite dans perl5.003_02.

2. USE_PERLIO

Introduit juste après perl5.7.0, il s'agit d'une réimplémentation de l'abstraction ci-dessus qui permet à perl d'avoir plus de contrôle sur la façon dont les entrées-sorties sont effectuées car elle découple les entrées-sorties de la façon dont le système d'exploitation et la bibliothèque C choisissent de faire les choses. Pour USE_PERLIO PerlIO * a une couche supplémentaire d'indirection - c'est un pointeur vers un pointeur. Cela permet à PerlIO * de rester avec une valeur connue tout en échangeant l'implémentation autour en dessous. au moment de l'exécution. Dans ce cas, tous les éléments ci-dessus sont des fonctions vraies (mais très simples) qui appellent l'implémentation sous-jacente.

C'est la seule implémentation pour laquelle PerlIO_apply_layers() fait quelque chose d'"intéressant".

L'implémentation USE_PERLIO est décrite dans perliol.

Parce que "perlio.h" est une couche mince (pour l'efficacité), la sémantique de ces fonctions est quelque peu dépendante de l'implémentation sous-jacente. Lorsque ces variations sont comprises, elles sont notées ci-dessous.

Sauf indication contraire, les fonctions renvoient 0 en cas de succès, ou une valeur négative (généralement... EOF qui est habituellement -1) et définissent errno en cas d'erreur.

PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()

Utilisez-les plutôt que stdin, stdout, stderr. Ils sont écrits de manière à ressembler à des "appels de fonction" plutôt qu'à des variables, car cela facilite l'utilisation de les faire appels de fonction si la plateforme ne peut pas exporter de données vers les modules chargés, ou si (disons) différents "threads" peuvent avoir des valeurs différentes.

PerlIO_open(path, mode), PerlIO_fdopen(fd,mode)

Ces fonctions correspondent à fopen()/fdopen() et les arguments sont les mêmes. Retourner NULL et définit errno s'il y a une erreur. Il peut y avoir une limite d'implémentation sur le nombre de handles ouverts, qui peut être inférieure à la limite sur le nombre de fichiers ouverts -. errno peut ne pas être défini lorsque NULL est retourné si cette limite est dépassée.

PerlIO_reopen(path,mode,f)

Bien que cela existe actuellement dans les deux implémentations, perl lui-même ne l'utilise pas. Comme perl ne l'utilise pas, il n'est pas bien testé.

Perl préfère dup le nouveau descripteur de bas niveau au descripteur utilisé par le PerlIO existant. Cela peut devenir le comportement de cette fonction à l'avenir.

PerlIO_printf(f,fmt,...), PerlIO_vprintf(f,fmt,a)

Ce sont les équivalents de fprintf()/vfprintf().

PerlIO_stdoutf(fmt,...)

Ceci est l'équivalent de printf(). printf est #défini à cette fonction, il est donc (actuellement) légal de l'utiliser. printf(fmt,...) dans les sources perl.

PerlIO_read(f,buf,count), PerlIO_write(f,buf,count)

Elles correspondent fonctionnellement à fread() et fwrite() mais les arguments et les valeurs de retour sont différents. Les signatures PerlIO_read() et PerlIO_write() ont été modelées sur les fonctions read() et write() de bas niveau plus saines à la place : L'argument "file" est passé en premier, il n'y a qu'un seul "count", et la valeur de retour peut distinguer entre erreur et EOF.

Renvoie un nombre d'octets en cas de succès (qui peut être zéro ou positif), renvoie une valeur négative et met errno en cas d'erreur. Selon l'implémentation errno peut être EINTR si l'opération a été interrompue par un signal.

PerlIO_close(f)

Selon l'implémentation errno peut être EINTR si l'opération a été interrompue par un signal.

PerlIO_puts(f,s), PerlIO_putc(f,c)

Ces fonctions correspondent à fputs() et fputc(). Notez que les arguments ont été révisés pour avoir "file" en premier.

PerlIO_ungetc(f,c)

Ceci correspond à ungetc(). Notez que les arguments ont été révisés pour avoir "file" en premier. S'arrange pour que la prochaine opération de lecture renvoie l'octet. c. Malgré le "caractère" implicite dans le nom, seules les valeurs comprises dans la plage 0..0xFF sont définies. Renvoie l'octet c en cas de succès ou -1 (EOF) en cas d'erreur. Le nombre d'octets qui peuvent être "repoussés" peut varier, seul 1 caractère est certain, et seulement s'il s'agit du dernier caractère qui a été lu dans le handle.

PerlIO_getc(f)

Ceci correspond à getc(). Malgré le c dans le nom, seule la plage d'octets 0..0xFF est supportée. Renvoie le caractère lu ou -1 (EOF) en cas d'erreur.

PerlIO_eof(f)

Ceci correspond à feof(). Renvoie une indication vrai/faux pour savoir si le handle est à la fin du fichier. Pour les périphériques terminaux, cela peut ou non être "collant" selon l'implémentation. L'indicateur est effacé par PerlIO_seek(), ou PerlIO_rewind().

PerlIO_error(f)

Ceci correspond à ferror(). Renvoie une indication vrai/faux pour savoir s'il y a eu une erreur d'entrée-sortie sur le handle.

PerlIO_fileno(f)

Ceci correspond à fileno(), notez que sur certaines plateformes, la signification de "fileno" peut ne pas correspondre à Unix. Renvoie -1 si le handle n'a pas de descripteur ouvert associé.

PerlIO_clearerr(f)

Cela correspond à clearerr(), c'est-à-dire qu'elle efface les drapeaux 'error' et (généralement) 'eof' pour le "stream". Ne renvoie pas de valeur.

PerlIO_flush(f)

Ceci correspond à fflush(). Envoie toutes les données d'écriture tamponnées au fichier sous-jacent. Si elle est appelée avec NULL cela peut vider tous les flux ouverts (ou le core dump avec certaines implémentations USE_STDIO). Appeler sur un handle ouvert en lecture seule, ou sur lequel la dernière opération était une lecture de quelque sorte peut conduire à un comportement non défini sur certaines implémentations USE_STDIO. L'implémentation de USE_PERLIO (couches) essaie de mieux se comporter : elle vide tous les flux ouverts lorsqu'on lui transmet NULL, et tente de conserver les données sur les flux lus soit dans le tampon, soit en recherchant le handle de la position logique actuelle.

PerlIO_seek(f,offset,whence)

Ceci correspond à fseek(). Envoie des données d'écriture en mémoire tampon au fichier sous-jacent, ou rejette toute donnée de lecture en mémoire tampon, puis positionne le descripteur de fichier comme spécifié par. offset et d'où (sic). C'est la chose correcte à faire quand on passe de la lecture à l'écriture sur le même handle (voir les problèmes avec PerlIO_flush() ci-dessus). L'offset est de type Off_t qui est une valeur perl Configure qui peut ne pas être la même que celle de stdio. off_t.

PerlIO_tell(f)

Ceci correspond à ftell(). Renvoie la position actuelle du fichier, ou (Off_t) -1 en cas d'erreur. Peut juste retourner la valeur que le système "connaît" sans faire un appel système ou vérifier le descripteur de fichier sous-jacent (donc l'utilisation sur des descripteurs de fichiers partagés n'est pas sûre sans un PerlIO_seek()). La valeur de retour est de type Off_t qui est une valeur perl Configure qui peut ne pas être la même que celle de stdio. off_t.

PerlIO_getpos(f,p), PerlIO_setpos(f,p)

Ils correspondent (vaguement) à fgetpos() et fsetpos(). Plutôt que le Fpos_t de stdio, ils attendent qu'une "valeur scalaire Perl" soit passée. Ce qui est stocké là doit être considéré comme opaque. La disposition des données peut varier d'un handle à l'autre. Lorsque l'on n'utilise pas stdio ou si l'on ne dispose pas des appels stdio alors ils sont implémentés en termes de PerlIO_tell() et PerlIO_seek().

PerlIO_rewind(f)

Ceci correspond à rewind(). Il est généralement défini comme étant

PerlIO_seek(f,(Off_t)0L, SEEK_SET);
PerlIO_clearerr(f);
PerlIO_tmpfile()

Cela correspond à tmpfile(), c'est-à-dire qu'il renvoie un PerlIO anonyme ou NULL en cas d'erreur. Le système tentera de supprimer automatiquement le fichier lors de sa fermeture. Sous Unix, le fichier est généralement unlink-ed juste après sa création, donc la façon dont il est fermé n'a pas d'importance. Sur d'autres systèmes, le fichier ne peut être supprimé que s'il est fermé via PerlIO_close() et/ou si le programme sort via exit. Selon l'implémentation, il peut y avoir des "conditions de course" qui permettent à d'autres processus d'accéder au fichier, bien qu'en général il sera plus sûr à cet égard que les schémas ad. hoc.

PerlIO_setlinebuf(f)

Ceci correspond à setlinebuf(). Ne renvoie pas de valeur. Ce qui constitue une "ligne" dépend de l'implémentation mais signifie généralement que l'écriture de "n" vide le tampon. Ce qui se passe avec des choses comme "cecinthat" est incertain. (Perl core l'utilise seulement lors du " dumping " ; cela n'a rien à voir avec le $| auto-flush).

Coexistence avec stdio

Il y a un support sommaire pour la coexistence de PerlIO avec stdio. Évidemment si PerlIO est implémenté en termes de stdio il n'y a pas de problème. Cependant, dans d'autres cas, alors des mécanismes doivent exister pour créer un FILE * qui peut être passé au code de la bibliothèque qui va utiliser des appels stdio.

La première étape est d'ajouter cette ligne :

#define PERLIO_NOT_STDIO 0

avant y compris tout fichier d'en-tête perl. (Cela deviendra probablement la valeur par défaut à un moment donné). Cela empêche "perlio.h" de tenter de #définir des fonctions stdio sur des fonctions PerlIO.

Le code XS est probablement mieux en utilisant "typemap" s'il attend des arguments FILE *. Le standard typemap sera ajusté pour comprendre tout changement dans ce domaine.

PerlIO_importFILE(f,mode)

Utilisé pour obtenir un PerlIO * à partir d'un FILE *.

L'argument mode doit être une chaîne comme celle qui serait passée à fopen/PerlIO_open. S'il est NULL alors - pour le support de l'héritage - le code va (en fonction de la plate-forme et de l'implémentation) soit tenter de déterminer empiriquement le mode dans lequel... f est ouvert, soit utiliser "r+" pour indiquer un flux de lecture/écriture.

Une fois appelé, le FILE * doit SEULEMENT être fermé en appelant PerlIO_close() sur le PerlIO * retourné.

Le PerlIO est configuré en mode texte. Utilisez PerlIO_binmode si ce n'est pas le mode souhaité.

Ceci est pas l'inverse de PerlIO_exportFILE().

PerlIO_exportFILE(f,mode)

Étant donné un PerlIO * crée un FILE 'natif' * approprié pour être passé au code s'attendant à être compilé et lié avec ANSI C. stdio.h. L'argument mode doit être une chaîne de caractères comme celle qui serait passée à fopen/PerlIO_open. S'il est NULL alors - pour le support de l'héritage - le FILE * est ouvert dans le même mode que le PerlIO *.

Le fait qu'un tel FILE * ait été "exporté" est enregistré (normalement en poussant une nouvelle "couche" :stdio sur le PerlIO *), ce qui peut affecter les futures opérations PerlIO sur le PerlIO * original. Vous ne devriez pas appeler fclose() sur le fichier à moins que vous n'appeliez PerlIO_releaseFILE() pour le dissocier de PerlIO *. (N'utilisez pas PerlIO_importFILE() pour effectuer la dissociation).

L'appel répété de cette fonction créera un FILE * à chaque appel (et poussera également une couche :stdio à chaque fois).

PerlIO_releaseFILE(p,f)

L'appel à PerlIO_releaseFILE informe PerlIO que toute utilisation de FILE * est terminée. Il est retiré de la liste des FILE * 'exportés', et le PerlIO * associé devrait revenir à son comportement original.

Utilisez ceci pour dissocier un fichier d'un PerlIO * qui a été associé en utilisant PerlIO_exportFILE().

PerlIO_findFILE(f)

Renvoie un FICHIER natif * utilisé par une couche stdio. S'il n'y en a pas, il en créera un avec PerlIO_exportFILE. Dans les deux cas, le FILE * doit être considéré comme appartenant au sous-système PerlIO et ne doit être fermé qu'en appelant. PerlIO_close().

"Fonctions "Fast gets

En plus de l'API de type standard définie jusqu'à présent ci-dessus, il existe une interface "d'implémentation" qui permet à perl d'obtenir les internes de PerlIO. Les appels suivants correspondent aux diverses macros FILE_xxx déterminées par Configure - ou leur équivalent dans d'autres implémentations. Cette section n'est vraiment intéressante que pour ceux qui s'intéressent au comportement détaillé de perl-core, à l'implémentation d'un mapping PerlIO ou à l'écriture de code qui peut utiliser la "lecture anticipée" qui a été faite par le système IO de la même manière que perl. Notez que tout code qui utilise ces interfaces doit être préparé à faire les choses de la manière traditionnelle si un handle ne les supporte pas.

PerlIO_fast_gets(f)

Renvoie vrai si l'implémentation a toutes les interfaces requises pour permettre à perl d'utiliser les interfaces de perl. sv_gets de "contourner" le mécanisme normal d'entrée-sortie. Cela peut varier d'un handle à l'autre.

PerlIO_fast_gets(f)= PerlIO_has_cntptr(f)&&
                      PerlIO_canset_cnt(f)&&'Can set pointer into buffer'
PerlIO_has_cntptr(f)

L'implémentation peut retourner un pointeur sur la position actuelle dans le "tampon" et un compte d'octets disponibles dans le tampon. Ne l'utilisez pas - utilisez PerlIO_fast_gets.

PerlIO_get_cnt(f)

Retourne le compte d'octets lisibles dans le tampon. Un retour nul ou négatif signifie qu'il n'y a plus d'octets disponibles.

PerlIO_get_ptr(f)

Retourne le pointeur vers le prochain octet lisible dans le tampon, l'accès via le pointeur (déréférencement) n'est sûr que si PerlIO_get_cnt() a retourné une valeur positive. Seuls les décalages positifs jusqu'à la valeur retournée par PerlIO_get_cnt() sont autorisés.

PerlIO_set_ptrcnt(f,p,c)

Fixe le pointeur dans le tampon, et un compte d'octets encore dans le tampon. Ne devrait être utilisé que pour placer le pointeur dans la plage impliquée par les appels précédents à... PerlIO_get_ptr et PerlIO_get_cnt. Les deux valeurs doivent être cohérentes l'une avec l'autre (la mise en œuvre peut n'utiliser que l'une ou l'autre ou peut exiger les deux).

PerlIO_canset_cnt(f)

L'implémentation peut ajuster son idée du nombre d'octets dans le tampon. Ne pas utiliser ceci - utiliser PerlIO_fast_gets.

PerlIO_set_cnt(f,c)

Obscure - définir le nombre d'octets dans le tampon. Déprécié. Utilisable uniquement si PerlIO_canset_cnt() renvoie true. Actuellement utilisé uniquement dans doio.c pour forcer un compte inférieur à -1 à -1. Peut-être que cela devrait être PerlIO_set_empty ou similaire. Cet appel peut en fait ne rien faire si "count" est déduit du pointeur et d'une "limite". Ne l'utilisez pas - utilisez PerlIO_set_ptrcnt().

PerlIO_has_base(f)

Retourne vrai si l'implémentation a un tampon, et peut retourner le pointeur vers le tampon entier et sa taille. Utilisé par perl pour -T / -B tests. Les autres utilisations seraient très obscures...

PerlIO_get_base(f)

Retourner démarrage de du tampon. Accède uniquement aux décalages positifs dans le tampon jusqu'à la valeur renvoyée par PerlIO_get_bufsiz().

PerlIO_get_bufsiz(f)

Retourne le nombre total d'octets dans le tampon, ce n'est ni le nombre qui peut être lu, ni la quantité de mémoire allouée au tampon. Il s'agit plutôt de ce que le système d'exploitation et/ou l'implémentation sont arrivés à... read() (ou autre) la dernière fois que IO a été demandé.

Autres fonctions

PerlIO_apply_layers(f,mode,layers)

La nouvelle interface de l'implémentation USE_PERLIO. Les couches ":crlf" et ":raw" sont les seules autorisées pour les autres implémentations et celles-ci sont ignorées silencieusement. (A partir de perl5.8 ":raw" est déprécié.) Utilisez PerlIO_binmode() ci-dessous pour le cas portable.

PerlIO_binmode(f,ptype,imode,layers)

Le hook utilisé par la fonction perl binmode de perl. ptype est le caractère de perl pour le type d'entrée-sortie :

'<' lire

'>' écrire
'+' lecture/écriture

imode est O_BINARY ou O_TEXT.

couches est une chaîne de couches à appliquer, seul ":crlf" a un sens dans le cas non USE_PERLIO. (A partir de perl5.8, ":raw" est déprécié en faveur du passage de NULL).

Les cas portables sont :

    PerlIO_binmode(f,ptype,O_BINARY,NULL);and
    PerlIO_binmode(f,ptype,O_TEXT,":crlf");

Sous Unix, ces appels n'ont probablement aucun effet. Ailleurs, ils modifient la traduction de "n" en CR,LF et provoquent éventuellement l'écriture d'un texte spécial indicateur de "fin de fichier" ou l'honorent en lecture. L'effet de l'appel après avoir effectué une entrée/sortie sur le handle dépend de l'implémentation. (Il peut être ignoré, affecter toute donnée déjà mise en mémoire tampon également, ou ne s'appliquer qu'aux données suivantes).

PerlIO_debug(fmt,...)

PerlIO_debug est une fonction semblable à printf() qui peut être utilisée pour le débogage. Il n'y a pas de valeur de retour. Son utilisation principale est à l'intérieur de PerlIO où l'utilisation de printf réel, warn() etc... appellerait récursivement PerlIO et serait un problème.

PerlIO_debug écrit dans le fichier nommé par $ENV{'PERLIO_DEBUG'} ou par défaut dans stderr si la variable d'environnement n'est pas définie. Une utilisation typique pourrait être

Bourne shells (sh, ksh, bash, zsh, ash,...):
 PERLIO_DEBUG=/tmp/perliodebug.log ./perl -Di somescript some args

Csh/Tcsh:
 setenv PERLIO_DEBUG /tmp/perliodebug.log
 ./perl -Di somescript some args

If you have the "env" utility:
 env PERLIO_DEBUG=/tmp/perliodebug.log ./perl -Di somescript args

Win32:
 set PERLIO_DEBUG=perliodebug.log
 perl -Di somescript some args

Sur un Perl construit sans -DDEBUGGINGou lorsque l'option -Di n'est pas spécifié, ou sous taint, PerlIO_debug() est un no-op.