This file is indexed.

/usr/share/perl5/Prima/File.pod is in libprima-perl 1.28-1.2.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
=for rcs $Id: File.pod,v 1.5 2004/12/15 16:11:03 dk Exp $

=head1 NAME

Prima::File - asynchronous stream I/O.

=head1 SYNOPSIS

  use strict;
  use Prima qw(Application);

  # create pipe and autoflush the writer end
  pipe(READ, WRITE) or die "pipe():$!\n"; 
  select WRITE;
  $|=1;
  select STDOUT;

  # create Prima listener on the reader end
  my $read = Prima::File-> new(
      file => \*READ,
      mask => fe::Read,
      onRead => sub {
      	 $_ = <READ>;
	 print "read:$_\n";
      },
  );

  print WRITE "line\n";
  run Prima;

=head1 DESCRIPTION

Prima::File provides access to the I/O stream events,
that are called when a file handle becomes readable, writable
or if an exception occurred. Registering file handles to Prima::File
objects makes possible the stream operations coexist with the event loop. 

=head1 USAGE

Prima::File is a descendant of Prima::Component.
Objects of Prima::File class must be binded to a valid file handle object,
before the associated events can occur:

  my $f = Prima::File-> create();
  $f-> file( *STDIN);

When a file handle, binded via the C<::file> property becomes readable,
writable or when an exception signaled, one of three correspondent
events called - C<Read>, C<Write> or C<Exception>. When a handle is
always readable, or always writable, or, some of these events are
desired to be blocked, the file event mask can be set via the C<::mask>
property:

  $f-> mask( fe::Read | fe::Exception);

NB. Due to different system implementations, the only handles,
currently supported on all systems, are socket handle and disk file 
handles. Pipes only work on unix platforms. The example file I<socket.pl>
elucidates the use of sockets together with Prima::File.

When a file handle is not needed anymore, it is expected to
be detached from an object explicitly:

  $f-> file( undef);

However, if the system detects that a file handle is no longer valid,
it is automatically detached. It is possible to check, if a file handle
is still valid by calling the C<is_active()> method.

Prima::File events are basically the same I/O callbacks, provided by
a system C<select()> call. See documentation of your system's select()
for the implementation details.

=head1 API

=head2 Properties

=over

=item file HANDLE

Selects a file handle, that is to be monitored for stream I/O events.
If HANDLE is C<undef>, object is returned to a passive state, and
the previously binded file handle is de-selected.

=item mask EVENT_MASK

Selects a event mask, that is a combination of C<fe::XXX> integer constants,
each representing an event:

   fe::Read
   fe::Write
   fe::Exception

The omitted events are effectively excluded from the system file event
multiplexing mechanism.

=back

=head2 Methods

=over

=item get_handle

Returns C<sprintf("0x%08x", fileno( file ))> string.
If C<::file> is C<undef>, -1 is used instead fileno() result.

=item is_active AUTODETACH = 0

Returns a boolean flag, indicating if a file handle is valid.
If AUTODETACH is 1, and the file handle is not valid, 
C<file(undef)> is called.

=back

=head2 Events

=over

=item Read

Called when a file handle becomes readable. The callback procedure
is expected to call a non-blocking read() on the file handle.

=item Write

Called when a file handle becomes writable. The callback procedure
is expected to call a non-blocking write() on the file handle.

=item Exception

Called when an exception is signaled on a file handle.
The exceptions are specific to handle type and the operating system.
For example, a unix socket signals C<Exception> when a control status 
data for a pseudo terminal or an out-of-band data arrives.

=back

=head1 AUTHOR

Dmitry Karasik, E<lt>dmitry@karasik.eu.orgE<gt>.

=head1 SEE ALSO

L<Prima>, L<Prima::Object>