HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous Contents Index

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

The close 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 OpenVMS 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

The closedir 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 dir_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 OpenVMS 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 ( dir_example( "FOO.BAR;1", 0 ) == FOUND ) 
        puts("OpenVMS style: found"); 
   else 
        puts("OpenVMS style: not found"); 
 
   if ( dir_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 HP 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

The confstr 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.

conj (ALPHA, I64)

Returns the complex conjugate of its argument.

Format

#include <complex.h>

double complex conj (double complex z);

float complex conjf (float complex z);

long double complex conjl (long double complex z);

Argument

z

A complex value.

Description

The conj functions return the complex conjugate of z, by reversing the sign of its imaginary part.

Return Values

x The complex conjugate value.

copysign (ALPHA, I64)

Returns x with the same sign as y.

Format

#include <math.h>

double copysign (double x, double y);

float copysignf (float x, float y); (ALPHA, I64)

long double copysignl (long double x, long double y); (ALPHA, I64)

Arguments

x

A real value.

y

A real value.

Description

The copysign functions return x with the same sign as y. IEEE 754 requires copysign (x,NaN), copysignf (x,NaN), and copysignl (x,NaN) to return +x or - x.

Return Value

x The value of x with the same sign as y.

cos

Returns the cosine of its radian argument.

Format

#include <math.h>

double cos (double x);

float cosf (float x); (ALPHA, I64)

long double cosl (long double x); (ALPHA, I64)

double cosd (double x); (ALPHA, I64)

float cosdf (float x); (ALPHA, I64)

long double cosdl (long double x); (ALPHA, I64)

Argument

x

A radian expressed as a real value.

Description

The cos functions return the cosine of their argument, measured in radians.

The cosd functions return the cosine of their argument, measured in degrees.

|x| = Infinity is an invalid argument.

Return Values

x The cosine of the argument.
HUGE_VAL Indicates that the argument is too large; errno is set to ERANGE.

cosh

Returns the hyperbolic cosine of its radian argument.

Format

#include <math.h>

double cosh (double x);

float coshf (float x); (ALPHA, I64)

long double coshl (long double x); (ALPHA, I64)

Argument

x

A radian expressed as a real number.

Description

The cosh functions return the hyperbolic cosine of x and are defined as (e**x + e**( - x))/2.

Return Values

x The hyperbolic cosine of the argument.
HUGE_VAL Indicates that the argument is too large; errno is set to ERANGE.

cot

Returns the cotangent of its radian argument.

Format

#include <math.h>

double cot (double x);

float cotf (float x); (ALPHA, I64)

long double cotl (long double x); (ALPHA, I64)

double cotd (double x); (ALPHA, I64)

float cotdf (float x); (ALPHA, I64)

long double cotdl (long double x); (ALPHA, I64)

Argument

x

A radian expressed as a real number.

Description

The cot functions return the cotangent of their argument, measured in radians.

The cotd functions return the cotangent of their argument, measured in degrees.

x = 0 is an invalid argument.

Return Values

x The cotangent of the argument.
HUGE_VAL Indicates that the argument is zero; errno is set to ERANGE.

cpow (ALPHA, I64)

Returns the complex power function x**y.

Format

#include <complex.h>

double complex cpow (double complex x, double complex y);

float complex cpowf (float complex x, float complex y);

long double complex cpowl (long double complex x, long double complex y);

Argument

x

A complex value.

y

A complex value.

Description

The cpow functions return the complex power function x**y, with a branch cut for the first parameter along the negative real axis.

Return Values

x The complex power function value.

cproj (ALPHA, I64)

Returns a projection of its argument onto the Riemann sphere.

Format

#include <complex.h>

double complex cproj (double complex z);

float complex cprojf (float complex z);

long double complex cprojl (long double complex z);

Argument

z

A complex value.

Description

The cproj functions compute and return a projection of z onto the Riemann sphere: z projects to z, except that all complex infinities (even those with one infinite part and one NaN part) project to positive infinity on the real axis. If z has an infinite part, then cproj(z) is equivalent to:

INFINITY + I * copysign (0.0, cimag (z))

Return Values

x The value of the projection onto the Riemann sphere.

creal (ALPHA, I64)

Returns the real part of its complex argument.

Format

#include <complex.h>

double creal (double complex z);

float crealf (float complex z);

long double creall (long double complex z);

Argument

z

A complex value.

Description

The creal functions return the real part of z.

Return Values

x The real part value.

creat

Creates a new file.

Format

#include <fcntl.h>

int creat (const char *file_spec, mode_t mode); (ISO POSIX-1)

int creat (const char *file_spec, mode_t mode, ...); (HP C EXTENSION)

Arguments

file_spec

A null-terminated string containing any valid file specification.

mode

An unsigned value that specifies the file-protection mode. The compiler performs a bitwise AND operation on the mode and the complement of the current protection mode.

You can construct modes by using the bitwise OR operator (|) to create mode combinations. The modes are:
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

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

Note
To create files with OpenVMS RMS default protections using the UNIX system-call functions umask , mkdir , creat , and open , call mkdir , creat , and open with a file-protection mode argument of 0777 in a program that never specifically calls umask . These default protections include correctly establishing protections based on ACLs, previous versions of files, and so on.

In programs that do vfork / exec calls, the new process image inherits whether umask has ever been called or not from the calling process image. The umask setting and whether the umask function has ever been called are both inherited attributes.

...

An optional argument list of character strings of the following form:

"keyword = value",...,"keyword = value"

Or in the case of "acc" or "err", this form:

"keyword"

Here, keyword is an RMS field in the file access block (FAB) or record access block (RAB); value is valid for assignment to that field. Some fields permit you to specify more than one value. In these cases, the values are separated by commas.

The RMS callback keywords "acc" and "err" are the only keywords that do not take values. Instead, they are followed by a pointer to the callback routine to be used, followed by a pointer to a user-specified value to be used as the first argument of the callback routine. For example, to set up an access callback routine called acc_callback whose first argument is a pointer to the integer variable first_arg in a call to open , you can use the following statement: 


open("file.dat", O_RDONLY, 0 ,"acc", acc_callback, &first_arg)

The second and third arguments to the callback routine must be pointers to a FAB and RAB, respectively, and the routine must have a return type of int . If the callback returns a value less than 0, the open , creat , or fopen fails. The error callback can correct the error condition and return a status greater than or equal to 0 to continue the creat call. Assuming the previous open statement, the function prototype for acc_callback would be similar to the following statement: 


#include <rms.h> 
 
int acc_callback(int *first_arg, struct FAB *fab, struct RAB *rab);

FAB and RAB are defined in the <rms.h> header file, and the actual pointers passed to the routine are pointers to the RAB and FAB being used to open the file file.dat.

If an access callback routine is established, then it will be called in the open-type routine immediately before the call to the RMS function sys$create or sys$open. If an error callback routine is established and an error status is returned from the sys$create or sys$open function, then the callback routine will be invoked immediately after the status is checked and the error value is discovered.

Note
Any manipulation of the RAB or FAB in a callback function could lead to serious problems in later calls to the HP C RTL I/O functions.

Table REF-3 describes the RMS keywords and values.

Table REF-3 RMS Valid Keywords and Values
Keyword Value Description
"acc" callback Access callback routine.
"alq = n" decimal Allocation quantity.
"bls = n" decimal Block size.
"ctx = bin" string No translation of '\n' to the terminal. Use this for writing binary data to files.
"ctx = cvt" string Negates a previous setting of "ctx=nocvt". This is the default.
"ctx = nocvt" string No conversion of Fortran carriage-control bytes.
"ctx = rec" string Forces record mode access.
"ctx = stm" string Forces stream mode access.
"ctx = xplct" string Causes records to be written only when explicitly specified by a call to fflush , close , or fclose .
"deq = n" decimal Default extension quantity.
"dna = filespec" string Default file-name string.
"err" callback Error callback routine.
"fop = val, val ,..."   File-processing options:
  ctg
cbt
dfw

dlt
tef
cif
sup
scf
spl
tmd
tmp
nef
rck
wck
mxv
rwo
pos
rwc
sqo 		Contiguous.
Contiguous-best-try.
Deferred write; only applicable to files opened for shared access.
Delete file on close.
Truncate at end-of-file.
Create if nonexistent.
Supersede.
Submit as command file on close.
Spool to system printer on close.
Temporary delete.
Temporary (no file directory).
Not end-of-file.
Read check compare operation.
Write check compare operation.
Maximize version number.
Rewind file on open.
Current position.
Rewind file on close.
File can only be processed in a sequential manner.
"fsz = n" decimal Fixed header size.
"gbc = n" decimal The requested number of global buffers for a file.
"mbc = n" decimal Multiblock count.
"mbf = n" decimal Multibuffer count.
"mrs = n" decimal Maximum record size.
"pmt=usr-prmpt" string Prompts for terminal input. Any RMS input from a terminal device will be preceded by "usr-prmpt" when this option and "rop=pmt" are specified.
"rat = val, val..."   Record attributes:
  cr
blk
ftn
none
prn 		Carriage-return control.
Disallow records to span block boundaries.
Fortran print control.
Explicitly forces no carriage control.
Print file format.
"rfm = val"   Record format:
  fix
stm
stmlf
stmcr

var
vfc
udf 		Fixed-length record format.
RMS stream record format.
Stream format with line-feed terminator.
Stream format with carriage-return terminator.
Variable-length record format.
Variable-length record with fixed control.
Undefined.
"rop = val, val..."   Record-processing operations:
  asy Asynchronous I/O.
  cco Cancels Ctrl/O (used with Terminal I/O).
  cvt Capitalizes characters on a read from the terminal.
  eof Positions the record stream to the end-of-file for the connect operation only.
  nlk Do not lock record.
  pmt Enables use of the prompt specified by "pmt=usr-prmpt" on input from the terminal.
  pta Eliminates any information in the type-ahead buffer on a read from the terminal.
  rea Locks record for a read operation for this process, while allowing other accessors to read the record.
  rlk Locks record for write.
  rne Suppresses echoing of input data on the screen as it is entered on the keyboard.
  rnf Indicates that Ctrl/U, Ctrl/R, and DELETE are not to be considered control commands on terminal input, but are to be passed to the application program.
  rrl Reads regardless of lock.
  syncsts Returns a success status of RMS$_SYNCH if the requested service completes its task immediately.
  tmo Timeout I/O.
  tpt Allows put/write services using sequential record access mode to occur at any point in the file, truncating the file at that point.
  ulk Prohibits RMS from automatically unlocking records.
  wat Wait until record is available, if currently locked by another stream.
  rah Read ahead.
  wbh Write behind.
"rtv=n" decimal The number of retrieval pointers that RMS has to maintain in memory (0 to 127,255).
"shr = val, val, ..."   File sharing options:
  del
get
mse
nil
put
upd
upi
nql 		Allows users to delete.
Allows users to read.
Allows multistream connects.
Prohibits file sharing.
Allows users to write.
Allows users to update.
Allows one or more writers.
No query locking (file level).
"tmo = n" decimal I/O timeout value.

Previous Next Contents Index