perliol - Trực tuyến trên đám mây

CHƯƠNG TRÌNH:

TÊN

perliol - API C để Perl triển khai IO trong các Lớp.

SYNOPSIS

/ * Định nghĩa một lớp ... * /
#bao gồm

MÔ TẢ

Tài liệu này mô tả hành vi và việc thực hiện phép trừu tượng PerlIO
được mô tả trong perlapio khi "USE_PERLIO" được xác định.

Lịch Sử và Tiểu sử
Phần trừu tượng PerlIO đã được giới thiệu trong perl5.003_02 nhưng bị hao mòn chỉ là một
trừu tượng cho đến perl5.7.0. Tuy nhiên trong thời gian đó, một số phần mở rộng perl đã chuyển
để sử dụng nó, vì vậy API chủ yếu được cố định để duy trì khả năng tương thích (nguồn).

Mục đích của việc triển khai là cung cấp API PerlIO trong một nền tảng và linh hoạt
cách thức trung lập. Nó cũng là một thử nghiệm của phương pháp tiếp cận "Hướng đối tượng C, với vtables"
có thể được áp dụng cho Perl 6.

Cơ bản Structure
PerlIO là một chồng các lớp.

Các cấp thấp của ngăn xếp hoạt động với các lệnh gọi hệ điều hành cấp thấp (tệp
bộ mô tả trong C) nhận byte vào và ra, các lớp cao hơn của bộ đệm ngăn xếp, bộ lọc,
và nếu không thì thao tác I / O và trả về các ký tự (hoặc byte) cho Perl. Điều kiện ở trên
và phía dưới được sử dụng để chỉ vị trí tương đối của các lớp ngăn xếp.

Một lớp chứa một "vtable", bảng các hoạt động I / O (ở mức C, một bảng chức năng
con trỏ) và cờ trạng thái. Các chức năng trong vtable thực hiện các hoạt động như
"mở", "đọc" và "viết".

Khi I / O, ví dụ "đọc", được yêu cầu, yêu cầu đi từ Perl đầu tiên xuống
ngăn xếp bằng cách sử dụng các chức năng "đọc" của mỗi lớp, sau đó ở dưới cùng, đầu vào được yêu cầu từ
các dịch vụ của hệ điều hành, sau đó kết quả được trả về trong ngăn xếp, cuối cùng là
được hiểu là dữ liệu Perl.

Các yêu cầu không nhất thiết phải luôn đi xuống hệ điều hành: đó là
nơi bộ đệm PerlIO phát huy tác dụng.

Khi bạn làm một mở() và chỉ định các lớp PerlIO bổ sung sẽ được triển khai, các lớp mà bạn
chỉ định được "đẩy" lên đầu ngăn xếp mặc định đã tồn tại. Một cách để xem nó là
rằng "hệ điều hành ở bên trái" và "Perl ở bên phải".

Những lớp chính xác nào trong ngăn xếp mặc định này phụ thuộc vào rất nhiều thứ: hoạt động của bạn
hệ thống, phiên bản Perl, cấu hình thời gian biên dịch Perl và cấu hình thời gian chạy Perl.
Xem PerlIO, "PERLIO" trong perlrun và mở để biết thêm thông tin.

binmode () hoạt động tương tự như mở(): theo mặc định, các lớp được chỉ định được đẩy lên trên cùng
của ngăn xếp hiện có.

Tuy nhiên, lưu ý rằng ngay cả khi các lớp được chỉ định được "đẩy lên trên" cho mở() và
binmode (), điều này không có nghĩa là các hiệu ứng bị giới hạn ở "trên cùng": Các lớp PerlIO có thể
rất 'tích cực' và kiểm tra và ảnh hưởng đến các lớp cũng sâu hơn trong ngăn xếp. Như một ví dụ
có một lớp được gọi là "thô" liên tục "bật" các lớp cho đến khi nó đạt đến lớp đầu tiên
lớp đã tự khai báo có khả năng xử lý dữ liệu nhị phân. Các lớp được "đẩy" là
được xử lý theo thứ tự từ trái sang phải.

sysopen () hoạt động (không có gì đáng ngạc nhiên) ở cấp độ thấp hơn trong ngăn xếp so với mở(). Đối với
ví dụ trong Unix hoặc các hệ thống giống Unix sysopen () hoạt động trực tiếp ở cấp độ tệp
bộ mô tả: theo thuật ngữ của các lớp PerlIO, nó chỉ sử dụng lớp "unix", là một
trình bao bọc khá mỏng trên đầu bộ mô tả tệp Unix.

Layers vs Kỷ luật
Thảo luận ban đầu về khả năng sửa đổi hành vi luồng IO đã sử dụng thuật ngữ
"kỷ luật" cho các thực thể đã được thêm vào. Điều này đến (tôi tin) từ việc sử dụng
thuật ngữ trong "sfio", từ đó mượn nó từ "nguyên tắc dòng" trên các thiết bị đầu cuối Unix.
Tuy nhiên, tài liệu này (và mã C) sử dụng thuật ngữ "lớp".

Tôi hy vọng đây là một thuật ngữ tự nhiên được đưa ra khi triển khai và nên tránh hàm ý
vốn có trong các cách sử dụng trước đây của "kỷ luật" cho những thứ khá khác biệt.

Ngày Cấu trúc
Cấu trúc dữ liệu cơ bản là PerlIOl:

cấu trúc typedef _PerlIO PerlIOl;
cấu trúc typedef _PerlIO_funcs PerlIO_funcs;
typedef PerlIOl * PerlIO;

cấu trúc _PerlIO
{
PerlIOl * tiếp theo; /* Tầng thấp hơn */
PerlIO_funcs * tab; / * Các chức năng cho lớp này * /
Cờ U32; / * Nhiều cờ khác nhau cho tiểu bang * /
};

"PerlIOl *" là một con trỏ đến cấu trúc và ứng dụng cấp độ "PerlIO *" là
con trỏ tới một "PerlIOl *" - tức là một con trỏ tới một con trỏ tới cấu trúc. Điều này cho phép
cấp ứng dụng "PerlIO *" không đổi trong khi "PerlIOl *" thực tế bên dưới
những thay đổi. (So ​​sánh "SV *" của perl không đổi trong khi trường "sv_any" của nó thay đổi như
kiểu của vô hướng thay đổi.) Sau đó, một luồng IO nói chung được biểu diễn dưới dạng một con trỏ tới
danh sách "lớp" được liên kết này.

Cần lưu ý rằng do chuyển hướng kép trong "PerlIO *",
"& (perlio-> next)" "là" một "PerlIO *" và vì vậy ở một mức độ nào đó, ít nhất một lớp có thể sử dụng
API "tiêu chuẩn" trên lớp tiếp theo xuống.

Một "lớp" bao gồm hai phần:

1. Các chức năng và thuộc tính của "lớp lớp".

2. Dữ liệu từng trường hợp cho một xử lý cụ thể.

Chức năng và Thuộc tính
Các chức năng và thuộc tính được truy cập thông qua thành viên "tab" (cho bảng) của "PerlIOl".
Các hàm (các phương thức của lớp "class") là cố định và được định nghĩa bởi
Loại "PerlIO_funcs". Nhìn chung, chúng giống với các hàm "PerlIO_" công khai:

cấu trúc _PerlIO_funcs
{
Size_t fsize;
tên nhân vật;
Kích_thước;
Loại IV;
IV (* Đã đẩy) (pTHX_ PerlIO * f, const char * mode, SV * arg, PerlIO_funcs * tab);
IV (* Đã bật) (pTHX_ PerlIO * f);
PerlIO * (* Mở) (pTHX_ PerlIO_funcs * tab,
PerlIO_list_t * lớp, IV n,
chế độ const char *,
int fd, int imode, int perm,
PerlIO * cũ,
int narg, SV ** args);
IV (* Binmode) (pTHX_ PerlIO * f);
SV * (* Getarg) (pTHX_ PerlIO * f, CLONE_PARAMS * param, int flags)
IV (* Fileno) (pTHX_ PerlIO * f);
PerlIO * (* Dup) (pTHX_ PerlIO * f, PerlIO * o, CLONE_PARAMS * param, int flags)
/ * Các hàm giống Unix - các nguyên tắc dòng cf sfio * /
SSize_t (* Read) (pTHX_ PerlIO * f, void * vbuf, Size_t count);
SSize_t (* Chưa đọc) (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 whence);
Off_t (* Tell) (pTHX_ PerlIO * f);
IV (* Đóng) (pTHX_ PerlIO * f);
/ * Các chức năng IO được đệm giống Stdio * /
IV (* Xả) (pTHX_ PerlIO * f);
IV (* Điền) (pTHX_ PerlIO * f);
IV (* Eof) (pTHX_ PerlIO * f);
IV (* Lỗi) (pTHX_ PerlIO * f);
void (* Clearerr) (pTHX_ PerlIO * f);
void (* Setlinebuf) (pTHX_ PerlIO * f);
/ * Các chức năng rình mò của 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);
};

Một số thành viên đầu tiên của cấu trúc cung cấp kích thước bảng hàm để kiểm tra tính tương thích
"tên" cho lớp, kích thước thành "malloc" cho dữ liệu mỗi trường hợp và một số cờ
là các thuộc tính của toàn bộ lớp (chẳng hạn như liệu nó có phải là lớp đệm hay không), thì
tuân theo các chức năng được chia thành bốn nhóm cơ bản:

1. Mở và thiết lập các chức năng

2. Các hoạt động IO cơ bản

3. Tùy chọn đệm lớp Stdio.

4. Các chức năng hỗ trợ truy cập "nhanh" truyền thống của Perl vào bộ đệm.

Một lớp không nhất thiết phải triển khai tất cả các chức năng, nhưng toàn bộ bảng phải
hiện nay. Các vị trí chưa hoàn thành có thể là NULL (sẽ dẫn đến lỗi khi được gọi) hoặc
có thể được điền vào các sơ khai để "kế thừa" hành vi từ một "lớp cơ sở". "Kế thừa" này
được cố định cho tất cả các trường hợp của lớp, nhưng khi lớp chọn gốc nào để điền
bảng, "đa kế thừa" hạn chế là có thể.

Mỗi trường hợp Ngày
Dữ liệu cho mỗi trường hợp được lưu giữ trong bộ nhớ ngoài cấu trúc PerlIOl cơ bản, bằng cách tạo
PerlIOl thành viên đầu tiên trong cấu trúc của lớp:

cấu trúc typedef
{
cơ sở struct _PerlIO; / * Thông tin "lớp" cơ sở * /
STDCHAR * buf; / * Bắt đầu bộ đệm * /
STDCHAR * end; / * Kết thúc phần hợp lệ của bộ đệm * /
STDCHAR * ptr; / * Vị trí hiện tại trong bộ đệm * /
Off_t posn; / * Phần bù buf vào tệp * /
Kích_thước bufsiz; / * Kích thước thực của bộ đệm * /
IV một từ; / * Bộ đệm khẩn cấp * /
} PerlIOBUf;

Theo cách này (đối với vô hướng của perl) một con trỏ tới PerlIOBuf có thể được coi như một con trỏ
sang PerlIOl.

Layers in hành động.
bảng perlio unix
| |
+ ----------- + + ---------- + + -------- +
PerlIO -> | | ---> | tiếp theo | ---> | NULL |
+ ----------- + + ---------- + + -------- +
| | | đệm | | fd |
+ ----------- + | | + -------- +
| | + ---------- +

Các nỗ lực trên để chỉ ra cách thức hoạt động của lược đồ lớp trong một trường hợp đơn giản. Ứng dụng của
"PerlIO *" trỏ đến một mục nhập trong (các) bảng biểu thị các chốt điều khiển đang mở (được cấp phát). Vì
ví dụ ba vị trí đầu tiên trong bảng tương ứng với "stdin", "stdout" và "stderr".
Bảng đến lượt nó trỏ đến lớp "trên cùng" hiện tại cho tay cầm - trong trường hợp này là
ví dụ của lớp đệm chung "perlio". Lớp đó lần lượt chỉ đến lớp tiếp theo
lớp xuống - trong trường hợp này là lớp "unix" cấp thấp.

Ở trên gần tương đương với luồng được đệm "stdio", nhưng với nhiều hơn thế nữa
Uyển chuyển:

· Nếu mức Unix "đọc" / "ghi" / "lseek" không phù hợp với (nói) các ổ cắm thì
Lớp "unix" có thể được thay thế (tại thời điểm mở hoặc thậm chí động) bằng lớp "ổ cắm".

· Các tay cầm khác nhau có thể có các sơ đồ đệm khác nhau. Lớp "trên cùng" có thể là
lớp "mmap" nếu đọc tệp đĩa nhanh hơn bằng "mmap" so với "đọc". Một
luồng "unbuffered" có thể được thực hiện đơn giản bằng cách không có lớp đệm.

· Các lớp bổ sung có thể được chèn vào để xử lý dữ liệu khi nó chạy qua. Đây là
thúc đẩy nhu cầu bao gồm chương trình trong perl 5.7.0+ - chúng tôi cần một cơ chế để cho phép
dữ liệu được dịch giữa mã hóa nội bộ của perl (về mặt khái niệm ít nhất là Unicode
như UTF-8) và định dạng "gốc" được hệ thống sử dụng. Điều này được cung cấp bởi
Lớp ": encoding (xxxx)" thường nằm phía trên lớp đệm.

· Có thể thêm một lớp có "\ n" vào bản dịch CRLF. Lớp này có thể được sử dụng trên bất kỳ
nền tảng, không chỉ những nền tảng thường làm những việc như vậy.

Mỗi trường hợp cờ bit
Các bit cờ chung là sự kết hợp của cờ kiểu "O_XXXXX" được suy ra từ chuỗi chế độ
được chuyển tới "PerlIO_open ()", và các bit trạng thái cho các lớp đệm điển hình.

PERLIO_F_EOF
Phần cuối của tập tin.

PERLIO_F_CANWRITE
Được phép viết, nghĩa là được mở là "w" hoặc "r +" hoặc "a", v.v.

PERLIO_F_CANREAD
Được phép đọc tức là đã mở "r" hoặc "w +" (hoặc thậm chí "a +" - ick).

PERLIO_F_ERROR
Đã xảy ra lỗi (đối với "PerlIO_error ()").

PERLIO_F_TRUNCATE
Cắt ngắn tệp được đề xuất bởi chế độ mở.

PERLIO_F_APPEND
Tất cả các bài viết nên được bổ sung.

PERLIO_F_CRLF
Lớp đang thực hiện "\ n" giống Win32 được ánh xạ tới CR, LF cho đầu ra và CR, LF được ánh xạ tới
"\ n" cho đầu vào. Thông thường, lớp "crlf" được cung cấp là lớp duy nhất cần bận tâm
về điều này. "PerlIO_binmode ()" sẽ gây rối với cờ này thay vì thêm / xóa các lớp
nếu bit "PERLIO_K_CANCRLF" được đặt cho lớp lớp.

PERLIO_F_UTF8
Dữ liệu được ghi vào lớp này phải được mã hóa UTF-8; dữ liệu do lớp này cung cấp nên
được coi là mã hóa UTF-8. Có thể được đặt trên bất kỳ lớp nào bằng lớp giả ": utf8". Cũng được thiết lập
trên lớp ": encoding".

PERLIO_F_UNBUF
Lớp không có bộ đệm - tức là ghi xuống lớp tiếp theo sẽ xảy ra cho mỗi lần ghi vào
lớp này.

PERLIO_F_WRBUF
Bộ đệm cho lớp này hiện giữ dữ liệu được ghi vào nó nhưng không được gửi đến lớp tiếp theo
lớp.

PERLIO_F_RDBUF
Bộ đệm cho lớp này hiện đang chứa dữ liệu chưa tích lũy được đọc từ lớp bên dưới.

PERLIO_F_LINEBUF
Lớp được đệm dòng. Ghi dữ liệu phải được chuyển cho lớp tiếp theo xuống bất cứ khi nào "\ n"
được nhìn thấy. Sau đó, bất kỳ dữ liệu nào ngoài "\ n" sẽ được xử lý.

PERLIO_F_TEMP
Tệp đã được chỉnh sửa "unlink ()", hoặc sẽ bị xóa vào "close ()".

PERLIO_F_OPEN
Tay cầm đang mở.

PERLIO_F_FASTGETS
Phiên bản này của lớp này hỗ trợ giao diện "nhanh" được "". Thường được đặt dựa trên
trên "PERLIO_K_FASTGETS" cho lớp và bởi sự tồn tại của (các) hàm trong
bàn. Tuy nhiên, một lớp thường cung cấp giao diện đó có thể cần phải tránh nó trên một
Ví dụ cụ thể. Lớp "đang chờ xử lý" cần thực hiện việc này khi nó được đẩy lên trên
lớp không hỗ trợ giao diện. (Perl's "sv_gets ()" không mong đợi
luồng nhanh, hành vi "get" thay đổi trong một lần "get".)

Phương pháp in Chi tiết
cỡ nhỏ
Size_t fsize;

Kích thước của bảng chức năng. Điều này được so sánh với giá trị mà mã PerlIO "biết" là
kiểm tra tính tương thích. Phiên bản tương lai có thể có thể chịu đựng các lớp được biên dịch chống lại
phiên bản cũ của tiêu đề.

tên
tên nhân vật;

Tên của lớp có mở() phương thức Perl nên gọi trên mở(). Ví dụ
nếu lớp được gọi là APR, bạn sẽ gọi:

mở $ fh, ">: APR", ...

và Perl biết rằng nó phải gọi PerlIOAPR_open () phương pháp được thực hiện bởi
Lớp APR.

kích thước
Kích_thước;

Kích thước của cấu trúc dữ liệu cho mỗi trường hợp, ví dụ:

sizeof (PerlIOAPR)

Nếu trường này bằng XNUMX thì "PerlIO_pushing" không sai bất cứ điều gì và giả sử
chức năng đẩy của lớp sẽ thực hiện bất kỳ thao tác xếp chồng lớp bắt buộc nào - được sử dụng để tránh
malloc / chi phí miễn phí cho các lớp giả. Nếu trường khác XNUMX thì ít nhất phải bằng
kích thước của "PerlIOl", "PerlIO_pushing" sẽ cấp phát bộ nhớ cho dữ liệu của lớp
cấu trúc và liên kết lớp mới vào ngăn xếp của luồng. (Nếu phương thức được đẩy của lớp
trả về một chỉ báo lỗi lớp lại được xuất hiện.)

loại
Loại IV;

· PERLIO_K_BUFFERED

Lớp được đệm.

· PERLIO_K_RAW

Lớp được chấp nhận để có trong ngăn xếp binmode (FH) - tức là nó không (hoặc sẽ
tự cấu hình để không) chuyển đổi các byte đi qua nó.

· PERLIO_K_CANCRLF

Lớp có thể dịch giữa "\ n" và đầu dòng CRLF.

· PERLIO_K_FASTGETS

Lớp cho phép snooping bộ đệm.

· PERLIO_K_MULTIARG

Được sử dụng khi lớp mở() chấp nhận nhiều đối số hơn bình thường. Bổ sung
đối số không được đứng trước đối số "MODE". Khi cờ này được sử dụng, nó
lên đến lớp để xác thực args.

Đẩy
IV (* Đã đẩy) (pTHX_ PerlIO * f, chế độ const char *, SV * arg);

Phương pháp hoàn toàn bắt buộc duy nhất. Được gọi khi lớp được đẩy lên ngăn xếp.
Đối số "mode" có thể là NULL nếu điều này xảy ra sau khi mở. "Arg" sẽ không phải là "NULL"
nếu một chuỗi đối số được truyền. Trong hầu hết các trường hợp, điều này sẽ gọi "PerlIOBase_pushing ()"
để chuyển đổi "chế độ" thành cờ "PERLIO_F_XXXXX" thích hợp ngoài bất kỳ
các hành động mà lớp tự thực hiện. Nếu một lớp không mong đợi một đối số, nó cần
không lưu cái được chuyển cho nó, cũng không cung cấp "Getarg ()" (có lẽ nó có thể
"Perl_warn" mà đối số không được mong đợi).

Trả về 0 khi thành công. Khi thất bại trả về -1 và nên đặt errno.

Xuất hiện
IV (* Đã bật) (pTHX_ PerlIO * f);

Được gọi khi lớp được bật ra từ ngăn xếp. Một lớp thường sẽ được xuất hiện sau
"Close ()" được gọi. Nhưng một lớp có thể được xuất hiện mà không bị đóng nếu chương trình
quản lý động các lớp trên luồng. Trong những trường hợp như vậy, "Popped ()" sẽ giải phóng bất kỳ
tài nguyên (bộ đệm, bảng dịch, ...) không được giữ trực tiếp trong cấu trúc của lớp.
Nó cũng phải "Chưa đọc ()" bất kỳ dữ liệu chưa tích lũy nào đã được đọc và lưu vào bộ đệm từ
lớp bên dưới trở lại lớp đó, để nó có thể được cung cấp lại như bây giờ
ở trên.

Trả về 0 cho thành công và thất bại. Nếu "Popped ()" trả về đúng sau đó perlio.c giả định
rằng lớp đó đã tự xuất hiện hoặc lớp này siêu đặc biệt và cần phải
được giữ lại vì những lý do khác. Trong hầu hết các trường hợp, nó sẽ trở lại sai.

Mở
PerlIO * (* Mở) (...);

Phương thức "Open ()" có rất nhiều đối số vì nó kết hợp các chức năng của perl's
"open", "PerlIO_open", "sysopen" của perl, "PerlIO_fdopen" và "PerlIO_reopen". Các
nguyên mẫu đầy đủ như sau:

PerlIO * (* Mở) (pTHX_ PerlIO_funcs * tab,
PerlIO_list_t * lớp, IV n,
chế độ const char *,
int fd, int imode, int perm,
PerlIO * cũ,
int narg, SV ** args);

Open nên (có lẽ gián tiếp) gọi "PerlIO_allocate ()" để phân bổ một vị trí trong
và liên kết nó với thông tin các lớp cho tệp đã mở, bằng cách gọi
"PerlIO_push". Các lớp là một mảng của tất cả các lớp dành cho "PerlIO *",
và bất kỳ đối số nào được chuyển cho chúng, n là chỉ mục trong mảng đó của lớp
triệu tập. Macro "PerlIOArg" sẽ trả về SV * (có thể là "NULL") cho đối số
được chuyển đến lớp.

Sản phẩm chế độ string là một chuỗi "" fopen () "- like" sẽ khớp với biểu thức chính quy
"/ ^ [I #]? [Rwa] \ +? [Bt]? $ /".

Tiền tố 'I' được sử dụng trong quá trình tạo "stdin" .. "stderr" thông qua đặc biệt
"PerlIO_fdopen" gọi; tiền tố '#' có nghĩa là đây là "sysopen" và imode và
uốn nên được chuyển đến "PerlLIO_open3"; 'r' có nghĩa là read, 'w' có nghĩa là wnghi thức và 'a'
có nghĩa achi tiêu. Hậu tố '+' có nghĩa là cả đọc và viết / thêm vào đều
được phép. Hậu tố 'b' có nghĩa là tệp phải là tệp nhị phân và "t" có nghĩa là tệp là văn bản.
(Hầu hết tất cả các lớp nên thực hiện IO ở chế độ nhị phân và bỏ qua các bit b / t.
Lớp ": crlf" nên được đẩy để xử lý sự phân biệt.)

If xưa không phải là "NULL" thì đây là "PerlIO_reopen". Perl chính nó không sử dụng cái này
(chưa?) và ngữ nghĩa là một chút mơ hồ.

If fd không âm thì nó là bộ mô tả tệp số fd, sẽ được mở trong một
tương thích với chuỗi chế độ được cung cấp, do đó, lệnh gọi tương đương với
"PerlIO_fdopen". Trong trường hợp này tường thuật sẽ bằng không.

If tường thuật lớn hơn XNUMX thì nó cung cấp số lượng đối số được truyền cho "open",
nếu không, nó sẽ là 1 nếu ví dụ "PerlIO_open" được gọi. Trong những trường hợp đơn giản
SvPV_nolen (* args) là tên đường dẫn để mở.

Nếu một lớp cung cấp "Open ()", nó thường sẽ gọi phương thức "Open ()" của lớp tiếp theo
xuống (nếu có) và sau đó tự đẩy lên trên nếu thành công. "PerlIOBase_open" là
được cung cấp để làm chính xác điều đó, vì vậy trong hầu hết các trường hợp, bạn không phải viết
Phương thức "Open ()". Nếu phương thức này không được xác định, các lớp khác có thể gặp khó khăn
đẩy mình lên trên nó trong khi mở.

Nếu "PerlIO_push" được thực hiện và không mở được, nó phải là "PerlIO_pop", vì
nếu không, lớp sẽ không bị xóa và có thể gây ra các vấn đề xấu.

Trả về "NULL" khi không thành công.

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

Không bắt buộc. Được sử dụng khi lớp ": raw" được đẩy (rõ ràng hoặc là kết quả của binmode (FH)).
Nếu không hiện tại lớp sẽ được xuất hiện. Nếu có, nên định cấu hình lớp dưới dạng nhị phân (hoặc
tự bật lên) và trả về 0. Nếu nó trả về -1 cho lỗi "binmode" sẽ không thành công với lớp
vẫn còn trên ngăn xếp.

Tải xuống
SV * (* Getarg) (pTHX_ PerlIO * f,
CLONE_PARAMS * param, int flags);

Không bắt buộc. Nếu có thì sẽ trả về một SV * đại diện cho đối số chuỗi được chuyển đến
lớp khi nó được đẩy. ví dụ: ": encoding (ascii)" sẽ trả về một SvPV có giá trị
"ascii". (tiền của tôi và cờ đối số có thể bị bỏ qua trong hầu hết các trường hợp)

"Dup" sử dụng "Getarg" để truy xuất đối số ban đầu được chuyển đến "Pushing", vì vậy bạn
phải triển khai chức năng này nếu lớp của bạn có thêm một đối số cho "Đã đẩy" và sẽ
đã từng bị "trùng lặp"

Thư mục số
IV (* Fileno) (pTHX_ PerlIO * f);

Trả về bộ mô tả tệp số Unix / Posix cho xử lý. Thông thường
"PerlIOBase_fileno ()" (chỉ yêu cầu lớp tiếp theo xuống) sẽ đủ cho điều này.

Trả về -1 khi lỗi, được coi là bao gồm trường hợp lớp không thể
cung cấp một bộ mô tả tệp như vậy.

Trùng lặp
PerlIO * (* Trùng lặp) (pTHX_ PerlIO * f, PerlIO * o,
CLONE_PARAMS * param, int flags);

XXX: Cần thêm tài liệu.

Được sử dụng như một phần của quá trình "sao chép" khi một luồng được tạo ra (trong trường hợp đó, param sẽ
không phải là NULL) và khi luồng đang được sao chép qua '&' trong "mở".

Tương tự như "Mở", trả về PerlIO * khi thành công, "NULL" khi thất bại.

Đọc
SSize_t (* Read) (pTHX_ PerlIO * f, void * vbuf, Size_t count);

Thao tác đọc cơ bản.

Thông thường sẽ gọi "Fill" và thao tác với con trỏ (có thể thông qua API).
"PerlIOBuf_read ()" có thể phù hợp với các lớp dẫn xuất cung cấp "fast get"
phương pháp.

Trả về byte thực tế đã đọc hoặc -1 khi có lỗi.

Chưa đọc
SSize_t (* Chưa đọc) (pTHX_ PerlIO * f,
const void * vbuf, Size_t count);

Một tập hợp siêu đẳng của "ungetc ()" của stdio. Nên sắp xếp các lần đọc trong tương lai để xem các byte trong
"vbuf". Nếu không có cách triển khai rõ ràng nào tốt hơn thì "PerlIOBase_unread ()"
cung cấp chức năng bằng cách đẩy một lớp "giả" "đang chờ xử lý" lên trên lớp đang gọi.

Trả về số ký tự chưa đọc.

Viết
SSize_t (* Write) (PerlIO * f, const void * vbuf, Size_t count);

Thao tác ghi cơ bản.

Trả về các byte đã viết hoặc -1 trên một lỗi.

Tìm kiếm
IV (* Seek) (pTHX_ PerlIO * f, Off_t offset, int whence);

Định vị con trỏ tệp. Thông thường sẽ gọi phương thức "Flush" của riêng nó và sau đó là
"Tìm kiếm" của lớp tiếp theo xuống.

Trả về 0 khi thành công, -1 khi thất bại.

Giới thiệu
Off_t (* Tell) (pTHX_ PerlIO * f);

Trả lại con trỏ tệp. Có thể dựa trên khái niệm vị trí cần tránh của các lớp được lưu trong bộ nhớ cache
trên không.

Trả về -1 khi không lấy được con trỏ tệp.

Đóng
IV (* Đóng) (pTHX_ PerlIO * f);

Đóng luồng. Thông thường sẽ gọi "PerlIOBase_close ()" để tự xả và đóng
các lớp bên dưới, và sau đó phân bổ bất kỳ cấu trúc dữ liệu nào (bộ đệm, bảng dịch,
...) không được giữ trực tiếp trong cấu trúc dữ liệu.

Trả về 0 khi thành công, -1 khi thất bại.

Thùng
IV (* Xả) (pTHX_ PerlIO * f);

Phải làm cho trạng thái của luồng nhất quán với các lớp bên dưới. Đó là, bất kỳ ghi có bộ đệm nào
dữ liệu phải được ghi và vị trí tệp của các lớp thấp hơn được điều chỉnh để dữ liệu được đọc từ
dưới đây nhưng không thực sự tiêu thụ. (Có lẽ nên "Chưa đọc ()" dữ liệu như vậy xuống thấp hơn
lớp.)

Trả về 0 khi thành công, -1 khi thất bại.

Điền
IV (* Điền) (pTHX_ PerlIO * f);

Bộ đệm cho lớp này nên được lấp đầy (để đọc) từ lớp bên dưới. Khi bạn
lớp PerlIOBuf "subclass", bạn muốn sử dụng nó _đọc phương pháp và cung cấp của riêng bạn
phương thức điền, lấp đầy bộ đệm của PerlIOBuf.

Trả về 0 khi thành công, -1 khi thất bại.

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

Trả về chỉ báo cuối tệp. "PerlIOBase_eof ()" thường là đủ.

Trả về 0 ở cuối tệp, 1 nếu không phải ở cuối tệp, -1 khi có lỗi.

lỗi
IV (* Lỗi) (pTHX_ PerlIO * f);

Chỉ báo lỗi trả lại. "PerlIOBase_error ()" thường là đủ.

Trả về 1 nếu có lỗi (thường là khi "PERLIO_F_ERROR" được đặt), nếu không thì trả về 0.

Rõ ràng hơn
void (* Clearerr) (pTHX_ PerlIO * f);

Xóa các chỉ báo lỗi và cuối tệp. Nên gọi "PerlIOBase_clearerr ()" để đặt
Cờ "PERLIO_F_XXXXX", có thể đủ.

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

Đánh dấu luồng là dòng được lưu vào bộ đệm. "PerlIOBase_setlinebuf ()" đặt PERLIO_F_LINEBUF
cờ và thường là đủ.

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

Phân bổ (nếu chưa được thực hiện) bộ đệm đọc cho lớp này và trả về con trỏ
nó. Trả về NULL khi không thành công.

Get_bufsiz
Size_t (* Get_bufsiz) (pTHX_ PerlIO * f);

Trả về số byte cuối cùng "Fill ()" được đưa vào bộ đệm.

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

Trả lại con trỏ đọc hiện tại liên quan đến bộ đệm của lớp này.

Nhận_cnt
SSize_t (* Get_cnt) (pTHX_ PerlIO * f);

Trả về số byte còn lại được đọc trong bộ đệm hiện tại.

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

Điều chỉnh con trỏ đọc và số byte để khớp với "ptr" và / hoặc "cnt". Các
ứng dụng (hoặc lớp trên) phải đảm bảo chúng nhất quán. (Kiểm tra được cho phép bởi
hoang tưởng.)

Tiện ích
Để yêu cầu lớp tiếp theo xuống, hãy sử dụng PerlIONext (PerlIO * f).

Để kiểm tra xem PerlIO * có hợp lệ hay không, hãy sử dụng PerlIOValid (PerlIO * f). (Tất cả những điều này thực sự là
chỉ để kiểm tra xem con trỏ có phải là NULL và con trỏ đằng sau đó không phải là NULL hay không.)

PerlIOBase (PerlIO * f) trả về con trỏ "Cơ sở", hay nói cách khác, "PerlIOl *"
con trỏ.

PerlIOSelf (PerlIO * f, type) trả về kiểu ép PerlIOBase thành một kiểu.

Perl_PerlIO_or_Base (PerlIO * f, callback, base, fail, args) gọi gọi lại
từ các chức năng của lớp f (chỉ bằng tên của hàm IO, như "Đọc") với
các args.hoặc nếu không có cuộc gọi lại như vậy, hãy gọi cơ sở phiên bản của cuộc gọi lại với
cùng một args, hoặc nếu f không hợp lệ, hãy đặt errno thành EBADF và trả về thất bại.

Perl_PerlIO_or_fail (PerlIO * f, callback, fail, args) gọi gọi lại của
chức năng của lớp f với args.hoặc nếu không có lệnh gọi lại như vậy, hãy đặt errno thành
CUỐI CÙNG. Hoặc nếu f không hợp lệ, hãy đặt errno thành EBADF và trả về thất bại.

Perl_PerlIO_or_Base_void (PerlIO * f, callback, base, args) gọi gọi lại của
chức năng của lớp f với args.hoặc nếu không có cuộc gọi lại như vậy, hãy gọi cơ sở
phiên bản của lệnh gọi lại với cùng một args, hoặc nếu f không hợp lệ, hãy đặt errno thành EBADF.

Perl_PerlIO_or_fail_void (PerlIO * f, callback, args) gọi gọi lại của
chức năng của lớp f với args.hoặc nếu không có lệnh gọi lại như vậy, hãy đặt errno thành
CUỐI CÙNG. Hoặc nếu f không hợp lệ, hãy đặt errno thành EBADF.

Thực thi PerlIO Layers
Nếu bạn thấy tài liệu triển khai không rõ ràng hoặc không đầy đủ, hãy xem tài liệu hiện có
Triển khai lớp PerlIO, bao gồm:

· C triển khai

Sản phẩm perlio.c và perliol.h trong lõi Perl triển khai "unix", "perlio", "stdio",
"crlf", "utf8", "byte", "raw", "pending" và cả lớp "mmap" và "win32"
các lớp nếu có. ("Win32" hiện chưa hoàn thành và chưa được sử dụng, hãy xem
được sử dụng thay thế trong Win32, hãy xem "Truy vấn các lớp của trình xử lý tệp" trong PerlIO.)

PerlIO :: mã hóa, PerlIO :: vô hướng, PerlIO :: qua trong lõi Perl.

PerlIO :: gzip và APR :: PerlIO (mod_perl 2.0) trên CPAN.

· Triển khai Perl

PerlIO :: qua :: QuotedPrint trong lõi Perl và PerlIO :: qua :: * trên CPAN.

Nếu bạn đang tạo một lớp PerlIO, bạn có thể muốn lười biếng, nói cách khác, triển khai
chỉ những phương pháp mà bạn quan tâm. Các phương pháp khác bạn có thể thay thế bằng
phương thức "trống"

PerlIOBase_noop_ok
PerlIOBase_noop_fail

(không làm gì cả và trả về 1 và -XNUMX, tương ứng) hoặc đối với một số phương pháp nhất định, bạn có thể
giả định một hành vi mặc định bằng cách sử dụng một phương thức NULL. Phương thức Mở tìm kiếm sự trợ giúp trong
lớp 'cha'. Bảng sau đây tóm tắt hành vi:

hành vi phương thức với NULL

Rõ ràng hơn PerlIOBase_clearerr
Đóng PerlIOBase_close
Sao chép PerlIOBase_dup
Eof PerlIOBase_eof
Lỗi PerlIOBase_error
Tệp PerlIOBase_fileno
Điền vào sự THẤT BẠI
Tuôn ra thành công
Getarg THÀNH CÔNG
Get_base THẤT BẠI
Get_bufsiz THẤT BẠI
Get_cnt LỖI
Get_ptr LỖI
Mở INHERITED
THÀNH CÔNG
Thúc đẩy THÀNH CÔNG
Đọc PerlIOBase_read
Tìm kiếm thất bại
Set_cnt LỖI
Set_ptrcnt LỖI
Setlinebuf PerlIOBase_setlinebuf
Nói với FAILURE
PerlIOBase_unread chưa đọc
Viết THẤT BẠI

FAILURE Đặt errno (thành EINVAL trong Unixish, thành LIB $ _INVARG trong VMS) và
trả về -1 (đối với giá trị trả về dạng số) hoặc NULL (đối với con trỏ)
INHERITED Được kế thừa từ lớp bên dưới
SUCCESS Trả về 0 (đối với các giá trị trả về dạng số) hoặc một con trỏ

Trung tâm Layers
Tệp "perlio.c" cung cấp các lớp sau:

"unix"
Một lớp không đệm cơ bản gọi Unix / POSIX "read ()", "write ()", "lseek ()",
"gần()". Không có bộ đệm. Ngay cả trên các nền tảng phân biệt giữa O_TEXT và
O_BINARY lớp này luôn là O_BINARY.

"perlio"
Một lớp đệm chung rất hoàn chỉnh cung cấp toàn bộ API PerlIO. Nó là
cũng được sử dụng như một "lớp cơ sở" cho các lớp khác. (Ví dụ: "Read ()"
phương thức được triển khai theo các phương thức "Get_cnt ()" / "Get_ptr ()" / "Set_ptrcnt ()").

"perlio" thay vì "unix" cung cấp một sự thay thế hoàn toàn cho stdio như đã thấy qua API PerlIO.
Đây là mặc định cho USE_PERLIO khi stdio của hệ thống không cho phép perl "nhanh
được quyền truy cập "và không phân biệt giữa" O_TEXT "và" O_BINARY ".

"stdio"
Một lớp cung cấp API PerlIO thông qua lược đồ lớp, nhưng triển khai nó bằng cách
gọi stdio của hệ thống. Đây là (hiện tại) mặc định nếu stdio của hệ thống cung cấp
đủ quyền truy cập để cho phép truy cập "nhanh chóng" của perl và không phân biệt
giữa "O_TEXT" và "O_BINARY".

"crlf"
Một lớp có nguồn gốc bằng cách sử dụng "perlio" làm lớp cơ sở. Nó cung cấp "\ n" giống Win32 thành CR, LF
dịch. Có thể được áp dụng trên "perlio" hoặc dùng làm lớp đệm.
"crlf" trên "unix" là mặc định nếu hệ thống phân biệt giữa "O_TEXT" và
"O_BINARY" mở ra. (Tại một số điểm "unix" sẽ được thay thế bằng một lớp Win32 IO "nguyên bản"
trên nền tảng đó, vì lớp đọc / ghi của Win32 có nhiều nhược điểm khác nhau.) Lớp "crlf"
là một mô hình hợp lý cho một lớp biến đổi dữ liệu theo một cách nào đó.

"mmap"
Nếu Cấu hình phát hiện các chức năng "mmap ()" thì lớp này sẽ được cung cấp (với "perlio" là
"base") thực hiện các hoạt động "đọc" bởi mmap ()nhập tệp. Cải thiện hiệu suất là
biên trên các hệ thống hiện đại, vì vậy nó chủ yếu ở đó như một bằng chứng về khái niệm. Nó có khả năng
để được tách khỏi lõi tại một số điểm. Lớp "mmap" là một mô hình hợp lý
cho một lớp "có nguồn gốc" tối giản.

"chưa giải quyết"
Một dẫn xuất "nội bộ" của "perlio" có thể được sử dụng để cung cấp Chưa đọc () chức năng
cho các lớp không có bộ đệm hoặc không thể bị làm phiền. (Về cơ bản lớp này là
"Fill ()" tự bật ra khỏi ngăn xếp và do đó, tiếp tục đọc từ lớp bên dưới.)

"thô"
Một lớp giả không bao giờ tồn tại trên ngăn xếp lớp. Thay vào đó, khi "đẩy" nó thực sự
bật ngăn xếp đang xóa chính nó, sau đó nó gọi mục nhập bảng hàm Binmode trên tất cả
các lớp trong ngăn xếp - thông thường điều này (thông qua PerlIOBase_binmode) loại bỏ bất kỳ lớp nào
không đặt bit "PERLIO_K_RAW". Các lớp có thể sửa đổi hành vi đó bằng cách xác định
mục nhập Binmode riêng.

"utf8"
Một lớp giả khác. Khi được đẩy, nó sẽ tự bật lên và đặt cờ "PERLIO_F_UTF8" lên
lớp trước đây (và bây giờ là một lần nữa) trên cùng của ngăn xếp.

Ngoài ra perlio.c cũng cung cấp một số hàm "PerlIOBase_xxxx ()"
nhằm mục đích sử dụng trong các vị trí bảng của các lớp không cần phải làm bất cứ điều gì đặc biệt
cho một phương pháp cụ thể.

Extension Layers
Các lớp có thể được tạo sẵn bởi các mô-đun mở rộng. Khi gặp một lớp không xác định
mã PerlIO sẽ thực hiện tương đương với:

sử dụng 'lớp' PerlIO;

Ở đâu lớp là lớp chưa biết. PerlIO.pm sau đó sẽ cố gắng:

yêu cầu lớp PerlIO ::;

Nếu sau quá trình đó, lớp vẫn không được xác định thì "mở" sẽ không thành công.

Các lớp mở rộng sau được đóng gói với perl:

": mã hóa"
sử dụng Mã hóa;

làm cho lớp này có sẵn, mặc dù PerlIO.pm "biết" tìm nó ở đâu. Nó là một
ví dụ về một lớp có một đối số như nó được gọi như vậy:

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

":vô hướng"
Cung cấp hỗ trợ để đọc dữ liệu từ và ghi dữ liệu vào một đại lượng vô hướng.

open ($ fh, "+ <: vô hướng", \ $ vô hướng);

Khi một xử lý được mở như vậy, sau đó đọc các byte nhận được từ giá trị chuỗi của $ vô hướngvà
ghi thay đổi giá trị. Trong cả hai trường hợp, vị trí trong $ vô hướng bắt đầu bằng XNUMX nhưng có thể
được thay đổi thông qua "seek" và xác định thông qua "tell".

Xin lưu ý rằng lớp này được ngụ ý khi gọi mở() do đó:

open ($ fh, "+ <", \ $ vô hướng);

":thông qua"
Được cung cấp để cho phép các lớp được triển khai dưới dạng mã Perl. Ví dụ:

sử dụng PerlIO :: qua :: StripHTML;
open (my $ fh, "<: via (StripHTML)", "index.html");

Xem PerlIO :: qua để biết chi tiết.

ALL

Những điều cần làm để cải thiện tài liệu này.

· Giải thích cách tạo fh hợp lệ mà không cần thông qua mở()(tức là áp dụng một lớp). Vì
Ví dụ: nếu tệp không được mở thông qua perl, nhưng chúng tôi muốn lấy lại fh, giống như nó
đã được mở bởi Perl.

PerlIO_apply_layera phù hợp như thế nào, tài liệu của nó ở đâu, nó đã được công khai chưa?

Hiện tại, ví dụ có thể là một cái gì đó như thế này:

PerlIO * foo_to_PerlIO (pTHX_ char * mode, ...)
{
chế độ char *; / * "w", "r", v.v. * /
const char * layer = ": APR"; / * tên lớp * /
PerlIO * f = PerlIO_allocate (aTHX);
nếu (! f) {
trả về NULL;
}

PerlIO_apply_layers (aTHX_ f, chế độ, lớp);

nếu (f) {
PerlIOAPR * st = PerlIOSelf (f, PerlIOAPR);
/ * điền vào cấu trúc st, như trong _open () * /
st-> file = tập tin;
PerlIOBase (f) -> cờ | = PERLIO_F_OPEN;

trả về f;
}
trả về NULL;
}

· Sửa / thêm tài liệu ở những nơi được đánh dấu là XXX.

· Việc xử lý các lỗi của lớp không được chỉ định. ví dụ: khi $! nên được thiết lập
một cách rõ ràng, khi việc xử lý lỗi chỉ nên được ủy quyền cho lớp trên cùng.

Có thể đưa ra một số gợi ý về cách sử dụng SETERRNO () hoặc trỏ đến nơi chúng có thể được tìm thấy.

· Tôi nghĩ sẽ hữu ích nếu đưa ra một số ví dụ cụ thể để dễ hiểu hơn
API. Tất nhiên tôi đồng ý rằng API phải ngắn gọn, nhưng vì không có
tài liệu thứ hai mang tính hướng dẫn nhiều hơn, tôi nghĩ rằng nó sẽ giúp bạn bắt đầu dễ dàng hơn
với tài liệu là một API, nhưng có các ví dụ trong đó ở những nơi mọi thứ
không rõ ràng, đối với một người không phải là guru PerlIO (chưa).

Sử dụng perliol trực tuyến bằng các dịch vụ onworks.net