\hypertarget{BFO_8h}{ \section{BFO.h File Reference} \label{BFO_8h}\index{BFO.h@{BFO.h}} } Balloon Flight Output, Interface. \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{BFO_8h_a0}{ \index{BFO_ocb@{BFO\_\-ocb}!BFO.h@{BFO.h}}\index{BFO.h@{BFO.h}!BFO_ocb@{BFO\_\-ocb}} typedef \hyperlink{struct__BFO__ocb}{\_\-BFO\_\-ocb} \hyperlink{BFO_8h_a0}{BFO\_\-ocb}} \label{BFO_8h_a0} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__BFO__ocb}{\_\-BFO\_\-ocb}.\item\end{CompactList}\item typedef int($\ast$ \hyperlink{BFO_8h_a1}{BFO\_\-dsk\-Write\-Rtn} )(int fd, const void $\ast$buf, int size) \begin{CompactList}\small\item\em Callback signature for writing data files.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item \hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ \hyperlink{BFO_8h_a2}{BFO\_\-get} (void) \begin{CompactList}\small\item\em Returns a pointer to the BFO output control block.\item\end{CompactList}\item int \hyperlink{BFO_8h_a3}{BFO\_\-ocb\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of the BFO output control block.\item\end{CompactList}\item int \hyperlink{BFO_8h_a4}{BFO\_\-msg\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of a BFO message.\item\end{CompactList}\item int \hyperlink{BFO_8h_a5}{BFO\_\-ocb\_\-init} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, \hyperlink{BFO_8h_a1}{BFO\_\-dsk\-Write\-Rtn} wrt, void $\ast$msgs, int msgs\_\-size, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$acb) \begin{CompactList}\small\item\em Initializes the Output Control Block.\item\end{CompactList}\item int \hyperlink{BFO_8h_a6}{BFO\_\-flush} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Ques a message to flush data from all internal BFO buffers.\item\end{CompactList}\item int \hyperlink{BFO_8h_a7}{BFO\_\-synch} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Attempts to ensure that all previous requests have been acted upon.\item\end{CompactList}\item int \hyperlink{BFO_8h_a8}{BFO\_\-write} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, struct \hyperlink{struct__BFU__fileDsc}{\_\-BFU\_\-file\-Dsc} $\ast$dsc) \begin{CompactList}\small\item\em Ques a message to write the specified events to the output streams.\item\end{CompactList}\item void \hyperlink{BFO_8h_a9}{BFO\_\-dsk\-Blk\-Size\-Set} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, int blk\-Size) \begin{CompactList}\small\item\em Sets the disk blocking size.\item\end{CompactList}\item int \hyperlink{BFO_8h_a10}{BFO\_\-dsk\-Disable} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Disables writing to the disk.\item\end{CompactList}\item int \hyperlink{BFO_8h_a11}{BFO\_\-dsk\-Enable} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Enables writing to the disk.\item\end{CompactList}\item void \hyperlink{BFO_8h_a12}{BFO\_\-dsk\-File\-Set} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, int fd) \begin{CompactList}\small\item\em Simply routine to set the current file descriptor.\item\end{CompactList}\item int \hyperlink{BFO_8h_a13}{BFO\_\-dsk\-File\-Get} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Simply query routine to return the current file descriptor.\item\end{CompactList}\item void \hyperlink{BFO_8h_a14}{BFO\_\-biu\-Sampling\-Set} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, int sample\-Rate, int limit) \begin{CompactList}\small\item\em Sets the parameters controlling the BIU sampling factors.\item\end{CompactList}\item int \hyperlink{BFO_8h_a15}{BFO\_\-biu\-Disable} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Disables writing to the BIU sampling stream.\item\end{CompactList}\item int \hyperlink{BFO_8h_a16}{BFO\_\-biu\-Dst\-Set} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo, unsigned int ip, unsigned short port) \begin{CompactList}\small\item\em Sets the destination IP address.\item\end{CompactList}\item int \hyperlink{BFO_8h_a17}{BFO\_\-biu\-Enable} (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$bfo) \begin{CompactList}\small\item\em Enables writing to the BIU sampling stream.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} Balloon Flight Output, Interface. \begin{Desc} \item[Author: ]\par JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} \subsection{Typedef Documentation} \hypertarget{BFO_8h_a1}{ \index{BFO.h@{BFO.h}!BFO_dskWriteRtn@{BFO\_\-dskWriteRtn}} \index{BFO_dskWriteRtn@{BFO\_\-dskWriteRtn}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskWriteRtn]{\setlength{\rightskip}{0pt plus 5cm}BFO\_\-dsk\-Write\-Rtn}} \label{BFO_8h_a1} Callback signature for writing data files. The callback signature exactly matches that of the standard UNIX write routine. \subsection{Function Documentation} \hypertarget{BFO_8h_a15}{ \index{BFO.h@{BFO.h}!BFO_biuDisable@{BFO\_\-biuDisable}} \index{BFO_biuDisable@{BFO\_\-biuDisable}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-biuDisable]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-biu\-Disable (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a15} Disables writing to the BIU sampling stream. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \end{description} \end{Desc} \begin{Desc} \item[Return values: ]\par \begin{description} \item[{\em 0, if}]the BIU was already disabled \item[{\em 1, if}]the BIU was previously enabled. \end{description} \end{Desc} \hypertarget{BFO_8h_a16}{ \index{BFO.h@{BFO.h}!BFO_biuDstSet@{BFO\_\-biuDstSet}} \index{BFO_biuDstSet@{BFO\_\-biuDstSet}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-biuDstSet]{\setlength{\rightskip}{0pt plus 5cm}void BFO\_\-biu\-Dst\-Set (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, unsigned int {\em ip}, unsigned short {\em port})}} \label{BFO_8h_a16} Sets the destination IP address. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \item[{\em ip}]The destination IP address. \item[{\em port}]The destination port number. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status. \end{Desc} \hypertarget{BFO_8h_a17}{ \index{BFO.h@{BFO.h}!BFO_biuEnable@{BFO\_\-biuEnable}} \index{BFO_biuEnable@{BFO\_\-biuEnable}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-biuEnable]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-biu\-Enable (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a17} Enables writing to the BIU sampling stream. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \end{description} \end{Desc} \begin{Desc} \item[Return values: ]\par \begin{description} \item[{\em 0, if}]the BIU was already enabled \item[{\em 1, if}]the BIU was previously disabled.\end{description} \end{Desc} As a side effect, this routine restores the credit limit to its maximum. There seemed to be only 2 sensible choices, setting it to 0, and starting the timer, or setting to the maximum. \hypertarget{BFO_8h_a14}{ \index{BFO.h@{BFO.h}!BFO_biuSamplingSet@{BFO\_\-biuSamplingSet}} \index{BFO_biuSamplingSet@{BFO\_\-biuSamplingSet}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-biuSamplingSet]{\setlength{\rightskip}{0pt plus 5cm}void BFO\_\-biu\-Sampling\-Set (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, int {\em sample\-Rate}, int {\em limit})}} \label{BFO_8h_a14} Sets the parameters controlling the BIU sampling factors. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \item[{\em sample\-Rate}]The sample rate expressed in bytes/sec. This number must be less than 2$\ast$$\ast$22, i.e. around 4Mbytes/sec. \item[{\em limit}]An upper limit on the number of bytes that one can accumulate. If this is specified as 0, the it is set to the amount on can accumulate in 1 second.\end{description} \end{Desc} Sets the sampling parameters for the BIU stream. This stream is allowed to output a stream of data at no more than 'sample\-Rate', expressed in bytes/second. In order to not allow pauses in the flow of data to accumulate a big backlog (imagine that little to no data flows for a long period of time, then delta\-T $\ast$ sample\-Rate will be a very big number), the amount one can 'save' is limited to some amount. This is essentially the second parameter. \hypertarget{BFO_8h_a9}{ \index{BFO.h@{BFO.h}!BFO_dskBlkSizeSet@{BFO\_\-dskBlkSizeSet}} \index{BFO_dskBlkSizeSet@{BFO\_\-dskBlkSizeSet}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskBlkSizeSet]{\setlength{\rightskip}{0pt plus 5cm}void BFO\_\-dsk\-Blk\-Size\-Set (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, int {\em blk\-Size})}} \label{BFO_8h_a9} Sets the disk blocking size. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \item[{\em blk\-Size}]The block size, in bytes.\end{description} \end{Desc} Sets the blocking size. Output will be written to the disk only when this many bytes are accumulated or an explicit write is forced using a \hyperlink{BFO_8h_a6}{BFO\_\-flush}() operation. \hypertarget{BFO_8h_a10}{ \index{BFO.h@{BFO.h}!BFO_dskDisable@{BFO\_\-dskDisable}} \index{BFO_dskDisable@{BFO\_\-dskDisable}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskDisable]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-dsk\-Disable (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a10} Disables writing to the disk. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \end{description} \end{Desc} \begin{Desc} \item[Return values: ]\par \begin{description} \item[{\em 0, if}]the writing was already disabled \item[{\em 1, if}]the writing was previously enabled.\end{description} \end{Desc} \begin{Desc} \item[Warning: ]\par This routine is meant to be used only in a test situation. This routine is dangerous to use unless precautions are taken. Because the output is being buffered up, arbitrary disabling can leave the state of buffer in an inconsistent state. Always make sure that all output is flushed and that no more new output is sent before a call to this routine is issued.\end{Desc} For disk writing efficiency, the previous file should be closed out and a new one opened. This is because the writing has been stopped before a new cluster is completely filled, leaving the disk driver always reading the partial record from disk, appending the new stuff, then writing it all back out. Since the disk writing routines always submit their output in clusters, one is permanently out of synch. \hypertarget{BFO_8h_a11}{ \index{BFO.h@{BFO.h}!BFO_dskEnable@{BFO\_\-dskEnable}} \index{BFO_dskEnable@{BFO\_\-dskEnable}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskEnable]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-dsk\-Enable (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a11} Enables writing to the disk. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \end{description} \end{Desc} \begin{Desc} \item[Return values: ]\par \begin{description} \item[{\em 0, if}]the writing was already disabled \item[{\em 1, if}]the writing was previously enabled.\end{description} \end{Desc} \begin{Desc} \item[Warning: ]\par See \hyperlink{BFO_8h_a10}{BFO\_\-dsk\-Disable}() for usage warnings. \end{Desc} \hypertarget{BFO_8h_a13}{ \index{BFO.h@{BFO.h}!BFO_dskFileGet@{BFO\_\-dskFileGet}} \index{BFO_dskFileGet@{BFO\_\-dskFileGet}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskFileGet]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-dsk\-File\-Get (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a13} Simply query routine to return the current file descriptor. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The file descriptor\end{Desc} This is a simply query routine to return the current file descriptor. This saves the user from having to buffer the file descriptor. \hypertarget{BFO_8h_a12}{ \index{BFO.h@{BFO.h}!BFO_dskFileSet@{BFO\_\-dskFileSet}} \index{BFO_dskFileSet@{BFO\_\-dskFileSet}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-dskFileSet]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-dsk\-File\-Set (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, int {\em fd})}} \label{BFO_8h_a12} Simply routine to set the current file descriptor. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \item[{\em fd}]The file descriptor.\end{description} \end{Desc} This is a simple routine to set the current file descriptor. Note that it is the user's responsibility to ensure that all previous activity on this stream is complete. This is usually accomplished by performing a \hyperlink{BFO_8h_a6}{BFO\_\-flush}() followed by a \hyperlink{BFO_8h_a7}{BFO\_\-synch}(). \hypertarget{BFO_8h_a6}{ \index{BFO.h@{BFO.h}!BFO_flush@{BFO\_\-flush}} \index{BFO_flush@{BFO\_\-flush}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-flush]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-flush (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a6} Ques a message to flush data from all internal BFO buffers. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The output control block to perform the flush on. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} Flushes the whatever is in the disk buffers. This only posts the last remaining piece for writing. Because this only posts a message requesting a {\bf flush}, use \hyperlink{BFO_8h_a7}{BFO\_\-synch}() to ensure that {\bf flush} message has been consumed. \begin{Desc} \item[Warning: ]\par It is imperative that no more data be written to the disk until after this operation has been completed. The stream should be disabled and \hyperlink{BFO_8h_a7}{BFO\_\-synch}(). \end{Desc} \hypertarget{BFO_8h_a2}{ \index{BFO.h@{BFO.h}!BFO_get@{BFO\_\-get}} \index{BFO_get@{BFO\_\-get}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-get]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-get (void)}} \label{BFO_8h_a2} Returns a pointer to the BFO output control block. \begin{Desc} \item[Returns: ]\par A pointer to the BFO output control block. \end{Desc} \hypertarget{BFO_8h_a4}{ \index{BFO.h@{BFO.h}!BFO_msg_sizeof@{BFO\_\-msg\_\-sizeof}} \index{BFO_msg_sizeof@{BFO\_\-msg\_\-sizeof}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-msg\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-msg\_\-sizeof (void)}} \label{BFO_8h_a4} Returns the size of a BFO message. \begin{Desc} \item[Returns: ]\par The BFO message size.\end{Desc} This routine allows the user to control the allocation and management of the pool messages used by the BFO routines to post messages across the FORK tasks. The customary usage would be to call \hyperlink{BFO_8h_a4}{BFO\_\-msg\_\-sizeof}(), multiple the returned message size by however many messages that the user wished to use, allocate the that amount of memory, and, finally pass the allocated memory and its size to \hyperlink{BFO_8h_a5}{BFO\_\-ocb\_\-init}(). \hypertarget{BFO_8h_a5}{ \index{BFO.h@{BFO.h}!BFO_ocb_init@{BFO\_\-ocb\_\-init}} \index{BFO_ocb_init@{BFO\_\-ocb\_\-init}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-ocb\_\-init]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-ocb\_\-init (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, \hyperlink{BFO_8h_a1}{BFO\_\-dsk\-Write\-Rtn} {\em wrt}, void $\ast$ {\em msgs}, int {\em msgs\_\-size}, struct \hyperlink{struct__BFA__acb}{\_\-BFA\_\-acb} $\ast$ {\em acb})}} \label{BFO_8h_a5} Initializes the Output Control Block. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block to initialize. \item[{\em wrt}]The routine to perform the writing. \item[{\em msgs}]A pool of memory to be used for the messages. \item[{\em msgs\_\-size}]The size of msgs area \item[{\em acb}]The allocation control structure. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} This routine only initialize properties of the BFO which are very static, ie the are very unlikely to change as long as the BFO control structure is in existence. Other properties, such as the file to write to and the BIU sampling parameters can be changed during the BFO stream's lifetime. \hypertarget{BFO_8h_a3}{ \index{BFO.h@{BFO.h}!BFO_ocb_sizeof@{BFO\_\-ocb\_\-sizeof}} \index{BFO_ocb_sizeof@{BFO\_\-ocb\_\-sizeof}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-ocb\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-ocb\_\-sizeof (void)}} \label{BFO_8h_a3} Returns the size of the BFO output control block. \begin{Desc} \item[Returns: ]\par The size of the BFO output control block.\end{Desc} Returns the size of the Output Control Block. This includes the size of the FORK and Free Packet Pool control blocks. This allows the user to control and manage the allocation of this memory. \hypertarget{BFO_8h_a7}{ \index{BFO.h@{BFO.h}!BFO_synch@{BFO\_\-synch}} \index{BFO_synch@{BFO\_\-synch}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-synch]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-synch (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo})}} \label{BFO_8h_a7} Attempts to ensure that all previous requests have been acted upon. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The output control block to synchronize. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status. Currently the only failure modes are of the irrecoverable variety, ie program error or corruption.\end{Desc} This routine can never really ensure that all the data is actually physically on the disk. The UNIX IO routines have no mechanism to enforce such a wish. All this routine can really do is ensure that all previous messages have been acted on. What one can do is perform a \hyperlink{BFO_8h_a6}{BFO\_\-flush}() operation, ensuring that all data within the internal BFO buffers are sent to disk with a UNIX 'write' operation. This should then be followed by a \hyperlink{BFO_8h_a7}{BFO\_\-synch}(), ensuring the {\bf flush} message itself has been consumed. \hypertarget{BFO_8h_a8}{ \index{BFO.h@{BFO.h}!BFO_write@{BFO\_\-write}} \index{BFO_write@{BFO\_\-write}!BFO.h@{BFO.h}} \subsubsection[BFO\_\-write]{\setlength{\rightskip}{0pt plus 5cm}int BFO\_\-write (\hyperlink{BFO_8h_a0}{BFO\_\-ocb} $\ast$ {\em bfo}, struct \hyperlink{struct__BFU__fileDsc}{\_\-BFU\_\-file\-Dsc} $\ast$ {\em file\-Dsc})}} \label{BFO_8h_a8} Ques a message to write the specified events to the output streams. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em bfo}]The Output Control Block \item[{\em file\-Dsc}]The 'file' descriptor describing the events to write. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Status\end{Desc} This routine posts a message to the write the specified events to the output streams. It does not actually perform the IO itself. To ensure that this message has been consumed, call \hyperlink{BFO_8h_a7}{BFO\_\-synch}().