summaryrefslogtreecommitdiff
path: root/ext/socket/socket.c
diff options
context:
space:
mode:
authordrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-08-15 23:08:39 +0000
committerdrbrain <drbrain@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2011-08-15 23:08:39 +0000
commit12979424515344460afb12002ce07b670bf7cd6f (patch)
tree2d85f664a0fb708e459a30c56738487948ced8f9 /ext/socket/socket.c
parent39e112f89a4e7471bb95ec516b05c75ac6df5aa9 (diff)
* ext/socket: Make Socket documentation appear. Add documentation for
Socket, TCPServer, SOCKSSocket. Patch by Sylvain Daubert. [Ruby 1.9 - Feature #5182] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32977 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'ext/socket/socket.c')
-rw-r--r--ext/socket/socket.c142
1 files changed, 105 insertions, 37 deletions
diff --git a/ext/socket/socket.c b/ext/socket/socket.c
index c2743cd..4613892 100644
--- a/ext/socket/socket.c
+++ b/ext/socket/socket.c
@@ -1792,48 +1792,116 @@ socket_s_ip_address_list(VALUE self)
#define socket_s_ip_address_list rb_f_notimplement
#endif
-/*
- * Document-class: ::Socket < BasicSocket
- *
- * Class +Socket+ provides access to the underlying operating system
- * socket implementations. It can be used to provide more operating system
- * specific functionality than the protocol-specific socket classes.
- *
- * The constants defined under Socket::Constants are also defined under Socket.
- * For example, Socket::AF_INET is usable as well as Socket::Constants::AF_INET.
- * See Socket::Constants for the list of constants.
- *
- * === Exception Handling
- * Ruby's implementation of +Socket+ causes an exception to be raised
- * based on the error generated by the system dependent implementation.
- * This is why the methods are documented in a way that isolate
- * Unix-based system exceptions from Windows based exceptions. If more
- * information on particular exception is needed please refer to the
- * Unix manual pages or the Windows WinSock reference.
- *
- * === Convenient methods
- *
- * Although the general way to create socket is Socket.new,
- * there are several methods for socket creation for most cases.
- *
- * * TCP client socket: Socket.tcp, TCPSocket.open
- * * TCP server socket: Socket.tcp_server_loop, TCPServer.open
- * * UNIX client socket: Socket.unix, UNIXSocket.open
- * * UNIX server socket: Socket.unix_server_loop, UNIXServer.open
- *
- * === Documentation by
- * * Zach Dennis
- * * Sam Roberts
- * * <em>Programming Ruby</em> from The Pragmatic Bookshelf.
- *
- * Much material in this documentation is taken with permission from
- * <em>Programming Ruby</em> from The Pragmatic Bookshelf.
- */
void
Init_socket()
{
rsock_init_basicsocket();
+ /*
+ * Document-class: Socket < BasicSocket
+ *
+ * Class +Socket+ provides access to the underlying operating system
+ * socket implementations. It can be used to provide more operating system
+ * specific functionality than the protocol-specific socket classes.
+ *
+ * The constants defined under Socket::Constants are also defined under
+ * Socket. For example, Socket::AF_INET is usable as well as
+ * Socket::Constants::AF_INET. See Socket::Constants for the list of
+ * constants.
+ *
+ * === What's a socket?
+ *
+ * Sockets are endpoints of a bidirectionnal communication channel.
+ * Sockets can communicate within a process, between processes on the same
+ * machine or between different machines. There are many types of socket:
+ * TCPSocket, UDPSocket or UNIXSocket for example.
+ *
+ * Sockets have their own vocabulary:
+ * domain::
+ * The family of protocols: Socket::PF_INET, Socket::PF_INET6,
+ * Socket::PF_UNIX, etc.
+ * type::
+ * The type of communications between the two endpoints, typically
+ * Socket::SOCK_STREAM or Socket::SOCK_DGRAM.
+ * protocol::
+ * Typically zero. This may be used to identify a variant of a
+ * protocol.
+ * hostname::
+ * The identifier of a network interface:
+ * * a string (hostname, IPv4 or IPv6 adress or <tt><broadcast></tt>
+ * which specifies a broadcast address)
+ * * a zero-length string which specifies INADDR_ANY
+ * * an integer (interpreted as binary address in host byte order).
+ *
+ * === Quick start
+ *
+ * Some classes such as TCPSocket, UDPSocket or UNIXSocket ease use of
+ * sockets of these types compared to C programming.
+ *
+ * # Creating a TCP socket in a C-like manner
+ * s = Socket.new Socket::INET, Socket::SOCK_STREAM
+ * s.connect Socket.pack_sockaddr_in(80, 'example.com')
+ *
+ * # Using TCPSocket
+ * s = TCPSocket.new 'example.com', 80
+ *
+ * A simple server would look like:
+ *
+ * require 'socket'
+ *
+ * server = TCPServer.new 2000 # Server bound to port 2000
+ *
+ * loop do
+ * client = server.accept # Wait for a client to connect
+ * client.puts "Hello !"
+ * client.puts "Time is #{Time.now}"
+ * client.close
+ * end
+ *
+ * A simple client may look like:
+ *
+ * require 'socket'
+ *
+ * s = TCPSocket.new 'localhost', 2000
+ *
+ * while line = s.gets # Read lines from socket
+ * puts line # and print them
+ * end
+ *
+ * s.close # close socket when done
+ *
+ * === Exception Handling
+ *
+ * Ruby's Socket implementation raises exceptions based on the error
+ * generated by the system dependent implementation. This is why the
+ * methods are documented in a way that isolate Unix-based system
+ * exceptions from Windows based exceptions. If more information on
+ * particular exception is needed please refer to the Unix manual pages or
+ * the Windows WinSock reference.
+ *
+ * === Convenient methods
+ *
+ * Although the general way to create socket is Socket.new,
+ * there are several methods for socket creation for most cases.
+ *
+ * TCP client socket::
+ * Socket.tcp, TCPSocket.open
+ * TCP server socket::
+ * Socket.tcp_server_loop, TCPServer.open
+ * UNIX client socket::
+ * Socket.unix, UNIXSocket.open
+ * UNIX server socket::
+ * Socket.unix_server_loop, UNIXServer.open
+ *
+ * === Documentation by
+ *
+ * * Zach Dennis
+ * * Sam Roberts
+ * * <em>Programming Ruby</em> from The Pragmatic Bookshelf.
+ *
+ * Much material in this documentation is taken with permission from
+ * <em>Programming Ruby</em> from The Pragmatic Bookshelf.
+ */
rb_cSocket = rb_define_class("Socket", rb_cBasicSocket);
rsock_init_socket_init();