Module Kgio
In: lib/kgio.rb  (CVS)
lib/kgio.rb  (CVS)
ext/kgio/accept.c  (CVS)
ext/kgio/autopush.c  (CVS)
ext/kgio/connect.c  (CVS)
ext/kgio/poll.c  (CVS)
ext/kgio/read_write.c  (CVS)
ext/kgio/wait.c  (CVS)
ext/kgio/tryopen.c  (CVS)

call-seq:

     Kgio::File.tryopen(filename, [, mode [, perm]])      -> Kgio::File or Symbol

Returns a Kgio::File object on a successful open. filename is a path to any file on the filesystem. If specified, mode is a bitmask of flags (see IO.sysopen) and perm should be an octal number.

This does not raise errors for most failures, but installs returns a Ruby symbol for the constant in the Errno::* namespace.

Common error symbols are:

  • :ENOENT
  • :EACCES

See your open(2) manpage for more information on open(2) errors.

Methods

Classes and Modules

Module Kgio::DefaultWaiters
Module Kgio::PipeMethods
Module Kgio::SocketMethods
Class Kgio::File
Class Kgio::Pipe
Class Kgio::Socket
Class Kgio::TCPServer
Class Kgio::TCPSocket
Class Kgio::UNIXServer
Class Kgio::UNIXSocket

Constants

LOCALHOST = '127.0.0.1'   The IPv4 address of UNIX domain sockets, useful for creating Rack (and CGI) servers that also serve HTTP traffic over UNIX domain sockets.
WaitReadable = :wait_readable   Kgio::PipeMethods#kgio_tryread and Kgio::SocketMethods#kgio_tryread will return :wait_readable when waiting for a read is required.
WaitWritable = :wait_writable   PipeMethods#kgio_trywrite and SocketMethods#kgio_trywrite will return :wait_writable when waiting for a read is required.
LOCALHOST = '127.0.0.1'   The IPv4 address of UNIX domain sockets, useful for creating Rack (and CGI) servers that also serve HTTP traffic over UNIX domain sockets.
WaitReadable = :wait_readable   Kgio::PipeMethods#kgio_tryread and Kgio::SocketMethods#kgio_tryread will return :wait_readable when waiting for a read is required.
WaitWritable = :wait_writable   PipeMethods#kgio_trywrite and SocketMethods#kgio_trywrite will return :wait_writable when waiting for a read is required.
SOCK_NONBLOCK = INT2NUM(SOCK_NONBLOCK)   Maps to the SOCK_NONBLOCK constant in Linux for setting the non-blocking flag on newly accepted sockets. This is usually unnecessary as sockets are made non-blocking whenever non-blocking methods are used.
SOCK_CLOEXEC = INT2NUM(SOCK_CLOEXEC)   Maps to the SOCK_CLOEXEC constant in Linux for setting the close-on-exec flag on newly accepted descriptors. This is enabled by default, and there is usually no reason to disable close-on-exec for accepted sockets.

Public Class methods

Returns the default class for newly accepted sockets when kgio_accept or kgio_tryaccept are not passed arguments

Sets the default class for newly accepted sockets. This is legacy behavior, kgio_accept and kgio_tryaccept now take optional class arguments to override this value.

     Kgio.accept_cloexec = true
     Kgio.accept_cloexec = false

Sets whether or not Kgio::Socket objects created by TCPServer#kgio_accept, TCPServer#kgio_tryaccept, UNIXServer#kgio_accept, and UNIXServer#kgio_tryaccept default to being created with the FD_CLOEXEC file descriptor flag.

This is on by default, as there is little reason to deal to enable it for client sockets on a socket server.

Deprecated, use the per-socket flags for kgio_*accept instead.

     Kgio.accept_cloexec? -> true or false

Returns true if newly accepted Kgio::Sockets are created with the FD_CLOEXEC file descriptor flag, false if not.

Deprecated, use the per-socket flags for kgio_*accept instead.

     Kgio.accept_nonblock = true
     Kgio.accept_nonblock = false

Sets whether or not Kgio::Socket objects created by TCPServer#kgio_accept, TCPServer#kgio_tryaccept, UNIXServer#kgio_accept, and UNIXServer#kgio_tryaccept are created with the O_NONBLOCK file status flag.

This defaults to false for GNU/Linux where MSG_DONTWAIT is available (and on newer GNU/Linux, accept4() may also set the non-blocking flag. This defaults to true on non-GNU/Linux systems.

This is always true on Ruby implementations using user-space threads.

Deprecated, use the per-socket flags for kgio_*accept instead.

     Kgio.accept_nonblock? -> true or false

Returns true if newly accepted Kgio::Sockets are created with the O_NONBLOCK file status flag, false if not.

Deprecated, use the per-socket flags for kgio_*accept instead.

Enables or disables autopush for sockets created with kgio_accept and kgio_tryaccept methods. Autopush relies on TCP_CORK/TCP_NOPUSH being enabled on the listen socket.

Only available on systems with TCP_CORK (Linux) or TCP_NOPUSH (FreeBSD, and maybe other *BSDs).

Returns whether or not autopush is enabled.

Only available on systems with TCP_CORK (Linux) or TCP_NOPUSH (FreeBSD, and maybe other *BSDs).

     Kgio.poll({ $stdin => :wait_readable }, 100)  -> hash or nil
     Kgio.poll({ $stdin => Kgio::POLLIN }, 100)  -> hash or nil

Accepts an input hash with IO objects to wait for as the key and the events to wait for as its value. The events may either be +:wait_readable+ or +:wait_writable+ symbols or a Fixnum mask of Kgio::POLL* constants:

     Kgio::POLLIN      - there is data to read
     Kgio::POLLPRI     - there is urgent data to read
     Kgio::POLLOUT     - writing will not block
     Kgio::POLLRDHUP   - peer has shutdown writes (Linux 2.6.17+ only)

Timeout is specified in Integer milliseconds just like the underlying poll(2), not in seconds like IO.select. A nil timeout means to wait forever. It must be an Integer or nil.

Kgio.poll modifies and returns its input hash on success with the IO-like object as the key and an Integer mask of events as the hash value. It can return any of the events specified in the input above, along with the following events:

     Kgio::POLLERR     - error condition occurred on the descriptor
     Kgio::POLLHUP     - hang up
     Kgio::POLLNVAL    - invalid request (bad file descriptor)

This method is only available under Ruby 1.9 or any other implementations that uses native threads and rb_thread_blocking_region()

     Kgio.trypeek(socket, maxlen)           ->  buffer
     Kgio.trypeek(socket, maxlen, buffer)   ->  buffer

Like Kgio.tryread, except it uses MSG_PEEK so it does not drain the socket buffer. This can only be used on sockets and not pipe objects. Maybe used in place of SocketMethods#kgio_trypeek for non-Kgio objects

     Kgio.tryread(io, maxlen)           ->  buffer
     Kgio.tryread(io, maxlen, buffer)   ->  buffer

Returns nil on EOF. Returns :wait_readable if EAGAIN is encountered.

Maybe used in place of PipeMethods#kgio_tryread for non-Kgio objects

     Kgio.trywrite(io, str)    -> nil, String or :wait_writable

Returns nil if the write was completed in full.

Returns a String containing the unwritten portion if EAGAIN was encountered, but some portion was successfully written.

Returns :wait_writable if EAGAIN is encountered and nothing was written.

Maybe used in place of PipeMethods#kgio_trywrite for non-Kgio objects

[Validate]