VxWorks Reference Manual : Libraries

pingLib

NAME

pingLib - Packet InterNet Grouper (PING) library

ROUTINES

pingLibInit( ) - initialize the ping( ) utility
ping( ) - test that a remote host is reachable

DESCRIPTION

This library contains the ping( ) utility, which tests the reachability of a remote host.

The routine ping( ) is typically called from the VxWorks shell to check the network connection to another VxWorks target or to a UNIX host. ping( ) may also be used programmatically by applications that require such a test. The remote host must be running TCP/IP networking code that responds to ICMP echo request packets. The ping( ) routine is re-entrant, thus may be called by many tasks concurrently.

The routine pingLibInit( ) initializes the ping( ) utility and allocates resources used by this library. It is called automatically when the configuration macro INCLUDE_PING is defined.

SEE ALSO

pingLib

---

Libraries : Routines

pingLibInit( )

NAME

pingLibInit( ) - initialize the ping( ) utility

SYNOPSIS

STATUS pingLibInit (void)

DESCRIPTION

This routine allocates resources used by the ping( ) utility. It must be called before ping( ) is used. It is called automatically when the configuration macro INCLUDE_PING is defined.

RETURNS

OK, or ERROR if the ping( ) utility could not be initialized.

SEE ALSO

pingLib

---

Libraries : Routines

ping( )

NAME

ping( ) - test that a remote host is reachable

SYNOPSIS

STATUS ping
    (
    char *  host,       /* host to ping */
    int     numPackets, /* number of packets to receive */
    ulong_t options     /* option flags */
    )

DESCRIPTION

This routine tests that a remote host is reachable by sending ICMP echo request packets, and waiting for replies. It may called from the VxWorks shell as follows:

   -> ping "remoteSystem", 1, 0

where remoteSystem is either a host name that has been previously added to the remote host table by a call to hostAdd( ), or an Internet address in dot notation (for example, "90.0.0.2").

The second parameter, numPackets, specifies the number of ICMP packets to receive from the remote host. If numPackets is 1, this routine waits for a single echo reply packet, and then prints a short message indicating whether the remote host is reachable. For all other values of numPackets, timing and sequence information is printed as echoed packets are received. If numPackets is 0, this routine runs continuously.

If no replies are received within a 5-second timeout period, the routine exits. An ERROR status is returned if no echo replies are received from the remote host.

The following flags may be given through the options parameter:

PING_OPT_SILENT

Suppress output. This option is useful for applications that use ping( ) programmatically to examine the return status.

PING_OPT_DONTROUTE

Do not route packets past the local network.

PING_OPT_NOHOST

Suppress host lookup. This is useful when you have the DNS resovler but the DNS server is down and not returning host names.

NOTE

The following global variables can be set from the target shell or Windsh to configure the ping( ) parameters:

_pingTxLen

Size of the ICMP echo packet (default 64).

_pingTxInterval

Packet interval in seconds (default 1 second).

_pingTxTmo

Packet timeout in seconds (default 5 seconds).

RETURNS

OK, or ERROR if the remote host is not reachable.

ERRNO

EINVAL, S_pingLib_NOT_INITIALIZED, S_pingLib_TIMEOUT

SEE ALSO

pingLib