[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

[w]setattr

Activate the video display attribute attr within the window. The setattr function acts on the stdscr window.

Format

#include <curses.h>
int setattr (int attr);
int wsetattr (WINDOW *win, int attr);

Arguments

win
A pointer to the window.
attr
One of a set of video display attributes, which are blinking, boldface, reverse video, and underlining, and are represented by the defined constants _BLINK, _BOLD, _REVERSE, and _UNDERLINE, respectively. You can set multiple attributes by separating them with a bitwise OR operator (|) as follows:
setattr(_BLINK | _UNDERLINE);

Description

The setattr and wsetattr functions are specific to HP C for OpenVMS Systems and are not portable.

Return Values

OK Indicates success.

ERR Indicates an error.

setbuf

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

Format

#include <stdio.h>
void setbuf (FILE *file_ptr, char *buffer);

Arguments

file_ptr
A file pointer.
buffer
A pointer to a character array or a NULL pointer.

Description

You can use the setbuf function after the specified file is opened but before any I/O operations are performed.
If buffer is a NULL pointer, then the call is equivalent to a call to setvbuf with the same file_ptr, a NULL buffer pointer, a buffering type of _IONBF (no buffering), and a buffer size of 0.
If buffer is not a NULL pointer, then the call is equivalent to a call to setvbuf with the same file_ptr, the same buffer pointer, a buffering type of _IOFBF, and a buffer size given by the value BUFSIZ (defined in <stdio.h> ). Therefore, use BUFSIZ to allocate the buffer argument used in the call to setbuf . For example:
#include <stdio.h> . . . char my_buf[BUFSIZ]; . . . setbuf(stdout, my_buf); . . .
User programs must not depend on the contents of buffer once I/O has been performed on the stream. The HP C RTL might or might not use buffer for any given I/O operation.
The setbuf function originally allowed programmers to substitute larger buffers in place of the system default buffers in obsolete versions of UNIX. The large default buffer sizes in modern implementations of C make the use of this function unnecessary most of the time. The setbuf function is retained in the ANSI C standard for compatibility with old programs. New programs should use setvbuf instead, because it allows the programmer to bind the buffer size at run time instead of compile time, and it returns a result value that can be tested.

setenv

Inserts or resets the environment variable specified by name in the current environment list.

Format

#include <stdlib.h>
int setenv (const char *name, const char *value, int overwrite);

Arguments

name
A variable name in the environment variable list.
value
The value for the environment variable.
overwrite
A value of 0 or 1 indicating whether to reset the environment variable, if it exists.

Description

The setenv function inserts or resets the environment variable name in the current environment list. If the variable name does not exist in the list, it is inserted with the value argument. If the variable does exist, the overwrite argument is tested. When the overwrite argument value is:

0 then the variable is not reset.
1 then the variable is reset to value.

Note
Do not use the setenv , getenv , and putenv functions to manipulate symbols and logicals. Instead, use the OpenVMS library calls lib$set_logical , lib$get_logical , lib$set_symbol , and lib$get_symbol . The * env functions deliberately provide UNIX behavior, and are not a substitute for these OpenVMS runtime library calls.

OpenVMS DCL symbols, not logical names, are the closest analog to environment variables on UNIX systems. While getenv is a mechanism to retrieve either a logical name or a symbol, it maintains an internal cache of values for use with setenv and subsequent getenv calls. The setenv function does not write or create DCL symbols or OpenVMS logical names.

This is consistent with UNIX behavior. On UNIX systems, setenv does not change or create any symbols that will be visible in the shell after the program exits.

Return Values

0 Indicates success.

- 1 Indicates an error. errno is set to ENOMEM---Not enough memory available to expand the environment list.

seteuid (INTEGRITY SERVERS, ALPHA)

Sets the process's effective user ID.

Format

#include <unistd.h>
int seteuid (uid_t euid);

Argument

euid
The value to which you want the effective user ID set.

Description

If the process has the IMPERSONATE privilege, the seteuid function sets the process's effective user ID.
An unprivileged process can set the effective user ID only if the euid argument is equal to either the real, effective, or saved user ID of the process.
This function requires that long (32-bit) UID/GID support be enabled. See Section 1.4.8 for more information.
See also getuid to know how UIC is represented.

Return Values

0 Successful completion.

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

EINVAL -- The value of the euid argument is invalid and not supported.
EPERM -- The process does not have the IMPERSONATE privilege, and euid does not match the real user ID or the saved set-user-ID.

setgid

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

Format

#include <types.h>
#include <unistd.h>
int setgid (__gid_t gid); (_DECC_V4_SOURCE)
int setgid (gid_t gid); (NOT _DECC_V4_SOURCE)

Argument

gid
The value to which you want the group IDs set.

Description

The setgid function can be used with POSIX style identifiers enabled or disabled.
POSIX style IDs are supported on OpenVMS Version 7.3-2 and higher.
With POSIX IDs disabled, the setgid 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 setgid function sets the real group ID, effective group ID, and the saved set-group-ID to gid.
If the process does not have appropriate privileges but gid is equal to the real group ID or to the saved set-group-ID, then the setgid function sets the effective group ID to gid. The real group ID and saved set-group-ID remain unchanged.
Any supplementary group IDs of the calling process remain unchanged.

To enable/disable POSIX style IDs, see Section 1.6.

Return Values

0 Successful completion.

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

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

setgrent (INTEGRITY SERVERS, ALPHA)

Rewinds the group database.

Format

#include <grp.h>
void setgrent (void);

Description

The setgrent function effectively rewinds the group database to allow repeated searches.
This function is always successful. No value is returned, and errno is not set.

setitimer

Sets the value of interval timers.

Format

#include <time.h>
int setitimer (int which, struct itimerval *value, struct itimerval *ovalue);

Arguments

which
The type of interval timer. The HP C RTL only supports ITIMER_REAL.
value
A pointer to an itimerval structure whose members specify a timer interval and the time left to the end of the interval.
ovalue
A pointer to an itimerval structure whose members specify a current timer interval and the time left to the end of the interval.

Description

The setitimer function sets the timer specified by which to the value specified by value, returning the previous value of the timer if ovalue is nonzero.
A timer value is defined by the itimerval structure:
struct itimerval { struct timeval it_interval; struct timeval it_value; };
The value of the itimerval structure members are: as follows

itimerval Member Value Meaning

it_interval = 0 Disables a timer after its next expiration (assumes it_value is nonzero).

it_interval = nonzero Specifies a value used in reloading it_value when the timer expires.

it_value = 0 Disables a timer.

it_value = nonzero Indicates the time to the next timer expiration.

Time values smaller than the resolution of the system clock are rounded up to this resolution.
The getitimer function provides one interval timer, defined in the <time.h> header file as ITIMER_REAL. This timer decrements in real time. When the timer expires, it delivers a SIGALARM signal.

Note
The interaction between setitimer and any of alarm , sleep , or usleep is unspecified.

Return Values

0 Indicates success.

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

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 HP C RTL specified signal that allows the OpenVMS condition-handling facility to unwind back to the desired destination.
The HP C RTL must be in control of signal handling for any HP C image. For HP 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 for more information.

Note
The C RTL provides nonstandard decc$setjmp and decc$fast_longjmp functions for Alpha and Integrity server systems. To use these nonstandard 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 HP 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.

setkey

Sets an encoding key for use by the encrypt function.

Format

#include <unistd.h>
#include <stdlib.h>
void setkey (const char *key;)

Argument

key
A character array of length 64 containing 0s and 1s.

Description

The argument of setkey is a character array of length 64 containing only the characters with numerical value 0 and 1. If this string is divided into groups of 8, the low-order bit in each group is ignored, leading to a 56-bit key which is set into the machine.
No value is returned.
See also crypt and encrypt .

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

The setlocale 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 is 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 successful\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 successful\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 successful\n"); 
}

Running the example program produces the following result:

setlocale (LC_ALL, "POSIX") call was successful 
 
setlocale (LC_ALL, "junk.junk_codeset") 
returned error: no such file or directory 
 
setlocale (LC_ALL, "sys$login:login.com") 
returned error: nontranslatable vms error code: 0x35C07C 
%c-f-localebad, not a locale file

Contents

Index

HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for OpenVMS Systems

[w]setattr

Format

Arguments

win

attr

Description

Return Values

setbuf

Format

Arguments

file_ptr

buffer

Description

setenv

Format

Arguments

name

value

overwrite

Description

Return Values

seteuid (INTEGRITY SERVERS, ALPHA)

Format

Argument

euid

Description

Return Values

setgid

Format

Argument

gid

Description

Return Values

setgrent (INTEGRITY SERVERS, ALPHA)

Format

Description

setitimer

Format

Arguments

which

value

ovalue

Description

Return Values

setjmp

Format

Argument

env

Description

Restrictions

Return Values

setkey

Format

Argument

key

Description

setlocale

Format

Arguments

category

locale

Description

Return Values

Example

HP C
Run-Time Library Reference Manual for OpenVMS Systems