#include "orb.h" int orbopen(char *orbhost, char *perm) int orbclose(int orbfd) int orbput(int orbfd, char *srcname, double pkttime, char *pkt, int nbytes) int orbputx(int orbfd, char *srcname, double pkttime, char *pkt, int nbytes) int orbget(int orbfd, int whichpkt, int *pktid, char *srcname, double *pkttime, char **pkt, int *nbytes, int *bufsize) int orbreap(int orbfd, int *pktid, char *srcname, double *pkttime, char **pkt, int *nbytes, int *bufsize) int orbreap_nd(int orbfd, int *pktid, char *srcname, double *pkttime, char **pkt, int *nbytes, int *bufsize) int orbreap_timeout(int orbfd, int maxseconds, int *pktid, char *srcname, double *pkttime, char **pkt, int *nbytes, int *bufsize) int orbseek(int orbfd, int whichpkt) int orbtell(int orbfd) int orbposition(int orbfd, char *orbwhere) int orbafter(int orbfd, double atime) int orbselect(int orbfd, char *regex) int orbreject(int orbfd, char *regex) int orbping(int orbfd, int *orbversion) int orbset_logging(int orbfd, int level) int orbstat(int orbfd, Orbstat **orbstat) int orbsources(int orbfd, double *atime, Orbsrc **source, int *nsource) int orbclients(int orbfd, double *atime, Orbclient **client, int *nclient) int orbstashselect ( int orb, int stashflag ) int orbgetstash ( int orb, char *srcname, double *time, char **packet, int *nbytes, int *bufsize )
orbopen takes a name, orbhost, in the form server:port, and a permission, which may be either 'r' or 'w', and returns an orb connection descriptor, orbfd. orbhost may be an empty string, in which case the current machine and the default port are used. Alternatively, either just the server name (no colon) or just the port name (colon followed by a port number) may be specified.
If the last character of orbhost is an '@' character, then the orbopen will never return failure; instead it will continue to try to open a connection forever. Otherwise, orbopen makes one attempt and may fail for various reasons.
The permission (r or w) may optionally be followed with an ampersand, ie r& or w&. In this case, when an error occurs on the socket, or an end-of-file is encountered, the orb routines try continuously to close and reopen the port. If the port was opened with 'r&', then the library attempts to position the new port to the previous position (when it was closed), and restore its select/reject criteria. If the port was opened with 'w&', the library resends the previous packet as well as the current one. This appears to avoid most problems where a packet is dropped due to the loss of communication, though it may lead to duplicate packets on the orbserver.
Specifying the automatic reopen flag (the ampersand) causes the program to ignore SIGPIPE.
During any period when communications are unsuccessful, the orb routines do not return, except for orbreap_nd and orbreap_timeout. These generally return quickly, sometimes with an ORB_INCOMPLETE error code. However, an attempt to reopen the connection may take some time to fail (several seconds).
orbopen also accepts the name of a file, which must begin with either "/" or "./". In this case, rather than connecting to an existing orbserver, orbopen runs a subprocess, forbserver(1), which uses the named file for input. See forb(5) for details of the file format; files of this format can be written with orb2orb(1) or orbstat(1).
Orb ports are either write only, or primarily read. It is possible to use orbput on a port which was opened with the 'r' permission, but this orbput is slower and less efficient than an orbput on a port opened with 'w' permission. An orbput also disrupts an orbreap.
orbput takes an orbid, srcname, pkttime, a buffer with nbytes bytes, and sends it to the orb ring buffer server, returning zero for success, -1 for failure.
Typically, orb connections communicate without explicit handshakes, relying on the underlying tcp synchronization. However, this means that the pushing client does not know which packets have actually reached the orbserver when a connection fails. Some may be in flight.
At the expense of dramatically reduced throughput, you may use orbputx instead of orbput. This causes the orbserver to acknowledge each packet.
orbget takes an orbid and a code, and returns a pktid, a srcname, a pkttime, the actual packet pkt and the count of bytes in the packet. orbreap is very similar, but notifies the server to continuously send any available packets without waiting for an explicit request. Future calls to orbreap return the next available packet, blocking if no packet is available. Repeated calls to orbreap are faster than repeated calls to orbget, because the communication is all one way from the server, rather than requiring a two-way exchange.
select or poll can be used on the orb file descriptor to implement a non-blocking interface; however, it is important to call orbreap or related functions regularly to allow automatic reconnection.
Note that once orbreap has been called in a program, it should be called in a tight loop with no other orb calls intervening. Any intervening calls disrupt the stream of data from the orbserver; the caller must reposition itself on the ring buffer, as any in-flight packets from the orbserver are dropped, and thus packets could be missed.
orbreap and orbget block if a packet is not available, or if only part of a packet is read. This makes it problematic to use select with orbreap and orbget, as sometimes partial packets are read. However, the orbreap_nd call and orbreap_timeout calls (almost) always return quickly. They sometimes return ORB_INCOMPLETE, indicating that no packet is ready.
The bufsize argument to orbget and orbreap is expected to be a pointer to an integer which specifies the size of the packet buffer. The packet argument to orbget and orbreap must be a pointer to a pointer to malloc'ed memory. If *bufsize is too small, orbget or orbreap resize the memory buffer (using malloc(3.gz)) to be large enough to contain the packet. orbget and orbreap return nbytes, which is the actual size of the stored packet.
Each packet in the ring buffer receives a unique packet id, which is a small positive integer. Generally, you may ignore this packet id, although it is returned by orbget and orbreap.
Each read connection (opened file descriptor) to the orb ring buffer has an associated position in the ring buffer: a packet id. The current position can be obtained with orbtell, or set with orbseek. In addition, orbget and orbreap set the read position to the returned pktid. By default, the read position is initially set to the newest packet in the ring buffer.
orbget and orbseek accept several special values for whichpkt, that may be used to set the ring buffer read position :
The next or previous packet may not exist, in which case, a packet id of -1 is returned, and the read position is unchanged. A more insidious problem is that (after some time, perhaps a long time), the current read position becomes invalid. Once this occurs, (orbtell returns -1), the read position must be explicitly reset using orbseek and specifying ORBNEWEST or ORBOLDEST, or by using orbafter.
orbgetstash returns the current stash packet corresponding to the specified srcname, similar to orbget.
orbselect restricts packets to those for which the srcname completely matches the specified regular expression. By default, all sources are initially selected. A null string selects all sources. If the select string begins with '@', the remainder of the string identifies a file containing the selection criteria. All the lines in the file are joined into one large regular expression, consecutive lines separated by a '|' (pipe) character.
orbreject rejects packets for which the srcname completely matches the specified regular expression. Only packets which both match the orbselect regular expression, and don't match the orbreject regular expression are returned by orbreap. If the reject string begins with '@', the remainder of the string identifies a file containing the selection criteria. All the lines in the file are joined into one large regular expression, consecutive lines separated by a '|' (pipe) character.
orbstashselect may be used to eliminate stash packets from the input, or restrict the input to only stash packets, according to the following settings of stashflag.
STASH_ALL | all packets (default) | |
STASH_ONLY | only stash packets | |
NO_STASH | no stash packets |
orbafter sets the ring buffer read position to the first selected packet with a time tag after the specified time atime. It always returns immediately, even if no packet after the specified time is available.
orbposition can be used to position the orb using a string orbwhere. The string may contain either an epoch time (in any of the formats understood by str2epoch(3)), or the string newest or oldest. If the string is not understood (ie, it's neither newest, oldest, or a recognizable time string), the position is not changed.
orbping just pings the server; the server returns a version number orbversion.
orbset_logging allows setting the level of logging which the orbserver is doing on its machine. The possible values of level are ALL_MSGS, MY_MSGS, and CONNECTIONS to turn on that logging, or -ALL_MSGS, -MY_MSGS and -CONNECTIONS to turn off that logging.
orbstat, orbsources, and orbclients return various dynamic arrays, which are managed and reused by the orb interface. You should not attempt to free this space, nor keep and reuse old arrays across calls to orbstat, orbsources or orbclients.
orbreap_nd and orbreap_timeout may return ORB_INCOMPLETE, indicating no packet packet is ready. A partial packet may be in the returned buffer; a subsequent call to orbreap_nd fills in the rest of the packet.
orbopen returns a non-negative integer for success, -1 for failure.
orbclose, orbput, orbget, orbreap return zero for success, -1 for failure.
orbseek and orbafter return the read position pktid for success, -1 for error, leaving a message on the error log. In the event of an error, the current read position is unchanged.
orbtell should always return a pktid; it's possible that this pktid may refer to a packet which is no longer available, but this is only indicated by the failure of an attempt to get this packet.
orbposition returns the current pktid, after repositioning according to the argument.
orbping should always return zero.
orbselect returns the number of distinct sources selected, or zero to indicate all sources are selected.
orbshow_server, orbshow_clients and orbshow_sources dump the contents of the structure returned by orbstat to the specified file.
orbnames(5) orbserver(1) forbserver(1) forb(3) forb(5)
orbping should return a character string version.
orbselect should automatically cause newly added sources to be screened and possibly selected.