HP C
Run-Time Library Reference Manual for OpenVMS Systems
Previous 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 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 I64 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:

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:

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:

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

setpgid (ALPHA, I64)

Sets the process group ID for job control.

Format

#include <unistd.h>

int setpgid (pid_t pid, pid_t pgid);

Arguments

pid

The process ID for which the process group ID is to be set.

pgid

The value to which the process group ID is set.

Description

The setpgid function is used either to join an existing process group or create a new process group within the session of the calling process. The process group ID of a session leader will not change.

Upon successful completion, the process group ID of the process with a process ID of pid is set to pgid. As a special case, if pid is 0, the process ID of the calling process is used. Also, if pgid is 0, the process group ID of the indicated process is used.

Return Values

0 Successful completion.
- 1 Indicates an error. The function sets errno to one of the following values:
  • EACCES -- The value of the pid argument matches the process ID of a child process of the calling process and the child process has successfully executed one of the exec functions.
  • EINVAL -- The value of the pgid argument is less than 0, or is not a value supported by the implementation.
  • EPERM -- The process indicated by the pid argument is a session leader. The value of the pid argument matches the process ID of a child process of the calling process, and the child process is not in the same session as the calling process. The value of the pgid argument is valid but does not match the process ID of the process indicated by the pid argument, and there is no process with a process group ID that matches the value of the pgid argument in the same session as the calling process.
  • ESRCH -- The value of the pid argument does not match the process ID of the calling process or of a child process of the calling process.

setpgrp (ALPHA, I64)

Sets the process group ID.

Format

#include <unistd.h>

pid_t setpgrp (void);

Description

If the calling process is not already a session leader, setpgrp sets the process group ID of the calling process to the process ID of the calling process. If setpgrp creates a new session, then the new session has no controlling terminal.

The setpgrp function has no effect when the calling process is a session leader.

Return Value

x The process group ID of the calling process.

setpwent

Rewinds the user database.

Format

#include <pwd.h>

void setpwent (void);

Description

The setpwent function effectively rewinds the user database to allow repeated searches.

No value is returned, but errno is set to EIO if an I/O error occurred.

See also getpwent .

setregid (ALPHA, I64)

Sets the real and effective group IDs.

Format

#include <unistd.h>

int setregid (gid_t rgid, gid_t egid);

Arguments

rgid

The value to which you want the real group ID set.

egid

The value to which you want the effective group ID set.

Description

The setregid function is used to set the real and effective group IDs of the calling process. If rgid is - 1, the real group ID is not changed; if egid is - 1, the effective group ID is not changed. The real and effective group IDs can be set to different values in the same call.

Only a process with the IMPERSONATE privilege can set the real group ID and the effective group ID to any valid value.

A nonprivileged process can set either the real group ID to the saved set-group-ID from an exec function, or the effective group ID to the saved set-group-ID or the real group ID.

Any supplementary group IDs of the calling process remain unchanged.

If a set-group-ID process sets its effective group ID to its real group ID, it can still set its effective group ID back to the saved set-group-ID.

Return Values

0 Successful completion.
- 1 Indicates an error. Neither of the group IDs is changed, and errno is set to one of the following values:
  • EINVAL -- The value of the rgid or egid argument is invalid or out-of-range.
  • EPERM -- The process does not have the IMPERSONATE privilege, and a change other than changing the real group ID to the saved set-group-ID, or changing the effective group ID to the real group ID or the saved group ID, was requested.

setreuid (ALPHA, I64)

Sets the user IDs.

Format

#include <unistd.h>

int setreuid (uid_t ruid, uid_t euid);

Arguments

ruid

The value to which you want the real user ID set.

euid

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

Description

The setreuid function sets the real and effective user IDs of the current process to the values specified by the ruid and euid arguments. If ruid or euid is - 1, the corresponding effective or real user ID of the current process is left unchanged.

A process with the IMPERSONATE privilege can set either ID to any value. 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.

It is unspecified whether a process without the IMPERSONATE privilege is permitted to change the real user ID to match the current real, effective, or saved user ID of the process.

Return Values

0 Successful completion.
- 1 Indicates an error. The function sets errno to one of the following values:
  • EINVAL -- The value of the ruid or euid argument is invalid or out of range.
  • EPERM -- The current process does not have the IMPERSONATE privilege, and either an attempt was made to change the effective user ID to a value other than the real user ID or the saved set-user-ID, or an an attempt was made to change the real user ID to a value not permitted by the implementation.

setsid (ALPHA, I64)

Creates a session and sets the process group ID.

Format

#include <unistd.h>

pid_t setsid (void);

Description

The setsid function creates a new session if the calling process is not a process group leader. Upon return, the calling process is the session leader of this new session and the process group leader of a new process group, and it has no controlling terminal. The process group ID of the calling process is set equal to the process ID of the calling process. The calling process is the only process in the new process group and the only process in the new session.

The __USE_LONG_GID_T feature macro must be enabled to make the setsid function prototype visible.

Return Values

x The process group ID of the calling process.
(pid_t) - 1 Indicates an error. The function sets errno to the following value:
  • EPERM -- The calling process is already a process group leader, or the process group ID of a process other than the calling process matches the process ID of the calling process.

setstate

Restarts and changes random-number generators.

Format

char *setstate (char *state;)

Argument

state

Points to the array of state information.

Description

The setstate 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:

See also initstate , srandom , and random .

Return Values

x A pointer to the previous state array information.
0 Indicates an error. The state information is damaged, and errno is set to the following value:
  • EINVAL---The state argument is invalid.

Previous Next Contents Index