MeatAxe  2.4 Programs for working with modular representations
Operating System Interface

## Detailed Description

The MeatAxe is written for a UNIX-like operating environment and uses many functions of the standard C library. To make the MeatAxe more portable between different operating systems, some C library and system calls are accessed through wrapper functions. These wrapper functions have names that begin with 'Sys'. For example SysFree() is the wrapper function for free().

## Macros

#define FM_CREATE   0x02
File mode: write.

#define FM_APPEND   0x03
File mode: append.

## Functions

int SysReadLong32 (FILE *f, long *buf, int n)

int SysWriteLong32 (FILE *f, const long *buf, int n)
Write long integers. More...

void SysInit ()
OS-specific initialization. More...

long SysTimeUsed (void)
CPU time. More...

void SysSetTimeLimit (long nsecs)
Set CPU time limit. More...

FILE * SysFopen (const char *name, int mode)
Open a file. More...

int SysFseek (FILE *file, long pos)
Set file pointer. More...

int SysRemoveFile (const char *name)
Remove a file This function deletes a file. More...

int SysRemoveDirectory (const char *name)
Removes a directory (which must be empty). More...

int SysCreateDirectory (const char *name)
Create a directory. More...

int SysFseekRelative (FILE *file, long distance)
Set file pointer relative to current position. More...

void * SysMalloc (size_t nbytes)
Allocate memory. More...

void * SysRealloc (void *buf, size_t nbytes)
Resizes a memory block. More...

void SysFree (void *x)
Free memory block. More...

int SysGetPid ()
Get process id. More...

## Function Documentation

 int SysCreateDirectory ( const char * name )

Create a directory.

This function creates a new directory. If the directory cannot be created for some reason, a run-time error is generated and the function returns -1.

SysRemoveDirectory()
Parameters
 name Name of the directory.
Returns
0 on success, -1 on error.
 FILE* SysFopen ( const char * name, int mode )

Open a file.

This function opens a file, like fopen(). The second argument, must be one of the predfined constants FM_READ (open for reading), FM_CREAT (create a new file and open for writing, or FM_APPEND (append to existing file or create a new file). Additional flags may be or'ed to the mode:

FM_LIB
If the file does not exist in the current directory, look in the library directory. The library directory is defined either by the environment variable MTXLIB, or at compile-time by the macro MTXLIB.
FM_TEXT
Open in text mode. This flag must be used on some systems (e.g., MS-DOS) to open text files. By default, files are assumed to contain binary data.
FM_NOERROR
Do not generate an error if the file does not exist.
Returns
A pointer to the open file or NULL on error.
 void SysFree ( void * x )

Free memory block.

This function works like free() but checks if the argument is not NULL. Otherwise, an appropriate error message is generated.

Parameters
 x Pointer to the memory block.
 int SysFseek ( FILE * file, long pos )

Set file pointer.

This function sets the file pointer to a given position. If pos is greater than or equal to zero, it is interpreted as an absolute position (relative to start of file). If pos is negative, the file pointer is moved to the end of file.

SysFseekRelative(), FfSeekRow()
Parameters
 file File handle. pos New position of file pointer.
Returns
0 on success, nonzero otherwise.
 int SysFseekRelative ( FILE * file, long distance )

Set file pointer relative to current position.

This function moves the file pointer by a given number of bytes, which may be positive or negative.

Parameters
 file The file handle. distance The number of bytes by which the file pointer shall be moved.
Returns
0 on success, nonzero on error.
SysFseek(), FfSeekRow()
 int SysGetPid ( )

Get process id.

This function returns a number which uniquely identifies the calling process on the local system. The exact meaning of this number depends on the operating system. In an UNIX environment, it is the process id (PID).

Returns
Process id.
 void SysInit ( void )

OS-specific initialization.

This function is called during library initialization. It performs any OS-specific actions. Applications should never call this function directly. Use MtxInit() instead.

 void* SysMalloc ( size_t nbytes )

Allocate memory.

This function works like malloc(), but the return value is never 0, even when the function was called with a 0 argument.

Parameters
 nbytes Size of memory block to allocate.
Returns
Pointer to memory block or NULL on error.
 int SysReadLong32 ( FILE * f, long * buf, int n )

This function reads @ n long integers from the file f into the array buf. buf must point to a memory area of at least n*sizeof(long) bytes and the file must be open for reading. The return value indicates how many integers have actually been read. This number may be less than n because the end of file was encountered while reading. A negative return value indicates a file i/o error.

SysReadLong32() expects that the numbers in the file are 4-byte integers in little-endian format, i.e. the least significant byte first. Using a machine-independent data format makes MeatAxe data files more portable, but there are also some disadvantages:

• The conversion to and from machine-independent format involves several arithmetic operations for each number read/written.
• The highest number which can be read/written is 232-1.
Parameters
 f File to read from. buf Pointer to buffer. n Number of integers to read.
Returns
Number of integers that were actually read, or $/1$ on error.
 void* SysRealloc ( void * buf, size_t nbytes )

Resizes a memory block.

This function works like realloc() but handles zero-length blocks differently (namely, by allocating 1 byte instead) to avoid problems with broken realloc() implementations.

Parameters
 buf Pointer to the memory block. nbytes Desired new size.
Returns
Pointer to resized memory block or NULL on error.
 int SysRemoveDirectory ( const char * name )

Removes a directory (which must be empty).

SysCreateDirectory().
Parameters
 name Name of the directory to be removed.
Returns
0 on success, -1 on error.
 int SysRemoveFile ( const char * name )

Remove a file This function deletes a file.

On a UNIX system, SysRemoveFile() just calls remove(). If the file to be deleted does not exist or cannot be removed for some other reason, run-time error error is generated.

 void SysSetTimeLimit ( long nsecs )

Set CPU time limit.

This function sets a CPU time limit for the calling process. When the limit is exceeded the process is killed.

Parameters
 nsecs CPU time limit in seconds.
Attention
This function is not available on all platforms.
 long SysTimeUsed ( void )

CPU time.

This function returns the CPU time used by the calling process in units of 1/10 seconds.

SysSetTimeLimit()
Returns
CPU time used.
 int SysWriteLong32 ( FILE * f, const long * buf, int n )

Write long integers.

This function writes n long integers from the the array buf to the file f. buf must point to a memory area of at least n*sizeof(long) bytes and f must be open for writing. The numbers are written in a machine-independent format which can be read by SysReadLong().

Parameters
 f File to write to. buf Pointer to buffer. n Number of integers to write.
Returns
Number of integers that were written, or $-1$ on error.

MeatAxe 2.4 documentation, generated on Wed Jan 7 2015 08:38:36