[rds-commits] zab commits r85 - trunk/man
svn-commits@oss.oracle.com
svn-commits at oss.oracle.com
Tue May 30 18:25:12 CDT 2006
Author: zab
Date: 2006-05-30 18:25:11 -0500 (Tue, 30 May 2006)
New Revision: 85
Modified:
trunk/man/rds.7
Log:
Update the rds man page to reflect the current api.
Modified: trunk/man/rds.7
===================================================================
--- trunk/man/rds.7 2006-05-30 20:28:04 UTC (rev 84)
+++ trunk/man/rds.7 2006-05-30 23:25:11 UTC (rev 85)
@@ -1,22 +1,29 @@
.TH RDS 7 2006-01-16 "Linux Man Page" "Linux Programmer's Manual"
.SH NAME
-rds \- RDS protocol
+rds \- RDS socket API
.SH SYNOPSIS
.B #include <sys/socket.h>
.br
.B #include <netinet/in.h>
.br
-.B #include <netinet/rds.h>
+.B #define RDS_CANCEL_SENT_TO 1
+.br
+.B #define RDS_SNDBUF 2
.TP
-.B rds_socket = socket(PF_RDS, SOCK_DGRAM, 0);
+.B rds_socket = socket(pf_rds, SOCK_SEQPACKET, 0);
.br
.SH DESCRIPTION
This is an implementation of the RDS socket API. It provides reliable,
-in-order datagram delivery between sockets over a variety of transports. RDS
-guarantees that the data arrives in order and retransmits lost packets. RDS
-preserves message boundaries. Transports aim to protect message contents from
-transmission errors but can not guarantee complete data integrity.
+in-order datagram delivery between sockets over a variety of transports.
+.SH SOCKET CREATION
+RDS is still in development and as such does not have a reserved protocol
+family constant. Applications must read the string representation of
+the protocol family value from the
+.B pf_rds
+sysctl parameter file described below.
+
+.SH BINDING
A new RDS socket has no local address when it is first returned from
.BR socket (2).
It must be bound to a local address by calling
@@ -28,168 +35,215 @@
to a given address. If no port is specified in the binding address then an
unbound port is selected at random.
-The address part of the bound local address selects a local interface for the
-socket. The local interface determines what other addresses are reachable
-through the socket once it is bound to that device. An RDS socket bound to an
-ethernet device, for example, will only be able to reach addresses that are on
-same ethernet segment as the device that the socket is bound to.
+RDS has the notion of associating a socket to an underlying transport. The
+transport for a socket is decided based on the local address that is bound.
+From that point on the socket can only reach destinations which are available
+through the this transport.
-Messages may be received with
-.BR recvmsg (2)
-on an RDS socket once it is bound to a source address. The
-.B SO_RECVBUF
-socket option specifies the size in bytes of the receive queue.
-.B msg_name
-can be used to determine the address of the sending socket as documented in
-.BR recvmsg (2).
+.SH MESSAGE TRANSMISSION
Messages may be sent using
.BR sendmsg (2)
-once the RDS socket is bound.
+once the RDS socket is bound. Message length cannot exceed 4 gigabytes,
+that is an unsigned 32 bit integer.
+
+RDS does not support any out of band data of any kind.
+
A successful
.BR sendmsg(2)
call puts the message in the socket's transmit queue where it will remain until
-the destination acknowledges that the message has been queued for receipt.
-If the transmit buffer is full then
-.BR sendmsg (2)
-will wait for a previously sent message to be acknowleged and removed
-before proceeding. If MSG_DONTWAIT is specified in this case then -EAGAIN
-is returned instead of waiting. The
-.B SO_SNDBUF
-socket option specifies the size in bytes of the transmit queue. The
-destination is specified with
-.B msg_name.
-Messages are delivered in order with respect to a sending socket and a
-specific destination address. Messages to different destinations are not
-delivered in sending order. Message boundaries are preserved.
+either the destination acknowledges that the message is no longer in the
+network or the application removes the message from the send queue.
+Messages are removed from the send queue with the
+.B RDS_CANCEL_SENT_TO
+socket option described below.
-Sent messages do not stay in the transmit queue indefinitely. If the
-destination does not acknowledge their arrival promptly then they are removed
-from the socket's transmit queue and put in a seperate
-error queue on the socket. The
+A given RDS socket has limited transmit buffer space for each destination
+address. While a message is in the transmit queue its payload bytes
+are accounted for. If an attempt is made to send a message to a destination
+whose buffer does not have room for the new message then the sender will block
+or EAGAIN will be returned depending on
+.B MSG_DONTWAIT
+message flag. The
.B SO_SNDTIMEO
-socket option specifies the amount of time to wait before moving them
-to the error queue.
+socket option dictates how long the send will wait for buffer.
+
+The size of the send buffer for a given destination is governed by the
+.B RDS_SNDBUF
+socket option and sysctl parameters described below. The
+.B SO_SNDBUF
+socket option is ignored.
+
+.SH MESSAGE RECEIPT
+
+Messages may be received with
.BR recvmsg (2)
-with the
-.B MSG_ERRQUEUE
-flag set is used to remove these messages from the error queue.
-The presence of messages is in the error queue will cause
+on an RDS socket once it is bound to a source address. The
+.B MSG_DONTWAIT
+message flag determines if the receive will block waiting for message
+arrival and the
+.B SO_RCVTIMEO
+socket option dictates how long the receive will wait.
+The
+.B MSG_PEEK
+flag stops the message from being removed from the receive queue.
+
+The memory consumed by messages waiting for delivery does not limit the
+number of messages that can be queued for receive.
+Senders must be careful not to overwhelm the receiver by sizing their send
+buffers appropriately. The
+.B SO_RCVBUF
+socket option is ignored.
+
+.SH POLL
+
+RDS supports a limited
.BR poll (2)
-to return POLLERR on the socket and
+API.
+.B POLLIN
+is returned when there is a message waiting in the socket's receive queue.
+.B POLLOUT
+is
+.B always
+returned, it is up to the application to back off if poll is used to
+trigger sends.
+
+.SH RELIABILITY
+
+If
.BR sendmsg (2)
-will fail for any destination and set errno to
-.B ECOMM.
+succeeds then RDS guarantees that the message will be visible to
+.BR recvmsg (2)
+on a socket bound to the destination address as long as that destination
+socket remains open.
-RDS does not support any out of band data of any kind.
+If there is no socket bound on the destination than the message is silently
+dropped. If the sending RDS can't be sure that there is no socket bound then
+it will try to send the message indefinitely until it can be sure or the
+sent message is canceled.
+If a socket is closed then all pending sent messages on the socket are
+canceled and may or may not be seen by the receiver.
+
+The
+.B RDS_CANCEL_SENT_TO
+socket option can be used to cancel all pending messages to a given
+destination.
+
+If a receiving socket is closed with pending messages then the sender
+considers those messages as having left the network and will not retransmit
+them.
+
+A message will only be seen by
+.BR recvmsg (2)
+without
+.B
+MSG_PEEK
+once. Once the message has been delivered it is removed from the sending
+socket's transmit queue.
+
+All messages sent from the same socket to the same destination will be
+delivered in the order they're sent. Messages sent from different sockets,
+or to different destinations, may be delivered in any order.
+
.SH "ADDRESS FORMATS"
-RDS uses IP addresses to refer to local and remote devices.
-The address formats defined by
+RDS uses
+.B sockaddr_in
+as described in
.BR ip (7)
-apply to RDS. RDS only supports point-to-point
-communication -- broadcasting and multicasting are not
-supported.
+to describe addresses, including setting
+.B sin_family
+to
+.B AF_INET
+\&. RDS only supports unicast communication -- broadcast and
+multicast addresses are not supported.
.SH "SOCKET OPTIONS"
-To set or get a RDS socket option, call
+The following RDS specific socket options are available when the
+.B sol_rds
+sysctl parameter is read and used as the level with
.BR getsockopt (2)
-to read or
+or
.BR setsockopt (2)
-to write the option with the option level argument set to
-.BR SOL_RDS
-or
-.BR SOL_SOCKET.
-.SH ERRORS
.TP
-.B ESOCKNOTSUPPORT
-The
-.B type
-argument to
-.BR socket (2)
-was not
-.B SOCK_DGRAM.
+.B RDS_SNDBUF
+This determines the total number of bytes that may be queued in the
+transmit queue for a given destination. Changing this does not have
+an immediate effect on pending transmission, it is intended to be set
+early and infrequently. The default, minimum, and maximum values of
+this option are governed by the
+.B sndbuf_*
+sysctl parameters described below.
+
.TP
-.B ETIMEDOUT
-The destination did not acknowledge receipt of a message within the time
-specified by
-.B SO_SNDTIMEO.
+.B RDS_CANCEL_SENT_TO
+Setting this option is used to cancel messages sent to a specific destination.
+The destination address is specified by passing a sockaddr pointer and
+length as the optval and optlen arguments to
+.BR setsockopt (2)
+\&. Errors are only returned if the socket is not yet bound or if sockaddr
+is malformed. No error is returned if there are no messages queued for
+the given destination.
+.BR getsockopt (2)
+is not supported on this option and will return
+.B ENOPROTOOPT
+\&.
+
+.SH SYSCTL
+These parameteres may only be accessed through their files in
+.I /proc/sys/net/rds/
+\&. Access through
+.BR sysctl(2)
+is
+.B not
+supported.
+
.TP
-.B ECOMM
-A send that previously succeeded has since failed and is waiting in the
-error queue. This is returned by
-.BR sendmsg(2).
+.B pf_rds
+This file contains the string representation of the protocol family
+constant passed to
+.BR socket (2)
+to create a new RDS socket.
+
.TP
-.B EAFNOTSUPPORT
-A socket address was specified that did not have the
-.I sin_family
-member set to
-.B AF_INET.
+.B sol_rds
+This file contains the string representation of the socket level
+parameter that is passed to
+.BR getsockopt (2)
+and
+.BR setsockopt (2)
+to manipulate RDS socket options.
+
.TP
-.B ENETUNREACH
-The specified destination address could not be reached from the device
-that the socket was bound to with
-.BR bind (2).
+.B sndbuf_default_bytes
+This parameter determines the initial value of
+.B RDS_SNDBUF
+on a newly created socket. New values written to this file must not be
+less than
+.B sndbuf_min_bytes
+and not greater than
+.B sndbuf_max_bytes
.TP
-.B EADDRINUSE
-The address specified to
-.BR bind (2)
-is already bound to an existing RDS socket.
+.B sndbuf_max_bytes
+This parameter determines the maximum value of the
+.B sndbuf_default_bytes
+and
+.B sndbuf_min_bytes
+parameters. It can not be greater than the number of bytes represented
+in an unsigned 32bit integer (4 gigabytes).
.TP
-.B ENOTCONN
-A send or receive was attempted on a socket that was not bound.
-.PP
-Any errors defined for the generic socket API may also be returned by
-those operations when performed on RDS sockets. This includes errors like
-.B ENOMEM, EAGAIN, EINTR, EINVAL,
-etc.
+.B sndbuf_min_bytes
+This parameter determines the minimum value of the
+.B sndbuf_default_bytes
+and
+.B sndbuf_max_bytes
+parameters. It can not be less than 0.
-.SH "TO BE DOCUMENTED"
-
-.TP 3
-\(bu
-sysctl section
-.TP 3
-\(bu
-socket options
-.TP 3
-\(bu
-SIOCGIFCONF
-.TP 3
-\(bu
-details of reliability guarantee
-.TP 3
-\(bu
-maximum messages sizes.. sockopt to discover?
-.TP 3
-\(bu
-mention buf socket options being in payload bytes, mention sysctls
-.TP 3
-\(bu
-socket option to stop payload checksuming?
-.TP 3
-\(bu
-msg flags (MSG_PEEK, say)
-.TP 3
-\(bu
-rx DONTWAIT/EAGAIN
-.TP 3
-\(bu
-is SOCK_DGRAM ok?
-.TP 3
-\(bu
-having to drain send queues before resending after clearing errors?
-.TP 3
-\(bu
-failover
-.TP 3
-\(bu
-receiver back pressure?
-
.SH "SEE ALSO"
.BR socket (2),
.BR bind (2),
.BR sendmsg (2),
.BR recvmsg (2),
.BR getsockopt (2).
+.BR setsockopt (2).
More information about the rds-commits
mailing list