-- --
-- S p e c --
-- --
--- Copyright (C) 2001-2009, 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. --
-- 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
-- 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'
-- 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.
-- -- 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
-- Socket_Level,
-- (Reuse_Address, True));
- -- -- Force Pong to block
+ -- -- Force Ping to block
-- delay 0.2;
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;
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
-- 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
-- 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
-- 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
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;
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;
-- 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;
-- 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;
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 (or to Stream_Element_Array'Last if Item'First is
- -- Stream_Element_Offset'First) 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;
-- 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;
-- 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 Item'First is
- -- Stream_Element_Offset'First, to Stream_Element_Array'Last) when the
- -- socket has been closed by peer. This is not an error and no exception
- -- is raised. 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.
+ -- 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;
Last : out Ada.Streams.Stream_Element_Offset;
Flags : Request_Flag_Type := No_Request_Flag);
-- Transmit a message over a socket. Upon return, Last is set to the index
- -- within Item of the last element transmitted. Flags allows to control
+ -- within Item of the last element transmitted. Flags allows control of
-- the transmission. Raises Socket_Error on any detected error condition.
procedure Send_Socket
To : Sock_Addr_Type;
Flags : Request_Flag_Type := No_Request_Flag);
-- Transmit a message over a datagram socket. The destination address is
- -- To. Flags allows to control the transmission. Raises Socket_Error on
+ -- To. Flags allows control of the transmission. Raises Socket_Error on
-- error.
procedure Send_Vector
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.
- -- Flags allow control over transmission.
+ -- 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;
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
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 has default
+ -- 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
-- 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 safely abort 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.
+ -- 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;
-- 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;
-- 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
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.long'Alignment;
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;