Watcom C Library : main, _makepath, malloc Functions, matherr

 

 

Watcom C Library Reference : main, _makepath, malloc Functions, matherr

 

 

 

 

main

 

Synopsis : int main( void ); 

              int main( int argc, const char *argv[ ] );

 

Description : The function main is a user-supplied function where program execution begins. The command line to the program is broken into a sequence of tokens separated by blanks and are passed to main as an array of pointers to character strings in the parameter argv. The number of arguments found is passed in the parameter argc.

 

The first element of argv will be a pointer to a character string containing the program name. The last element of the array pointed to by argv will be a NULL pointer (i.e. argv[argc] will be NULL). Arguments that contain blanks can be passed to main by enclosing them within double quote characters (which are removed from that element in the argv vector.

The command line arguments can also be obtained in its original format by using the getcmd function.

 

 

Returns : The function main returns a return code back to the calling program (usually the operating system)

 

 

See Also : abort, atexit, _bgetcmd, exec Functions, exit, _exit, getcmd, getenv, onexit, putenv, spawn Functions, system

 

Example :

#include <stdio.h>

int main( int argc, char *argv[ ] )

{
    int     i;

   

    for( i = 0; i < argc; ++i) {
        printf( "argv[ %d] = %s\n", i, argv[i] );

    }
    return( 0 );

}

 

produces the following :
argv[0] = C:\WATCOM\DEMO\MYPGM.EXE 

argv[1] = hhhhh 

argv[2] = another arg

when the program mypgm is executed with the command
mypgm hhhhh "another arg"

 

Classification : ANSI
Systems : All

 

 

 

 

 

_makepath

 

Synopsis : #include <stdlib.h> 

              void makepath( char *path,
                                  const char *drive,

                                  const char *dir,

                                  const char *fname,

                                  const char *ext );


Description : The _makepath function constructs a full pathname from the components consisting of a drive letter, directory path, file name and file name extension. The full pathname is placed in the buffer pointed to by the argument path.

 

The maximum size required for each buffer is specified by the manifest constants _MAX_PATH, _MAX_DRIVE, _MAX_DIR, _MAX_FNAME, and _MAX_EXT which are defined in <stdlib.h>.

 

drive	The drive argument points to a buffer containing the drive letter (A, B, C, etc.) followed by an optional colon. The _makepath function will automatically insert a colon in the full pathname if it is missing. If drive is a NULL pointer or points to an empty string, no drive letter or colon will be placed in the full pathname.
dir	The dir argument points to a buffer containing just the pathname. Either forward slashes (/) or backslashes (\) may be used. The trailing slash is optional. The _makepath function will automatically insert a trailing slash in the full pathname if it is missing. If dir is a NULL pointer or points to an empty string, no slash will be placed in the full pathname.
fname	The fname argument points to a buffer containing the base name of the file without any extension (suffix).
ext	The ext argument points to a buffer containing the filename extension or suffix. A leading period (.) is optional. The _makepath routine will automatically insert a period in the full pathname if it is missing. If ext is a NULL pointer or points to an empty string, no period will be placed in the full pathname.

 

Returns : The _makepath function returns no value.

 

 

See Also : _fullpath, _splitpath

 

Example :

#include <stdio.h> 

#include <stdlib.h>

void main( )

{
    char     full_path[ _MAX_PATH ];

    char     drive[ _MAX_DRIVE ];

    char     dir[ _MAX_DIR ];

    char     fname[ _MAX_FNAME ];

    char     ext[ _MAX_EXT ];

    _makepath( full-path, "c", "watcomc\\h\\", "stdio","h");

    printf( "Full path is : %s\n\n", full_path);

 

    _splitpath( full_path, drive, dir, fname, ext );

    printf( "Components after _splitpath\n" );

    printf( "drive :   %s\n", drive );

    printf( "dir:       %s\n", dir );

    printf( "fname : %s\n", fname);

    printf( "ext :      %s\n", ext );

}

 

produces the following :
Full path is : c:watcomc\h\stdio.h

Components after _splitpath 

drive :   c: 

dir :      watcomc\h\

fname : stdio

ext :      .h

 

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single backslash.

 

Classification : WATCOM
Systems : All

 

 

 

 

 

malloc Functions

 

Synopsis : #include <stdlib.h>   For ANSI compatibility (malloc only)

              #include <malloc.h> Required for other function prototypes

              void *malloc( size_t size );

              void __based (void) *_bmalloc( __segment seg, size_t size );

              void __far *_fmalloc( size_t size );

              void __near *_nmalloc( size_t size );

 

Description : The malloc functions allocate space for an object of size bytes. Nothing is allocated when the size argument has a value of zero.

Each function allocates memory from a particular heap, as listed below:

Function	Heap
malloc	Depends on data model of the program
_bmalloc	Based heap specified by seg value
_fmalloc	Far heap (outside the default data segment)
_nmalloc	Near heap (inside the default data segment)

In a small data memory model, the malloc function is equivalent to the _nmalloc function; in a large data memory model, the malloc function is equivalent to the _fmalloc function.

 

Returns : The malloc functions return a pointer to the start of the allocated memory. The malloc, _fmalloc and _nmalloc functions return NULL if there is insufficient memory available or if the requested size is zero. The _bmalloc function returns _NULLOFF if there is insufficient memory available or if the requested size is zero.

 

 

See Also : calloc Functions, _expand Functions, free Functions, halloc, hfree, _msize Functions, realloc Functions, sbrk

 

Example :

void main( )

{
    char     *buffer;

 

    buffer = (char *) malloc( 80 );

    if( buffer != NULL ) {
        /* body of program */
        free( buffer );

    }

}

 

Classification : malloc is ANSI; _bmalloc, _fmalloc, _nmalloc are not ANSI
Systems : malloc - All

             _bmalloc - DOS/16, Win/16, QNX/16, OS/2 1.x(all)

             _fmalloc - DOS/16, Win/16, QNX/16, OS/2 1.x(all)

             _nmalloc - DOS, Win, QNX, OS/2 1.x, OS/2 1.x(MT), OS/2 2.x, NT

 

 

 

 

 

matherr

 

Synopsis : #include <math.h> 

              int matherr( struct exception *err_info );

 

Description : The matherr function is invoked each time an error is detected by functions in the math library. The default matherr function supplied in the library returns zero which causes an error message to be displayed upon stderr and errno to be set with an appropriate error value. An alternative version of this function can be provided, instead of the library version, in order that the error handling for mathematical errors can be handled by an application.

A program may contain a user-written version of matherr to take any appropriate action when an error is detected. When zero is returned, an error message will be printed upon stderr and errno will be set as was the case with the default function. When a non-zero value is returned, no message is printed and errno is not changed. The value err_info->retval is used as the return value for the function in which the error was detected.

The matherr function is passed a pointer to a structure of type struct exception which contains information about the error that has been detected:

 

struct exception { 

    int        type;      /* TYPE OF ERROR                          */

    char     *name;    /* NAME OF FUNCTION                       */

    double   arg1;     /* FIRST ARGUMENT TO FUNCTION          */

    double   arg2;     /* SECOND ARGUMENT TO FUNCTION      */

    double   retval;    /* DEFAULT RETURN VALUE                  */

};

The type field will contain one of the following values:

Value	Meaning
DOMAIN	A domain error has occurred, such as sqrt(-1e0).
SING	A singularity will result, such as pow(0e0, -2).
OVERFLOW	An overflow will result, such as pow(10e0, 100).
UNDERFLOW	An underflow will result, such as pow(10e0, -100).
TLOSS	Total loss of significance will result, such as exp(1000).
PLOSS	Partial loss of significance will result, such as sin(10e70).

The name field points to a string containing the name of the function which detected the error. The fields arg1 and arg2 (if required) give the values which caused the error. The field retval contains the value which will be returned by the function. This value may be changed by a user-supplied version of the matherr function.

 

 

Returns : The matherr function returns zero when an error message is to be printed and a non-zero value otherwise.

 

 

Example :

#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 

#include <math.h>

/* Demonstrate error routine in which negative */ 

/* arguments to "sqrt" are treated as positive */

void main( )

{
    printf("%e\n", sqrt( -5e0 ) );

    exit( 0 );

}

 

int matherr( struct exception *err )

{
    if ( strcmp( err->name, "sqrt" ) == 0 ) {

        if( err->type == DOMAIN ) {
            err->retval = sqrt( -(err->arg1) );
            return( 1 );

        } else {
            return( 0 );

        }

    } else {
        return( 0 );

    }

}

 

Classification : WATCOM
Systems : All

 

 

 

 

 

 

 

 

 

This manual describes the WATCOM C library for DOS, Windows, and OS/2, It includes the Standard C Library (as defined in the ANSI C Standard).

 

WATCOM C Language Reference manual describes the ANSI C Programming language and extensions to it which are supported by WATCOM C/C++ (32bit)