1------------------------------------------------------------------------------ 2-- -- 3-- GNAT COMPILER COMPONENTS -- 4-- -- 5-- G N A T . S O C K E T S -- 6-- -- 7-- S p e c -- 8-- -- 9-- Copyright (C) 2001-2019, AdaCore -- 10-- -- 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 3, 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. -- 17-- -- 18-- As a special exception under Section 7 of GPL version 3, you are granted -- 19-- additional permissions described in the GCC Runtime Library Exception, -- 20-- version 3.1, as published by the Free Software Foundation. -- 21-- -- 22-- You should have received a copy of the GNU General Public License and -- 23-- a copy of the GCC Runtime Library Exception along with this program; -- 24-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- 25-- <http://www.gnu.org/licenses/>. -- 26-- -- 27-- GNAT was originally developed by the GNAT team at New York University. -- 28-- Extensive contributions were provided by Ada Core Technologies Inc. -- 29-- -- 30------------------------------------------------------------------------------ 31 32-- This package provides an interface to the sockets communication facility 33-- provided on many operating systems. This is implemented on the following 34-- platforms: 35 36-- All native ports, with restrictions as follows 37 38-- Multicast is available only on systems which provide support for this 39-- feature, so it is not available if Multicast is not supported, or not 40-- installed. 41 42-- VxWorks cross ports fully implement this package 43 44-- This package is not yet implemented on LynxOS or other cross ports 45 46with Ada.Exceptions; 47with Ada.Streams; 48with Ada.Strings.Unbounded; 49with Ada.Unchecked_Deallocation; 50 51with Interfaces.C; 52 53with System.OS_Constants; 54with System.Storage_Elements; 55 56package GNAT.Sockets is 57 58 -- Sockets are designed to provide a consistent communication facility 59 -- between applications. This package provides an Ada binding to the 60 -- de-facto standard BSD sockets API. The documentation below covers 61 -- only the specific binding provided by this package. It assumes that 62 -- the reader is already familiar with general network programming and 63 -- sockets usage. A useful reference on this matter is W. Richard Stevens' 64 -- "UNIX Network Programming: The Sockets Networking API" 65 -- (ISBN: 0131411551). 66 67 -- GNAT.Sockets has been designed with several ideas in mind 68 69 -- This is a system independent interface. Therefore, we try as much as 70 -- possible to mask system incompatibilities. Some functionalities are not 71 -- available because there are not fully supported on some systems. 72 73 -- This is a thick binding. For instance, a major effort has been done to 74 -- avoid using memory addresses or untyped ints. We preferred to define 75 -- streams and enumeration types. Errors are not returned as returned 76 -- values but as exceptions. 77 78 -- This package provides a POSIX-compliant interface (between two 79 -- different implementations of the same routine, we adopt the one closest 80 -- to the POSIX specification). For instance, using select(), the 81 -- notification of an asynchronous connect failure is delivered in the 82 -- write socket set (POSIX) instead of the exception socket set (NT). 83 84 -- The example below demonstrates various features of GNAT.Sockets: 85 86 -- with GNAT.Sockets; use GNAT.Sockets; 87 88 -- with Ada.Text_IO; 89 -- with Ada.Exceptions; use Ada.Exceptions; 90 91 -- procedure PingPong is 92 93 -- Group : constant String := "239.255.128.128"; 94 -- -- Multicast group: administratively scoped IP address 95 96 -- task Pong is 97 -- entry Start; 98 -- entry Stop; 99 -- end Pong; 100 101 -- task body Pong is 102 -- Address : Sock_Addr_Type; 103 -- Server : Socket_Type; 104 -- Socket : Socket_Type; 105 -- Channel : Stream_Access; 106 107 -- begin 108 -- -- Get an Internet address of a host (here the local host name). 109 -- -- Note that a host can have several addresses. Here we get 110 -- -- the first one which is supposed to be the official one. 111 112 -- Address.Addr := Addresses (Get_Host_By_Name (Host_Name), 1); 113 114 -- -- Get a socket address that is an Internet address and a port 115 116 -- Address.Port := 5876; 117 118 -- -- The first step is to create a socket. Once created, this 119 -- -- socket must be associated to with an address. Usually only a 120 -- -- server (Pong here) needs to bind an address explicitly. Most 121 -- -- of the time clients can skip this step because the socket 122 -- -- routines will bind an arbitrary address to an unbound socket. 123 124 -- Create_Socket (Server); 125 126 -- -- Allow reuse of local addresses 127 128 -- Set_Socket_Option 129 -- (Server, 130 -- Socket_Level, 131 -- (Reuse_Address, True)); 132 133 -- Bind_Socket (Server, Address); 134 135 -- -- A server marks a socket as willing to receive connect events 136 137 -- Listen_Socket (Server); 138 139 -- -- Once a server calls Listen_Socket, incoming connects events 140 -- -- can be accepted. The returned Socket is a new socket that 141 -- -- represents the server side of the connection. Server remains 142 -- -- available to receive further connections. 143 144 -- accept Start; 145 146 -- Accept_Socket (Server, Socket, Address); 147 148 -- -- Return a stream associated to the connected socket 149 150 -- Channel := Stream (Socket); 151 152 -- -- Force Pong to block 153 154 -- delay 0.2; 155 156 -- -- Receive and print message from client Ping 157 158 -- declare 159 -- Message : String := String'Input (Channel); 160 161 -- begin 162 -- Ada.Text_IO.Put_Line (Message); 163 164 -- -- Send same message back to client Ping 165 166 -- String'Output (Channel, Message); 167 -- end; 168 169 -- Close_Socket (Server); 170 -- Close_Socket (Socket); 171 172 -- -- Part of the multicast example 173 174 -- -- Create a datagram socket to send connectionless, unreliable 175 -- -- messages of a fixed maximum length. 176 177 -- Create_Socket (Socket, Family_Inet, Socket_Datagram); 178 179 -- -- Allow reuse of local addresses 180 181 -- Set_Socket_Option 182 -- (Socket, 183 -- Socket_Level, 184 -- (Reuse_Address, True)); 185 186 -- -- Controls the live time of the datagram to avoid it being 187 -- -- looped forever due to routing errors. Routers decrement 188 -- -- the TTL of every datagram as it traverses from one network 189 -- -- to another and when its value reaches 0 the packet is 190 -- -- dropped. Default is 1. 191 192 -- Set_Socket_Option 193 -- (Socket, 194 -- IP_Protocol_For_IP_Level, 195 -- (Multicast_TTL, 1)); 196 197 -- -- Want the data you send to be looped back to your host 198 199 -- Set_Socket_Option 200 -- (Socket, 201 -- IP_Protocol_For_IP_Level, 202 -- (Multicast_Loop, True)); 203 204 -- -- If this socket is intended to receive messages, bind it 205 -- -- to a given socket address. 206 207 -- Address.Addr := Any_Inet_Addr; 208 -- Address.Port := 55505; 209 210 -- Bind_Socket (Socket, Address); 211 212 -- -- Join a multicast group 213 214 -- -- Portability note: On Windows, this option may be set only 215 -- -- on a bound socket. 216 217 -- Set_Socket_Option 218 -- (Socket, 219 -- IP_Protocol_For_IP_Level, 220 -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr)); 221 222 -- -- If this socket is intended to send messages, provide the 223 -- -- receiver socket address. 224 225 -- Address.Addr := Inet_Addr (Group); 226 -- Address.Port := 55506; 227 228 -- Channel := Stream (Socket, Address); 229 230 -- -- Receive and print message from client Ping 231 232 -- declare 233 -- Message : String := String'Input (Channel); 234 235 -- begin 236 -- -- Get the address of the sender 237 238 -- Address := Get_Address (Channel); 239 -- Ada.Text_IO.Put_Line (Message & " from " & Image (Address)); 240 241 -- -- Send same message back to client Ping 242 243 -- String'Output (Channel, Message); 244 -- end; 245 246 -- Close_Socket (Socket); 247 248 -- accept Stop; 249 250 -- exception when E : others => 251 -- Ada.Text_IO.Put_Line 252 -- (Exception_Name (E) & ": " & Exception_Message (E)); 253 -- end Pong; 254 255 -- task Ping is 256 -- entry Start; 257 -- entry Stop; 258 -- end Ping; 259 260 -- task body Ping is 261 -- Address : Sock_Addr_Type; 262 -- Socket : Socket_Type; 263 -- Channel : Stream_Access; 264 265 -- begin 266 -- accept Start; 267 268 -- -- See comments in Ping section for the first steps 269 270 -- Address.Addr := Addresses (Get_Host_By_Name (Host_Name), 1); 271 -- Address.Port := 5876; 272 -- Create_Socket (Socket); 273 274 -- Set_Socket_Option 275 -- (Socket, 276 -- Socket_Level, 277 -- (Reuse_Address, True)); 278 279 -- -- Force Ping to block 280 281 -- delay 0.2; 282 283 -- -- If the client's socket is not bound, Connect_Socket will 284 -- -- bind to an unused address. The client uses Connect_Socket to 285 -- -- create a logical connection between the client's socket and 286 -- -- a server's socket returned by Accept_Socket. 287 288 -- Connect_Socket (Socket, Address); 289 290 -- Channel := Stream (Socket); 291 292 -- -- Send message to server Pong 293 294 -- String'Output (Channel, "Hello world"); 295 296 -- -- Force Ping to block 297 298 -- delay 0.2; 299 300 -- -- Receive and print message from server Pong 301 302 -- Ada.Text_IO.Put_Line (String'Input (Channel)); 303 -- Close_Socket (Socket); 304 305 -- -- Part of multicast example. Code similar to Pong's one 306 307 -- Create_Socket (Socket, Family_Inet, Socket_Datagram); 308 309 -- Set_Socket_Option 310 -- (Socket, 311 -- Socket_Level, 312 -- (Reuse_Address, True)); 313 314 -- Set_Socket_Option 315 -- (Socket, 316 -- IP_Protocol_For_IP_Level, 317 -- (Multicast_TTL, 1)); 318 319 -- Set_Socket_Option 320 -- (Socket, 321 -- IP_Protocol_For_IP_Level, 322 -- (Multicast_Loop, True)); 323 324 -- Address.Addr := Any_Inet_Addr; 325 -- Address.Port := 55506; 326 327 -- Bind_Socket (Socket, Address); 328 329 -- Set_Socket_Option 330 -- (Socket, 331 -- IP_Protocol_For_IP_Level, 332 -- (Add_Membership, Inet_Addr (Group), Any_Inet_Addr)); 333 334 -- Address.Addr := Inet_Addr (Group); 335 -- Address.Port := 55505; 336 337 -- Channel := Stream (Socket, Address); 338 339 -- -- Send message to server Pong 340 341 -- String'Output (Channel, "Hello world"); 342 343 -- -- Receive and print message from server Pong 344 345 -- declare 346 -- Message : String := String'Input (Channel); 347 348 -- begin 349 -- Address := Get_Address (Channel); 350 -- Ada.Text_IO.Put_Line (Message & " from " & Image (Address)); 351 -- end; 352 353 -- Close_Socket (Socket); 354 355 -- accept Stop; 356 357 -- exception when E : others => 358 -- Ada.Text_IO.Put_Line 359 -- (Exception_Name (E) & ": " & Exception_Message (E)); 360 -- end Ping; 361 362 -- begin 363 -- Initialize; 364 -- Ping.Start; 365 -- Pong.Start; 366 -- Ping.Stop; 367 -- Pong.Stop; 368 -- Finalize; 369 -- end PingPong; 370 371 package SOSC renames System.OS_Constants; 372 -- Renaming used to provide short-hand notations throughout the sockets 373 -- binding. Note that System.OS_Constants is an internal unit, and the 374 -- entities declared therein are not meant for direct access by users, 375 -- including through this renaming. 376 377 use type Interfaces.C.int; 378 -- Need visibility on "-" operator so that we can write -1 379 380 procedure Initialize; 381 pragma Obsolescent 382 (Entity => Initialize, 383 Message => "explicit initialization is no longer required"); 384 -- Initialize must be called before using any other socket routines. 385 -- Note that this operation is a no-op on UNIX platforms, but applications 386 -- should make sure to call it if portability is expected: some platforms 387 -- (such as Windows) require initialization before any socket operation. 388 -- This is now a no-op (initialization and finalization are done 389 -- automatically). 390 391 procedure Initialize (Process_Blocking_IO : Boolean); 392 pragma Obsolescent 393 (Entity => Initialize, 394 Message => "passing a parameter to Initialize is no longer supported"); 395 -- Previous versions of GNAT.Sockets used to require the user to indicate 396 -- whether socket I/O was process- or thread-blocking on the platform. 397 -- This property is now determined automatically when the run-time library 398 -- is built. The old version of Initialize, taking a parameter, is kept 399 -- for compatibility reasons, but this interface is obsolete (and if the 400 -- value given is wrong, an exception will be raised at run time). 401 -- This is now a no-op (initialization and finalization are done 402 -- automatically). 403 404 procedure Finalize; 405 pragma Obsolescent 406 (Entity => Finalize, 407 Message => "explicit finalization is no longer required"); 408 -- After Finalize is called it is not possible to use any routines 409 -- exported in by this package. This procedure is idempotent. 410 -- This is now a no-op (initialization and finalization are done 411 -- automatically). 412 413 type Socket_Type is private; 414 -- Sockets are used to implement a reliable bi-directional point-to-point, 415 -- stream-based connections between hosts. No_Socket provides a special 416 -- value to denote uninitialized sockets. 417 418 No_Socket : constant Socket_Type; 419 420 type Selector_Type is limited private; 421 type Selector_Access is access all Selector_Type; 422 -- Selector objects are used to wait for i/o events to occur on sockets 423 424 Null_Selector : constant Selector_Type; 425 -- The Null_Selector can be used in place of a normal selector without 426 -- having to call Create_Selector if the use of Abort_Selector is not 427 -- required. 428 429 -- Timeval_Duration is a subtype of Standard.Duration because the full 430 -- range of Standard.Duration cannot be represented in the equivalent C 431 -- structure (struct timeval). Moreover, negative values are not allowed 432 -- to avoid system incompatibilities. 433 434 Immediate : constant Duration := 0.0; 435 436 Forever : constant Duration := 437 Duration'Min 438 (Duration'Last, 439 (if SOSC."=" (SOSC.Target_OS, SOSC.Windows) 440 then Duration (2 ** 32 / 1000) 441 else 1.0 * SOSC.MAX_tv_sec)); 442 -- Largest possible Duration that is also a valid value for the OS type 443 -- used for socket timeout. 444 445 subtype Timeval_Duration is Duration range Immediate .. Forever; 446 447 subtype Selector_Duration is Timeval_Duration; 448 -- Timeout value for selector operations 449 450 type Selector_Status is (Completed, Expired, Aborted); 451 -- Completion status of a selector operation, indicated as follows: 452 -- Complete: one of the expected events occurred 453 -- Expired: no event occurred before the expiration of the timeout 454 -- Aborted: an external action cancelled the wait operation before 455 -- any event occurred. 456 457 Socket_Error : exception; 458 -- There is only one exception in this package to deal with an error during 459 -- a socket routine. Once raised, its message contains a string describing 460 -- the error code. 461 462 function Image (Socket : Socket_Type) return String; 463 -- Return a printable string for Socket 464 465 function To_Ada (Fd : Integer) return Socket_Type with Inline; 466 -- Convert a file descriptor to Socket_Type. This is useful when a socket 467 -- file descriptor is obtained from an external library call. 468 469 function To_C (Socket : Socket_Type) return Integer with Inline; 470 -- Return a file descriptor to be used by external subprograms. This is 471 -- useful for C functions that are not yet interfaced in this package. 472 473 type Family_Type is (Family_Inet, Family_Inet6, Family_Unix, Family_Unspec); 474 -- Address family (or protocol family) identifies the communication domain 475 -- and groups protocols with similar address formats. 476 -- The order of the enumeration elements should not be changed unilaterally 477 -- because the IPv6_TCP_Preferred routine rely on it. 478 479 subtype Family_Inet_4_6 is Family_Type range Family_Inet .. Family_Inet6; 480 481 type Mode_Type is (Socket_Stream, Socket_Datagram, Socket_Raw); 482 -- Stream sockets provide connection-oriented byte streams. Datagram 483 -- sockets support unreliable connectionless message-based communication. 484 -- Raw sockets provide raw network-protocol access. 485 -- The order of the enumeration elements should not be changed unilaterally 486 -- because the IPv6_TCP_Preferred routine relies on it. 487 488 type Shutmode_Type is (Shut_Read, Shut_Write, Shut_Read_Write); 489 -- When a process closes a socket, the policy is to retain any data queued 490 -- until either a delivery or a timeout expiration (in this case, the data 491 -- are discarded). Finer control is available through shutdown. With 492 -- Shut_Read, no more data can be received from the socket. With_Write, no 493 -- more data can be transmitted. Neither transmission nor reception can be 494 -- performed with Shut_Read_Write. 495 496 type Port_Type is range 0 .. 16#ffff#; 497 -- TCP/UDP port number 498 499 Any_Port : constant Port_Type; 500 -- All ports 501 502 No_Port : constant Port_Type; 503 -- Uninitialized port number 504 505 type Inet_Addr_Comp_Type is mod 2 ** 8; 506 -- Octet for Internet address 507 508 Inet_Addr_Bytes_Length : constant array (Family_Inet_4_6) of Natural := 509 (Family_Inet => 4, Family_Inet6 => 16); 510 511 type Inet_Addr_Bytes is array (Natural range <>) of Inet_Addr_Comp_Type; 512 513 subtype Inet_Addr_V4_Type is 514 Inet_Addr_Bytes (1 .. Inet_Addr_Bytes_Length (Family_Inet)); 515 subtype Inet_Addr_V6_Type is 516 Inet_Addr_Bytes (1 .. Inet_Addr_Bytes_Length (Family_Inet6)); 517 518 subtype Inet_Addr_VN_Type is Inet_Addr_Bytes; 519 -- For backwards compatibility 520 521 type Inet_Addr_Type (Family : Family_Inet_4_6 := Family_Inet) is record 522 case Family is 523 when Family_Inet => 524 Sin_V4 : Inet_Addr_V4_Type := (others => 0); 525 526 when Family_Inet6 => 527 Sin_V6 : Inet_Addr_V6_Type := (others => 0); 528 529 end case; 530 end record; 531 532 -- An Internet address depends on an address family (IPv4 contains 4 octets 533 -- and IPv6 contains 16 octets). 534 535 Any_Inet_Addr : constant Inet_Addr_Type; 536 -- Wildcard enabling all addresses to use with bind 537 538 Any_Inet6_Addr : constant Inet_Addr_Type; 539 -- Idem for IPV6 socket 540 541 No_Inet_Addr : constant Inet_Addr_Type; 542 -- Uninitialized inet address 543 544 Broadcast_Inet_Addr : constant Inet_Addr_Type; 545 -- Broadcast destination address in the current network 546 547 Loopback_Inet_Addr : constant Inet_Addr_Type; 548 -- Loopback address to the local host 549 550 Loopback_Inet6_Addr : constant Inet_Addr_Type; 551 -- IPv6 Loopback address to the local host 552 553 -- Useful constants for multicast addresses 554 555 Unspecified_Group_Inet_Addr : constant Inet_Addr_Type; 556 -- IPv4 multicast mask with prefix length 4 557 558 Unspecified_Group_Inet6_Addr : constant Inet_Addr_Type; 559 -- IPv6 multicast mask with prefix length 16 560 561 All_Hosts_Group_Inet_Addr : constant Inet_Addr_Type; 562 -- Multicast group addresses all hosts on the same network segment 563 564 All_Hosts_Group_Inet6_Addr : constant Inet_Addr_Type; 565 -- Idem for IPv6 protocol 566 567 All_Routers_Group_Inet_Addr : constant Inet_Addr_Type; 568 -- Multicast group addresses all routers on the same network segment 569 570 All_Routers_Group_Inet6_Addr : constant Inet_Addr_Type; 571 -- Idem for IPv6 protocol 572 573 IPv4_To_IPv6_Prefix : constant Inet_Addr_Bytes := 574 (1 .. 10 => 0, 11 .. 12 => 255); 575 -- Prefix for IPv4 mapped to IPv6 addresses 576 577 -- Functions to handle masks and prefixes 578 579 function Mask 580 (Family : Family_Inet_4_6; 581 Length : Natural; 582 Host : Boolean := False) return Inet_Addr_Type; 583 -- Return an address mask of the given family with the given prefix length. 584 -- If Host is False, this is a network mask (i.e. network bits are 1, 585 -- and host bits are 0); if Host is True, this is a host mask (i.e. 586 -- network bits are 0, and host bits are 1). 587 588 function "and" (Addr, Mask : Inet_Addr_Type) return Inet_Addr_Type; 589 function "or" (Net, Host : Inet_Addr_Type) return Inet_Addr_Type; 590 function "not" (Mask : Inet_Addr_Type) return Inet_Addr_Type; 591 -- Bit-wise operations on inet addresses (both operands must have the 592 -- same address family). 593 594 type Sock_Addr_Type (Family : Family_Type := Family_Inet) is record 595 case Family is 596 when Family_Unix => 597 Name : Ada.Strings.Unbounded.Unbounded_String; 598 when Family_Inet_4_6 => 599 Addr : Inet_Addr_Type (Family); 600 Port : Port_Type; 601 when Family_Unspec => 602 null; 603 end case; 604 end record; 605 pragma No_Component_Reordering (Sock_Addr_Type); 606 -- Socket addresses fully define a socket connection with protocol family, 607 -- an Internet address and a port. No_Sock_Addr provides a special value 608 -- for uninitialized socket addresses. 609 610 No_Sock_Addr : constant Sock_Addr_Type; 611 -- Uninitialized socket address 612 613 function Is_IPv4_Address (Name : String) return Boolean; 614 -- Return true when Name is an IPv4 address in dotted quad notation 615 616 function Is_IPv6_Address (Name : String) return Boolean; 617 -- Return true when Name is an IPv6 address in numeric format 618 619 function Image (Value : Inet_Addr_Type) return String; 620 -- Return an image of an Internet address. IPv4 notation consists in 4 621 -- octets in decimal format separated by dots. IPv6 notation consists in 622 -- 8 hextets in hexadecimal format separated by colons. 623 624 function Image (Value : Sock_Addr_Type) return String; 625 -- Return socket address image. Network socket address image will be with 626 -- a port image separated by a colon. 627 628 function Inet_Addr (Image : String) return Inet_Addr_Type; 629 -- Convert address image from numbers-dots-and-colons notation into an 630 -- inet address. 631 632 function Unix_Socket_Address (Addr : String) return Sock_Addr_Type; 633 -- Convert unix local socket name to Sock_Addr_Type 634 635 function Network_Socket_Address 636 (Addr : Inet_Addr_Type; Port : Port_Type) return Sock_Addr_Type; 637 -- Create network socket address 638 639 -- Host entries provide complete information on a given host: the official 640 -- name, an array of alternative names or aliases and array of network 641 -- addresses. 642 643 type Host_Entry_Type 644 (Aliases_Length, Addresses_Length : Natural) is private; 645 646 function Official_Name (E : Host_Entry_Type) return String; 647 -- Return official name in host entry 648 649 function Aliases_Length (E : Host_Entry_Type) return Natural; 650 -- Return number of aliases in host entry 651 652 function Addresses_Length (E : Host_Entry_Type) return Natural; 653 -- Return number of addresses in host entry 654 655 function Aliases 656 (E : Host_Entry_Type; 657 N : Positive := 1) return String; 658 -- Return N'th aliases in host entry. The first index is 1 659 660 function Addresses 661 (E : Host_Entry_Type; 662 N : Positive := 1) return Inet_Addr_Type; 663 -- Return N'th addresses in host entry. The first index is 1 664 665 Host_Error : exception; 666 -- Exception raised by the two following procedures. Once raised, its 667 -- message contains a string describing the error code. This exception is 668 -- raised when an host entry cannot be retrieved. 669 670 function Get_Host_By_Address 671 (Address : Inet_Addr_Type; 672 Family : Family_Type := Family_Inet) return Host_Entry_Type; 673 -- Return host entry structure for the given Inet address. Note that no 674 -- result will be returned if there is no mapping of this IP address to a 675 -- host name in the system tables (host database, DNS or otherwise). 676 677 function Get_Host_By_Name 678 (Name : String) return Host_Entry_Type; 679 -- Return host entry structure for the given host name. Here name is 680 -- either a host name, or an IP address. If Name is an IP address, this 681 -- is equivalent to Get_Host_By_Address (Inet_Addr (Name)). 682 683 function Host_Name return String; 684 -- Return the name of the current host 685 686 type Service_Entry_Type (Aliases_Length : Natural) is private; 687 -- Service entries provide complete information on a given service: the 688 -- official name, an array of alternative names or aliases and the port 689 -- number. 690 691 function Official_Name (S : Service_Entry_Type) return String; 692 -- Return official name in service entry 693 694 function Port_Number (S : Service_Entry_Type) return Port_Type; 695 -- Return port number in service entry 696 697 function Protocol_Name (S : Service_Entry_Type) return String; 698 -- Return Protocol in service entry (usually UDP or TCP) 699 700 function Aliases_Length (S : Service_Entry_Type) return Natural; 701 -- Return number of aliases in service entry 702 703 function Aliases 704 (S : Service_Entry_Type; 705 N : Positive := 1) return String; 706 -- Return N'th aliases in service entry (the first index is 1) 707 708 function Get_Service_By_Name 709 (Name : String; 710 Protocol : String) return Service_Entry_Type; 711 -- Return service entry structure for the given service name 712 713 function Get_Service_By_Port 714 (Port : Port_Type; 715 Protocol : String) return Service_Entry_Type; 716 -- Return service entry structure for the given service port number 717 718 Service_Error : exception; 719 -- Comment required ??? 720 721 -- Errors are described by an enumeration type. There is only one exception 722 -- Socket_Error in this package to deal with an error during a socket 723 -- routine. Once raised, its message contains the error code between 724 -- brackets and a string describing the error code. 725 726 -- The name of the enumeration constant documents the error condition 727 -- Note that on some platforms, a single error value is used for both 728 -- EWOULDBLOCK and EAGAIN. Both errors are therefore always reported as 729 -- Resource_Temporarily_Unavailable. 730 731 type Error_Type is 732 (Success, 733 Permission_Denied, 734 Address_Already_In_Use, 735 Cannot_Assign_Requested_Address, 736 Address_Family_Not_Supported_By_Protocol, 737 Operation_Already_In_Progress, 738 Bad_File_Descriptor, 739 Software_Caused_Connection_Abort, 740 Connection_Refused, 741 Connection_Reset_By_Peer, 742 Destination_Address_Required, 743 Bad_Address, 744 Host_Is_Down, 745 No_Route_To_Host, 746 Operation_Now_In_Progress, 747 Interrupted_System_Call, 748 Invalid_Argument, 749 Input_Output_Error, 750 Transport_Endpoint_Already_Connected, 751 Too_Many_Symbolic_Links, 752 Too_Many_Open_Files, 753 Message_Too_Long, 754 File_Name_Too_Long, 755 Network_Is_Down, 756 Network_Dropped_Connection_Because_Of_Reset, 757 Network_Is_Unreachable, 758 No_Buffer_Space_Available, 759 Protocol_Not_Available, 760 Transport_Endpoint_Not_Connected, 761 Socket_Operation_On_Non_Socket, 762 Operation_Not_Supported, 763 Protocol_Family_Not_Supported, 764 Protocol_Not_Supported, 765 Protocol_Wrong_Type_For_Socket, 766 Cannot_Send_After_Transport_Endpoint_Shutdown, 767 Socket_Type_Not_Supported, 768 Connection_Timed_Out, 769 Too_Many_References, 770 Resource_Temporarily_Unavailable, 771 Broken_Pipe, 772 Unknown_Host, 773 Host_Name_Lookup_Failure, 774 Non_Recoverable_Error, 775 Unknown_Server_Error, 776 Cannot_Resolve_Error); 777 778 -- Get_Socket_Options and Set_Socket_Options manipulate options associated 779 -- with a socket. Options may exist at multiple protocol levels in the 780 -- communication stack. Socket_Level is the uppermost socket level. 781 782 type Level_Type is 783 (Socket_Level, 784 IP_Protocol_For_IP_Level, 785 IP_Protocol_For_IPv6_Level, 786 IP_Protocol_For_UDP_Level, 787 IP_Protocol_For_TCP_Level, 788 IP_Protocol_For_ICMP_Level, 789 IP_Protocol_For_IGMP_Level, 790 IP_Protocol_For_RAW_Level); 791 792 -- There are several options available to manipulate sockets. Each option 793 -- has a name and several values available. Most of the time, the value 794 -- is a boolean to enable or disable this option. Each socket option is 795 -- provided with an appropriate C name taken from the sockets API comments. 796 -- The C name can be used to find a detailed description in the OS-specific 797 -- documentation. The options are grouped by main Level_Type value, which 798 -- can be used together with this option in calls to the Set_Socket_Option 799 -- and Get_Socket_Option routines. Note that some options can be used with 800 -- more than one level. 801 802 type Option_Name is 803 (Generic_Option, 804 -- Can be used to set/get any socket option via an OS-specific option 805 -- code with an integer value. 806 807 ------------------ 808 -- Socket_Level -- 809 ------------------ 810 811 Keep_Alive, -- SO_KEEPALIVE 812 -- Enable sending of keep-alive messages on connection-oriented sockets 813 814 Reuse_Address, -- SO_REUSEADDR 815 -- Enable binding to an address and port already in use 816 817 Broadcast, -- SO_BROADCAST 818 -- Enable sending broadcast datagrams on the socket 819 820 Send_Buffer, -- SO_SNDBUF 821 -- Set/get the maximum socket send buffer in bytes 822 823 Receive_Buffer, -- SO_RCVBUF 824 -- Set/get the maximum socket receive buffer in bytes 825 826 Linger, -- SO_LINGER 827 -- When enabled, a Close_Socket or Shutdown_Socket will wait until all 828 -- queued messages for the socket have been successfully sent or the 829 -- linger timeout has been reached. 830 831 Error, -- SO_ERROR 832 -- Get and clear the pending socket error integer code 833 834 Send_Timeout, -- SO_SNDTIMEO 835 -- Specify sending timeout until reporting an error 836 837 Receive_Timeout, -- SO_RCVTIMEO 838 -- Specify receiving timeout until reporting an error 839 840 Busy_Polling, -- SO_BUSY_POLL 841 -- Sets the approximate time in microseconds to busy poll on a blocking 842 -- receive when there is no data. 843 844 ------------------------------- 845 -- IP_Protocol_For_TCP_Level -- 846 ------------------------------- 847 848 No_Delay, -- TCP_NODELAY 849 -- Disable the Nagle algorithm. This means that output buffer content 850 -- is always sent as soon as possible, even if there is only a small 851 -- amount of data. 852 853 ------------------------------ 854 -- IP_Protocol_For_IP_Level -- 855 ------------------------------ 856 857 Add_Membership_V4, -- IP_ADD_MEMBERSHIP 858 -- Join a multicast group 859 860 Drop_Membership_V4, -- IP_DROP_MEMBERSHIP 861 -- Leave a multicast group 862 863 Multicast_If_V4, -- IP_MULTICAST_IF 864 -- Set/Get outgoing interface for sending multicast packets 865 866 Multicast_Loop_V4, -- IP_MULTICAST_LOOP 867 -- This boolean option determines whether sent multicast packets should 868 -- be looped back to the local sockets. 869 870 Multicast_TTL, -- IP_MULTICAST_TTL 871 -- Set/Get the time-to-live of sent multicast packets 872 873 Receive_Packet_Info, -- IP_PKTINFO 874 -- Receive low-level packet info as ancillary data 875 876 -------------------------------- 877 -- IP_Protocol_For_IPv6_Level -- 878 -------------------------------- 879 880 Add_Membership_V6, -- IPV6_ADD_MEMBERSHIP 881 -- Join IPv6 multicast group 882 883 Drop_Membership_V6, -- IPV6_DROP_MEMBERSHIP 884 -- Leave IPv6 multicast group 885 886 Multicast_If_V6, -- IPV6_MULTICAST_IF 887 -- Set/Get outgoing interface index for sending multicast packets 888 889 Multicast_Loop_V6, -- IPV6_MULTICAST_LOOP 890 -- This boolean option determines whether sent multicast IPv6 packets 891 -- should be looped back to the local sockets. 892 893 IPv6_Only, -- IPV6_V6ONLY 894 -- Restricted to IPv6 communications only 895 896 Multicast_Hops -- IPV6_MULTICAST_HOPS 897 -- Set the multicast hop limit for the IPv6 socket 898 ); 899 900 subtype Specific_Option_Name is 901 Option_Name range Keep_Alive .. Option_Name'Last; 902 903 Add_Membership : Option_Name renames Add_Membership_V4; 904 Drop_Membership : Option_Name renames Drop_Membership_V4; 905 Multicast_If : Option_Name renames Multicast_If_V4; 906 Multicast_Loop : Option_Name renames Multicast_Loop_V4; 907 908 type Option_Type (Name : Option_Name := Keep_Alive) is record 909 case Name is 910 when Generic_Option => 911 Optname : Interfaces.C.int := -1; 912 Optval : Interfaces.C.int; 913 914 when Keep_Alive | 915 Reuse_Address | 916 Broadcast | 917 Linger | 918 No_Delay | 919 Receive_Packet_Info | 920 IPv6_Only | 921 Multicast_Loop_V4 | 922 Multicast_Loop_V6 => 923 Enabled : Boolean; 924 925 case Name is 926 when Linger => 927 Seconds : Natural; 928 when others => 929 null; 930 end case; 931 932 when Busy_Polling => 933 Microseconds : Natural; 934 935 when Send_Buffer | 936 Receive_Buffer => 937 Size : Natural; 938 939 when Error => 940 Error : Error_Type; 941 942 when Add_Membership_V4 | 943 Add_Membership_V6 | 944 Drop_Membership_V4 | 945 Drop_Membership_V6 => 946 Multicast_Address : Inet_Addr_Type; 947 case Name is 948 when Add_Membership_V4 | 949 Drop_Membership_V4 => 950 Local_Interface : Inet_Addr_Type; 951 when others => 952 Interface_Index : Natural; 953 end case; 954 955 when Multicast_If_V4 => 956 Outgoing_If : Inet_Addr_Type; 957 958 when Multicast_If_V6 => 959 Outgoing_If_Index : Natural; 960 961 when Multicast_TTL => 962 Time_To_Live : Natural; 963 964 when Multicast_Hops => 965 Hop_Limit : Integer range -1 .. 255; 966 967 when Send_Timeout | 968 Receive_Timeout => 969 Timeout : Timeval_Duration; 970 971 end case; 972 end record; 973 974 -- There are several controls available to manipulate sockets. Each option 975 -- has a name and several values available. These controls differ from the 976 -- socket options in that they are not specific to sockets but are 977 -- available for any device. 978 979 type Request_Name is 980 (Non_Blocking_IO, -- Cause a caller not to wait on blocking operations 981 N_Bytes_To_Read); -- Return the number of bytes available to read 982 983 type Request_Type (Name : Request_Name := Non_Blocking_IO) is record 984 case Name is 985 when Non_Blocking_IO => 986 Enabled : Boolean; 987 988 when N_Bytes_To_Read => 989 Size : Natural; 990 991 end case; 992 end record; 993 994 -- A request flag allows specification of the type of message transmissions 995 -- or receptions. A request flag can be combination of zero or more 996 -- predefined request flags. 997 998 type Request_Flag_Type is private; 999 1000 No_Request_Flag : constant Request_Flag_Type; 1001 -- This flag corresponds to the normal execution of an operation 1002 1003 Process_Out_Of_Band_Data : constant Request_Flag_Type; 1004 -- This flag requests that the receive or send function operates on 1005 -- out-of-band data when the socket supports this notion (e.g. 1006 -- Socket_Stream). 1007 1008 Peek_At_Incoming_Data : constant Request_Flag_Type; 1009 -- This flag causes the receive operation to return data from the beginning 1010 -- of the receive queue without removing that data from the queue. A 1011 -- subsequent receive call will return the same data. 1012 1013 Wait_For_A_Full_Reception : constant Request_Flag_Type; 1014 -- This flag requests that the operation block until the full request is 1015 -- satisfied. However, the call may still return less data than requested 1016 -- if a signal is caught, an error or disconnect occurs, or the next data 1017 -- to be received is of a different type than that returned. Note that 1018 -- this flag depends on support in the underlying sockets implementation, 1019 -- and is not supported under Windows. 1020 1021 Send_End_Of_Record : constant Request_Flag_Type; 1022 -- This flag indicates that the entire message has been sent and so this 1023 -- terminates the record. 1024 1025 function "+" (L, R : Request_Flag_Type) return Request_Flag_Type; 1026 -- Combine flag L with flag R 1027 1028 type Stream_Element_Reference is access all Ada.Streams.Stream_Element; 1029 1030 type Vector_Element is record 1031 Base : Stream_Element_Reference; 1032 Length : Interfaces.C.size_t; 1033 end record; 1034 1035 type Vector_Type is array (Integer range <>) of Vector_Element; 1036 1037 type Address_Info is record 1038 Addr : Sock_Addr_Type; 1039 Mode : Mode_Type := Socket_Stream; 1040 Level : Level_Type := IP_Protocol_For_IP_Level; 1041 end record; 1042 1043 type Address_Info_Array is array (Positive range <>) of Address_Info; 1044 1045 function Get_Address_Info 1046 (Host : String; 1047 Service : String; 1048 Family : Family_Type := Family_Unspec; 1049 Mode : Mode_Type := Socket_Stream; 1050 Level : Level_Type := IP_Protocol_For_IP_Level; 1051 Numeric_Host : Boolean := False; 1052 Passive : Boolean := False; 1053 Unknown : access procedure 1054 (Family, Mode, Level, Length : Integer) := null) 1055 return Address_Info_Array; 1056 -- Returns available addresses for the Host and Service names. 1057 -- If Family is Family_Unspec, all available protocol families returned. 1058 -- Service is the name of service as defined in /etc/services or port 1059 -- number in string representation. 1060 -- If Unknown procedure access specified it will be called in case of 1061 -- unknown family found. 1062 -- Numeric_Host flag suppresses any potentially lengthy network host 1063 -- address lookups, and Host have to represent numerical network address in 1064 -- this case. 1065 -- If Passive is True and Host is empty then the returned socket addresses 1066 -- will be suitable for binding a socket that will accept connections. 1067 -- The returned socket address will contain the "wildcard address". 1068 -- The wildcard address is used by applications (typically servers) that 1069 -- intend to accept connections on any of the hosts's network addresses. 1070 -- If Host is not empty, then the Passive flag is ignored. 1071 -- If Passive is False, then the returned socket addresses will be suitable 1072 -- for use with connect, sendto, or sendmsg. If Host is empty, then the 1073 -- network address will be set to the loopback interface address; 1074 -- this is used by applications that intend to communicate with peers 1075 -- running on the same host. 1076 1077 procedure Sort 1078 (Addr_Info : in out Address_Info_Array; 1079 Compare : access function (Left, Right : Address_Info) return Boolean); 1080 -- Sort address info array in order defined by compare function 1081 1082 function IPv6_TCP_Preferred (Left, Right : Address_Info) return Boolean; 1083 -- To use with Sort to order where IPv6 and TCP addresses first 1084 1085 type Host_Service (Host_Length, Service_Length : Natural) is record 1086 Host : String (1 .. Host_Length); 1087 Service : String (1 .. Service_Length); 1088 end record; 1089 1090 function Get_Name_Info 1091 (Addr : Sock_Addr_Type; 1092 Numeric_Host : Boolean := False; 1093 Numeric_Serv : Boolean := False) return Host_Service; 1094 -- Returns host and service names by the address and port. 1095 -- If Numeric_Host is True, then the numeric form of the hostname is 1096 -- returned. When Numeric_Host is False, this will still happen in case the 1097 -- host name cannot be determined. 1098 -- If Numenric_Serv is True, then the numeric form of the service address 1099 -- (port number) is returned. When Numenric_Serv is False, this will still 1100 -- happen in case the service's name cannot be determined. 1101 1102 procedure Create_Socket 1103 (Socket : out Socket_Type; 1104 Family : Family_Type := Family_Inet; 1105 Mode : Mode_Type := Socket_Stream; 1106 Level : Level_Type := IP_Protocol_For_IP_Level); 1107 -- Create an endpoint for communication. Raises Socket_Error on error. 1108 1109 procedure Create_Socket_Pair 1110 (Left : out Socket_Type; 1111 Right : out Socket_Type; 1112 Family : Family_Type := Family_Unspec; 1113 Mode : Mode_Type := Socket_Stream; 1114 Level : Level_Type := IP_Protocol_For_IP_Level); 1115 -- Create two connected sockets. Raises Socket_Error on error. 1116 -- If Family is unspecified, it creates Family_Unix sockets on UNIX and 1117 -- Family_Inet sockets on non UNIX platforms. 1118 1119 procedure Accept_Socket 1120 (Server : Socket_Type; 1121 Socket : out Socket_Type; 1122 Address : out Sock_Addr_Type); 1123 -- Extracts the first connection request on the queue of pending 1124 -- connections, creates a new connected socket with mostly the same 1125 -- properties as Server, and allocates a new socket. The returned Address 1126 -- is filled in with the address of the connection. Raises Socket_Error on 1127 -- error. Note: if Server is a non-blocking socket, whether or not this 1128 -- aspect is inherited by Socket is platform-dependent. 1129 1130 procedure Accept_Socket 1131 (Server : Socket_Type; 1132 Socket : out Socket_Type; 1133 Address : out Sock_Addr_Type; 1134 Timeout : Selector_Duration; 1135 Selector : access Selector_Type := null; 1136 Status : out Selector_Status); 1137 -- Accept a new connection on Server using Accept_Socket, waiting no longer 1138 -- than the given timeout duration. Status is set to indicate whether the 1139 -- operation completed successfully, timed out, or was aborted. If Selector 1140 -- is not null, the designated selector is used to wait for the socket to 1141 -- become available, else a private selector object is created by this 1142 -- procedure and destroyed before it returns. 1143 1144 procedure Bind_Socket 1145 (Socket : Socket_Type; 1146 Address : Sock_Addr_Type); 1147 -- Once a socket is created, assign a local address to it. Raise 1148 -- Socket_Error on error. 1149 1150 procedure Close_Socket (Socket : Socket_Type); 1151 -- Close a socket and more specifically a non-connected socket 1152 1153 procedure Connect_Socket 1154 (Socket : Socket_Type; 1155 Server : Sock_Addr_Type); 1156 -- Make a connection to another socket which has the address of Server. 1157 -- Raises Socket_Error on error. 1158 1159 procedure Connect_Socket 1160 (Socket : Socket_Type; 1161 Server : Sock_Addr_Type; 1162 Timeout : Selector_Duration; 1163 Selector : access Selector_Type := null; 1164 Status : out Selector_Status); 1165 -- Connect Socket to the given Server address using Connect_Socket, waiting 1166 -- no longer than the given timeout duration. Status is set to indicate 1167 -- whether the operation completed successfully, timed out, or was aborted. 1168 -- If Selector is not null, the designated selector is used to wait for the 1169 -- socket to become available, else a private selector object is created 1170 -- by this procedure and destroyed before it returns. If Timeout is 0.0, 1171 -- no attempt is made to detect whether the connection has succeeded; it 1172 -- is up to the user to determine this using Check_Selector later on. 1173 1174 procedure Control_Socket 1175 (Socket : Socket_Type; 1176 Request : in out Request_Type); 1177 -- Obtain or set parameter values that control the socket. This control 1178 -- differs from the socket options in that they are not specific to sockets 1179 -- but are available for any device. 1180 1181 function Get_Peer_Name (Socket : Socket_Type) return Sock_Addr_Type; 1182 -- Return the peer or remote socket address of a socket. Raise 1183 -- Socket_Error on error. 1184 1185 function Get_Socket_Name (Socket : Socket_Type) return Sock_Addr_Type; 1186 -- Return the local or current socket address of a socket. Return 1187 -- No_Sock_Addr on error (e.g. socket closed or not locally bound). 1188 1189 function Get_Socket_Option 1190 (Socket : Socket_Type; 1191 Level : Level_Type; 1192 Name : Option_Name; 1193 Optname : Interfaces.C.int := -1) return Option_Type; 1194 -- Get the options associated with a socket. Raises Socket_Error on error. 1195 -- Optname identifies specific option when Name is Generic_Option. 1196 1197 procedure Listen_Socket 1198 (Socket : Socket_Type; 1199 Length : Natural := 15); 1200 -- To accept connections, a socket is first created with Create_Socket, 1201 -- a willingness to accept incoming connections and a queue Length for 1202 -- incoming connections are specified. Raise Socket_Error on error. 1203 -- The queue length of 15 is an example value that should be appropriate 1204 -- in usual cases. It can be adjusted according to each application's 1205 -- particular requirements. 1206 1207 procedure Receive_Socket 1208 (Socket : Socket_Type; 1209 Item : out Ada.Streams.Stream_Element_Array; 1210 Last : out Ada.Streams.Stream_Element_Offset; 1211 Flags : Request_Flag_Type := No_Request_Flag); 1212 -- Receive message from Socket. Last is the index value such that Item 1213 -- (Last) is the last character assigned. Note that Last is set to 1214 -- Item'First - 1 when the socket has been closed by peer. This is not 1215 -- an error, and no exception is raised in this case unless Item'First 1216 -- is Stream_Element_Offset'First, in which case Constraint_Error is 1217 -- raised. Flags allows control of the reception. Raise Socket_Error on 1218 -- error. 1219 1220 procedure Receive_Socket 1221 (Socket : Socket_Type; 1222 Item : out Ada.Streams.Stream_Element_Array; 1223 Last : out Ada.Streams.Stream_Element_Offset; 1224 From : out Sock_Addr_Type; 1225 Flags : Request_Flag_Type := No_Request_Flag); 1226 -- Receive message from Socket. If Socket is not connection-oriented, the 1227 -- source address From of the message is filled in. Last is the index 1228 -- value such that Item (Last) is the last character assigned. Flags 1229 -- allows control of the reception. Raises Socket_Error on error. 1230 1231 procedure Receive_Vector 1232 (Socket : Socket_Type; 1233 Vector : Vector_Type; 1234 Count : out Ada.Streams.Stream_Element_Count; 1235 Flags : Request_Flag_Type := No_Request_Flag); 1236 -- Receive data from a socket and scatter it into the set of vector 1237 -- elements Vector. Count is set to the count of received stream elements. 1238 -- Flags allow control over reception. 1239 1240 function Resolve_Exception 1241 (Occurrence : Ada.Exceptions.Exception_Occurrence) return Error_Type; 1242 -- When Socket_Error or Host_Error are raised, the exception message 1243 -- contains the error code between brackets and a string describing the 1244 -- error code. Resolve_Error extracts the error code from an exception 1245 -- message and translate it into an enumeration value. 1246 1247 procedure Send_Socket 1248 (Socket : Socket_Type; 1249 Item : Ada.Streams.Stream_Element_Array; 1250 Last : out Ada.Streams.Stream_Element_Offset; 1251 To : access Sock_Addr_Type; 1252 Flags : Request_Flag_Type := No_Request_Flag); 1253 pragma Inline (Send_Socket); 1254 -- Transmit a message over a socket. For a datagram socket, the address 1255 -- is given by To.all. For a stream socket, To must be null. Last 1256 -- is the index value such that Item (Last) is the last character 1257 -- sent. Note that Last is set to Item'First - 1 if the socket has been 1258 -- closed by the peer (unless Item'First is Stream_Element_Offset'First, 1259 -- in which case Constraint_Error is raised instead). This is not an error, 1260 -- and Socket_Error is not raised in that case. Flags allows control of the 1261 -- transmission. Raises exception Socket_Error on error. Note: this 1262 -- subprogram is inlined because it is also used to implement the two 1263 -- variants below. 1264 1265 procedure Send_Socket 1266 (Socket : Socket_Type; 1267 Item : Ada.Streams.Stream_Element_Array; 1268 Last : out Ada.Streams.Stream_Element_Offset; 1269 Flags : Request_Flag_Type := No_Request_Flag); 1270 -- Transmit a message over a socket. Upon return, Last is set to the index 1271 -- within Item of the last element transmitted. Flags allows control of 1272 -- the transmission. Raises Socket_Error on any detected error condition. 1273 1274 procedure Send_Socket 1275 (Socket : Socket_Type; 1276 Item : Ada.Streams.Stream_Element_Array; 1277 Last : out Ada.Streams.Stream_Element_Offset; 1278 To : Sock_Addr_Type; 1279 Flags : Request_Flag_Type := No_Request_Flag); 1280 -- Transmit a message over a datagram socket. The destination address is 1281 -- To. Flags allows control of the transmission. Raises Socket_Error on 1282 -- error. 1283 1284 procedure Send_Vector 1285 (Socket : Socket_Type; 1286 Vector : Vector_Type; 1287 Count : out Ada.Streams.Stream_Element_Count; 1288 Flags : Request_Flag_Type := No_Request_Flag); 1289 -- Transmit data gathered from the set of vector elements Vector to a 1290 -- socket. Count is set to the count of transmitted stream elements. Flags 1291 -- allow control over transmission. 1292 1293 procedure Set_Close_On_Exec 1294 (Socket : Socket_Type; 1295 Close_On_Exec : Boolean; 1296 Status : out Boolean); 1297 -- When Close_On_Exec is True, mark Socket to be closed automatically when 1298 -- a new program is executed by the calling process (i.e. prevent Socket 1299 -- from being inherited by child processes). When Close_On_Exec is False, 1300 -- mark Socket to not be closed on exec (i.e. allow it to be inherited). 1301 -- Status is False if the operation could not be performed, or is not 1302 -- supported on the target platform. 1303 1304 procedure Set_Socket_Option 1305 (Socket : Socket_Type; 1306 Level : Level_Type; 1307 Option : Option_Type); 1308 -- Manipulate socket options. Raises Socket_Error on error 1309 1310 procedure Shutdown_Socket 1311 (Socket : Socket_Type; 1312 How : Shutmode_Type := Shut_Read_Write); 1313 -- Shutdown a connected socket. If How is Shut_Read further receives will 1314 -- be disallowed. If How is Shut_Write further sends will be disallowed. 1315 -- If How is Shut_Read_Write further sends and receives will be disallowed. 1316 1317 type Stream_Access is access all Ada.Streams.Root_Stream_Type'Class; 1318 -- Same interface as Ada.Streams.Stream_IO 1319 1320 function Stream (Socket : Socket_Type) return Stream_Access; 1321 -- Create a stream associated with a connected stream-based socket. 1322 -- Note: keep in mind that the default stream attributes for composite 1323 -- types perform separate Read/Write operations for each component, 1324 -- recursively. If performance is an issue, you may want to consider 1325 -- introducing a buffering stage. 1326 1327 function Stream 1328 (Socket : Socket_Type; 1329 Send_To : Sock_Addr_Type) return Stream_Access; 1330 -- Create a stream associated with an already bound datagram-based socket. 1331 -- Send_To is the destination address to which messages are being sent. 1332 1333 function Get_Address 1334 (Stream : not null Stream_Access) return Sock_Addr_Type; 1335 -- Return the socket address from which the last message was received 1336 1337 procedure Free is new Ada.Unchecked_Deallocation 1338 (Ada.Streams.Root_Stream_Type'Class, Stream_Access); 1339 -- Destroy a stream created by one of the Stream functions above, releasing 1340 -- the corresponding resources. The user is responsible for calling this 1341 -- subprogram when the stream is not needed anymore. 1342 1343 type Socket_Set_Type is limited private; 1344 -- This type allows manipulation of sets of sockets. It allows waiting 1345 -- for events on multiple endpoints at one time. This type has default 1346 -- initialization, and the default value is the empty set. 1347 -- 1348 -- Note: This type used to contain a pointer to dynamically allocated 1349 -- storage, but this is not the case anymore, and no special precautions 1350 -- are required to avoid memory leaks. 1351 1352 procedure Clear (Item : in out Socket_Set_Type; Socket : Socket_Type); 1353 -- Remove Socket from Item 1354 1355 procedure Copy (Source : Socket_Set_Type; Target : out Socket_Set_Type); 1356 -- Copy Source into Target as Socket_Set_Type is limited private 1357 1358 procedure Empty (Item : out Socket_Set_Type); 1359 -- Remove all Sockets from Item 1360 1361 procedure Get (Item : in out Socket_Set_Type; Socket : out Socket_Type); 1362 -- Extract a Socket from socket set Item. Socket is set to 1363 -- No_Socket when the set is empty. 1364 1365 function Is_Empty (Item : Socket_Set_Type) return Boolean; 1366 -- Return True iff Item is empty 1367 1368 function Is_Set 1369 (Item : Socket_Set_Type; 1370 Socket : Socket_Type) return Boolean; 1371 -- Return True iff Socket is present in Item 1372 1373 procedure Set (Item : in out Socket_Set_Type; Socket : Socket_Type); 1374 -- Insert Socket into Item 1375 1376 function Image (Item : Socket_Set_Type) return String; 1377 -- Return a printable image of Item, for debugging purposes 1378 1379 -- The select(2) system call waits for events to occur on any of a set of 1380 -- file descriptors. Usually, three independent sets of descriptors are 1381 -- watched (read, write and exception). A timeout gives an upper bound 1382 -- on the amount of time elapsed before select returns. This function 1383 -- blocks until an event occurs. On some platforms, the select(2) system 1384 -- can block the full process (not just the calling thread). 1385 -- 1386 -- Check_Selector provides the very same behavior. The only difference is 1387 -- that it does not watch for exception events. Note that on some platforms 1388 -- it is kept process blocking on purpose. The timeout parameter allows the 1389 -- user to have the behavior he wants. Abort_Selector allows the safe 1390 -- abort of a blocked Check_Selector call. A special socket is opened by 1391 -- Create_Selector and included in each call to Check_Selector. 1392 -- 1393 -- Abort_Selector causes an event to occur on this descriptor in order to 1394 -- unblock Check_Selector. Note that each call to Abort_Selector will cause 1395 -- exactly one call to Check_Selector to return with Aborted status. The 1396 -- special socket created by Create_Selector is closed when Close_Selector 1397 -- is called. 1398 -- 1399 -- A typical case where it is useful to abort a Check_Selector operation is 1400 -- the situation where a change to the monitored sockets set must be made. 1401 1402 procedure Create_Selector (Selector : out Selector_Type); 1403 -- Initialize (open) a new selector 1404 1405 procedure Close_Selector (Selector : in out Selector_Type); 1406 -- Close Selector and all internal descriptors associated; deallocate any 1407 -- associated resources. This subprogram may be called only when there is 1408 -- no other task still using Selector (i.e. still executing Check_Selector 1409 -- or Abort_Selector on this Selector). Has no effect if Selector is 1410 -- already closed. 1411 1412 procedure Check_Selector 1413 (Selector : Selector_Type; 1414 R_Socket_Set : in out Socket_Set_Type; 1415 W_Socket_Set : in out Socket_Set_Type; 1416 Status : out Selector_Status; 1417 Timeout : Selector_Duration := Forever); 1418 -- Return when one Socket in R_Socket_Set has some data to be read or if 1419 -- one Socket in W_Socket_Set is ready to transmit some data. In these 1420 -- cases Status is set to Completed and sockets that are ready are set in 1421 -- R_Socket_Set or W_Socket_Set. Status is set to Expired if no socket was 1422 -- ready after a Timeout expiration. Status is set to Aborted if an abort 1423 -- signal has been received while checking socket status. 1424 -- 1425 -- Note that two different Socket_Set_Type objects must be passed as 1426 -- R_Socket_Set and W_Socket_Set (even if they denote the same set of 1427 -- Sockets), or some event may be lost. Also keep in mind that this 1428 -- procedure modifies the passed socket sets to indicate which sockets 1429 -- actually had events upon return. The socket set therefore has to 1430 -- be reset by the caller for further calls. 1431 -- 1432 -- Socket_Error is raised when the select(2) system call returns an error 1433 -- condition, or when a read error occurs on the signalling socket used for 1434 -- the implementation of Abort_Selector. 1435 1436 procedure Check_Selector 1437 (Selector : Selector_Type; 1438 R_Socket_Set : in out Socket_Set_Type; 1439 W_Socket_Set : in out Socket_Set_Type; 1440 E_Socket_Set : in out Socket_Set_Type; 1441 Status : out Selector_Status; 1442 Timeout : Selector_Duration := Forever); 1443 -- This refined version of Check_Selector allows watching for exception 1444 -- events (i.e. notifications of out-of-band transmission and reception). 1445 -- As above, all of R_Socket_Set, W_Socket_Set and E_Socket_Set must be 1446 -- different objects. 1447 1448 procedure Abort_Selector (Selector : Selector_Type); 1449 -- Send an abort signal to the selector. The Selector may not be the 1450 -- Null_Selector. 1451 1452 type Fd_Set is private; 1453 -- ??? This type must not be used directly, it needs to be visible because 1454 -- it is used in the visible part of GNAT.Sockets.Thin_Common. This is 1455 -- really an inversion of abstraction. The private part of GNAT.Sockets 1456 -- needs to have visibility on this type, but since Thin_Common is a child 1457 -- of Sockets, the type can't be declared there. The correct fix would 1458 -- be to move the thin sockets binding outside of GNAT.Sockets altogether, 1459 -- e.g. by renaming it to GNAT.Sockets_Thin. 1460 1461private 1462 1463 package ASU renames Ada.Strings.Unbounded; 1464 1465 type Socket_Type is new Integer; 1466 No_Socket : constant Socket_Type := -1; 1467 1468 -- A selector is either a null selector, which is always "open" and can 1469 -- never be aborted, or a regular selector, which is created "closed", 1470 -- becomes "open" when Create_Selector is called, and "closed" again when 1471 -- Close_Selector is called. 1472 1473 type Selector_Type (Is_Null : Boolean := False) is limited record 1474 case Is_Null is 1475 when True => 1476 null; 1477 1478 when False => 1479 R_Sig_Socket : Socket_Type := No_Socket; 1480 W_Sig_Socket : Socket_Type := No_Socket; 1481 -- Signalling sockets used to abort a select operation 1482 end case; 1483 end record; 1484 1485 pragma Volatile (Selector_Type); 1486 1487 Null_Selector : constant Selector_Type := (Is_Null => True); 1488 1489 type Fd_Set is 1490 new System.Storage_Elements.Storage_Array (1 .. SOSC.SIZEOF_fd_set); 1491 for Fd_Set'Alignment use Interfaces.C.long'Alignment; 1492 -- Set conservative alignment so that our Fd_Sets are always adequately 1493 -- aligned for the underlying data type (which is implementation defined 1494 -- and may be an array of C long integers). 1495 1496 type Fd_Set_Access is access all Fd_Set; 1497 pragma Convention (C, Fd_Set_Access); 1498 No_Fd_Set_Access : constant Fd_Set_Access := null; 1499 1500 type Socket_Set_Type is record 1501 Last : Socket_Type := No_Socket; 1502 -- Highest socket in set. Last = No_Socket denotes an empty set (which 1503 -- is the default initial value). 1504 1505 Set : aliased Fd_Set; 1506 -- Underlying socket set. Note that the contents of this component is 1507 -- undefined if Last = No_Socket. 1508 end record; 1509 1510 Any_Port : constant Port_Type := 0; 1511 No_Port : constant Port_Type := 0; 1512 1513 Any_Inet_Addr : constant Inet_Addr_Type := 1514 (Family_Inet, (others => 0)); 1515 Any_Inet6_Addr : constant Inet_Addr_Type := 1516 (Family_Inet6, (others => 0)); 1517 No_Inet_Addr : constant Inet_Addr_Type := 1518 (Family_Inet, (others => 0)); 1519 Broadcast_Inet_Addr : constant Inet_Addr_Type := 1520 (Family_Inet, (others => 255)); 1521 Loopback_Inet_Addr : constant Inet_Addr_Type := 1522 (Family_Inet, (127, 0, 0, 1)); 1523 Loopback_Inet6_Addr : constant Inet_Addr_Type := 1524 (Family_Inet6, 1525 (0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1)); 1526 1527 Unspecified_Group_Inet_Addr : constant Inet_Addr_Type := 1528 (Family_Inet, (224, 0, 0, 0)); 1529 All_Hosts_Group_Inet_Addr : constant Inet_Addr_Type := 1530 (Family_Inet, (224, 0, 0, 1)); 1531 All_Routers_Group_Inet_Addr : constant Inet_Addr_Type := 1532 (Family_Inet, (224, 0, 0, 2)); 1533 1534 Unspecified_Group_Inet6_Addr : constant Inet_Addr_Type := 1535 (Family_Inet6, (255, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0)); 1536 All_Hosts_Group_Inet6_Addr : constant Inet_Addr_Type := 1537 (Family_Inet6, (255, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1)); 1538 All_Routers_Group_Inet6_Addr : constant Inet_Addr_Type := 1539 (Family_Inet6, (255, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2)); 1540 1541 No_Sock_Addr : constant Sock_Addr_Type := (Family_Inet, No_Inet_Addr, 0); 1542 1543 Max_Name_Length : constant := 64; 1544 -- The constant MAXHOSTNAMELEN is usually set to 64 1545 1546 subtype Name_Index is Natural range 1 .. Max_Name_Length; 1547 1548 type Name_Type (Length : Name_Index := Max_Name_Length) is record 1549 Name : String (1 .. Length); 1550 end record; 1551 -- We need fixed strings to avoid access types in host entry type 1552 1553 type Name_Array is array (Positive range <>) of Name_Type; 1554 type Inet_Addr_Array is array (Positive range <>) of Inet_Addr_Type; 1555 1556 type Host_Entry_Type (Aliases_Length, Addresses_Length : Natural) is record 1557 Official : Name_Type; 1558 Aliases : Name_Array (1 .. Aliases_Length); 1559 Addresses : Inet_Addr_Array (1 .. Addresses_Length); 1560 end record; 1561 1562 type Service_Entry_Type (Aliases_Length : Natural) is record 1563 Official : Name_Type; 1564 Port : Port_Type; 1565 Protocol : Name_Type; 1566 Aliases : Name_Array (1 .. Aliases_Length); 1567 end record; 1568 1569 type Request_Flag_Type is mod 2 ** 8; 1570 No_Request_Flag : constant Request_Flag_Type := 0; 1571 Process_Out_Of_Band_Data : constant Request_Flag_Type := 1; 1572 Peek_At_Incoming_Data : constant Request_Flag_Type := 2; 1573 Wait_For_A_Full_Reception : constant Request_Flag_Type := 4; 1574 Send_End_Of_Record : constant Request_Flag_Type := 8; 1575 1576end GNAT.Sockets; 1577