• NAME
• SYNOPSIS
• DESCRIPTION
  • Co-existence with stdio

NAME

SYNOPSIS

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

    PerlIO *PerlIO_open(const char *,const char *);
    int     PerlIO_close(PerlIO *);

    int     PerlIO_stdoutf(const char *,...)
    int     PerlIO_puts(PerlIO *,const char *);
    int     PerlIO_putc(PerlIO *,int);
    int     PerlIO_write(PerlIO *,const void *,size_t);
    int     PerlIO_printf(PerlIO *, const char *,...);
    int     PerlIO_vprintf(PerlIO *, const char *, va_list);
    int     PerlIO_flush(PerlIO *);

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

    int     PerlIO_getc(PerlIO *);
    int     PerlIO_ungetc(PerlIO *,int);
    int     PerlIO_read(PerlIO *,void *,size_t);

    int     PerlIO_fileno(PerlIO *);
    PerlIO *PerlIO_fdopen(int, const char *);
    PerlIO *PerlIO_importFILE(FILE *);
    FILE   *PerlIO_exportFILE(PerlIO *);
    FILE   *PerlIO_findFILE(PerlIO *);
    void    PerlIO_releaseFILE(PerlIO *,FILE *);

    void    PerlIO_setlinebuf(PerlIO *);

    long    PerlIO_tell(PerlIO *);
    int     PerlIO_seek(PerlIO *,off_t,int);
    int     PerlIO_getpos(PerlIO *,Fpos_t *)
    int     PerlIO_setpos(PerlIO *,Fpos_t *)
    void    PerlIO_rewind(PerlIO *);

    int     PerlIO_has_base(PerlIO *);
    int     PerlIO_has_cntptr(PerlIO *);
    int     PerlIO_fast_gets(PerlIO *);
    int     PerlIO_canset_cnt(PerlIO *);

    char   *PerlIO_get_ptr(PerlIO *);
    int     PerlIO_get_cnt(PerlIO *);
    void    PerlIO_set_cnt(PerlIO *,int);
    void    PerlIO_set_ptrcnt(PerlIO *,char *,int);
    char   *PerlIO_get_base(PerlIO *);
    int     PerlIO_get_bufsiz(PerlIO *);

DESCRIPTION

The functions are modeled on those in stdio.h, but parameter order has been ``tidied up a little''.

PerlIO *

This takes the place of FILE *. Unlike FILE * it should be treated as opaque (it is probably safe to assume it is a pointer to something).

PerlIO_stdin(), PerlIO_stdout(), PerlIO_stderr()

Use these rather than stdin, stdout, stderr. They are written to look like ``function calls'' rather than variables because this makes it easier to make them function calls if platform cannot export data to loaded modules, or if (say) different ``threads'' might have different values.

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

These correspond to fopen()/fdopen() arguments are the same.

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

These are is fprintf()/vfprintf equivalents.

PerlIO_stdoutf(fmt,...)

This is printf() equivalent. printf is #defined to this function, so it is (currently) legal to use printf(fmt,...) in perl sources.

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

These correspond to fread() and fwrite(). Note that arguments are different, there is only one ``count'' and order has ``file'' first.

PerlIO_close(f)

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

These correspond to fputs() and fputc(). Note that arguments have been revised to have ``file'' first.

PerlIO_ungetc(f,c)

This corresponds to ungetc(). Note that arguments have been revised to have ``file'' first.

PerlIO_getc(f)

This corresponds to getc().

PerlIO_eof(f)

This corresponds to feof().

PerlIO_error(f)

This corresponds to ferror().

PerlIO_fileno(f)

This corresponds to fileno(), note that on some platforms, the meaning of ``fileno'' may not match Unix.

PerlIO_clearerr(f)

This corresponds to clearerr(), i.e., clears 'eof' and 'error' flags for the ``stream''.

PerlIO_flush(f)

This corresponds to fflush().

PerlIO_tell(f)

This corresponds to ftell().

PerlIO_seek(f,o,w)

This corresponds to fseek().

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

These correspond to fgetpos() and fsetpos(). If platform does not have the stdio calls then they are implemented in terms of PerlIO_tell() and PerlIO_seek().

PerlIO_rewind(f)

This corresponds to rewind(). Note may be redefined in terms of PerlIO_seek() at some point.

PerlIO_tmpfile()

This corresponds to tmpfile(), i.e., returns an anonymous PerlIO which will automatically be deleted when closed.

Co-existence with stdio

PerlIO_importFILE(f,flags)

Used to get a PerlIO * from a FILE *. May need additional arguments, interface under review.

PerlIO_exportFILE(f,flags)

Given an PerlIO * return a 'native' FILE * suitable for passing to code expecting to be compiled and linked with ANSI C stdio.h.

The fact that such a FILE * has been 'exported' is recorded, and may affect future PerlIO operations on the original PerlIO *.

PerlIO_findFILE(f)

Returns previously 'exported' FILE * (if any). Place holder until interface is fully defined.

PerlIO_releaseFILE(p,f)

Calling PerlIO_releaseFILE informs PerlIO that all use of FILE * is complete. It is removed from list of 'exported' FILE *s, and associated PerlIO * should revert to original behaviour.

PerlIO_setlinebuf(f)

This corresponds to setlinebuf(). Use is deprecated pending further discussion. (Perl core uses it only when ``dumping'' is has nothing to do with $| auto-flush.)

PerlIO_has_cntptr(f)

Implementation can return pointer to current position in the ``buffer'' and a count of bytes available in the buffer.

PerlIO_get_ptr(f)

Return pointer to next readable byte in buffer.

PerlIO_get_cnt(f)

Return count of readable bytes in the buffer.

PerlIO_canset_cnt(f)

Implementation can adjust its idea of number of bytes in the buffer.

PerlIO_fast_gets(f)

Implementation has all the interfaces required to allow perl's fast code to handle <FILE> mechanism.

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

PerlIO_set_ptrcnt(f,p,c)

Set pointer into buffer, and a count of bytes still in the buffer. Should be used only to set pointer to within range implied by previous calls to PerlIO_get_ptr and PerlIO_get_cnt.

PerlIO_set_cnt(f,c)

Obscure - set count of bytes in the buffer. Deprecated. Currently used in only doio.c to force count < -1 to -1. Perhaps should be PerlIO_set_empty or similar. This call may actually do nothing if ``count'' is deduced from pointer and a ``limit''.

PerlIO_has_base(f)

Implementation has a buffer, and can return pointer to whole buffer and its size. Used by perl for -T / -B tests. Other uses would be very obscure...

PerlIO_get_base(f)

Return start of buffer.

PerlIO_get_bufsiz(f)

Return total size of buffer.