[perl5.git] / plan9 / perlplan9.pod

=head1 NAME

perlplan9 - Plan 9-specific documentation for Perl

=head1 DESCRIPTION

These are a few notes describing features peculiar to
Plan 9 Perl. As such, it is not intended to be a replacement
for the rest of the Perl 5 documentation (which is both 
copious and excellent). If you have any questions to 
which you can't find answers in these man pages, contact 
Luther Huffman at lutherh@stratcom.com and we'll try to 
answer them.

=head2 Invoking Perl

Perl is invoked from the command line as described in 
L<perl>. Most perl scripts, however, do have a first line 
such as "#!/usr/local/bin/perl". This is known as a shebang 
(shell-bang) statement and tells the OS shell where to find 
the perl interpreter. In Plan 9 Perl this statement should be 
"#!/bin/perl" if you wish to be able to directly invoke the 
script by its name.
     Alternatively, you may invoke perl with the command "aperl"
instead of "perl". This will produce Acme-friendly error
messages of the form "filename:18".

Some scripts, usually identified with a *.PL extension, are 
self-configuring and are able to correctly create their own 
shebang path from config information located in Plan 9 
Perl. These you won't need to be worried about.

=head2 What's in Plan 9 Perl

Although Plan 9 Perl currently only  provides static 
loading, it is built with a number of useful extensions. 
These include Safe, FileHandle, Fcntl, and POSIX. Expect 
to see others (and DynaLoading!) in the future.

=head2 What's not in Plan 9 Perl

As mentioned previously, dynamic loading isn't currently 
available nor is MakeMaker. Both are high-priority items.

=head2 Perl5 Functions not currently supported

Some, such as C<chown> and C<umask> aren't provided 
because the concept does not exist within Plan 9. Others,
such as some of the socket-related functions, simply
haven't been written yet. Many in the latter category 
may be supported in the future.

The functions not currently implemented include:

    chown, chroot, dbmclose, dbmopen, getsockopt, 
    setsockopt, recvmsg, sendmsg, getnetbyname, 
    getnetbyaddr, getnetent, getprotoent, getservent, 
    sethostent, setnetent, setprotoent, setservent, 
    endservent, endnetent, endprotoent, umask

There may be several other functions that have undefined 
behavior so this list shouldn't be considered complete.

=head2 Signals

For compatibility with perl scripts written for the Unix 
environment, Plan 9 Perl uses the POSIX signal emulation
provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
isn't supported. The signals provided are:

    SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
    SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM, 
    SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
    SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU

=head1 BUGS

"As many as there are grains of sand on all the beaches of the 
world . . ." - Carl Sagan

=head1 Revision date

This document was revised 04-July-1996 for Perl 5.003_1.

=head1 AUTHOR

Luther Huffman,    lutherh@stratcom.com
Commit	Line	Data
396e9e6f	1	=head1 NAME
	2
	3	perlplan9 - Plan 9-specific documentation for Perl
	4
	5	=head1 DESCRIPTION
	6
	7	These are a few notes describing features peculiar to
	8	Plan 9 Perl. As such, it is not intended to be a replacement
	9	for the rest of the Perl 5 documentation (which is both
	10	copious and excellent). If you have any questions to
	11	which you can't find answers in these man pages, contact
	12	Luther Huffman at lutherh@stratcom.com and we'll try to
	13	answer them.
	14
	15	=head2 Invoking Perl
	16
	17	Perl is invoked from the command line as described in
	18	L<perl>. Most perl scripts, however, do have a first line
	19	such as "#!/usr/local/bin/perl". This is known as a shebang
	20	(shell-bang) statement and tells the OS shell where to find
	21	the perl interpreter. In Plan 9 Perl this statement should be
	22	"#!/bin/perl" if you wish to be able to directly invoke the
	23	script by its name.
	24	Alternatively, you may invoke perl with the command "aperl"
	25	instead of "perl". This will produce Acme-friendly error
	26	messages of the form "filename:18".
	27
	28	Some scripts, usually identified with a *.PL extension, are
	29	self-configuring and are able to correctly create their own
	30	shebang path from config information located in Plan 9
	31	Perl. These you won't need to be worried about.
	32
	33	=head2 What's in Plan 9 Perl
	34
	35	Although Plan 9 Perl currently only provides static
	36	loading, it is built with a number of useful extensions.
	37	These include Safe, FileHandle, Fcntl, and POSIX. Expect
	38	to see others (and DynaLoading!) in the future.
	39
	40	=head2 What's not in Plan 9 Perl
	41
	42	As mentioned previously, dynamic loading isn't currently
	43	available nor is MakeMaker. Both are high-priority items.
	44
	45	=head2 Perl5 Functions not currently supported
	46
	47	Some, such as C<chown> and C<umask> aren't provided
	48	because the concept does not exist within Plan 9. Others,
	49	such as some of the socket-related functions, simply
	50	haven't been written yet. Many in the latter category
	51	may be supported in the future.
	52
	53	The functions not currently implemented include:
	54
	55	chown, chroot, dbmclose, dbmopen, getsockopt,
	56	setsockopt, recvmsg, sendmsg, getnetbyname,
	57	getnetbyaddr, getnetent, getprotoent, getservent,
	58	sethostent, setnetent, setprotoent, setservent,
	59	endservent, endnetent, endprotoent, umask
	60
	61	There may be several other functions that have undefined
	62	behavior so this list shouldn't be considered complete.
	63
	64	=head2 Signals
65
66	For compatibility with perl scripts written for the Unix
67	environment, Plan 9 Perl uses the POSIX signal emulation
68	provided in Plan 9's ANSI POSIX Environment (APE). Signal stacking
69	isn't supported. The signals provided are:
70
71	SIGHUP, SIGINT, SIGQUIT, SIGILL, SIGABRT,
72	SIGFPE, SIGKILL, SIGSEGV, SIGPIPE, SIGPIPE, SIGALRM,
73	SIGTERM, SIGUSR1, SIGUSR2, SIGCHLD, SIGCONT,
74	SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU
75
76	=head1 BUGS
77
78	"As many as there are grains of sand on all the beaches of the
79	world . . ." - Carl Sagan
80
81	=head1 Revision date
82
83	This document was revised 04-July-1996 for Perl 5.003_1.
84
85	=head1 AUTHOR
86
43cc1d52	87	Luther Huffman, lutherh@stratcom.com