sys::syscall(3pm) [debian man page]

Sys::Syscall(3pm)					User Contributed Perl Documentation					 Sys::Syscall(3pm)

NAME

       Sys::Syscall - access system calls that Perl doesn't normally provide access to

SYNOPSIS

	 use Sys::Syscall;

DESCRIPTION

       Use epoll, sendfile, from Perl.	Mostly Linux-only support now, but more syscalls/OSes planned for future.

Exports
       Nothing by default.

       May export: sendfile epoll_ctl epoll_create epoll_wait EPOLLIN EPOLLOUT EPOLLERR EPOLLHUP EPOLL_CTL_ADD	EPOLL_CTL_DEL EPOLL_CTL_MOD

       Export tags:  :epoll and :sendfile

Functions
   epoll support
       $ok = epoll_defined()
	   Returns true if epoll might be available.  (caller must still test with epoll_create)

       $epfd = epoll_create([ $start_size ])
	   Create a new epoll filedescriptor.  Returns -1 if epoll isn't available.

       $rv = epoll_ctl($epfd, $op, $fd, $events)
	   See manpage for epoll_ctl

       $count = epoll_wait($epfd, $max_events, $timeout, $arrayref)
	   See manpage for epoll_wait.	$arrayref is an arrayref to be modified with the items returned.  The values put into $arrayref are
	   arrayrefs of [$fd, $state].

   sendfile support
       $ok = sendfile_defined()
	   Returns true if sendfile should work on this operating system.

       $sent = sendfile($sock_fd, $file_fd, $max_send)
	   Sends up to $max_send bytes from $file_fd to $sock_fd.  Returns bytes actually sent, or -1 on error.

COPYRIGHT

       This module is Copyright (c) 2005, 2006 Six Apart, Ltd.

       All rights reserved.

       You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.
       If you need more liberal licensing terms, please contact the maintainer.

Contributing
       Want to contribute?  See:

	 L<http://contributing.appspot.com/sys-syscall>

WARRANTY

       This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.

AUTHORS

       Brad Fitzpatrick <brad@danga.com>

perl v5.10.1							    2010-04-19							 Sys::Syscall(3pm)

IO::Epoll(3pm)						User Contributed Perl Documentation					    IO::Epoll(3pm)

NAME

       IO::Epoll - Scalable IO Multiplexing for Linux 2.5.44 and higher

SYNOPSIS

	   # Low level interface
	   use IO::Epoll;

	   $epfd = epoll_create(10);

	   epoll_ctl($epfd, EPOLL_CTL_ADD, fileno STDIN, EPOLLIN) >= 0
	       || die "epoll_ctl: $!
";
	   epoll_ctl($epfd, ...);

	   $events = epoll_wait($epfd, 10, 1000); # Max 10 events returned, 1s timeout

	   # High level IO::Poll emulation layer
	   use IO::EPoll qw(:compat);

	   $poll = new IO::Epoll;

	   $poll->mask($input_handle => POLLIN);
	   $poll->mask($output_handle => POLLOUT);

	   $poll->poll($timeout);

	   $ev = $poll->events($input);

DESCRIPTION

       The epoll(4) subsystem is a new, (currently) Linux-specific variant of poll(2).	It is designed to offer O(1) scalability over large
       numbers of watched file descriptors.  You will need at least version 2.5.44 of Linux to use this module, and you might need to upgrade your
       C library.

       The epoll(2) API comprises four system calls: epoll_create(2), epoll_ctl(2), epoll_wait(2) and epoll_pwait(2).  "IO::Epoll" provides a low-
       level API which closely matches the underlying system calls.  It also provides a higher-level layer designed to emulate the behavior of
       "IO::Poll" and "IO::Ppoll".

LOW-LEVEL API
   epoll_create
       Create a new "epoll" file descriptor by requesting the kernel allocate an event backing store dimensioned for "size" descriptors.  The size
       is not the maximum size of the backing store but just a hint to the kernel about how to dimension internal structures.  The returned file
       descriptor will be used for all the subsequent calls to the "epoll" interface.  The file descriptor returned by "epoll_create" must be
       closed by using "POSIX::close".

	   $epfd = epoll_create(15);
	   ...
	   POSIX::close($epfd);

       When successful, "epoll_create" returns a positive integer identifying the descriptor.  When an error occurs, "epoll_create" returns -1 and
       errno is set appropriately.

   epoll_ctl
       Control an "epoll" descriptor, $epfd, by requesting the operation op be performed on the target file descriptor, fd.

	 $ret = epoll_ctl($epfd, $op, $fd, $eventmask)

       $epfd is an "epoll" descriptor returned from "epoll_create".

       $op is one of "EPOLL_CTL_ADD", "EPOLL_CTL_MOD" or "EPOLL_CTL_DEL".

       $fd is the file desciptor to be watched.

       $eventmask is a bitmask of events defined by "EPOLLIN", "EPOLLOUT", etc.

       When successful, "epoll_ctl" returns 0.	When an error occurs, "epoll_ctl" returns -1 and errno is set appropriately.

   epoll_wait
       Wait for events on the "epoll" file descriptor $epfd.

	 $ret = epoll_wait($epfd, $maxevents, $timeout)

       $epfd is an "epoll" descriptor returned from "epoll_create".

       $maxevents is an integer specifying the maximum number of events to be returned.

       $timeout is a timeout, in milliseconds

       When successful, "epoll_wait" returns a reference to an array of events.  Each event is a two element array, the first element being the
       file descriptor which triggered the event, and the second is the mask of event types triggered.	For example, if "epoll_wait" returned the
       following data structure:

	   [
	     [ 0, EPOLLIN ],
	     [ 6, EPOLLOUT | EPOLLIN ]
	   ]

       then file descriptor 0 would be ready for reading, and fd 4 would be ready for both reading and writing.

       On error, "epoll_wait" returns undef and sets "errno" appropriately.

   epoll_pwait
       Wait for events on the "epoll" file descriptor $epfd.

	 $ret = epoll_pwait($epfd, $maxevents, $timeout, $sigmask)

       Identical to "epoll_wait", except that the kernel will atomically swap the current signal mask for the process to that supplied in
       $sigmask, wait for events, then restore it to what it was originally. The $sigmask parameter should be undef, or an instance of
       "POSIX::SigSet".

HIGH LEVEL API

       IO::Epoll provides an object oriented API designed to be a drop-in replacement for IO::Poll.  See the documentation for that module for
       more information.

METHODS

       mask ( IO [, EVENT_MASK ] )
	   If EVENT_MASK is given, then, if EVENT_MASK is non-zero, IO is added to the list of file descriptors and the next call to poll will
	   check for any event specified in EVENT_MASK. If EVENT_MASK is zero then IO will be removed from the list of file descriptors.

	   If EVENT_MASK is not given then the return value will be the current event mask value for IO.

       poll ( [ TIMEOUT ] )
	   Call the system level poll routine. If TIMEOUT is not specified then the call will block. Returns the number of handles which had
	   events happen, or -1 on error. TIMEOUT is in seconds and may be fractional.

       events ( IO )
	   Returns the event mask which represents the events that happend on IO during the last call to "poll".

       remove ( IO )
	   Remove IO from the list of file descriptors for the next poll.

       handles( [ EVENT_MASK ] )
	   Returns a list of handles. If EVENT_MASK is not given then a list of all handles known will be returned. If EVENT_MASK is given then a
	   list of handles will be returned which had one of the events specified by EVENT_MASK happen during the last call ti "poll"

IO
::Ppoll METHODS
       IO::Epoll also provides methods compatible with IO::Ppoll. When any of these methods are called, the IO::Epoll object switches up to
       IO::Ppoll-compatible mode, and will use the epoll_pwait(2) system call when the "poll" method is invoked.

       sigmask
	   Returns the "POSIX::SigSet" object in which the signal mask is stored. Since this is a reference to the object used in the call to
	   epoll_pwait(2), any modifications made to it will be reflected in the signal mask given to the system call.

       sigmask_add ( SIGNALS )
	   Adds the given signals to the signal mask. These signals will be blocked during the "poll" call.

       sigmask_del ( SIGNALS )
	   Removes the given signals from the signal mask. These signals will not be blocked during the "poll" call, and may be delivered while
	   "poll" is waiting.

       sigmask_ismember ( SIGNAL )
	   Tests if the given signal is present in the signal mask.

Exportable constants
       Exported by default:

	 EPOLLERR
	 EPOLLET
	 EPOLLHUP
	 EPOLLIN
	 EPOLLMSG
	 EPOLLOUT
	 EPOLLPRI
	 EPOLLRDBAND
	 EPOLLRDNORM
	 EPOLLWRBAND
	 EPOLLWRNORM
	 EPOLL_CTL_ADD
	 EPOLL_CTL_DEL
	 EPOLL_CTL_MOD

       Exported by the :compat tag:

	 POLLNVAL
	 POLLIN
	 POLLOUT
	 POLLERR
	 POLLHUP
	 POLLPRI
	 POLLRDNORM
	 POLLWRNORM
	 POLLRDBAND
	 POLLWRBAND

SEE ALSO

       "IO::Poll" "IO::Select" "IO::Ppoll" epoll(4) epoll_create(2) epoll_ctl(2) epoll_wait(2) epoll_pwait(2)

AUTHOR

       Bruce J Keeler, <bruce@gridpoint.com>

CREDITS

       The "IO::Poll" compatibility code borrows heavily from the "IO::Poll" code itself, which was written by Graham Barr.

COPYRIGHT AND LICENSE

       Copyright (C) 2004 by Bruce J. Keeler Portions Copyright (C) 1997-8 Graham Barr <gbarr@pobox.com>

       This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

perl v5.14.2							    2012-01-13							    IO::Epoll(3pm)