aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorMicael Karlberg <[email protected]>2018-07-04 18:37:32 +0200
committerMicael Karlberg <[email protected]>2018-09-18 14:50:18 +0200
commiteacb95d88db1e1123d17288e71835b457bcf4016 (patch)
tree85815c2c5e25f6585732b83ae90c6424d184e949
parente39e25d84405e13ca0ce476e3ba473510e5548de (diff)
downloadotp-eacb95d88db1e1123d17288e71835b457bcf4016.tar.gz
otp-eacb95d88db1e1123d17288e71835b457bcf4016.tar.bz2
otp-eacb95d88db1e1123d17288e71835b457bcf4016.zip
[socket-doc-nif] Updated documentation
Updated the documentation of recv, recvfrom, send and sendto. Also added doc for functions peername and sockname. OTP-14831
-rw-r--r--erts/doc/src/socket.xml37
-rw-r--r--erts/preloaded/ebin/socket.beambin42660 -> 43472 bytes
-rw-r--r--erts/preloaded/src/socket.erl157
3 files changed, 154 insertions, 40 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
index 3efa412b8a..6f116abca9 100644
--- a/erts/doc/src/socket.xml
+++ b/erts/doc/src/socket.xml
@@ -63,13 +63,16 @@
<name name="ip_address"/>
</datatype>
<datatype>
- <name name="in4_sockaddr"/>
+ <name name="sockaddr"/>
</datatype>
<datatype>
- <name name="in6_sockaddr"/>
+ <name name="sockaddr_in4"/>
</datatype>
<datatype>
- <name name="in_sockaddr"/>
+ <name name="sockaddr_in6"/>
+ </datatype>
+ <datatype>
+ <name name="sockaddr_un"/>
</datatype>
<datatype>
<name name="port_number"/>
@@ -244,8 +247,18 @@
</func>
<func>
+ <name name="peername" arity="1"/>
+ <fsummary>Get name of connected socket peer.</fsummary>
+ <desc>
+ <p>Returns the address of the peer connected to the socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recv" arity="1"/>
<name name="recv" arity="2"/>
- <name name="recv" arity="3"/>
+ <name name="recv" arity="3" clause_i="1"/>
+ <name name="recv" arity="3" clause_i="2"/>
<name name="recv" arity="4"/>
<fsummary>Receive a message from a socket.</fsummary>
<desc>
@@ -259,7 +272,9 @@
<func>
<name name="recvfrom" arity="1"/>
<name name="recvfrom" arity="2"/>
- <name name="recvfrom" arity="3"/>
+ <name name="recvfrom" arity="3" clause_i="1"/>
+ <name name="recvfrom" arity="3" clause_i="2"/>
+ <name name="recvfrom" arity="3" clause_i="3"/>
<name name="recvfrom" arity="4"/>
<fsummary>Receive a message from a socket.</fsummary>
<desc>
@@ -279,7 +294,8 @@
<func>
<name name="send" arity="2"/>
- <name name="send" arity="3"/>
+ <name name="send" arity="3" clause_i="1"/>
+ <name name="send" arity="3" clause_i="2"/>
<name name="send" arity="4"/>
<fsummary>Send a message on a socket.</fsummary>
<desc>
@@ -288,6 +304,7 @@
</func>
<func>
+ <name name="sendto" arity="3"/>
<name name="sendto" arity="4"/>
<name name="sendto" arity="5"/>
<fsummary>Send a message on a socket.</fsummary>
@@ -329,6 +346,14 @@
</desc>
</func>
+ <func>
+ <name name="sockname" arity="1"/>
+ <fsummary>Get socket name.</fsummary>
+ <desc>
+ <p>Returns the current address to which the socket is bound.</p>
+ </desc>
+ </func>
+
</funcs>
<section>
<title>Examples</title>
diff --git a/erts/preloaded/ebin/socket.beam b/erts/preloaded/ebin/socket.beam
index 99a9f0f749..8a3dab1313 100644
--- a/erts/preloaded/ebin/socket.beam
+++ b/erts/preloaded/ebin/socket.beam
Binary files differ
diff --git a/erts/preloaded/src/socket.erl b/erts/preloaded/src/socket.erl
index 79b8471e08..a1db295a79 100644
--- a/erts/preloaded/src/socket.erl
+++ b/erts/preloaded/src/socket.erl
@@ -88,7 +88,10 @@
udp_socket_option/0,
sctp_socket_option/0,
- ip_tos_flag/0
+ ip_tos_flag/0,
+
+
+ msg_hdr/0
]).
%% We support only a subset of all domains.
@@ -385,22 +388,23 @@
-type shutdown_how() :: read | write | read_write.
+%% This is just a place-holder
-record(msg_hdr,
{
- %% Optional address
- %% On an unconnected socket this is used to specify the target
- %% address for a datagram.
- %% For a connected socket, this field should be specifiedset to [].
- name :: list(),
-
- %% Scatter/gather array
- iov :: [binary()], % iovec(),
-
- %% Ancillary (control) data
- ctrl :: binary(),
-
- %% Unused
- flags = [] :: list()
+ %% Optional address
+ %% On an unconnected socket this is used to specify the target
+ %% address for a datagram.
+ %% For a connected socket, this field should be specifiedset to [].
+ name :: list(),
+
+ %% Scatter/gather array
+ iov :: [binary()], % iovec(),
+
+ %% Ancillary (control) data
+ ctrl :: binary(),
+
+ %% Unused
+ flags = [] :: list()
}).
-type msg_hdr() :: #msg_hdr{}.
@@ -858,9 +862,25 @@ do_accept(LSockRef, SI, Timeout) ->
%% send, sendto, sendmsg - send a message on a socket
%%
+-spec send(Socket, Data) -> ok | {error, Reason} when
+ Socket :: socket(),
+ Data :: iodata(),
+ Reason :: term().
+
send(Socket, Data) ->
send(Socket, Data, ?SOCKET_SEND_FLAGS_DEFAULT, ?SOCKET_SEND_TIMEOUT_DEFAULT).
+-spec send(Socket, Data, Flags) -> ok | {error, Reason} when
+ Socket :: socket(),
+ Data :: iodata(),
+ Flags :: send_flags(),
+ Reason :: term()
+ ; (Socket, Data, Timeout) -> ok | {error, Reason} when
+ Socket :: socket(),
+ Data :: iodata(),
+ Timeout :: timeout(),
+ Reason :: term().
+
send(Socket, Data, Flags) when is_list(Flags) ->
send(Socket, Data, Flags, ?SOCKET_SEND_TIMEOUT_DEFAULT);
send(Socket, Data, Timeout) ->
@@ -932,14 +952,27 @@ do_send(SockRef, Data, EFlags, Timeout) ->
%% ---------------------------------------------------------------------------
%%
+-spec sendto(Socket, Data, Dest) ->
+ ok | {error, Reason} when
+ Socket :: socket(),
+ Data :: binary(),
+ Dest :: null | sockaddr(),
+ Reason :: term().
+
sendto(Socket, Data, Dest) ->
sendto(Socket, Data, Dest, ?SOCKET_SENDTO_FLAGS_DEFAULT).
+-spec sendto(Socket, Data, Dest, Flags) -> ok | {error, Reason} when
+ Socket :: socket(),
+ Data :: binary(),
+ Dest :: null | sockaddr(),
+ Flags :: send_flags(),
+ Reason :: term().
+
sendto(Socket, Data, Dest, Flags) ->
sendto(Socket, Data, Dest, Flags, ?SOCKET_SENDTO_TIMEOUT_DEFAULT).
--spec sendto(Socket, Data, Dest, Flags, Timeout) ->
- ok | {error, Reason} when
+-spec sendto(Socket, Data, Dest, Flags, Timeout) -> ok | {error, Reason} when
Socket :: socket(),
Data :: binary(),
Dest :: null | sockaddr(),
@@ -1014,7 +1047,7 @@ do_sendto(SockRef, Data, Dest, EFlags, Timeout) ->
%% -spec sendmsg(Socket, MsgHdr, Flags) -> ok | {error, Reason} when
%% Socket :: socket(),
-%% MsgHdr :: msg_header(),
+%% MsgHdr :: msg_hdr(),
%% Flags :: send_flags(),
%% Reason :: term().
@@ -1106,14 +1139,38 @@ do_sendto(SockRef, Data, Dest, EFlags, Timeout) ->
%% Flags - A list of "options" for the read.
%% Timeout - Time-out in milliseconds.
+-spec recv(Socket) -> {ok, Data} | {error, Reason} when
+ Socket :: socket(),
+ Data :: binary(),
+ Reason :: term().
+
recv(Socket) ->
recv(Socket, 0).
+-spec recv(Socket, Length) -> {ok, Data} | {error, Reason} when
+ Socket :: socket(),
+ Length :: non_neg_integer(),
+ Data :: binary(),
+ Reason :: term().
+
recv(Socket, Length) ->
recv(Socket, Length,
?SOCKET_RECV_FLAGS_DEFAULT,
?SOCKET_RECV_TIMEOUT_DEFAULT).
+-spec recv(Socket, Length, Flags) -> {ok, Data} | {error, Reason} when
+ Socket :: socket(),
+ Length :: non_neg_integer(),
+ Flags :: recv_flags(),
+ Data :: binary(),
+ Reason :: term()
+ ; (Socket, Length, Timeout) -> {ok, Data} | {error, Reason} when
+ Socket :: socket(),
+ Length :: non_neg_integer(),
+ Timeout :: timeout(),
+ Data :: binary(),
+ Reason :: term().
+
recv(Socket, Length, Flags) when is_list(Flags) ->
recv(Socket, Length, Flags, ?SOCKET_RECV_TIMEOUT_DEFAULT);
recv(Socket, Length, Timeout) ->
@@ -1270,14 +1327,51 @@ do_recv(_SockRef, _RecvRef, _Length, _EFlags, _Acc, _Timeout) ->
%% is needed, possibly with a then adjusted buffer size.
%%
+-spec recvfrom(Socket) -> {ok, {Source, Data}} | {error, Reason} when
+ Socket :: socket(),
+ Source :: sockaddr() | undefined,
+ Data :: binary(),
+ Reason :: term().
+
recvfrom(Socket) ->
recvfrom(Socket, 0).
+-spec recvfrom(Socket, BufSz) -> {ok, {Source, Data}} | {error, Reason} when
+ Socket :: socket(),
+ BufSz :: non_neg_integer(),
+ Source :: sockaddr() | undefined,
+ Data :: binary(),
+ Reason :: term().
+
recvfrom(Socket, BufSz) ->
recvfrom(Socket, BufSz,
?SOCKET_RECV_FLAGS_DEFAULT,
?SOCKET_RECV_TIMEOUT_DEFAULT).
+-spec recvfrom(Socket, Flags, Timeout) ->
+ {ok, {Source, Data}} | {error, Reason} when
+ Socket :: socket(),
+ Flags :: recv_flags(),
+ Timeout :: timeout(),
+ Source :: sockaddr() | undefined,
+ Data :: binary(),
+ Reason :: term()
+ ; (Socket, BufSz, Flags) ->
+ {ok, {Source, Data}} | {error, Reason} when
+ Socket :: socket(),
+ BufSz :: non_neg_integer(),
+ Flags :: recv_flags(),
+ Source :: sockaddr() | undefined,
+ Data :: binary(),
+ Reason :: term()
+ ; (Socket, BufSz, Timeout) ->
+ {ok, {Source, Data}} | {error, Reason} when
+ Socket :: socket(),
+ BufSz :: non_neg_integer(),
+ Timeout :: timeout(),
+ Source :: sockaddr() | undefined,
+ Data :: binary(),
+ Reason :: term().
recvfrom(Socket, Flags, Timeout) when is_list(Flags) ->
recvfrom(Socket, 0, Flags, Timeout);
@@ -1286,7 +1380,8 @@ recvfrom(Socket, BufSz, Flags) when is_list(Flags) ->
recvfrom(Socket, BufSz, Timeout) ->
recvfrom(Socket, BufSz, ?SOCKET_RECV_FLAGS_DEFAULT, Timeout).
--spec recvfrom(Socket, BufSz, Flags, Timeout) -> {ok, {Source, Data}} | {error, Reason} when
+-spec recvfrom(Socket, BufSz, Flags, Timeout) ->
+ {ok, {Source, Data}} | {error, Reason} when
Socket :: socket(),
BufSz :: non_neg_integer(),
Flags :: recv_flags(),
@@ -1305,21 +1400,16 @@ recvfrom(#socket{ref = SockRef}, BufSz, Flags, Timeout)
do_recvfrom(SockRef, BufSz, EFlags, Timeout) ->
TS = timestamp(Timeout),
RecvRef = make_ref(),
- p("recvfrom -> try recvfrom"),
case nif_recvfrom(SockRef, RecvRef, BufSz, EFlags) of
{ok, {_Source, _NewData}} = OK ->
- p("recvfrom -> ok: "
- "~n Source: ~p", [_Source]),
OK;
{error, eagain} ->
- p("recvfrom -> eagain - wait for select ready-input"),
%% There is nothing just now, but we will be notified when there
%% is something to read (a select message).
NewTimeout = next_timeout(TS, Timeout),
receive
{select, SockRef, RecvRef, ready_input} ->
- p("recvfrom -> eagain - got select ready-input"),
do_recvfrom(SockRef, BufSz, EFlags,
next_timeout(TS, Timeout));
@@ -1333,7 +1423,6 @@ do_recvfrom(SockRef, BufSz, EFlags, Timeout) ->
end;
{error, _Reason} = ERROR ->
- p("recvfrom -> error: ~p", [_Reason]),
ERROR
end.
@@ -1345,7 +1434,7 @@ do_recvfrom(SockRef, BufSz, EFlags, Timeout) ->
%% -spec recvmsg(Socket, [out] MsgHdr, Flags) -> {ok, Data} | {error, Reason} when
%% Socket :: socket(),
-%% MsgHdr :: msg_header(),
+%% MsgHdr :: msg_hdr(),
%% Flags :: recv_flags(),
%% Data :: binary(),
%% Reason :: term().
@@ -2227,16 +2316,16 @@ tdiff(T1, T2) ->
-p(F) ->
- p(F, []).
+%% p(F) ->
+%% p(F, []).
-p(F, A) ->
- p(get(sname), F, A).
+%% p(F, A) ->
+%% p(get(sname), F, A).
-p(undefined, F, A) ->
- p("***", F, A);
-p(SName, F, A) ->
- io:format("[~s,~p] " ++ F ++ "~n", [SName, self()|A]).
+%% p(undefined, F, A) ->
+%% p("***", F, A);
+%% p(SName, F, A) ->
+%% io:format("[~s,~p] " ++ F ++ "~n", [SName, self()|A]).