United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# Chapter 8
Memory Allocation Functions

Table 8-1 lists and describes all the memory allocation functions found in the Compaq C Run-Time Library (RTL). For a more detailed description of each function, see the Reference Section.

Table 8-1 Memory Allocation Functions
Function | Description
--- | ---
`brk, sbrk` | Determine the lowest virtual address that is not used with the program.
`calloc, malloc` | Allocate an area of memory.
`cfree, free` | Make available for reallocation the area allocated by a previous `calloc` , `malloc` , or `realloc` call.
`realloc` | Changes the size of the area pointed to by the first argument to the number of bytes given by the second argument.
`strdup` | Finds and points to a duplicate string.

All Compaq C RTL functions requiring additional storage from the heap get that storage using the Compaq C RTL memory allocation functions `malloc` , `calloc` , `realloc` , `free` , and `cfree` . Memory allocated by these functions is quadword-aligned.

The ANSI C standard does not include `cfree` . For this reason, it is preferable to free memory using the functionally equivalent `free` function.

The `brk` and `sbrk` functions assume that memory can be allocated contiguously from the top of your address space. However, the `malloc` function and RMS may allocate space from this same address space. You should not use the `brk` and `sbrk` functions in conjunction with RMS and Compaq C RTL routines that use `malloc` .

Previous versions of the VAX C RTL documentation indicated that the memory allocation routines used the OpenVMS RTL functions LIB$GET_VM and LIB$FREE_VM to acquire and return dynamic memory. This is no longer the case; interaction between these routines and the Compaq C RTL memory allocation routines is no longer problematic (although LIB$SHOW_VM can no longer be used to track Compaq C RTL `malloc` and `free` usage).

The Compaq C RTL memory allocation functions `calloc` , `malloc` , `realloc` , and `free` are based on the LIB$ routines LIB$VM_CALLOC, LIB$VM_MALLOC, LIB$VM_REALLOC and LIB$VM_FREE, respectively.

The routines `VAXC$CALLOC_OPT` , `VAXC$CFREE_OPT` , `VAXC$FREE_OPT` , `VAXC$MALLOC_OPT` , and `VAXC$REALLOC_OPT` are now obsolete and should not be used in new development. However, versions of these routines that are equivalent to the standard C memory allocation routines are provided for backward compatibility.

# 8.1 Program Example

Example 8-1 shows the use of the `malloc` , `calloc` , and `free` functions.

Example 8-1 Allocating and Deallocating Memory for Structures

    /*        CHAP_8_MEM_MANAGEMENT.C                               */

    /* This example takes lines of input from the terminal until    */
    /* it encounters a Ctrl/Z, places the strings into an           */
    /* allocated buffer, copies the strings to memory allocated for */
    /* structures, prints the lines back to the screen, and then    */
    /* deallocates all the memory used for the structures.          */

    #include  <stdlib.h>
    #include  <stdio.h>
    #define   MAX_LINE_LENGTH  80

    struct line_rec {               /*  Declare the structure.   */
        struct line_rec *next;      /*  Pointer to next line.    */
        char *data;                 /*  A line from terminal.    */
    };

    int main(void)
    {
        char *buffer;

        /* Define pointers to        */
        /*  structure (input lines). */

        struct line_rec *first_line = NULL,
                *next_line,
                *last_line = NULL;

        /* Buffer points to memory.  */
        buffer = malloc(MAX_LINE_LENGTH);

        if (buffer == NULL) {       /* If error ...  */
            perror("malloc");
            exit(EXIT_FAILURE);
        }

        while (gets(buffer) != NULL) {      /* While not Ctrl/Z ...  */
            /* Allocate for input line.  */
            next_line = calloc(1, sizeof (struct line_rec));

            if (next_line == NULL) {
                perror("calloc");
                exit(EXIT_FAILURE);
            }

            /* Put line in data area.    */
            next_line->data = buffer;

            if (last_line == NULL)  /* Reset pointers.   */
                first_line = next_line;
            else
                last_line->next = next_line;

            last_line = next_line;
            /* Allocate space for the     */
            /*  next input line.          */
            buffer = malloc(MAX_LINE_LENGTH);

            if (buffer == NULL) {
                perror("malloc");
                exit(EXIT_FAILURE);
            }
        }
        free(buffer);       /* Last buffer always unused. */
        next_line = first_line;     /* Pointer to beginning.  */

        while (next_line != NULL) {
            puts(next_line->data);  /* Write line to screen.  */
            free(next_line->data);  /* Deallocate a line.     */
            last_line = next_line;
            next_line = next_line->next;
            free(last_line);
        }

        exit(EXIT_SUCCESS);
    }

The sample input and output for Example 8-1 are as follows:

    $ RUN  EXAMPLE
    line one
    line two
    [Ctrl/Z]
    EXIT
    line one
    line two
    $

# Chapter 9
System Functions

The C programming language is a good choice if you wish to write operating systems. For example, much of the UNIX operating system is written in C. When writing system programs, it is sometimes necessary to retrieve or modify the environment in which the program is running. This chapter describes the Compaq C Run-Time Library (RTL) functions that accomplish this and other system tasks.

Table 9-1 lists and describes all the system functions found in the Compaq C RTL. For a more detailed description of each function, see the Reference Section.

Table 9-1 System Functions
Function | Description
--- | ---
System Functions---Searching and Sorting Utilities
`bsearch` | Performs a binary search on an array of sorted objects for a specified object.
`qsort` | Sorts an array of objects in place by implementing the quick-sort algorithm.
System Functions---Retrieving Process Information
`ctermid` | Returns a character string giving the equivalence string of SYS$COMMAND, which is the name of the controlling terminal.
`cuserid` | Returns a pointer to a character string containing the name of the user who initiated the current process.
`getcwd` | Returns a pointer to the file specification for the current working directory.
`getegid` , `geteuid` , `getgid` , `getuid` | Returns, in OpenVMS terms, group and member numbers from the user identification code (UIC).
`getenv` | Searches the environment array for the current process and returns the value associated with a specified environment.
`getlogin` | Gets the login name of the user associated with the current session.
`getpid` | Returns the process ID of the current process.
`getppid` | Returns the parent process ID of the calling process.
`getpwnam` | Accesses user-name information in the user database.
`getpwuid` | Accesses user-ID information in the user database.
System Functions---Changing Process Information
`chdir` | Changes the default directory.
`chmod` | Changes the file protection of a file.
`chown` | Changes the owner user identification code (UIC) of a file.
`mkdir` | Creates a directory.
`nice` | Increases or decreases the process priority to the process base priority by the amount of the argument.
`putenv` | Sets an environmental variable.
`setenv` | Inserts or resets the environment variable name in the current environment list.
`setgid, setuid` | Implemented for program portability and have no functionality.
`sleep` , `usleep` | Suspends the execution of the current process for at least the number of seconds indicated by its argument.
`umask` | Creates a file protection mask that is used whenever a new file is created. It returns the old mask value.
System Functions---Retrieving and Converting Date/Time Information
`asctime` | Converts a broken-down time into a 26-character string.
`clock` | Determines the CPU time (in microseconds) used since the beginning of the program execution.
`ctime` | Converts a time, in seconds, to an ASCII string in the form generated by the `asctime` function.
`decc$fix_time` | Converts OpenVMS binary system times to UNIX binary times.
`difftime` | Computes the difference, in seconds, between the two times specified by its arguments.
`ftime` | Returns the elapsed time since 00:00:00, January 1, 1970, in the structure `timeb` .
`getclock` | Gets the current value of the system-wide clock.
`getdate` | Converts a formatted string to a time/date structure.
`getitimer` | Returns the value of interval timers.
`gettimeofday` | Gets date and time.
`gmtime` | Converts time units to broken-down UTC time.
`localtime` | Converts a time (expressed as the number of seconds elapsed since 00:00:00, January 1, 1970) into hours, minutes, seconds, and so on.
`mktime` | Converts a local-time structure into time since the Epoch.
`setitimer` | Sets the value of interval timers.
`strftime, wcsftime` | Places characters into an array, as controlled by a specified format string.
`strptime` | Converts a character string into date and time values.
`time` | Returns the time elapsed since 00:00:00, January 1, 1970, in seconds.
`times` | Returns the accumulated times of the current process and of its terminated child processes.
`tzset` | Sets and accesses time-zone conversion.
`ualarm` | Sets or changes the timeout of interval timers.
`wcsftime` | Uses date and time information stored in a `tm` structure to create a wide-character output string.
System Functions---Miscellaneous
`VAXC$CRTL_INIT` | Initializes the run-time environment and establishes an exit and condition handler, which makes it possible for Compaq C RTL functions to be called from other languages.

Example 9-1 shows how the `cuserid` function is used.

Example 9-1 Accessing the User Name

    /*        CHAP_9_GET_USER.C                                   */

    /* Using cuserid, this program returns the user name.         */

    #include <stdio.h>

    main()
    {
        static char string[L_cuserid];

        cuserid(string);
        printf("Initiating user: %s\n", string);
    }

If a user named TOLLIVER runs the program, the following is displayed on stdout:

    $ RUN  EXAMPLE1
    Initiating user: TOLLIVER

Example 9-2 shows how the `getenv` function is used.

Example 9-2 Accessing Terminal Information

    /*        CHAP_9_GETTERM.C                              */

    /* Using getenv, this program returns the terminal.     */

    #include <stdio.h>
    #include <stdlib.h>

    main()
    {
        printf("Terminal type: %s\n", getenv("TERM"));
    }

Running Example 9-2 on a Compaq VT100 terminal in 132-column mode displays the following:

    $ RUN  EXAMPLE3
    Terminal type: vt100-132

Example 9-3 shows how to use `getenv` to find the user's default login directory and how to use `chdir` to change to that directory.

Example 9-3 Manipulating the Default Directory

    /*       CHAP_9_CHANGE_DIR.C                                    */

    /* This program performs the equivalent of the DCL command      */
    /* SET DEFAULT SYS$LOGIN. However, once the program exits, the  */
    /* directory is reset to the directory from which the program   */
    /* was run.                                                     */

    #include <stdio.h>
    #include <unistd.h>
    #include <stdlib.h>

    main()
    {
        char *dir;
        int i;

        dir = getenv("HOME");
        if ((i = chdir(dir)) != 0) {
            perror("Cannot set directory");
            exit(0);
        }

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

Running Example 9-3 displays the following:

    $ RUN EXAMPLE4
    Current directory: dba0:[tolliver]
    $

Example 9-4 shows how to use the `time` , `localtime` , and `strftime` functions to print the correct date and time at the terminal.

Example 9-4 Printing the Date and Time

    /*        CHAP_9_DATE_TIME.C                                    */

    /* The time function returns the time in seconds; the localtime */
    /* function converts the time to hours, minutes, and so on;     */
    /* the strftime function uses these values to obtain a string   */
    /* in the desired format.                                       */

    #include <time.h>
    #include <stdio.h>

    #define MAX_STRING 80

    main()
    {
        struct tm *time_structure;
        time_t time_val;
        char output_str[MAX_STRING];

        time(&time_val);
        time_structure = localtime(&time_val);

        /* Print the date  */

        strftime(output_str, MAX_STRING,
                 "Today is %A, %B %d, %Y", time_structure);

        printf("%s\n", output_str);

        /* Print the time using a 12-hour clock format. */

        strftime(output_str, MAX_STRING,
                 "The time is %I:%M %p", time_structure);

        printf("%s\n", output_str);
    }

Running Example 9-4 displays the following:

    $ RUN  EXAMPLE5
    Today is Thursday, May 20, 1993
    The time is 10:18 AM
    $

Previous | Next | Contents | Index

privacy and legal statement