| Previous | Contents | Index |
typedef struct {double x,y;} cabs_t;
|
On overflow, the return value is undefined.
Allocates an area of zeroed memory. This function is AST-reentrant.
#include <stdlib.h>Function Variants This function also has variants named _calloc32 and _calloc64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.void *calloc (size_t number, size_t size);
number
The number of items to be allocated.size
The size of each item.
The calloc function initializes the items to 0.See also malloc and realloc in this section.
n The address of the first byte, which is aligned on a quadword boundary. NULL Indicates an inability to allocate the space.
Closes a message catalog.
#include <nl_types.h>int catclose (nl_catd catd);
catd
A message catalog descriptor. This is returned by a successful call to catopen.
This function closes the message catalog referenced by catd and frees the catalog file descriptor.
0 Indicates that the catalog was successfully closed. --1 Indicates that an error occurred. The function sets errno to the following value:
- EBADF -- The catalog descriptor is not valid.
Retrieves a message from a message catalog.
#include <nl_types.h>Function Variants This function also has variants named _catgets32 and _catgets64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.8 for more information on using pointer-size-specific functions.char *catgets (nl_catd catd, int set_id, int msg_id, const char *s);
catd
A message catalog descriptor. This is returned by a successful call to catopen.set_id
An integer set identifier.msg_id
An integer message identifier.s
A pointer to a default message string that is returned by the function if the message cannot be retrieved.
This function retrieves a message identified by set_id and msg_id, in the message catalog catd. The message is stored in a message buffer in the nl_catd structure, which is overwritten by subsequent calls to catgets. If a message string needs to be preserved, it should be copied to another location by the program.
x Pointer to the retrieved message. s Pointer to the default message string. Indicates that the function is not able to retrieve the requested message from the catalogue. This condition can arise if the requested pair ( set_d, msg_id) does not represent an existing message from the open catalogue, or it indicates that an error occurred. If an error occurred, the function sets errno to one of the following values:
- EBADF -- The catalog descriptor is not valid.
- EVMSRR -- A VMS I/O read error; the VMS error code can be found in vaxc$errno .
#include <nl_types.h> #include <locale.h> #include <stdarg.h> #include <stdio.h> #include <stdlib.h> /* This test makes use of all the message catalog routines. catopen() */ /* opens the catalog ready for reading, then each of the three messages */ /* in the catalog are extracted in turn using catgets() and printed out. */ /* catclose() closes the catalog after use. */ /* The catalog source file used to create the catalog is as follows: */ /* $ this is a message file $ $quote " $ another comment line $set 1 1 "First set, first message" 2 "second message -- This long message uses a backslash \ for continuation." $set 2 1 "Second set, first message" */ char *default_msg = "this is the first message."; main() { nl_catd catalog; int msg1, msg2, retval; char *cat = "sys$disk:[]test.cat"; char *msgtxt; char string[128]; if ((catalog = catopen(cat,0)) == (nl_catd)-1) { perror("catopen"); exit(EXIT_FAILURE); } msgtxt = catgets(catalog,1,1,default_msg); printf("%s\n", msgtxt); msgtxt = catgets(catalog,1,2,default_msg); printf("%s\n", msgtxt); msgtxt = catgets(catalog,2,1,default_msg); printf("%s\n", msgtxt); if ((retval = catclose(catalog)) == -1) { perror("catclose"); exit(EXIT_FAILURE); } }Running the example program produces the following result:
First set, first message second message -- This long message uses a backslash for continuation. Second set, first message
Opens a message catalog.
#include <nl_types.h>nl_catd catopen (const char *name, int oflag);
name
The name of the message catalog to open.oflag
An object of type int that determines whether the category LC_MESSAGES or the logical name LANG is used to search for the catalog file.
This function opens the message catalog identified by name. If name contains a colon (:), a square opening bracket ([), or an angle bracket (<), then it is assumed that name is the complete file specification of the catalog. If it does not include these characters, the logical name NLSPATH is used to define the file specification of the message catalog. NLSPATH is defined in the user's process. If the NLSPATH logical name is not defined, then the system-wide logical name SYS$NLSPATH is used to search for a message catalog file.NLSPATH consists of one or more templates. The catopen function uses each template to construct a file specification. For example, NLSPATH could be defined as:
DEFINE NLSPATH SYS$SYSROOT:[SYS$I18N.MSG]%N.CAT,SYS$COMMON:[SYSMSG]%N.CATIn this example, catopen first searches the directory SYS$SYSROOT:[SYS$I18N.MSG] for the named catalog. If the named catalog is not found there, the directory SYS$COMMON:[SYSMSG] is searced. The catalog name is constructed by substituting %N with the name passed to catopen , and adding the .cat suffix. %N is known as a substitution field. The following substitution fields are valid:
Field Meaning %N Substitute the name passed to catopen %L Substitute the name of the locale from the LANG environment variable or as defined for the LC_MESSAGES category of the current locale. The period (.) and at-sign (@) characters in the specified name are replaced by an underscore (_) character.
For example, a locale name of "zh_CN.dechanzi@radical" results in a substitution of ZH_CN_DECHANZI_RADICAL.
%l 1 Substitute the language part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the language part is en. %t 1 Substitute the territory part of the locale name. For example, if the current locale is en_GB.ISO8859-1, then the territory part is GB. %c 1 Substitute the codeset name from the locale name. For example, if the current locale is en_GB.ISO8859-1, then the codeset name is ISO8859-1.
1This substitution assumes that the locale name is of the form language_territory.codeset@mode
If the oflag argument is set to NL_CAT_LOCALE, then the current locale as defined for the LC_MESSAGES category is used to determine the substitution for the %L, %l, %t, and %c substitution fields. If the oflag argument is set to 0, then the value of the LANG environment variable is used as a locale name to determine the substitution for these fields. Note that using NL_CAT_LOCALE conforms to the XPG4 specification while a value of 0 (zero) exists for the purpose of preserving XPG3 compatibility.
If the substitution value is not defined, an empty string is substituted.
Each template is separated by a comma (,). A leading comma or two adjacent commas (,,) is equivalent to specifying %N. For example,
DEFINE NLSPATH ",%N.CAT,SYS$COMMON:[SYSMSG.%L]%N.CAT"In this example, catopen searches in the following locations in the order shown:
- name (in the current directory)
- name.cat (in the current directory)
- SYS$COMMON:[SYSMSG.locale_name]name.cat
x A message catalog file descriptor. Indicates the call was successful. This descriptor is used in calls to catgets and catopen . (nl_catd) --1 Indicates an error occurred. The function sets errno to one of the following values:
- EACCES -- Insufficient privilege or file protection violation, or file currently locked by another user.
- EMFILE -- Process channel count exceeded.
- ENAMETOOLONG -- The full file specification for message catalogue is too long
- ENOENT -- Unable to find the requested message catalogue.
- ENOMEM -- Insufficient memory available.
- ENOTDIR -- Part of the name argument is not a valid directory.
- EVMSERR -- An error occurred that does not match any errno value. Check the value of vaxc$errno .
Returns (as a double ) the smallest integer that is greater than or equal to its argument.
#include <math.h>double ceil (double x);
x
A real value.
x The smallest integer greater than or equal to the function argument.
Makes available for reallocation the area allocated by a previous calloc , malloc , or realloc call. This function is AST-reentrant.
#include <stdlib.h>void cfree (void *ptr);
ptr
The address returned by a previous call to malloc , calloc , or realloc .
The contents of the deallocated area are unchanged.In DEC 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.
Changes the default directory.
#include <unistd.h>int chdir (const char *dir_spec);
(ISO POSIX-1) int chdir (const char *dir_spec, ...);
(DEC C EXTENSION)
dir_spec
A null-terminated character string naming a directory in either an OpenVMS or UNIX style specification....
This argument is a DEC 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.
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:
- Call chdir from USER mode with the second argument set to 1.
- Call chdir from SUPERVISOR or EXECUTIVE mode, regardless of the value of the second argument.
Otherwise, the change is temporary.
0 Indicates that the directory is successfully changed to the given name. --1 Indicates that the change attempt has failed.
Changes the file protection of a file.
#include <stat.h>int chmod (const char *file_spec, mode_t mode);
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.
You must have a WRITE privilege for the file specified to change the mode.
0 Indicates that the mode is successfully changed. --1 Indicates that the change attempt has failed.
Changes the owner user identification code (UIC) of the file.
#include <unistd.h>int chown (const char *file_spec, uid_t owner, gid_t group);
(ISO POSIX-1) int chown (const char *file_spec, unsigned int owner, unsigned int group);
(COMPATABILITY)
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.
0 Indicates success. --1 Indicates failure.
Erase the contents of the specified window and reset the cursor to coordinates (0,0). The clear function acts on the stdscr window.
#include <curses.h>int clear();
int wclear (WINDOW *win);
win
A pointer to the window.
OK Indicates success. ERR Indicates an error.
Resets the error and end-of-file indicators for a file (so that ferror and feof will not return a nonzero value).
#include <stdio.h>void clearerr (FILE *file_ptr);
file_ptr
A file pointer.
Sets the clear flag for the window.
#include <curses.h>clearok (WINDOW *win, bool boolf);
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
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.
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 .
#include <time.h>clock_t clock (void);
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.
n The processor time used. --1 Indicates that the processor time used is not available.
Closes the file associated with a file descriptor.
#include <unistd.h>int close (int file_desc);
file_desc
A file descriptor.
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 .
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).
#include <unistd.h> int fd; . . . fd = open ("student.dat", 1); . . . close(fd);
Closes directories.
#include <dirent.h>int closedir (DIR *dir_pointer);
dir_pointer
Pointer to the dir structure of an open directory.
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.
The following example shows how to search a directory for the entry name, using the opendir , readdir , and closedir functions:
Previous Next Contents Index