Returns pseudorandom numbers in the range 0 to 2³¹ -- 1.

Format

#include <math.h>

int rand (void);

Description

This function uses the following ANSI Standard algorithm to return a random number:

static unsigned int next = 1; int rand(void) { next = next * 1103515245 + 12345; return (next & RAND_MAX); }

See also srand in this section.

For other random number algorithms, see random and all the * 48 functions.

Generates pseudorandom numbers in a more random sequence.

Format

#include <stdlib.h>

long int random (void);

Description

This function is a random number generator that has virtually the same calling sequence and initialization properties as the rand function, but produces sequences that are more random. The low 12 bits generated by rand go through a cyclic pattern. All bits generated by random are usable. For example, random () &1 produces a random binary value.

The random function uses a nonlinear additive feedback random number generator employing a default state array size of 31 integers to return successive pseudorandom numbers in the range from 0 to ( 2³¹ )-1. The period of this random number generator is approximately 16*(( 2³¹ )-1). The size of the state array determines the period of the random number generator. Increasing the state array size increases the period.

With a full 256 bytes of state information, the period of the random number generator is greater than 2⁶⁹ , and is sufficient for most purposes.

Like the rand function, the random function produces by default a sequence of numbers that you can duplicate by calling the srandom function with a value of 1 as the seed. The srandom function, unlike the srand function, does not return the old seed because the amount of state information used is more than a single word.

See also rand , srand , srandom , setstate , and initstate in this section.

Return Values

n	A random number.

Raw mode only works with the Curses input routines [w]getch and [w]getstr . Raw mode is not supported with the Compaq C RTL emulation of UNIX I/O, Terminal I/O, or Standard I/O.

Format

#include <curses.h>

raw()

noraw()

Description

Raw mode reads are satisfied on one of two conditions: after a minimum number (5) of characters are input at the terminal or after waiting a fixed time (10 seconds) from receipt of any characters from the terminal.

Example

/* Example of standard and raw input in Curses package. */ #include <curses.h> main() { WINDOW *win1; char vert = '.', hor = '.', str[80]; /* Initialize standard screen, turn echo off. */ initscr(); noecho(); /* Define a user window. */ win1 = newwin(22, 78, 1, 1); leaveok(win1, TRUE); leaveok(stdscr, TRUE); box(stdscr, vert, hor); /* Reset the video, refresh(redraw) both windows. */ mvwaddstr(win1, 2, 2, "Test line terminated input"); wrefresh(win1); /* Do some input and output it. */ nocrmode(); wgetstr(win1, str); mvwaddstr(win1, 5, 5, str); mvwaddstr(win1, 7, 7, "Type something to clear screen"); wrefresh(win1); /* Get another character then delete the window. */ wgetch(win1); wclear(win1); mvwaddstr(win1, 2, 2, "Test raw input"); wrefresh(win1); /* Do some raw input 5 chars or timeout - and output it. */ raw(); getstr(str); noraw(); mvwaddstr(win1, 5, 5, str); mvwaddstr(win1, 7, 7, "Raw input completed"); wrefresh(win1); endwin(); }

Reads bytes from a file and places them in a buffer.

Format

#include <unistd.h>

ssize_t read (int file_desc, void *buffer, size_t nbytes); (ISO POSIX-1)

int read (int file_desc, void *buffer, int nbytes); (COMPATABILITY)

Arguments

file_desc

A file descriptor. The specified file descriptor must refer to a file currently opened for reading.

buffer

The address of contiguous storage in which the input data is placed.

nbytes

The maximum number of bytes involved in the read operation.

Description

This function returns the number of bytes read. The return value does not necessarily equal nbytes. For example, if the input is from a terminal, at most one line of characters is read.

Note The read function does not span record boundaries in a record file and, therefore, reads at most one record. A separate read must be done for each record.

Return Values

n	The number of bytes read.
--1	Indicates a read error, including physical input errors, illegal buffer addresses, protection violations, undefined file descriptors, and so forth.

Example

#include <file.h> #include <unistd.h> #include <stdlib.h> #include <stdio.h> #include <fcntl.h> main() { int fd, i; char buf[10]; FILE *fp ; /* Temporary STDIO file */ /* Create a dummy data file */ if ((fp = fopen("test.txt", "w+")) == NULL) { perror("open"); exit(1); } fputs("XYZ\n",fp) ; fclose(fp) ; /* And now practice "read" */ if ((fd = open("test.txt", O_RDWR, 0, "shr=upd")) <= 0) { perror("open"); exit(0); } /* Read 2 characters into buf. */ if ((i = read(fd, buf, 2)) < 0) { perror("read"); exit(0); } /* Print out what was read. */ if (i > 0) printf("buf='%c%c'\n", buf[0], buf[1]); close(fd); }

Finds entries in a directory.

Format

#include <dirent.h>

struct dirent *readdir (DIR *dir_pointer);

int readdir_r (DIR *dir_pointer, struct dirent *entry, struct dirent **result);

Arguments

dir_pointer

A pointer to the dir structure of an open directory.

entry

A pointer to a dirent structure that will be initialized with the directory entry at the current position of the specified stream.

result

Upon successful completion, the location where a pointer to entry is stored.

Description

The readdir function returns a pointer to a structure representing the directory entry at the current position in the directory stream specified by dir_pointer, and positions the directory stream at the next entry. It returns a NULL pointer upon reaching the end of the directory stream. The dirent structure defined in the <dirent.h> header file describes a directory entry.

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. You can remove files from or add files to a directory asynchronously to the operation of the readdir function.

The pointer returned by the readdir function points to data that you can overwrite by another call to readdir on the same directory stream. This data is not overwritten by another call to readdir on a different directory stream.

If a file is removed from or added to the directory after the most recent call to the opendir or rewinddir function, a subsequent call to the readdir function might not return an entry for that file.

When it reaches the end of the directory, or when it detects an invalid seekdir operation, the readdir function returns the null value.

An attempt to seek to an invalid location causes the readdir function to return the null value the next time it is called. A previous telldir function call returns the position.

The readdir_r function is a reentrant version of readdir . In addition to dir_pointer, you must specify a pointer to a dirent structure in which the current directory entry of the specified stream is returned.

If the operation is successful, readdir_r returns 0 and stores one of the two following pointers in result:

• Pointer to entry if the entry was found
• NULL pointer if the end of the directory stream was reached

If an error occurred, an error value is returned that indicates the cause of the error.

The storage pointed to by entry must be large enough for a dirent with an array of char d_name member containing at least NAME_MAX + 1 elements.

Example

See the description of closedir for an example.

Return Values

x	On successful completion of readdir , a pointer to an object of type struct dirent .
0	Successful completion of readdir_r .
x	On error, an error value ( readdir_r only).
NULL	An error occurred or end of the directory stream ( readdir_r only). If an error occurred, errno is set to a value indicating the cause.

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);

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, Compaq 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.

See also free , cfree , calloc , and malloc in this section.

Return Values

x	The address of the area, quadword-aligned. 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).

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 in this section.

Return Values

OK	Indicates success.
ERR	Indicates an error.

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 file name and it is a search list that contains an error, Compaq C for OpenVMS Systems interprets it as a file error.

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

See also delete in this section.

Return Values

0	Indicates success.
nonzero value	Indicates failure.

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");

Whereas 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 filename 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");

Return Values

0	Indicates success.
nonzero value	Indicates failure.

Sets the file to its beginning.

Format

#include <stdio.h>

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

int rewind (FILE *file_ptr); (COMPAQ 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 Compaq 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 in this section.

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

Format

#include <dirent.h>

void rewinddir (DIR *dir_pointer);

Arguments

dir_pointer

A pointer to the dir structure of an open directory.

Description

This 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 corresonding 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 in this section.

Searches for character in string.

Format

#include <strings.h>

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

Arguments

s

The string to search.

c

The character to search for.

Description

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

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.