--- name: "dgr" section: "3" platform: "linux" package: "ion-doc" version: "3.2.1+dfsg-1.1" release: "Debian 9 (Stretch)" platforms: ["linux"] url: "https://new.carta.tech/dgr" --- # dgr(3) Datagram Retransmission system library ## NAME dgr - Datagram Retransmission system library ## SYNOPSIS ``` #include "dgr.h" [see description for available functions] ``` ## DESCRIPTION The DGR library is an alternative implementation of a subset of LTP, intended for use over UDP/IP in the Internet; unlike ION's canonical LTP implementation it includes a congestion control mechanism that interprets LTP block transmission failure as an indication of network congestion (not data corruption) and reduces data transmission rate in response. As such, DGR differs from many reliable-UDP systems in two main ways: ``` It uses adaptive timeout interval computation techniques borrowed from TCP to try to avoid introducing congestion into the network. It borrows the concurrent-session model of transmission from LTP (and ultimately from CFDP), rather than waiting for one datagram to be acknowledged before sending the next, to improve bandwidth utilization. ``` At this time DGR is interoperable with other implementations of LTP only when each block it receives is transmitted in a single LTP data segment encapsulated in a single UDP datagram. More complex LTP behavior may be implemented in the future. - int dgr\_open(uvast ownEngineId, unsigned in clientSvcId, unsigned short ownPortNbr, unsigned int ownIpAddress, char \*memmgrName, Dgr \*dgr, DgrRC \*rc) Establishes the application's access to DGR communication service. *ownEngineId* is the sending LTP engine ID that will characterize segments issued by this DGR service access point. In order to prevent erroneous system behavior, never assign the same LTP engine ID to any two interoperating DGR SAPs. *clientSvcId* identifies the LTP client service to which all LTP segments issued by this DGR service access point will be directed. *ownPortNbr* is the port number to use for DGR service. If zero, a system-assigned UDP port number is used. *ownIpAddress* is the Internet address of the network interface to use for DGR service. If zero, this argument defaults to the address of the interface identified by the local machine's host name. *memmgrName* is the name of the memory manager (see [*memmgr*(3)](/memmgr/3.md)) to use for dynamic memory management in DGR. If NULL, defaults to the standard system *malloc()* and *free()* functions. *dgr* is the location in which to store the service access pointer that must be supplied on subsequent DGR function invocations. *rc* is the location in which to store the DGR return code resulting from the attempt to open this service access point (always DgrOpened). On any failure, returns -1. On success, returns zero. - void dgr\_getsockname(Dgr dgr, unsigned short \*portNbr, unsigned int \*ipAddress) States the port number and IP address of the UDP socket used for this DGR service access point. - void dgr\_close(Dgr dgr) Reverses *dgr\_open()*, releasing resources where possible. - int dgr\_send(Dgr dgr, unsigned short toPortNbr, unsigned int toIpAddress, int notificationFlags, char \*content, int length, DgrRC \*rc) Sends the indicated content, of length as indicated, to the remote DGR service access point identified by *toPortNbr* and *toIpAddress*. The message will be retransmitted as necessary until either it is acknowledged or DGR determines that it cannot be delivered. *notificationFlags*, if non-zero, is the logical OR of the notification behaviors requested for this datagram. Available behaviors are DGR\_NOTE\_FAILED (a notice of datagram delivery failure will issued if delivery of the datagram fails) and DGR\_NOTE\_ACKED (a notice of datagram delivery success will be issued if delivery of the datagram succeeds). Notices are issued via *dgr\_receive()* that is, the thread that calls *dgr\_receive()* on this DGR service access point will receive these notices interspersed with inbound datagram contents. *length* of content must be greater than zero and may be as great as 65535, but lengths greater than 8192 may not be supported by the local underlying UDP implementation; to minimize the chance of data loss when transmitting over the internet, length should not exceed 512. *rc* is the location in which to store the DGR return code resulting from the attempt to send the content. On any failure, returns -1 and sets *\*rc* to DgrFailed. On success, returns zero. - int dgr\_receive(Dgr dgr, unsigned short \*fromPortNbr, unsigned int \*fromIpAddress, char \*content, int \*length, int \*errnbr, int timeoutSeconds, DgrRC \*rc) Delivers the oldest undelivered DGR event queued for delivery. DGR events are of two type: (a) messages received from a remote DGR service access point and (b) notices of previously sent messages that DGR has determined either have been or cannot be delivered, as requested in the *notificationFlags* parameters provided to the *dgr\_send()* calls that sent those messages. In the former case, *dgr\_receive()* will place the content of the inbound message in *content*, its length in *length*, and the IP address and port number of the sender in *fromIpAddress* and *fromPortNbr*, and it will set *\*rc* to DgrDatagramReceived and return zero. In the latter case, *dgr\_receive()* will place the content of the affected **outbound** message in *content* and its length in *length* and return zero. If the event being reported is a delivery success, then DgrDatagramAcknowledged will be placed in *\*rc*. Otherwise, DgrDatagramNotAcknowledged will be placed in *\*rc* and the relevant errno (if any) will be placed in *\*errnbr*. The *content* buffer should be at least 65535 bytes in length to enable delivery of the content of the received or delivered/undeliverable message. *timeoutSeconds* controls blocking behavior. If *timeoutSeconds* is DGR\_BLOCKING (i.e., -1), *dgr\_receive()* will not return until (a) there is either an inbound message to deliver or an outbound message delivery result to report, or (b) the function is interrupted by means of *dgr\_interrupt()*. If *timeoutSeconds* is DGR\_POLL (i.e., zero), *dgr\_receive()* returns immediately; if there is currently no inbound message to deliver and no outbound message delivery result to report, the function sets *\*rc* to DgrTimedOut and returns zero. For any other positive value of *timeoutSeconds*, *dgr\_receive()* returns after the indicated number of seconds have lapsed (in which case the returned value of *\*rc* is DgrTimedOut), or when there is a message to deliver or a delivery result to report, or when the function is interrupted by means of *dgr\_interrupt()*, whichever occurs first. When the function returns due to interruption by *dgr\_interrupt()*, the value placed in *\*rc* is DgrInterrupted instead of DgrDatagramReceived. *rc* is the location in which to store the DGR return code resulting from the attempt to receive content. On any I/O error or other unrecoverable system error, returns -1. Otherwise always returns zero, placing DgrFailed in *\*rc* and writing a failure message in the event of an operating error. - void dgr\_interrupt(Dgr dgr) Interrupts a *dgr\_receive()* invocation that is currently blocked. Designed to be called from a signal handler; for this purpose, *dgr* may need to be obtained from a static variable. ## SEE ALSO [*ltp*(3)](/ltp/3.md), [*file2dgr*(1)](/file2dgr/1.md), [*dgr2file*(1)](/dgr2file/1.md)