1 ------------------------------------------------------------------------------
3 -- GNAT COMPILER COMPONENTS --
5 -- G N A T . S O C K E T S --
9 -- Copyright (C) 2001-2003 Ada Core Technologies, Inc. --
11 -- GNAT is free software; you can redistribute it and/or modify it under --
12 -- terms of the GNU General Public License as published by the Free Soft- --
13 -- ware Foundation; either version 2, or (at your option) any later ver- --
14 -- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
15 -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
16 -- or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License --
17 -- for more details. You should have received a copy of the GNU General --
18 -- Public License distributed with GNAT; see file COPYING. If not, write --
19 -- to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, --
20 -- MA 02111-1307, USA. --
22 -- As a special exception, if other files instantiate generics from this --
23 -- unit, or you link this unit with other files to produce an executable, --
24 -- this unit does not by itself cause the resulting executable to be --
25 -- covered by the GNU General Public License. This exception does not --
26 -- however invalidate any other reasons why the executable file might be --
27 -- covered by the GNU Public License. --
29 -- GNAT was originally developed by the GNAT team at New York University. --
30 -- Extensive contributions were provided by Ada Core Technologies Inc. --
32 ------------------------------------------------------------------------------
34 -- This package provides an interface to the sockets communication
35 -- facility provided on many operating systems. This is implemented
36 -- on the following platforms:
38 -- All native ports, except Interix, with restrictions as follows
40 -- Multicast is available only on systems which provide support
41 -- for this feature, so it is not available if Multicast is not
42 -- supported, or not installed. In particular Multicast is not
43 -- available with the Windows version.
45 -- The VMS implementation has implemented using the DECC RTL Socket
46 -- API, and is thus subject to limitations in the implementation of
49 -- This package is not supported on the Interix port of GNAT.
51 -- VxWorks cross ports fully implement this package.
53 -- This package is not yet implemented on LynxOS.
60 package GNAT.Sockets is
62 -- Sockets are designed to provide a consistent communication facility
63 -- between applications. This package provides an Ada-like interface
64 -- similar to that proposed as part of the BSD socket layer.
66 -- GNAT.Sockets has been designed with several ideas in mind.
68 -- This is a system independent interface. Therefore, we try as
69 -- much as possible to mask system incompatibilities. Some
70 -- functionalities are not available because there are not fully
71 -- supported on some systems.
73 -- This is a thick binding. For instance, a major effort has been
74 -- done to avoid using memory addresses or untyped ints. We
75 -- preferred to define streams and enumeration types. Errors are
76 -- not returned as returned values but as exceptions.
78 -- This package provides a POSIX-compliant interface (between two
79 -- different implementations of the same routine, we adopt the one
80 -- closest to the POSIX specification). For instance, using
81 -- select(), the notification of an asynchronous connect failure
82 -- is delivered in the write socket set (POSIX) instead of the
83 -- exception socket set (NT).
85 -- Here is a typical example of what you can do:
87 -- with GNAT.Sockets; use GNAT.Sockets;
90 -- with Ada.Exceptions; use Ada.Exceptions;
92 -- procedure PingPong is
94 -- Group : constant String := "239.255.128.128";
95 -- -- Multicast group: administratively scoped IP address
103 -- Address : Sock_Addr_Type;
104 -- Server : Socket_Type;
105 -- Socket : Socket_Type;
106 -- Channel : Stream_Access;
111 -- -- Get an Internet address of a host (here the local host name).
112 -- -- Note that a host can have several addresses. Here we get
113 -- -- the first one which is supposed to be the official one.
115 -- Address.Addr := Addresses (Get_Host_By_Name (Host_Name), 1);
117 -- -- Get a socket address that is an Internet address and a port
119 -- Address.Port := 5876;
121 -- -- The first step is to create a socket. Once created, this
122 -- -- socket must be associated to with an address. Usually only
123 -- -- a server (Pong here) needs to bind an address explicitly.
124 -- -- Most of the time clients can skip this step because the
125 -- -- socket routines will bind an arbitrary address to an unbound
128 -- Create_Socket (Server);
130 -- -- Allow reuse of local addresses
135 -- (Reuse_Address, True));
137 -- Bind_Socket (Server, Address);
139 -- -- A server marks a socket as willing to receive connect events
141 -- Listen_Socket (Server);
143 -- -- Once a server calls Listen_Socket, incoming connects events
144 -- -- can be accepted. The returned Socket is a new socket that
145 -- -- represents the server side of the connection. Server remains
146 -- -- available to receive further connections.
148 -- Accept_Socket (Server, Socket, Address);
150 -- -- Return a stream associated to the connected socket
152 -- Channel := Stream (Socket);
154 -- -- Force Pong to block
158 -- -- Receive and print message from client Ping
161 -- Message : String := String'Input (Channel);
164 -- Ada.Text_IO.Put_Line (Message);
166 -- -- Send same message back to client Ping
168 -- String'Output (Channel, Message);
171 -- Close_Socket (Server);
172 -- Close_Socket (Socket);
174 -- -- Part of the multicast example
176 -- -- Create a datagram socket to send connectionless, unreliable
177 -- -- messages of a fixed maximum length.
179 -- Create_Socket (Socket, Family_Inet, Socket_Datagram);
181 -- -- Allow reuse of local addresses
186 -- (Reuse_Address, True));
188 -- -- Join a multicast group
192 -- IP_Protocol_For_IP_Level,
193 -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
195 -- -- Controls the live time of the datagram to avoid it being
196 -- -- looped forever due to routing errors. Routers decrement
197 -- -- the TTL of every datagram as it traverses from one network
198 -- -- to another and when its value reaches 0 the packet is
199 -- -- dropped. Default is 1.
203 -- IP_Protocol_For_IP_Level,
204 -- (Multicast_TTL, 1));
206 -- -- Want the data you send to be looped back to your host
210 -- IP_Protocol_For_IP_Level,
211 -- (Multicast_Loop, True));
213 -- -- If this socket is intended to receive messages, bind it
214 -- -- to a given socket address.
216 -- Address.Addr := Any_Inet_Addr;
217 -- Address.Port := 55505;
219 -- Bind_Socket (Socket, Address);
221 -- -- If this socket is intended to send messages, provide the
222 -- -- receiver socket address.
224 -- Address.Addr := Inet_Addr (Group);
225 -- Address.Port := 55506;
227 -- Channel := Stream (Socket, Address);
229 -- -- Receive and print message from client Ping
232 -- Message : String := String'Input (Channel);
235 -- -- Get the address of the sender
237 -- Address := Get_Address (Channel);
238 -- Ada.Text_IO.Put_Line (Message & " from " & Image (Address));
240 -- -- Send same message back to client Ping
242 -- String'Output (Channel, Message);
245 -- Close_Socket (Socket);
249 -- exception when E : others =>
250 -- Ada.Text_IO.Put_Line
251 -- (Exception_Name (E) & ": " & Exception_Message (E));
260 -- Address : Sock_Addr_Type;
261 -- Socket : Socket_Type;
262 -- Channel : Stream_Access;
267 -- -- See comments in Ping section for the first steps
269 -- Address.Addr := Addresses (Get_Host_By_Name (Host_Name), 1);
270 -- Address.Port := 5876;
271 -- Create_Socket (Socket);
276 -- (Reuse_Address, True));
278 -- -- Force Pong to block
282 -- -- If the client's socket is not bound, Connect_Socket will
283 -- -- bind to an unused address. The client uses Connect_Socket to
284 -- -- create a logical connection between the client's socket and
285 -- -- a server's socket returned by Accept_Socket.
287 -- Connect_Socket (Socket, Address);
289 -- Channel := Stream (Socket);
291 -- -- Send message to server Pong.
293 -- String'Output (Channel, "Hello world");
295 -- -- Force Ping to block
299 -- -- Receive and print message from server Pong
301 -- Ada.Text_IO.Put_Line (String'Input (Channel));
302 -- Close_Socket (Socket);
304 -- -- Part of multicast example. Code similar to Pong's one
306 -- Create_Socket (Socket, Family_Inet, Socket_Datagram);
311 -- (Reuse_Address, True));
315 -- IP_Protocol_For_IP_Level,
316 -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr));
320 -- IP_Protocol_For_IP_Level,
321 -- (Multicast_TTL, 1));
325 -- IP_Protocol_For_IP_Level,
326 -- (Multicast_Loop, True));
328 -- Address.Addr := Any_Inet_Addr;
329 -- Address.Port := 55506;
331 -- Bind_Socket (Socket, Address);
333 -- Address.Addr := Inet_Addr (Group);
334 -- Address.Port := 55505;
336 -- Channel := Stream (Socket, Address);
338 -- -- Send message to server Pong
340 -- String'Output (Channel, "Hello world");
342 -- -- Receive and print message from server Pong
345 -- Message : String := String'Input (Channel);
348 -- Address := Get_Address (Channel);
349 -- Ada.Text_IO.Put_Line (Message & " from " & Image (Address));
352 -- Close_Socket (Socket);
356 -- exception when E : others =>
357 -- Ada.Text_IO.Put_Line
358 -- (Exception_Name (E) & ": " & Exception_Message (E));
362 -- -- Indicate whether the thread library provides process
363 -- -- blocking IO. Basically, if you are not using FSU threads
364 -- -- the default is ok.
366 -- Initialize (Process_Blocking_IO => False);
374 procedure Initialize (Process_Blocking_IO : Boolean := False);
375 -- Initialize must be called before using any other socket routines.
376 -- The Process_Blocking_IO parameter indicates whether the thread
377 -- library provides process-blocking or thread-blocking input/output
378 -- operations. In the former case (typically with FSU threads)
379 -- GNAT.Sockets should be initialized with a value of True to
380 -- provide task-blocking IO through an emulation mechanism.
381 -- Only the first call to Initialize is taken into account (further
382 -- calls will be ignored). Note that with the default value
383 -- of Process_Blocking_IO, this operation is a no-op on UNIX
384 -- platforms, but applications should make sure to call it
385 -- if portability is expected: some platforms (such as Windows)
386 -- require initialization before any other socket operations.
389 -- After Finalize is called it is not possible to use any routines
390 -- exported in by this package. This procedure is idempotent.
392 type Socket_Type is private;
393 -- Sockets are used to implement a reliable bi-directional
394 -- point-to-point, stream-based connections between
395 -- hosts. No_Socket provides a special value to denote
396 -- uninitialized sockets.
398 No_Socket : constant Socket_Type;
400 Socket_Error : exception;
401 -- There is only one exception in this package to deal with an
402 -- error during a socket routine. Once raised, its message
403 -- contains a string describing the error code.
405 function Image (Socket : Socket_Type) return String;
406 -- Return a printable string for Socket
408 function To_C (Socket : Socket_Type) return Integer;
409 -- Return a file descriptor to be used by external subprograms
410 -- especially the C functions that are not yet interfaced in this
413 type Family_Type is (Family_Inet, Family_Inet6);
414 -- Address family (or protocol family) identifies the
415 -- communication domain and groups protocols with similar address
416 -- formats. IPv6 will soon be supported.
418 type Mode_Type is (Socket_Stream, Socket_Datagram);
419 -- Stream sockets provide connection-oriented byte
420 -- streams. Datagram sockets support unreliable connectionless
421 -- message based communication.
423 type Shutmode_Type is (Shut_Read, Shut_Write, Shut_Read_Write);
424 -- When a process closes a socket, the policy is to retain any
425 -- data queued until either a delivery or a timeout expiration (in
426 -- this case, the data are discarded). A finer control is
427 -- available through shutdown. With Shut_Read, no more data can be
428 -- received from the socket. With_Write, no more data can be
429 -- transmitted. Neither transmission nor reception can be
430 -- performed with Shut_Read_Write.
432 type Port_Type is new Natural;
433 -- Classical port definition. No_Port provides a special value to
434 -- denote uninitialized port. Any_Port provides a special value
435 -- enabling all ports.
437 Any_Port : constant Port_Type;
438 No_Port : constant Port_Type;
440 type Inet_Addr_Type (Family : Family_Type := Family_Inet) is private;
441 -- An Internet address depends on an address family (IPv4 contains
442 -- 4 octets and Ipv6 contains 16 octets). Any_Inet_Address is a
443 -- special value treated like a wildcard enabling all addresses.
444 -- No_Inet_Addr provides a special value to denote uninitialized
447 Any_Inet_Addr : constant Inet_Addr_Type;
448 No_Inet_Addr : constant Inet_Addr_Type;
450 type Sock_Addr_Type (Family : Family_Type := Family_Inet) is record
451 Addr : Inet_Addr_Type (Family);
454 -- Socket addresses fully define a socket connection with a
455 -- protocol family, an Internet address and a port. No_Sock_Addr
456 -- provides a special value for uninitialized socket addresses.
458 No_Sock_Addr : constant Sock_Addr_Type;
460 function Image (Value : Inet_Addr_Type) return String;
461 -- Return an image of an Internet address. IPv4 notation consists
462 -- in 4 octets in decimal format separated by dots. IPv6 notation
463 -- consists in 16 octets in hexadecimal format separated by
464 -- colons (and possibly dots).
466 function Image (Value : Sock_Addr_Type) return String;
467 -- Return inet address image and port image separated by a colon.
469 function Inet_Addr (Image : String) return Inet_Addr_Type;
470 -- Convert address image from numbers-and-dots notation into an
473 -- Host entries provide complete information on a given host:
474 -- the official name, an array of alternative names or aliases and
475 -- array of network addresses.
478 (Aliases_Length, Addresses_Length : Natural) is private;
480 function Official_Name (E : Host_Entry_Type) return String;
481 -- Return official name in host entry
483 function Aliases_Length (E : Host_Entry_Type) return Natural;
484 -- Return number of aliases in host entry
486 function Addresses_Length (E : Host_Entry_Type) return Natural;
487 -- Return number of addresses in host entry
490 (E : Host_Entry_Type;
493 -- Return N'th aliases in host entry. The first index is 1.
496 (E : Host_Entry_Type;
498 return Inet_Addr_Type;
499 -- Return N'th addresses in host entry. The first index is 1.
501 Host_Error : exception;
502 -- Exception raised by the two following procedures. Once raised,
503 -- its message contains a string describing the error code. This
504 -- exception is raised when an host entry can not be retrieved.
506 function Get_Host_By_Address
507 (Address : Inet_Addr_Type;
508 Family : Family_Type := Family_Inet)
509 return Host_Entry_Type;
510 -- Return host entry structure for the given inet address
512 function Get_Host_By_Name
514 return Host_Entry_Type;
515 -- Return host entry structure for the given host name. Here name
516 -- is either a host name, or an IP address.
518 function Host_Name return String;
519 -- Return the name of the current host
521 -- Service entries provide complete information on a given
522 -- service: the official name, an array of alternative names or
523 -- aliases and the port number.
525 type Service_Entry_Type (Aliases_Length : Natural) is private;
527 function Official_Name (S : Service_Entry_Type) return String;
528 -- Return official name in service entry
530 function Port_Number (S : Service_Entry_Type) return Port_Type;
531 -- Return port number in service entry
533 function Protocol_Name (S : Service_Entry_Type) return String;
534 -- Return Protocol in service entry (usually UDP or TCP)
536 function Aliases_Length (S : Service_Entry_Type) return Natural;
537 -- Return number of aliases in service entry
540 (S : Service_Entry_Type;
543 -- Return N'th aliases in service entry. The first index is 1.
545 function Get_Service_By_Name
548 return Service_Entry_Type;
549 -- Return service entry structure for the given service name
551 function Get_Service_By_Port
554 return Service_Entry_Type;
555 -- Return service entry structure for the given service port number
557 Service_Error : exception;
559 -- Errors are described by an enumeration type. There is only one
560 -- exception Socket_Error in this package to deal with an error
561 -- during a socket routine. Once raised, its message contains the
562 -- error code between brackets and a string describing the error code.
564 -- The name of the enumeration constant documents the error condition.
569 Address_Already_In_Use,
570 Cannot_Assign_Requested_Address,
571 Address_Family_Not_Supported_By_Protocol,
572 Operation_Already_In_Progress,
574 Software_Caused_Connection_Abort,
576 Connection_Reset_By_Peer,
577 Destination_Address_Required,
581 Operation_Now_In_Progress,
582 Interrupted_System_Call,
585 Transport_Endpoint_Already_Connected,
586 Too_Many_Symbolic_Links,
591 Network_Dropped_Connection_Because_Of_Reset,
592 Network_Is_Unreachable,
593 No_Buffer_Space_Available,
594 Protocol_Not_Available,
595 Transport_Endpoint_Not_Connected,
596 Socket_Operation_On_Non_Socket,
597 Operation_Not_Supported,
598 Protocol_Family_Not_Supported,
599 Protocol_Not_Supported,
600 Protocol_Wrong_Type_For_Socket,
601 Cannot_Send_After_Transport_Endpoint_Shutdown,
602 Socket_Type_Not_Supported,
603 Connection_Timed_Out,
605 Resource_Temporarily_Unavailable,
607 Host_Name_Lookup_Failure,
608 Non_Recoverable_Error,
609 Unknown_Server_Error,
610 Cannot_Resolve_Error);
612 -- Get_Socket_Options and Set_Socket_Options manipulate options
613 -- associated with a socket. Options may exist at multiple
614 -- protocol levels in the communication stack. Socket_Level is the
615 -- uppermost socket level.
619 IP_Protocol_For_IP_Level,
620 IP_Protocol_For_UDP_Level,
621 IP_Protocol_For_TCP_Level);
623 -- There are several options available to manipulate sockets. Each
624 -- option has a name and several values available. Most of the
625 -- time, the value is a boolean to enable or disable this option.
627 type Option_Name is (
628 Keep_Alive, -- Enable sending of keep-alive messages
629 Reuse_Address, -- Allow bind to reuse local address
630 Broadcast, -- Enable datagram sockets to recv/send broadcast packets
631 Send_Buffer, -- Set/get the maximum socket send buffer in bytes
632 Receive_Buffer, -- Set/get the maximum socket recv buffer in bytes
633 Linger, -- Shutdown wait for msg to be sent or timeout occur
634 Error, -- Get and clear the pending socket error
635 No_Delay, -- Do not delay send to coalesce packets (TCP_NODELAY)
636 Add_Membership, -- Join a multicast group
637 Drop_Membership, -- Leave a multicast group
638 Multicast_TTL, -- Indicate the time-to-live of sent multicast packets
639 Multicast_Loop); -- Sent multicast packets are looped to the local socket
641 type Option_Type (Name : Option_Name := Keep_Alive) is record
665 when Add_Membership |
667 Multiaddr : Inet_Addr_Type;
668 Interface : Inet_Addr_Type;
670 when Multicast_TTL =>
671 Time_To_Live : Natural;
676 -- There are several controls available to manipulate
677 -- sockets. Each option has a name and several values available.
678 -- These controls differ from the socket options in that they are
679 -- not specific to sockets but are available for any device.
681 type Request_Name is (
682 Non_Blocking_IO, -- Cause a caller not to wait on blocking operations.
683 N_Bytes_To_Read); -- Return the number of bytes available to read
685 type Request_Type (Name : Request_Name := Non_Blocking_IO) is record
687 when Non_Blocking_IO =>
690 when N_Bytes_To_Read =>
696 -- A request flag allows to specify the type of message
697 -- transmissions or receptions. A request flag can be a
698 -- combination of zero or more predefined request flags.
700 type Request_Flag_Type is private;
702 No_Request_Flag : constant Request_Flag_Type;
703 -- This flag corresponds to the normal execution of an operation.
705 Process_Out_Of_Band_Data : constant Request_Flag_Type;
706 -- This flag requests that the receive or send function operates
707 -- on out-of-band data when the socket supports this notion (e.g.
710 Peek_At_Incoming_Data : constant Request_Flag_Type;
711 -- This flag causes the receive operation to return data from the
712 -- beginning of the receive queue without removing that data from
713 -- the queue. A subsequent receive call will return the same data.
715 Wait_For_A_Full_Reception : constant Request_Flag_Type;
716 -- This flag requests that the operation block until the full
717 -- request is satisfied. However, the call may still return less
718 -- data than requested if a signal is caught, an error or
719 -- disconnect occurs, or the next data to be received is of a dif-
720 -- ferent type than that returned.
722 Send_End_Of_Record : constant Request_Flag_Type;
723 -- This flag indicates that the entire message has been sent and
724 -- so this terminates the record.
726 function "+" (L, R : Request_Flag_Type) return Request_Flag_Type;
727 -- Combine flag L with flag R
729 type Stream_Element_Reference is access all Ada.Streams.Stream_Element;
731 type Vector_Element is record
732 Base : Stream_Element_Reference;
733 Length : Ada.Streams.Stream_Element_Count;
736 type Vector_Type is array (Integer range <>) of Vector_Element;
738 procedure Create_Socket
739 (Socket : out Socket_Type;
740 Family : Family_Type := Family_Inet;
741 Mode : Mode_Type := Socket_Stream);
742 -- Create an endpoint for communication. Raises Socket_Error on error.
744 procedure Accept_Socket
745 (Server : Socket_Type;
746 Socket : out Socket_Type;
747 Address : out Sock_Addr_Type);
748 -- Extract the first connection request on the queue of pending
749 -- connections, creates a new connected socket with mostly the
750 -- same properties as Server, and allocates a new socket. The
751 -- returned Address is filled in with the address of the
752 -- connection. Raises Socket_Error on error.
754 procedure Bind_Socket
755 (Socket : Socket_Type;
756 Address : Sock_Addr_Type);
757 -- Once a socket is created, assign a local address to it. Raise
758 -- Socket_Error on error.
760 procedure Close_Socket (Socket : Socket_Type);
761 -- Close a socket and more specifically a non-connected socket.
763 procedure Connect_Socket
764 (Socket : Socket_Type;
765 Server : in out Sock_Addr_Type);
766 -- Make a connection to another socket which has the address of
767 -- Server. Raises Socket_Error on error.
769 procedure Control_Socket
770 (Socket : Socket_Type;
771 Request : in out Request_Type);
772 -- Obtain or set parameter values that control the socket. This
773 -- control differs from the socket options in that they are not
774 -- specific to sockets but are available for any device.
776 function Get_Peer_Name (Socket : Socket_Type) return Sock_Addr_Type;
777 -- Return the peer or remote socket address of a socket. Raise
778 -- Socket_Error on error.
780 function Get_Socket_Name (Socket : Socket_Type) return Sock_Addr_Type;
781 -- Return the local or current socket address of a socket. Return
782 -- No_Sock_Addr on error (for instance, socket closed or not
785 function Get_Socket_Option
786 (Socket : Socket_Type;
787 Level : Level_Type := Socket_Level;
790 -- Get the options associated with a socket. Raises Socket_Error
793 procedure Listen_Socket
794 (Socket : Socket_Type;
795 Length : Positive := 15);
796 -- To accept connections, a socket is first created with
797 -- Create_Socket, a willingness to accept incoming connections and
798 -- a queue Length for incoming connections are specified. Raise
799 -- Socket_Error on error.
801 procedure Receive_Socket
802 (Socket : Socket_Type;
803 Item : out Ada.Streams.Stream_Element_Array;
804 Last : out Ada.Streams.Stream_Element_Offset;
805 Flags : Request_Flag_Type := No_Request_Flag);
806 -- Receive message from Socket. Last is the index value such that
807 -- Item (Last) is the last character assigned. Note that Last is
808 -- set to Item'First - 1 when the socket has been closed by
809 -- peer. This is not an error and no exception is raised. Flags
810 -- allows to control the reception. Raise Socket_Error on error.
812 procedure Receive_Socket
813 (Socket : Socket_Type;
814 Item : out Ada.Streams.Stream_Element_Array;
815 Last : out Ada.Streams.Stream_Element_Offset;
816 From : out Sock_Addr_Type;
817 Flags : Request_Flag_Type := No_Request_Flag);
818 -- Receive message from Socket. If Socket is not
819 -- connection-oriented, the source address From of the message is
820 -- filled in. Last is the index value such that Item (Last) is the
821 -- last character assigned. Flags allows to control the
822 -- reception. Raises Socket_Error on error.
824 procedure Receive_Vector
825 (Socket : Socket_Type;
826 Vector : Vector_Type;
827 Count : out Ada.Streams.Stream_Element_Count);
828 -- Receive data from a socket and scatter it into the set of vector
829 -- elements Vector. Count is set to the count of received stream elements.
831 function Resolve_Exception
832 (Occurrence : Ada.Exceptions.Exception_Occurrence)
834 -- When Socket_Error or Host_Error are raised, the exception
835 -- message contains the error code between brackets and a string
836 -- describing the error code. Resolve_Error extracts the error
837 -- code from an exception message and translate it into an
838 -- enumeration value.
840 procedure Send_Socket
841 (Socket : Socket_Type;
842 Item : Ada.Streams.Stream_Element_Array;
843 Last : out Ada.Streams.Stream_Element_Offset;
844 Flags : Request_Flag_Type := No_Request_Flag);
845 -- Transmit a message to another socket. Note that Last is set to
846 -- Item'First-1 when socket has been closed by peer. This is not
847 -- considered an error and no exception is raised. Flags allows to
848 -- control the transmission. Raises Socket_Error on any other
851 procedure Send_Socket
852 (Socket : Socket_Type;
853 Item : Ada.Streams.Stream_Element_Array;
854 Last : out Ada.Streams.Stream_Element_Offset;
856 Flags : Request_Flag_Type := No_Request_Flag);
857 -- Transmit a message to another socket. The address is given by
858 -- To. Flags allows to control the transmission. Raises
859 -- Socket_Error on error.
861 procedure Send_Vector
862 (Socket : Socket_Type;
863 Vector : Vector_Type;
864 Count : out Ada.Streams.Stream_Element_Count);
865 -- Transmit data gathered from the set of vector elements Vector to a
866 -- socket. Count is set to the count of transmitted stream elements.
868 procedure Set_Socket_Option
869 (Socket : Socket_Type;
870 Level : Level_Type := Socket_Level;
871 Option : Option_Type);
872 -- Manipulate socket options. Raises Socket_Error on error.
874 procedure Shutdown_Socket
875 (Socket : Socket_Type;
876 How : Shutmode_Type := Shut_Read_Write);
877 -- Shutdown a connected socket. If How is Shut_Read, further
878 -- receives will be disallowed. If How is Shut_Write, further
879 -- sends will be disallowed. If how is Shut_Read_Write, further
880 -- sends and receives will be disallowed.
882 type Stream_Access is access all Ada.Streams.Root_Stream_Type'Class;
883 -- Same interface as Ada.Streams.Stream_IO
886 (Socket : Socket_Type)
887 return Stream_Access;
888 -- Create a stream associated with a stream-based socket that is
889 -- already connected.
892 (Socket : Socket_Type;
893 Send_To : Sock_Addr_Type)
894 return Stream_Access;
895 -- Create a stream associated with a datagram-based socket that is
896 -- already bound. Send_To is the socket address to which messages are
900 (Stream : Stream_Access)
901 return Sock_Addr_Type;
902 -- Return the socket address from which the last message was
905 procedure Free (Stream : in out Stream_Access);
906 -- Destroy a stream created by one of the Stream functions above, and
907 -- release associated resources. The user is responsible for calling
908 -- this subprogram when the stream is not needed anymore.
910 type Socket_Set_Type is limited private;
911 -- This type allows to manipulate sets of sockets. It allows to
912 -- wait for events on multiple endpoints at one time. This is an
913 -- access type on a system dependent structure. To avoid memory
914 -- leaks it is highly recommended to clean the access value with
917 procedure Clear (Item : in out Socket_Set_Type; Socket : Socket_Type);
918 -- Remove Socket from Item
920 procedure Copy (Source : Socket_Set_Type; Target : in out Socket_Set_Type);
921 -- Copy Source into Target as Socket_Set_Type is limited private
923 procedure Empty (Item : in out Socket_Set_Type);
924 -- Remove all Sockets from Item and deallocate internal data
926 procedure Get (Item : in out Socket_Set_Type; Socket : out Socket_Type);
927 -- Extract a Socket from socket set Item. Socket is set to
928 -- No_Socket when the set is empty.
931 (Item : Socket_Set_Type)
933 -- Return True if Item is empty
936 (Item : Socket_Set_Type;
937 Socket : Socket_Type)
939 -- Return True if Socket is present in Item
941 procedure Set (Item : in out Socket_Set_Type; Socket : Socket_Type);
942 -- Insert Socket into Item
944 -- C select() waits for a number of file descriptors to change
945 -- status. Usually, three independent sets of descriptors are
946 -- watched (read, write and exception). A timeout gives an upper
947 -- bound on the amount of time elapsed before select returns.
948 -- This function blocks until an event occurs. On some platforms,
949 -- C select can block the full process.
951 -- Check_Selector provides the very same behaviour. The only
952 -- difference is that it does not watch for exception events. Note
953 -- that on some platforms it is kept process blocking in purpose.
954 -- The timeout parameter allows the user to have the behaviour he
955 -- wants. Abort_Selector allows to abort safely a Check_Selector
956 -- that is blocked forever. A special file descriptor is opened by
957 -- Create_Selector and included in each call to
958 -- Check_Selector. Abort_Selector causes an event to occur on this
959 -- descriptor in order to unblock Check_Selector. The user must
960 -- call Close_Selector to discard this special file. A reason to
961 -- abort a select operation is typically to add a socket in one of
962 -- the socket sets when the timeout is set to forever.
964 type Selector_Type is limited private;
965 type Selector_Access is access all Selector_Type;
967 -- Selector_Duration is a subtype of Standard.Duration because the
968 -- full range of Standard.Duration cannot be represented in the
969 -- equivalent C structure. Moreover, negative values are not
970 -- allowed to avoid system incompatibilities.
972 Immediate : constant := 0.0;
973 Forever : constant := Duration (Integer'Last) * 1.0;
975 subtype Selector_Duration is Duration range Immediate .. Forever;
977 procedure Create_Selector (Selector : out Selector_Type);
978 -- Create a new selector
980 procedure Close_Selector (Selector : in out Selector_Type);
981 -- Close Selector and all internal descriptors associated
983 type Selector_Status is (Completed, Expired, Aborted);
985 procedure Check_Selector
986 (Selector : in out Selector_Type;
987 R_Socket_Set : in out Socket_Set_Type;
988 W_Socket_Set : in out Socket_Set_Type;
989 Status : out Selector_Status;
990 Timeout : Selector_Duration := Forever);
991 -- Return when one Socket in R_Socket_Set has some data to be read
992 -- or if one Socket in W_Socket_Set is ready to receive some
993 -- data. In these cases Status is set to Completed and sockets
994 -- that are ready are set in R_Socket_Set or W_Socket_Set. Status
995 -- is set to Expired if no socket was ready after a Timeout
996 -- expiration. Status is set to Aborted if an abort signal has been
997 -- received while checking socket status. As this procedure
998 -- returns when Timeout occurs, it is a design choice to keep this
999 -- procedure process blocking. Note that a Timeout of 0.0 returns
1000 -- immediately. Also note that two different objects must be passed
1001 -- as R_Socket_Set and W_Socket_Set (even if they contain the same
1002 -- set of Sockets), or some event will be lost.
1004 procedure Check_Selector
1005 (Selector : in out Selector_Type;
1006 R_Socket_Set : in out Socket_Set_Type;
1007 W_Socket_Set : in out Socket_Set_Type;
1008 E_Socket_Set : in out Socket_Set_Type;
1009 Status : out Selector_Status;
1010 Timeout : Selector_Duration := Forever);
1011 -- This refined version of Check_Selector allows to watch for
1012 -- exception events (that is notifications of out-of-band
1013 -- transmission and reception). As above, all of R_Socket_Set,
1014 -- W_Socket_Set and E_Socket_Set must be different objects.
1016 procedure Abort_Selector (Selector : Selector_Type);
1017 -- Send an abort signal to the selector.
1021 type Socket_Type is new Integer;
1022 No_Socket : constant Socket_Type := -1;
1024 type Selector_Type is limited record
1025 R_Sig_Socket : Socket_Type;
1026 W_Sig_Socket : Socket_Type;
1029 pragma Volatile (Selector_Type);
1031 -- The two signalling sockets are used to abort a select
1034 subtype Socket_Set_Access is System.Address;
1035 No_Socket_Set : constant Socket_Set_Access := System.Null_Address;
1037 type Socket_Set_Type is record
1038 Last : Socket_Type := No_Socket;
1039 Set : Socket_Set_Access := No_Socket_Set;
1042 subtype Inet_Addr_Comp_Type is Natural range 0 .. 255;
1043 -- Octet for Internet address
1045 type Inet_Addr_VN_Type is array (Natural range <>) of Inet_Addr_Comp_Type;
1047 subtype Inet_Addr_V4_Type is Inet_Addr_VN_Type (1 .. 4);
1048 subtype Inet_Addr_V6_Type is Inet_Addr_VN_Type (1 .. 16);
1050 type Inet_Addr_Type (Family : Family_Type := Family_Inet) is record
1053 Sin_V4 : Inet_Addr_V4_Type := (others => 0);
1055 when Family_Inet6 =>
1056 Sin_V6 : Inet_Addr_V6_Type := (others => 0);
1060 Any_Port : constant Port_Type := 0;
1061 No_Port : constant Port_Type := 0;
1063 Any_Inet_Addr : constant Inet_Addr_Type := (Family_Inet, (others => 0));
1064 No_Inet_Addr : constant Inet_Addr_Type := (Family_Inet, (others => 0));
1066 No_Sock_Addr : constant Sock_Addr_Type := (Family_Inet, No_Inet_Addr, 0);
1068 Max_Name_Length : constant := 64;
1069 -- The constant MAXHOSTNAMELEN is usually set to 64
1071 subtype Name_Index is Natural range 1 .. Max_Name_Length;
1074 (Length : Name_Index := Max_Name_Length)
1076 Name : String (1 .. Length);
1078 -- We need fixed strings to avoid access types in host entry type
1080 type Name_Array is array (Natural range <>) of Name_Type;
1081 type Inet_Addr_Array is array (Natural range <>) of Inet_Addr_Type;
1083 type Host_Entry_Type (Aliases_Length, Addresses_Length : Natural) is record
1084 Official : Name_Type;
1085 Aliases : Name_Array (1 .. Aliases_Length);
1086 Addresses : Inet_Addr_Array (1 .. Addresses_Length);
1089 type Service_Entry_Type (Aliases_Length : Natural) is record
1090 Official : Name_Type;
1091 Aliases : Name_Array (1 .. Aliases_Length);
1093 Protocol : Name_Type;
1096 type Request_Flag_Type is mod 2 ** 8;
1097 No_Request_Flag : constant Request_Flag_Type := 0;
1098 Process_Out_Of_Band_Data : constant Request_Flag_Type := 1;
1099 Peek_At_Incoming_Data : constant Request_Flag_Type := 2;
1100 Wait_For_A_Full_Reception : constant Request_Flag_Type := 4;
1101 Send_End_Of_Record : constant Request_Flag_Type := 8;