[an error occurred while processing this directive]

HP OpenVMS Systems

C Programming Language

Compaq C

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

setjmp

Provides a way to transfer control from a nested series of function invocations back to a predefined point without returning normally. It does not use a series of return statements. The setjmp function saves the context of the calling function in an environment buffer.

Format

#include <setjmp.h>
int setjmp (jmp_buf env);

Argument

env
The environment buffer, which must be an array of integers long enough to hold the register context of the calling function. The type jmp_buf is defined in the <setjmp.h> header file. The contents of the general-purpose registers, including the program counter (PC), are stored in the buffer.

Description

When setjmp is first called, it returns the value 0. If longjmp is then called, naming the same environment as the call to setjmp , control is returned to the setjmp call as if it had returned normally a second time. The return value of setjmp in this second return is the value supplied by you in the longjmp call. To preserve the true value of setjmp , the function calling setjmp must not be called again until the associated longjmp is called.
The setjmp function preserves the hardware general purpose registers, and the longjmp function restores them. After a longjmp , all variables have their values as of the time of the longjmp except for local automatic variables not marked volatile . These variables have indeterminate values.
The setjmp and longjmp functions rely on the OpenVMS condition-handling facility to effect a nonlocal goto with a signal handler. The longjmp function is implemented by generating a Compaq C RTL specified signal that allows the OpenVMS condition-handling facility to unwind back to the desired destination.
The Compaq C RTL must be in control of signal handling for any Compaq C image. For Compaq C to be in control of signal handling, you must establish all exception handlers through a call to the VAXC$ESTABLISH function. See Section 4.2.5 and the VAXC$ESTABLISH function in this section for more information.

Note
There are Alpha specific, non-standard decc$setjmp and decc$fast_longjmp functions. To use these non-standard functions instead of the standard ones, a program must be compiled with __FAST_SETJMP or __UNIX_SETJMP macros defined.

Unlike the standard longjmp function, the decc$fast_longjmp function does not convert its second argument from 0 to 1. After a call to decc$fast_longjmp , a corresponding setjmp function returns with the exact value of the second argument specified in the decc$fast_longjmp call.

Restrictions

You cannot invoke the longjmp function from an OpenVMS condition handler. However, you may invoke longjmp from a signal handler that has been established for any signal supported by the Compaq C RTL, subject to the following nesting restrictions:

The longjmp function will not work if you invoke it from nested signal handlers. The result of the longjmp function, when invoked from a signal handler that has been entered as a result of an exception generated in another signal handler, is undefined.
Do not invoke the setjmp function from a signal handler unless the associated longjmp is to be issued before the handling of that signal is completed.
Do not invoke the longjmp function from within an exit handler (established with atexit or SYS$DCLEXH). Exit handlers are invoked after image tear-down, so the destination address of the longjmp no longer exists.
Invoking longjmp from within a signal handler to return to the main thread of execution might leave your program in an inconsistent state. Possible side effects include the inability to perform I/O or to receive any more UNIX signals. Use siglongjmp instead.

Return Values

See the Description section.

setlocale

Selects the appropriate portion of the program's locale as specified by the category and locale arguments. You can use this function to change or query one category or the program's entire current locale.

Format

#include <locale.h>
char *setlocale (int category, const char *locale);

Arguments

category
The name of the category. Specify LC_ALL to change or query the entire locale. Other valid category names are:

LC_COLLATE
LC_CTYPE
LC_MESSAGES
LC_MONETARY
LC_NUMERIC
LC_TIME

locale
Pointer to a string that specifies the locale.

Description

This function sets or queries the appropriate portion of the program's locale as specified by the category and locale arguments. Specifying LC_ALL for the category argument names the entire locale; specifying the other values name only a portion of the program's locale.
The locale argument points to a character string that identifies the locale to be used. This argument can be one of the following:
Name of the public locale
Specifies the public locale in the following format:
language_country.codeset[@modifier]
The function searches for the public locale binary file in the location defined by the logical name SYS$I18N_LOCALE. The file type defaults to .LOCALE. The period (.) and at-sign (@) characters in the name are replaced by an underscore (_).
For example:
If the specified name is "zh_CN.dechanzi@radical", the function searches for the SYS$I18N_LOCALE:ZH_CN_DECHANZI_RADICAL.LOCALE binary locale file.
A file specification
Specifies the binary locale file. It can be any valid file specification. If either the device or directory is omitted, the function first applies the current caller's device and directory as defaults for any missing component. If the file not found, the function applies the device and directory defined by the SYS$I18N_LOCALE logical name as defaults. The file type defaults to .LOCALE.
No wildcards are allowed. The binary locale file cannot reside on a remote node.
"C"
Specifies the C locale. If a program does not call setlocale , the C locale is the default.
"POSIX"
This is the same as the C locale.
""
Specifies that the locale is initialized from the setting of the international environment logical names. The function checks the following logical names in the order shown until it finds a logical that is defined:

LC_ALL
Logical names corresponding to the category. For example, if LC_NUMERIC is specified as the category, then the first logical name that setlocale checks is LC_NUMERIC.
LANG
SYS$LC_ALL
The system default for the category, which is defined by the SYS$LC_* logical names. For example, the default for the LC_NUMERIC category is defined by the SYS$LC_NUMERIC logical name.
SYS$LANG
If none of the logical names is defined, the C locale is used as the default. The SYS$LC_* logical names are set up at the system startup time.

Like the locale argument, the equivalence name of the international environment logical name can be either the name of the public locale or the file specification. The setlocale function treats this equivalence name as if it were specified as the locale argument.
NULL
Causes setlocale to query the current locale. The function returns a pointer to a string describing the portion of the program's locale associated with category. Specifying the LC_ALL category returns the string describing the entire locale. The locale is not changed.
The string returned from the previous call to setlocale
Causes the function to restore the portion of the program's locale associated with category. If the string contains the description of the entire locale, the part of the string corresponding to category is used. If the string describes the portion of the program's locale for a single category, this locale is used. For example, this means that you can use the string returned from the call setlocale with the LC_COLLATE category to set the same locale for the LC_MESSAGES category.
If the specified locale is available, then setlocale returns a pointer to the string that describes the portion of the program's locale associated with category. For the LC_ALL category, the returned string describes the entire program's locale. If an error occurs, a NULL pointer is returned and the program's locale is not changed.
Subsequent calls to setlocale overwrite the returned string. If that part of the locale needs to be restored, the program should save the string. The calling program should make no assumptions about the format or length of the returned string.

Return Values

x Pointer to a string describing the locale.

NULL Indicates an error occurred; errno is set.

Example

#include <errno.h>
#include <stdio.h>
#include <locale.h>

/* This program calls setlocale() three times. The second call  */
/* is for a nonexistent locale. The third call is for an        */
/* existing file that is not a locale file.                     */

main()
{
    char *ret_str;

    errno = 0;
    printf("setlocale (LC_ALL, \"POSIX\")");
    ret_str = (char *) setlocale(LC_ALL, "POSIX");

    if (ret_str == NULL)
        perror("setlocale error");
    else
        printf(" call was succesfull\n");

    errno = 0;
    printf("\n\nsetlocale (LC_ALL, \"junk.junk_codeset\")");
    ret_str = (char *) setlocale(LC_ALL, "junk.junk_codeset");

    if (ret_str == NULL)
        perror(" returned error");
    else
        printf(" call was succesfull\n");

    errno = 0;
    printf("\n\nsetlocale (LC_ALL, \"sys$login:login.com\")");
    ret_str = (char *) setlocale(LC_ALL, "sys$login:login.com");

    if (ret_str == NULL)
        perror(" returned error");
    else
        printf(" call was succesfull\n");
}

Running the example program produces the following result:

setlocale (LC_ALL, "POSIX") call was succesfull

setlocale (LC_ALL, "junk.junk_codeset")
returned error: no such file or directory

setlocale (LC_ALL, "sys$login:login.com")
returned error: non-translatable vms error code: 0x35C07C
%c-f-localebad, not a locale file

setpwent

Accesses the first entry of user attribute information in the user database.

Format

#include <stdio.h>
#include <pwd.h>
int *setpwent (void);

Description

Use this function to access basic user attributes about a specified user. The setpwent function ensures that the next call to the getpwent function returns the first entry.
See also getpwent in this section.

setstate

Restarts, and changes random number generators.

Format

char *setstate (char *state;)

Arguments

state
Points to the array of state information.

Description

This function handles restarting and changing random number generators.
Once you initialize a state, the setstate function allows rapid switching between state arrays. The array defined by state is used for further random number generation until the initstate function is called or the setstate function is called again. The setstate function returns a pointer to the previous state array.
After initialization, you can restart a state array at a different point in one of two ways:

Use the initstate function, with the desired seed, state array, and size of the array.
Use the setstate function, with the desired state, followed by the srandom function with the desired seed . The advantage of using both functions is that you do not have to save the state array size once you initialize it.

See also initstate , srandom , and random , in this section.

Return Values

x A pointer to the previous state array information.

0 Indicates an error. The state information is damaged. Further specified in the following errno value:

EINVAL---The state argument is invalid.

setuid

With POSIX IDs disabled, implemented for program portability and serves no function. It returns 0 (to indicate success).
With POSIX IDs enabled, sets the user IDs.

Format

#include <types.h>
#include <unistd.h>
int setuid (__uid_t uid); (_DECC_V4_SOURCE)
uid_t setuid (uid_t uid); (NOT _DECC_V4_SOURCE)

Arguments

uid
The value to which you want the user IDs set.

Description

This function can be used with POSIX-style identifiers enabled or disabled.

Note
Currently, POSIX-style IDs are supported only by some OpenVMS versions done for specific government agencies, but will be integrated into future OpenVMS releases. OpenVMS Version 7.3-1 does not support POSIX-style IDs, but it does support 32-bit identifiers.

With POSIX IDs disabled (the default), the setuid function is implemented for program portability and serves no function. It returns 0 (to indicate success).
With POSIX-style IDs enabled:

If the process has the IMPERSONATE privilege, the setuid function sets the real user ID, effective user ID, and the saved set-user-ID to uid.
If the process does not have appropriate privileges but uid is equal to the real user ID or to the saved set-user-ID, then the setuid function sets the effective user ID to uid. The real user ID and saved set-user-ID remain unchanged.

Return Values

0 Successful completion.

-1 Indicates an error. The function sets errno to one of the following values:

EINVAL -- The value of the uid argument is invalid and not supported by the implementation.
EPERM -- The process does not have appropriate privileges and uid does not match the real user ID or the saved set-user-ID.

setvbuf

Associates a buffer with an input or output file and potentially modifies the buffering behavior.

Format

#include <stdio.h>
int setvbuf (FILE *file_ptr, char *buffer, int type, size_t size);

Arguments

file_ptr
A pointer to a file.
buffer
A pointer to a character array, or a NULL pointer.
type
The buffering type. Use one of the following values defined in <stdio.h> : _IONBF, _IOFBF, _IOLBF.
size
The number of bytes to be used in buffer by the Compaq C RTL for buffering this file. The buffer size must be a minimum of 8192 bytes and a maximum of 32767 bytes.

Description

You can use this function after the file is opened but before any I/O operations are performed.
The ANSI C standard defines the following types of file buffering. In unbuffered I/O, each I/O operation is performed immediately. Output characters or lines are written to the output device before control is returned to the program. Input characters or lines are sent directly to the program without read-ahead by the Compaq C RTL.
In line-buffered I/O, characters are buffered in an area of memory until a new-line character is seen, at which point the appropriate RMS routine is called to transmit the entire buffer. Line buffering is more efficient than unbuffered I/O since it reduces the system overhead, but it delays the availability of the data to the user or disk on output.
In fully buffered I/O, characters are buffered in an area of memory until the buffer is full, regardless of the presence of break characters. Full buffering is more efficient than line buffering or unbuffered I/O, but it delays the availability of output data even longer than line buffering.
Use the values _IONBF, _IOLBF, and _IOFBF defined in <stdio.h> for the type argument to specify unbuffered, line-buffered, and fully buffered I/O, respectively.
If _IONBF is specified for type, I/O will be unbuffered and the buffer and size arguments are ignored.
If _IOLBF or _IOFBF is specified for type, the Compaq C RTL will use line-buffered I/O if file_ptr specifies a terminal device; otherwise, it will use fully buffered I/O.
The Compaq C RTL automatically allocates a buffer to use for each I/O stream. So there are several buffer allocation possibilities:

If buffer is not a NULL pointer and size is not smaller than the automatically allocated buffer, then setvbuf uses buffer as the file buffer.
If buffer is a NULL pointer or size is smaller than the automatically allocated buffer, the automatically allocated buffer is used as the buffer area.
If buffer is a NULL pointer and size is larger than the automatically allocated buffer, then setvbuf allocates a new buffer equal to the specified size and uses that as the file buffer.

User programs must not depend on the contents of buffer once I/O has been performed on the stream. The Compaq C RTL might or might not use buffer for any given I/O operation.
Generally, it is unnecessary to use setvbuf or setbuf to control the buffer size used by the Compaq C RTL. The automatically allocated buffer sizes are chosen for efficiency based on the kind of I/O operations performed and the device characteristics (such as terminal, disk, or socket).
The setvbuf and setbuf functions are useful to introduce buffering for improved performance when writing a large amount of text to the stdout stream. This stream is unbuffered by default when bound to a terminal device (the normal case), and therefore incurs a large number of OpenVMS buffered I/O operations unless Compaq C RTL buffering is introduced by a call to setvbuf or setbuf .
The setvbuf function is used only to control the buffering used by the Compaq C RTL, not the buffering used by the underlying RMS I/O operations. You can modify RMS default buffering behavior by specifying various values for the ctx, fop, rat, gbc, mbc, mbf, rfm, and rop RMS keywords when the file is opened by the creat , freopen or open functions.

Return Values

0 Indicates success.

nonzero value Indicates that an invalid input value was specifed for type or file_ptr, or because file_ptr is being used by another thread (see Section 1.9.1).

sigaction

Specifies the action to take upon delivery of a signal.

Format

#include <signal.h>
int sigaction (int sig, const struct sigaction *action, struct sigaction *o_action);

Arguments

sig
The signal for which the action is to be taken.
action
A pointer to a sigaction structure that describes the action to take when you receive the signal specified by the sig argument.
o_action
A pointer to a sigaction structure. When the sigaction function returns from a call, the action previously attached to the specified signal is stored in this structure.

Description

When a process requests the sigaction function, the process can both examine and specify what action to perform when the specified signal is delivered. The arguments determine the behavior of the sigaction function as follows:

Specifying the sig argument identifies the affected signal. Use any one of the signal values defined in the <signal.h> header file, except SIGKILL.
If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sa_flags, then a SIGCHLD signal is generated for the calling process whenever any of its child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, then SIGCHLD signal is not generated in this way.
Specifying the action argument, if not null, points to a sigaction structure that defines what action to perform when the signal is received. If the action argument is null, signal handling remains unchanged, so you can use the call to inquire about the current handling of the signal.
Specifying the o_action argument, if not null, points to a sigaction structure that contains the action previously attached to the specified signal.

The sigaction structure consists of the following members:
void (*sa_handler)(int); sigset_t sa_mask; int sa_flags;
The sigaction structure members are defined as follows:

sa_handler This member can contain the following values:

SIG_DFL -- Specifies the default action taken when the signal is delivered.
SIG_IGN -- Specifies that the signal has no effect on the receiving process.
Function pointer -- Requests to catch the signal. The signal causes the function call.

sa_mask This member can request that individual signals, in addition to those in the process signal mask, are blocked from delivery while the signal handler function specified by the sa_handler member is executing.

sa_flags This member can set the flags to enable further control over the actions taken when a signal is delivered.

The sa_flags member of the sigaction structure has the following values:

SA_ONSTACK Setting this bit causes the system to run the signal catching function on the signal stack specified by the sigstack function. If this bit is not set, the function runs on the stack of the process where the signal is delivered.

SA_RESETHAND Setting this bit resets the signal to SIG_DFL. Be aware that you cannot automatically reset SIGILL and SIGTRAP.

SA_NODEFER Setting this bit does not automatically block the signal as it is caught.

SA_NOCLDSTOP If this bit is set and the sig argument is equal to SIGCHLD and a child process of the calling process stops, then a SIGCHLD signal is sent to the calling process only if SA_NOCLDSTOP is not set for SIGCHLD.

When a signal is caught by a signal-catching function installed by sigaction , a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either sigprocmask or sigsuspend is made. This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or SA_RESETHAND is set, and then including the signal being delivered. If and when the user's signal handler returns normally, the original signal mask is restored.
Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to sigaction ), until the SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called.

Previous Next Contents Index

HP OpenVMS Systems

Compaq CRun-Time Library Reference Manual for OpenVMS Systems

setjmp

Format

Argument

env

Description

Restrictions

Return Values

setlocale

Format

Arguments

category

locale

Description

Return Values

Example

setpwent

Format

Description

setstate

Format

Arguments

state

Description

Return Values

setuid

Format

Arguments

uid

Description

Return Values

setvbuf

Format

Arguments

file_ptr

buffer

type

size

Description

Return Values

sigaction

Format

Arguments

sig

action

o_action

Description

Compaq C
Run-Time Library Reference Manual for OpenVMS Systems