Merge branch 'bmk/esock/20190614/fix-net-docbuilding' into bmk/erts/esock/20190614/split_modules/OTP-15765

5 files changed, 259 insertions, 47 deletions

diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile
index f8867ccf25..70623ab9aa 100644
--- a/lib/kernel/doc/src/Makefile
+++ b/lib/kernel/doc/src/Makefile
@@ -1,7 +1,7 @@
 #
 # %CopyrightBegin%
 #
-# Copyright Ericsson AB 1997-2018. All Rights Reserved.
+# Copyright Ericsson AB 1997-2019. All Rights Reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -36,6 +36,18 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
 # Target Specs
 # ----------------------------------------------------
 XML_APPLICATION_FILES = ref_man.xml
+
+# The doc build has problems with if-defing out modules...
+ifeq ($(USE_ESOCK),yes)
+XML_REF3_ESOCK_FILES = net.xml
+ESOCK_USE_NET_XML=<xi:include href="net.xml"\/>
+ESOCK_USE_NET_SPECS_XML=<xi:include href="../specs/specs_net.xml"/>
+else
+XML_REF3_ESOCK_FILES =
+ESOCK_USE_NET_SPECS_XML =
+ESOCK_USE_NET_XML =
+endif
+
 XML_REF3_FILES = application.xml \
 	auth.xml \
 	code.xml \
@@ -62,6 +74,7 @@ XML_REF3_FILES = application.xml \
         logger_disk_log_h.xml \
         logger_filters.xml \
         logger_formatter.xml \
+	$(XML_REF3_ESOCK_FILES) \
 	net_adm.xml \
 	net_kernel.xml \
 	os.xml \
@@ -112,6 +125,7 @@ SPECS_FILES = $(XML_REF3_FILES:%.xml=$(SPECDIR)/specs_%.xml)
 
 TOP_SPECS_FILE = specs.xml
 
+
 # ----------------------------------------------------
 # FIGURES
 # ----------------------------------------------------
@@ -138,7 +152,7 @@ SPECS_FLAGS = -I../../include
 $(HTMLDIR)/%: %
 	$(INSTALL_DATA) $< $@
 
-docs: man pdf html
+docs: ref_man specs man pdf html
 
 $(TOP_PDF_FILE): $(XML_FILES)
 
@@ -148,19 +162,32 @@ html: images $(HTML_REF_MAN_FILE)
 
 man: $(MAN3_FILES) $(MAN4_FILES) $(MAN6_FILES)
 
+ref_man: ref_man.xml
+specs: specs.xml
+
 images: $(IMAGE_FILES:%=$(HTMLDIR)/%)
 
+info:
+	@echo "XML_APPLICATION_FILES: $(XML_APPLICATION_FILES)"
+	@echo "XML_REF3_ESOCK_FILES:  $(XML_REF3_ESOCK_FILES)"
+	@echo "XML_REF3_FILES:        $(XML_REF3_FILES)"
+	@echo "XML_REF4_FILES:        $(XML_REF4_FILES)"
+	@echo "XML_REF6_FILES:        $(XML_REF6_FILES)"
+	@echo "XML_PART_FILES:        $(XML_PART_FILES)"
+	@echo "XML_CHAPTER_FILES:     $(XML_CHAPTER_FILES)"
+	@echo "BOOK_FILES:            $(BOOK_FILES)"
+
 debug opt:
 
 clean clean_docs:
 	rm -rf $(HTMLDIR)/*
 	rm -rf $(XMLDIR)
-	rm -f $(MAN3DIR)/*
-	rm -f $(MAN4DIR)/*
-	rm -f $(MAN6DIR)/*
-	rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
-	rm -f $(SPECDIR)/*
-	rm -f errs core *~ *.eps
+	rm -f  $(MAN3DIR)/*
+	rm -f  $(MAN4DIR)/*
+	rm -f  $(MAN6DIR)/*
+	rm -f  $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+	rm -f  $(SPECDIR)/*
+	rm -f  errs core *~ *.eps
 
 $(SPECDIR)/specs_erl_prim_loader_stub.xml:
 	$(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
@@ -175,6 +202,14 @@ $(SPECDIR)/specs_zlib_stub.xml:
 	$(gen_verbose)escript $(SPECS_EXTRACTOR) $(SPECS_FLAGS) \
                 -o$(dir $@) -module zlib_stub
 
+ref_man.xml: ref_man.xml.src
+	($(PERL) -p -e 's?%ESOCK_USE_NET_XML%?$(ESOCK_USE_NET_XML)?' \
+            $<) > $@
+specs.xml: specs.xml.src
+	($(PERL) -p -e 's?%ESOCK_USE_NET_SPECS_XML%?$(ESOCK_USE_NET_SPECS_XML)?' \
+            $<) > $@
+
+
 # ----------------------------------------------------
 # Release Target
 # ----------------------------------------------------
diff --git a/lib/kernel/doc/src/net.xml b/lib/kernel/doc/src/net.xml
new file mode 100644
index 0000000000..6fbc37076c
--- /dev/null
+++ b/lib/kernel/doc/src/net.xml
@@ -0,0 +1,129 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>2018</year><year>2018</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>net</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>net.xml</file>
+  </header>
+  <module since="OTP 22.0">net</module>
+  <modulesummary>Network interface.</modulesummary>
+  <description>
+    <p>This module provides an API for the network interface.</p>
+    <note>
+      <p>There is currently <em>no</em> support for Windows. </p>
+    </note>
+  </description>
+
+  <datatypes>
+    <datatype>
+      <name name="address_info"/>
+    </datatype>
+    <datatype>
+      <name name="name_info"/>
+    </datatype>
+    <datatype>
+      <name name="name_info_flags"/>
+    </datatype>
+    <datatype>
+      <name name="name_info_flag"/>
+    </datatype>
+    <datatype>
+      <name name="name_info_flag_ext"/>
+    </datatype>
+    <datatype>
+      <name name="network_interface_name"/>
+    </datatype>
+    <datatype>
+      <name name="network_interface_index"/>
+    </datatype>
+  </datatypes>
+
+  <funcs>
+    <func>
+      <name name="gethostname" arity="0"/>
+      <fsummary>Get hostname.</fsummary>
+      <desc>
+        <p>Returns the name of the current host.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="getnameinfo" arity="1" since="OTP 22.0"/>
+      <name name="getnameinfo" arity="2" since="OTP 22.0"/>
+      <fsummary>Address-to-name transaltion.</fsummary>
+      <desc>
+        <p>Address-to-name translation in a protocol-independant manner.</p>
+	<p>This function is the inverse of
+	<seealso marker="#getaddrinfo/1"><c>getaddrinfo</c></seealso>.
+	It converts a socket address to a corresponding host and service.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="getaddrinfo" arity="1" since="OTP 22.0"/>
+      <name name="getaddrinfo" arity="2" clause_i="1" since="OTP 22.0"/>
+      <name name="getaddrinfo" arity="2" clause_i="2" since="OTP 22.0"/>
+      <name name="getaddrinfo" arity="2" clause_i="3" since="OTP 22.0"/>
+      <fsummary>Network address and service transation.</fsummary>
+      <desc>
+	<p>Network address and service translation.</p>
+	<p>This function is the inverse of
+	<seealso marker="#getnameinfo/1"><c>getnameinfo</c></seealso>.
+	It converts host and service to a corresponding socket address.</p>
+	<p>One of the <c>Host</c> and <c>Service</c> may be <c>undefined</c>
+	but <em>not</em> both.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="if_name2index" arity="1" since="OTP 22.0"/>
+      <fsummary>Mappings between network interface names and indexes.</fsummary>
+      <desc>
+        <p>Mappings between network interface names and indexes.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="if_index2name" arity="1" since="OTP 22.0"/>
+      <fsummary>Mappings between network interface index and names.</fsummary>
+      <desc>
+        <p>Mappings between network interface index and names.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="if_names" arity="0" since="OTP 22.0"/>
+      <fsummary>Get network interface names and indexes.</fsummary>
+      <desc>
+        <p>Get network interface names and indexes.</p>
+      </desc>
+    </func>
+
+  </funcs>
+
+</erlref>
+
diff --git a/lib/kernel/doc/src/ref_man.xml b/lib/kernel/doc/src/ref_man.xml.src
index d3b947527f..72e3409123 100644
--- a/lib/kernel/doc/src/ref_man.xml
+++ b/lib/kernel/doc/src/ref_man.xml.src
@@ -4,7 +4,7 @@
 <application xmlns:xi="http://www.w3.org/2001/XInclude">
   <header>
     <copyright>
-      <year>1996</year><year>2018</year>
+      <year>1996</year><year>2019</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -60,6 +60,7 @@
   <xi:include href="logger_formatter.xml"/>
   <xi:include href="logger_std_h.xml"/>
   <xi:include href="logger_disk_log_h.xml"/>
+  %ESOCK_USE_NET_XML%
   <xi:include href="net_adm.xml"/>
   <xi:include href="net_kernel.xml"/>
   <xi:include href="os.xml"/>
diff --git a/lib/kernel/doc/src/specs.xml b/lib/kernel/doc/src/specs.xml.src
index b8c25ca53b..ccb26b9458 100644
--- a/lib/kernel/doc/src/specs.xml
+++ b/lib/kernel/doc/src/specs.xml.src
@@ -26,6 +26,7 @@
   <xi:include href="../specs/specs_logger_formatter.xml"/>
   <xi:include href="../specs/specs_logger_std_h.xml"/>
   <xi:include href="../specs/specs_logger_disk_log_h.xml"/>
+  %ESOCK_USE_NET_SPECS_XML%
   <xi:include href="../specs/specs_net_adm.xml"/>
   <xi:include href="../specs/specs_net_kernel.xml"/>
   <xi:include href="../specs/specs_os.xml"/>
diff --git a/lib/kernel/src/net.erl b/lib/kernel/src/net.erl
index ac8b600e4b..b8ffa64043 100644
--- a/lib/kernel/src/net.erl
+++ b/lib/kernel/src/net.erl
@@ -20,7 +20,13 @@
 
 -module(net).
 
--ifdef(USE_ESOCK).
+%% We should really ifdef this module depending on if we actually built
+%% the system with esock support (socket and prim_net), but our doc-building
+%% can't handle the "variables" we need (USE_ESOCK). So instead, we just
+%% leave everything hanging...
+%% If one of the "hanging" functions is called when esock has been disabled,
+%% the function will through a 'notsup' error (erlang:error/1).
+
 %% Administrative and utility functions
 -export([
 	 info/0,
@@ -36,7 +42,6 @@
          if_index2name/1,
          if_names/0
         ]).
--endif.
 
 %% Deprecated functions from the "old" net module
 -export([call/4,
@@ -46,8 +51,6 @@
 	 relay/1,
 	 sleep/1]).
 
--ifdef(USE_ESOCK).
-
 %% Should we define these here or refer to the prim_net module
 -export_type([
               address_info/0,
@@ -60,7 +63,7 @@
               network_interface_name/0,
               network_interface_index/0
              ]).
--endif.
+
 
 -deprecated({call,      4, eventually}).
 -deprecated({cast,      4, eventually}).
@@ -70,34 +73,23 @@
 -deprecated({sleep,     1, eventually}).
 
 
--ifdef(USE_ESOCK).
--type name_info_flags()         :: prim_net:name_info_flags().
--type name_info_flag()          :: prim_net:name_info_flag().
--type name_info_flag_ext()      :: prim_net:name_info_flag_ext().
--type name_info()               :: prim_net:name_info().
--type address_info()            :: prim_net:address_info().
--type network_interface_name()  :: prim_net:network_interface_name().
--type network_interface_index() :: prim_net:network_interface_index().
-
-%% -type name_info_flags()         :: [name_info_flag()|name_info_flag_ext()].
-%% -type name_info_flag()          :: namereqd |
-%%                                    dgram |
-%%                                    nofqdn |
-%%                                    numerichost |
-%%                                    nomericserv.
-%% -type name_info_flag_ext()      :: idn |
-%%                                    idna_allow_unassigned |
-%%                                    idna_use_std3_ascii_rules.
-%% -type name_info()               :: #{host    := string(),
-%%                                      service := string()}.
-%% -type address_info()            :: #{family   := socket:domain(),
-%%                                      socktype := socket:type(),
-%%                                      protocol := socket:protocol(),
-%%                                      address  := socket:sockaddr()}.
-%% -type network_interface_name()  :: string().
-%% -type network_interface_index() :: non_neg_integer().
-
--endif.
+-type name_info_flags()         :: [name_info_flag()|name_info_flag_ext()].
+-type name_info_flag()          :: namereqd |
+                                   dgram |
+                                   nofqdn |
+                                   numerichost |
+                                   nomericserv.
+-type name_info_flag_ext()      :: idn |
+                                   idna_allow_unassigned |
+                                   idna_use_std3_ascii_rules.
+-type name_info()               :: #{host    := string(),
+                                     service := string()}.
+-type address_info()            :: #{family   := socket:domain(),
+                                     socktype := socket:type(),
+                                     protocol := socket:protocol(),
+                                     address  := socket:sockaddr()}.
+-type network_interface_name()  :: string().
+-type network_interface_index() :: non_neg_integer().
 
 
 %% ===========================================================================
@@ -114,8 +106,6 @@ sleep(T) -> receive after T -> ok end.
 relay(X) -> slave:relay(X).
 
 
--ifdef(USE_ESOCK).
-
 %% ===========================================================================
 %%
 %% Administrative and utility API
@@ -124,14 +114,26 @@ relay(X) -> slave:relay(X).
 
 -spec info() -> list().
 
+-ifdef(USE_ESOCK).
 info() ->
     prim_net:info().
+-else.
+-dialyzer({nowarn_function, info/0}).
+info() ->
+    erlang:error(notsup).
+-endif.
 
 
 -spec command(Cmd :: term()) -> term().
 
+-ifdef(USE_ESOCK).
 command(Cmd) ->
     prim_net:command(Cmd).
+-else.
+-dialyzer({nowarn_function, command/1}).
+command(_Cmd) ->
+    erlang:error(notsup).
+-endif.
 
 
 
@@ -151,8 +153,14 @@ command(Cmd) ->
       HostName :: string(),
       Reason   :: term().
 
+-ifdef(USE_ESOCK).
 gethostname() ->
     prim_net:gethostname().
+-else.
+-dialyzer({nowarn_function, gethostname/0}).
+gethostname() ->
+    erlang:error(notsup).
+-endif.
 
 
 %% ===========================================================================
@@ -175,6 +183,7 @@ getnameinfo(SockAddr) ->
       Info     :: name_info(),
       Reason   :: term().
 
+-ifdef(USE_ESOCK).
 getnameinfo(SockAddr, [] = _Flags) ->
     getnameinfo(SockAddr, undefined);
 getnameinfo(#{family := Fam, addr := _Addr} = SockAddr, Flags)
@@ -184,7 +193,18 @@ getnameinfo(#{family := Fam, addr := _Addr} = SockAddr, Flags)
 getnameinfo(#{family := Fam, path := _Path} = SockAddr, Flags)
   when (Fam =:= local) andalso (is_list(Flags) orelse (Flags =:= undefined)) ->
     prim_net:getnameinfo(SockAddr, Flags).
-
+-else.
+-dialyzer({nowarn_function, getnameinfo/2}).
+getnameinfo(SockAddr, [] = _Flags) ->
+    getnameinfo(SockAddr, undefined);
+getnameinfo(#{family := Fam, addr := _Addr} = _SockAddr, Flags)
+  when ((Fam =:= inet) orelse (Fam =:= inet6)) andalso 
+       (is_list(Flags) orelse (Flags =:= undefined)) ->
+    erlang:error(notsup);
+getnameinfo(#{family := Fam, path := _Path} = _SockAddr, Flags)
+  when (Fam =:= local) andalso (is_list(Flags) orelse (Flags =:= undefined)) ->
+    erlang:error(notsup).
+-endif.
 
 
 %% ===========================================================================
@@ -216,11 +236,21 @@ getaddrinfo(Host) when is_list(Host) ->
       Info    :: [address_info()],
       Reason  :: term().
 
+-ifdef(USE_ESOCK).
 getaddrinfo(Host, Service)
   when (is_list(Host) orelse (Host =:= undefined)) andalso
        (is_list(Service) orelse (Service =:= undefined)) andalso
        (not ((Service =:= undefined) andalso (Host =:= undefined))) ->
     prim_net:getaddrinfo(Host, Service).
+-else.
+-dialyzer({nowarn_function, getaddrinfo/2}).
+getaddrinfo(Host, Service)
+  when (is_list(Host) orelse (Host =:= undefined)) andalso
+       (is_list(Service) orelse (Service =:= undefined)) andalso
+       (not ((Service =:= undefined) andalso (Host =:= undefined))) ->
+    erlang:error(notsup).
+-endif.
+
 
 
 
@@ -236,8 +266,14 @@ getaddrinfo(Host, Service)
       Idx    :: network_interface_index(),
       Reason :: term().
 
+-ifdef(USE_ESOCK).
 if_name2index(If) when is_list(If) ->
     prim_net:if_name2index(If).
+-else.
+-dialyzer({nowarn_function, if_name2index/1}).
+if_name2index(If) when is_list(If) ->
+    erlang:error(notsup).
+-endif.
 
 
 
@@ -253,8 +289,14 @@ if_name2index(If) when is_list(If) ->
       Name   :: network_interface_name(),
       Reason :: term().
 
+-ifdef(USE_ESOCK).
 if_index2name(Idx) when is_integer(Idx) ->
     prim_net:if_index2name(Idx).
+-else.
+-dialyzer({nowarn_function, if_index2name/1}).
+if_index2name(Idx) when is_integer(Idx) ->
+    erlang:error(notsup).
+-endif.
 
 
 
@@ -270,9 +312,13 @@ if_index2name(Idx) when is_integer(Idx) ->
       If     :: network_interface_name(),
       Reason :: term().
 
+-ifdef(USE_ESOCK).
 if_names() ->
     prim_net:if_names().
+-else.
+-dialyzer({nowarn_function, if_names/0}).
+if_names() ->
+    erlang:error(notsup).
+-endif.
 
 
-
--endif.