summaryrefslogtreecommitdiff
path: root/ext/socket
diff options
context:
space:
mode:
Diffstat (limited to 'ext/socket')
-rw-r--r--ext/socket/ancdata.c4
-rw-r--r--ext/socket/basicsocket.c29
-rw-r--r--ext/socket/ipsocket.c2
-rw-r--r--ext/socket/lib/socket.rb2
-rw-r--r--ext/socket/option.c8
-rw-r--r--ext/socket/socket.c43
-rw-r--r--ext/socket/tcpserver.c2
-rw-r--r--ext/socket/tcpsocket.c2
-rw-r--r--ext/socket/udpsocket.c2
-rw-r--r--ext/socket/unixserver.c2
-rw-r--r--ext/socket/unixsocket.c2
11 files changed, 62 insertions, 36 deletions
diff --git a/ext/socket/ancdata.c b/ext/socket/ancdata.c
index 11409aa834..0d3846056a 100644
--- a/ext/socket/ancdata.c
+++ b/ext/socket/ancdata.c
@@ -1769,6 +1769,10 @@ rsock_bsock_recvmsg_nonblock(int argc, VALUE *argv, VALUE sock)
/*
* Document-class: ::Socket::AncillaryData
+ *
+ * Socket::AncillaryData represents the ancillary data (control information)
+ * used by sendmsg and recvmsg system call.
+ * It contains socket family, cmsg level, cmsg type and cmsg data.
*/
void
Init_ancdata(void)
diff --git a/ext/socket/basicsocket.c b/ext/socket/basicsocket.c
index 5e28bcf956..60db31074c 100644
--- a/ext/socket/basicsocket.c
+++ b/ext/socket/basicsocket.c
@@ -89,7 +89,7 @@ bsock_shutdown(int argc, VALUE *argv, VALUE sock)
* call-seq:
* basicsocket.close_read => nil
*
- * Disallows further read.
+ * Disallows further read using shutdown system call.
*
* s1, s2 = UNIXSocket.pair
* s1.close_read
@@ -117,7 +117,7 @@ bsock_close_read(VALUE sock)
* call-seq:
* basicsocket.close_write => nil
*
- * Disallows further write.
+ * Disallows further write using shutdown system call.
*
* UNIXSocket.pair {|s1, s2|
* s1.print "ping"
@@ -198,7 +198,8 @@ bsock_close_write(VALUE sock)
* };
*
* In this case #setsockopt could be called like this:
- * optval = IPAddr.new("224.0.0.251").hton + IPAddr.new(Socket::INADDR_ANY, Socket::AF_INET).hton
+ * optval = IPAddr.new("224.0.0.251").hton +
+ * IPAddr.new(Socket::INADDR_ANY, Socket::AF_INET).hton
* sock.setsockopt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, optval)
*
*/
@@ -263,7 +264,7 @@ bsock_setsockopt(int argc, VALUE *argv, VALUE sock)
*
* Gets a socket option. These are protocol and system specific, see your
* local system documentation for details. The option is returned as
- * a Socket::Option.
+ * a Socket::Option object.
*
* === Parameters
* * +level+ is an integer, usually one of the SOL_ constants such as
@@ -349,7 +350,8 @@ bsock_getsockopt(VALUE sock, VALUE lev, VALUE optname)
* p serv.getsockname #=> "\x02\x00;\x10\x7F\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00"
* }
*
- * If Addrinfo object is preferred, use BasicSocket#local_address.
+ * If Addrinfo object is preferred over the binary string,
+ * use BasicSocket#local_address.
*/
static VALUE
bsock_getsockname(VALUE sock)
@@ -376,7 +378,8 @@ bsock_getsockname(VALUE sock)
* p s.getpeername #=> "\x02\x00\x82u\x7F\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x00"
* }
*
- * If Addrinfo object is preferred, use BasicSocket#remote_address.
+ * If Addrinfo object is preferred over the binary string,
+ * use BasicSocket#remote_address.
*
*/
static VALUE
@@ -458,6 +461,10 @@ bsock_getpeereid(VALUE self)
*
* Note that addrinfo.protocol is filled by 0.
*
+ * TCPSocket.open("www.ruby-lang.org", 80) {|s|
+ * p s.local_address #=> #<Addrinfo: 192.168.0.129:36873 TCP>
+ * }
+ *
* TCPServer.open("127.0.0.1", 1512) {|serv|
* p serv.local_address #=> #<Addrinfo: 127.0.0.1:1512 TCP>
* }
@@ -484,6 +491,10 @@ bsock_local_address(VALUE sock)
*
* Note that addrinfo.protocol is filled by 0.
*
+ * TCPSocket.open("www.ruby-lang.org", 80) {|s|
+ * p s.remote_address #=> #<Addrinfo: 221.186.184.68:80 TCP>
+ * }
+ *
* TCPServer.open("127.0.0.1", 1728) {|serv|
* c = TCPSocket.new("127.0.0.1", 1728)
* s = serv.accept
@@ -506,7 +517,7 @@ bsock_remote_address(VALUE sock)
/*
* call-seq:
- * basicsocket.send(mesg, flags [, sockaddr_to]) => numbytes_sent
+ * basicsocket.send(mesg, flags [, dest_sockaddr]) => numbytes_sent
*
* send _mesg_ via _basicsocket_.
*
@@ -514,7 +525,7 @@ bsock_remote_address(VALUE sock)
*
* _flags_ should be a bitwise OR of Socket::MSG_* constants.
*
- * _sockaddr_to_ should be a packed sockaddr string or an addrinfo.
+ * _dest_sockaddr_ should be a packed sockaddr string or an addrinfo.
*
* TCPSocket.open("localhost", 80) {|s|
* s.send "GET / HTTP/1.0\r\n\r\n", 0
@@ -722,7 +733,7 @@ bsock_do_not_rev_lookup_set(VALUE self, VALUE val)
}
/*
- * BasicSocket class
+ * BasicSocket is the super class for the all socket classes.
*/
void
Init_basicsocket(void)
diff --git a/ext/socket/ipsocket.c b/ext/socket/ipsocket.c
index ad1ac231c3..c1f329b52e 100644
--- a/ext/socket/ipsocket.c
+++ b/ext/socket/ipsocket.c
@@ -286,7 +286,7 @@ ip_s_getaddress(VALUE obj, VALUE host)
/*
* Document-class: ::IPSocket < BasicSocket
*
- * IPSocket class
+ * IPSocket is the super class of TCPSocket and UDPSocket.
*/
void
Init_ipsocket(void)
diff --git a/ext/socket/lib/socket.rb b/ext/socket/lib/socket.rb
index 5b7438182d..0f26c3efc5 100644
--- a/ext/socket/lib/socket.rb
+++ b/ext/socket/lib/socket.rb
@@ -683,7 +683,7 @@ class Socket < BasicSocket
end
end
- # creates UNIX server sockets on _path_
+ # creates a UNIX server socket on _path_
#
# If no block given, it returns a listening socket.
#
diff --git a/ext/socket/option.c b/ext/socket/option.c
index 89265b78ad..4be651f7c6 100644
--- a/ext/socket/option.c
+++ b/ext/socket/option.c
@@ -148,7 +148,7 @@ sockopt_data(VALUE self)
*
* Creates a new Socket::Option object which contains an int as data.
*
- * The size and endian is dependent on the host.
+ * The size and endian is dependent on the platform.
*
* p Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1)
* #=> #<Socket::Option: INET SOCKET KEEPALIVE 1>
@@ -169,7 +169,7 @@ sockopt_s_int(VALUE klass, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE vi
*
* Returns the data in _sockopt_ as an int.
*
- * The size and endian is dependent on the host.
+ * The size and endian is dependent on the platform.
*
* sockopt = Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1)
* p sockopt.int => 1
@@ -660,6 +660,10 @@ sockopt_unpack(VALUE self, VALUE template)
/*
* Document-class: ::Socket::Option
+ *
+ * Socket::Option represents a socket option used by getsockopt and setsockopt
+ * system call.
+ * It contains socket family, protocol level, option name and option value.
*/
void
Init_sockopt(void)
diff --git a/ext/socket/socket.c b/ext/socket/socket.c
index 1b026a6741..66dd5d9c20 100644
--- a/ext/socket/socket.c
+++ b/ext/socket/socket.c
@@ -134,13 +134,13 @@ rsock_sock_s_socketpair(int argc, VALUE *argv, VALUE klass)
/*
* call-seq:
- * socket.connect(server_sockaddr) => 0
+ * socket.connect(remote_sockaddr) => 0
*
- * Requests a connection to be made on the given +server_sockaddr+. Returns 0 if
+ * Requests a connection to be made on the given +remote_sockaddr+. Returns 0 if
* successful, otherwise an exception is raised.
*
* === Parameter
- * * +server_sockaddr+ - the +struct+ sockaddr contained in a string
+ * * +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object
*
* === Example:
* # Pull down Google's web page
@@ -263,14 +263,14 @@ sock_connect(VALUE sock, VALUE addr)
/*
* call-seq:
- * socket.connect_nonblock(server_sockaddr) => 0
+ * socket.connect_nonblock(remote_sockaddr) => 0
*
- * Requests a connection to be made on the given +server_sockaddr+ after
+ * Requests a connection to be made on the given +remote_sockaddr+ after
* O_NONBLOCK is set for the underlying file descriptor.
* Returns 0 if successful, otherwise an exception is raised.
*
* === Parameter
- * * +server_sockaddr+ - the +struct+ sockaddr contained in a string
+ * * +remote_sockaddr+ - the +struct+ sockaddr contained in a string or Addrinfo object
*
* === Example:
* # Pull down Google's web page
@@ -325,15 +325,22 @@ sock_connect_nonblock(VALUE sock, VALUE addr)
/*
* call-seq:
- * socket.bind(server_sockaddr) => 0
+ * socket.bind(local_sockaddr) => 0
*
- * Binds to the given +struct+ sockaddr.
+ * Binds to the given local address.
*
* === Parameter
- * * +server_sockaddr+ - the +struct+ sockaddr contained in a string
+ * * +local_sockaddr+ - the +struct+ sockaddr contained in a string or an Addrinfo object
*
* === Example
* require 'socket'
+ *
+ * # use Addrinfo
+ * socket = Socket.new(:INET, :STREAM, 0)
+ * socket.bind(Addrinfo.tcp("127.0.0.1", 2222))
+ * p socket.local_address #=> #<Addrinfo: 127.0.0.1:2222 TCP>
+ *
+ * # use struct sockaddr
* include Socket::Constants
* socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
* sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
@@ -507,11 +514,11 @@ rsock_sock_listen(VALUE sock, VALUE log)
*
* Receives up to _maxlen_ bytes from +socket+. _flags_ is zero or more
* of the +MSG_+ options. The first element of the results, _mesg_, is the data
- * received. The second element, _sender_addrinfo_, contains protocol-specific information
- * on the sender.
+ * received. The second element, _sender_addrinfo_, contains protocol-specific
+ * address information of the sender.
*
* === Parameters
- * * +maxlen+ - the number of bytes to receive from the socket
+ * * +maxlen+ - the maximum number of bytes to receive from the socket
* * +flags+ - zero or more of the +MSG_+ options
*
* === Example
@@ -620,15 +627,15 @@ sock_recvfrom(int argc, VALUE *argv, VALUE sock)
* O_NONBLOCK is set for the underlying file descriptor.
* _flags_ is zero or more of the +MSG_+ options.
* The first element of the results, _mesg_, is the data received.
- * The second element, _sender_addrinfo_, contains protocol-specific information
- * on the sender.
+ * The second element, _sender_addrinfo_, contains protocol-specific address
+ * information of the sender.
*
* When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns
* an empty string as data.
* The meaning depends on the socket: EOF on TCP, empty packet on UDP, etc.
*
* === Parameters
- * * +maxlen+ - the number of bytes to receive from the socket
+ * * +maxlen+ - the maximum number of bytes to receive from the socket
* * +flags+ - zero or more of the +MSG_+ options
*
* === Example
@@ -689,7 +696,7 @@ sock_recvfrom_nonblock(int argc, VALUE *argv, VALUE sock)
* serv = Socket.new(:INET, :STREAM, 0)
* serv.listen(5)
* c = Socket.new(:INET, :STREAM, 0)
- * c.connect(serv.local_address)
+ * c.connect(serv.connect_address)
* p serv.accept #=> [#<Socket:fd 6>, #<Addrinfo: 127.0.0.1:48555 TCP>]
*
*/
@@ -830,10 +837,10 @@ sock_sysaccept(VALUE sock)
*
* Returns the hostname.
*
- * Note that it is not guaranteed to be able to convert to IP address using gethostbyname, getaddrinfo, etc.
- *
* p Socket.gethostname #=> "hal"
*
+ * Note that it is not guaranteed to be able to convert to IP address using gethostbyname, getaddrinfo, etc.
+ * If you need local IP address, use Socket.ip_address_list.
*/
static VALUE
sock_gethostname(VALUE obj)
diff --git a/ext/socket/tcpserver.c b/ext/socket/tcpserver.c
index 229c2b1607..bd5701f6d2 100644
--- a/ext/socket/tcpserver.c
+++ b/ext/socket/tcpserver.c
@@ -131,7 +131,7 @@ tcp_sysaccept(VALUE sock)
/*
* Document-class: ::TCPServer < TCPSocket
*
- * TCPServer class
+ * TCPServer represents a TCP/IP server socket.
*/
void
Init_tcpserver(void)
diff --git a/ext/socket/tcpsocket.c b/ext/socket/tcpsocket.c
index d7164ad861..fb51a01c97 100644
--- a/ext/socket/tcpsocket.c
+++ b/ext/socket/tcpsocket.c
@@ -58,7 +58,7 @@ tcp_s_gethostbyname(VALUE obj, VALUE host)
/*
* Document-class: ::TCPSocket < IPSocket
*
- * TCPSocket class
+ * TCPSocket represents a TCP/IP client socket.
*/
void
Init_tcpsocket(void)
diff --git a/ext/socket/udpsocket.c b/ext/socket/udpsocket.c
index 3a42e0e25b..12b910d777 100644
--- a/ext/socket/udpsocket.c
+++ b/ext/socket/udpsocket.c
@@ -249,7 +249,7 @@ udp_recvfrom_nonblock(int argc, VALUE *argv, VALUE sock)
/*
* Document-class: ::UDPSocket < IPSocket
*
- * UDPSocket class
+ * UDPSocket represents a UDP/IP socket.
*/
void
Init_udpsocket(void)
diff --git a/ext/socket/unixserver.c b/ext/socket/unixserver.c
index e29e9cb87b..86447e8aba 100644
--- a/ext/socket/unixserver.c
+++ b/ext/socket/unixserver.c
@@ -138,7 +138,7 @@ unix_sysaccept(VALUE sock)
/*
* Document-class: ::UNIXServer < UNIXSocket
*
- * UNIXServer class
+ * UNIXServer represents a UNIX domain stream server socket.
*/
void
Init_unixserver(void)
diff --git a/ext/socket/unixsocket.c b/ext/socket/unixsocket.c
index 89beb666ec..8eca0d56c8 100644
--- a/ext/socket/unixsocket.c
+++ b/ext/socket/unixsocket.c
@@ -487,7 +487,7 @@ unix_s_socketpair(int argc, VALUE *argv, VALUE klass)
/*
* Document-class: ::UNIXSocket < BasicSocket
*
- * UNIXSocket class
+ * UNIXSocket represents a UNIX domain stream client socket.
*/
void
Init_unixsocket(void)
generated by cgit v1.2.3 (git 2.25.1) at 2024-04-26 16:02:04 +0000