The @code{Sockets} package contains all the definitions and
subprograms needed to build a simple unicast client or server.

@deftypefn Sockets.Socket_FD type Socket_FD is tagged private;
The @code{Socket_FD} tagged type is the root type of all
sockets. It gets initialized by calling @ref{Socket (procedure)}.
An uninitialized @code{Socket_FD} can be succesfully compared to
@code{Null_Socket_FD}.

@end deftypefn

@menu
* Accept_Socket (procedure)::
                        Accept an incoming connection
* Bind (procedure)::    Associate a local port to a socket
* Connect (procedure):: Connect a socket on a given host/port
* Get (function)::      Get a string from a remote host
* Get_Char (function):: Get a character from a remote host
* Get_Line (function):: Get a whole line from a remote host
* Get_Line (procedure)::
                        Get a whole line from a remote host
* Getsockopt (procedure)::
                        Retrieve a socket option
* Listen (procedure)::  Establish a listen queue
* New_Line (procedure)::
                        Send a CR/LF to a remote host
* Put (procedure)::     Send a string to a remote host
* Put_Line (procedure)::
                        Send a CR/LF terminated string to a remote host
* Receive (function)::  Receive raw data over a socket
* Receive (procedure):: Receive raw data over a socket
* Receive_Some (procedure)::
                        Receive raw data over a socket
* Send (procedure)::    Send raw data over a socket
* Set_Buffer (procedure)::
                        Install a line-oriented buffer of the socket object
* Setsockopt (procedure)::
                        Set a socket option
* Shutdown (procedure)::
                        Shutdown a socket
* Socket (procedure)::  Create a socket of the given mode
* Unset_Buffer (procedure)::
                        Deinstall the line-oriented buffer of the socket object
@end menu

@node Accept_Socket (procedure)
@unnumberedsubsec Accept_Socket (procedure)
@cindex Accepting a new connection
@cindex Handling a new connection

@table @sc
@item Purpose
Accept an incoming connection
@item Prototype
@deftypefn Sockets.Accept_Socket procedure Accept_Socket (@w{@var{Socket} : Socket_FD}; @w{@var{New_Socket} : out Socket_FD});
@end deftypefn
@fnindex Sockets.Accept_Socket

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized
@item @var{New_Socket} @tab out @tab Incoming socket object
@end multitable


@item Description
This procedure creates a new socket corresponding to an incoming
connection on TCP socket @var{Socket}. All the communications
with the peer will take place on @var{New_Socket}, while the
program can accept another connection on @var{Socket}.

@var{New_Socket} must not be initialized before calling this
procedure, or must have been cleaned up by calling
@code{Shutdown}, in order to avoid a file descriptors leak.

@code{Accept_Socket} will block until an incoming connection is
ready to be accepted.



@item Example
@example
declare
   Sock     : Socket_FD;
   Incoming : Socket_FD;
begin
   -- Create a TCP socket listening on local port 4161
   Socket (Sock, PF_INET, SOCK_STREAM);
   Bind (Sock, 4161);
   Listen (Sock, 3);
   -- One-connection-at-a-time server (3 may be pending)
   loop
      -- Wait for a new connection and accept it
      Accept_Socket (Sock, Incoming);
      -- Do some dialog with the remote host
      Do_Some_Dialog (Incoming);
      -- Close incoming socket and wait for next connection
      Shutdown (Incoming);
   end loop;
end;
@end example


@item See also
@ref{Bind (procedure)},@*@ref{Listen (procedure)},@*@ref{Shutdown (procedure)},@*@ref{Socket (procedure)}.

@end table

@node Bind (procedure)
@unnumberedsubsec Bind (procedure)
@cindex Binding a socket
@cindex Assigning a local port
@cindex Creating a server

@table @sc
@item Purpose
Associate a local port to a socket
@item Prototype
@deftypefn Sockets.Bind procedure Bind (@w{@var{Socket} : Socket_FD}; @w{@var{Port} : Natural}; @w{@var{Host} : String := @w{}""});
@end deftypefn
@fnindex Sockets.Bind

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized socket object
@item @var{Port} @tab in @tab Local port to bind to
@item @var{Host} @tab in @tab Local interface to bind to
@end multitable


@item Description
This procedure requests a local port from the operating
system. If 0 is given in @var{Port}, the system will assign a
free port whose number can later be retrieved using
@ref{Get_Sock_Port (function)}. Also, most operating systems require
special privileges if you want to bind to ports below 1024.

If @var{Host} is not the empty string, it must contain the
IP address of a local interface to bind to, or a name which
resolves into such an address. If an empty string is given (the
default), the socket will be bound to all the available
interfaces.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Socket_Error} @tab Requested port or interface not available@exindex Socket_Error
@end multitable





@item See also
@ref{Listen (procedure)},@*@ref{Socket (procedure)}.

@end table

@node Connect (procedure)
@unnumberedsubsec Connect (procedure)
@cindex Connecting a socket

@table @sc
@item Purpose
Connect a socket on a given host/port
@item Prototype
@deftypefn Sockets.Connect procedure Connect (@w{@var{Socket} : Socket_FD}; @w{@var{Host} : String}; @w{@var{Port} : Positive});
@end deftypefn
@fnindex Sockets.Connect

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized socket object
@item @var{Host} @tab in @tab Host to connect to
@item @var{Port} @tab in @tab Port to connect to
@end multitable


@item Description
This procedure connects an initialized socket to a given host on
a given port. In the case of a TCP socket, a real connection is
attempted. In the case of a UDP socket, no connection takes place
but the endpoint coordinates are recorded.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Refused} @tab The connection has been refused by the server@exindex Connection_Refused
@item @code{Socket_Error} @tab Another error occurred during the connection@exindex Socket_Error
@end multitable





@item Example
@example
declare
   Sock : Socket_FD;
begin
   -- Create a TCP socket
   Socket (Sock, PF_INET, SOCK_STREAM);
   -- Connect it to rfc1149.net's mail server
   Connect (Sock, "mail.rfc1149.net", 25);
   -- Do a mail transaction then close the socket
   [...]
end;
@end example


@item See also
@ref{Socket (procedure)}.

@end table

@node Get (function)
@unnumberedsubsec Get (function)
@cindex Receiving data

@table @sc
@item Purpose
Get a string from a remote host
@item Prototype
@deftypefn Sockets.Get function Get (@w{@var{Socket} : Socket_FD'Class})@*@w{return String;}
@end deftypefn
@fnindex Sockets.Get

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@end multitable

@item Return value
Some characters that have been received

@item Description
This function receives some characters from a remote host.
As soon that at least one character is available, the current
reception buffer is returned.

There is usually little gain in using this function whose behaviour is
comparable to the one of @ref{Receive (function)}. Other
functions such as @ref{Get_Char (function)}, or
@ref{Get_Line (function)}, allow more structured programming.

However, this function may be used to avoid loosing characters
when calling @ref{Unset_Buffer (procedure)}, if, for some reason,
the remote host may have sent some.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending any data@exindex Connection_Closed
@end multitable





@end table

@node Get_Char (function)
@unnumberedsubsec Get_Char (function)
@cindex Receiving data

@table @sc
@item Purpose
Get a character from a remote host
@item Prototype
@deftypefn Sockets.Get_Char function Get_Char (@w{@var{Socket} : Socket_FD'Class})@*@w{return Character;}
@end deftypefn
@fnindex Sockets.Get_Char

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@end multitable

@item Return value
One character sent by the remote host

@item Description
This function receives exactly one character from the remote host.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending the character@exindex Connection_Closed
@end multitable





@item See also
@ref{Get (function)},@*@ref{Get_Line (function)},@*@ref{Get_Line (procedure)},@*@ref{Receive (procedure)},@*@ref{Set_Buffer (procedure)}.

@end table

@node Get_Line (function)
@unnumberedsubsec Get_Line (function)
@cindex Receiving data

@table @sc
@item Purpose
Get a whole line from a remote host
@item Prototype
@deftypefn Sockets.Get_Line function Get_Line (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Max_Length} : Positive := 2048})@*@w{return String;}
@end deftypefn
@fnindex Sockets.Get_Line

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Max_Length} @tab in @tab Maximum returned line length
@end multitable

@item Return value
A line without the CR and LF separators

@item Description
@ctindex CR
@ctindex LF
This function receives one line from the remote host. A line
consists into zero or more characters followed by an optional CR
and by a LF. Those terminators are stripped before the line is
returned.

This function blocks until one full line has been received. The line
length is limited with the value of the Max_Length argument, to avoid
exhaustion of the secondary stack.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending a whole line@exindex Connection_Closed
@end multitable





@item See also
@ref{Get (function)},@*@ref{Get_Char (function)},@*@ref{Get_Line (procedure)},@*@ref{Receive (procedure)},@*@ref{Set_Buffer (procedure)}.

@end table

@node Get_Line (procedure)
@unnumberedsubsec Get_Line (procedure)
@cindex Receiving data

@table @sc
@item Purpose
Get a whole line from a remote host
@item Prototype
@deftypefn Sockets.Get_Line procedure Get_Line (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Str} : in out String}; @w{@var{Last} : out Natural});
@end deftypefn
@fnindex Sockets.Get_Line

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Str} @tab in out @tab String to fill
@item @var{Last} @tab out @tab Last index used in the string
@end multitable


@item Description
@ctindex CR
@ctindex LF
This procedure receives one line from the remote host. A line
consists into zero or more characters followed by an optional CR
and by a LF. Those terminators are stripped before the line is
returned.

This procedure blocks until one full line has been received.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending a whole line@exindex Connection_Closed
@end multitable





@item See also
@ref{Get (function)},@*@ref{Get_Char (function)},@*@ref{Get_Line (function)},@*@ref{Receive (procedure)},@*@ref{Set_Buffer (procedure)}.

@end table

@node Getsockopt (procedure)
@unnumberedsubsec Getsockopt (procedure)
@cindex Manipulating socket options
@cindex Retrieving socket options

@table @sc
@item Purpose
Retrieve a socket option
@item Prototype
@deftypefn Sockets.Getsockopt procedure Getsockopt (@w{@var{Socket} : Socket_FD}; @w{@var{Level} : Socket_Level := SOL_SOCKET}; @w{@var{Optname} : Socket_Option}; @w{@var{Optval} : out Integer});
@end deftypefn
@fnindex Sockets.Getsockopt

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound socket object
@item @var{Level} @tab in @tab Protocol level
@item @var{Optname} @tab in @tab Option name
@item @var{Optval} @tab out @tab Option value
@end multitable


@item Description
@ctindex Sockets.SOL_SOCKET
@ctindex Sockets.IPPROTO_IP
@ctindex Sockets.SO_REUSEADDR
@ctindex Sockets.SO_REUSEPORT
@ctindex Sockets.IP_MULTICAST_TTL
@ctindex Sockets.IP_ADD_MEMBERSHIP
@ctindex Sockets.IP_DROP_MEMBERSHIP
@ctindex Sockets.IP_MULTICAST_LOOP
@ctindex Sockets.SO_SNDBUF
@ctindex Sockets.SO_RCVBUF
@ctindex SOL_SOCKET
@ctindex IPPROTO_IP
@ctindex SO_REUSEADDR
@ctindex SO_REUSEPORT
@ctindex IP_MULTICAST_TTL
@ctindex IP_ADD_MEMBERSHIP
@ctindex IP_DROP_MEMBERSHIP
@ctindex IP_MULTICAST_LOOP
@ctindex SO_SNDBUF
@ctindex SO_RCVBUF
This procedure retrieves options applicable to a socket. Please
see your operating system manual for usable levels and options.

Two levels are defined: @code{SOL_SOCKET} (the default) and
@code{IPPROTO_IP}. The options are @code{SO_REUSEADDR},
@code{SO_REUSEPORT}, @code{IP_MULTICAST_TTL},
@code{IP_ADD_MEMBERSHIP}, @code{IP_DROP_MEMBERSHIP},
@code{IP_MULTICAST_LOOP}, @code{SO_SNDBUF} and
@code{IP_RCVBUF}.

Note that unlike their C language counterpart, @code{Getsockopt}
and @code{Setsockopt} do not require an extra parameter
representing the length in bytes of the option value. AdaSockets
nows the right size for every option.




@item See also
@ref{Setsockopt (procedure)}.

@end table

@node Listen (procedure)
@unnumberedsubsec Listen (procedure)
@cindex Establishing a listen queue
@cindex Listen queue

@table @sc
@item Purpose
Establish a listen queue
@item Prototype
@deftypefn Sockets.Listen procedure Listen (@w{@var{Socket} : Socket_FD}; @w{@var{Queue_Size} : Positive := 5});
@end deftypefn
@fnindex Sockets.Listen

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound socket object
@item @var{Queue_Size} @tab in @tab Requested slots in the listen queue
@end multitable


@item Description
This procedure establishes a listen queue after a TCP socket as been
initialized and bound. Each slot in the queue can hold one
incoming connection that has not been accepted yet. Note that
most operating systems ignore queue sizes larger than five.




@item See also
@ref{Accept_Socket (procedure)},@*@ref{Bind (procedure)},@*@ref{Socket (procedure)}.

@end table

@node New_Line (procedure)
@unnumberedsubsec New_Line (procedure)
@cindex Sending data

@table @sc
@item Purpose
Send a CR/LF to a remote host
@item Prototype
@deftypefn Sockets.New_Line procedure New_Line (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Count} : Natural := 1});
@end deftypefn
@fnindex Sockets.New_Line

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Count} @tab in @tab Number of CR/LF sequences to send
@end multitable


@item Description
@ctindex CR
@ctindex LF
This procedure sends one or more CR/LF combinations to the peer.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has prematurely closed the connection@exindex Connection_Closed
@end multitable





@item See also
@ref{Put (procedure)},@*@ref{Put_Line (procedure)}.

@end table

@node Put (procedure)
@unnumberedsubsec Put (procedure)
@cindex Sending data

@table @sc
@item Purpose
Send a string to a remote host
@item Prototype
@deftypefn Sockets.Put procedure Put (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Str} : String});
@end deftypefn
@fnindex Sockets.Put

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Str} @tab in @tab String to send
@end multitable


@item Description
This procedure sends the content of @var{Str} over an outgoing
or incoming socket.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has prematurely closed the connection@exindex Connection_Closed
@end multitable





@item See also
@ref{New_Line (procedure)},@*@ref{Put_Line (procedure)},@*@ref{Send (procedure)}.

@end table

@node Put_Line (procedure)
@unnumberedsubsec Put_Line (procedure)
@cindex Sending data

@table @sc
@item Purpose
Send a CR/LF terminated string to a remote host
@item Prototype
@deftypefn Sockets.Put_Line procedure Put_Line (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Str} : String});
@end deftypefn
@fnindex Sockets.Put_Line

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Str} @tab in @tab String to send
@end multitable


@item Description
This procedure sends the content of @var{Str} plus a CR/LF combination
over an outgoing or incoming socket.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has prematurely closed the connection@exindex Connection_Closed
@end multitable





@item See also
@ref{New_Line (procedure)},@*@ref{Put (procedure)},@*@ref{Send (procedure)}.

@end table

@node Receive (function)
@unnumberedsubsec Receive (function)
@cindex Receiving data

@table @sc
@item Purpose
Receive raw data over a socket
@item Prototype
@deftypefn Sockets.Receive function Receive (@w{@var{Socket} : Socket_FD}; @w{@var{Max} : Ada.Streams.Stream_Element_Count := 4096})@*@w{return Ada.Streams.Stream_Element_Array;}
@end deftypefn
@fnindex Sockets.Receive

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound or connected socket object
@item @var{Max} @tab in @tab Maximum data length
@end multitable

@item Return value
Received raw data

@item Description
@tindex Ada.Streams.Stream_Element_Count
@tindex Ada.Streams.Stream_Element_Array
@tindex Stream_Element_Count
@tindex Stream_Element_Array
This procedure receives data from a bound UDP socket or a connected
TCP socket. Only one system call will be performed; this
function will return whatever data has arrived. Note that in
GNAT the secondary stack may be used to store  the data and may
result in stack storage exhaustion.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending any data@exindex Connection_Closed
@end multitable





@item See also
@ref{Receive (procedure)},@*@ref{Receive_Some (procedure)},@*@ref{Get_Line (function)},@*@ref{Get_Line (procedure)}.

@end table

@node Receive (procedure)
@unnumberedsubsec Receive (procedure)
@cindex Receiving data

@table @sc
@item Purpose
Receive raw data over a socket
@item Prototype
@deftypefn Sockets.Receive procedure Receive (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Data} : out Ada.Streams.Stream_Element_Array});
@end deftypefn
@fnindex Sockets.Receive

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound or connected socket object
@item @var{Data} @tab out @tab Incoming data buffer
@end multitable


@item Description
@tindex Ada.Streams.Stream_Element_Array
@tindex Stream_Element_Array
This procedure receives data from a bound UDP socket or a connected
TCP socket. It will block until the @var{Data} reception buffer
has been totally filled.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before @code{Data'Length} bytes@*
were received@exindex Connection_Closed
@end multitable





@item See also
@ref{Get_Line (function)},@*@ref{Get_Line (procedure)},@*@ref{Receive (function)},@*@ref{Receive_Some (procedure)}.

@end table

@node Receive_Some (procedure)
@unnumberedsubsec Receive_Some (procedure)
@cindex Receiving data

@table @sc
@item Purpose
Receive raw data over a socket
@item Prototype
@deftypefn Sockets.Receive_Some procedure Receive_Some (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Data} : out Ada.Streams.Stream_Element_Array}; @w{@var{Last} : out Ada.Streams.Stream_Element_Offset});
@end deftypefn
@fnindex Sockets.Receive_Some

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound or connected socket object
@item @var{Data} @tab out @tab Incoming data buffer
@item @var{Last} @tab out @tab Index of last element placed into @var{Data}
@end multitable


@item Description
@tindex Ada.Streams.Stream_Element_Array
@tindex Stream_Element_Array
@tindex Ada.Streams.Stream_Element_Count
@tindex Stream_Element_Count
This procedure receives data from a bound UDP socket or a connected
TCP socket. As soon as at least one byte has been read, it returns
with @var{Last} set to the index of the latest written element
of @var{Data}.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has closed the connection before sending any data@exindex Connection_Closed
@end multitable





@item See also
@ref{Get_Line (function)},@*@ref{Get_Line (procedure)},@*@ref{Receive (function)},@*@ref{Receive (procedure)}.

@end table

@node Send (procedure)
@unnumberedsubsec Send (procedure)
@cindex Sending data

@table @sc
@item Purpose
Send raw data over a socket
@item Prototype
@deftypefn Sockets.Send procedure Send (@w{@var{Socket} : Socket_FD}; @w{@var{Data} : out Ada.Streams.Stream_Element_Array});
@end deftypefn
@fnindex Sockets.Send

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Data} @tab out @tab Data to be sent
@end multitable


@item Description
@tindex Ada.Streams.Stream_Element_Array
@tindex Stream_Element_Array
This procedure sends data over a connected outgoing socket or
over an incoming socket.


@item Exceptions
@multitable {XXXXXXXXXXXXXXXX} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @code{Connection_Closed} @tab Peer has prematurely closed the connection@exindex Connection_Closed
@end multitable





@item See also
@ref{Put (procedure)},@*@ref{Put_Line (procedure)}.

@end table

@node Set_Buffer (procedure)
@unnumberedsubsec Set_Buffer (procedure)
@cindex Receiving data

@table @sc
@item Purpose
Install a line-oriented buffer of the socket object
@item Prototype
@deftypefn Sockets.Set_Buffer procedure Set_Buffer (@w{@var{Socket} : Socket_FD'Class}; @w{@var{Length} : Positive := 1500});
@end deftypefn
@fnindex Sockets.Set_Buffer

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@item @var{Length} @tab in @tab Size in bytes of the newly installed buffer
@end multitable


@item Description
This procedure puts the socket object in buffered mode. If the
socket was already buffered, the content of the previous buffer
will be lost. The buffered mode only affects character- and
line-oriented read operation such as @ref{Get (function)},
@ref{Get_Char (function)}, and @ref{Get_Line (function)}. Other
reception subprograms will not function properly if buffered mode
is used at the same time.

The size of the buffer has to be greater than the biggest
possible packet sent by the remote host, otherwise data loss may
occur.




@item See also
@ref{Unset_Buffer (procedure)}.

@end table

@node Setsockopt (procedure)
@unnumberedsubsec Setsockopt (procedure)
@cindex Manipulating socket options
@cindex Setting socket options

@table @sc
@item Purpose
Set a socket option
@item Prototype
@deftypefn Sockets.Setsockopt procedure Setsockopt (@w{@var{Socket} : Socket_FD}; @w{@var{Level} : Socket_Level := SOL_SOCKET}; @w{@var{Optname} : Socket_Option}; @w{@var{Optval} : Integer});
@end deftypefn
@fnindex Sockets.Setsockopt

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and bound socket object
@item @var{Level} @tab in @tab Protocol level
@item @var{Optname} @tab in @tab Option name
@item @var{Optval} @tab in @tab Option value
@end multitable


@item Description
@ctindex Sockets.SOL_SOCKET
@ctindex Sockets.IPPROTO_IP
@ctindex Sockets.SO_REUSEADDR
@ctindex Sockets.SO_REUSEPORT
@ctindex Sockets.IP_MULTICAST_TTL
@ctindex Sockets.IP_ADD_MEMBERSHIP
@ctindex Sockets.IP_DROP_MEMBERSHIP
@ctindex Sockets.IP_MULTICAST_LOOP
@ctindex Sockets.SO_SNDBUF
@ctindex Sockets.SO_RCVBUF
@ctindex SOL_SOCKET
@ctindex IPPROTO_IP
@ctindex SO_REUSEADDR
@ctindex SO_REUSEPORT
@ctindex IP_MULTICAST_TTL
@ctindex IP_ADD_MEMBERSHIP
@ctindex IP_DROP_MEMBERSHIP
@ctindex IP_MULTICAST_LOOP
@ctindex SO_SNDBUF
@ctindex SO_RCVBUF
This procedure sets options applicable to a socket. Please
see your operating system manual for usable levels and options.

Two levels are defined: @code{SOL_SOCKET} (the default) and
@code{IPPROTO_IP}. The options are @code{SO_REUSEADDR},
@code{SO_REUSEPORT}, @code{IP_MULTICAST_TTL},
@code{IP_ADD_MEMBERSHIP}, @code{IP_DROP_MEMBERSHIP},
@code{IP_MULTICAST_LOOP}, @code{SO_SNDBUF} and
@code{IP_RCVBUF}.

Note that unlike their C language counterpart, @code{Getsockopt}
and @code{Setsockopt} do not require an extra parameter
representing the length in bytes of the option value. AdaSockets
nows the right size for every option.




@item See also
@ref{Getsockopt (procedure)}.

@end table

@node Shutdown (procedure)
@unnumberedsubsec Shutdown (procedure)
@cindex Closing a socket
@cindex Socket shutdown

@table @sc
@item Purpose
Shutdown a socket
@item Prototype
@deftypefn Sockets.Shutdown procedure Shutdown (@w{@var{Socket} : in out Socket_FD}; @w{@var{How} : Shutdown_Type := Both});
@end deftypefn
@fnindex Sockets.Shutdown

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in out @tab Socket object to shutdown
@item @var{How} @tab in @tab Direction to shutdown
@end multitable


@item Description
@ctindex Send
@ctindex Receive
@ctindex Both
This procedure shutdowns either direction of the socket. @var{How}
can take the value @samp{Send}, @samp{Receive} or @samp{Both}.




@item See also
@ref{Socket (procedure)}.

@end table

@node Socket (procedure)
@unnumberedsubsec Socket (procedure)
@cindex Creating a socket

@table @sc
@item Purpose
Create a socket of the given mode
@item Prototype
@deftypefn Sockets.Socket procedure Socket (@w{@var{Socket} : out Socket_FD}; @w{@var{Domain} : Socket_Domain := PF_INET}; @w{@var{Typ} : Socket_Type := SOCK_STREAM});
@end deftypefn
@fnindex Sockets.Socket

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab out @tab Socket object to initialize
@item @var{Domain} @tab in @tab Protocol family
@item @var{Typ} @tab in @tab Kind of sockets
@end multitable


@item Description
@ctindex PF_INET
@ctindex AF_INET
@ctindex SOCK_STREAM
@ctindex SOCK_DGRAM
This procedure initializes a new socket object by reserving a file
descriptor to the operating system. For backward compatibility with
older versions of this library, @code{AF_INET} is still accepted as
a value but should be replaced as soon as possible with the proper
@code{PF_INET}. Using @code{SOCK_STREAM} for the @var{Typ}
argument will create a TCP socket while a @code{SOCK_DGRAM} will
create a UDP one.



@item Example
@example
declare
   Sock : Socket_FD;
begin
   -- Create a TCP socket
   Socket (Sock, PF_INET, SOCK_STREAM);
   -- Perform some operations on socket
   [...]
   -- Shutdown the socket in both directions
   Shutdown (Sock, Both);
end;
@end example


@item See also
@ref{Shutdown (procedure)}.

@end table

@node Unset_Buffer (procedure)
@unnumberedsubsec Unset_Buffer (procedure)
@cindex Receiving data

@table @sc
@item Purpose
Deinstall the line-oriented buffer of the socket object
@item Prototype
@deftypefn Sockets.Unset_Buffer procedure Unset_Buffer (@w{@var{Socket} : Socket_FD'Class});
@end deftypefn
@fnindex Sockets.Unset_Buffer

@item Parameters
@multitable {XXXXXXXX} {in out X} {XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX}
@item @var{Socket} @tab in @tab Initialized and connected socket object
@end multitable


@item Description
This procedure deinstalls the buffer previously installed by
@ref{Set_Buffer (procedure)}. If any data is still present in
the buffer, it will be lost. To avoid this situation, the buffer
can be flushed by calling @ref{Get (function)}.




@end table