View Source gen_icmp (gen_icmp v0.5.6)

Link to this section Summary

Link to this section Functions

Link to this function

addr_list(Family, Hosts, Multi)

View Source
Close the ICMP socket
Link to this function

code_change(OldVsn, State, Extra)

View Source
Link to this function

controlling_process(Ref, Pid)

View Source

Change the controlling process of the ICMP socket

Change the process owning the socket. Allows another process to receive the ICMP responses.
Link to this function

echo(Family, Id, Seq, Payload)

View Source
Link to this function

handle_call(Request, From, State)

View Source
Link to this function

handle_info(Info, State)

View Source
Link to this function

icmp6_filter_setblock(Type0, Filter)

View Source
Link to this function

icmp6_filter_setblockall()

View Source
Link to this function

icmp6_filter_setpass(Type0, Filter)

View Source
Link to this function

icmp6_filter_setpassall()

View Source
Link to this function

icmp6_filter_willblock(Type0, Filter)

View Source
Link to this function

icmp6_filter_willpass(Type0, Filter)

View Source

Open an ICMP socket

By default, the ICMP socket is opened in {active,false} mode. No packets will be received by the socket. setopts/2 can be used to place the socket in {active,true} mode.

See the procket README for the raw socket options and for instructions on setting up the setuid helper.

gen_icmp first attempts to natively open the socket and falls back to forking the setuid helper program if beam does not have the appropriate privileges. Privileges to open a raw socket can be given by, for example, running as root or, on Linux, granting the CAP_NET_RAW capability to beam:

setcap cap_net_raw=ep /usr/local/lib/erlang/erts-5.8.3/bin/beam.smp

Only the owning process will receive ICMP packets (see controlling_process/2 to change the owner). The process owning the raw socket will receive all ICMP packets sent to the host.

Messages sent to the controlling process are:

{icmp, Socket, Address, TTL, Packet}

Where:

* Socket is the pid of the gen_icmp process

* Address is a tuple representing the IPv4 or IPv6 source address

* TTL: IPv4: TTL taken from the IP header

* TTL: IPv6: the socket's hop limit returned from getsockopt(IPV6_UNICAST_HOPS) (this is not the packet's TTL, it is the socket's max TTL)

* Packet is the complete ICMP packet including the ICMP headers
Link to this function

packet(_, Header, Payload)

View Source
Link to this function

ping(Socket, Hosts, Options)

View Source

Send an ICMP ECHO_REQUEST

ping/1 is a convenience function to send a single ping packet. The argument to ping/1 can be either a hostname or a list of hostnames.

To prevent the process mailbox from being flooded with ICMP messages, ping/3 will put the socket into {active,false} mode after completing.

The ping/3 function blocks until either an ICMP ECHO REPLY is received from all hosts or Timeout is reached.

Id and sequence are used to differentiate ping responses. Usually, the sequence is incremented for each ping in one run.

A list of responses is returned. If the ping was successful, the elapsed time in milliseconds is included (calculated by subtracting the current time from the time we sent in the ICMP ECHO packet and returned to us in the ICMP ECHOREPLY payload) where:

* Host: the provided hostname

* Address: the resolved IPv4 or IPv6 network address represented as a 4 or 8-tuple used in the ICMP echo request

* ReplyAddr: the IPv4 or IPv6 network address originating the ICMP echo reply

The timeout is set for all ICMP packets and is set after all packets have been sent out.

ping/1 and ping/2 open and close an ICMP socket for the user. For best performance, ping/3 should be used instead, with the socket being maintained between runs.

By default only one address per hostname is pinged. To enable pinging all addresses per hostname pass {multi, true} to options.

A ping payload contains an 8 byte timestamp in microseconds. When creating a custom payload, the first 8 bytes of the ICMP echo reply payload will be used for calculating the elapsed time. To disable this behaviour, use the option {timestamp,false} (the elapsed time in the return value will be set to 0).

The timeout defaults to 5 seconds.

ICMPv6 sockets can restrict which ICMPv6 types are received by the socket using the filter option. The filter argument is a binary generated using the icmp6_filter functions described below.

The default filter allows: ICMP6_ECHO_REPLY, ICMP6_DST_UNREACH, ICMP6_PACKET_TOO_BIG, ICMP6_TIME_EXCEEDED and ICMP6_PARAM_PROB. Note: ping/3 does not restore the original filter on the socket.

Read data from an ICMP socket

This function receives a packet from a socket in passive mode.

The optional Timeout parameter specifies a timeout in milliseconds. The default value is infinity.
Link to this function

recv(Ref, Length, Timeout)

View Source
Link to this function

send(Ref, Address, Packet)

View Source

Send data via an ICMP socket

Like the gen_udp and gen_tcp modules, any process can send ICMP packets but only the owner will receive the responses.

Set socket options

For options, see the inet man page. Simply calls inet:setopts/2 on the gen_udp socket.

setopts/2 can be used to toggle the socket between passive and active mode:

  {ok, Socket} = gen_icmp:open(), % socket is {active,false}
  ok = gen_icmp:setopts(Socket, [{active, true}]),
  % do stuff with the socket
  ok = gen_icmp:setopts(Socket, [{active, false}]).
Link to this function

start(RawOpts, SockOpts)

View Source
Link to this function

start_link(RawOpts, SockOpts)

View Source
Link to this function

terminate(Reason, State)

View Source