NAME¶

libscamperctrl — scamper control library

LIBRARY¶

scamper control library (libscamperctrl -lscamperctrl)

SYNOPSIS¶

#include <libscamperctrl.h>

DESCRIPTION¶

The libscamperctrl library provides an application programming interface (API) to execute measurements using the control mechanisms available for a set of external scamper(1) processes.

SCAMPER_CTRL_T 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 must pass a callback function, which must be defined as follows:

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

scamper_ctrl_wait() calls this function every time there is an event. It passes a pointer to the scamper instance that the event is in relation to in the first parameter. The second parameter identifies the type of the event, which could be one of the following.

• 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.

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.

void scamper_ctrl_param_set(scamper_ctrl_t *ctrl, void *param)
Associates the specified pointer with the scamper_ctrl_t structure.

void * scamper_ctrl_param_get(const scamper_ctrl_t *ctrl)
Returns the current value of the parameter set with scamper_ctrl_param_set().

const char * scamper_ctrl_strerror(const scamper_ctrl_t *ctrl)
Returns a pointer to the contents of the error buffer held internally by scamper_ctrl_t, which is set when a function associated with the scamper_ctrl_t encounters an error.

SCAMPER_MUX_T ROUTINES¶

scamper_mux_t * scamper_mux_add(scamper_ctrl_t *ctrl, const char *path)
Adds a sc_remoted(1) mux socket found at the specified path in the filesystem to the scamper_ctrl_t.

scamper_mux_t * scamper_mux_add_inet(scamper_ctrl_t *ctrl, const char *ip, uint16_t port)
Add a sc_remoted(1) mux socket found at the specified IP address and port to the scamper_ctrl_t. Note that sc_remoted(1) currently has no ability to provide a mux socket itself on IP socket, but it is possible to forward a sc_remoted(1) mux socket from a unix domain socket to an IP socket using socat(1) or ssh(1).

SCAMPER_VPSET_T ROUTINES¶

scamper_vpset_t * scamper_vpset_get(const scamper_mux_t *mux)
Return an opaque scamper_vpset_t pointer that refers to a set of scamper_vp_t. The contents of a given scamper_vpset_t does not change for the lifetime of the program. The caller must use scamper_vpset_free() to deallocate the scamper_vpset_t once it is no longer needed.

void scamper_vpset_free(scamper_vpset_t *vps)
Free the opaque scamper_vpset_t.

size_t scamper_vpset_vp_count(const scamper_vpset_t *vps)
Return the number of scamper_vp_t items in the scamper_vpset_t.

scamper_vp_t * scamper_vpset_vp_get(const scamper_vpset_t *vps, size_t i)
Return the opaque scamper_vp_t referred to at the given index. Valid index values are between zero and scamper_vpset_vp_count() - 1, inclusive, for the specified scamper_vpset_t.

SCAMPER_VP_T ROUTINES¶

scamper_vp_t * scamper_vp_use(scamper_vp_t *vp)
Advise libscamperctrl(3) that the programmer is keeping a copy of the vp in their program.

void scamper_vp_free(scamper_vp_t *vp)
Free vp resources, if the programmer previously called scamper_vp_use() to advise libscamperctrl(3) that the programmer would also be keeping a copy of a vp pointer.

const char * scamper_vp_name_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains the full name of a remote scamper vantage point, or NULL.

const char * scamper_vp_shortname_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains the short name of a remote scamper vantage point, or NULL.

const char * scamper_vp_ipv4_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains the IPv4 address observed by sc_remoted(1).

const char * scamper_vp_asn4_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains an ASN value associated with the IPv4 address of the VP.

const char * scamper_vp_ipv6_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains the IPv6 address observed by sc_remoted(1).

const char * scamper_vp_asn6_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains an ASN value associated with the IPv6 address of the VP.

const char * scamper_vp_cc_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains, by convention, an uppercase ISO-3166 2-letter country code associated with the VP.

const char * scamper_vp_st_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains, by convention, an uppercase ISO-3166 state code associated with the VP.

const char * scamper_vp_place_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains the name of the city or town where the VP is located.

const char * scamper_vp_latlong_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains, by convention, the latitude and longitude values where the VP is located, separated by a comma.

const char * scamper_vp_iata_get(const scamper_vp_t *vp)
Returns a pointer to a string that contains, by convention, an uppercase 3-letter IATA airport code closes to the VP.

size_t scamper_vp_tagc_get(const scamper_vp_t *vp)
Returns the number of tags associated with the VP.

const char * scamper_vp_tag_get(const scamper_vp_t *vp, size_t i)
Returns a pointer to a string containing the specified tag, or NULL. Tag numbers are zero-indexed, so valid tag numbers are between zero and scamper_vp_tagc_get() - 1, inclusive, for the specified scamper_vpset_t.

SCAMPER_INST_T ROUTINES¶

scamper_inst_t * scamper_inst_vp(scamper_ctrl_t *ctrl, scamper_vp_t *vp)
Attach to a remote scamper instance specified in the scamper_vp_t.

scamper_inst_t * scamper_inst_muxvp(scamper_ctrl_t *ctrl, const char *str)
Attach to a remote scamper instance connected to an sc_remoted(1) mux at the specified path. If the mux socket is in the file system at /path/to/mux, and the name of the VP to connect is hlz2-nz, then the string parameter should be /path/to/mux/hlz2-nz. Internally, the name of the VP can be either the short name or full name of the VP, and scamper_inst_muxvp() will match the first one.

scamper_inst_t * scamper_inst_unix(scamper_ctrl_t *ctrl, const scamper_attp_t *attp, const char *path)
Attach to a local scamper instance via the unix domain socket at the supplied path. Attach parameters for local scamper instances can be supplied via the scamper_attp_t parameter.

scamper_inst_t * scamper_inst_inet(scamper_ctrl_t *ctrl, const scamper_attp_t *attp, const char *addr, uint16_t port)
Attach to a local scamper instance via the supplied IP address and port. Attach parameters for local scamper instances can be supplied via the scamper_attp_t parameter.

scamper_inst_t * scamper_inst_remote(scamper_ctrl_t *ctrl, const char *path)
Attach to a remote scamper instance via the instance-specific unix domain socket at the supplied path. The remote scamper instance is connected to the local machine using a sc_remoted(1) process.

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 identifes 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.

void scamper_inst_param_set(scamper_inst_t *inst, void *param)
Associates the specified pointer with the scamper_inst_t structure.

void * scamper_inst_param_get(const scamper_inst_t *inst)
Returns the current value of the parameter set with scamper_inst_param_set().

int scamper_inst_is_muxvp(const scamper_inst_t *inst)
Returns non-zero if the instance is associated with a sc_remoted(1) mux.

int scamper_inst_is_inet(const scamper_inst_t *inst)
Returns non-zero if the instance is associated with a local scamper instance directly reachable via an IP address.

int scamper_inst_is_unix(const scamper_inst_t *inst)
Returns non-zero if the instance is associated with a local scamper instance directly reachable via a unix domain socket.

int scamper_inst_is_remote(const scamper_inst_t *inst)
Returns non-zero if the instance is associated with a remote scamper instance reachable via a unix domain socket from sc_remoted(1).

const char * scamper_inst_name_get(const scamper_inst_t *inst)
Returns a pointer to a string that contains the name of the instance. For instances from a mux, it will be the name of the VP. For other types of instance, the name will be derived from how the instance is reached.

uint8_t scamper_inst_type_get(const scamper_inst_t *inst)
Returns one of the following values, identifying the type of instance:

• SCAMPER_INST_TYPE_UNIX: a local scamper instance directly reached via a unix domain socket.
• SCAMPER_INST_TYPE_INET: a local scamper instance directly reached via an IP socket.
• SCAMPER_INST_TYPE_REMOTE: a remote scamper instance provided by sc_remoted(3) via a unix domain socket.
• SCAMPER_INST_TYPE_MUXVP: a remote scamper instance provided by sc_remoted(3) via a mux socket.

const char * scamper_inst_strerror(const scamper_inst_t *inst)
Returns a pointer to the contents of the error buffer held internally by scamper_inst_t, which is set when a function associated with the scamper_inst_t encounters an error.

scamper_ctrl_t * scamper_inst_ctrl_get(const scamper_inst_t *inst)
Returns a pointer to the scamper_ctrl_t associated with the supplied scamper_inst_t.

scamper_vp_t * scamper_inst_vp_get(const scamper_inst_t *inst)
Returns a pointer to the scamper_vp_t associated with the supplied scamper_inst_t, if the scamper_inst_t were created via an sc_remoted(3) mux.

SCAMPER_TASK_T ROUTINES¶

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.

SCAMPER_ATTP_T ROUTINES¶

scamper_attp_t * scamper_attp_alloc(void)
Allocate an opaque scamper_attp_t structure that can be used with scamper_inst_unix() and scamper_inst_inet() to specify parameters to a local scamper during the attach phase. It is the responsibility of the caller to free the scamper_attp_t once it is no longer needed with scamper_attp_free()

void scamper_attp_free(scamper_attp_t *attp)
Free the scamper_attp_t structure.

void scamper_attp_listid_set(scamper_attp_t *attp, uint32_t id)
Set the list ID parameter that will be passed to scamper during the attach phase.

int scamper_attp_listname_set(scamper_attp_t *attp, char *name)
Set the list name parameter that will be passed to scamper during the attach phase. This function returns zero on success.

int scamper_attp_listdescr_set(scamper_attp_t *attp, char *descr)
Set the list description parameter that will be passed to scamper during the attach phase. This function returns zero on success.

int scamper_attp_listmonitor_set(scamper_attp_t *attp, char *monitor)
Set the list monitor name parameter that will be passed to scamper during the attach phase. This function returns zero on success.

void scamper_attp_cycleid_set(scamper_attp_t *attp, uint32_t id)
Set the cycle ID parameter that will be passed to scamper during the attach phase.

void scamper_attp_priority_set(scamper_attp_t *attp, uint32_t priority)
Set the cycle priority parameter that will be passed to scamper during the attach phase. This parameter controls the mixing rate of tasks from the associated source relative to other sources also managed by the same scamper process.

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>.