[multiple changes]
[gcc.git] / gcc / ada / g-socket.ads
index 39107783eb14fd4523b2a26760102d6ac17680fa..517dd4f510ad86aa6c2de081874fd1b1cbea55fb 100644 (file)
@@ -6,25 +6,23 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---                     Copyright (C) 2001-2008, AdaCore                     --
+--                     Copyright (C) 2001-2014, AdaCore                     --
 --                                                                          --
 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
 -- terms of the  GNU General Public License as published  by the Free Soft- --
--- ware  Foundation;  either version 2,  or (at your option) any later ver- --
+-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
--- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
--- for  more details.  You should have  received  a copy of the GNU General --
--- Public License  distributed with GNAT;  see file COPYING.  If not, write --
--- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
--- Boston, MA 02110-1301, USA.                                              --
+-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
 --                                                                          --
--- As a special exception,  if other files  instantiate  generics from this --
--- unit, or you link  this unit with other files  to produce an executable, --
--- this  unit  does not  by itself cause  the resulting  executable  to  be --
--- covered  by the  GNU  General  Public  License.  This exception does not --
--- however invalidate  any other reasons why  the executable file  might be --
--- covered by the  GNU Public License.                                      --
+-- As a special exception under Section 7 of GPL version 3, you are granted --
+-- additional permissions described in the GCC Runtime Library Exception,   --
+-- version 3.1, as published by the Free Software Foundation.               --
+--                                                                          --
+-- You should have received a copy of the GNU General Public License and    --
+-- a copy of the GCC Runtime Library Exception along with this program;     --
+-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
+-- <http://www.gnu.org/licenses/>.                                          --
 --                                                                          --
 -- GNAT was originally developed  by the GNAT team at  New York University. --
 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
@@ -41,9 +39,6 @@
 --       feature, so it is not available if Multicast is not supported, or not
 --       installed.
 
---       The VMS implementation was implemented using the DECC RTL Socket API,
---       and is thus subject to limitations in the implementation of this API.
-
 --     VxWorks cross ports fully implement this package
 
 --     This package is not yet implemented on LynxOS or other cross ports
@@ -61,7 +56,7 @@ package GNAT.Sockets is
 
    --  Sockets are designed to provide a consistent communication facility
    --  between applications. This package provides an Ada binding to the
-   --  the de-facto standard BSD sockets API. The documentation below covers
+   --  de-facto standard BSD sockets API. The documentation below covers
    --  only the specific binding provided by this package. It assumes that
    --  the reader is already familiar with general network programming and
    --  sockets usage. A useful reference on this matter is W. Richard Stevens'
@@ -109,8 +104,6 @@ package GNAT.Sockets is
    --        Channel  : Stream_Access;
 
    --     begin
-   --        accept Start;
-   --
    --        --  Get an Internet address of a host (here the local host name).
    --        --  Note that a host can have several addresses. Here we get
    --        --  the first one which is supposed to be the official one.
@@ -147,6 +140,8 @@ package GNAT.Sockets is
    --        --  represents the server side of the connection. Server remains
    --        --  available to receive further connections.
 
+   --        accept Start;
+
    --        Accept_Socket (Server, Socket, Address);
 
    --        --  Return a stream associated to the connected socket
@@ -280,7 +275,7 @@ package GNAT.Sockets is
    --           Socket_Level,
    --           (Reuse_Address, True));
 
-   --        --  Force Pong to block
+   --        --  Force Ping to block
 
    --        delay 0.2;
 
@@ -422,16 +417,21 @@ package GNAT.Sockets is
    type Selector_Access is access all Selector_Type;
    --  Selector objects are used to wait for i/o events to occur on sockets
 
+   Null_Selector : constant Selector_Type;
+   --  The Null_Selector can be used in place of a normal selector without
+   --  having to call Create_Selector if the use of Abort_Selector is not
+   --  required.
+
    --  Timeval_Duration is a subtype of Standard.Duration because the full
    --  range of Standard.Duration cannot be represented in the equivalent C
-   --  structure. Moreover, negative values are not allowed to avoid system
-   --  incompatibilities.
+   --  structure (struct timeval). Moreover, negative values are not allowed
+   --  to avoid system incompatibilities.
 
    Immediate : constant Duration := 0.0;
 
-   Timeval_Forever : constant := 2.0 ** (SOSC.SIZEOF_tv_sec * 8 - 1) - 1.0;
-   Forever         : constant Duration :=
-                       Duration'Min (Duration'Last, Timeval_Forever);
+   Forever : constant Duration :=
+               Duration'Min (Duration'Last, 1.0 * SOSC.MAX_tv_sec);
+   --  Largest possible Duration that is also a valid value for struct timeval
 
    subtype Timeval_Duration is Duration range Immediate .. Forever;
 
@@ -459,8 +459,7 @@ package GNAT.Sockets is
 
    type Family_Type is (Family_Inet, Family_Inet6);
    --  Address family (or protocol family) identifies the communication domain
-   --  and groups protocols with similar address formats. IPv6 will soon be
-   --  supported.
+   --  and groups protocols with similar address formats.
 
    type Mode_Type is (Socket_Stream, Socket_Datagram);
    --  Stream sockets provide connection-oriented byte streams. Datagram
@@ -474,13 +473,14 @@ package GNAT.Sockets is
    --  more data can be transmitted. Neither transmission nor reception can be
    --  performed with Shut_Read_Write.
 
-   type Port_Type is new Natural;
-   --  Classical port definition. No_Port provides a special value to
-   --  denote uninitialized port. Any_Port provides a special value
-   --  enabling all ports.
+   type Port_Type is range 0 .. 16#ffff#;
+   --  TCP/UDP port number
 
    Any_Port : constant Port_Type;
-   No_Port  : constant Port_Type;
+   --  All ports
+
+   No_Port : constant Port_Type;
+   --  Uninitialized port number
 
    type Inet_Addr_Type (Family : Family_Type := Family_Inet) is private;
    --  An Internet address depends on an address family (IPv4 contains 4 octets
@@ -491,6 +491,13 @@ package GNAT.Sockets is
    Any_Inet_Addr       : constant Inet_Addr_Type;
    No_Inet_Addr        : constant Inet_Addr_Type;
    Broadcast_Inet_Addr : constant Inet_Addr_Type;
+   Loopback_Inet_Addr  : constant Inet_Addr_Type;
+
+   --  Useful constants for IPv4 multicast addresses
+
+   Unspecified_Group_Inet_Addr : constant Inet_Addr_Type;
+   All_Hosts_Group_Inet_Addr   : constant Inet_Addr_Type;
+   All_Routers_Group_Inet_Addr : constant Inet_Addr_Type;
 
    type Sock_Addr_Type (Family : Family_Type := Family_Inet) is record
       Addr : Inet_Addr_Type (Family);
@@ -603,6 +610,9 @@ package GNAT.Sockets is
    --  brackets and a string describing the error code.
 
    --  The name of the enumeration constant documents the error condition
+   --  Note that on some platforms, a single error value is used for both
+   --  EWOULDBLOCK and EAGAIN. Both errors are therefore always reported as
+   --  Resource_Temporarily_Unavailable.
 
    type Error_Type is
      (Success,
@@ -644,6 +654,7 @@ package GNAT.Sockets is
       Connection_Timed_Out,
       Too_Many_References,
       Resource_Temporarily_Unavailable,
+      Broken_Pipe,
       Unknown_Host,
       Host_Name_Lookup_Failure,
       Non_Recoverable_Error,
@@ -654,33 +665,33 @@ package GNAT.Sockets is
    --  with a socket. Options may exist at multiple protocol levels in the
    --  communication stack. Socket_Level is the uppermost socket level.
 
-   type Level_Type is (
-     Socket_Level,
-     IP_Protocol_For_IP_Level,
-     IP_Protocol_For_UDP_Level,
-     IP_Protocol_For_TCP_Level);
+   type Level_Type is
+     (Socket_Level,
+      IP_Protocol_For_IP_Level,
+      IP_Protocol_For_UDP_Level,
+      IP_Protocol_For_TCP_Level);
 
    --  There are several options available to manipulate sockets. Each option
    --  has a name and several values available. Most of the time, the value is
    --  a boolean to enable or disable this option.
 
-   type Option_Name is (
-     Keep_Alive,          -- Enable sending of keep-alive messages
-     Reuse_Address,       -- Allow bind to reuse local address
-     Broadcast,           -- Enable datagram sockets to recv/send broadcasts
-     Send_Buffer,         -- Set/get the maximum socket send buffer in bytes
-     Receive_Buffer,      -- Set/get the maximum socket recv buffer in bytes
-     Linger,              -- Shutdown wait for msg to be sent or timeout occur
-     Error,               -- Get and clear the pending socket error
-     No_Delay,            -- Do not delay send to coalesce data (TCP_NODELAY)
-     Add_Membership,      -- Join a multicast group
-     Drop_Membership,     -- Leave a multicast group
-     Multicast_If,        -- Set default out interface for multicast packets
-     Multicast_TTL,       -- Set the time-to-live of sent multicast packets
-     Multicast_Loop,      -- Sent multicast packets are looped to local socket
-     Receive_Packet_Info, -- Receive low level packet info as ancillary data
-     Send_Timeout,        -- Set timeout value for output
-     Receive_Timeout);    -- Set timeout value for input
+   type Option_Name is
+     (Keep_Alive,          -- Enable sending of keep-alive messages
+      Reuse_Address,       -- Allow bind to reuse local address
+      Broadcast,           -- Enable datagram sockets to recv/send broadcasts
+      Send_Buffer,         -- Set/get the maximum socket send buffer in bytes
+      Receive_Buffer,      -- Set/get the maximum socket recv buffer in bytes
+      Linger,              -- Shutdown wait for msg to be sent or timeout occur
+      Error,               -- Get and clear the pending socket error
+      No_Delay,            -- Do not delay send to coalesce data (TCP_NODELAY)
+      Add_Membership,      -- Join a multicast group
+      Drop_Membership,     -- Leave a multicast group
+      Multicast_If,        -- Set default out interface for multicast packets
+      Multicast_TTL,       -- Set the time-to-live of sent multicast packets
+      Multicast_Loop,      -- Sent multicast packets are looped to local socket
+      Receive_Packet_Info, -- Receive low level packet info as ancillary data
+      Send_Timeout,        -- Set timeout value for output
+      Receive_Timeout);    -- Set timeout value for input
 
    type Option_Type (Name : Option_Name := Keep_Alive) is record
       case Name is
@@ -730,8 +741,8 @@ package GNAT.Sockets is
    --  socket options in that they are not specific to sockets but are
    --  available for any device.
 
-   type Request_Name is (
-      Non_Blocking_IO,  --  Cause a caller not to wait on blocking operations.
+   type Request_Name is
+     (Non_Blocking_IO,  --  Cause a caller not to wait on blocking operations
       N_Bytes_To_Read); --  Return the number of bytes available to read
 
    type Request_Type (Name : Request_Name := Non_Blocking_IO) is record
@@ -745,8 +756,8 @@ package GNAT.Sockets is
       end case;
    end record;
 
-   --  A request flag allows to specify the type of message transmissions or
-   --  receptions. A request flag can be combination of zero or more
+   --  A request flag allows specification of the type of message transmissions
+   --  or receptions. A request flag can be combination of zero or more
    --  predefined request flags.
 
    type Request_Flag_Type is private;
@@ -783,7 +794,7 @@ package GNAT.Sockets is
 
    type Vector_Element is record
       Base   : Stream_Element_Reference;
-      Length : Ada.Streams.Stream_Element_Count;
+      Length : Interfaces.C.size_t;
    end record;
 
    type Vector_Type is array (Integer range <>) of Vector_Element;
@@ -802,7 +813,8 @@ package GNAT.Sockets is
    --  connections, creates a new connected socket with mostly the same
    --  properties as Server, and allocates a new socket. The returned Address
    --  is filled in with the address of the connection. Raises Socket_Error on
-   --  error.
+   --  error. Note: if Server is a non-blocking socket, whether or not this
+   --  aspect is inherited by Socket is platform-dependent.
 
    procedure Accept_Socket
      (Server   : Socket_Type;
@@ -844,7 +856,9 @@ package GNAT.Sockets is
    --  whether the operation completed successfully, timed out, or was aborted.
    --  If Selector is not null, the designated selector is used to wait for the
    --  socket to become available, else a private selector object is created
-   --  by this procedure and destroyed before it returns.
+   --  by this procedure and destroyed before it returns. If Timeout is 0.0,
+   --  no attempt is made to detect whether the connection has succeeded; it
+   --  is up to the user to determine this using Check_Selector later on.
 
    procedure Control_Socket
      (Socket  : Socket_Type;
@@ -884,9 +898,11 @@ package GNAT.Sockets is
       Flags  : Request_Flag_Type := No_Request_Flag);
    --  Receive message from Socket. Last is the index value such that Item
    --  (Last) is the last character assigned. Note that Last is set to
-   --  Item'First - 1 when the socket has been closed by peer. This is not an
-   --  error and no exception is raised. Flags allows to control the
-   --  reception. Raise Socket_Error on error.
+   --  Item'First - 1 when the socket has been closed by peer. This is not
+   --  an error, and no exception is raised in this case unless Item'First
+   --  is Stream_Element_Offset'First, in which case Constraint_Error is
+   --  raised. Flags allows control of the reception. Raise Socket_Error on
+   --  error.
 
    procedure Receive_Socket
      (Socket : Socket_Type;
@@ -897,14 +913,16 @@ package GNAT.Sockets is
    --  Receive message from Socket. If Socket is not connection-oriented, the
    --  source address From of the message is filled in. Last is the index
    --  value such that Item (Last) is the last character assigned. Flags
-   --  allows to control the reception. Raises Socket_Error on error.
+   --  allows control of the reception. Raises Socket_Error on error.
 
    procedure Receive_Vector
      (Socket : Socket_Type;
       Vector : Vector_Type;
-      Count  : out Ada.Streams.Stream_Element_Count);
+      Count  : out Ada.Streams.Stream_Element_Count;
+      Flags  : Request_Flag_Type := No_Request_Flag);
    --  Receive data from a socket and scatter it into the set of vector
    --  elements Vector. Count is set to the count of received stream elements.
+   --  Flags allow control over reception.
 
    function Resolve_Exception
      (Occurrence : Ada.Exceptions.Exception_Occurrence) return Error_Type;
@@ -913,15 +931,32 @@ package GNAT.Sockets is
    --  error code. Resolve_Error extracts the error code from an exception
    --  message and translate it into an enumeration value.
 
+   procedure Send_Socket
+     (Socket : Socket_Type;
+      Item   : Ada.Streams.Stream_Element_Array;
+      Last   : out Ada.Streams.Stream_Element_Offset;
+      To     : access Sock_Addr_Type;
+      Flags  : Request_Flag_Type := No_Request_Flag);
+   pragma Inline (Send_Socket);
+   --  Transmit a message over a socket. For a datagram socket, the address
+   --  is given by To.all. For a stream socket, To must be null. Last
+   --  is the index value such that Item (Last) is the last character
+   --  sent. Note that Last is set to Item'First - 1 if the socket has been
+   --  closed by the peer (unless Item'First is Stream_Element_Offset'First,
+   --  in which case Constraint_Error is raised instead). This is not an error,
+   --  and Socket_Error is not raised in that case. Flags allows control of the
+   --  transmission. Raises exception Socket_Error on error. Note: this
+   --  subprogram is inlined because it is also used to implement the two
+   --  variants below.
+
    procedure Send_Socket
      (Socket : Socket_Type;
       Item   : Ada.Streams.Stream_Element_Array;
       Last   : out Ada.Streams.Stream_Element_Offset;
       Flags  : Request_Flag_Type := No_Request_Flag);
-   --  Transmit a message to another socket. Note that Last is set to
-   --  Item'First-1 when socket has been closed by peer. This is not
-   --  considered an error and no exception is raised. Flags allows to control
-   --  the transmission. Raises Socket_Error on any other error condition.
+   --  Transmit a message over a socket. Upon return, Last is set to the index
+   --  within Item of the last element transmitted. Flags allows control of
+   --  the transmission. Raises Socket_Error on any detected error condition.
 
    procedure Send_Socket
      (Socket : Socket_Type;
@@ -929,15 +964,29 @@ package GNAT.Sockets is
       Last   : out Ada.Streams.Stream_Element_Offset;
       To     : Sock_Addr_Type;
       Flags  : Request_Flag_Type := No_Request_Flag);
-   --  Transmit a message to another socket. The address is given by To. Flags
-   --  allows to control the transmission. Raises Socket_Error on error.
+   --  Transmit a message over a datagram socket. The destination address is
+   --  To. Flags allows control of the transmission. Raises Socket_Error on
+   --  error.
 
    procedure Send_Vector
      (Socket : Socket_Type;
       Vector : Vector_Type;
-      Count  : out Ada.Streams.Stream_Element_Count);
+      Count  : out Ada.Streams.Stream_Element_Count;
+      Flags  : Request_Flag_Type := No_Request_Flag);
    --  Transmit data gathered from the set of vector elements Vector to a
-   --  socket. Count is set to the count of transmitted stream elements.
+   --  socket. Count is set to the count of transmitted stream elements. Flags
+   --  allow control over transmission.
+
+   procedure Set_Close_On_Exec
+     (Socket        : Socket_Type;
+      Close_On_Exec : Boolean;
+      Status        : out Boolean);
+   --  When Close_On_Exec is True, mark Socket to be closed automatically when
+   --  a new program is executed by the calling process (i.e. prevent Socket
+   --  from being inherited by child processes). When Close_On_Exec is False,
+   --  mark Socket to not be closed on exec (i.e. allow it to be inherited).
+   --  Status is False if the operation could not be performed, or is not
+   --  supported on the target platform.
 
    procedure Set_Socket_Option
      (Socket : Socket_Type;
@@ -948,23 +997,21 @@ package GNAT.Sockets is
    procedure Shutdown_Socket
      (Socket : Socket_Type;
       How    : Shutmode_Type := Shut_Read_Write);
-   --  Shutdown a connected socket. If How is Shut_Read, further receives will
-   --  be disallowed. If How is Shut_Write, further sends will be disallowed.
-   --  If how is Shut_Read_Write, further sends and receives will be
-   --  disallowed.
+   --  Shutdown a connected socket. If How is Shut_Read further receives will
+   --  be disallowed. If How is Shut_Write further sends will be disallowed.
+   --  If How is Shut_Read_Write further sends and receives will be disallowed.
 
    type Stream_Access is access all Ada.Streams.Root_Stream_Type'Class;
    --  Same interface as Ada.Streams.Stream_IO
 
    function Stream (Socket : Socket_Type) return Stream_Access;
-   --  Create a stream associated with a stream-based socket that is
-   --  already connected.
+   --  Create a stream associated with an already connected stream-based socket
 
    function Stream
      (Socket  : Socket_Type;
       Send_To : Sock_Addr_Type) return Stream_Access;
-   --  Create a stream associated with a datagram-based socket that is already
-   --  bound. Send_To is the socket address to which messages are being sent.
+   --  Create a stream associated with an already bound datagram-based socket.
+   --  Send_To is the destination address to which messages are being sent.
 
    function Get_Address
      (Stream : not null Stream_Access) return Sock_Addr_Type;
@@ -972,23 +1019,26 @@ package GNAT.Sockets is
 
    procedure Free is new Ada.Unchecked_Deallocation
      (Ada.Streams.Root_Stream_Type'Class, Stream_Access);
-   --  Destroy a stream created by one of the Stream functions above,
-   --  releasing the corresponding resources. The user is responsible for
-   --  calling this subprogram when the stream is not needed anymore.
+   --  Destroy a stream created by one of the Stream functions above, releasing
+   --  the corresponding resources. The user is responsible for calling this
+   --  subprogram when the stream is not needed anymore.
 
    type Socket_Set_Type is limited private;
-   --  This type allows to manipulate sets of sockets. It allows to wait for
-   --  events on multiple endpoints at one time. This type used to contain
-   --  a pointer to dynamically allocated storage, but this is not the case
-   --  anymore, and no special precautions are required to avoid memory leaks.
+   --  This type allows manipulation of sets of sockets. It allows waiting
+   --  for events on multiple endpoints at one time. This type has default
+   --  initialization, and the default value is the empty set.
+   --
+   --  Note: This type used to contain a pointer to dynamically allocated
+   --  storage, but this is not the case anymore, and no special precautions
+   --  are required to avoid memory leaks.
 
    procedure Clear (Item : in out Socket_Set_Type; Socket : Socket_Type);
    --  Remove Socket from Item
 
-   procedure Copy  (Source : Socket_Set_Type; Target : in out Socket_Set_Type);
+   procedure Copy (Source : Socket_Set_Type; Target : out Socket_Set_Type);
    --  Copy Source into Target as Socket_Set_Type is limited private
 
-   procedure Empty (Item : in out Socket_Set_Type);
+   procedure Empty (Item : out Socket_Set_Type);
    --  Remove all Sockets from Item
 
    procedure Get (Item : in out Socket_Set_Type; Socket : out Socket_Type);
@@ -1017,28 +1067,33 @@ package GNAT.Sockets is
    --  can block the full process (not just the calling thread).
    --
    --  Check_Selector provides the very same behaviour. The only difference is
-   --  that it does not watch for exception events. Note that on some
-   --  platforms it is kept process blocking on purpose. The timeout parameter
-   --  allows the user to have the behaviour he wants. Abort_Selector allows
-   --  to abort safely a Check_Selector that is blocked forever. A special
-   --  file descriptor is opened by Create_Selector and included in each call
-   --  to Check_Selector. Abort_Selector causes an event to occur on this
-   --  descriptor in order to unblock Check_Selector. The user must call
-   --  Close_Selector to discard this special file. A reason to abort a select
-   --  operation is typically to add a socket in one of the socket sets when
-   --  the timeout is set to forever.
+   --  that it does not watch for exception events. Note that on some platforms
+   --  it is kept process blocking on purpose. The timeout parameter allows the
+   --  user to have the behaviour he wants. Abort_Selector allows the safe
+   --  abort of a blocked Check_Selector call. A special socket is opened by
+   --  Create_Selector and included in each call to Check_Selector.
+   --
+   --  Abort_Selector causes an event to occur on this descriptor in order to
+   --  unblock Check_Selector. Note that each call to Abort_Selector will cause
+   --  exactly one call to Check_Selector to return with Aborted status. The
+   --  special socket created by Create_Selector is closed when Close_Selector
+   --  is called.
+   --
+   --  A typical case where it is useful to abort a Check_Selector operation is
+   --  the situation where a change to the monitored sockets set must be made.
 
    procedure Create_Selector (Selector : out Selector_Type);
-   --  Create a new selector
+   --  Initialize (open) a new selector
 
    procedure Close_Selector (Selector : in out Selector_Type);
    --  Close Selector and all internal descriptors associated; deallocate any
    --  associated resources. This subprogram may be called only when there is
    --  no other task still using Selector (i.e. still executing Check_Selector
-   --  or Abort_Selector on this Selector).
+   --  or Abort_Selector on this Selector). Has no effect if Selector is
+   --  already closed.
 
    procedure Check_Selector
-     (Selector     : in out Selector_Type;
+     (Selector     : Selector_Type;
       R_Socket_Set : in out Socket_Set_Type;
       W_Socket_Set : in out Socket_Set_Type;
       Status       : out Selector_Status;
@@ -1049,27 +1104,30 @@ package GNAT.Sockets is
    --  R_Socket_Set or W_Socket_Set. Status is set to Expired if no socket was
    --  ready after a Timeout expiration. Status is set to Aborted if an abort
    --  signal has been received while checking socket status.
+   --
    --  Note that two different Socket_Set_Type objects must be passed as
    --  R_Socket_Set and W_Socket_Set (even if they denote the same set of
    --  Sockets), or some event may be lost.
-   --  Socket_Error is raised when the select(2) system call returns an
-   --  error condition, or when a read error occurs on the signalling socket
-   --  used for the implementation of Abort_Selector.
+   --
+   --  Socket_Error is raised when the select(2) system call returns an error
+   --  condition, or when a read error occurs on the signalling socket used for
+   --  the implementation of Abort_Selector.
 
    procedure Check_Selector
-     (Selector     : in out Selector_Type;
+     (Selector     : Selector_Type;
       R_Socket_Set : in out Socket_Set_Type;
       W_Socket_Set : in out Socket_Set_Type;
       E_Socket_Set : in out Socket_Set_Type;
       Status       : out Selector_Status;
       Timeout      : Selector_Duration := Forever);
-   --  This refined version of Check_Selector allows to watch for exception
-   --  events (that is notifications of out-of-band transmission and
-   --  reception). As above, all of R_Socket_Set, W_Socket_Set and
-   --  E_Socket_Set must be different objects.
+   --  This refined version of Check_Selector allows watching for exception
+   --  events (i.e. notifications of out-of-band transmission and reception).
+   --  As above, all of R_Socket_Set, W_Socket_Set and E_Socket_Set must be
+   --  different objects.
 
    procedure Abort_Selector (Selector : Selector_Type);
-   --  Send an abort signal to the selector
+   --  Send an abort signal to the selector. The Selector may not be the
+   --  Null_Selector.
 
    type Fd_Set is private;
    --  ??? This type must not be used directly, it needs to be visible because
@@ -1085,17 +1143,33 @@ private
    type Socket_Type is new Integer;
    No_Socket : constant Socket_Type := -1;
 
-   type Selector_Type is limited record
-      R_Sig_Socket : Socket_Type := No_Socket;
-      W_Sig_Socket : Socket_Type := No_Socket;
-      --  Signalling sockets used to abort a select operation
+   --  A selector is either a null selector, which is always "open" and can
+   --  never be aborted, or a regular selector, which is created "closed",
+   --  becomes "open" when Create_Selector is called, and "closed" again when
+   --  Close_Selector is called.
+
+   type Selector_Type (Is_Null : Boolean := False) is limited record
+      case Is_Null is
+         when True =>
+            null;
+
+         when False =>
+            R_Sig_Socket : Socket_Type := No_Socket;
+            W_Sig_Socket : Socket_Type := No_Socket;
+            --  Signalling sockets used to abort a select operation
+      end case;
    end record;
 
    pragma Volatile (Selector_Type);
 
+   Null_Selector : constant Selector_Type := (Is_Null => True);
+
    type Fd_Set is
      new System.Storage_Elements.Storage_Array (1 .. SOSC.SIZEOF_fd_set);
-   for Fd_Set'Alignment use Interfaces.C.int'Alignment;
+   for Fd_Set'Alignment use Interfaces.C.long'Alignment;
+   --  Set conservative alignment so that our Fd_Sets are always adequately
+   --  aligned for the underlying data type (which is implementation defined
+   --  and may be an array of C long integers).
 
    type Fd_Set_Access is access all Fd_Set;
    pragma Convention (C, Fd_Set_Access);
@@ -1103,7 +1177,12 @@ private
 
    type Socket_Set_Type is record
       Last : Socket_Type := No_Socket;
-      Set  : aliased Fd_Set;
+      --  Highest socket in set. Last = No_Socket denotes an empty set (which
+      --  is the default initial value).
+
+      Set : aliased Fd_Set;
+      --  Underlying socket set. Note that the contents of this component is
+      --  undefined if Last = No_Socket.
    end record;
 
    subtype Inet_Addr_Comp_Type is Natural range 0 .. 255;
@@ -1133,6 +1212,15 @@ private
                            (Family_Inet, (others => 0));
    Broadcast_Inet_Addr : constant Inet_Addr_Type :=
                            (Family_Inet, (others => 255));
+   Loopback_Inet_Addr  : constant Inet_Addr_Type :=
+                           (Family_Inet, (127, 0, 0, 1));
+
+   Unspecified_Group_Inet_Addr : constant Inet_Addr_Type :=
+                                   (Family_Inet, (224, 0, 0, 0));
+   All_Hosts_Group_Inet_Addr   : constant Inet_Addr_Type :=
+                                   (Family_Inet, (224, 0, 0, 1));
+   All_Routers_Group_Inet_Addr : constant Inet_Addr_Type :=
+                                   (Family_Inet, (224, 0, 0, 2));
 
    No_Sock_Addr : constant Sock_Addr_Type := (Family_Inet, No_Inet_Addr, 0);
 
@@ -1141,9 +1229,7 @@ private
 
    subtype Name_Index is Natural range 1 .. Max_Name_Length;
 
-   type Name_Type
-     (Length : Name_Index := Max_Name_Length)
-   is record
+   type Name_Type (Length : Name_Index := Max_Name_Length) is record
       Name : String (1 .. Length);
    end record;
    --  We need fixed strings to avoid access types in host entry type
@@ -1158,10 +1244,10 @@ private
    end record;
 
    type Service_Entry_Type (Aliases_Length : Natural) is record
-      Official  : Name_Type;
-      Aliases   : Name_Array (1 .. Aliases_Length);
-      Port      : Port_Type;
-      Protocol  : Name_Type;
+      Official : Name_Type;
+      Aliases  : Name_Array (1 .. Aliases_Length);
+      Port     : Port_Type;
+      Protocol : Name_Type;
    end record;
 
    type Request_Flag_Type is mod 2 ** 8;