=over

=item ioctl FILEHANDLE,FUNCTION,SCALAR

Implements the ioctl(2) function.  You'll probably have to say

    require "ioctl.ph";	# probably in /usr/local/lib/perl/ioctl.ph

first to get the correct function definitions.  If F<ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
own, based on your C header files such as F<E<lt>sys/ioctl.hE<gt>>.
(There is a Perl script called B<h2ph> that comes with the Perl kit that
may help you in this, but it's nontrivial.)  SCALAR will be read and/or
written depending on the FUNCTION--a pointer to the string value of SCALAR
will be passed as the third argument of the actual C<ioctl()> call.  (If SCALAR
has no string value but does have a numeric value, that value will be
passed rather than a pointer to the string value.  To guarantee this to be
TRUE, add a C<0> to the scalar before using it.)  The C<pack()> and C<unpack()>
functions are useful for manipulating the values of structures used by
C<ioctl()>.  The following example sets the erase character to DEL.

    require 'ioctl.ph';
    $getp = &TIOCGETP;
    die "NO TIOCGETP" if $@ || !$getp;
    $sgttyb_t = "ccccs";		# 4 chars and a short
    if (ioctl(STDIN,$getp,$sgttyb)) {
	@ary = unpack($sgttyb_t,$sgttyb);
	$ary[2] = 127;
	$sgttyb = pack($sgttyb_t,@ary);
	ioctl(STDIN,&TIOCSETP,$sgttyb)
	    || die "Can't ioctl: $!";
    }

The return value of C<ioctl()> (and C<fcntl()>) is as follows:

	if OS returns:		then Perl returns:
	    -1	  		  undefined value
	     0	 		string "0 but true"
	anything else		    that number

Thus Perl returns TRUE on success and FALSE on failure, yet you can
still easily determine the actual value returned by the operating
system:

    ($retval = ioctl(...)) || ($retval = -1);
    printf "System returned %d\n", $retval;

The special string "C<0> but true" is excempt from B<-w> complaints
about improper numeric conversions.

=back