clarify documentation of flags parameter

Net/include/Poco/Net/DatagramSocket.h

@@ -69,7 +69,7 @@ public:
 		///
 		/// Releases the socket's SocketImpl and
 		/// attaches the SocketImpl from the other socket and
-		/// increments the reference count of the SocketImpl.	
+		/// increments the reference count of the SocketImpl.
 
 	void connect(const SocketAddress& address);
 		/// Restricts incoming and outgoing
@@ -81,7 +81,7 @@ public:
 		/// Bind a local address to the socket.
 		///
 		/// This is usually only done when establishing a server
-		/// socket. 
+		/// socket.
 		///
 		/// If reuseAddress is true, sets the SO_REUSEADDR
 		/// socket option.
@@ -92,7 +92,7 @@ public:
 		/// Bind a local address to the socket.
 		///
 		/// This is usually only done when establishing a server
-		/// socket. 
+		/// socket.
 		///
 		/// If reuseAddress is true, sets the SO_REUSEADDR
 		/// socket option.
@@ -108,6 +108,9 @@ public:
 		///
 		/// Returns the number of bytes sent, which may be
 		/// less than the number of bytes specified.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for send() like MSG_DONTROUTE.
 
 	int sendBytes(const SocketBufVec& buffer, int flags = 0);
 		/// Sends the contents of the given buffers through
@@ -115,22 +118,34 @@ public:
 		///
 		/// Returns the number of bytes sent, which may be
 		/// less than the number of bytes specified.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for send() like MSG_DONTROUTE.
 
 	int receiveBytes(void* buffer, int length, int flags = 0);
 		/// Receives data from the socket and stores it
 		/// in buffer. Up to length bytes are received.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_PEEK.
 
 	int receiveBytes(SocketBufVec& buffer, int flags = 0);
 		/// Receives data from the socket and stores it in buffers.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_PEEK.
 
 	int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& timeout = 100000);
 		/// Receives data from the socket and stores it in buffers.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_PEEK.
 
 	int sendTo(const void* buffer, int length, const SocketAddress& address, int flags = 0);
 		/// Sends the contents of the given buffer through
@@ -138,6 +153,9 @@ public:
 		///
 		/// Returns the number of bytes sent, which may be
 		/// less than the number of bytes specified.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for sendto() like MSG_DONTROUTE.
 
 	int sendTo(const SocketBufVec& buffers, const SocketAddress& address, int flags = 0);
 		/// Sends the contents of the given buffers through
@@ -145,6 +163,9 @@ public:
 		///
 		/// Returns the number of bytes sent, which may be
 		/// less than the number of bytes specified.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for sendto() like MSG_DONTROUTE.
 
 	int receiveFrom(void* buffer, int length, SocketAddress& address, int flags = 0);
 		/// Receives data from the socket and stores it
@@ -152,6 +173,9 @@ public:
 		/// Stores the address of the sender in address.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recvfrom() like MSG_PEEK.
 
 	int receiveFrom(void* buffer, int length, struct sockaddr** ppSA, poco_socklen_t** ppSALen, int flags = 0);
 		/// Receives data from the socket and stores it
@@ -160,6 +184,9 @@ public:
 		/// ppSA, and the length of native address in ppSALen.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recvfrom() like MSG_PEEK.
 
 	int receiveFrom(SocketBufVec& buffers, SocketAddress& address, int flags = 0);
 		/// Receives data from the socket and stores it
@@ -168,6 +195,9 @@ public:
 		/// Stores the address of the sender in address.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recvfrom() like MSG_PEEK.
 
 	int receiveFrom(SocketBufVec& buffers, struct sockaddr** ppSA, poco_socklen_t** ppSALen, int flags = 0);
 		/// Receives data from the socket and stores it
@@ -176,13 +206,16 @@ public:
 		/// ppSA, and the length of native address in ppSALen.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recvfrom() like MSG_PEEK.
 
 	void setBroadcast(bool flag);
 		/// Sets the value of the SO_BROADCAST socket option.
 		///
 		/// Setting this flag allows sending datagrams to
 		/// the broadcast address.
-	
+
 	bool getBroadcast() const;
 		/// Returns the value of the SO_BROADCAST socket option.
 

Net/include/Poco/Net/StreamSocket.h

@@ -50,7 +50,7 @@ public:
 		/// for the given address family.
 		///
 		/// This is useful if certain socket options
-		/// (like send and receive buffer) sizes, that must 
+		/// (like send and receive buffer) sizes, that must
 		/// be set before connecting the socket, will be
 		/// set later on.
 
@@ -68,10 +68,10 @@ public:
 		///
 		/// Releases the socket's SocketImpl and
 		/// attaches the SocketImpl from the other socket and
-		/// increments the reference count of the SocketImpl.	
+		/// increments the reference count of the SocketImpl.
 
 	void connect(const SocketAddress& address);
-		/// Initializes the socket and establishes a connection to 
+		/// Initializes the socket and establishes a connection to
 		/// the TCP server at the given address.
 		///
 		/// Can also be used for UDP sockets. In this case, no
@@ -79,24 +79,24 @@ public:
 		/// packets are restricted to the specified address.
 
 	void connect(const SocketAddress& address, const Poco::Timespan& timeout);
-		/// Initializes the socket, sets the socket timeout and 
+		/// Initializes the socket, sets the socket timeout and
 		/// establishes a connection to the TCP server at the given address.
 
 	void connectNB(const SocketAddress& address);
-		/// Initializes the socket and establishes a connection to 
+		/// Initializes the socket and establishes a connection to
 		/// the TCP server at the given address. Prior to opening the
 		/// connection the socket is set to nonblocking mode.
 
 	void shutdownReceive();
 		/// Shuts down the receiving part of the socket connection.
-		
+
 	void shutdownSend();
 		/// Shuts down the sending part of the socket connection.
-		
+
 	void shutdown();
 		/// Shuts down both the receiving and the sending part
 		/// of the socket connection.
-	
+
 	int sendBytes(const void* buffer, int length, int flags = 0);
 		/// Sends the contents of the given buffer through
 		/// the socket.
@@ -106,6 +106,9 @@ public:
 		///
 		/// Certain socket implementations may also return a negative
 		/// value denoting a certain condition.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for send() like MSG_OOB.
 
 	int sendBytes(const SocketBufVec& buffer, int flags = 0);
 		/// Sends the contents of the given buffers through
@@ -113,6 +116,9 @@ public:
 		///
 		/// Returns the number of bytes sent, which may be
 		/// less than the number of bytes specified.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for send() like MSG_OOB.
 
 	int sendBytes(Poco::FIFOBuffer& buffer);
 		/// Sends the contents of the given buffer through
@@ -126,38 +132,50 @@ public:
 		///
 		/// Certain socket implementations may also return a negative
 		/// value denoting a certain condition.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for send() like MSG_OOB.
 
 	int receiveBytes(void* buffer, int length, int flags = 0);
 		/// Receives data from the socket and stores it
 		/// in buffer. Up to length bytes are received.
 		///
-		/// Returns the number of bytes received. 
+		/// Returns the number of bytes received.
-		/// A return value of 0 means a graceful shutdown 
+		/// A return value of 0 means a graceful shutdown
 		/// of the connection from the peer.
 		///
 		/// Throws a TimeoutException if a receive timeout has
 		/// been set and nothing is received within that interval.
 		/// Throws a NetException (or a subclass) in case of other errors.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.
 
 	int receiveBytes(SocketBufVec& buffer, int flags = 0);
 		/// Receives data from the socket and stores it in buffers.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.
 
 	int receiveBytes(Poco::Buffer<char>& buffer, int flags = 0, const Poco::Timespan& timeout = 100000);
 		/// Receives data from the socket and stores it in buffers.
 		///
 		/// Returns the number of bytes received.
+		///
+		/// The flags parameter can be used to pass system-defined flags
+		/// for recv() like MSG_OOB, MSG_PEEK or MSG_WAITALL.
 
 	int receiveBytes(Poco::FIFOBuffer& buffer);
 		/// Receives data from the socket and stores it
-		/// in buffer. Up to length bytes are received. FIFOBuffer has 
+		/// in buffer. Up to length bytes are received. FIFOBuffer has
-		/// writable/readable transition notifications which may be enabled 
+		/// writable/readable transition notifications which may be enabled
-		/// to notify the caller when the buffer transitions between empty, 
+		/// to notify the caller when the buffer transitions between empty,
 		/// partially full and full states.
 		///
-		/// Returns the number of bytes received. 
+		/// Returns the number of bytes received.
-		/// A return value of 0 means a graceful shutdown 
+		/// A return value of 0 means a graceful shutdown
 		/// of the connection from the peer.
 		///
 		/// Throws a TimeoutException if a receive timeout has