MR1PR

Section: C Library Functions (3)
Updated: 12 July 2000
Index
 

NAME

MR1PR - MR1 post-processing data library  

DESCRIPTION

/usr/lib/libmr1pr.a is a collection of functions which allow a programmer to manipulate MR1 post-processing data files.  

USAGE

Following is a description of all available subroutines in the MR1 library. An application referencing any of these routines must be linked to the library at compile time by specifying the -lmr1pr flag. The MR1 memory allocation library may also need to be referenced via the -lmem flag if the application calls certain of the routines described below.

Most of the subroutines described below which return an integer will return either MR1_SUCCESS or a defined failure code such as MR1_READ, MR1_MEMALLOC, etc. Return values for all other functions will be explicitly described.

Many of the subroutines which relate to input or output require a pointer to an open XDR stream as one of the arguments. Such a stream will generally be obtained by calling xdrstdio_create() on an open file pointer. All of the input functions assume that the XDR stream is appropriately positioned at the time of the function call, e.g., a function which attempts to read a particular type of header will succeed only if the XDR stream is currently positioned at the beginning of such a header.

Note that the file reading functions described below are capable of reading files stored in obsolete versions of the file format as well as files stored in the current format. The file writing functions, however, will always write output files in the current format regardless of the value of the mf_version field of the file header which defines the format version.

#include <rpc/rpc.h>
#include <sys/time.h>
#include <sys/ipc.h>
#include <sys/shm.h>
#include <local/mr1pr.h>

int
mr1_rdmrfhdr(MR1File *
mrf, XDR *xdrs)

reads the next MR1 file header from the XDR input stream xdrs and stores it into the user-allocated structure mrf.

int
mr1_wrmrfhdr(MR1File *
mrf , XDR *xdrs)

writes the MR1 file header mrf to the XDR output stream xdrs.

int
mr1_rdpnghdr(Ping *
png, XDR *xdrs, int version)

reads the next MR1 ping header from the XDR input stream xdrs and stores it into the user-allocated structure png. The version of the file format being read must be indicated by version, which should normally be the value of the mf_version field of the input file's file header record.

int
mr1_wrpnghdr(Ping *
png, XDR *xdrs)

writes the ping header png to the XDR output stream xdrs.

unsigned int
mr1_pngdatabufsz(Ping *
png)

returns the size in bytes of the smallest buffer capable of holding the sensor, bathymetry and sidescan data associated with png.

float *
mr1_pngmemalloc(Ping *
png)

allocates enough memory to store the data associated with the ping header png. A pointer to the allocated memory is returned. (The pointer may be a null pointer if the function fails for any reason.) The quantity of memory allocated is dependent upon the number of data samples and padding samples indicated by png. Padding samples, i.e., meaningless placeholder samples that are immediately contiguous and subsequent to valid data samples, are never stored to files, but it is sometimes convenient to allocate this additional sample memory at the time a ping is read in order to perform an operation that may result in an increase in the number of meaningful samples associated with that ping. An arbitrary amount of such additional memory can be allocated with this function by setting png->png_snspad and the ps_btypad and ps_sspad fields of the png->png_sides[ACP_PORT] and png->png_sides[ACP_STBD] substructures to appropriate values before the function is called.

int
mr1_pngrealloc(Ping *
png, float **data, unsigned int *datasz)

allocates memory similarly to mr1_pngmemalloc() as described above but is generally more convenient to use. Its second and third arguments are the addresses of a buffer pointer and an integer describing the size of the buffer. The buffer pointer and the integer should be set to the null pointer and 0, respectively, before the first call to this routine. Each time the routine is called it will determine the smallest buffer size sufficient to hold the data samples and padding samples indicated by png. If the buffer pointed to by *data is large enough (as described by *datasz) to hold those samples then it is zeroed and nothing else is done, otherwise the existing buffer (if any) is freed, a new buffer is allocated, and *data and *datasz are updated to reflect the new buffer and its size. Note that, unlike mr1_pngmemalloc(), the return value of this function is an error code (e.g., MR1_SUCCESS) and not a pointer to the buffer.

int
mr1_rdpngdata(Ping *
png, float *data, XDR *xdrs)

reads ping data from the XDR input stream xdrs and stores it into the memory pointed to by data. The number of data samples to be read is obtained from the header structure png. This routine assumes that the data memory has already been allocated (e.g., by mr1_pngmemalloc()). Compass samples are read and stored into the first png->png_compass.sns_nsamps*sizeof(float) bytes of data. Towfish depth samples are read and stored into the next png->png_depth.sns_nsamps*sizeof(float) bytes. Pitch samples are read and stored into the next png->png_pitch.sns_nsamps*sizeof(float) bytes. Roll samples are read and stored into the next png->png_roll.sns_nsamps*sizeof(float) bytes. Port bathymetry samples are read and stored into the next 2*png->png_sides[ACP_PORT].ps_btycount*sizeof(float) bytes. Port sidescan samples are read and stored into the next png->png_sides[ACP_PORT].ps_sscount*sizeof(float) bytes. Starboard bathymetry samples are read and stored into the next 2*png->png_sides[ACP_STBD].ps_btycount*sizeof(float) bytes. Finally, starboard sidescan samples are read and stored into the last png->png_sides[ACP_STBD].ps_sscount*sizeof(float) bytes. If sample padding has been specified by the png header as described above, each group of samples as described above may be separated from the preceding group by a byte offset corresponding to the amount of padding applied to the previous group. For instance, if the port bathymetry has been padded, then the port sidescan samples will be offset from the end of the port bathymetry samples by a gap which is 2*png->png_sides[ACP_PORT].ps_btypad*sizeof(float) bytes in length. Note that each bathymetry sample consists of two consecutive floating point values, the first value representing across-track distance and the second value representing depth (hence the factor of 2 included in the preceding expressions). Sensor sample padding as specified by png->png_snspad is applied between the last group of sensor samples and the port bathymetry, not between each group (e.g., compass and depth) of sensor samples.

int
mr1_wrpngdata(Ping *
png, float *data, XDR *xdrs)

writes the ping data pointed to by data and associated with the ping header png to the XDR output stream xdrs. The number of data samples to be written is obtained from png. Padding samples, if any, are not written, but their presence as indicated by the png_snspad, ps_btypad and ps_sspad fields of png will affect the offsets from data at which the various bathymetry and sidescan samples are presumed to be located.

int
mr1_getpngdataptrs(Ping *
png, float *data, float **cp, float **dp, float **pp, float **rp, float **pbty, float **pss, float **sbty, float **sss)

returns pointers to the various sensor, bathymetry and sidescan components of the data buffer associated with png. *cp, *dp, *pp, *rp, *pbty, *pss, *sbty and *sss will be set to point to the compass, depth, pitch, roll, port bathymetry, port sidescan, starboard bathymetry and starboard sidescan samples respectively. Any of the last eight arguments may be set to (float **) 0 if it is not desired that the routine return a pointer to that particular data component.

int
mr1_rdpng(Ping *
png, float **data, XDR *xdrs, int version)

reads a ping from the XDR input stream xdrs. The header will be stored into png, and the data will be stored into *data. This routine allocates the memory pointed to by *data. (The data parameter should be passed as the address of a float * variable, which will be set to point to the newly allocated memory.) The version of the file format being read must be indicated by version, which should normally be the value of the mf_version field of the input file's file header record. This function performs the same operation as calling mr1_rdpnghdr(), mr1_pngmemalloc() and mr1_rdpngdata() in succession. Note that it is not possible to allocate sample padding with this routine.

int
mr1_wrpng(Ping *
png, float *data, XDR *xdrs)

writes both the ping header pointed to by png and the data pointed to by data to the XDR output stream xdrs.

int
mr1_seekpng(int
n, XDR *xdrs, int version)

skips over the next n pings in the XDR input stream xdrs, leaving the stream positioned at the beginning of the next ping. The version of the file format being read must be indicated by version, which should normally be the value of the mf_version field of the input file's file header record.

int
mr1_seekpngdata(Ping *
png, XDR *xdrs)

skips over a ping data segment (whose size is described by png) in the XDR input stream xdrs, leaving the stream positioned at the beginning of the next ping.

int
mr1_copypng(int
n, XDR *xdris, XDR *xdros, int version)

copies the next n pings from the XDR input stream xdris to the XDR output stream xdros, leaving the input stream positioned at the beginning of the next ping. The version of the file format being read must be indicated by version, which should normally be the value of the mf_version field of the input file's file header record.

int
mr1_appendstr(char **
field, char *string)

appends the specified string to any character string field of an existing MR1 header. Note that the field parameter must be the address of the header's character string field, and not the string itself. This routine will allocate new memory for the appended string and deallocate the memory consumed by the previous string where appropriate.

int
mr1_replacestr(char **
field, char *string)

replaces an existing character string field of an MR1 header with the specified string. Note that the field parameter must be the address of the header's character string field, and not the string itself. This routine will allocate new memory for the replacement string and deallocate the memory consumed by the previous string where appropriate. (A copy is made of the character string pointed to by string, so string may be safely deallocated, overwritten, etc., after the function returns.)

int
mr1_appendlog(MR1File *
mrf, char **argv)

appends the specified argument vector argv to the log field of the named MR1 header, inserting a blank space between each of the character strings pointed to by argv and appending a trailing semicolon to the final string. The routine will also append a newline to the pre-existing log field before appending argv if that pre-existing log field is non-empty. The last element of the argv array of character pointers must be a null pointer. This routine will allocate new memory for the modified log field and deallocate the memory consumed by the previous log field.

Two routines are provided for the generation of single- and double-precision IEEE NaN (not-a-number) quantities which are used by the mr1file(4) format to note that the value of a certain parameter (e.g., the towfish pulse length as described by the ps_pulse field of the PingSide data structure) is unknown.

float
mr1_nanf()

and

double
mr1_nand()

respectively generate these single- and double-precision NaN quantities. Each of the routines

int
mr1_isnanf(float
f)

and

int
mr1_isnand(double
d)

will return 1 if its argument is a NaN quantity and 0 otherwise.

A group of routines are provided for the manipulation of ping marks, which are used to flag pings either within a single program or between cooperating applications. A ping mark will have an integer value which is either MR1_NULLMARK or some bitwise combination of the bitflags MR1_LOWMARK and/or MR1_HIGHMARK. Each side of a ping, ACP_PORT and ACP_STBD, is marked separately.

void *
mr1_mrkmemalloc(int
size)

allocates enough memory to maintain ping marks for a group of size pings, sets all of those marks to MR1_NULLMARK and returns a pointer to that memory. (The pointer may be a null pointer if the function fails for any reason.)

int
mr1_mrkget(void *
markers, int side, int pingid)

returns the mark value of the specified pingid on the declared side from the ping mark memory buffer markers.

void
mr1_mrkset(void *
markers, int side, int pingid, int value)

sets the mark value of the specified pingid on the declared side in the ping mark memory buffer markers to the stated value.

Finally, the routine

int
mr1_tmparse(char *
str, int mode, double *tmval)

parses a character string str of the form

       year/julianday-hour:minute:second

(when mode is TM_JULIAN) or

       year/month/day-hour:minute:second

(when mode is TM_CALENDAR), setting *tmval equal to the number of seconds since January 1, 1970, represented by the time described within str. The routine will allow any of the field separation characters '/', '-', ':' and/or ' ' to be used interchangeably within str, e.g., '92-67-1-23-56' and '92/67 1:23:56' denote the same time value. All fields except the year are optional and, if not specified, will be set to appropriate minimum values. If any particular field other than the year is specified, however, then all other fields which would normally precede that field within the string must also be specified. The year will be interpreted explicitly unless it is (i) between 0 and 49, in which case it will be interpreted as 2000+year, or (ii) between 50 and 99, in which case it will be interpreted as 1900+year. Month and day values are specified in normal human (rather than Unix) format, meaning that the julianday may range from 1 to 366, while the calendar month and day may range from 1 to 12 and 1 to 31 respectively. The second field may include a decimal fraction if so desired, while all other fields must be non-negative integers. The length of str may not exceed TM_MAXSTRLEN.  

SEE ALSO

mr1file(4)  

AUTHOR

Roger Davis, August 1991.


 

Index

NAME
DESCRIPTION
USAGE
SEE ALSO
AUTHOR

This document was created by man2html, using the manual pages.