LIBSCAMPERCTRL(3)

🌸 NAME 🌸

okay bestie, welcome to the libscamperctrl(3) page — this is the scamper control library, and it's giving "let's run measurements across a whole set of external scamper processes" energy. 💅

📚 LIBRARY 📚

This is the scamper control library. The link line is libscamperctrl -lscamperctrl. ✨

🧚 SYNOPSIS 🧚

#include <libscamperctrl.h>

💖 DESCRIPTION 💖

Okay so the libscamperctrl library gives you an application programming interface (API) to execute measurements using the control mechanisms that are available for a set of external scamper(1) processes. No cap. 🦋

💅 ROUTINES 💅

🌟 scamper_ctrl_t * scamper_ctrl_alloc(scamper_ctrl_cb_t cb) 🌟

Allocate a control structure for managing a set of scamper(1) instances. The caller has to pass a callback function, and that callback must be defined like this:

void cb(scamper_inst_t *inst, uint8_t type, scamper_task_t *task, const
void *data, size_t len)

Every time there is an event, scamper_ctrl_wait() calls this function. It hands you a pointer to the scamper instance that the event is in relation to as the first parameter. The second parameter identifies the type of the event, and it could be one of these:

• SCAMPER_CTRL_TYPE_DATA — a measurement task has completed. The task pointer points to the task returned by scamper_inst_do(). The data pointer points to the data, and the length parameter reports the number of bytes of data. The programmer does not have to call scamper_task_free() unless they kept a copy of the task pointer by calling scamper_task_use().
• SCAMPER_CTRL_TYPE_MORE — the scamper instance is requesting another command to execute.
• SCAMPER_CTRL_TYPE_ERR — the command was not accepted.
• SCAMPER_CTRL_TYPE_EOF — the scamper instance disconnected.
• SCAMPER_CTRL_TYPE_FATAL — the library encountered a fatal error.

🫶 int scamper_ctrl_wait(scamper_ctrl_t *ctrl, struct timeval *to) 🫶

Wait for events from the collection of scamper(1) instances. If the timeout parameter is null, then the wait function will block indefinitely until an event occurs. Otherwise, this function will return after the length of time specified in the timeout parameter has elapsed, or after it has called the callback function for an event. ⏳

🎀 void scamper_ctrl_free(scamper_ctrl_t *ctrl) 🎀

Cleanup the resources associated with managing the set of scamper(1) instances. Goodbye, little resources. 💖

⭐ int scamper_ctrl_isdone(scamper_ctrl_t *ctrl) ⭐

Returns 0 if there is at least one active scamper instance. Returns non-zero if there are no active scamper instances. Vibe check: are we done or not? 👑

🌈 scamper_inst_t * scamper_inst_unix(scamper_ctrl_t *ctrl, const char *path) 🌈

Attach to a local scamper instance via the unix domain socket at the supplied path. 🔌

🍓 scamper_inst_t * scamper_inst_inet(scamper_ctrl_t *ctrl, const char *addr, uint16_t port) 🍓

Attach to a local scamper instance via the supplied IP address and port. 🌐

🧚 scamper_inst_t * scamper_inst_remote(scamper_ctrl_t *ctrl, const char *path) 🧚

Attach to a remote scamper instance via the unix domain socket at the supplied path. The remote scamper instance is connected to the local machine using a sc_remoted(3) process. Remote but still connected, iykyk. 🦋

💜 void scamper_inst_free(scamper_inst_t *inst) 💜

Disconnect and then free the resources associated with the instance. ✂️

🔥 scamper_task_t * scamper_inst_do(scamper_inst_t *inst, const char *cmd) 🔥

Issue a command on the supplied instance. The returned task pointer uniquely identifies the task. If a programmer wishes to keep a copy of the task pointer in the process, they must call scamper_task_use() to keep a reference, and then call scamper_task_free() once done with it. 🫡

🌸 int scamper_inst_done(scamper_inst_t *inst) 🌸

Send a done command, which will cause the scamper(1) instance to disconnect when it has returned all completed measurements. Periodt. 💅

💀 int scamper_task_halt(scamper_task_t *task) 💀

Issue a halt command for the task. If the command has not been issued to scamper yet, then no DATA object will be returned; otherwise, a DATA object will be returned. 🛑

🎀 void scamper_task_free(scamper_task_t *task) 🎀

Free task resources, if the programmer previously called scamper_task_use() to advise libscamperctrl(3) that the programmer would also be keeping a copy of a task pointer. 🧹

✨ scamper_task_t * scamper_task_use(scamper_task_t *task) ✨

Advise libscamperctrl(3) that the programmer is keeping a copy of the task in their program. Not me remembering the reference bookkeeping and feeling iconic. 💖

🌈 SEE ALSO 🌈

• scamper(1)
• sc_remoted(1)
• libscamperfile(3)

M. Luckie, Scamper: a Scalable and Extensible Packet Prober for Active Measurement of the Internet, Proc. ACM/SIGCOMM Internet Measurement Conference 2010.

👑 AUTHORS 👑

libscamperctrl was written by Matthew Luckie <mjl@luckie.org.nz>. 🫶

---

Debian, February 24, 2023, LIBSCAMPERCTRL(3) — byeee, bestie, go measure something cute 💖✨