Detailed Description

Provides routines for opening, closing, positioning, and performing other manipulations on a LALFrStream.

A frame stream is like a file stream except that it streams along the set of frames in a set of frame files. These routines are high-level routines that allow you to extract frame data. Many of these routines have names similar to the standard C file stream manipulation routines and perform similar functions.

The routines XLALFrStreamOpen() and XLALFrStreamClose() are used to open and close a frame stream. The stream is created by XLALFrStreamOpen(), and must be a pointer to NULL before it is opened. It must have been created prior to calling XLALFrStreamClose(), and after this call, the stream will be a pointer to NULL. The routine XLALFrStreamOpen() requires the user to specify the directory name of the frame files and the head names. If the directory is NULL, the routine uses the current director (.). The head names specifies which files are the wanted files in the specified directory. Wildcards are allowed. For example, to get LLO frames only, the head names could be set to L-*.gwf. If the head name is NULL, the default value *.gwf is used. The routine XLALFrStreamCacheOpen() is like XLALFrStreamOpen() except that the list of frame files is taken from a frame file cache. [In fact, XLALFrStreamOpen() simply uses XLALFrCacheGenerate() and XLALFrStreamCacheOpen() to create the stream.]

The routine XLALFrStreamSetMode() is used to change the operating mode of a frame stream, which determines how the routines try to accomodate gaps in data and requests for times when there is no data (e.g., before the beginning of the data, after the end of the data, or in some missing data). The default mode, which is given the value LAL_FR_STREAM_DEFAULT_MODE, prints warnings if a time requested corresponds to a time when there is no data (but then skips to the first avaliable data) and prints an info message when a gap in the data occurs (but then skips beyond the gap). This default mode is equal to the combination LAL_FR_STREAM_VERBOSE_MODE | LAL_FR_STREAM_IGNOREGAP_MODE | LAL_FR_STREAM_IGNORETIME_MODE where LAL_FR_STREAM_VERBOSE_MODE is equal to the combination LAL_FR_STREAM_TIMEWARN_MODE | LAL_FR_STREAM_GAPINFO_MODE. Use LAL_FR_STREAM_VERBOSE_MODE to print out warnings when requesting times with no data and print out an info message when a gap in the data is encountered. Unless the mode is supplemented with LAL_FR_STREAM_IGNOREGAP_MODE, gaps encountered in the data will cause a routine to exit with a non-zero status code; similarly, LAL_FR_STREAM_IGNORETIME_MODE prevents routines from failing if a time when there is not data is requested. Set the mode to LAL_FR_STREAM_SILENT_MODE to suppress the warning and info messages but still cause routines to fail when data is not available. Note: the default value LAL_FR_STREAM_DEFAULT_MODE is assumed initially, but this is not necessarily the recommended mode — it is adopted for compatibility reasons.

The routine XLALFrStreamEnd() determines if the end-of-frame-data flag for the data stream has been set.

The routine XLALFrStreamNext() advances the frame stream to the beginning of the next frame.

The routine XLALFrStreamRewind() rewinds the frame stream to the first frame.

The routine XLALFrStreamSeek() sets the frame stream to a specified time, or the earliest time after the specified time if that time is not available (e.g., if it is before the beginning of the frame stream or if it is in a gap in the frame data). The routine XLALFrStreamTell() returns the current time within the frame stream.

The routine XLALFrStreamGetpos() returns a structure containing the current frame stream position. The frame stream can later be restored to this position using XLALFrStreamSetpos().

Prototypes
int	gethostname (char *name, int len)

Data Structures
struct	LALFrStream
	This structure details the state of the frame stream. More...

struct	LALFrStreamPos
	This structure contains a record of the state of a frame stream; this record can be used to restore the stream to the state when the record was made (provided the stream has not been closed). More...

Enumerations
enum	LALFrStreamState { LAL_FR_STREAM_OK = 0 , LAL_FR_STREAM_ERR = 1 , LAL_FR_STREAM_END = 2 , LAL_FR_STREAM_GAP = 4 , LAL_FR_STREAM_URL = 8 , LAL_FR_STREAM_TOC = 16 }
	Enum listing different stream states. More...

enum	LALFrStreamMode { LAL_FR_STREAM_SILENT_MODE = 0 , LAL_FR_STREAM_TIMEWARN_MODE = 1 , LAL_FR_STREAM_GAPINFO_MODE = 2 , LAL_FR_STREAM_VERBOSE_MODE = 3 , LAL_FR_STREAM_IGNOREGAP_MODE = 4 , LAL_FR_STREAM_IGNORETIME_MODE = 8 , LAL_FR_STREAM_DEFAULT_MODE = 15 , LAL_FR_STREAM_CHECKSUM_MODE = 16 }
	Enum listing different stream modes. More...

Routines to Open, Close and Get/Set Modes of a LALFrStream
int	XLALFrStreamClose (LALFrStream *stream)
	Closes a LALFrStream. More...

LALFrStream *	XLALFrStreamCacheOpen (LALCache *cache)
	Opens a LALFrStream associated with a LALCache. More...

LALFrStream *	XLALFrStreamOpen (const char dirname, const char pattern)
	Opens a LALFrStream for specified frame files. More...

int	XLALFrStreamGetMode (LALFrStream *stream)
	Returns the current operating mode of a LALFrStream. More...

int	XLALFrStreamSetMode (LALFrStream *stream, int mode)
	Change the operating mode of a LALFrStream. More...

Routines for Positioning and Manipulating the State of a LALFrStream
int	XLALFrStreamState (LALFrStream *stream)
	Gets the current state of a LALFrStream. More...

int	XLALFrStreamEnd (LALFrStream *stream)
	Checks to see if a LALFrStream is at the end of the stream. More...

int	XLALFrStreamError (LALFrStream *stream)
	Checks to see if a LALFrStream has encountered an error. More...

int	XLALFrStreamClearErr (LALFrStream *stream)
	Resets the state of a LALFrStream. More...

int	XLALFrStreamRewind (LALFrStream *stream)
	Rewinds a LALFrStream stream. More...

int	XLALFrStreamNext (LALFrStream *stream)
	Advance a LALFrStream stream to the beginning of the next frame. More...

int	XLALFrStreamSeek (LALFrStream stream, const LIGOTimeGPS epoch)
	Seeks a LALFrStream stream to data at a given time. More...

int	XLALFrStreamSeekO (LALFrStream *stream, double dt, int whence)
	Seeks a LALFrStream stream by a time offset. More...

int	XLALFrStreamTell (LIGOTimeGPS epoch, LALFrStream stream)
	Tells the current time of the current position of a LALFrStream stream. More...

int	XLALFrStreamGetpos (LALFrStreamPos position, LALFrStream stream)
	Gets the current position of a LALFrStream stream. More...

int	XLALFrStreamSetpos (LALFrStream stream, const LALFrStreamPos position)
	Sets the current position of a LALFrStream stream. More...

Function Documentation

◆ gethostname()

int gethostname	(	char *	name,
		int	len
	)

◆ XLALFrStreamClose()

int XLALFrStreamClose ( LALFrStream * stream )

Closes a LALFrStream.

This routine closes all file pointers and deallocates memory associated with a given LALFrStream. It performs no action if stream is NULL.

Parameters

stream Pointer to the LALFrStream structure to be closed.

Return values

0	Success.
<0	Failure.

Definition at line 170 of file LALFrStream.c.

◆ XLALFrStreamCacheOpen()

LALFrStream * XLALFrStreamCacheOpen ( LALCache * cache )

Opens a LALFrStream associated with a LALCache.

This routine creates a LALFrStream that is a stream associated with the frame files contained in a LALCache.

Parameters

cache Pointer to a LALCache structure describing the frame files to stream.

Returns: Pointer to a newly created LALFrStream structure.

Return values

NULL Failure.

Definition at line 189 of file LALFrStream.c.

◆ XLALFrStreamOpen()

LALFrStream * XLALFrStreamOpen	(	const char *	dirname,
		const char *	pattern
	)

Opens a LALFrStream for specified frame files.

This routine creates a LALFrStream that is a stream associated with the frame files in the specified directory matching the specified pattern. The directory containing the frame files is specified by the parameter dirname, or the current directory (.) if NULL. Files matching pattern will included in the stream. Wildcards are allowed. For example, to get LLO frames only, pattern could be set to L-*.gwf. If pattern is NULL, the default value *.gwf is used.

Parameters

dirname	String containing the director name containing the frame files
pattern	Pattern matching the desired frame files.

Returns: Pointer to a newly created LALFrStream structure.

Return values

NULL Failure.

Definition at line 253 of file LALFrStream.c.

◆ XLALFrStreamGetMode()

int XLALFrStreamGetMode ( LALFrStream * stream )

Returns the current operating mode of a LALFrStream.

The operating mode of a LALFrStream determines how routines try to accommodate gaps in data and requests for times when there is no data (e.g., before the beginning of the data, after the end of the data, or in some period of missing data). See XLALFrStreamSetMode() for a description of the LALFrStreamMode modes.

Parameters

stream Pointer to a LALFrStream structure whose mode will be determined.

Returns: The current LALFrStreamMode mode, which is a bit field flag of indicating the current operating modes of the LALFrStream.

Definition at line 284 of file LALFrStream.c.

◆ XLALFrStreamSetMode()

int XLALFrStreamSetMode	(	LALFrStream *	stream,
		int	mode
	)

Change the operating mode of a LALFrStream.

The operating mode of a LALFrStream determines how routines try to accommodate gaps in data and requests for times when there is no data (e.g., before the beginning of the data, after the end of the data, or in some period of missing data).

The default LALFrStreamMode mode, which is given the value LAL_FR_STREAM_DEFAULT_MODE, prints warnings if a time requested corresponds to a time when there is no data (but then skips to the first avaliable data) and prints an info message when a gap in the data occurs (but then skips beyond the gap). This default mode is equal to the combination LAL_FR_STREAM_VERBOSE_MODE | LAL_FR_STREAM_IGNOREGAP_MODE | LAL_FR_STREAM_IGNORETIME_MODE where LAL_FR_STREAM_VERBOSE_MODE is equal to the combination LAL_FR_STREAM_TIMEWARN_MODE | LAL_FR_STREAM_GAPINFO_MODE. Use LAL_FR_STREAM_VERBOSE_MODE to print out warnings when requesting times with no data and print out an info message when a gap in the data is encountered. Unless the mode is supplemented with LAL_FR_STREAM_IGNOREGAP_MODE, gaps encountered in the data will cause a routine to exit with a non-zero status code; similarly, LAL_FR_STREAM_IGNORETIME_MODE prevents routines from failing if a time when there is not data is requested. Set the mode to LAL_FR_STREAM_SILENT_MODE to suppress the warning and info messages but still cause routines to fail when data is not available. To enable frame file checksum checking, set the LAL_FR_STREAM_CHECKSUM_MODE bit.

Note: The default value LAL_FR_STREAM_DEFAULT_MODE is assumed initially, but this is not necessarily the recommended mode — it is adopted for compatibility reasons.

Parameters

stream	Pointer to a `LALFrStream` structure whose mode will be changed.
mode	Bit lag field specifying the operating modes.

Return values

0	Success.
<0	Current file does not pass frame file checksum.

Definition at line 327 of file LALFrStream.c.

◆ XLALFrStreamState()

int XLALFrStreamState ( LALFrStream * stream )

Gets the current state of a LALFrStream.

Gets the LALFrStreamState state value in a LALFrStream structure. The value returned is a bit field specifying the combination of states described by the LALFrStreamState bits.

Parameters

stream Pointer to a LALFrStream structure whose state will be returned.

Returns: The LALFrStreamState state of the LALFrStream.

Definition at line 353 of file LALFrStream.c.

◆ XLALFrStreamEnd()

int XLALFrStreamEnd ( LALFrStream * stream )

Checks to see if a LALFrStream is at the end of the stream.

Determines if the LAL_FR_STREAM_END bit is set in the LALFrStreamState state value in a LALFrStream structure, indicating that the stream is at the end.

Parameters

stream Pointer to a LALFrStream structure.

Return values

0	The LAL_FR_STREAM_END bit is not set in `stream`.
1	The LAL_FR_STREAM_END bit is set in `stream`.

Definition at line 368 of file LALFrStream.c.

◆ XLALFrStreamError()

int XLALFrStreamError ( LALFrStream * stream )

Checks to see if a LALFrStream has encountered an error.

Determines if the LAL_FR_STREAM_ERR bit is set in the LALFrStreamState state value in a LALFrStream structure, indicating that there has been an error in the stream.

Parameters

stream Pointer to a LALFrStream structure.

Return values

0	The LAL_FR_STREAM_ERR bit is not set in `stream`.
1	The LAL_FR_STREAM_ERR bit is set in `stream`.

Definition at line 383 of file LALFrStream.c.

◆ XLALFrStreamClearErr()

int XLALFrStreamClearErr ( LALFrStream * stream )

Resets the state of a LALFrStream.

Sets the LALFrStreamState state of a LALFrStream structure to the value LAL_FR_STREAM_OK.

Parameters

stream Pointer to a LALFrStream structure.

Return values

0 Success.

Definition at line 396 of file LALFrStream.c.

◆ XLALFrStreamRewind()

int XLALFrStreamRewind ( LALFrStream * stream )

Rewinds a LALFrStream stream.

Rewinds a LALFrStream stream to the beginning and resets the state to LAL_FR_STREAM_OK.

Parameters

stream Pointer to a LALFrStream structure.

Return values

0	Success.
<0	Failure.

Definition at line 411 of file LALFrStream.c.

◆ XLALFrStreamNext()

int XLALFrStreamNext ( LALFrStream * stream )

Advance a LALFrStream stream to the beginning of the next frame.

The position of a LALFrStream is advanced so that the next read will be at the next frame. If the stream is at the end, the LAL_FR_STREAM_END bit of the LALFrStreamState state is set, and the routine returns the return code 1. If there is a gap in the data before the next frame, the LAL_FR_STREAM_GAP bit of the LALFrStreamState state is set, and the routine returns the return code 2. If, however, the LAL_FR_STREAM_IGNOREGAP_MODE bit is not set in the LALFrStreamMode mode then the routine produces an error if a gap is encountered.

Parameters

stream Pointer to a LALFrStream structure.

Return values

2	Gap in the data is encountered.
1	End of stream encountered.
0	Normal success.
<0	Failure.

Definition at line 437 of file LALFrStream.c.

◆ XLALFrStreamSeek()

int XLALFrStreamSeek	(	LALFrStream *	stream,
		const LIGOTimeGPS *	epoch
	)

Seeks a LALFrStream stream to data at a given time.

The position of a LALFrStream is set so that the next read will be at the specified time. LAL_FR_STREAM_END and LAL_FR_STREAM_GAP bits are turned off in the LALFrStreamState state. If the time is before the beginning of the stream, the stream position is set to the beginning of the stream and the routine returns with code 1. If the time is after the end of the stream, the LAL_FR_STREAM_END bit is set in the LALFrStreamState state, and the routine returns with code 2. If the time is in a gap in the data, the LAL_FR_STREAM_GAP bit is set in the LALFrStreamState state, the position is advanced to the next data, and the routine returns with code 3. If, however, the LAL_FR_STREAM_IGNORETIME_MODE bit is not set in the LALFrStreamMode mode then these conditions result in an error.

Parameters

stream	Pointer to a `LALFrStream` structure.
epoch	The LIGOTimeGPS time of the next data to read.

Return values

3	Time requested is in a gap in the data.
2	Time requested is after the end of the stream.
1	Time requested is before the beginning of the stream.
0	Normal success.
<0	Failure.

Definition at line 542 of file LALFrStream.c.

◆ XLALFrStreamSeekO()

int XLALFrStreamSeekO	(	LALFrStream *	stream,
		double	dt,
		int	whence
	)

Seeks a LALFrStream stream by a time offset.

The position of a LALFrStream is set so that the next read will be at the specified time offset. The offset dt is a number of seconds relative to the whence postion, which can be SEEK_SET to seek relative to the beginning of the stream, SEEK_CUR to seek relative to the current position of the stream, or SEEK_END to seek relative to the end of the stream. The return codes and conditions are the same as XLALFrStreamSeek().

Parameters

stream	Pointer to a `LALFrStream` structure.
dt	The offset time in seconds.
whence	The position whence to seek: one of `SEEK_SET`, `SEEK_CUR`, or `SEEK_END`.

Return values

3	Time requested is in a gap in the data.
2	Time requested is after the end of the stream.
1	Time requested is before the beginning of the stream.
0	Normal success.
<0	Failure.

Definition at line 676 of file LALFrStream.c.

◆ XLALFrStreamTell()

int XLALFrStreamTell	(	LIGOTimeGPS *	epoch,
		LALFrStream *	stream
	)

Tells the current time of the current position of a LALFrStream stream.

Parameters

[out]	epoch	Pointer to a LIGOTimeGPS structure that will contain the time of the current position of the stream.
[in]	stream	Pointer to a `LALFrStream` structure.

Return values

0 Success.

Definition at line 717 of file LALFrStream.c.

◆ XLALFrStreamGetpos()

int XLALFrStreamGetpos	(	LALFrStreamPos *	position,
		LALFrStream *	stream
	)

Gets the current position of a LALFrStream stream.

The XLALFrStreamGetpos() and XLALFrStreamSetpos() provide the ability to save the position of a LALFrStream stream and to return the stream to that previously saved position. This can be useful, e.g., when reading several different channels from the data files.

Parameters

[out]	position	Pointer to a `LALFrStreamPos` structure that will save the current position.
[in]	stream	Pointer to a `LALFrStream` structure. time of the current position of the stream.

Return values

0 Success.

Definition at line 736 of file LALFrStream.c.

◆ XLALFrStreamSetpos()

int XLALFrStreamSetpos	(	LALFrStream *	stream,
		const LALFrStreamPos *	position
	)

Sets the current position of a LALFrStream stream.

The XLALFrStreamGetpos() and XLALFrStreamSetpos() provide the ability to save the position of a LALFrStream stream and to return the stream to that previously saved position. This can be useful, e.g., when reading several different channels from the data files.

Parameters

[in,out]	stream	Pointer to a `LALFrStream` structure.
[in]	position	Pointer to a `LALFrStreamPos` structure that has a previously saved position.

Return values

0 Success.

Definition at line 756 of file LALFrStream.c.

Enumeration Type Documentation

◆ LALFrStreamState

enum LALFrStreamState

Enum listing different stream states.

Enumerator
LAL_FR_STREAM_OK	nominal
LAL_FR_STREAM_ERR	error in frame stream
LAL_FR_STREAM_END	end of frame stream
LAL_FR_STREAM_GAP	gap in frame stream
LAL_FR_STREAM_URL	error opening frame URL
LAL_FR_STREAM_TOC	error reading frame TOC

Definition at line 70 of file LALFrStream.h.

◆ LALFrStreamMode

enum LALFrStreamMode

Enum listing different stream modes.

Enumerator
LAL_FR_STREAM_SILENT_MODE	silent mode
LAL_FR_STREAM_TIMEWARN_MODE	display warning for invalid time requests
LAL_FR_STREAM_GAPINFO_MODE	display info for gaps in data
LAL_FR_STREAM_VERBOSE_MODE	display warnings and info
LAL_FR_STREAM_IGNOREGAP_MODE	ignore gaps in data
LAL_FR_STREAM_IGNORETIME_MODE	ignore invalid times requested
LAL_FR_STREAM_DEFAULT_MODE	ignore time/gaps but report warnings & info
LAL_FR_STREAM_CHECKSUM_MODE	ensure that file checksums are OK

Definition at line 80 of file LALFrStream.h.

Detailed Description

Prototypes

Data Structures

Enumerations

Routines to Open, Close and Get/Set Modes of a LALFrStream

Routines for Positioning and Manipulating the State of a LALFrStream

Function Documentation

◆ gethostname()

◆ XLALFrStreamClose()

◆ XLALFrStreamCacheOpen()

◆ XLALFrStreamOpen()

◆ XLALFrStreamGetMode()

◆ XLALFrStreamSetMode()

◆ XLALFrStreamState()

◆ XLALFrStreamEnd()

◆ XLALFrStreamError()

◆ XLALFrStreamClearErr()

◆ XLALFrStreamRewind()

◆ XLALFrStreamNext()

◆ XLALFrStreamSeek()

◆ XLALFrStreamSeekO()

◆ XLALFrStreamTell()

◆ XLALFrStreamGetpos()

◆ XLALFrStreamSetpos()

Enumeration Type Documentation

◆ LALFrStreamState

◆ LALFrStreamMode