--- name: "ping_setopt" section: "3" platform: "linux" package: "liboping-dev" version: "1.10.0-5+b5" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/ping_setopt" --- # ping\_setopt(3) Set options for a liboping object ## NAME ping\_setopt - Set options for a liboping object ## SYNOPSIS ``` #include int ping_setopt (pingobj_t *obj, int opt, void *val); ``` ## DESCRIPTION The **ping\_setopt** method sets options that apply to all hosts associated with the object *obj* and hosts that are yet to be added to the object. The *obj* argument is a pointer to an *liboping* object, as returned by [**ping\_construct**(3)](/ping_construct/3.md). The *opt* argument specifies the option to set. Use one of the following constants. You can check if the required constant is supported by the library at compile time using `"#ifdef"`. It is recommended to check for desired features using the `"OPING_VERSION"` define. - **PING\_OPT\_TIMEOUT** The time to wait for a "echo reply" to be received; in seconds. In this case the memory pointed to by *val* is interpreted as a double value and must be greater than zero. The default is **PING\_DEF\_TIMEOUT**. - **PING\_OPT\_TTL** The value written into the time-to-live (= TTL) field of generated ICMP packets. The memory pointed to by *val* is interpreted as an integer. Valid values are 1 through 255. Default is **PING\_DEF\_TTL**. - **PING\_OPT\_AF** The address family to use. The memory pointed to by *val* is interpreted as an integer and must be either **AF\_UNSPEC**, **AF\_INET**, or **AF\_INET6**. This option only affects hosts that are being added **after** this option has been set. Default is **PING\_DEF\_AF**. If you change this option, and a source address is set (see **PING\_OPT\_SOURCE**) that setting will be reset. - **PING\_OPT\_DATA** Set the data to send. The value passed must be a char-pointer to a null-terminated string. By default a 56 byte long string is used so that the packet size of an ICMPv4 packet is exactly 64 bytes. That's the behavior of the [**ping**(1)](/ping/1.md) command. - **PING\_OPT\_SOURCE** Set the source address to use. The value passed must be a char-pointer to a null-terminated string specifying either a numerical network address or network hostname. This option will ignore the address family setting (as set with **PING\_OPT\_AF**) and will set the object's address family according to the source address assigned. - **PING\_OPT\_DEVICE** Set the outgoing network device to be used. The value passed must be a char-pointer to a null-terminated string specifying an interface name (e. g. `"eth0"`). Please note that this might not be supported by all operating systems. In that case, **ping\_setopt** sets the error to `"operation not supported"`. - **PING\_OPT\_QOS** Sets the *Quality of Service* flags that should be used when crafting ICMP and ICMPv6 packets. The memory pointed to by *val* is interpreted as a `"uint8_t"`. The byte is passed to [**setsockopt**(2)](/setsockopt/2.md) without modification, using the `"IP_TOS"` (IPv4) or `"IPV6_TCLASS"` (IPv6) option. It is the caller's responsibility to chose a valid bit combination. For details, read the [**ip**(7)](/ip/7.md) and [**ipv6**(7)](/ipv6/7.md) manual pages, as well as *RFC 2474*. - **PING\_OPT\_MARK** Mark (as in netfilter) outgoing packets using the SO\_MARK socket option. Takes an int\* pointer as a value. Setting this requires CAP\_NET\_ADMIN under Linux. Fails with `"operation not supported"` on platforms which don't have SO\_MARK. The *val* argument is a pointer to the new value. It must not be NULL. It is dereferenced depending on the value of the *opt* argument, see above. The memory pointed to by *val* is not changed. ## RETURN VALUE **ping\_setopt** returns zero upon success or less than zero upon failure. ## SEE ALSO [**ping\_construct**(3)](/ping_construct/3.md), [**liboping**(3)](/liboping/3.md) ## AUTHOR liboping is written by Florian "octo" Forster \. Its homepage can be found at \. Copyright (c) 2006-2017 by Florian "octo" Forster.