(892c46283a5ea4179500d951c9d4866c0051f27b)

Public APIs to provide rb_fd_select(). More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/pure.h"
#include "ruby/internal/dllexport.h"

Include dependency graph for largesize.h:

Data Structures
struct	rb_fdset_t
	The data structure which wraps the fd_set bitmap used by select(2). More...

Functions
void	rb_fd_init (rb_fdset_t *f)
	(Re-)initialises a fdset. More...

void	rb_fd_term (rb_fdset_t *f)
	Destroys the rb_fdset_t, releasing any memory and resources it used. More...

void	rb_fd_zero (rb_fdset_t *f)
	Wipes out the current set of FDs. More...

void	rb_fd_set (int fd, rb_fdset_t *f)
	Sets an fd to a fdset. More...

void	rb_fd_clr (int fd, rb_fdset_t *f)
	Releases a specific FD from the given fdset. More...

int	rb_fd_isset (int fd, const rb_fdset_t *f)
	Queries if the given FD is in the given set. More...

void	rb_fd_copy (rb_fdset_t dst, const fd_set src, int max)
	Destructively overwrites an fdset with another. More...

void	rb_fd_dup (rb_fdset_t dst, const rb_fdset_t src)
	Identical to rb_fd_copy(), except it copies unlimited number of file descriptors. More...

int	rb_fd_select (int nfds, rb_fdset_t rfds, rb_fdset_t wfds, rb_fdset_t efds, struct timeval timeout)
	Waits for multiple file descriptors at once. More...

static fd_set *	rb_fd_ptr (const rb_fdset_t *f)
	Raw pointer to `fd_set`. More...

static int	rb_fd_max (const rb_fdset_t *f)
	It seems this function has no use. More...

Detailed Description

Public APIs to provide rb_fd_select().

Author: Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright: This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

Warning: Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.

Note: To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Several Unix platforms support file descriptors bigger than FD_SETSIZE in select(2) system call.

Linux 2.2.12 (?)
NetBSD 1.2 (src/sys/kern/sys_generic.c:1.25) select(2) documents how to allocate fd_set dynamically. http://netbsd.gw.com/cgi-bin/man-cgi?select++NetBSD-4.0
FreeBSD 2.2 (src/sys/kern/sys_generic.c:1.19)
OpenBSD 2.0 (src/sys/kern/sys_generic.c:1.4) select(2) documents how to allocate fd_set dynamically. http://www.openbsd.org/cgi-bin/man.cgi?query=select&manpath=OpenBSD+4.4
Solaris 8 has select_large_fdset
Mac OS X 10.7 (Lion) select(2) returns EINVAL if nfds is greater than FD_SET_SIZE and _DARWIN_UNLIMITED_SELECT (or _DARWIN_C_SOURCE) isn't defined. http://developer.apple.com/library/mac/#releasenotes/Darwin/SymbolVariantsRelNotes/_index.html

When fd_set is not big enough to hold big file descriptors, it should be allocated dynamically. Note that this assumes fd_set is structured as bitmap.

rb_fd_init allocates the memory. rb_fd_term frees the memory. rb_fd_set may re-allocate bitmap.

So rb_fd_set doesn't reject file descriptors bigger than FD_SETSIZE.

Definition in file largesize.h.

Function Documentation

◆ rb_fd_clr()

void rb_fd_clr	(	int	fd,
		rb_fdset_t *	f
	)

Releases a specific FD from the given fdset.

Parameters

[in]	fd	Target FD.
[out]	f	The fdset that holds `fd`.

Postcondition: f doesn't hold n.

◆ rb_fd_copy()

void rb_fd_copy	(	rb_fdset_t *	dst,
		const fd_set *	src,
		int	max
	)

Destructively overwrites an fdset with another.

Parameters

[out]	dst	Target fdset.
[in]	src	Source fdset.
[in]	max	Maximum number of file descriptors to copy.

Postcondition: dst is a copy of src.

◆ rb_fd_dup()

void rb_fd_dup	(	rb_fdset_t *	dst,
		const rb_fdset_t *	src
	)

Identical to rb_fd_copy(), except it copies unlimited number of file descriptors.

Parameters

[out]	dst	Target fdset.
[in]	src	Source fdset.

Postcondition: dst is a copy of src.

◆ rb_fd_init()

void rb_fd_init ( rb_fdset_t * f )

(Re-)initialises a fdset.

One must be initialised before other rb_fd_* operations. Analogous to calling malloc(3) to allocate an fd_set.

Parameters

[out] f An fdset to squash.

Postcondition: f holds no file descriptors.

◆ rb_fd_isset()

int rb_fd_isset	(	int	fd,
		const rb_fdset_t *	f
	)

Queries if the given FD is in the given set.

Parameters

[in]	fd	Target FD.
[in]	f	The fdset to scan.

Return values

1	Yes there is.
0	No there isn't.

See also: http://www.freebsd.org/cgi/query-pr.cgi?pr=91421

◆ rb_fd_max()

static int rb_fd_max ( const rb_fdset_t * f )

inlinestatic

It seems this function has no use.

Maybe just remove?

Parameters

[in] f A set.

Returns: Number of file descriptors stored.

Definition at line 209 of file largesize.h.

◆ rb_fd_ptr()

static fd_set* rb_fd_ptr ( const rb_fdset_t * f )

inlinestatic

Raw pointer to fd_set.

Parameters

[in] f Target fdset.

Return values

NULL	`f` is already terminated by rb_fd_term().
otherwise	Underlying fd_set.

Definition at line 195 of file largesize.h.

◆ rb_fd_select()

int rb_fd_select	(	int	nfds,
		rb_fdset_t *	rfds,
		rb_fdset_t *	wfds,
		rb_fdset_t *	efds,
		struct timeval *	timeout
	)

Waits for multiple file descriptors at once.

Parameters

[in]	nfds	Max FD in everything passed, plus one.
[in,out]	rfds	Set of FDs to wait for reads.
[in,out]	wfds	Set of FDs to wait for writes.
[in,out]	efds	Set of FDs to wait for OOBs.
[in,out]	timeout	Max blocking duration.

Return values

-1	Failed, errno set.
0	Timeout exceeded.
otherwise	Total number of file descriptors returned.

Postcondition: rfds contains readable FDs.; wfds contains writable FDs.; efds contains exceptional FDs.; timeout is the time left.

Note: All pointers are allowed to be null pointers.

◆ rb_fd_set()

void rb_fd_set	(	int	fd,
		rb_fdset_t *	f
	)

Sets an fd to a fdset.

Parameters

[in]	fd	A file descriptor.
[out]	f	Target fdset.

Postcondition: f holds fd.

◆ rb_fd_term()

void rb_fd_term ( rb_fdset_t * f )

Destroys the rb_fdset_t, releasing any memory and resources it used.

It must be reinitialised using rb_fd_init() before future use. Analogous to calling free(3) to release memory for an fd_set.

Parameters

[out] f An fdset to squash.

Postcondition: f holds no file descriptors.

◆ rb_fd_zero()

void rb_fd_zero ( rb_fdset_t * f )

Wipes out the current set of FDs.

Parameters

[out] f The fdset to clear.

Postcondition: f has no FDs.

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Functions

Detailed Description

Function Documentation

◆ rb_fd_clr()

◆ rb_fd_copy()

◆ rb_fd_dup()

◆ rb_fd_init()

◆ rb_fd_isset()

◆ rb_fd_max()

◆ rb_fd_ptr()

◆ rb_fd_select()

◆ rb_fd_set()

◆ rb_fd_term()

◆ rb_fd_zero()