-- --
-- S p e c --
-- --
--- Copyright (C) 2001-2005 Ada Core Technologies, Inc. --
+-- Copyright (C) 2001-2007, 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- --
-- 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, 59 Temple Place - Suite 330, Boston, --
--- MA 02111-1307, USA. --
+-- to the Free Software Foundation, 51 Franklin Street, Fifth Floor, --
+-- Boston, MA 02110-1301, USA. --
-- --
-- As a special exception, if other files instantiate generics from this --
-- unit, or you link this unit with other files to produce an executable, --
-- installed. In particular Multicast is not available with the Windows
-- version.
--- The VMS implementation has implemented using the DECC RTL Socket API,
+-- 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
-- Socket_Level,
-- (Reuse_Address, True));
- -- -- Join a multicast group
-
- -- Set_Socket_Option
- -- (Socket,
- -- IP_Protocol_For_IP_Level,
- -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
-
-- -- Controls the live time of the datagram to avoid it being
-- -- looped forever due to routing errors. Routers decrement
-- -- the TTL of every datagram as it traverses from one network
-- Bind_Socket (Socket, Address);
+ -- -- Join a multicast group
+
+ -- -- Portability note: On Windows, this option may be set only
+ -- -- on a bound socket.
+
+ -- Set_Socket_Option
+ -- (Socket,
+ -- IP_Protocol_For_IP_Level,
+ -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
+
-- -- If this socket is intended to send messages, provide the
-- -- receiver socket address.
-- Set_Socket_Option
-- (Socket,
-- IP_Protocol_For_IP_Level,
- -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
-
- -- Set_Socket_Option
- -- (Socket,
- -- IP_Protocol_For_IP_Level,
-- (Multicast_TTL, 1));
-- Set_Socket_Option
-- Bind_Socket (Socket, Address);
+ -- Set_Socket_Option
+ -- (Socket,
+ -- IP_Protocol_For_IP_Level,
+ -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
+
-- Address.Addr := Inet_Addr (Group);
-- Address.Port := 55505;
-- end Ping;
-- begin
- -- -- Indicate whether the thread library provides process
- -- -- blocking IO. Basically, if you are not using FSU threads
- -- -- the default is ok.
-
- -- Initialize (Process_Blocking_IO => False);
+ -- Initialize;
-- Ping.Start;
-- Pong.Start;
-- Ping.Stop;
-- Finalize;
-- end PingPong;
- procedure Initialize (Process_Blocking_IO : Boolean := False);
- -- Initialize must be called before using any other socket routines. The
- -- Process_Blocking_IO parameter indicates whether the thread library
- -- provides process-blocking or thread-blocking input/output operations.
- -- In the former case (typically with FSU threads) GNAT.Sockets should be
- -- initialized with a value of True to provide task-blocking IO through an
- -- emulation mechanism. Only the first call to Initialize is taken into
- -- account (further calls will be ignored). Note that with the default
- -- value of Process_Blocking_IO, this operation is a no-op on UNIX
- -- platforms, but applications should make sure to call it if portability
- -- is expected: some platforms (such as Windows) require initialization
- -- before any other socket operations.
+ procedure Initialize;
+ -- Initialize must be called before using any other socket routines.
+ -- Note that this operation is a no-op on UNIX platforms, but applications
+ -- should make sure to call it if portability is expected: some platforms
+ -- (such as Windows) require initialization before any socket operation.
+
+ procedure Initialize (Process_Blocking_IO : Boolean);
+ pragma Obsolescent
+ (Entity => Initialize,
+ "passing a parameter to Initialize is not supported anymore");
+ -- Previous versions of GNAT.Sockets used to require the user to indicate
+ -- whether socket I/O was process- or thread-blocking on the platform.
+ -- This property is now determined automatically when the run-time library
+ -- is built. The old version of Initialize, taking a parameter, is kept
+ -- for compatibility reasons, but this interface is obsolete (and if the
+ -- value given is wrong, an exception will be raised at run time).
procedure Finalize;
-- After Finalize is called it is not possible to use any routines
Host_Error : exception;
-- Exception raised by the two following procedures. Once raised, its
-- message contains a string describing the error code. This exception is
- -- raised when an host entry can not be retrieved.
+ -- raised when an host entry cannot be retrieved.
function Get_Host_By_Address
(Address : Inet_Addr_Type;
Unknown_Server_Error,
Cannot_Resolve_Error);
+ -- 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.
+
+ Immediate : constant := 0.0;
+ Forever : constant := Duration (Integer'Last) * 1.0;
+
+ subtype Timeval_Duration is Duration range Immediate .. Forever;
+
-- Get_Socket_Options and Set_Socket_Options manipulate options associated
-- with a socket. Options may exist at multiple protocol levels in the
-- communication stack. Socket_Level is the uppermost socket level.
-- 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 broadcast packets
- 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 packets (TCP_NODELAY)
- Add_Membership, -- Join a multicast group
- Drop_Membership, -- Leave a multicast group
- Multicast_TTL, -- Indicate the time-to-live of sent multicast packets
- Multicast_Loop); -- Sent multicast packets are looped to the local socket
+ 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 packets (TCP_NODELAY)
+ Add_Membership, -- Join a multicast group
+ Drop_Membership, -- Leave a multicast group
+ Multicast_If, -- Set default outgoing interface for multicast packets
+ Multicast_TTL, -- Indicate the time-to-live of sent multicast packets
+ Multicast_Loop, -- Sent multicast packets are looped to local socket
+ 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
Multicast_Address : Inet_Addr_Type;
Local_Interface : Inet_Addr_Type;
+ when Multicast_If =>
+ Outgoing_If : Inet_Addr_Type;
+
when Multicast_TTL =>
Time_To_Live : Natural;
+ when Send_Timeout |
+ Receive_Timeout =>
+ Timeout : Timeval_Duration;
+
end case;
end record;
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;
+ 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 a datagram-based socket that is already
-- bound. Send_To is the socket address to which messages are being sent.
- function Get_Address
- (Stream : Stream_Access) return Sock_Addr_Type;
+ function Get_Address (Stream : Stream_Access) return Sock_Addr_Type;
-- Return the socket address from which the last message was received
procedure Free is new Ada.Unchecked_Deallocation
-- Extract a Socket from socket set Item. Socket is set to
-- No_Socket when the set is empty.
- function Is_Empty
- (Item : Socket_Set_Type) return Boolean;
+ function Is_Empty (Item : Socket_Set_Type) return Boolean;
-- Return True iff Item is empty
function Is_Set
type Selector_Type is limited private;
type Selector_Access is access all Selector_Type;
- -- Selector_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.
-
- Immediate : constant := 0.0;
- Forever : constant := Duration (Integer'Last) * 1.0;
-
- subtype Selector_Duration is Duration range Immediate .. Forever;
+ subtype Selector_Duration is Timeval_Duration;
procedure Create_Selector (Selector : out Selector_Type);
-- Create a new selector
procedure Close_Selector (Selector : in out Selector_Type);
- -- Close Selector and all internal descriptors associated
+ -- 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).
type Selector_Status is (Completed, Expired, Aborted);
-- cases Status is set to Completed and sockets that are ready are set in
-- 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. As this
- -- procedure returns when Timeout occurs, it is a design choice to keep
- -- this procedure process blocking. Note that a Timeout of 0.0 returns
- -- immediately. Also 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 will be lost.
+ -- 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.
No_Socket : constant Socket_Type := -1;
type Selector_Type is limited record
- R_Sig_Socket : Socket_Type;
- W_Sig_Socket : Socket_Type;
+ R_Sig_Socket : Socket_Type := No_Socket;
+ W_Sig_Socket : Socket_Type := No_Socket;
end record;
pragma Volatile (Selector_Type);