.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "cfdp::doc::pod3::cfdp 3" .TH cfdp::doc::pod3::cfdp 3 "2016-07-07" "perl v5.24.1" "CFDP library functions" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" cfdp \- CCSDS File Delivery Protocol (CFDP) communications library .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "cfdp.h" \& \& typedef int (*CfdpReaderFn)(int fd, unsigned int *checksum); \& \& typedef enum \& { \& CfdpCreateFile = 0, \& CfdpDeleteFile, \& CfdpRenameFile, \& CfdpAppendFile, \& CfdpReplaceFile, \& CfdpCreateDirectory, \& CfdpRemoveDirectory, \& CfdpDenyFile, \& CfdpDenyDirectory \& } CfdpAction; \& \& typedef enum \& { \& CfdpNoEvent = 0, \& CfdpTransactionInd, \& CfdpEofSentInd, \& CfdpTransactionFinishedInd, \& CfdpMetadataRecvInd, \& CfdpFileSegmentRecvInd, \& CfdpEofRecvInd, \& CfdpSuspendedInd, \& CfdpResumedInd, \& CfdpReportInd, \& CfdpFaultInd, \& CfdpAbandonedInd \& } CfdpEventType; \& \& [see description for available functions] .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The cfdp library provides functions enabling application software to use \s-1CFDP\s0 to send and receive files. It conforms to the Class 1 (Unacknowledged) service class defined in the \s-1CFDP\s0 Blue Book. .PP In the \s-1ION\s0 implementation of \s-1CFDP,\s0 the \s-1CFDP\s0 notion of \fBentity \s-1ID\s0\fR is taken to be identical to the \s-1BP \s0(\s-1CBHE\s0) notion of \s-1DTN \s0\fBnode number\fR. .PP \&\s-1CFDP\s0 entity and transaction numbers may be up to 64 bits in length. For portability to 32\-bit machines, these numbers are stored in the \s-1CFDP\s0 state machine as structures of type CfdpNumber. .PP To simplify the interface between \s-1CFDP\s0 the user application without risking storage leaks, the CFDP-ION \s-1API\s0 uses MetadataList objects. A MetadataList is a specially formatted \s-1SDR\s0 list of user messages, filestore requests, or filestore responses. During the time that a MetadataList is pending processing via the \s-1CFDP API,\s0 but is not yet (or is no longer) reachable from any \s-1FDU\s0 object, a pointer to the list is appended to one of the lists of MetadataList objects in the \s-1CFDP\s0 non-volatile database. This assures that any unplanned termination of the \s-1CFDP\s0 daemons won't leave any \&\s-1SDR\s0 lists unreachable \*(-- and therefore un-recyclable \*(-- due to the absence of references to those lists. Restarting \s-1CFDP\s0 automatically purges any unused MetadataLists from the \s-1CFDP\s0 database. The \*(L"user data\*(R" variable of the MetadataList itself is used to implement this feature: while the list is reachable only from the database root, its user data variable points to the database root list from which it is referenced; while the list is attached to a File Delivery Unit, its user data is null. .PP By default, \s-1CFDP\s0 transmits the data in a source file in segments of fixed size. The user application can override this behavior at the time transmission of a file is requested, by supplying a file reader callback function that reads the file \*(-- one byte at a time \*(-- until it detects the end of a \*(L"record\*(R" that has application significance. Each time \s-1CFDP\s0 calls the reader function, the function must return the length of one such record (which must be no greater than 65535). .PP When \s-1CFDP\s0 is used to transmit a file, a 32\-bit checksum must be provided in the \*(L"\s-1EOF\*(R" PDU\s0 to enable the receiver of the file to assure that it was not corrupted in transit. When an application-specific file reader function is supplied, that function is responsible for updating the computed checksum as it reads each byte of the file; a \s-1CFDP\s0 library function is provided for this purpose. .PP The return value for each \s-1CFDP \s0\*(L"request\*(R" function (put, cancel, suspend, resume, report) is a reference number that enables \*(L"events\*(R" obtained by calling \fIcfdp_get_event()\fR to be matched to the requests that caused them. Events with reference number set to zero are events that were caused by autonomous \s-1CFDP\s0 activity, e.g., the reception of a file data segment. .IP "int \fIcfdp_attach()\fR" 4 .IX Item "int cfdp_attach()" Attaches the application to \s-1CFDP\s0 functionality on the local computer. Returns 0 on success, \-1 on any error. .IP "int \fIcfdp_entity_is_started()\fR" 4 .IX Item "int cfdp_entity_is_started()" Returns 1 if the local \s-1CFDP\s0 entity has been started and not yet stopped, 0 otherwise. .IP "void \fIcfdp_detach()\fR" 4 .IX Item "void cfdp_detach()" Terminates all access to \s-1CFDP\s0 functionality on the local computer. .IP "void cfdp_compress_number(CfdpNumber *toNbr, uvast from)" 4 .IX Item "void cfdp_compress_number(CfdpNumber *toNbr, uvast from)" Converts an unsigned \fBvast\fR number into a CfdpNumber structure, e.g., for use when invoking the \fIcfdp_put()\fR function. .IP "void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)" 4 .IX Item "void cfdp_decompress_number(uvast toNbr, CfdpNumber *from)" Converts a numeric value in a CfdpNumber structure to an unsigned \fBvast\fR integer. .IP "void cfdp_update_checksum(unsigned char octet, unsigned int *offset, unsigned int *checksum)" 4 .IX Item "void cfdp_update_checksum(unsigned char octet, unsigned int *offset, unsigned int *checksum)" For use by an application-specific file reader callback function, which must pass to \fIcfdp_update_checksum()\fR the value of each byte (octet) it reads. \&\fIoffset\fR must be \fIoctet\fR's displacement in bytes from the start of the file. The \fIchecksum\fR pointer is provided to the reader function by \s-1CFDP.\s0 .IP "MetadataList \fIcfdp_create_usrmsg_list()\fR" 4 .IX Item "MetadataList cfdp_create_usrmsg_list()" Creates a non-volatile linked list, suitable for containing messages-to-user that are to be presented to \fIcfdp_put()\fR. .IP "int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)" 4 .IX Item "int cfdp_add_usrmsg(MetadataList list, unsigned char *text, int length)" Appends the indicated message-to-user to \fIlist\fR. .IP "int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)" 4 .IX Item "int cfdp_get_usrmsg(MetadataList list, unsigned char *textBuf, int *length)" Removes from \fIlist\fR the first of the remaining messages-to-user contained in the list and delivers its text and length. When the last message in the list is delivered, destroys the list. .IP "void cfdp_destroy_usrmsg_list(MetadataList *list)" 4 .IX Item "void cfdp_destroy_usrmsg_list(MetadataList *list)" Removes and destroys all messages-to-user in \fIlist\fR and destroys the list. .IP "MetadataList \fIcfdp_create_fsreq_list()\fR" 4 .IX Item "MetadataList cfdp_create_fsreq_list()" Creates a non-volatile linked list, suitable for containing filestore requests that are to be presented to \fIcfdp_put()\fR. .IP "int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)" 4 .IX Item "int cfdp_add_fsreq(MetadataList list, CfdpAction action, char *firstFileName, char *seconfdFIleName)" Appends the indicated filestore request to \fIlist\fR. .IP "int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)" 4 .IX Item "int cfdp_get_fsreq(MetadataList list, CfdpAction *action, char *firstFileNameBuf, char *secondFileNameBuf)" Removes from \fIlist\fR the first of the remaining filestore requests contained in the list and delivers its action code and file names. When the last request in the list is delivered, destroys the list. .IP "void cfdp_destroy_fsreq_list(MetadataList *list)" 4 .IX Item "void cfdp_destroy_fsreq_list(MetadataList *list)" Removes and destroys all filestore requests in \fIlist\fR and destroys the list. .IP "int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)" 4 .IX Item "int cfdp_get_fsresp(MetadataList list, CfdpAction *action, int *status, char *firstFileNameBuf, char *secondFileNameBuf, char *messageBuf)" Removes from \fIlist\fR the first of the remaining filestore responses contained in the list and delivers its action code, status, file names, and message. When the last response in the list is delivered, destroys the list. .IP "void cfdp_destroy_fsresp_list(MetadataList *list)" 4 .IX Item "void cfdp_destroy_fsresp_list(MetadataList *list)" Removes and destroys all filestore responses in \fIlist\fR and destroys the list. .IP "int cfdp_read_space_packets(int fd, unsigned int *checksum)" 4 .IX Item "int cfdp_read_space_packets(int fd, unsigned int *checksum)" This is a standard \*(L"reader\*(R" function that segments the source file on \s-1CCSDS\s0 space packet boundaries. Multiple small packets may be aggregated into a single file data segment. .IP "int cfdp_read_text_lines(int fd, unsigned int *checksum)" 4 .IX Item "int cfdp_read_text_lines(int fd, unsigned int *checksum)" This is a standard \*(L"reader\*(R" function that segments a source file of text lines on line boundaries. .IP "int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)" 4 .IX Item "int cfdp_put(CfdpNumber *destinationEntityNbr, unsigned int utParmsLength, unsigned char *utParms, char *sourceFileName, char *destFileName, CfdpReaderFn readerFn, CfdpHandler *faultHandlers, unsigned int flowLabelLength, unsigned char *flowLabel, MetadataList messagesToUser, MetadataList filestoreRequests, CfdpTransactionId *transactionId)" Sends the file identified by \fIsourceFileName\fR to the \s-1CFDP\s0 entity identified by \&\fIdestinationEntityNbr\fR. \fIdestinationFileName\fR is used to indicate the name by which the file will be catalogued upon arrival at its final destination; if \&\s-1NULL,\s0 the destination file name defaults to \fIsourceFileName\fR. If \&\fIsourceFileName\fR is \s-1NULL,\s0 it is assumed that the application is requesting transmission of metadata only (as discussed below) and \fIdestinationFileName\fR is ignored. Note that both \fIsourceFileName\fR and \fIdestinationFileName\fR are interpreted as path names, i.e., directory paths may be indicated in either or both. The syntax of path names is opaque to \s-1CFDP\s0; the syntax of \&\fIsourceFileName\fR must conform to the path naming syntax of the source entity's file system and the syntax of \fIdestinationFileName\fR must conform to the path naming syntax of the destination entity's file system. .Sp The byte array identified by \fIutParms\fR, if non-NULL, is interpreted as transmission control information that is to be passed on to the \s-1UT\s0 layer. The nominal \s-1UT\s0 layer for \s-1ION\s0's \s-1CFDP\s0 being Bundle Protocol, the \fIutParms\fR array is normally a pointer to a structure of type BpUtParms; see the \fIbp\fR man page for a discussion of the parameters in that structure. .Sp \&\fImessagesToUser\fR and \fIfilestoreRequests\fR, where non-zero, must be the addresses of non-volatile linked lists (that is, linked lists in \s-1ION\s0's \&\s-1SDR\s0 database) of CfdpMsgToUser and CfdpFilestoreRequest objects identifying metadata that are intended to accompany the transmitted file. Note that this metadata may accompany a file of zero length (as when \fIsourceFileName\fR is \s-1NULL\s0 as noted above) \*(-- a transmission of metadata only. .Sp On success, the function populates \fI*transactionID\fR with the source entity \&\s-1ID\s0 and the transaction number assigned to this transmission and returns the request number identifying this \*(L"put\*(R" request. The transaction \s-1ID\s0 may be used to suspend, resume, cancel, or request a report on the progress of this transmission. \fIcfdp_put()\fR returns \-1 on any error. .IP "int cfdp_cancel(CfdpTransactionId *transactionId)" 4 .IX Item "int cfdp_cancel(CfdpTransactionId *transactionId)" Cancels transmission or reception of the indicated transaction. Note that, since the \s-1ION\s0 implementation of \s-1CFDP\s0 is Unacknowledged, cancellation of a file transmission may have little effect. Returns request number on success, \&\-1 on any error. .IP "int cfdp_suspend(CfdpTransactionId *transactionId)" 4 .IX Item "int cfdp_suspend(CfdpTransactionId *transactionId)" Suspends transmission of the indicated transaction. Note that, since the \s-1ION\s0 implementation of \s-1CFDP\s0 is Unacknowledged, suspension of a file transmission may have little effect. Returns request number on success, \-1 on any error. .IP "int cfdp_resume(CfdpTransactionId *transactionId)" 4 .IX Item "int cfdp_resume(CfdpTransactionId *transactionId)" Resumes transmission of the indicated transaction. Note that, since the \s-1ION\s0 implementation of \s-1CFDP\s0 is Unacknowledged, resumption of a file transmission may have little effect. Returns request number on success, \-1 on any error. .IP "int cfdp_report(CfdpTransactionId *transactionId)" 4 .IX Item "int cfdp_report(CfdpTransactionId *transactionId)" Requests issuance of a report on the transmission or reception progress of the indicated transaction. The report takes the form of a character string that is returned in a CfdpEvent structure; use \fIcfdp_get_event()\fR to receive the event (which may be matched to the request by request number). Returns request number on success, 0 if transaction is unknown, \-1 on any error. .IP "int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, unsigned int *fileSize, MetadataList *messagesToUser, unsigned int *offset, unsigned int *length, CfdpCondition *condition, unsigned int *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);" 4 .IX Item "int cfdp_get_event(CfdpEventType *type, time_t *time, int *reqNbr, CfdpTransactionId *transactionId, char *sourceFileNameBuf, char *destFileNameBuf, unsigned int *fileSize, MetadataList *messagesToUser, unsigned int *offset, unsigned int *length, CfdpCondition *condition, unsigned int *progress, CfdpFileStatus *fileStatus, CfdpDeliveryCode *deliveryCode, CfdpTransactionId *originatingTransactionId, char *statusReportBuf, MetadataList *filestoreResponses);" Populates return value fields with data from the oldest \s-1CFDP\s0 event not yet delivered to the application. .Sp \&\fIcfdp_get_event()\fR always blocks indefinitely until an \s-1CFDP\s0 processing event is delivered or the function is interrupted by an invocation of \&\fIcfdp_interrupt()\fR. .Sp On application error, returns zero but sets errno to \s-1EINVAL. \s0 Returns \-1 on system failure, zero otherwise. .IP "void \fIcfdp_interrupt()\fR" 4 .IX Item "void cfdp_interrupt()" Interrupts an \fIcfdp_get_event()\fR invocation. This function is designed to be called from a signal handler. .IP "int cfdp_preview(CfdpTransactionId *transactionId, unsigned int offset, int length, char *buffer);" 4 .IX Item "int cfdp_preview(CfdpTransactionId *transactionId, unsigned int offset, int length, char *buffer);" This function is provided to enable the application to get an advance look at the content of a file that \s-1CFDP\s0 has not yet fully received. Reads \fIlength\fR bytes starting at \fIoffset\fR bytes from the start of the file that is the destination file of the transaction identified by \fItransactionID\fR, into \&\fIbuffer\fR. On user error (transaction is nonexistent or is outbound, or offset is beyond the end of file) returns 0. On system failure, returns \-1. Otherwise returns number of bytes read. .IP "int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);" 4 .IX Item "int cfdp_map(CfdpTransactionId *transactionId, unsigned int *extentCount, CfdpExtent *extentsArray);" This function is provided to enable the application to report on the portions of a partially-received file that have been received and written. Lists the received continuous data extents in the destination file of the transaction identified by \fItransactionID\fR. The extents (offset and length) are returned in the elements of \fIextentsArray\fR; the number of extents returned in the array is the total number of continuous extents received so far, or \&\fIextentCount\fR, whichever is less. The total number of extents received so far is returned as the new value of \fIextentCount\fR. On system failure, returns \-1. Otherwise returns 0. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIcfdpadmin\fR\|(1), \fIcfdprc\fR\|(5)