This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Upgrade to IPC::SysV 1.99_07
[perl5.git] / ext / IPC / SysV / lib / IPC / SharedMem.pm
CommitLineData
8f85282b
MHM
1################################################################################
2#
3# $Revision: 2 $
4# $Author: mhx $
5# $Date: 2007/10/14 05:16:08 +0200 $
6#
7################################################################################
8#
9# Version 2.x, Copyright (C) 2007, Marcus Holland-Moritz <mhx@cpan.org>.
10# Version 1.x, Copyright (C) 1997, Graham Barr <gbarr@pobox.com>.
11#
12# This program is free software; you can redistribute it and/or
13# modify it under the same terms as Perl itself.
14#
15################################################################################
16
17package IPC::SharedMem;
18
19use IPC::SysV qw(IPC_STAT IPC_RMID shmat shmdt memread memwrite);
20use strict;
21use vars qw($VERSION);
22use Carp;
23
24$VERSION = do { my @r = '$Snapshot: /IPC-SysV/1.99_07 $' =~ /(\d+\.\d+(?:_\d+)?)/; @r ? $r[0] : '9.99' };
25$VERSION = eval $VERSION;
26
27# Figure out if we have support for native sized types
28my $N = do { my $foo = eval { pack "L!", 0 }; $@ ? '' : '!' };
29
30{
31 package IPC::SharedMem::stat;
32
33 use Class::Struct qw(struct);
34
35 struct 'IPC::SharedMem::stat' => [
36 uid => '$',
37 gid => '$',
38 cuid => '$',
39 cgid => '$',
40 mode => '$',
41 segsz => '$',
42 lpid => '$',
43 cpid => '$',
44 nattch => '$',
45 atime => '$',
46 dtime => '$',
47 ctime => '$',
48 ];
49}
50
51sub new
52{
53 @_ == 4 or croak 'IPC::SharedMem->new(KEY, SIZE, FLAGS)';
54 my($class, $key, $size, $flags) = @_;
55
56 my $id = shmget $key, $size, $flags or return undef;
57
58 bless { _id => $id, _addr => undef, _isrm => 0 }, $class
59}
60
61sub id
62{
63 my $self = shift;
64 $self->{_id};
65}
66
67sub addr
68{
69 my $self = shift;
70 $self->{_addr};
71}
72
73sub stat
74{
75 my $self = shift;
76 my $data = '';
77 shmctl $self->id, IPC_STAT, $data or return undef;
78 IPC::SharedMem::stat->new->unpack($data);
79}
80
81sub attach
82{
83 @_ >= 1 && @_ <= 2 or croak '$shm->attach([FLAG])';
84 my($self, $flag) = @_;
85 defined $self->addr and return undef;
86 $self->{_addr} = shmat($self->id, undef, $flag || 0);
87 defined $self->addr;
88}
89
90sub detach
91{
92 my $self = shift;
93 defined $self->addr or return undef;
94 my $rv = defined shmdt($self->addr);
95 undef $self->{_addr} if $rv;
96 $rv;
97}
98
99sub remove
100{
101 my $self = shift;
102 return undef if $self->is_removed;
103 my $rv = shmctl $self->id, IPC_RMID, 0;
104 $self->{_isrm} = 1 if $rv;
105 return $rv;
106}
107
108sub is_removed
109{
110 my $self = shift;
111 $self->{_isrm};
112}
113
114sub read
115{
116 @_ == 3 or croak '$shm->read(POS, SIZE)';
117 my($self, $pos, $size) = @_;
118 my $buf = '';
119 if (defined $self->addr) {
120 memread($self->addr, $buf, $pos, $size) or return undef;
121 }
122 else {
123 shmread($self->id, $buf, $pos, $size) or return undef;
124 }
125 $buf;
126}
127
128sub write
129{
130 @_ == 4 or croak '$shm->write(STRING, POS, SIZE)';
131 my($self, $str, $pos, $size) = @_;
132 if (defined $self->addr) {
133 return memwrite($self->addr, $str, $pos, $size);
134 }
135 else {
136 return shmwrite($self->id, $str, $pos, $size);
137 }
138}
139
1401;
141
142__END__
143
144=head1 NAME
145
146IPC::SharedMem - SysV Shared Memory IPC object class
147
148=head1 SYNOPSIS
149
150 use IPC::SysV qw(IPC_PRIVATE S_IRUSR S_IWUSR);
151 use IPC::SharedMem;
152
153 $shm = IPC::SharedMem->new(IPC_PRIVATE, 8, S_IRWXU);
154
155 $shm->write(pack("S", 4711), 2, 2);
156
157 $data = $shm->read(0, 2);
158
159 $ds = $shm->stat;
160
161 $shm->remove;
162
163=head1 DESCRIPTION
164
165A class providing an object based interface to SysV IPC shared memory.
166
167=head1 METHODS
168
169=over 4
170
171=item new ( KEY , SIZE , FLAGS )
172
173Creates a new shared memory segment associated with C<KEY>. A new
174segment is created if
175
176=over 4
177
178=item *
179
180C<KEY> is equal to C<IPC_PRIVATE>
181
182=item *
183
184C<KEY> does not already have a shared memory segment associated
185with it, and C<I<FLAGS> & IPC_CREAT> is true.
186
187=back
188
189On creation of a new shared memory segment C<FLAGS> is used to
190set the permissions. Be careful not to set any flags that the
191Sys V IPC implementation does not allow: in some systems setting
192execute bits makes the operations fail.
193
194=item id
195
196Returns the shared memory identifier.
197
198=item read ( POS, SIZE )
199
200Read C<SIZE> bytes from the shared memory segment at C<POS>. Returns
201the string read, or C<undef> if there was an error. The return value
202becomes tainted. See L<shmread>.
203
204=item write ( STRING, POS, SIZE )
205
206Write C<SIZE> bytes to the shared memory segment at C<POS>. Returns
207true if successful, or false if there is an error. See L<shmwrite>.
208
209=item remove
210
211Remove the shared memory segment from the system or mark it as
212removed as long as any processes are still attached to it.
213
214=item is_removed
215
216Returns true if the shared memory segment has been removed or
217marked for removal.
218
219=item stat
220
221Returns an object of type C<IPC::SharedMem::stat> which is a sub-class
222of C<Class::Struct>. It provides the following fields. For a description
223of these fields see you system documentation.
224
225 uid
226 gid
227 cuid
228 cgid
229 mode
230 segsz
231 lpid
232 cpid
233 nattach
234 atime
235 dtime
236 ctime
237
238=item attach ( [FLAG] )
239
240Permanently attach to the shared memory segment. When a C<IPC::SharedMem>
241object is attached, it will use L<memread> and L<memwrite> instead of
242L<shmread> and L<shmwrite> for accessing the shared memory segment.
243Returns true if successful, or false on error. See L<shmat>.
244
245=item detach
246
247Detach from the shared memory segment that previously has been attached
248to. Returns true if successful, or false on error. See L<shmdt>.
249
250=item addr
251
252Returns the address of the shared memory that has been attached to in a
253format suitable for use with C<pack('P')>. Returns C<undef> if the shared
254memory has not been attached.
255
256=back
257
258=head1 SEE ALSO
259
260L<IPC::SysV>, L<Class::Struct>
261
262=head1 AUTHORS
263
264Marcus Holland-Moritz <mhx@cpan.org>
265
266=head1 COPYRIGHT
267
268Version 2.x, Copyright (C) 2007, Marcus Holland-Moritz.
269
270Version 1.x, Copyright (c) 1997, Graham Barr.
271
272This program is free software; you can redistribute it and/or
273modify it under the same terms as Perl itself.
274
275=cut
276