B3dutil Module

The b3dutil module contains various utility functions, such as for large-file I/O and error processing.

Header to include: b3dutil.h
(includes cfsemshare.h and mrcslice.h)


int imodVersion(const char *pname)
void imodCopyright(void)
void imodUsageHeader(const char *pname)
char *IMOD_DIR_or_default(int *assumed)
char *imodProgName(const char *fullname)
int imodBackupFile(const char *filename)
int imodbackupfile(const char *filename, int strlen)
int imodgetenv(char *var, char *value, int varSize, int valueSize)
int imodGetpid()
int imodgetpid()
void pidToStderr()
void pidtostderr()
int imodgetstamp()
void overrideWriteBytes(int value)
void overridewritebytes(int *value)
int writeBytesSigned()
int writebytessigned()
int readBytesSigned(int stamp, int flags, int mode, float dmin, float dmax)
int readbytessigned(int *stamp, int *flags, int *mode, float *dmin, float *dmax)
char *f2cString(const char *str, int strSize)
int c2fString(const char *cStr, char *fStr, int fSize)
void b3dError(FILE *out, char *format, ...)
void b3dSetStoreError(int ival)
char *b3dGetError()
int b3dFseek(FILE *fp, int offset, int flag)
size_t b3dFread(void *buf, size_t size, size_t count, FILE *fp)
size_t b3dFwrite(void *buf, size_t size, size_t count, FILE *fp)
void b3dRewind(FILE *fp)
int mrc_big_seek(FILE *fp, int base, int size1, int size2, int flag)
int mrcHugeSeek(FILE *fp, int base, int x, int y, int z, int nx, int ny, int dsize, int flag)
int fgetline(FILE *fp, char s[], int limit)
void b3dHeaderItemBytes(int *nflags, int *nbytes)
void b3dheaderitembytes(int *nflags, int *nbytes)
void setOrClearFlags(b3dUInt32 *flags, b3dUInt32 mask, int state)
int numberInList(int num, int *list, int nlist, int noListValue)
int numberinlist(int *num, int *list, int *nlist, int *noListValue)
unsigned char **makeLinePointers(void *array, int xsize, int ysize, int dsize)
int b3dIMin(int narg, ...)
int b3dIMax(int narg, ...)
double wallTime(void)
double walltime(void)
int b3dMilliSleep(int msecs)
int b3dmillisleep(int *msecs)
int numOMPthreads(int optimalThreads)
int b3dOMPthreadNum()

int imodVersion(const char *pname)

Prints program name provided in pname, IMOD version and compilation date

void imodCopyright(void)

Prints copyright notice

void imodUsageHeader(const char *pname)

Calls imodVersion and imodCopyright

char *IMOD_DIR_or_default(int *assumed)

Returns the value of IMOD_DIR if it is set, or the default install location for the particular OS.  If assumed is not NULL, it is returned with 1 if the string is the default install location.

char *imodProgName(const char *fullname)

Returns a program name stripped of directories and .exe, given the full name (argv[0]) in fullname. It returns a pointer internal to argv[0], unless the name ends in .exe, in which case it tries to return a duplicate copy.  Do not free it.

int imodBackupFile(const char *filename)

Renames an existing file named filename to filename~ and deletes filename~ first if necessary

int imodbackupfile(const char *filename, int strlen)

A fortran wrapper for imodBackupFile

int imodgetenv(char *var, char *value, int varSize, int valueSize)

A Fortran-callable routine to get an environment variable, var and return its value in value.  Returns -1 for error or 1 if the variable is not defined.

int imodGetpid()

Returns the process ID

int imodgetpid()

Fortran-callable routine to get the process ID

void pidToStderr()

Prints the PID to standard error with the prefix expected by eTomo

void pidtostderr()

Fortran wrapper to pidToStderr

int imodgetstamp()

Fortran-callable function to return the IMOD stamp for MRC files

void overrideWriteBytes(int value)

Sets the value to be returned by writeBytesSigned overriding both the default value and the value of the environment variable WRITE_MODE0_SIGNED.

void overridewritebytes(int *value)

Fortran-callable  version of overrideWriteBytes

int writeBytesSigned()

Returns 0 if bytes are to be written unsigned, or non-zero if they are to be written, based on the default value, WRITE_SBYTES_DEFAULT, the value of environment variable WRITE_MODE0_SIGNED, and whether overrideWriteBytes has been called.

int writebytessigned()

Fortran wrapper for writeBytesSigned

int readBytesSigned(int stamp, int flags, int mode, float dmin, float dmax)

Returns 1 if bytes are to be read as signed and the file mode in mode is 0, otherwise returns 0.  stamp is the imodStamp header entry, flags is the imodFlags entry, dmin and dmax are the minimum and maximum from the header.  If the stamp is for an IMOD file, the value of the first bit of flags determines the result unless it is overridden by environment variable READ_MODE0_SIGNED having a value < -1 or > 1. Otherwise, the values of dmin and dmax determine the value unless READ_MODE0_SIGNED is nonzero.

int readbytessigned(int *stamp, int *flags, int *mode, float *dmin, float *dmax)

Fortran wrapper for readBytesSigned

char *f2cString(const char *str, int strSize)

Creates a C string with a copy of a Fortran string described by str and strsize, using malloc.

int c2fString(const char *cStr, char *fStr, int fSize)

Converts a C string in cStr into a Fortran string fStr with size fSize; returns -1 for error if the string will not fit.

void b3dError(FILE *out, char *format, ...)

Stores an error message and may print it as well.  The message is internally printed with vsprintf.  It is printed to fout unless b3dSetStoreError has been called with a non-zero value.

void b3dSetStoreError(int ival)

Sets flag to print messages passed by b3dError if ival is 0 (the default), just to store them internally if ival is 1, or to print messages destined to stderr to stdout instead if ival is -1.

char *b3dGetError()

Returns the current error string

int b3dFseek(FILE *fp, int offset, int flag)

A substitute for fseek that works for large files on all systems.

size_t b3dFread(void *buf, size_t size, size_t count, FILE *fp)

A substitute for fread that works for large files on all systems.  On Windows and Mac OSX, if the file is stdin, it will call again up to 5 times to try to satisfy the full request.

size_t b3dFwrite(void *buf, size_t size, size_t count, FILE *fp)

A substitute for fwrite that works for large files on all systems.

void b3dRewind(FILE *fp)

A substitute for rewind that works for large files on all systems.

int mrc_big_seek(FILE *fp, int base, int size1, int size2, int flag)

Does a seek in a large file with pointer fp.  The amount to seek is given by base + size1 * size2.  flag has the standard meaning for seeks, e.g., SEEK_SET, etc.  Returns the nonzero seek error if error.

int mrcHugeSeek(FILE *fp, int base, int x, int y, int z, int nx, int ny, int dsize, int flag)

Does a seek in a large image file with pointer fp.  The amount to seek is given by base plus the change in position indicated by x, y, and z, where nx and ny are the image dimensions in X and Y and dsize is the number of bytes per data element.  Specifically, it seeks by
  base + x * dsize + nx * dsize * (y + ny * z).
flag has the standard meaning for seeks, e.g., SEEK_SET, etc.  Returns the nonzero seek error if error.

int fgetline(FILE *fp, char s[], int limit)

Reads a line of characters from the file pointed to by fp and places it into array s of size limit.  Replaces newline with a null or terminates the string with null if reading stops because the array limit is reached.  Returns the length of the string, -1 for an error, -2 for end of file after a newline, or the negative of the length of the string plus two for end of file on a line not terminated by newline.

void b3dHeaderItemBytes(int *nflags, int *nbytes)

Returns the number of possible extra header items encoded as short integers by SerialEM in nflags, and the number of bytes that each occupies in nbytes, an array that should be dimensioned to 32.

void b3dheaderitembytes(int *nflags, int *nbytes)

A Fortran wrapper for b3dHeaderItemBytes.

void setOrClearFlags(b3dUInt32 *flags, b3dUInt32 mask, int state)

Set or clear bits in flags with the given mask, depending on whether state is nonzero or zero.

int numberInList(int num, int *list, int nlist, int noListValue)

Return 1 if num is in the list of nlist values in list, 0 if it is not, and noListValue if the list is empty (nlist 0 or list NULL).

int numberinlist(int *num, int *list, int *nlist, int *noListValue)

Fortran wrapper for numberInList

unsigned char **makeLinePointers(void *array, int xsize, int ysize, int dsize)

Returns a set of pointers to the lines of array, which has xsize data elements per line, ysize lines, and data element size dsize.  Returns NULL for memory error.

int b3dIMin(int narg, ...)

A variable argument min function for multiple integer arguments. Call as:  b3dIMin(4, ival1, ival2, ival3, ival4); For only two arguments with acceptable cost of multiple evaluations, use the macro, B3DMIN(val1, val2);

int b3dIMax(int narg, ...)

A variable argument max function for multiple integer arguments. Call as:  b3dIMax(4, ival1, ival2, ival3, ival4); For only two arguments with acceptable cost of multiple evaluations, use the macro, B3DMAX(val1, val2);

double wallTime(void)

Returns a measure of time in seconds with microsecond precision on Linux and Mac and the precision of the high performance counter on Windows.

double walltime(void)

Fortran wrapper for wallTime

int b3dMilliSleep(int msecs)

Sleeps for msec milliseconds.  Returns 0 on Windows; elsewhere it returns -1 for an error or the number of times the sleep was interrupted.

int b3dmillisleep(int *msecs)

Fortran wrapper for b3dMilliSleep

int numOMPthreads(int optimalThreads)

Computes the number of threads to specify in an OpenMP directive by taking the minimum of the given optimal thread number optimalThreads, the number of processors, and the value of OMP_NUM_THREADS, if any.  It evaluates the number of processors and value of OMP_NUM_THREADS only on the first call.  Returns 1 if there is no OpenMP available.

int b3dOMPthreadNum()

Returns the thread number of the current thread, numbered from 0 when calling from C or numbered from 1 when calling the Fortran wrapper.