ping_setopt(3)

📦
version 1.10.0 · 8 versions
, in alpine 3.24, epel 10, epel 9, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0

💖 ping_setopt — the liboping options-setter, bestie edition ✨

okay so this is ping_setopt(3) from the liboping manual, and it's genuinely one of my faves because it's the lil' control panel for your ping object. let's get into it 🎀

🌸 NAME 🌸

ping_setopt — set options for a liboping object. that's it, that's the vibe.

✨ SYNOPSIS ✨

#include <oping.h>

int ping_setopt (pingobj_t *obj, int opt, void *val);

🦋 DESCRIPTION 🦋

so basically ping_setopt sets options that apply to all hosts already chillin' with the object obj, and the hosts that haven't even been added yet. future hosts? covered. periodt. 💅

the obj argument is a pointer to a liboping object, exactly the kind you get back from ping_construct(3).

the opt argument says which option you're setting. use one of these constants, bestie. you can check at compile time whether the library even supports the one you want by using #ifdef — and honestly it's recommended that you check for the features you want using the OPING_VERSION define. iykyk 👑

the options, one by one 🫶

  • PING_OPT_TIMEOUT — how long to wait for an "echo reply" to come back, measured in seconds. here val points at memory that gets read as a double, and it must be greater than zero. the default is PING_DEF_TIMEOUT. ⏳
  • PING_OPT_TTL — the value that gets written into the time-to-live (= TTL) field of the generated ICMP packets. the memory val points at is read as an integer. valid values go from 1 through 255. default is PING_DEF_TTL. 🌈
  • PING_OPT_AF — the address family to use. val points at memory read as an integer, and it must be either AF_UNSPEC, AF_INET, or AF_INET6. heads up: this one only affects hosts that get added after you set it. default is PING_DEF_AF. and ooh — if you change this option and a source address is already set (see PING_OPT_SOURCE), that setting will be reset. no takebacks 🫠
  • PING_OPT_DATA — sets the data to send. the value you pass has to 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 literally the behavior of the ping(1) command. iconic. 📦
  • PING_OPT_SOURCE — sets the source address to use. the value you pass has to be a char-pointer to a null-terminated string, and that string specifies either a numerical network address or a network hostname. this option ignores the address family setting (the one from PING_OPT_AF) and sets the object's address family according to whichever source address you assigned. it does its own thing fr fr 🧚
  • PING_OPT_DEVICE — sets the outgoing network device to be used. the value you pass has to be a char-pointer to a null-terminated string naming an interface (e. g. "eth0"). > ⚠️ please note: 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 val points at is read as a "uint8_t". that byte gets passed to setsockopt(2) without modification, using the "IP_TOS" (IPv4) or "IPV6_TCLASS" (IPv6) option. > 🚨 it is the caller's responsibility to choose a valid bit combination — that's on you, bestie. for the details, go read the ip(7) and ipv6(7) manual pages, plus RFC 2474. 📚
  • PING_OPT_MARK — marks (as in netfilter) outgoing packets using the SO_MARK socket option. takes an int* pointer as its value. > 🔐 setting this requires CAP_NET_ADMIN under Linux. and on platforms that don't have SO_MARK, it fails with "operation not supported". 🍓

about val 🌟

the val argument is a pointer to the new value. it must not be NULL. it gets dereferenced depending on what opt is set to (see alllll the way above ☝️). and good news: the memory that val points to is not changed. your data is safe, bestie. 💜

👑 RETURN VALUE 👑

ping_setopt returns zero upon success, or less than zero upon failure. short and sweet.

🔥 SEE ALSO 🔥

🎀 AUTHOR 🎀

liboping is written by Florian "octo" Forster <ff at octo.it>. its homepage can be found at <http://noping.cc/>. 🌈

Copyright (c) 2006-2017 by Florian "octo" Forster.

okay that's the whole page, bestie — we ate that up 💅✨ this was liboping version 1.10.0, dated 2017-05-11, and that's the ping_setopt(3) tea. mwah 🫶💖

📦 where this page comes from