\hypertarget{IVTE_8ih}{ \section{IVTE.ih File Reference} \label{IVTE_8ih}\index{IVTE.ih@{IVTE.ih}} } IVTE Inline Interface. {\tt \#include \char`\"{}BBC/inline.h\char`\"{}}\par {\tt \#include \char`\"{}BBC/IVTE\_\-id.h\char`\"{}}\par \subsection*{Data Structures} \begin{CompactItemize} \item struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} \begin{CompactList}\small\item\em Directory structure definition.\item\end{CompactList}\item struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} \begin{CompactList}\small\item\em Header structure definition.\item\end{CompactList}\item struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} \begin{CompactList}\small\item\em Trailer structure definition.\item\end{CompactList}\end{CompactItemize} \subsection*{Defines} \begin{CompactItemize} \item \hypertarget{IVTE_8ih_a0}{ \index{IVTE_EXT_PROTO@{IVTE\_\-EXT\_\-PROTO}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_EXT_PROTO@{IVTE\_\-EXT\_\-PROTO}} \#define \hyperlink{IVTE_8ih_a0}{IVTE\_\-EXT\_\-PROTO}\ INLINE\_\-USR\_\-EXT\_\-PROTO} \label{IVTE_8ih_a0} \begin{CompactList}\small\item\em Declaration for external function prototype.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a1}{ \index{IVTE_LCL_PROTO@{IVTE\_\-LCL\_\-PROTO}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_LCL_PROTO@{IVTE\_\-LCL\_\-PROTO}} \#define \hyperlink{IVTE_8ih_a1}{IVTE\_\-LCL\_\-PROTO}\ INLINE\_\-USR\_\-LCL\_\-PROTO} \label{IVTE_8ih_a1} \begin{CompactList}\small\item\em Declaration for internal function prototype.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a2}{ \index{IVTE_EXT_FNC@{IVTE\_\-EXT\_\-FNC}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_EXT_FNC@{IVTE\_\-EXT\_\-FNC}} \#define \hyperlink{IVTE_8ih_a2}{IVTE\_\-EXT\_\-FNC}\ INLINE\_\-USR\_\-EXT\_\-FNC} \label{IVTE_8ih_a2} \begin{CompactList}\small\item\em Declaration for external function.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a3}{ \index{IVTE_LCL_FNC@{IVTE\_\-LCL\_\-FNC}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_LCL_FNC@{IVTE\_\-LCL\_\-FNC}} \#define \hyperlink{IVTE_8ih_a3}{IVTE\_\-LCL\_\-FNC}\ INLINE\_\-USR\_\-LCL\_\-FNC} \label{IVTE_8ih_a3} \begin{CompactList}\small\item\em Declaration for internal function.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a4}{ \index{IVTE_V_NDIR@{IVTE\_\-V\_\-NDIR}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_V_NDIR@{IVTE\_\-V\_\-NDIR}} \#define \hyperlink{IVTE_8ih_a4}{IVTE\_\-V\_\-NDIR}\ 0} \label{IVTE_8ih_a4} \begin{CompactList}\small\item\em Shift amount to right justify the NDIR field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a5}{ \index{IVTE_W_NDIR@{IVTE\_\-W\_\-NDIR}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_W_NDIR@{IVTE\_\-W\_\-NDIR}} \#define \hyperlink{IVTE_8ih_a5}{IVTE\_\-W\_\-NDIR}\ 24} \label{IVTE_8ih_a5} \begin{CompactList}\small\item\em Shift amount to left justify the NDIR field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a6}{ \index{IVTE_S_NDIR@{IVTE\_\-S\_\-NDIR}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_S_NDIR@{IVTE\_\-S\_\-NDIR}} \#define \hyperlink{IVTE_8ih_a6}{IVTE\_\-S\_\-NDIR}\ 8} \label{IVTE_8ih_a6} \begin{CompactList}\small\item\em Size, in bits of the NDIR field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a7}{ \index{IVTE_M_NDIR@{IVTE\_\-M\_\-NDIR}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_M_NDIR@{IVTE\_\-M\_\-NDIR}} \#define \hyperlink{IVTE_8ih_a7}{IVTE\_\-M\_\-NDIR}\ 0xff} \label{IVTE_8ih_a7} \begin{CompactList}\small\item\em Right justified mask for the NDIR field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a8}{ \index{IVTE_V_STATUS@{IVTE\_\-V\_\-STATUS}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_V_STATUS@{IVTE\_\-V\_\-STATUS}} \#define \hyperlink{IVTE_8ih_a8}{IVTE\_\-V\_\-STATUS}\ 8} \label{IVTE_8ih_a8} \begin{CompactList}\small\item\em Shift amount to right justify the STATUS field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a9}{ \index{IVTE_W_STATUS@{IVTE\_\-W\_\-STATUS}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_W_STATUS@{IVTE\_\-W\_\-STATUS}} \#define \hyperlink{IVTE_8ih_a9}{IVTE\_\-W\_\-STATUS}\ 0} \label{IVTE_8ih_a9} \begin{CompactList}\small\item\em Shift amount to left justify the STATUS field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a10}{ \index{IVTE_S_STATUS@{IVTE\_\-S\_\-STATUS}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_S_STATUS@{IVTE\_\-S\_\-STATUS}} \#define \hyperlink{IVTE_8ih_a10}{IVTE\_\-S\_\-STATUS}\ 24} \label{IVTE_8ih_a10} \begin{CompactList}\small\item\em Size, in bits of the STATUS field.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a11}{ \index{IVTE_M_STATUS@{IVTE\_\-M\_\-STATUS}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_M_STATUS@{IVTE\_\-M\_\-STATUS}} \#define \hyperlink{IVTE_8ih_a11}{IVTE\_\-M\_\-STATUS}\ 0xffffff00} \label{IVTE_8ih_a11} \begin{CompactList}\small\item\em Right justified mask for the STATUS field.\item\end{CompactList}\item \#define \hyperlink{IVTE_8ih_a12}{IVTE\_\-DIR\_\-SIZEOF}\ (sizeof(struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir})) \begin{CompactList}\small\item\em Get the sizeof an IVTE directory structure.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a13}{ \index{IVTE_HDR_SIZEOF@{IVTE\_\-HDR\_\-SIZEOF}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_HDR_SIZEOF@{IVTE\_\-HDR\_\-SIZEOF}} \#define \hyperlink{IVTE_8ih_a13}{IVTE\_\-HDR\_\-SIZEOF}\ (sizeof(struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr}) - sizeof(struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir}))} \label{IVTE_8ih_a13} \begin{CompactList}\small\item\em Get the sizeof an IVTE header structure.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a14}{ \index{IVTE_TLR_SIZEOF@{IVTE\_\-TLR\_\-SIZEOF}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_TLR_SIZEOF@{IVTE\_\-TLR\_\-SIZEOF}} \#define \hyperlink{IVTE_8ih_a14}{IVTE\_\-TLR\_\-SIZEOF}\ (sizeof(struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr})} \label{IVTE_8ih_a14} \begin{CompactList}\small\item\em Get the sizeof an IVTE trailer structure.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a15}{ \index{IVTE_DIR_ALIGNMENT_SIZE@{IVTE\_\-DIR\_\-ALIGNMENT\_\-SIZE}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_DIR_ALIGNMENT_SIZE@{IVTE\_\-DIR\_\-ALIGNMENT\_\-SIZE}} \#define \hyperlink{IVTE_8ih_a15}{IVTE\_\-DIR\_\-ALIGNMENT\_\-SIZE}\ (sizeof (int))} \label{IVTE_8ih_a15} \begin{CompactList}\small\item\em The IVTE directory alignment size, expressed in bytes.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a16}{ \index{IVTE_DIR_ALIGNMENT_MASK@{IVTE\_\-DIR\_\-ALIGNMENT\_\-MASK}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_DIR_ALIGNMENT_MASK@{IVTE\_\-DIR\_\-ALIGNMENT\_\-MASK}} \#define \hyperlink{IVTE_8ih_a16}{IVTE\_\-DIR\_\-ALIGNMENT\_\-MASK}\ ($\sim$(IVTE\_\-DIR\_\-ALIGNMENT\_\-SIZE-1))} \label{IVTE_8ih_a16} \begin{CompactList}\small\item\em The IVTE directory alignment mask.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a17}{ \index{IVTE_DATA_ALIGNMENT_SIZE@{IVTE\_\-DATA\_\-ALIGNMENT\_\-SIZE}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_DATA_ALIGNMENT_SIZE@{IVTE\_\-DATA\_\-ALIGNMENT\_\-SIZE}} \#define \hyperlink{IVTE_8ih_a17}{IVTE\_\-DATA\_\-ALIGNMENT\_\-SIZE}\ (sizeof (int))} \label{IVTE_8ih_a17} \begin{CompactList}\small\item\em The IVTE data alignment size, expressed in bytes.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a18}{ \index{IVTE_DATA_ALIGNMENT_MASK@{IVTE\_\-DATA\_\-ALIGNMENT\_\-MASK}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_DATA_ALIGNMENT_MASK@{IVTE\_\-DATA\_\-ALIGNMENT\_\-MASK}} \#define \hyperlink{IVTE_8ih_a18}{IVTE\_\-DATA\_\-ALIGNMENT\_\-MASK}\ ($\sim$(IVTE\_\-DATA\_\-ALIGNMENT\_\-SIZE-1))} \label{IVTE_8ih_a18} \begin{CompactList}\small\item\em The IVTE data alignment mask.\item\end{CompactList}\end{CompactItemize} \subsection*{Typedefs} \begin{CompactItemize} \item \hypertarget{IVTE_8ih_a19}{ \index{IVTE_dir@{IVTE\_\-dir}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_dir@{IVTE\_\-dir}} typedef \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} \hyperlink{IVTE_8ih_a19}{IVTE\_\-dir}} \label{IVTE_8ih_a19} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir}.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a20}{ \index{IVTE_hdr@{IVTE\_\-hdr}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_hdr@{IVTE\_\-hdr}} typedef \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} \hyperlink{IVTE_8ih_a20}{IVTE\_\-hdr}} \label{IVTE_8ih_a20} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr}.\item\end{CompactList}\item \hypertarget{IVTE_8ih_a21}{ \index{IVTE_tlr@{IVTE\_\-tlr}!IVTE.ih@{IVTE.ih}}\index{IVTE.ih@{IVTE.ih}!IVTE_tlr@{IVTE\_\-tlr}} typedef \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} \hyperlink{IVTE_8ih_a21}{IVTE\_\-tlr}} \label{IVTE_8ih_a21} \begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr}.\item\end{CompactList}\end{CompactItemize} \subsection*{Functions} \begin{CompactItemize} \item IVTE\_\-EXT\_\-PROTO int \hyperlink{IVTE_8ih_a22}{IVTE\_\-\_\-dir\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of a directory entry.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO int \hyperlink{IVTE_8ih_a23}{IVTE\_\-\_\-hdr\_\-sizeof} (int ndir) \begin{CompactList}\small\item\em Returns the size of an IVTE header structure needed to contain the specified number of directories.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO int \hyperlink{IVTE_8ih_a24}{IVTE\_\-\_\-tlr\_\-sizeof} (void) \begin{CompactList}\small\item\em Returns the size of a trailer record.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ \hyperlink{IVTE_8ih_a25}{IVTE\_\-\_\-hdr\_\-next} (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$hdr) \begin{CompactList}\small\item\em Advances the hdr pointer to point just past the end of the current event.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO const void $\ast$ \hyperlink{IVTE_8ih_a26}{IVTE\_\-\_\-data\_\-locate} (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$hdr, const struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} $\ast$dir) \begin{CompactList}\small\item\em Locates the data area associated with the specified directory.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO const struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} $\ast$ \hyperlink{IVTE_8ih_a27}{IVTE\_\-\_\-tlr\_\-locate} (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$hdr) \begin{CompactList}\small\item\em Locates the trailer record for this event.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO int \hyperlink{IVTE_8ih_a28}{IVTE\_\-\_\-ndir} (unsigned int status\_\-ndir) \begin{CompactList}\small\item\em Unpacks the number of directories from the status/directory count word.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO unsigned int \hyperlink{IVTE_8ih_a29}{IVTE\_\-\_\-status} (unsigned int status\_\-ndir) \begin{CompactList}\small\item\em Unpacks the status word from the status/directory count word.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO unsigned int \hyperlink{IVTE_8ih_a30}{IVTE\_\-\_\-data\_\-align} (unsigned int offset) \begin{CompactList}\small\item\em Computes where the next data block should start.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO void \hyperlink{IVTE_8ih_a31}{IVTE\_\-\_\-hdr\_\-build} (struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$hdr, unsigned int hdr\_\-id, unsigned int size, unsigned int sequence, unsigned int status, unsigned int dir\_\-cnt) \begin{CompactList}\small\item\em Builds an IVTE header record.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO void \hyperlink{IVTE_8ih_a32}{IVTE\_\-\_\-dir\_\-build} (struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} $\ast$dir, unsigned int dir\_\-id, int size, unsigned int offset, unsigned int status) \begin{CompactList}\small\item\em Builds a directory record.\item\end{CompactList}\item IVTE\_\-EXT\_\-PROTO void \hyperlink{IVTE_8ih_a33}{IVTE\_\-\_\-tlr\_\-build} (struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} $\ast$tlr, unsigned int tlr\_\-id, unsigned int size) \begin{CompactList}\small\item\em Builds an IVTE trailer record.\item\end{CompactList}\end{CompactItemize} \subsection{Detailed Description} IVTE Inline Interface. \begin{Desc} \item[Author: ]\par JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc} {\bf DESCRIPTION} \par {\bf -----------} \par This defines the event structure. This consists of a header giving global information, followed by a series of directory entries describing the record structure. \subsection{Define Documentation} \hypertarget{IVTE_8ih_a12}{ \index{IVTE.ih@{IVTE.ih}!IVTE_DIR_SIZEOF@{IVTE\_\-DIR\_\-SIZEOF}} \index{IVTE_DIR_SIZEOF@{IVTE\_\-DIR\_\-SIZEOF}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-DIR\_\-SIZEOF]{\setlength{\rightskip}{0pt plus 5cm}\#define IVTE\_\-DIR\_\-SIZEOF\ (sizeof(struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir}))}} \label{IVTE_8ih_a12} Get the sizeof an IVTE directory structure. \begin{Desc} \item[MACROs]\par Parameterize the sizes of these structures. One should use these definitions or the callable versions, to ensure consistency. It is really only important for the IVTE header since it is a variable sized structure. \end{Desc} \subsection{Function Documentation} \hypertarget{IVTE_8ih_a30}{ \index{IVTE.ih@{IVTE.ih}!IVTE__data_align@{IVTE\_\-\_\-data\_\-align}} \index{IVTE__data_align@{IVTE\_\-\_\-data\_\-align}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-data\_\-align]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC unsigned int IVTE\_\-\_\-data\_\-align (unsigned int {\em offset})}} \label{IVTE_8ih_a30} Computes where the next data block should start. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em offset}]The current offset \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The offset where the next data block should start \end{Desc} \hypertarget{IVTE_8ih_a26}{ \index{IVTE.ih@{IVTE.ih}!IVTE__data_locate@{IVTE\_\-\_\-data\_\-locate}} \index{IVTE__data_locate@{IVTE\_\-\_\-data\_\-locate}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-data\_\-locate]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC const void $\ast$ IVTE\_\-\_\-data\_\-locate (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ {\em hdr}, const struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} $\ast$ {\em dir})}} \label{IVTE_8ih_a26} Locates the data area associated with the specified directory. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em hdr}]The IVTE header \item[{\em dir}]The IVTE directory to locate the data for. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Pointer to the data area. \end{Desc} \hypertarget{IVTE_8ih_a32}{ \index{IVTE.ih@{IVTE.ih}!IVTE__dir_build@{IVTE\_\-\_\-dir\_\-build}} \index{IVTE__dir_build@{IVTE\_\-\_\-dir\_\-build}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-dir\_\-build]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC void IVTE\_\-\_\-dir\_\-build (struct \hyperlink{struct__IVTE__dir}{\_\-IVTE\_\-dir} $\ast$ {\em dir}, unsigned int {\em dir\_\-id}, int {\em size}, unsigned int {\em offset}, unsigned int {\em status})}} \label{IVTE_8ih_a32} Builds a directory record. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em dir}]The IVTE directory to build \item[{\em dir\_\-id}]The id or name of this directory \item[{\em size}]The size, in bytes, of the data described by this directory. \item[{\em offset}]The offset, in bytes from the top of the IVTE data structure, of the data described by this directory. \item[{\em status}]The 'status' to associate with this directory entry.\end{description} \end{Desc} The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this. \hypertarget{IVTE_8ih_a22}{ \index{IVTE.ih@{IVTE.ih}!IVTE__dir_sizeof@{IVTE\_\-\_\-dir\_\-sizeof}} \index{IVTE__dir_sizeof@{IVTE\_\-\_\-dir\_\-sizeof}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-dir\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC int IVTE\_\-\_\-dir\_\-sizeof (void)}} \label{IVTE_8ih_a22} Returns the size of a directory entry. \begin{Desc} \item[Returns: ]\par The size, in bytes, of a directory entry\end{Desc} Returns the size of a directory entry. This is no big deal, but is provided to give the same look and feel as when one asks for a IVTE header size. Note that one should not calculate the sizeof an IVTE structure needed to hold a number of directories by using \par \footnotesize\begin{verbatim} nbytes = IVTE__hdr_sizeof(0) + n * IVTE__dir_sizeof () \end{verbatim}\normalsize This calculation potentially neglects alignment issues. Instead, use IVTE\_\-\_\-hdr\_\-sizeof (n). \hypertarget{IVTE_8ih_a31}{ \index{IVTE.ih@{IVTE.ih}!IVTE__hdr_build@{IVTE\_\-\_\-hdr\_\-build}} \index{IVTE__hdr_build@{IVTE\_\-\_\-hdr\_\-build}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-hdr\_\-build]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC void IVTE\_\-\_\-hdr\_\-build (struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ {\em hdr}, unsigned int {\em hdr\_\-id}, unsigned int {\em size}, unsigned int {\em sequence}, unsigned int {\em status}, unsigned int {\em dir\_\-cnt})}} \label{IVTE_8ih_a31} Builds an IVTE header record. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em hdr}]Pointer to the header structure to build. \item[{\em hdr\_\-id}]The header id or 'name' of this record. \item[{\em sequence}]The sequence number of this event. \item[{\em size}]The size, in bytes, of this event. \item[{\em status}]The global status of this event. \end{description} \end{Desc} \begin{Desc} \item[m dir\_\-cnt The number of directories associated with this event.]\par The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this.\end{Desc} \begin{Desc} \item[Warning: ]\par Note that the {\em size} parameter is the actual length of the event, i.e. how many bytes is it from the beginning of the header record to the end of the trailer record. Due to alignment factors, this number is not necessarily equivalent to the sum of the pieces. \end{Desc} \hypertarget{IVTE_8ih_a25}{ \index{IVTE.ih@{IVTE.ih}!IVTE__hdr_next@{IVTE\_\-\_\-hdr\_\-next}} \index{IVTE__hdr_next@{IVTE\_\-\_\-hdr\_\-next}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-hdr\_\-next]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ IVTE\_\-\_\-hdr\_\-next (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ {\em hdr})}} \label{IVTE_8ih_a25} Advances the hdr pointer to point just past the end of the current event. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em hdr}]Pointer to the beginning of the current event. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par Pointer to the next event.\end{Desc} If multiple events are stored off this pointer, then the returned pointer points to the beginning of the next event. This is useful for iterating through a series of contigious events. If this is the last event, then the pointer points at where the next event will start. \hypertarget{IVTE_8ih_a23}{ \index{IVTE.ih@{IVTE.ih}!IVTE__hdr_sizeof@{IVTE\_\-\_\-hdr\_\-sizeof}} \index{IVTE__hdr_sizeof@{IVTE\_\-\_\-hdr\_\-sizeof}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-hdr\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC int IVTE\_\-\_\-hdr\_\-sizeof (int {\em ndir})}} \label{IVTE_8ih_a23} Returns the size of an IVTE header structure needed to contain the specified number of directories. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em ndir}]The number of directories this IVTE header needs to hold. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The sizeof an IVTE an IVTE header structure with {\em ndir} directories.\end{Desc} Returns the size of an IVTE header structure needed to hold the specified number of directory entries. Since various C compilers do not allow the usual trick of leaving an unspecified array size as the last member of a structure, one is forced to put some arbitrary number (but not 0) for the array size. Because of this, a formalized interface must be presented which subtracts off this contribution to the size of the structure. \hypertarget{IVTE_8ih_a28}{ \index{IVTE.ih@{IVTE.ih}!IVTE__ndir@{IVTE\_\-\_\-ndir}} \index{IVTE__ndir@{IVTE\_\-\_\-ndir}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-ndir]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC int IVTE\_\-\_\-ndir (unsigned int {\em status\_\-ndir})}} \label{IVTE_8ih_a28} Unpacks the number of directories from the status/directory count word. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em status\_\-dir}]The status/directory count word to extract the directory count from. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The number of directories.\end{Desc} The user is encouraged to use this routine rather than the extracting the value using the bit field definitions. Because of the way inline functions work, those definitions are exposed, but are intended to be part of the public interface. \hypertarget{IVTE_8ih_a29}{ \index{IVTE.ih@{IVTE.ih}!IVTE__status@{IVTE\_\-\_\-status}} \index{IVTE__status@{IVTE\_\-\_\-status}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-status]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC unsigned int IVTE\_\-\_\-status (unsigned int {\em status\_\-ndir})}} \label{IVTE_8ih_a29} Unpacks the status word from the status/directory count word. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em status\_\-dir}]The status/directory count word to extract the status word from. \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par The status word.\end{Desc} The user is encouraged to use this routine rather than the extracting the value using the bit field definitions. Because of the way inline functions work, those definitions are exposed, but are intended to be part of the public interface. \hypertarget{IVTE_8ih_a33}{ \index{IVTE.ih@{IVTE.ih}!IVTE__tlr_build@{IVTE\_\-\_\-tlr\_\-build}} \index{IVTE__tlr_build@{IVTE\_\-\_\-tlr\_\-build}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-tlr\_\-build]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC void IVTE\_\-\_\-tlr\_\-build (struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} $\ast$ {\em tlr}, unsigned int {\em tlr\_\-id}, unsigned int {\em size})}} \label{IVTE_8ih_a33} Builds an IVTE trailer record. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em tlr}]The IVTE trailer record to build. \item[{\em tlr\_\-id}]The id or 'name' of the trailer record. \item[{\em size}]The size, in bytes, of the IVTE data record.\end{description} \end{Desc} The user is encourage to use this routine rather than filling in the data structure directly. It was not intended to expose the data structure as part of the public interface, but the way inlines work forces this. \begin{Desc} \item[Warning: ]\par Note that the {\em size} parameter is the actual length of the event, i.e. how many bytes is it from the beginning of the header record to the end of the trailer record. Due to alignment factors, this number is not necessarily equivalent to the sum of the pieces. \end{Desc} \hypertarget{IVTE_8ih_a27}{ \index{IVTE.ih@{IVTE.ih}!IVTE__tlr_locate@{IVTE\_\-\_\-tlr\_\-locate}} \index{IVTE__tlr_locate@{IVTE\_\-\_\-tlr\_\-locate}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-tlr\_\-locate]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC const struct \hyperlink{struct__IVTE__tlr}{\_\-IVTE\_\-tlr} $\ast$ IVTE\_\-\_\-tlr\_\-locate (const struct \hyperlink{struct__IVTE__hdr}{\_\-IVTE\_\-hdr} $\ast$ {\em hdr})}} \label{IVTE_8ih_a27} Locates the trailer record for this event. \begin{Desc} \item[Parameters: ]\par \begin{description} \item[{\em hdr}]The IVTE header \end{description} \end{Desc} \begin{Desc} \item[Returns: ]\par A pointer to the trailer record for this event. \end{Desc} \hypertarget{IVTE_8ih_a24}{ \index{IVTE.ih@{IVTE.ih}!IVTE__tlr_sizeof@{IVTE\_\-\_\-tlr\_\-sizeof}} \index{IVTE__tlr_sizeof@{IVTE\_\-\_\-tlr\_\-sizeof}!IVTE.ih@{IVTE.ih}} \subsubsection[IVTE\_\-\_\-tlr\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}IVTE\_\-EXT\_\-FNC int IVTE\_\-\_\-tlr\_\-sizeof (void)}} \label{IVTE_8ih_a24} Returns the size of a trailer record. \begin{Desc} \item[Returns: ]\par The size, in bytes, of a trailer record.\end{Desc} Returns the size of an IVTE trailer structure. This is provided merely for consistency. This is a fixed sized structure and can easily be gotten from sizeof (IVTE\_\-tlr). \begin{Desc} \item[Warning: ]\par When calculating size requirements or appending a trailer record to the end of an IVTE data record, make sure that alignment factors are taken into account. \end{Desc}