 |
SolarCapture C Bindings
|
|
SolarCapture C Bindings
|
Files | |
| file | args.h |
| sc_arg: An argument to a node's initialisation function. | |
| file | attr.h |
| sc_attr: Control optional behaviours and tunables. | |
| file | declare_types.h |
| This header is used to generate C type definitions and corresponding runtime type information for data structures that are shared by SolarCapture with other processes. | |
| file | dlist.h |
| sc_dlist: A doubly-linked list. | |
| file | event.h |
| sc_callback: Interface for event notification. | |
| file | ext_node.h |
| Interface for writing custom nodes. | |
| file | ext_packet.h |
| sc_packet: The representation of a packet or other data. | |
| file | ext_packet_list.h |
| sc_packet_list: A list of packets. | |
| file | iovec.h |
| sc_iovec_ptr: Supports iterating over a 'struct iovec'. | |
| file | mailbox.h |
| sc_mailbox: A means to pass packets from one thread to another. | |
| file | misc.h |
| Miscellaneous utility functions. | |
| file | node.h |
| sc_node: An object that processes packets. | |
| file | object.h |
| sc_object: Opaque object interface. Use this to pass all types of data that are not ints, doubles or char arrays (see SC_PARAM_INT, SC_PARAM_DBL and SC_PARAM_STR respectively for these). | |
| file | pkt_pool.h |
| sc_pool: A pool of packet buffers. | |
| file | predicate.h |
| sc_pkt_predicate: Interface for testing properties of packets. | |
| file | session.h |
| sc_session: A set of threads and other objects. | |
| file | stream.h |
| This header file defines sc_stream objects for directing packets to a sc_vi instance. A packet must match all the stream criteria for it to be directed by the stream to an sc_vi instance. | |
| file | thread.h |
| sc_thread: Representation of a thread in SolarCapture. | |
| file | time.h |
| Functions for managing time. | |
| file | vi.h |
| sc_vi: Supports receiving packets from the network. | |
Data Structures | |
| struct | sc_arg |
| Representation of an argument. Used by node init functions. More... | |
| union | sc_arg.val |
| struct | sc_dlist |
| Doubly linked list pointers. More... | |
| struct | sc_callback |
| A callback object. More... | |
| struct | sc_node |
| Description of a node. More... | |
| struct | sc_node_link |
| Description of a link the node has. More... | |
| struct | sc_node_factory |
| Struct to hold information about how to create an instance of this node. More... | |
| struct | sc_node_type |
| Describes a type of node. More... | |
| struct | sc_packet |
| Representation of a packet. More... | |
| struct | sc_packet_list |
| A list of packets or packet buffers. More... | |
| struct | sc_iovec_ptr |
| struct | sc_pkt_predicate |
| A packet predicate object. More... | |
| struct | sc_session_error |
| A SolarCapture session error object returned by sc_session_error_get. More... | |
| struct | sc_attr |
| Attribute object. More... | |
| struct | sc_object |
| An opaque object. Use this to pass all types of data that are not ints, doubles or char arrays (see SC_PARAM_INT, SC_PARAM_DBL and SC_PARAM_STR respectively for these) to nodes. More... | |
| struct | sc_vi |
| A VI object. More... | |
Macros | |
| #define | SC_ARG_INT(_name, _val) { .name = _name, .type = SC_PARAM_INT, .val.i = _val } |
| #define | SC_ARG_STR(_name, _val) { .name = _name, .type = SC_PARAM_STR, .val.str = _val } |
| #define | SC_ARG_OBJ(_name, _val) { .name = _name, .type = SC_PARAM_OBJ, .val.obj = _val } |
| #define | SC_ARG_DBL(_name, _val) { .name = _name, .type = SC_PARAM_DBL, .val.dbl = _val } |
| #define | ST_CONSTANT(name, val) enum { name = val };a |
| A constant value in the template definition. More... | |
| #define | ST_STRUCT(name) struct name { |
| Start of the template definition. More... | |
| #define | ST_FIELD_STR(name, len, kind) char name[len]; |
| A string field in the template definition. More... | |
| #define | ST_FIELD(type, name, kind) type name; |
| A C basic type field in the template definition. More... | |
| #define | ST_STRUCT_END }; |
| End of the template definition. | |
| #define | SC_CONTAINER(c_type, mbr_name, p_mbr) ( (c_type*) ((char*)(p_mbr) - SC_MEMBER_OFFSET(c_type, mbr_name)) ) |
| Fetch a pointer to the outer container of a given sc_dlist pointer. More... | |
| #define | SC_DLIST_FOR_EACH_OBJ(list, iter, mbr) |
| Create a for statement that loops over each container item in the list. It is not safe to modify the list using this macro, if list modifications are required see SC_DLIST_FOR_EACH_OBJ_SAFE. More... | |
| #define | SC_DLIST_FOR_EACH_OBJ_SAFE(list, iter, next_entry, mbr) |
| Create a for statement that loops over each container item in the list which can be safely be modified during traversal. More... | |
| #define | sc_node_set_error(node, errno_code,...) |
| Set error from within the implementation of a node. More... | |
| #define | sc_node_fwd_error(node, rc) __sc_node_fwd_error((node), __FILE__, __LINE__, __func__, (rc)) |
| Forward error from a failed sc call. More... | |
| #define | SC_MEMBER_OFFSET(c_type, mbr_name) ((uint32_t) (uintptr_t)(&((c_type*)0)->mbr_name)) |
| Calculate memory offset of a field within a struct. More... | |
| #define | SC_MEMBER_SIZE(c_type, mbr_name) (sizeof(((c_type*)0)->mbr_name)) |
| Calculate the size of a field within a struct. More... | |
| #define | SC_FRAME_LEN_LARGE UINT16_MAX |
| struct sc_packet.frame_len holds this special value to indicate that the frame is "large". (Meaning it would overflow sc_packet.frame_len). | |
| #define | SC_CSUM_ERROR (1 << 0) |
| struct sc_packet.flags will have this set if the packet has a checksum error | |
| #define | SC_CRC_ERROR (1 << 1) |
| struct sc_packet.flags will have this set if the packet has a crc error | |
| #define | SC_TRUNCATED (1 << 2) |
| struct sc_packet.flags will have this set if the packet has been truncated | |
| #define | SC_MCAST_MISMATCH (1 << 3) |
| struct sc_packet.flags will have this set if the packet is for a multicast group the host hasn't joined | |
| #define | SC_UCAST_MISMATCH (1 << 4) |
| struct sc_packet.flags will have this set if the packet is for a unicast address not matching the host's | |
Typedefs | |
| typedef void( | sc_callback_handler_fn )(struct sc_callback *, void *event_info) |
| A callback handler function. More... | |
| typedef int( | sc_node_init_fn )(struct sc_node *node, const struct sc_attr *attr, const struct sc_node_factory *) |
| Signature of function to initialise a node. More... | |
| typedef int( | sc_node_prep_fn )(struct sc_node *node, const struct sc_node_link *const *links, int n_links) |
| Signature of nt_prep_fn function. More... | |
| typedef void( | sc_node_pkts_fn )(struct sc_node *node, struct sc_packet_list *packet_list) |
| Signature of nt_pkts_fn function. More... | |
| typedef int( | sc_node_add_link_fn )(struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt) |
| Signature of nt_add_link_fn function. More... | |
| typedef struct sc_node *( | sc_node_select_subnode_fn )(struct sc_node *node, const char *name, char **new_name_out) |
| Signature of nt_select_subnode_fn function. More... | |
| typedef void( | sc_node_end_of_stream_fn )(struct sc_node *node) |
| Signature of nt_end_of_stream_fn function. More... | |
| typedef int( | sc_pkt_predicate_test_fn )(struct sc_pkt_predicate *, struct sc_packet *) |
Enumerations | |
| enum | sc_param_type { SC_PARAM_STR, SC_PARAM_INT, SC_PARAM_OBJ, SC_PARAM_DBL } |
| Possible parameter types that can be used for arguments in a node's init function. More... | |
| enum | sc_object_type { SC_OBJ_ANY, SC_OBJ_OPAQUE, SC_OBJ_PKT_PREDICATE } |
| The type of data the sc_object contains. More... | |
Functions | |
| int | sc_attr_alloc (struct sc_attr **attr_out) |
| Allocate an attribute object. More... | |
| void | sc_attr_free (struct sc_attr *attr) |
| Free an attribute object. More... | |
| void | sc_attr_reset (struct sc_attr *attr) |
| Return attributes to their default values. More... | |
| int | sc_attr_set_int (struct sc_attr *attr, const char *name, int64_t val) |
| Set an attribute to an integer value. More... | |
| int | sc_attr_set_str (struct sc_attr *attr, const char *name, const char *s) |
| Set an attribute to a string value. More... | |
| int | sc_attr_set_from_str (struct sc_attr *attr, const char *name, const char *val) |
| Set an attribute to a string value. More... | |
| struct sc_attr * | sc_attr_dup (const struct sc_attr *attr) |
| Duplicate an attribute object. More... | |
| int | sc_attr_doc (const char *attr_name_opt, const char ***docs_out, int *docs_len_out) |
| Returns documentation for attributes. Used by solar_capture_doc. More... | |
| static void | sc_dlist_init (struct sc_dlist *list) |
| Initialise a pre-allocated sc_dlist to be an empty doubly linked list. More... | |
| static int | sc_dlist_is_empty (const struct sc_dlist *list) |
| Check if a doubly linked list is empty, returns 1 if true 0 otherwise. | |
| static void | sc_dlist_push_head (struct sc_dlist *list, struct sc_dlist *l) |
| Prepend an item to the head of a doubly-linked list. More... | |
| static void | sc_dlist_push_tail (struct sc_dlist *list, struct sc_dlist *l) |
| Append an item to the tail of a doubly-linked list. More... | |
| static void | sc_dlist_remove (struct sc_dlist *l) |
| Remove an item from the list. More... | |
| static struct sc_dlist * | sc_dlist_pop_head (struct sc_dlist *list) |
| Pop off the head of a list. More... | |
| static struct sc_dlist * | sc_dlist_pop_tail (struct sc_dlist *list) |
| Pop the tail of a list. More... | |
| int | sc_callback_alloc (struct sc_callback **cb_out, const struct sc_attr *attr, struct sc_thread *thread) |
| Allocate a callback object instance. More... | |
| void | sc_callback_free (struct sc_callback *cb) |
| Free a callback object instance. More... | |
| static int | sc_callback_is_active (const struct sc_callback *cb) |
| Returns true if a callback object is active. More... | |
| static void | sc_callback_remove (struct sc_callback *cb) |
| Unregister a callback object from its event source. More... | |
| void | sc_callback_on_idle (struct sc_callback *cb) |
| Request a callback when the thread is idle. More... | |
| int | sc_epoll_ctl (struct sc_thread *thread, int op, int fd, unsigned events, struct sc_callback *cb) |
| Request a callback when the thread is idle. More... | |
| int | sc_node_type_alloc (struct sc_node_type **nt_out, const struct sc_attr *attr_opt, const struct sc_node_factory *factory) |
| Allocate an sc_node_type instance. More... | |
| void | sc_forward_list (struct sc_node *node, const struct sc_node_link *link, struct sc_packet_list *pl) |
| Forward a list of packets. More... | |
| void | sc_forward (struct sc_node *node, const struct sc_node_link *link, struct sc_packet *packet) |
| Forward a single packet. More... | |
| int | sc_node_init_get_arg_int (int *v_out, struct sc_node *node, const char *name, int v_default) |
| Get an integer argument. More... | |
| int | sc_node_init_get_arg_str (const char **v_out, struct sc_node *node, const char *name, const char *v_default) |
| Get an string argument. More... | |
| int | sc_node_init_get_arg_obj (struct sc_object **obj_out, struct sc_node *node, const char *name, enum sc_object_type obj_type) |
| Get an sc_object argument. More... | |
| int | sc_node_init_get_arg_dbl (double *v_out, struct sc_node *node, const char *name, double v_default) |
| Get a double argument. More... | |
| const struct sc_node_link * | sc_node_prep_get_link (struct sc_node *node, const char *link_name) |
| Find a named outgoing link. More... | |
| const struct sc_node_link * | sc_node_prep_get_link_or_free (struct sc_node *node, const char *link_name) |
| Find a named outgoing link or return a link for freeing. More... | |
| int | sc_node_prep_check_links (struct sc_node *node) |
| Check the node's links for any unused links. More... | |
| int | sc_node_prep_get_pool (struct sc_pool **pool_out, const struct sc_attr *attr, struct sc_node *node, const struct sc_node_link *const *links, int n_links) |
| Get a packet pool that can be used to obtain empty packet buffers that can be passed to any of the given set of links. More... | |
| void | sc_node_link_end_of_stream (struct sc_node *node, const struct sc_node_link *link) |
| Indicate end-of-stream on a link. More... | |
| int | sc_node_export_state (struct sc_node *node, const char *type_name, int type_size, void *pp_area) |
| Export dynamic state to solar_capture_monitor. More... | |
| static int | sc_packet_bytes (struct sc_packet *p) |
| Return the size of the packet data in bytes. More... | |
| static struct sc_packet * | sc_packet_frags_tail (struct sc_packet *p) |
| Return a packet's last fragment. More... | |
| static void | sc_packet_prefetch_r (struct sc_packet *p) |
| Prefetch a packet for reading. More... | |
| static void | sc_packet_prefetch_rw (struct sc_packet *p) |
| Prefetch a packet for reading and writing. More... | |
| static struct timespec | sc_packet_timespec (const struct sc_packet *p) |
| Return the timestamp of the packet in timespec format. More... | |
| static void | sc_packet_list_init (struct sc_packet_list *l) |
| Initialise a list. More... | |
| static int | sc_packet_list_is_empty (const struct sc_packet_list *l) |
| Check if packet list is empty. More... | |
| static void | sc_packet_list_finalise (struct sc_packet_list *l) |
| Finalise a list. More... | |
| static struct sc_packet * | sc_packet_list_tail (struct sc_packet_list *l) |
| Return the tail of current tail of the list. More... | |
| static void | sc_packet_list_push_head (struct sc_packet_list *pl, struct sc_packet *p) |
| Push a packet to the head of a list. More... | |
| static void | sc_packet_list_append (struct sc_packet_list *l, struct sc_packet *p) |
| Append a packet to a list and finalise. More... | |
| static void | sc_packet_list_append_list (struct sc_packet_list *dest, struct sc_packet_list *src) |
| Append a list to a list. More... | |
| static struct sc_packet * | sc_packet_list_pop_head (struct sc_packet_list *pl) |
| Remove and return the head of the list. More... | |
| static void | sc_iovec_ptr_init (struct sc_iovec_ptr *iovp, const struct iovec *iov, int iovlen) |
| Initialise a struct sc_iovec_ptr. More... | |
| static void | sc_iovec_ptr_init_buf (struct sc_iovec_ptr *iovp, void *buf, int len) |
| Initialise a struct sc_iovec_ptr with a contiguous buffer. More... | |
| static void | sc_iovec_ptr_init_packet (struct sc_iovec_ptr *iovp, const struct sc_packet *packet) |
| Initialise a struct sc_iovec_ptr to point at packet data. More... | |
| static int | sc_iovec_ptr_bytes (const struct sc_iovec_ptr *iovp) |
| Returns the number of bytes represented by an sc_iovec_ptr. More... | |
| int | sc_iovec_ptr_skip (struct sc_iovec_ptr *iovp, int bytes_to_skip) |
| Skip forward over an iovec. More... | |
| int | sc_iovec_ptr_find_chr (const struct sc_iovec_ptr *iovp, int c) |
| Find offset of character in iovec. More... | |
| int | sc_iovec_ptr_copy_out (void *dest, struct sc_iovec_ptr *iovp, int max_bytes) |
| Copy data out of an sc_iovec_ptr. More... | |
| static void | sc_iovec_copy_from_end (void *dest_buf, const struct iovec *iov, int iovlen, int bytes) |
| Copy data out of the end of a sc_iovec_ptr. More... | |
| static void | sc_iovec_trim_end (struct iovec *iov, uint8_t *iovlen, int bytes) |
| Remove data from the end of an iovec. More... | |
| int | sc_mailbox_alloc (struct sc_mailbox **mb_out, const struct sc_attr *attr, struct sc_thread *thread) |
| Allocate a mailbox. More... | |
| int | sc_mailbox_connect (struct sc_mailbox *mb1, struct sc_mailbox *mb2) |
| Connect a pair of mailboxes. More... | |
| int | sc_mailbox_set_recv (struct sc_mailbox *mailbox, struct sc_node *node, const char *name_opt) |
| Connect a mailbox to a node. More... | |
| struct sc_node * | sc_mailbox_get_send_node (struct sc_mailbox *mailbox) |
| Return a mailbox's "send node". More... | |
| int | sc_mailbox_poll (struct sc_mailbox *mailbox, struct sc_packet_list *list) |
| Poll a mailbox. More... | |
| void | sc_mailbox_send (struct sc_mailbox *mailbox, struct sc_packet *packet) |
| Send a packet through a mailbox to another thread. More... | |
| void | sc_mailbox_send_list (struct sc_mailbox *mailbox, struct sc_packet_list *list) |
| Send a list of packets through a mailbox to another thread. More... | |
| int | sc_join_mcast_group (struct sc_session *scs, const char *interface, const char *group) |
| Join a multicast group. More... | |
| int | sc_node_alloc (struct sc_node **node_out, const struct sc_attr *attr, struct sc_thread *thread, const struct sc_node_factory *factory, const struct sc_arg *args, int n_args) |
| Allocate a packet processing node. More... | |
| int | sc_node_alloc_named (struct sc_node **node_out, const struct sc_attr *attr, struct sc_thread *thread, const char *factory_name, const char *lib_name, const struct sc_arg *args, int n_args) |
| Allocate a packet processing node by name. More... | |
| int | sc_node_add_link (struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt) |
| Add a link from one node to another. More... | |
| struct sc_thread * | sc_node_get_thread (const struct sc_node *node) |
| Return the thread associated with a node. More... | |
| int | sc_node_factory_lookup (const struct sc_node_factory **factory_out, struct sc_session *session, const char *factory_name, const char *lib_name) |
| Find a node factory. More... | |
| void | sc_node_add_info_str (struct sc_node *node, const char *field_name, const char *field_val) |
| Export information to solar_capture_monitor. More... | |
| void | sc_node_add_info_int (struct sc_node *node, const char *field_name, int64_t field_val) |
| Export information to solar_capture_monitor. More... | |
| enum sc_object_type | sc_object_type (struct sc_object *obj) |
| Return the type of data contained within the sc_object. More... | |
| int | sc_opaque_alloc (struct sc_object **obj_out, void *opaque) |
| Allocate memory for an opaque sc_object. More... | |
| void | sc_opaque_free (struct sc_object *obj) |
| Free an sc_object previously allocated using sc_opaque_alloc. Only use this to free an opaque sc_object. The underlying data wrapped by this object will not be freed. More... | |
| void | sc_opaque_set_ptr (struct sc_object *obj, void *opaque) |
| Set the opaque pointer in an sc_object. More... | |
| void * | sc_opaque_get_ptr (const struct sc_object *obj) |
| Get the opaque pointer stored in an sc_object. More... | |
| int | sc_pool_get_packets (struct sc_packet_list *list, struct sc_pool *pool, int min_packets, int max_packets) |
| Get packet buffers from a pool. More... | |
| void | sc_pool_return_packets (struct sc_pool *pool, struct sc_packet_list *list) |
| Return packets to a pool. More... | |
| void | sc_pool_on_threshold (struct sc_pool *pool, struct sc_callback *event, int threshold) |
| Request a callback when the pool is refilled. More... | |
| struct sc_packet * | sc_pool_duplicate_packet (struct sc_pool *pool, struct sc_packet *packet, int snap) |
| Duplicate a packet. More... | |
| int | sc_packet_append_iovec_ptr (struct sc_packet *packet, struct sc_pool *pool, struct sc_iovec_ptr *iovp, int snap) |
| Append data to a packet. More... | |
| int | sc_pkt_predicate_alloc (struct sc_pkt_predicate **pred_out, int private_bytes) |
| Allocate a packet predicate object. More... | |
| struct sc_object * | sc_pkt_predicate_to_object (struct sc_pkt_predicate *pred) |
| Convert a sc_pkt_predicate into a sc_object. More... | |
| struct sc_pkt_predicate * | sc_pkt_predicate_from_object (struct sc_object *obj) |
| Convert a sc_object into a sc_pkt_predicate. More... | |
| int | sc_session_alloc (struct sc_session **scs_out, const struct sc_attr *attr) |
| Allocate a SolarCapture session. More... | |
| int | sc_session_prepare (struct sc_session *scs) |
| Prepare a SolarCapture session. More... | |
| int | sc_session_go (struct sc_session *scs) |
| Start a SolarCapture session. More... | |
| int | sc_session_pause (struct sc_session *scs) |
| Pause a SolarCapture session. More... | |
| struct sc_session_error * | sc_session_error_get (struct sc_session *scs) |
| Returns an error from a SolarCapture session. More... | |
| void | sc_session_error_free (struct sc_session *scs, struct sc_session_error *err) |
| Frees an error object. More... | |
| int | sc_stream_alloc (struct sc_stream **stream_out, const struct sc_attr *attr, struct sc_session *scs) |
| Create a new stream object for this session. More... | |
| int | sc_stream_free (struct sc_stream *stream) |
| Free a previously created stream. More... | |
| int | sc_stream_reset (struct sc_stream *stream) |
| Remove all stream filters. More... | |
| int | sc_stream_set_str (struct sc_stream *stream, const char *str) |
| Configure the stream to capture all packets matching the specified filter string. This is the preferred way of adding filters to a stream. More... | |
| int | sc_stream_all (struct sc_stream *stream) |
| Configure this stream to capture all packets that haven't been caught by another stream. More... | |
| int | sc_stream_mismatch (struct sc_stream *stream) |
| Configure this stream to capture all packets that haven't been caught by another stream and are not requested by the kernel network stack. More... | |
| int | sc_stream_ip_dest_hostport (struct sc_stream *stream, int protocol, const char *dhost, const char *dport) |
| Configure this stream to capture all packets with the matching protocol, destination hostname and destination port. More... | |
| int | sc_stream_ip_source_hostport (struct sc_stream *stream, const char *shost, const char *sport) |
| Configure this stream to capture all packets with the matching protocol, source hostname and source port. More... | |
| int | sc_stream_eth_dhost (struct sc_stream *stream, const uint8_t *mac_addr) |
| Configure this stream to capture all packets with the matching destination MAC address. More... | |
| int | sc_stream_eth_vlan_id (struct sc_stream *stream, int vlan_id) |
| Configure this stream to capture all packets with the matching VLAN ID. More... | |
| int | sc_stream_eth_shost (struct sc_stream *stream, const uint8_t *mac_addr) |
| Configure this stream to capture all packets with the matching source MAC address. More... | |
| int | sc_stream_eth_type (struct sc_stream *stream, uint16_t eth_type) |
| Configrue this stream to capture all packets with the matching ethernet type. More... | |
| int | sc_stream_ip_dest_host (struct sc_stream *stream, const char *dhost) |
| Configure this stream to capture all packets with matching destination hostname. More... | |
| int | sc_stream_ip_dest_port (struct sc_stream *stream, const char *dport) |
| Configure this stream to capture all packets with matching destination port. More... | |
| int | sc_stream_ip_source_host (struct sc_stream *stream, const char *shost) |
| Configure this stream to capture all packets with matching source hostname. More... | |
| int | sc_stream_ip_source_port (struct sc_stream *stream, const char *sport) |
| Configure this stream to capture all packets with matching source port. More... | |
| int | sc_stream_ip_protocol (struct sc_stream *stream, int protocol) |
| Configure this stream to capture all packets with matching IP protocol. More... | |
| int | sc_thread_alloc (struct sc_thread **thread_out, const struct sc_attr *attr, struct sc_session *scs) |
| Allocate a SolarCapture thread. More... | |
| struct sc_session * | sc_thread_get_session (const struct sc_thread *thread) |
| Return the session associated with a thread. | |
| void | sc_thread_get_time (const struct sc_thread *thread, struct timespec *time_out) |
| Return a thread's "current time". More... | |
| void * | sc_thread_calloc (struct sc_thread *thread, size_t bytes) |
| Allocate memory to be used by a thread. More... | |
| void * | sc_thread_calloc_aligned (struct sc_thread *thread, size_t bytes, int align) |
| Allocate memory to be used by a thread. More... | |
| void | sc_thread_mfree (struct sc_thread *thread, void *mem) |
| Free memory. More... | |
| int | sc_thread_poll (struct sc_thread *thread) |
| Poll a thread. More... | |
| void | sc_timer_expire_at (struct sc_callback *cb, const struct timespec *time) |
| Request a callback at a given time. More... | |
| void | sc_timer_expire_after_ns (struct sc_callback *cb, int64_t delta_ns) |
| Request a callback in the future. More... | |
| void | sc_timer_push_back_ns (struct sc_callback *cb, int64_t delta_ns) |
| Push the expiry time further into the future. More... | |
| int | sc_timer_get_expiry_time (const struct sc_callback *cb, struct timespec *ts_out) |
| Return the expiry time of a timer callback. More... | |
| static uint64_t | sc_ns_from_ts (const struct timespec *ts) |
| Convert a timespec struct to nanoseconds. More... | |
| static uint64_t | sc_ns_from_tv (const struct timeval *tv) |
| Convert a timeval struct to nanoseconds. More... | |
| static uint64_t | sc_ns_from_ms (uint64_t ms) |
| Convert milliseconds to nanoseconds. More... | |
| static uint64_t | sc_ns_from_us (uint64_t us) |
| Convert microseconds to nanoseconds. More... | |
| int | sc_vi_alloc (struct sc_vi **vi_out, const struct sc_attr *attr, struct sc_thread *thread, const char *interface) |
| Allocate a VI instance. More... | |
| int | sc_vi_set_recv_node (struct sc_vi *vi, struct sc_node *node, const char *name_opt) |
| Set the node a VI should deliver its received packets to. More... | |
| int | sc_vi_add_stream (struct sc_vi *vi, struct sc_stream *stream) |
| Direct a packet stream to a VI. More... | |
| struct sc_thread * | sc_vi_get_thread (const struct sc_vi *vi) |
| Return the thread associated with a VI. More... | |
| const char * | sc_vi_get_interface_name (const struct sc_vi *vi) |
| Return the name of the network interface associated with a VI. More... | |
| int | sc_vi_group_alloc (struct sc_vi_group **vi_out, const struct sc_attr *attr, struct sc_session *session, const char *interface, int num_vis) |
| Allocate a VI group. More... | |
| struct sc_session * | sc_vi_group_get_session (const struct sc_vi_group *vi_group) |
| Return the session associated with a VI group. More... | |
| int | sc_vi_alloc_from_group (struct sc_vi **vi_out, const struct sc_attr *attr, struct sc_thread *thread, struct sc_vi_group *vi_group) |
| Allocate a VI instance from a VI group. More... | |
| int | sc_vi_group_add_stream (struct sc_vi_group *vi_group, struct sc_stream *stream) |
| Direct a packet stream to a group of VIs. More... | |
| struct sc_arg |
Representation of an argument. Used by node init functions.
| Data Fields | ||
|---|---|---|
| const char * | name |
Parameter name |
| enum sc_param_type | type |
Parameter type |
| union sc_arg | val |
Parameter value |
| union sc_arg.val |
| Data Fields | ||
|---|---|---|
| double | dbl | |
| int64_t | i | |
| struct sc_object * | obj | |
| const char * | str | |
| struct sc_dlist |
| struct sc_callback |
A callback object.
Callback objects provide a way to be notified when an event of interest occurs.
| Data Fields | ||
|---|---|---|
| sc_callback_handler_fn * | cb_handler_fn |
The callback to be called when the event of interest occurs. |
| struct sc_dlist | cb_link | |
| void * | cb_private |
Additional state to be passed to the callback function. |
| struct sc_node |
Description of a node.
This is passed to every function used to call into the node.
| Data Fields | ||
|---|---|---|
| char * | nd_name |
Name of the node, set automatically when creating node. |
| void * | nd_private |
Set by node for local state |
| const struct sc_node_type * | nd_type |
Type of node, set automatically on creation of the node |
| struct sc_node_link |
| struct sc_node_factory |
Struct to hold information about how to create an instance of this node.
| Data Fields | ||
|---|---|---|
| sc_node_init_fn * | nf_init_fn |
The function to call to initialise the node |
| const char * | nf_name |
The name of the node. |
| int | nf_node_api_ver |
The version of solar_capture this node is designed for. The most recent version is stored in the macro SC_API_VER. |
| void * | nf_private |
For use as local state by the node sc_node_init_fn function only. This will not be passed to other node functions |
| void * | nf_reserved[8] | |
| const char * | nf_source_file |
The filename of the source file for this node. Use the FILE macro to set this. |
| struct sc_node_type |
Describes a type of node.
This struct describes what functions are responsible for the behaviour of the node.
| Data Fields | ||
|---|---|---|
| sc_node_add_link_fn * | nt_add_link_fn |
(Optional) Function to call when a node tries to establish a link from this node, set to NULL if not required. |
| sc_node_end_of_stream_fn * | nt_end_of_stream_fn |
(Optional) Function to call when nodes upstream indicate end of stream, set to NULL if not required. |
| const char * | nt_name |
Name of the node (set automatically by sc_node_type_alloc using sc_node_factory.nf_name. |
| sc_node_pkts_fn * | nt_pkts_fn |
Function to call when the node receives packets. |
| sc_node_prep_fn * | nt_prep_fn |
Function to call to prepare the node after the node graph is finalised. |
| void * | nt_private |
Additional state for the node. |
| sc_node_select_subnode_fn * | nt_select_subnode_fn |
(Optional) Function to call when another node tries to establish a link to this node, set to NULL if not required. |
| struct sc_packet |
Representation of a packet.
This data-structure describes a packet. It includes pointers to the packet contents, meta-data relating to the packet and fields to support creating lists of packets.
Each sc_packet instance is usually associated with a buffer that holds the packet contents. A packet may span multiple such buffers, in which case the 'head' buffer uses frags and frags_tail to identify the remaining buffers (which are linked via the next field). Nodes should generally not use the frags, frags_n and frags_tail fields, because they are sometimes used in special ways. Instead nodes should use iov and iovlen to find the buffer(s) underlying an sc_packet.
| Data Fields | ||
|---|---|---|
| uint16_t | flags |
flags defined below |
| struct sc_packet * | frags |
list of chained fragments |
| uint8_t | frags_n |
number of fragments in |
| struct sc_packet ** | frags_tail |
last fragment in chain |
| uint16_t | frame_len |
original frame length in bytes |
| struct iovec * | iov |
identifies packet data |
| uint8_t | iovlen |
number of entries in |
| uintptr_t * | metadata |
packet metadata |
| struct sc_packet * | next |
next packet in a packet list |
| uint16_t | reserved1 | |
| uint32_t | reserved2 | |
| uint32_t | ts_nsec |
timestamp (nanoseconds) |
| uint64_t | ts_sec |
timestamp (seconds) |
| struct sc_packet_list |
| struct sc_iovec_ptr |
An sc_iovec_ptr provides a convenient way to iterate over an iovec array without modifying it.
| Data Fields | ||
|---|---|---|
| struct iovec | io | |
| const struct iovec * | iov | |
| int | iovlen | |
| struct sc_pkt_predicate |
| struct sc_session_error |
A SolarCapture session error object returned by sc_session_error_get.
| Data Fields | ||
|---|---|---|
| int | err_errno | |
| char * | err_file | |
| char * | err_func | |
| int | err_line | |
| char * | err_msg | |
| struct sc_attr |
Attribute object.
Attributes are used to specify optional behaviours and parameters, usually when allocating other SolarCapture objects. Each attribute object defines a complete set of the attributes that SolarCapture understands.
For example, the "affinity_core" attribute controls which CPU core an sc_thread runs on.
The default values for attributes may be overridden by setting the environment variable SC_ATTR. For example:
SC_ATTR="log_level=3;snap=2"
Each function that takes an attribute argument will only be interested in a subset of the attributes specified by an sc_attr instance. Other attributes are ignored.
The set of attributes supported by SolarCapture may change between releases, so applications should where possible tolerate failures when setting attributes.
| struct sc_object |
An opaque object. Use this to pass all types of data that are not ints, doubles or char arrays (see SC_PARAM_INT, SC_PARAM_DBL and SC_PARAM_STR respectively for these) to nodes.
| struct sc_vi |
A VI object.
| #define SC_ARG_DBL | ( | _name, | |
| _val | |||
| ) | { .name = _name, .type = SC_PARAM_DBL, .val.dbl = _val } |
Macro to construct a sc_arg struct of type SC_PARAM_DBL
| _name | Name of argument. |
| _val | Value of argument. |
| #define SC_ARG_INT | ( | _name, | |
| _val | |||
| ) | { .name = _name, .type = SC_PARAM_INT, .val.i = _val } |
Macro to construct a sc_arg struct of type SC_PARAM_INT
| _name | Name of argument. |
| _val | Value of argument. |
| #define SC_ARG_OBJ | ( | _name, | |
| _val | |||
| ) | { .name = _name, .type = SC_PARAM_OBJ, .val.obj = _val } |
Macro to construct a sc_arg struct of type SC_PARAM_OBJ
| _name | Name of argument. |
| _val | Value of argument. |
| #define SC_ARG_STR | ( | _name, | |
| _val | |||
| ) | { .name = _name, .type = SC_PARAM_STR, .val.str = _val } |
Macro to construct a sc_arg struct of type SC_PARAM_STR
| _name | Name of argument. |
| _val | Value of argument. |
| #define SC_CONTAINER | ( | c_type, | |
| mbr_name, | |||
| p_mbr | |||
| ) | ( (c_type*) ((char*)(p_mbr) - SC_MEMBER_OFFSET(c_type, mbr_name)) ) |
| #define SC_DLIST_FOR_EACH_OBJ | ( | list, | |
| iter, | |||
| mbr | |||
| ) |
Create a for statement that loops over each container item in the list. It is not safe to modify the list using this macro, if list modifications are required see SC_DLIST_FOR_EACH_OBJ_SAFE.
| #define SC_DLIST_FOR_EACH_OBJ_SAFE | ( | list, | |
| iter, | |||
| next_entry, | |||
| mbr | |||
| ) |
Create a for statement that loops over each container item in the list which can be safely be modified during traversal.
| #define SC_MEMBER_OFFSET | ( | c_type, | |
| mbr_name | |||
| ) | ((uint32_t) (uintptr_t)(&((c_type*)0)->mbr_name)) |
Calculate memory offset of a field within a struct.
| c_type | The struct type. |
| mbr_name | The field name to calculate the offset of. |
| #define SC_MEMBER_SIZE | ( | c_type, | |
| mbr_name | |||
| ) | (sizeof(((c_type*)0)->mbr_name)) |
Calculate the size of a field within a struct.
| c_type | The struct type. |
| mbr_name | The field to calculate the size of. |
| #define sc_node_fwd_error | ( | node, | |
| rc | |||
| ) | __sc_node_fwd_error((node), __FILE__, __LINE__, __func__, (rc)) |
Forward error from a failed sc call.
| node | The node that forwards the error |
| rc | The error code returned by the sc call |
Call this function to propagate an error generated by SolarCapture.
| #define sc_node_set_error | ( | node, | |
| errno_code, | |||
| ... | |||
| ) |
Set error from within the implementation of a node.
| node | The node that originates the error |
| errno_code | An error code from errno.h (or can be zero) |
Call this function when returning an error to SolarCapture from a node. The value returned by this function should be passed on to the caller of the function reporting the error.
| #define ST_CONSTANT | ( | name, | |
| val | |||
| ) | enum { name = val };a |
A constant value in the template definition.
After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.
| name | The field name. |
| val | The constant. |
| #define ST_FIELD | ( | type, | |
| name, | |||
| kind | |||
| ) | type name; |
A C basic type field in the template definition.
After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.
| type | The basic data type. |
| name | The field name. |
| kind | A string to describe the kind of data. Examples used by SolarCapture nodes are pkt_count, ev_count, config, const, magnitude. |
| #define ST_FIELD_STR | ( | name, | |
| len, | |||
| kind | |||
| ) | char name[len]; |
A string field in the template definition.
After the node has initialised its shared data structures name will be used as the field in the stats struct to update this data.
| name | The field name. |
| len | The length of the string. |
| kind | A string to describe the kind of data. Examples used by SolarCapture nodes are pkt_count, ev_count, config, const, magnitude. |
| #define ST_STRUCT | ( | name | ) | struct name { |
Start of the template definition.
After the node has initialised its shared data structures the resulting struct type for updating the stats will use name for its type.
| name | The name of the template. |
| typedef void( sc_callback_handler_fn)(struct sc_callback *, void *event_info) |
A callback handler function.
| callback | The callback struct registered with this callback. |
| event_info | If callback was registered using sc_epoll_ctl this will contain the uint32_t epoll_events bitmask (see man 2 epoll_ctl) In all other cases this is not used. |
| typedef int( sc_node_add_link_fn)(struct sc_node *from_node, const char *link_name, struct sc_node *to_node, const char *to_name_opt) |
Signature of nt_add_link_fn function.
| from_node | The node being linked from |
| link_name | The name of the link |
| to_node | The node being linked to |
| to_name_opt | Optional name of ingress link |
This method is optional and supports compound nodes. It is invoked on from_node when sc_node_add_link() is called, and gives the implementation an opportunity to select the subnode(s) to be linked from or issue an error if an attempt is made to create an unwanted link.
The implementation of this function should invoke sc_node_add_link() on from_node or on a subnode, or should return an error. If it returns an error it should do so by calling sc_node_set_error with a suitable error message, and return the value returned by sc_node_set_error.
The to_node and to_name_opt arguments should be passed unmodified. The implementation may invoke sc_node_add_link() multiple times to create links from multiple subnodes.
| typedef void( sc_node_end_of_stream_fn)(struct sc_node *node) |
Signature of nt_end_of_stream_fn function.
| node | The node. |
This method is invoked when all incoming upstream nodes have indicated end-of-stream. After this method has been called sc_node_pkts_fn will not be called again. The implementation of this function may propagate end-of-stream through its outgoing links by calling sc_node_link_end_of_stream(). If this function is not provided end-of-stream will not propagate further through the node graph.
After the node has propagated end-of-stream to a node through its outgoing link it should not pass any more packets to this node.
This method is optional.
| typedef int( sc_node_init_fn)(struct sc_node *node, const struct sc_attr *attr, const struct sc_node_factory *) |
Signature of function to initialise a node.
| node | The node being initialised |
| factory | The node factory |
| attr | Attributes used to create the node. Valid only until this function exits. |
| args | Parameters passed by user |
This function is used to initialise an instance of a node. It will be called before the node graph has been finalised i.e. before all links between nodes have been established at the point when a python API user calls Thread.new_node() or when a C API user calls sc_node_alloc or sc_node_alloc_named. As much initialisation as possible should be done here, any initialisation that can't be done at this stage (for instance because it requires that the node graph is finalised) can be done later in sc_node_prep_fn.
attr will not remain valid once the init function returns. If you want to use attr after this function exits or use a modified version of attr you should use sc_attr_dup() to get a persistant writable version.
| typedef void( sc_node_pkts_fn)(struct sc_node *node, struct sc_packet_list *packet_list) |
Signature of nt_pkts_fn function.
| node | The node receiving the packets |
| packet_list | List of packets |
This function will be called when packets are received on any incoming link to the node. It is not possible to distinguish which incoming link the packets arrived from directly. If the node needs to distinguish between incoming streams then either upstream nodes must append metadata to the packets or the node must be constructed from subnodes with each subnode connected to a subset of incoming links.
Once this function is invoked the node gets ownership of the packets. Ownership is relinquished by invoking sc_forward_list or sc_forward to forward or free the packets.
| typedef int( sc_node_prep_fn)(struct sc_node *node, const struct sc_node_link *const *links, int n_links) |
Signature of nt_prep_fn function.
| node | The node being prepared |
| links | Array of outgoing links the node has |
| n_links | Number of outgoing links in the array |
This callback is invoked to prepare node for live packet processing. The implementation typically checks the egress links and saves them to private storage.
Any initialisation that could not be done in sc_node_init should be done here.
If the node needs to create subnodes and establish links it should be done before this stage in one of sc_node_init_fn, sc_node_select_subnode_fn or sc_node_add_link_fn.
Note that the array links is only valid for the duration of this function call, but the sc_node_link objects are valid for at least the lifetime of the node.
| typedef struct sc_node*( sc_node_select_subnode_fn)(struct sc_node *node, const char *name, char **new_name_out) |
Signature of nt_select_subnode_fn function.
| node | The node being linked to |
| name | The name of the link (may be NULL) |
| new_name_out | Use to set a different name for sub-node |
This method is optional and supports compound nodes. It is invoked on node when sc_node_add_link() is called, and gives the implementation an opportunity to select an alternative subnode that should be linked to or issue an error if an attempt is made to create an unwanted link.
The implementation should return node or a subnode, or NULL to indicate that name is not valid for this node.
If a new name is specified via new_name_out then ownership is passed to the caller, and it will be freed with free().
| enum sc_object_type |
The type of data the sc_object contains.
| Enumerator | |
|---|---|
| SC_OBJ_OPAQUE |
An opaque pointer |
| SC_OBJ_PKT_PREDICATE |
A packet predicate (see sc_pkt_predicate) |
| enum sc_param_type |
Possible parameter types that can be used for arguments in a node's init function.
| Enumerator | |
|---|---|
| SC_PARAM_STR |
const char pointer (nul terminated) |
| SC_PARAM_INT |
signed 64 bit int |
| SC_PARAM_OBJ |
sc_object pointer |
| SC_PARAM_DBL |
native double type |
| int sc_attr_alloc | ( | struct sc_attr ** | attr_out | ) |
Allocate an attribute object.
| attr_out | The attribute object is returned here. |
This function fails (returns -1) if the SC_ATTR environment variable is malformed. The SolarCapture error status is not set in this case because attribute objects are not associated with an sc_session.
| int sc_attr_doc | ( | const char * | attr_name_opt, |
| const char *** | docs_out, | ||
| int * | docs_len_out | ||
| ) |
Returns documentation for attributes. Used by solar_capture_doc.
| attr_name_opt | The attribute name. |
| docs_out | On success, the resulting doc string output. |
| docs_len_out | On success, the length of the doc string output. |
Duplicate an attribute object.
| attr | The attribute object. |
This function is useful when you want to make non-destructive changes to an existing attribute object.
| void sc_attr_free | ( | struct sc_attr * | attr | ) |
Free an attribute object.
| attr | The attribute object. |
| void sc_attr_reset | ( | struct sc_attr * | attr | ) |
Return attributes to their default values.
| attr | The attribute object. |
| int sc_attr_set_from_str | ( | struct sc_attr * | attr, |
| const char * | name, | ||
| const char * | val | ||
| ) |
Set an attribute to a string value.
| attr | The attribute object. |
| name | Name of the attribute. |
| val | New value for the attribute. |
Returns an error if name is not a valid attribute name, or if it is not possible to convert val to a valid value for the attribute.
| int sc_attr_set_int | ( | struct sc_attr * | attr, |
| const char * | name, | ||
| int64_t | val | ||
| ) |
Set an attribute to an integer value.
| attr | The attribute object. |
| name | Name of the attribute. |
| val | New value for the attribute. |
Returns an error if name is not a valid attribute name, or if the attribute is not an integer attribute.
| int sc_attr_set_str | ( | struct sc_attr * | attr, |
| const char * | name, | ||
| const char * | s | ||
| ) |
Set an attribute to a string value.
| attr | The attribute object. |
| name | Name of the attribute. |
| s | New value for the attribute (which can be NULL). |
Returns an error if name is not a valid attribute name, or if the attribute is not a string attribute.
| int sc_callback_alloc | ( | struct sc_callback ** | cb_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread | ||
| ) |
Allocate a callback object instance.
| cb_out | The allocated callback object is returned here |
| attr | Attributes |
| thread | The thread the callback will be used with |
This function allocates a callback object instance.
Before using the callback object the sc_callback::cb_handler_fn field must be initialised. The sc_callback::cb_private field may be used to store or point to caller-specific state.
A callback object can only be registered with a single event source at a time. If a callback object is registered with an event source it is "active". If an active callback is registered with an event source, it is automatically removed from the previous event source.
| void sc_callback_free | ( | struct sc_callback * | cb | ) |
Free a callback object instance.
| cb | The callback object to free |
This function frees a callback object instance.
|
inlinestatic |
Returns true if a callback object is active.
| cb | The callback object |
| void sc_callback_on_idle | ( | struct sc_callback * | cb | ) |
Request a callback when the thread is idle.
| cb | The callback object |
The callback will be invoked from the associated thread's polling loop if there is no work done in that loop iteration. ie. The when thread is idle.
The callback is only invoked once. If further callbacks are wanted the callback must be reregistered explicitly.
|
inlinestatic |
Unregister a callback object from its event source.
| cb | The callback object |
This function has no effect if the callback object is not active.
|
inlinestatic |
Pop off the head of a list.
| list | The point to pop the head from. |
Pop the tail of a list.
| list | The point to pop the tail from. |
Prepend an item to the head of a doubly-linked list.
| list | The list to prepend to. |
| l | The item to prepend to list. |
Append an item to the tail of a doubly-linked list.
| list | The list to append to. |
| l | The item to append to list. |
|
inlinestatic |
Remove an item from the list.
| l | The item to remove. |
| int sc_epoll_ctl | ( | struct sc_thread * | thread, |
| int | op, | ||
| int | fd, | ||
| unsigned | events, | ||
| struct sc_callback * | cb | ||
| ) |
Request a callback when the thread is idle.
| thread | The thread managing fd |
| op | EPOLL_CTL_ADD, EPOLL_CTL_MOD or EPOLL_CTL_DEL |
| fd | The file descriptor |
| events | Event flags (EPOLLIN, EPOLLOUT etc.) |
| cb | The callback object |
Request a callback when a file descriptor is readable or writable, or if op is EPOLL_CTL_DEL then cancel a callback.
This function uses epoll as the underlying mechanism to manage file descriptors, so please refer to the documentation of epoll for detailed semantics.
events and cb are ignored when op is EPOLL_CTL_DEL.
A callback registered via this interface cannot be removed with sc_callback_remove, and must not be re-registered with another event source without first calling sc_epoll_ctl with op set to EPOLL_CTL_DEL.
| void sc_forward | ( | struct sc_node * | node, |
| const struct sc_node_link * | link, | ||
| struct sc_packet * | packet | ||
| ) |
Forward a single packet.
| node | The node's data structure |
| link | The link to forward to |
| packet | The packet to forward |
| void sc_forward_list | ( | struct sc_node * | node, |
| const struct sc_node_link * | link, | ||
| struct sc_packet_list * | pl | ||
| ) |
Forward a list of packets.
| node | The node's data structure |
| link | The link to forward to |
| pl | The list of packets to forward |
|
inlinestatic |
Copy data out of the end of a sc_iovec_ptr.
| dest_buf | Buffer to copy to. |
| iov | A pointer to an array of iovec objects. |
| iovlen | The number of iovec objects in iov. This must be > 0. |
| bytes | Number of bytes to copy. |
Note: The caller must ensure that at least bytes of data are available in iov
|
inlinestatic |
Returns the number of bytes represented by an sc_iovec_ptr.
| iovp | The sc_iovec_ptr |
| int sc_iovec_ptr_copy_out | ( | void * | dest, |
| struct sc_iovec_ptr * | iovp, | ||
| int | max_bytes | ||
| ) |
Copy data out of an sc_iovec_ptr.
| dest | Buffer to copy to |
| iovp | An sc_iovec_ptr |
| max_bytes | Max number of bytes to copy (length of dest) |
Returns the number of bytes copied.
| int sc_iovec_ptr_find_chr | ( | const struct sc_iovec_ptr * | iovp, |
| int | c | ||
| ) |
Find offset of character in iovec.
| iovp | An sc_iovec_ptr |
| c | Character to find |
Returns the offset of first occurrence of character c in the memory reference by iovp, or -1 if not found.
|
inlinestatic |
Initialise a struct sc_iovec_ptr.
| iovp | The sc_iovec_ptr to initialise |
| iov | Pointer to array of 'struct iovec's |
| iovlen | Length of the iov array |
|
inlinestatic |
Initialise a struct sc_iovec_ptr with a contiguous buffer.
| iovp | The sc_iovec_ptr to initialise |
| buf | Pointer to the start of the buffer |
| len | Length of the buffer |
|
inlinestatic |
Initialise a struct sc_iovec_ptr to point at packet data.
| iovp | The sc_iovec_ptr to initialise |
| packet | The packet |
| int sc_iovec_ptr_skip | ( | struct sc_iovec_ptr * | iovp, |
| int | bytes_to_skip | ||
| ) |
Skip forward over an iovec.
| iovp | An sc_iovec_ptr |
| bytes_to_skip | Number of bytes to skip over |
Returns the number of bytes skipped, which may be fewer than bytes_to_skip if the total amount of memory referenced by iovp is less.
|
inlinestatic |
Remove data from the end of an iovec.
| iov | A pointer to an array of iovec objects. |
| iovlen | The number of iovec objects in iov. |
| bytes | The number of bytes to trim. |
Note: Caller must ensure that at least bytes of data are available in iov.
| int sc_join_mcast_group | ( | struct sc_session * | scs, |
| const char * | interface, | ||
| const char * | group | ||
| ) |
Join a multicast group.
| scs | A session |
| interface | The network interface to join on |
| group | The multicast group to join |
This function joins multicast group group on interface interface. This is needed when you need to use the IGMP protocol to arrange that multicast packets are delivered to the adapter.
| int sc_mailbox_alloc | ( | struct sc_mailbox ** | mb_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread | ||
| ) |
Allocate a mailbox.
| mb_out | The allocated mailbox is returned here. |
| attr | Attributes (see sc_attr). |
| thread | The thread the mailbox will be in. |
Mailboxes are used to pass packets between threads. To communicate you need a mailbox in each thread, and together they form a bi-directional link.
From SolarCapture 1.1 onwards it is not usually necessary to create mailboxes explicitly: They are created automatically when objects in different threads are connected together.
| int sc_mailbox_connect | ( | struct sc_mailbox * | mb1, |
| struct sc_mailbox * | mb2 | ||
| ) |
Connect a pair of mailboxes.
| mb1 | The first mailbox. |
| mb2 | The second mailbox. |
Link a pair of mailboxes so that they can communicate. A mailbox can only be connected once.
| struct sc_node* sc_mailbox_get_send_node | ( | struct sc_mailbox * | mailbox | ) |
Return a mailbox's "send node".
| mailbox | The mailbox. |
This function returns the mailbox's send-node. Packets passed to this send-node are forwarded to the paired mailboxes recv-node.
| int sc_mailbox_poll | ( | struct sc_mailbox * | mailbox, |
| struct sc_packet_list * | list | ||
| ) |
Poll a mailbox.
| mailbox | The mailbox to poll. |
| list | Received packets are appended to this list. |
This function should only be invoked on an unmanaged mailbox. It is necessary to poll a mailbox in order to receive packets from other threads, and to ensure that sent packets are delivered.
| void sc_mailbox_send | ( | struct sc_mailbox * | mailbox, |
| struct sc_packet * | packet | ||
| ) |
Send a packet through a mailbox to another thread.
| mailbox | The mailbox. |
| packet | The packet to send. |
This function should only be invoked on an unmanaged mailbox.
Invoke this function to place a packet on a mailbox's send queue. NB. The packet may not actually be delivered to the remote thread until a later call to sc_mailbox_poll().
| void sc_mailbox_send_list | ( | struct sc_mailbox * | mailbox, |
| struct sc_packet_list * | list | ||
| ) |
Send a list of packets through a mailbox to another thread.
| mailbox | The mailbox. |
| list | The packets to send. |
This function should only be invoked on an unmanaged mailbox.
Invoke this function to place packets on a mailbox's send queue. NB. The packets may not actually be delivered to the remote thread until a later call to sc_mailbox_poll().
| int sc_mailbox_set_recv | ( | struct sc_mailbox * | mailbox, |
| struct sc_node * | node, | ||
| const char * | name_opt | ||
| ) |
Connect a mailbox to a node.
| mailbox | The mailbox. |
| node | The node. |
| name_opt | Optional ingress port name (may be NULL). |
Connect the output of a mailbox to a node. Packets passed to the send-node of the paired mailbox are passed to node.
| void sc_node_add_info_int | ( | struct sc_node * | node, |
| const char * | field_name, | ||
| int64_t | field_val | ||
| ) |
Export information to solar_capture_monitor.
| node | The node exporting state. |
| field_name | Name of field. |
| field_val | State to export. |
Use this function to export static runtime information about a node to solar_capture_monitor. This function can be used in the implementation of a new node type, or in an application using a node.
See also sc_node_add_info_str() and sc_node_export_state().
| void sc_node_add_info_str | ( | struct sc_node * | node, |
| const char * | field_name, | ||
| const char * | field_val | ||
| ) |
Export information to solar_capture_monitor.
| node | The node exporting state. |
| field_name | Name of field. |
| field_val | State to export. |
Use this function to export static runtime information about a node to solar_capture_monitor. This function can be used in the implementation of a new node type, or in an application using a node.
See also sc_node_add_info_int() and sc_node_export_state().
| int sc_node_add_link | ( | struct sc_node * | from_node, |
| const char * | link_name, | ||
| struct sc_node * | to_node, | ||
| const char * | to_name_opt | ||
| ) |
Add a link from one node to another.
| from_node | Node to connect from. |
| link_name | Name of the from_node's egress link. |
| to_node | Node to connect to. |
| to_name_opt | Optional ingress port name (may be NULL). |
Packets flow from node to node along links. This function adds a link from from_node to to_node.
link_name identifies from_node's egress link. By convention the default egress link is named "".
Some node types support multiple ingress ports so that the node can receive and separate multiple incoming packet streams. The name of the ingress port is given by to_name_opt.
Since SolarCapture 1.1, if the nodes are in different threads then this function automatically creates a link between the threads using mailboxes.
| int sc_node_alloc | ( | struct sc_node ** | node_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread, | ||
| const struct sc_node_factory * | factory, | ||
| const struct sc_arg * | args, | ||
| int | n_args | ||
| ) |
Allocate a packet processing node.
| node_out | The allocated node is returned here |
| attr | Attributes |
| thread | The thread the node will be in |
| factory | A node factory |
| args | An array of arguments for node initialisation |
| n_args | The number of arguments |
Nodes perform packet processing services such as filtering, packet modification, import/export and packet injection.
A node factory allocates nodes of a particular type, and the argument list provides configuration for the node instance.
Use this function when you have a pointer to the node factory. For built-in nodes or nodes in a separate library it is simpler to use sc_node_alloc_named().
| int sc_node_alloc_named | ( | struct sc_node ** | node_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread, | ||
| const char * | factory_name, | ||
| const char * | lib_name, | ||
| const struct sc_arg * | args, | ||
| int | n_args | ||
| ) |
Allocate a packet processing node by name.
| node_out | The allocated node is returned here. |
| attr | Attributes. |
| thread | The thread the node will be in. |
| factory_name | Name of the node factory. |
| lib_name | Name of the node library (may be NULL). |
| args | An array of arguments for node initialisation. |
| n_args | The number of arguments. |
Nodes perform packet processing services such as filtering, packet modification, import/export and packet injection.
This function allocates a node of type factory_name, and the argument list provides configuration for the node instance.
This function is a short-cut for sc_node_factory_lookup() followed by sc_node_alloc().
| int sc_node_export_state | ( | struct sc_node * | node, |
| const char * | type_name, | ||
| int | type_size, | ||
| void * | pp_area | ||
| ) |
Export dynamic state to solar_capture_monitor.
| node | The node exporting state |
| type_name | Name of the exported datastructure |
| type_size | Size in bytes of the exported datastructure |
| pp_area | Pointer to memory is returned here |
Use this function to export dynamic runtime information about a node to solar_capture_monitor. The information can include configuration information, statistics and/or other runtime state.
pp_area gives the address of a pointer that is overwritten with a pointer to the memory area large enough for an instance of type_name. So pp_area should be of type 'struct type_name**'.
The type type_name must already have been declared by creating the type_name_declare() function using declare_types.h::SC_DECLARE_TYPES and calling it.
See also sc_node_add_info_str() and sc_node_add_info_int(), which are useful for exporting static data.
| int sc_node_factory_lookup | ( | const struct sc_node_factory ** | factory_out, |
| struct sc_session * | session, | ||
| const char * | factory_name, | ||
| const char * | lib_name | ||
| ) |
Find a node factory.
| factory_out | The node factory found. |
| session | The SolarCapture session. |
| factory_name | Name of the node factory. |
| lib_name | Name of the node library (may be NULL). |
Finds the factory of name factory_name. It may be a built-in factory (in which case lib_name should be NULL) or a factory in an external library.
A factory library is a shared object file that contains one or more node factory instances.
lib_name may be NULL, in which case it defaults to being the same as the factory_name.
If lib_name contains a '/' character it is treated as the full path to the library object file.
Otherwise lib_name is the name of the library object file (either with or without a .so suffix). This function will search for the library object file in the following directories (in order):
Depending on the target system, not all of the above directories may exist. In particular, the subdirectories of /usr/lib/x86_64-linux-gnu/ will only exist on Debian-derived systems using the multiarch structure for library folders. This is not expected to cause a problem at runtime.
If we decide to support 32-bit builds again, these directories will be searched instead (in order):
If a library containing the named factory is not found by this search, the built-in nodes are searched last.
| struct sc_thread* sc_node_get_thread | ( | const struct sc_node * | node | ) |
Return the thread associated with a node.
| node | The node. |
| int sc_node_init_get_arg_dbl | ( | double * | v_out, |
| struct sc_node * | node, | ||
| const char * | name, | ||
| double | v_default | ||
| ) |
Get a double argument.
| v_out | On success, the value is returned here |
| node | The node |
| name | The name of the argument |
| v_default | Default returned if arg not found |
This may only be called from sc_node_init_fn. Returns 0 if the argument is found, else 1 if not found (in which case v_default is copied to v_out), or -1 if the argument was found but is of the wrong type.
| int sc_node_init_get_arg_int | ( | int * | v_out, |
| struct sc_node * | node, | ||
| const char * | name, | ||
| int | v_default | ||
| ) |
Get an integer argument.
| v_out | On success, the value is returned here |
| node | The node |
| name | The name of the argument |
| v_default | Default returned if arg not found |
This may only be called from sc_node_init_fn. Returns 0 if the argument is found, else 1 if not found (in which case v_default is copied to v_out), or -1 if the argument was found but is of the wrong type.
| int sc_node_init_get_arg_obj | ( | struct sc_object ** | obj_out, |
| struct sc_node * | node, | ||
| const char * | name, | ||
| enum sc_object_type | obj_type | ||
| ) |
Get an sc_object argument.
| obj_out | On success, the value is returned here |
| node | The node |
| name | The name of the argument |
| obj_type | The type of object wanted, or SC_OBJ_ANY |
This may only be called from sc_node_init_fn. Returns 0 if the argument is found, else 1 if not found, or -1 if the argument was found but is of the wrong type (i.e. not an object, or the wrong type of object).
| int sc_node_init_get_arg_str | ( | const char ** | v_out, |
| struct sc_node * | node, | ||
| const char * | name, | ||
| const char * | v_default | ||
| ) |
Get an string argument.
| v_out | On success, the value is returned here |
| node | The node |
| name | The name of the argument |
| v_default | Default returned if arg not found |
This may only be called from sc_node_init_fn. Returns 0 if the argument is found, else 1 if not found (in which case v_default is copied to v_out), or -1 if the argument was found but is of the wrong type.
The string returned is valid only until the sc_node_init_fn call returns.
| void sc_node_link_end_of_stream | ( | struct sc_node * | node, |
| const struct sc_node_link * | link | ||
| ) |
Indicate end-of-stream on a link.
| node | The node |
| link | The link |
It is a fatal error to forward any further packets through the link after calling this function.
| int sc_node_prep_check_links | ( | struct sc_node * | node | ) |
Check the node's links for any unused links.
| node | The node |
This may only be called from sc_node_prep_fn(), and should only be used by nodes that find their links by calling sc_node_prep_get_link().
This function will complain about any links added to the node that have not been queried by sc_node_prep_get_link(). It may emit a warning, or generate an error.
Returns 0 if all is fine (or only warnings are needed). Returns -1 on error, which should be propagated out of sc_node_prep_fn().
| const struct sc_node_link* sc_node_prep_get_link | ( | struct sc_node * | node, |
| const char * | link_name | ||
| ) |
Find a named outgoing link.
| node | The node |
| link_name | Name of the link |
It returns NULL if the named link doesn't exist.
A node's sc_node_prep_fn can either use this mechanism to query its links, or it can simply iterate over the links passed as arguments to sc_node_prep_fn.
This function may only be called from sc_node_prep_fn.
See also sc_node_prep_check_links().
| const struct sc_node_link* sc_node_prep_get_link_or_free | ( | struct sc_node * | node, |
| const char * | link_name | ||
| ) |
Find a named outgoing link or return a link for freeing.
| node | The node |
| link_name | Name of the link |
This function behaves just like sc_node_prep_get_link(), except that if no link of that name has been added to the node, a special link is returned that frees packets.
link_name may be NULL, in which case a link for freeing packets is returned.
| int sc_node_prep_get_pool | ( | struct sc_pool ** | pool_out, |
| const struct sc_attr * | attr, | ||
| struct sc_node * | node, | ||
| const struct sc_node_link *const * | links, | ||
| int | n_links | ||
| ) |
Get a packet pool that can be used to obtain empty packet buffers that can be passed to any of the given set of links.
| pool_out | On success, the pool is returned here |
| attr | Packet pool attributes (optional, may be NULL) |
| node | The node |
| links | The link(s) packets from the pool may be passed to (set to NULL for all) |
| n_links | Number of links in 'links' |
The node must only forward packets from the returned pool over the links identified by links and n_links. If n_links is 0 then it is assumed that packets from the pool may be forwarded over any of the node's links.
Restricting the links packets can be sent along allows SolarCapture to optimise the releasing of packets back to the pool when the node graph is finished with them.
This may only be called from sc_node_prep_fn.
| int sc_node_type_alloc | ( | struct sc_node_type ** | nt_out, |
| const struct sc_attr * | attr_opt, | ||
| const struct sc_node_factory * | factory | ||
| ) |
Allocate an sc_node_type instance.
| nt_out | The allocated sc_node_type instance |
| attr_opt | Optional attributes (may be NULL) |
| factory | The factory that created the node |
At the time of writing attr_opt is not used and this call always succeeds. In future it may fail if the attributes are invalid in some way.
|
inlinestatic |
Convert milliseconds to nanoseconds.
| ms | The time in milliseconds to convert |
|
inlinestatic |
Convert a timespec struct to nanoseconds.
| ts | The timespec struct to convert |
|
inlinestatic |
Convert a timeval struct to nanoseconds.
| tv | The timeval struct to convert |
|
inlinestatic |
Convert microseconds to nanoseconds.
| us | The time in microseconds to convert |
| enum sc_object_type sc_object_type | ( | struct sc_object * | obj | ) |
Return the type of data contained within the sc_object.
| obj | The object to check the data type of. |
| int sc_opaque_alloc | ( | struct sc_object ** | obj_out, |
| void * | opaque | ||
| ) |
Allocate memory for an opaque sc_object.
| obj_out | On success the allocated object. |
| opaque | A pointer to the data to be wrapped by the object. |
| void sc_opaque_free | ( | struct sc_object * | obj | ) |
Free an sc_object previously allocated using sc_opaque_alloc. Only use this to free an opaque sc_object. The underlying data wrapped by this object will not be freed.
| obj | The object to free |
| void* sc_opaque_get_ptr | ( | const struct sc_object * | obj | ) |
Get the opaque pointer stored in an sc_object.
| obj | The object to fetch the opaque pointer from. |
| void sc_opaque_set_ptr | ( | struct sc_object * | obj, |
| void * | opaque | ||
| ) |
Set the opaque pointer in an sc_object.
| obj | The object to set the pointer on |
| opaque | The new opaque pointer to use |
| int sc_packet_append_iovec_ptr | ( | struct sc_packet * | packet, |
| struct sc_pool * | pool, | ||
| struct sc_iovec_ptr * | iovp, | ||
| int | snap | ||
| ) |
Append data to a packet.
| packet | The packet to append data to |
| pool | Packet pool to allocate frag buffers from (optional) |
| iovp | Identifies the data to copy in |
| snap | The maximum number of bytes to copy in |
Returns 0 if all the requested data could be appended. Returns -1 if more space was needed and it was not possible to allocate fragment buffers. Returns -2 if the packet runs out of space (ie. the fragments chain would exceed the maximum chain length).
If you need to know the number of bytes appended, compare the packet frame_len before and after the call.
|
inlinestatic |
Return the size of the packet data in bytes.
| p | A packet object. |
Return a packet's last fragment.
| p | A packet object. |
The result is only valid if the packet has at least one fragment.
|
inlinestatic |
Append a packet to a list and finalise.
| l | The packet list. |
| p | The packet. |
|
inlinestatic |
Append a list to a list.
| dest | The list to be extended. |
| src | The list to be appended to dest. |
After this call dest is finalised if and only if src was finalised.
src must be non-empty.
|
inlinestatic |
Finalise a list.
| l | The packet list. |
If a list is not finalised, it is possible that the next pointer of tail is not NULL.
|
inlinestatic |
Initialise a list.
| l | The packet list. |
|
inlinestatic |
Check if packet list is empty.
| l | The packet list. |
|
static |
Remove and return the head of the list.
| pl | The packet list. |
This must only be invoked on a non-empty list.
|
inlinestatic |
Push a packet to the head of a list.
| pl | The packet list. |
| p | The packet. |
|
static |
Return the tail of current tail of the list.
| l | The packet list. |
|
inlinestatic |
Prefetch a packet for reading.
| p | A packet object. |
|
inlinestatic |
Prefetch a packet for reading and writing.
| p | A packet object. |
|
static |
Return the timestamp of the packet in timespec format.
| p | A packet object. |
| int sc_pkt_predicate_alloc | ( | struct sc_pkt_predicate ** | pred_out, |
| int | private_bytes | ||
| ) |
Allocate a packet predicate object.
| pred_out | On success the allocated sc_pkt_predicate object. |
| private_bytes | Size of private memory area wanted. |
Packet predicates are used to test packets against some criteria. The test function should return true (1) or false (0).
If private_bytes is non-zero then pred_private is initialised with a pointer to a region of memory of size private_bytes. The pred_private field may be used by the implementation to hold state.
| struct sc_pkt_predicate* sc_pkt_predicate_from_object | ( | struct sc_object * | obj | ) |
Convert a sc_object into a sc_pkt_predicate.
| obj | An sc_object instance or NULL |
obj is NULL otherwise the converted sc_pkt_predicate. | struct sc_object* sc_pkt_predicate_to_object | ( | struct sc_pkt_predicate * | pred | ) |
Convert a sc_pkt_predicate into a sc_object.
| pred | An sc_pkt_predicate instance or NULL |
pred is NULL otherwise the converted sc_object. | struct sc_packet* sc_pool_duplicate_packet | ( | struct sc_pool * | pool, |
| struct sc_packet * | packet, | ||
| int | snap | ||
| ) |
Duplicate a packet.
| pool | The pool to allocate buffers from |
| packet | The packet to duplicate |
| snap | The maximum number of bytes to copy |
| int sc_pool_get_packets | ( | struct sc_packet_list * | list, |
| struct sc_pool * | pool, | ||
| int | min_packets, | ||
| int | max_packets | ||
| ) |
Get packet buffers from a pool.
| list | List where retrieved packets are placed |
| pool | The packet pool |
| min_packets | Minimum number of buffers to be returned |
| max_packets | Maximum number of buffers to be returned |
Returns the number of buffers added to list, or -1 if the minimum could not be satisfied.
list must be initialised on entry (and may already contain some packets), but need not be finalised. The list is finalised on return unless an error is returned (in which case the list is not modified).
Each packet returned is initialised as follows: pkt->flags = 0; pkt->frame_len = 0; pkt->iovlen = 1; pkt->iov[0] gives the base and extent of the DMA area The fragment list is empty
The following packet fields have undefined values: ts_sec, ts_nsec.
| void sc_pool_on_threshold | ( | struct sc_pool * | pool, |
| struct sc_callback * | event, | ||
| int | threshold | ||
| ) |
Request a callback when the pool is refilled.
| pool | The packet pool |
| event | The event object |
| threshold | Event fires when pool has >= threshold buffers |
Registers an event handler that is invoked when the pool fill level reaches the specified threshold. If the pool fill level is already at or above the threshold, the handler will be invoked as soon as possible.
| void sc_pool_return_packets | ( | struct sc_pool * | pool, |
| struct sc_packet_list * | list | ||
| ) |
Return packets to a pool.
| pool | The packet pool |
| list | List of packets to return |
list must be initialised on entry, but can be empty. The packets on the list can have frags.
| int sc_session_alloc | ( | struct sc_session ** | scs_out, |
| const struct sc_attr * | attr | ||
| ) |
Allocate a SolarCapture session.
| scs_out | The allocated session object is returned here |
| attr | Attributes for the new session |
This function allocates a SolarCapture session.
A session comprises a set of threads, VIs, nodes and/or other SolarCapture objects.
| void sc_session_error_free | ( | struct sc_session * | scs, |
| struct sc_session_error * | err | ||
| ) |
Frees an error object.
| scs | The session |
| err | The error |
Frees a sc_session_error pointer returned by sc_session_error_get.
| struct sc_session_error* sc_session_error_get | ( | struct sc_session * | scs | ) |
Returns an error from a SolarCapture session.
| scs | The session |
Returns a pointer to a sc_session_error struct representing the error encountered by session scs. The caller should pass the pointer to sc_session_error_free once once done with it.
If no error has occurred, this function returns NULL.
| int sc_session_go | ( | struct sc_session * | scs | ) |
Start a SolarCapture session.
| scs | The session |
Prepare the session scs (if necessary) and start the managed threads. This is usually called just once, after allocating resources. It can also be called after sc_session_pause() to restart a paused session.
| int sc_session_pause | ( | struct sc_session * | scs | ) |
Pause a SolarCapture session.
| scs | The session |
Pause the threads managed by session scs.
| int sc_session_prepare | ( | struct sc_session * | scs | ) |
Prepare a SolarCapture session.
| scs | The session |
Prepare the session scs. This step includes finalising resource allocations, preparing nodes, and starting packet capture. Managed threads are started in the "paused" state.
Note that although packet capture is started, you may get packet loss if the threads managing 'sc_vi's are not started soon afterwards.
Call sc_session_go() to start the managed threads and begin packet processing.
| int sc_stream_all | ( | struct sc_stream * | stream | ) |
Configure this stream to capture all packets that haven't been caught by another stream.
| stream | The stream to send the packets to. |
Returns 0 on success, a negative number on failure.
| int sc_stream_alloc | ( | struct sc_stream ** | stream_out, |
| const struct sc_attr * | attr, | ||
| struct sc_session * | scs | ||
| ) |
Create a new stream object for this session.
| stream_out | On success, the created stream. |
| attr | Attributes to pass in. |
| scs | The session this stream is for. |
This function returns 0 on success or a negative number on failure.
| int sc_stream_eth_dhost | ( | struct sc_stream * | stream, |
| const uint8_t * | mac_addr | ||
| ) |
Configure this stream to capture all packets with the matching destination MAC address.
| stream | The stream to send the packets to. |
| mac_addr | The destination MAC address to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_eth_shost | ( | struct sc_stream * | stream, |
| const uint8_t * | mac_addr | ||
| ) |
Configure this stream to capture all packets with the matching source MAC address.
| stream | The stream to send the packets to. |
| mac_addr | The source MAC address to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_eth_type | ( | struct sc_stream * | stream, |
| uint16_t | eth_type | ||
| ) |
Configrue this stream to capture all packets with the matching ethernet type.
| stream | The stream to send the packets to. |
| eth_type | The internet layer protocol to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_eth_vlan_id | ( | struct sc_stream * | stream, |
| int | vlan_id | ||
| ) |
Configure this stream to capture all packets with the matching VLAN ID.
| stream | The stream to send the packets to. |
| vlan_id | The VLAN ID to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_free | ( | struct sc_stream * | stream | ) |
Free a previously created stream.
| stream | The stream to free. |
This function will always return 0.
| int sc_stream_ip_dest_host | ( | struct sc_stream * | stream, |
| const char * | dhost | ||
| ) |
Configure this stream to capture all packets with matching destination hostname.
| stream | The stream to send the packets to. |
| dhost | The destination hostname to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_dest_hostport | ( | struct sc_stream * | stream, |
| int | protocol, | ||
| const char * | dhost, | ||
| const char * | dport | ||
| ) |
Configure this stream to capture all packets with the matching protocol, destination hostname and destination port.
| stream | The stream to send the packets to. |
| protocol | The transport layer protocol to match against. |
| dhost | The destination hostname to match against. |
| dport | The destination port to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_dest_port | ( | struct sc_stream * | stream, |
| const char * | dport | ||
| ) |
Configure this stream to capture all packets with matching destination port.
| stream | The stream to send the packets to. |
| dport | The destination port to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_protocol | ( | struct sc_stream * | stream, |
| int | protocol | ||
| ) |
Configure this stream to capture all packets with matching IP protocol.
| stream | The stream to send the packets to. |
| protocol | The IP protocol to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_source_host | ( | struct sc_stream * | stream, |
| const char * | shost | ||
| ) |
Configure this stream to capture all packets with matching source hostname.
| stream | The stream to send the packets to. |
| shost | The source hostname to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_source_hostport | ( | struct sc_stream * | stream, |
| const char * | shost, | ||
| const char * | sport | ||
| ) |
Configure this stream to capture all packets with the matching protocol, source hostname and source port.
| stream | The stream to send the packets to. |
| shost | The source hostname to match against. |
| sport | The source port to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_ip_source_port | ( | struct sc_stream * | stream, |
| const char * | sport | ||
| ) |
Configure this stream to capture all packets with matching source port.
| stream | The stream to send the packets to. |
| sport | The source port to match against. |
Returns 0 on success, a negative number on failure.
| int sc_stream_mismatch | ( | struct sc_stream * | stream | ) |
Configure this stream to capture all packets that haven't been caught by another stream and are not requested by the kernel network stack.
| stream | The stream to send the packets to. |
Returns 0 on success, a negative number on failure.
| int sc_stream_reset | ( | struct sc_stream * | stream | ) |
Remove all stream filters.
| stream | The stream to remove the filters from. |
| int sc_stream_set_str | ( | struct sc_stream * | stream, |
| const char * | str | ||
| ) |
Configure the stream to capture all packets matching the specified filter string. This is the preferred way of adding filters to a stream.
| stream | The stream to send the packets to. |
| str | The filter to match against. Filters are constructed as a comma separated list of key-value pairs, except for the special cases "all", "mismatch", "ip", "tcp", and "udp". Available keywords are: |
| key-value pair | Description |
|---|---|
| dmac=xx:xx:xx:xx:xx:xx | Filter on destination MAC address. |
| smac=xx:xx:xx:xx:xx:xx | Filter on source MAC addres. |
| vid=INT | Filter on VLAN id number. |
| eth_type=ip|INT | Filter on the ethernet type number (see net/ethertype.h header). |
| shost=hostname | Filter on source hostname, hostname can be either an IP address or a resolvable string. |
| dhost=hostname | Filter on destination hostname, hostname can be either an IP address or a resolvable string. |
| ip_protocol=udp|tcp|INT | Filter on ip protocol (set netinet/in.h header). |
| sport=INT | Filter on source port. |
| dport=INT | Filter on destination port. |
| all | All packets to this stream that haven't been filtered by another stream. |
| mismatch | All packets to this stream that haven't been filtered by another stream and are not requested by the kernel network stack. |
| ip | Shorthand for eth_type=ip. |
| tcp | Shorthand for ip_protocol=tcp. |
| udp | Shorthand for ip_protocol=udp. |
This function will return 0 on success or a negative number on failure.
| int sc_thread_alloc | ( | struct sc_thread ** | thread_out, |
| const struct sc_attr * | attr, | ||
| struct sc_session * | scs | ||
| ) |
Allocate a SolarCapture thread.
| thread_out | The allocated thread object is returned here |
| attr | Attributes |
| scs | The session |
This function allocates a SolarCapture thread.
Normally SolarCapture creates an OS thread for the sc_thread object, and starts the thread when sc_session_go() is called. If the 'managed' attribute is set to false, then it is up to the application to create an underlying thread.
| void* sc_thread_calloc | ( | struct sc_thread * | thread, |
| size_t | bytes | ||
| ) |
Allocate memory to be used by a thread.
| thread | The thread |
| bytes | Size of memory area to allocate |
This function is intended to be used for allocating small amounts of memory that are used on performance critical paths, such as the private state used by the implementation of a node.
The memory region may overlap cache lines used by other allocations from this API for the same thread.
| void* sc_thread_calloc_aligned | ( | struct sc_thread * | thread, |
| size_t | bytes, | ||
| int | align | ||
| ) |
Allocate memory to be used by a thread.
| thread | The thread |
| bytes | Size of memory area wanted |
| align | Alignment of memory area wanted |
This function is intended to be used for allocating small amounts of memory that are used on performance critical paths, such as the private state used by the implementation of a node.
The memory region may overlap cache lines used by other allocations from this API for the same thread.
| void sc_thread_get_time | ( | const struct sc_thread * | thread, |
| struct timespec * | time_out | ||
| ) |
Return a thread's "current time".
| thread | The thread |
| time_out | The current time is returned here |
Each thread's current time is updated by the polling loop, so may or may not be up-to-date when you call this function. The clock used as the time base is CLOCK_REALTIME.
| void sc_thread_mfree | ( | struct sc_thread * | thread, |
| void * | mem | ||
| ) |
Free memory.
| thread | The thread |
| mem | The memory area |
Use this function to free memory allocated with sc_thread_calloc or sc_thread_calloc_aligned.
| int sc_thread_poll | ( | struct sc_thread * | thread | ) |
Poll a thread.
| thread | The thread. |
Use this function to poll an unmanaged thread. This drives events through the node graph.
Note: For managed threads this functionality is provided internally by solar_capture.
The return value indicates whether any work was done. If the return is true, then one of the following has happened: Packets have been received by a VI; Packets have been received by a mailbox; Packets have been handled by a node; A timer has expired.
| void sc_timer_expire_after_ns | ( | struct sc_callback * | cb, |
| int64_t | delta_ns | ||
| ) |
Request a callback in the future.
| cb | A callback object |
| delta_ns | How far in the future in nanoseconds. |
The callback will be invoked at or after the specified time delta in nanoseconds. If delta_ns is zero or negative then the handler function will be invoked as soon as possible.
| void sc_timer_expire_at | ( | struct sc_callback * | cb, |
| const struct timespec * | time | ||
| ) |
Request a callback at a given time.
| cb | A callback object |
| time | Time at which callback is requested |
The callback cb will be invoked at or after the specified time. If the time is in the past, then the handler function will be invoked as soon as possible.
The time is relative to the system realtime clock (CLOCK_REALTIME), which is the same clock returned by sc_thread_get_time().
| int sc_timer_get_expiry_time | ( | const struct sc_callback * | cb, |
| struct timespec * | ts_out | ||
| ) |
Return the expiry time of a timer callback.
| cb | A callback object |
| ts_out | The expiry time is returned here |
cb is a timer else -1 | void sc_timer_push_back_ns | ( | struct sc_callback * | cb, |
| int64_t | delta_ns | ||
| ) |
Push the expiry time further into the future.
| cb | A callback object |
| delta_ns | How far in the future in nanoseconds. |
This function pushes the expiry time of a timer callback further into the future.
The callback cb must either be a currently active timer registered with sc_timer_expire_at() or sc_timer_expire_after_ns(), or it must be an inactive timer. ie. The most recent use of cb must have been as a timer callback.
If cb is active, then it is rescheduled at its current expiry time plus delta_ns. If it is not active then it is scheduled at its previous expiry time plus delta_ns.
| int sc_vi_add_stream | ( | struct sc_vi * | vi, |
| struct sc_stream * | stream | ||
| ) |
Direct a packet stream to a VI.
| vi | The VI receiving packets |
| stream | The packet stream |
Arrange for the packet stream identified by stream to be copied or steered to vi.
| int sc_vi_alloc | ( | struct sc_vi ** | vi_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread, | ||
| const char * | interface | ||
| ) |
Allocate a VI instance.
| vi_out | The allocated VI is returned here |
| attr | Attributes |
| thread | The thread the VI will be in |
| interface | The network interface to receive packets from |
A VI is a "virtual network interface" and supports receiving packets from the network. Packets received by a VI are passed to nodes (sc_node) for processing.
| int sc_vi_alloc_from_group | ( | struct sc_vi ** | vi_out, |
| const struct sc_attr * | attr, | ||
| struct sc_thread * | thread, | ||
| struct sc_vi_group * | vi_group | ||
| ) |
Allocate a VI instance from a VI group.
| vi_out | The allocated VI is returned here |
| attr | Attributes |
| thread | The thread the VI will be in |
| vi_group | The VI group |
See also sc_vi_group_alloc() and sc_vi_alloc().
| const char* sc_vi_get_interface_name | ( | const struct sc_vi * | vi | ) |
Return the name of the network interface associated with a VI.
| vi | The VI |
This call returns the name of the network interface associated with the sc_vi object. This can be different from the interface name used to create the sc_vi when application clustering is used.
The network interface name is most often needed so that the application can create an injector on the same interface as a VI.
| struct sc_thread* sc_vi_get_thread | ( | const struct sc_vi * | vi | ) |
Return the thread associated with a VI.
| vi | The VI |
| int sc_vi_group_add_stream | ( | struct sc_vi_group * | vi_group, |
| struct sc_stream * | stream | ||
| ) |
Direct a packet stream to a group of VIs.
| vi_group | The VI group receiving packets |
| stream | The packet stream |
Arrange for the packet stream identified by stream to be copied or steered to the VIs that comprise vi_group.
Note that packets are spread over the VIs in a group by computing a hash on the addresses in the packet headers. Normally the hash is computed over the IP addresses, and for TCP packets also the port numbers. The hash selects a VI within the group, so that packets with the same addresses are consistently delivered to the same VI.
If stream identifies a set of packets that all have the same source and destination IP addresses (and ports in the case of TCP) then they will all be received by a single VI.
| int sc_vi_group_alloc | ( | struct sc_vi_group ** | vi_out, |
| const struct sc_attr * | attr, | ||
| struct sc_session * | session, | ||
| const char * | interface, | ||
| int | num_vis | ||
| ) |
Allocate a VI group.
| vi_out | The allocated VI is returned here |
| attr | Attributes |
| session | The SolarCapture session |
| interface | The network interface to receive packets from |
| num_vis | The number of VIs in the group |
A VI group provides a way to distribute packet capture over multiple threads. A VI group consists of a set of VIs, each of which receives a distinct subset of the streams directed at the group.
Streams are directed to a group by calling sc_vi_group_add_stream().
While a VI allocated from a group receives packets from streams directed to the group (sc_vi_group_add_stream()), it is also possible to use sc_vi_add_stream() to direct a specific stream to a specific member of the group.
| struct sc_session* sc_vi_group_get_session | ( | const struct sc_vi_group * | vi_group | ) |
Return the session associated with a VI group.
| vi_group | The VI group |
Set the node a VI should deliver its received packets to.
| vi | The VI receiving packets |
| node | The node to deliver packets to |
| name_opt | Optional ingress port name (may be NULL) |
Since SolarCapture 1.1, if node is in a different thread from vi, then this function automatically creates a link between the threads using mailboxes.
1.8.6