Debian Codegraph @

upstream/debian-unstable/man3/Tie::Handle.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Tie::Handle 3perl"
58 .TH Tie::Handle 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Tie::Handle \- base class definitions for tied handles
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 2
68 \& package NewHandle;
69 \& require Tie::Handle;
70 \&
71 \& @ISA = qw(Tie::Handle);
72 \&
73 \& sub READ { ... } # Provide a needed method
74 \& sub TIEHANDLE { ... } # Overrides inherited method
75 \&
76 \&
77 \& package main;
78 \&
79 \& tie *FH, \*(AqNewHandle\*(Aq;
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 This module provides some skeletal methods for handle-tying classes. See
84 perltie for a list of the functions required in tying a handle to a package.
85 The basic \fBTie::Handle\fR package provides a \f(CW\*(C`new\*(C'\fR method, as well as methods
86 \&\f(CW\*(C`TIEHANDLE\*(C'\fR, \f(CW\*(C`PRINT\*(C'\fR, \f(CW\*(C`PRINTF\*(C'\fR and \f(CW\*(C`GETC\*(C'\fR.
87 .PP
88 For developers wishing to write their own tied-handle classes, the methods
89 are summarized below. The perltie section not only documents these, but
90 has sample code as well:
91 .IP "TIEHANDLE classname, LIST" 4
92 .IX Item "TIEHANDLE classname, LIST"
93 The method invoked by the command \f(CW\*(C`tie *glob, classname\*(C'\fR. Associates a new
94 glob instance with the specified class. \f(CW\*(C`LIST\*(C'\fR would represent additional
95 arguments (along the lines of AnyDBM_File and compatriots) needed to
96 complete the association.
97 .IP "WRITE this, scalar, length, offset" 4
98 .IX Item "WRITE this, scalar, length, offset"
99 Write \fIlength\fR bytes of data from \fIscalar\fR starting at \fIoffset\fR.
100 .IP "PRINT this, LIST" 4
101 .IX Item "PRINT this, LIST"
102 Print the values in \fILIST\fR
103 .IP "PRINTF this, format, LIST" 4
104 .IX Item "PRINTF this, format, LIST"
105 Print the values in \fILIST\fR using \fIformat\fR
106 .IP "READ this, scalar, length, offset" 4
107 .IX Item "READ this, scalar, length, offset"
108 Read \fIlength\fR bytes of data into \fIscalar\fR starting at \fIoffset\fR.
109 .IP "READLINE this" 4
110 .IX Item "READLINE this"
111 Read a single line
112 .IP "GETC this" 4
113 .IX Item "GETC this"
114 Get a single character
115 .IP "CLOSE this" 4
116 .IX Item "CLOSE this"
117 Close the handle
118 .IP "OPEN this, filename" 4
119 .IX Item "OPEN this, filename"
120 (Re\-)open the handle
121 .IP "BINMODE this" 4
122 .IX Item "BINMODE this"
123 Specify content is binary
124 .IP "EOF this" 4
125 .IX Item "EOF this"
126 Test for end of file.
127 .IP "TELL this" 4
128 .IX Item "TELL this"
129 Return position in the file.
130 .IP "SEEK this, offset, whence" 4
131 .IX Item "SEEK this, offset, whence"
132 Position the file.
133 .Sp
134 Test for end of file.
135 .IP "DESTROY this" 4
136 .IX Item "DESTROY this"
137 Free the storage associated with the tied handle referenced by \fIthis\fR.
138 This is rarely needed, as Perl manages its memory quite well. But the
139 option exists, should a class wish to perform specific actions upon the
140 destruction of an instance.
141 .SH "MORE INFORMATION"
142 .IX Header "MORE INFORMATION"
143 The perltie section contains an example of tying handles.
144 .SH COMPATIBILITY
145 .IX Header "COMPATIBILITY"
146 This version of Tie::Handle is neither related to nor compatible with
147 the Tie::Handle (3.0) module available on CPAN. It was due to an
148 accident that two modules with the same name appeared. The namespace
149 clash has been cleared in favor of this module that comes with the
150 perl core in September 2000 and accordingly the version number has
151 been bumped up to 4.0.