HP C
Run-Time Library Reference Manual for OpenVMS Systems


Previous Contents Index


realloc

Changes the size of the area pointed to by the first argument to the number of bytes given by the second argument. These functions are AST-reentrant.

Format

#include <stdlib.h>

void *realloc (void *ptr, size_t size);

Function Variants The realloc function has variants named _realloc32 and _realloc64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

ptr

Points to an allocated area, or can be NULL.

size

The new size of the allocated area.

Description

If ptr is the NULL pointer, the behavior of the realloc function is identical to the malloc function.

The contents of the area are unchanged up to the lesser of the old and new sizes. The ANSI C Standard states that, "If the new size is larger than the old size, the value of the newly allocated portion of memory is indeterminate." For compatibility with old implementations, HP C initializes the newly allocated memory to 0.

For efficiency, the previous actual allocation could have been larger than the requested size. If it was allocated with malloc , the value of the portion of memory between the previous requested allocation and the actual allocation is indeterminate. If it was allocated with calloc , that same memory was initialized to 0. If your application relies on realloc initializing memory to 0, then use calloc instead of malloc to perform the initial allocation. The maximum amount of memory allocated at once is limited to 0xFFFFD000.

See also free , cfree , calloc , and malloc .


Return Values

x The address of the area, quadword-aligned (ALPHA ONLY) or octaword-aligned (INTEGRITY SERVERS ONLY) . The address is returned because the area may have to be moved to a new address to reallocate enough space. If the area was moved, the space previously occupied is freed.
NULL Indicates that space cannot be reallocated (for example, if there is not enough room).

realpath

Returns an absolute pathname from the POSIX root.

Format

#include <stdlib.h>

char realpath (const char *restrict file_name, char *restrict resolved_name);


Arguments

file_name

Pointer to the text string representing the name of the file for which you want the absolute path.

resolved name

Pointer to the generated absolute path stored as a null-terminated string.

Description

The realpath function returns an absolute pathname from the POSIX root. The generated pathname is stored as a null-terminated string, up to a maximum of PATH_MAX bytes, in the buffer pointed to by resolved_name.

The realpath function is supported only in POSIX-compliant modes (that is, with DECC$POSIX_COMPLIANT_PATHNAMES defined to one of the allowed values).

See also symlink , unlink , readlink , lchown , and lstat .


Return Values

x Upon successful completion, a pointer to the resolved_name.
NULL Indicates an error. A null pointer is returned, the contents of the buffer pointed to by resolved_name are undefined, and errno is set to indicate the error:
  • ENAMETOOLONG -- The length of the file_name argument exceeds PATH_MAX, or a pathname component is longer than NAME_MAX.
  • ENOENT -- A component of file_name does not name an existing file, or file_name points to an empty string.
  • Any errno value from chdir or stat .

[w]refresh

Repaint the specified window on the terminal screen. The refresh function acts on the stdscr window.

Format

#include <curses.h>

int refresh();

int wrefresh (WINDOW *win);


Argument

win

A pointer to the window.

Description

The result of this process is that the portion of the window not occluded by subwindows or other windows appears on the terminal screen. To see the entire occluded window on the terminal screen, call the touchwin function instead of the refresh or wrefresh function.

See also touchwin .


Return Values

OK Indicates success.
ERR Indicates an error.

remainder (INTEGRITY SERVERS, ALPHA)

Returns the floating-point remainder r = x - n*y) when y is nonzero.

Format

#include <math.h>

double remainder (double x, double y);

float remainderf (float x, float y);

long double remainderl (long double x, long double y);


Argument

x

A real number.

y

A real number.

Description

These functions return the floating-point remainder r = x - n*y) when y is nonzero. The value n is the integral value nearest the exact value x/y. That is, n = rint (x/y).

When |n - x/y| = 1/2 , the value n is chosen to be even.

The behavior of the remainder function is independent of the rounding mode.

The remainder functions are functionally equivalent to the remquo functions.


Return Values

r Upon successful completion, these functions return the floating-point remainder r = x - ny when y is nonzero.
Nan If x or y is Nan.

remquo (INTEGRITY SERVERS, ALPHA)

Returns the floating-point remainder r = x - n*y) when y is nonzero.

Format

#include <math.h>

double remquo (double x, double y, int * quo);

float remquof (float x, float y, int * quo);

long double remquol (long double x, long double y, int * quo);


Argument

x

A real number.

y

A real number.

quo


Description

The remquo(), remquof(), and remquol() functions compute the same remainder as the remainder(), remainderf(), and remainderl() functions, respectively. In the object pointed to by quo, they store a value whose sign is the sign of x/y and whose magnitude is congruent modulo 2n to the magnitude of the integral quotient of x/y, where n is an implementation-defined integer greater than or equal to 3.

The remquo functions are functionally equivalent to the remainder functions.


Return Values

r Upon successful completion, these functions return the floating-point remainder r = x - ny when y is nonzero.
Nan If x or y is Nan.

remove

Deletes a file.

Format

#include <stdio.h>

int remove (const char *file_spec);


Argument

file_spec

A pointer to the string that is an OpenVMS or a UNIX style file specification. The file specification can include a wildcard in its version number. So, for example, files of the form filename.txt;* can be deleted.

Description

If you specify a directory in the filename and it is a search list that contains an error, HP C for OpenVMS Systems interprets it as a file error.

Note

The DECC$ALLOW_REMOVE_OPEN_FILES feature logical controls the behavior of the remove function on open files. Ordinarily, the operation fails. However, POSIX conformance dictates that the operation succeed.

With DECC$ALLOW_REMOVE_OPEN_FILES enabled, this POSIX conformant behavior is achieved.

When remove is used to delete a symbolic link, the link itself is deleted, not the file to which it refers.

The remove and delete functions are functionally equivalent in the HP C RTL.

See also delete .


Return Values

0 Indicates success.
nonzero value Indicates failure.

rename

Gives a new name to an existing file.

Format

#include <stdio.h>

int rename (const char *old_file_spec, const char *new_file_spec);


Arguments

old_file_spec

A pointer to a string that is the existing name of the file to be renamed.

new_file_spec

A pointer to a string that is to be the new name of the file.

Description

If you try to rename a file that is currently open, the behavior is undefined. You cannot rename a file from one physical device to another. Both the old and new file specifications must reside on the same device.

If the new_file_spec does not contain a file extension, the file extension of old_file_spec is used. To rename a file to have no file extension, new_file_spec must contain a period (.) For example, the following renames SYS$DISK:[]FILE.DAT to SYS$DISK:[]FILE1.DAT:


rename("file.dat", "file1"); 

However, the following renames SYS$DISK:[]FILE.DAT to SYS$DISK:[]FILE1:


rename("file.dat", "file1."); 

Note

Because the rename function does special processing of the file extension, the caller must be careful when specifying the name of the renamed file in a call to a C Run-Time Library function that accepts a file-name argument. For example, after the following call to the rename function, the new file should be opened as fopen("bar.dat",...) :


rename("foo.dat", "bar"); 

The rename function is affected by the setting of the DECC$RENAME_NO_INHERIT and DECC$RENAME_ALLOW_DIR feature logicals as follows:

See the DECC$RENAME_NO_INHERIT and DECC$RENAME_ALLOW_DIR descriptions in Section 1.5 for more information.


Return Values

0 Indicates success.
- 1 Indicates failure. The function sets errno to one of the following values:
  • EISDIR -- The new argument points to a directory, and the old argument points to a file that is not a directory.
  • EEXIST -- The new argument points to a directory that already exists.
  • ENOTDIR -- The old argument names a directory, and new argument names a non-directory file.
  • ENOENT -- The old argument points to a file, directory, or device that does not exist.

    Or the new argument points to a nonexisting directory path or device.


rewind

Sets the file to its beginning.

Format

#include <stdio.h>

void rewind (FILE *file_ptr); (ISO POSIX-1)

int rewind (FILE *file_ptr); (HP C EXTENSION)


Argument

file_ptr

A file pointer.

Description

The rewind function is equivalent to fseek (file_ptr, 0, SEEK_SET) . You can use the rewind function with either record or stream files.

A successful call to rewind clears the error indicator for the file.

The ANSI C standard defines rewind as not returning a value; therefore, the function prototype for rewind is declared with a return type of void . However, since a rewind can fail, and since previous versions of the HP C RTL have declared rewind to return an int , the code for rewind does return 0 on success and - 1 on failure.

See also fseek .


rewinddir

Resets the position of the specified directory stream to the beginning of a directory.

Format

#include <dirent.h>

void rewinddir (DIR *dir_pointer);


Argument

dir_pointer

A pointer to the dir structure of an open directory.

Description

The rewinddir function resets the position of the specified directory stream to the beginning of the directory. It also causes the directory stream to refer to the current state of the corresponding directory, the same as using the opendir function. If the dir_pointer argument does not refer to a directory stream, the effect is undefined.

The type DIR , defined in the <dirent.h> header file, represents a directory stream. A directory stream is an ordered sequence of all the directory entries in a particular directory. Directory entries represent files.

See also opendir .


rindex

Searches for a character in a string.

Format

#include <strings.h>

char *rindex (const char *s, int c);

Function Variants The rindex function has variants named _rindex32 and _rindex64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.9 for more information on using pointer-size-specific functions.

Arguments

s

The string to search.

c

The character to search for.

Description

The rindex function is identical to the strchr function, and is provided for compatibility with some UNIX implementations.

rint (INTEGRITY SERVERS, ALPHA)

Rounds its argument to an integral value according to the current IEEE rounding direction specified by the user.

Format

#include <math.h>

double rint (double x);

float rintf (float x,);

long double rintl (long double x);


Argument

x

A real number.

Description

The rint functions return the nearest integral value to x in the direction of the current IEEE rounding mode specified on the /ROUNDING_MODE command-line qualifier.

If the current rounding mode rounds toward negative Infinity, then rint is identical to floor . If the current rounding mode rounds toward positive Infinity, then rint is identical to ceil .

If |x| = Infinity, rint returns x.


Return Values

n The nearest integral value to x in the direction of the current IEEE rounding mode.
NaN x is NaN; errno is set to EDOM.

rmdir

Removes a directory file.

Format

#include <unistd.h>

int rmdir (const char *path);


Argument

path

A directory pathname.

Description

The rmdir function removes a directory file whose name is specified in the path argument. The directory is removed only if it is empty.

If path names a symbolic link, then rmdir fails and sets errno to ENOTDIR.


Restriction

When using OpenVMS format names, the path argument must be in the form directory.dir.

Return Values

0 Indicates success.
- 1 An error occurred; errno is set to indicate the error.

sbrk

Determines the lowest virtual address that is not used with the program.

Format

#include <unistd.h>

void *sbrk (long int incr);


Argument

incr

The number of bytes to add to the current break address.

Description

The sbrk function adds the number of bytes specified by its argument to the current break address and returns the old break address.

When a program is executed, the break address is set to the highest location defined by the program and data storage areas. Consequently, sbrk is needed only by programs that have growing data areas.

sbrk(0) returns the current break address.


Return Values

x The old break address.
( void *)( - 1) Indicates that the program is requesting too much memory.

Restriction

Unlike other C library implementations, the HP C RTL memory allocation functions (such as malloc ) do not rely on brk or sbrk to manage the program heap space. Consequently, on OpenVMS systems, calling brk or sbrk can interfere with memory allocation routines. The brk and sbrk functions are provided only for compatibility purposes.

scalb (INTEGRITY SERVERS, ALPHA)

Returns the exponent of a floating-point number.

Format

#include <math.h>

double scalb (double x, double n);

float scalbf (float x, float n);

long double scalbl (long double x, long double n);


Arguments

x

A nonzero floating-point number.

n

An integer.

Description

The scalb functions return x*(2**n) for integer n.

Return Values

x On successful completion, x*(2** n) is returned.
±HUGE_VAL On overflow, scalb returns ±HUGE_VAL (according to the sign of x) and sets errno to ERANGE.
0 Underflow occurred; errno is set to ERANGE.
x x is ±Infinity.
NaN x or n is NaN; errno is set to EDOM.


Previous Next Contents Index