aboutsummaryrefslogblamecommitdiffstats
path: root/erts/doc/src/socket_usage.xml
blob: e0f006e618602832876b47ec83f7db7f9872caf6 (plain) (tree)
1
2
3
4
5
6
7





                                       
                                        





























                                                                               



                                                                         


            
                                         








                                         
                                                             

            






                                                                         



















                                        

                           
                                                                              

                        

                                                                                 














                                               






                              
                                        








                                            
                                                             


























                                 
                                              





                             
                                                           





























                                     
                             




















                                          





                                      






                                      

                              



















                                          
                                      



                         
           






                                            





                              













                              
                                         








                                         
                                                             




































                                           






                              






                               






                               






                                         







                                 
                                  


























                                        
                            











                               






                                 






                                 






                              






                                       






                                    






                                    






                                    






                                    






                                 






                                



                             
                                                                               





                                
                                              

            
                        











                                     
                                     








                                          
                                                             

            







                                                                             






                                   






                                                  






                                    






                                                                                






                                                                                


                              








                                                                                
            







                                                                  






                                    






                                      






                                       






                                   






                              






                                          






                                 






                                                                                






                                      





                              
                                       








                                         
                                                             












                               
                         





                              
                         
            
                                      








                                         
                                                             





                              
                         
            
                                      








                                          
                                                             

            






                                       
                              
                                      

                        
                         

            






                                      






                                           






                                   






                                      



                              
                         
            






                                   
                                       




            
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">

<chapter>
  <header>
    <copyright>
      <year>2018</year><year>2019</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>Socket Usage</title>
    <prepared>Micael Karlberg</prepared>
    <docno></docno>
    <date>2018-07-17</date>
    <rev>PA1</rev>
    <file>socket_usage.xml</file>
  </header>

  <section>
    <title>Introduction</title>
    <p>The socket interface (module) is basically an "thin" layer on top of
    the OS socket interface. It is assumed that, unless you have special needs,
    gen_[tcp|udp|sctp] should be sufficent. </p>
    <p>Note that just because we have a documented and described option,
    it does <em>not</em> mean that the OS supports it. So its recommended
    that the user reads the platform specific documentation for the
    option used. </p>
  </section>

  <section>
    <marker id="socket_options"></marker>
    <title>Socket Options</title>

    <p>Options for level <c>otp</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>assoc_id</cell>
	<cell>integer()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>type = seqpacket, protocol = sctp, is an association</cell>
      </row>
      <row>
	<cell>debug</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>iow</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>controlling_process</cell>
	<cell>pid()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>rcvbuf</cell>
	<cell>default | pos_integer() | {pos_integer(), pos_ineteger()}</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>'default' only valid for set.
	The tuple form is only valid for type 'stream' and protocol 'tcp'.</cell>
      </row>
      <row>
	<cell>rcvctrlbuf</cell>
	<cell>default | pos_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>default only valid for set</cell>
      </row>
      <row>
	<cell>sndctrlbuf</cell>
	<cell>default | pos_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>default only valid for set</cell>
      </row>
      <row>
	<cell>fd</cell>
	<cell>integer()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <tcaption>option levels</tcaption>
    </table>
    
    <p>Options for level <c>socket</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>acceptcon</cell>
	<cell>boolean()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>bindtodevice</cell>
	<cell>string()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>broadcast</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram</cell>
      </row>
      <row>
	<cell>debug</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>requires admin capability</cell>
      </row>
      <row>
	<cell>domain</cell>
	<cell>domain()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell><em>Not</em> on FreeBSD (for instance)</cell>
      </row>
      <row>
	<cell>dontroute</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>keepalive</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>linger</cell>
	<cell>abort | linger()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>oobinline</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>peek_off</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>domain = local (unix)</cell>
      </row>
      <row>
	<cell>priority</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>protocol</cell>
	<cell>protocol()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>rcvbuf</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>rcvlowat</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>rcvtimeo</cell>
	<cell>timeval()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>reuseaddr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>reuseport</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>domain = inet | inet6</cell>
      </row>
      <row>
	<cell>sndbuf</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>sndlowat</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>not changeable on Linux</cell>
      </row>
      <row>
	<cell>sndtimeo</cell>
	<cell>timeval()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>timestamp</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>type</cell>
	<cell>type()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <tcaption>socket options</tcaption>
    </table>
    
    <p>Options for level <c>ip</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>add_membership</cell>
	<cell>ip_mreq()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>add_source_membership</cell>
	<cell>ip_mreq_source()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>block_source</cell>
	<cell>ip_mreq_source()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>drop_membership</cell>
	<cell>ip_mreq()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>drop_source_membership</cell>
	<cell>ip_mreq_source()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>freebind</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>hdrincl</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>minttl</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>msfilter</cell>
	<cell>null | ip_msfilter()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>mtu</cell>
	<cell>integer()</cell>
	<cell>no</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>mtu_discover</cell>
	<cell>ip_pmtudisc()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_all</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_if</cell>
	<cell>any | ip4_address()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_loop</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_ttl</cell>
	<cell>uint8()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>nodefrag</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>pktinfo</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram</cell>
      </row>
      <row>
	<cell>recvdstaddr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram</cell>
      </row>
      <row>
	<cell>recverr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>recvif</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw</cell>
      </row>
      <row>
	<cell>recvopts</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type =/= stream</cell>
      </row>
      <row>
	<cell>recvorigdstaddr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>recvttl</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type =/= stream</cell>
      </row>
      <row>
	<cell>retopts</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type =/= stream</cell>
      </row>
      <row>
	<cell>router_alert</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>sendsrcaddr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>tos</cell>
	<cell>ip_tos()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>some high-priority levels may require superuser capability</cell>
      </row>
      <row>
	<cell>transparent</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>requires admin capability</cell>
      </row>
      <row>
	<cell>ttl</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>unblock_source</cell>
	<cell>ip_mreq_source()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <tcaption>ip options</tcaption>
    </table>
    
    <p>Options for level <c>ipv6</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>addrform</cell>
	<cell>inet</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>allowed only for IPv6 sockets that are connected and bound to a
	v4-mapped-on-v6 address</cell>
      </row>
      <row>
	<cell>add_membership</cell>
	<cell>ipv6_mreq()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>authhdr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, obsolete?</cell>
      </row>
      <row>
	<cell>drop_membership</cell>
	<cell>ipv6_mreq()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>dstopts</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, requires superuser privileges to update</cell>
      </row>
      <row>
	<cell>flowinfo</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, requires superuser privileges to update</cell>
      </row>
      <row>
	<cell>hoplimit</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, requires superuser privileges to update</cell>
      </row>
      <row>
	<cell>hopopts</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, requires superuser privileges to update</cell>
      </row>
      <row>
	<cell>mtu</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>Get: Only after the socket has been connected</cell>
      </row>
      <row>
	<cell>mtu_discover</cell>
	<cell>ipv6_pmtudisc()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_hops</cell>
	<cell>default | uint8()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>multicast_if</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw</cell>
      </row>
      <row>
	<cell>multicast_loop</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>recverr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>recvpktinfo | pktinfo</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw</cell>
      </row>
      <row>
	<cell>router_alert</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = raw</cell>
      </row>
      <row>
	<cell>rthdr</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>type = dgram | raw, requires superuser privileges to update</cell>
      </row>
      <row>
	<cell>unicast_hops</cell>
	<cell>default | uint8()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>v6only</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <tcaption>ipv6 options</tcaption>
    </table>
    
    <p>Options for level <c>tcp</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>congestion</cell>
	<cell>string()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>maxseg</cell>
	<cell>integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>nodelay</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <tcaption>tcp options</tcaption>
    </table>
    
    <p>Options for level <c>udp</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>cork</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <tcaption>udp options</tcaption>
    </table>
    
    <p>Options for level <c>sctp</c>: </p>
    <table>
      <row>
	<cell><em>Option Name</em></cell>
	<cell><em>Value Type</em></cell>
	<cell><em>Set</em></cell>
	<cell><em>Get</em></cell>
	<cell><em>Other Requirements and comments</em></cell>
      </row>
      <row>
	<cell>associnfo</cell>
	<cell>sctp_assocparams()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>autoclose</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>disable_fragments</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>events</cell>
	<cell>sctp_event_subscribe()</cell>
	<cell>yes</cell>
	<cell>no</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>initmsg</cell>
	<cell>sctp_initmsg()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>maxseg</cell>
	<cell>non_neg_integer()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>nodelay</cell>
	<cell>boolean()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <row>
	<cell>rtoinfo</cell>
	<cell>sctp_rtoinfo()</cell>
	<cell>yes</cell>
	<cell>yes</cell>
	<cell>none</cell>
      </row>
      <tcaption>sctp options</tcaption>
    </table>
    
  </section>
</chapter>