IPC::Door - Interface to Solaris (>= 2.6) Door library
The server script:
use IPC::Door::Server; use Fcntl; my $door = "/path/to/door"; my $dserver = new IPC::Door::Server($door, &mysub); while (1) { die "$door disappeared: $!\n" unless IPC::Door::is_door($door); sysopen( DOOR, $door, O_WRONLY ) || die "Can't write to $door: $!\n"; close DOOR; select undef, undef, undef, 0.2; } sub mysub { my $arg = shift; # do something my $ans; return $ans; }
The client script:
use IPC::Door::Client; use Fcntl; my $door = "/path/to/door"; my $dclient = new IPC::Door::Client($door); my $data; my $answer = $client->call($data, O_RDWR);
IPC::Door is a Perl extension to the door library present in Solaris 2.6 and later.
The method new initializes the object, taking a mandatory argument $path. Each IPC::Door::* object is thus associated with a door through which it communicates with a server (if the object is a ::Client) or a client (if the object is a ::Server).
new
$path
IPC::Door::*
::Client
::Server
In addition, the IPC::Door::Server object requires a reference to a code block &mysub, which will be a part of the server process upon compilation. See IPC::Door::Server.
IPC::Door::Server
&mysub
$dserver->is_door; IPC::Door::is_door('/path/to/door');
Subroutine is_door can be called either as an object method or as a subroutine.
is_door
If the former, it determines if the path name assoicated with the object is a door. In the latter case, it determines if the path name passed to it is a door.
my ($target, $attr, $uniq) = IPC::Door::info($door);
Subroutine info takes the path to a door and return array ($target, $attributes, $uniquifer). $target is the server process id that is listening through the door. $attributes is the integer that represents the attributes of the door (see "Door attributes"), and $uniquifer is the system-wide unique number associated with the door.
info
($target, $attributes, $uniquifer)
$target
$attributes
$uniquifer
When testing for a door's attributes, it is convenient to import some symbols:
use IPC::Door qw( :attr );
This imports symbols DOOR_ATTR_MASK DOOR_CREATE_MASK DOOR_DELAY DOOR_IS_UNREF DOOR_KI_CREATE_MASK DOOR_LOCAL DOOR_PRIVATE DOOR_REVOKED DOOR_UNREF DOOR_UNREF_ACTIVE DOOR_UNREF_MULTI
DOOR_ATTR_MASK
DOOR_CREATE_MASK
DOOR_DELAY
DOOR_IS_UNREF
DOOR_KI_CREATE_MASK
DOOR_LOCAL
DOOR_PRIVATE
DOOR_REVOKED
DOOR_UNREF
DOOR_UNREF_ACTIVE
DOOR_UNREF_MULTI
Note that not all symbols are available in all versions of Solaris.
I know this module does not work nicely if perl was configured with -Dusethreads option. I know that the precompiled package from http://www.blastwave.org has this option set. I am not sure about the one from http://www.sunfreeware.com.
-Dusethreads
The doors created by IPC::Door::Server evaluates the passed data in the scalar context before passing it to the door server. If you want to pass complex data structures, use the Storable module, which is standard as of Perl 5.8.0.
Data an IPC::Door::Server object returns are probably incomprehensible and useless for non-IPC::Door::Client processes. You can read the source to find out exactly what are passed around, but it might not be worth your while to do that, when you can simply use IPC::Door::Client. (And of course, I might change the internal data structure in the future.)
IPC::Door::Client
Conversely, IPC::Door::Client can read data from doors created by non-IPC::Door::Server processes, but it is entirely up to the IPC::Door::Client process to make sense of what's read.
door_*
Some door library routines door_bind, door_revoke, door_server_create, and door_unbind still need to be implemented. These routines contribute to custom door server creation, which may be too complicated and unnecessary for this module's needs; if such a fine control over the server creation process is required, perhaps you should be writing your utility in C! If you are really interested in this sort of thing, contact the author.
door_bind
door_revoke
door_server_create
door_unbind
door_info is only partially implemented.
door_info
There should be more robust error checking and more friendly error messages throughout.
IPC::Door has been tested on Solaris 8 (with Sun Workshop compiler), 9 (with gcc 3.3), and 10 (with gcc 4.0.0) (all on SPARC).
IPC::Door
I need more testing on following configurations (both SPARC and x86 unless otherwisse noted):
Solaris 9 and 10 with Sun ONE Studio compiler (or whatever Sun calls its C compiler these days).
64-bit perl executable.
Threaded perl. (See above.)
Solaris 10 on x86.
Please let me know if you can help me test the module on these configurations.
I'm still a beginner at XS (some may argue also at Perl), so the code, especially the XS portion, can be improved. Any suggestions are welcome.
In my limited testing, I found that this module has difficulty dealing with Unicode data.
IPC::Door::Client, IPC::Door::Server
door_bind(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3m?a=view),
door_call(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3n?a=view),
door_create(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3n?a=view),
door_cred(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3p?a=view),
door_info(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3q?a=view),
door_return(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3r?a=view),
door_revoke(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3s?a=view),
door_server_create(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3t?a=view),
door_ucred(3DOOR) (http://docs.sun.com/app/docs/doc/816-5171/6mbb6dcnk?a=view),
door_unbind(3DOOR) (http://docs.sun.com/db/doc/817-0697/6mgfsdh3u?a=view),
UNIX Network Programming Volume 2: Interprocess Communications (http://www.kohala.com/start/unpv22e/unpv22e.html)
Solaris Internals: Core Kernel Architecture (http://www.solarisinternals.com)
ASARI Hirotsugu <asarih at cpan dot org>
(http://www.asari.net/perl)
Copyright 2003-2005 by ASARI Hirotsugu
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install IPC::Door, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IPC::Door
CPAN shell
perl -MCPAN -e shell install IPC::Door
For more information on module installation, please visit the detailed CPAN module installation guide.