United States    
COMPAQ
Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


ceil

Returns (as a double ) the smallest integer that is greater than or equal to its argument.

Format

#include <math.h>

double ceil (double x);


Argument

x

A real value.

Return Values

x The smallest integer greater than or equal to the function argument.

cfree

Makes available for reallocation the area allocated by a previous calloc , malloc , or realloc call. This function is AST-reentrant.

Format

#include <stdlib.h>

void cfree (void *ptr);


Argument

ptr

The address returned by a previous call to malloc , calloc , or realloc .

Description

The contents of the deallocated area are unchanged.

In Compaq C for OpenVMS Systems, the free and cfree functions are equivalent. Some other C implementations use free with malloc or realloc , and cfree with calloc . However, since the ANSI C standard does not include cfree , using free may be preferable.

See also free in this section.


chdir

Changes the default directory.

Format

#include <unistd.h>

int chdir (const char *dir_spec); (ISO POSIX-1)

int chdir (const char *dir_spec, ...); (DEC C EXTENSION)


Argument

dir_spec

A null-terminated character string naming a directory in either an OpenVMS or UNIX style specification.

...

This argument is a Compaq C extension available when not defining any of the standards-related feature-test macros (see Section 1.5 and not compiling in strict ANSI C mode (/STANDARD=ANSI89). The argument is an optional flag of type int that is significant only when calling chdir from USER mode.

If the value of the flag is 1, the new directory is effective across images. If the value is not 1, the original default directory is restored when the image exits.


Description

This function changes the default directory. The change can be permanent or temporary. Permanent means that the new directory remains as the default directory after the image exits. Temporary means that on image exit, the default is set to whatever it was before the execution of the image.

There are two ways of making the change permanent:

Otherwise, the change is temporary.


Return Values

0 Indicates that the directory is successfully changed to the given name.
--1 Indicates that the change attempt has failed.

chmod

Changes the file protection of a file.

Format

#include <stat.h>

int chmod (const char *file_spec, mode_t mode);


Arguments

file_spec

The name of an OpenVMS or UNIX style file specification.

mode

A file protection. Modes are constructed by performing a bitwise OR on any of the values shown in Table REF-2.

Table REF-2 File Protection Values and Their Meanings
Value Privilege
0400 OWNER:READ
0200 OWNER:WRITE
0100 OWNER:EXECUTE
0040 GROUP:READ
0020 GROUP:WRITE
0010 GROUP:EXECUTE
0004 WORLD:READ
0002 WORLD:WRITE
0001 WORLD:EXECUTE

When you supply a mode value of 0, the chmod function gives the file the user's default file protection.

The system is given the same privileges as the owner. A WRITE privilege also implies a DELETE privilege.


Description

You must have a WRITE privilege for the file specified to change the mode.

Return Values

0 Indicates that the mode is successfully changed.
--1 Indicates that the change attempt has failed.

chown

Changes the owner user identification code (UIC) of the file.

Format

#include <unistd.h>

int chown (const char *file_spec, uid_t owner, gid_t group);


Arguments

file_spec

The address of an ASCII file name.

owner

An integer corresponding to the new owner UIC of the file.

group

An integer corresponding to the group UIC of the file.

Return Values

0 Indicates success.
--1 Indicates failure.

[w]clear

Erase the contents of the specified window and reset the cursor to coordinates (0,0). The clear function acts on the stdscr window.

Format

#include <curses.h>

int clear();

int wclear (WINDOW *win);


Argument

win

A pointer to the window.

Return Values

OK Indicates success.
ERR Indicates an error.

clearerr

Resets the error and end-of-file indicators for a file (so that ferror and feof will not return a nonzero value).

Format

#include <stdio.h>

void clearerr (FILE *file_ptr);


Argument

file_ptr

A file pointer.

clearok

Sets the clear flag for the window.

Format

#include <curses.h>

clearok (WINDOW *win, bool boolf);


Arguments

win

The entire size of the terminal screen. You can use the windows stdscr and curscr with clearok .

boolf

A Boolean value of TRUE or FALSE. If the argument is TRUE, this forces a clearscreen to be printed on the next call to refresh , or stops the screen from being cleared if boolf is FALSE.

The type bool is defined in the <curses.h> header file as follows:


#define bool int 


Description

Unlike the clear function, the clearok function does not alter the contents of the window. If the win argument is curscr , the next call to refresh causes a clearscreen, even if the window passed to refresh is not a window the size of the entire terminal screen.

clock

Determines the CPU time (in 10-millisecond units) used since the beginning of the process. The time reported is the sum of the user and system times of the calling process and any terminated child processes for which the calling process has executed wait or system .

Format

#include <time.h>

clock_t clock (void);


Description

The value returned by the clock function must be divided by the value of the CLK_TCK, as defined in the standard header file <time.h> , to obtain the time in seconds.

The type clock_t is defined in the <time.h> header file as follows:


typedef long int clock_t; 

Only the accumulated times for child processes running a C main program or a program that calls VAXC$CRTL_INIT or DECC$CRTL_INIT are included.

A typical usage of the clock function is to call it after a program does its initial setup, and then again after the program executes the code to be timed. Then subtract the two values to give elapsed CPU time.


Return Values

n The processor time used.
--1 Indicates that the processor time used is not available.

close

Closes the file associated with a file descriptor.

Format

#include <unistd.h>

int close (int file_desc);


Argument

file_desc

A file descriptor.

Description

This function tries to write buffered data by using an implicit call to fflush . If the write fails (because the disk is full or the user's quota was exceeded, for example), close continues executing. It closes the VMS channel, deallocates any buffers, and releases the memory associated with the file descriptor (or FILE pointer). Any buffered data is lost, and the file descriptor (or FILE pointer) no longer refers to the file.

If your program needs to recover from errors when flushing buffered data, it should make an explicit call to fsync (or fflush ) before calling close .


Return Values

0 Indicates that the file is properly closed.
--1 Indicates that the file descriptor is undefined or an error occurred while the file was being closed (for example, if the buffered data cannot be written out).

Example


 
#include <unistd.h> 
 
int fd; 
   .
   .
   .
fd = open ("student.dat", 1); 
   .
   .
   .
close(fd); 


closedir

Closes directories.

Format

#include <dirent.h>

int closedir (DIR *dir_pointer);


Argument

dir_pointer

Pointer to the dir structure of an open directory.

Description

This function closes a directory stream and frees the structure associated with the dir_pointer argument. Upon return, the value of dir_pointer does not necessarily point to an accessible object of the type DIR .

The type DIR , which is defined in the <dirent.h> header file, represents a directory stream that is an ordered sequence of all the directory entries in a particular directory. Directory entries represent files. You can remove files from or add files to a directory asynchronously to the operation of the readdir function.

Note

An open directory must always be closed with the closedir function to ensure that the next attempt to open the directory is successful.

Example

The following example shows how to search a directory for the entry name, using the opendir , readdir , and closedir functions:


#include <dirent.h> 
#include <stdio.h> 
#include <stdlib.h> 
#include <string.h> 
 
#define FOUND     1 
#define NOT_FOUND 0 
 
static int dirent_example(const char *name, unsigned int unix_style) 
{ 
    DIR *dir_pointer; 
    struct dirent *dp; 
 
    if ( unix_style ) 
        dir_pointer = opendir("."); 
    else 
        dir_pointer = opendir(getenv("PATH")); 
 
    if ( !dir_pointer ) { 
        perror("opendir"); 
        return NOT_FOUND; 
    } 
 
    /* Note, that if opendir() was called with Unix-style file  */ 
    /* spec like ".", readdir() will return only a single       */ 
    /* version of each file in the directory. In this case the  */ 
    /* name returned in d_name member of the dirent structure   */ 
    /* will contain only file name and file extension fields,   */ 
    /* both lowercased like "foo.bar".                          */ 
   
    /* If opendir() was called with VMS-style file spec,        */ 
    /* readdir() will return every version of each file in the  */ 
    /* directory. In this case the name returned in d_name      */ 
    /* member of the dirent structure will contain file name,   */ 
    /* file extension and file version fields. All in upper     */ 
    /* case, like "FOO.BAR;1".                                  */ 
 
    for ( dp = readdir(dir_pointer); 
          dp && strcmp(dp->d_name, name); 
          dp = readdir(dir_pointer) ) 
        ; 
 
    closedir(dir_pointer); 
 
    if ( dp != NULL ) 
        return FOUND; 
    else 
        return NOT_FOUND; 
} 
 
int main(void) 
{ 
   char *filename = "foo.bar"; 
   FILE *fp; 
 
   remove(filename); 
 
   if ( !(fp = fopen(filename, "w")) ) { 
        perror("fopen"); 
        return (EXIT_FAILURE); 
   } 
 
   if ( dirent_example( "FOO.BAR;1", 0 ) == FOUND ) 
        puts("VMS style: found"); 
   else 
        puts("VMS style: not found"); 
 
   if ( dirent_example( "foo.bar", 1 ) == FOUND ) 
        puts("Unix style: found"); 
   else 
        puts("Unix style: not found"); 
 
   fclose(fp); 
   remove(filename); 
   return( EXIT_SUCCESS ); 
} 


Return Values

0 Indicates success.
--1 Indicates an error and is further specified in the global errno .

[w]clrattr

Deactivate the video display attribute attr within the window. The clrattr function acts on the stdscr window.

Format

#include <curses.h>

int clrattr (int attr);

int wclrattr (WINDOW *win, int attr);


Arguments

win

A pointer to the window.

attr

Video display attributes that can be blinking, boldface, reverse video, and underlining; they are represented by the defined constants _BLINK, _BOLD, _REVERSE, and _UNDERLINE. To clear multiple attributes, separate them with a bitwise OR operator (|) as follows:


clrattr(_BLINK | _UNDERLINE); 


Description

These functions are specific to Compaq C for OpenVMS Systems and are not portable.

Return Values

OK Indicates success.
ERR Indicates an error.

[w]clrtobot

Erase the contents of the window from the current position of the cursor to the bottom of the window. The clrtobot function acts on the stdscr window.

Format

#include <curses.h>

int clrtobot();

int wclrtobot (WINDOW *win);


Argument

win

A pointer to the window.

Return Values

OK Indicates success.
ERR Indicates an error.

[w]clrtoeol

Erase the contents of the window from the current cursor position to the end of the line on the specified window. The clrtoeol function acts on the stdscr window.

Format

#include <curses.h>

int clrtoeol();

int wclrtoeol (WINDOW *win);


Argument

win

A pointer to the window.

Return Values

OK Indicates success.
ERR Indicates an error.

confstr

Determines the current value of a specified system variable defined by a string value.

Format

#include <unistd.h>

size_t confstr (int name, char *buf, size_t len);


Arguments

name

The system variable setting. Valid values for the name argument are the _CS_X names defined in the <unistd.h> header file.

buf

Pointer to the buffer where the confstr function copies the name value.

len

The size of the buffer storing the name value.

Description

This function allows an application to determine the current setting of certain system parameters, limits, or options that are defined by a string value. The function is mainly used by applications to find the system default value for the PATH environment variable.

If the following conditions are true, then the confstr function copies that value into a len-byte buffer pointed to by buf:

If the returned string is longer than len bytes, including the terminating null, then the confstr function truncates the string to len --1 bytes and adds a terminating null to the result. The application can detect that the string was truncated by comparing the value returned by the confstr function with the value of the len argument.

The <limits.h> header file contains system-defined limits. The <unistd.h> header file contains system-defined environmental variables.


Example

To find out how big a buffer is needed to store the string value of name, enter:


 confstr(_CS_PATH, NULL, (size_t) 0) 

The confstr function returns the size of the buffer necessary.


Return Values

0 Indicates an error. When the specified name value:
  • Is invalid, errno is set to EINVAL.
  • Does not have a system-defined value, errno is not set.
n The size of the buffer needed to hold the value.
  • When the value of the name argument is system-defined, confstr returns the size of the buffer needed to hold the entire value. If this return value is greater than the len value, the string returned as the buf value is truncated.
  • When the value of the len argument is set to 0 or the buf value is NULL, confstr returns the size of the buffer needed to hold the entire system-defined value. The string value is not copied.


Previous Next Contents Index
  

1.800.AT.COMPAQ

privacy and legal statement