United States

Compaq C

# Compaq C
Run-Time Library Reference Manual for OpenVMS Systems

Previous | Contents | Index

# sigstack (VAX ONLY)

> Defines an alternate stack on which to process signals. This allows the processing of signals in a separate environment from that of the current process. This function is nonreentrant.

## Format

> #include <signal.h>

> int sigstack (struct sigstack *ss, struct sigstack *oss);

## Arguments

> ### ss

> If ss is not NULL, it specifies the address of a structure that holds a pointer to a designated section of memory to be used as a signal stack on which to deliver signals.

> ### oss

> If oss is not NULL, it specifies the address of a structure in which the old value of the stack address is returned.

## Description

> The `sigstack` structure is defined in the standard header file `<signal.h>` as follows:

>     struct sigstack
>        {
>           char     *ss_sp;
>           int      ss_onstack;
>        };

> If the `sigvec` function specifies that the signal handler is to execute on the signal stack, the system checks to see if the process is currently executing on that stack. If the process is not executing on the signal stack, the system arranges a switch to the signal stack for the duration of the signal handler's execution. If the oss argument is not NULL, the current state of the signal stack is returned.

> Signal stacks must be allocated an adequate amount of storage; they do not expand like the run-time stack. For example, if your signal handler calls `printf` or any similarly complex Compaq C RTL routine, at least 12,000 bytes of storage should be allocated for the signal stack. If the stack overflows, an error occurs.

> `ss_sp` must point to at least four bytes before the end of the allocated memory area (see the example). This is architecture-dependent and possibly not portable to other machine architectures or operating systems.

> The `sigstack` structure is defined in the `<signal.h>` header file.

## Return Values

> 0 | Indicates success.
> --1 | Indicates failure.

## Example

>     #define ss_size 15000
>     static char mystack[ss_size];
>     struct sigstack ss = {&mystack + sizeof(mystack) - sizeof(void *), 1};

# sigsuspend

> Atomically changes the set of blocked signals and waits for a signal.

## Format

> #include <signal.h>

> int sigsuspend (const sigset_t *signal_mask);

## Arguments

> ### signal_mask

> A pointer to a set of signals.

## Description

> This function replaces the signal mask of the process with the set of signals pointed to by the signal_mask argument. Then it suspends execution of the process until delivery of a signal whose action is either to execute a signal catching function or to terminate the process. You cannot block the SIGKILL or SIGSTOP signals with the `sigsuspend` function. If a program attempts to block either of these signals, `sigsuspend` gives no indication of the error.

> If delivery of a signal causes the process to terminate, `sigsuspend` does not return. If delivery of a signal causes a signal catching function to execute, `sigsuspend` returns after the signal catching function returns, with the signal mask restored to the set that existed prior to the call to `sigsuspend` .

> The `sigsuspend` function sets the signal mask and waits for an unblocked signal as one atomic operation. This means that signals cannot occur between the operations of setting the mask and waiting for a signal. If a program invokes `sigprocmask` SIG_SETMASK and `sigsuspend` separately, a signal that occurs between these functions is often not noticed by `sigsuspend` .

> In normal usage, a signal is blocked by using the `sigprocmask` function at the beginning of a critical section. The process then determines whether there is work for it to do. If there is no work, the process waits for work by calling `sigsuspend` with the mask previously returned by `sigprocmask` .

> If a signal is caught by the calling process and control is returned from the signal handler, the calling process resumes execution after `sigsuspend` , which always returns a value of --1 and sets `errno` to EINTR.

> See also `sigpause` , and `sigprocmask` in this section.

# sigvec

> Permanently assigns a handler for a specific signal.

## Format

> #include <signal.h>

> int sigvec (int sigint, struct sigvec *sv, struct sigvec *osv);

## Arguments

> ### sigint

> The signal identifier.

> ### sv

> Pointer to a `sigvec` structure (see the Description section).

> ### osv

> If osv is not NULL, the previous handling information for the signal is returned.

## Description

> If sv is not NULL, it specifies the address of a structure containing a pointer to a handler routine and mask to be used when delivering the specified signal, and a flag indicating whether the signal is to be processed on an alternative stack. If sv-->onstack has a value of 1, the system delivers the signal to the process on a signal stack specified with `sigstack` .

> The `sigvec` function establishes a handler that remains established until explicitly removed or until the image terminates.

> The `sigvec` structure is defined in the `<signal.h>` header file as follows:

>     struct sigvec
>        {
>           int   (*handler)();
>           int   mask;
>           int   onstack;
>        };

> See Section 4.2 for more information on signal handling.

## Return Values

> 0 | Indicates that the call succeeded.
> --1 | Indicates that an error occurred.

# sin

> Returns the sine of its radian argument.

## Format

> #include <math.h>

> double sin (double x);

## Argument

> ### x

> A radian expressed as a real number.

# sinh

> Returns the hyperbolic sine of its argument.

## Format

> #include <math.h>

> double sinh (double x);

## Argument

> ### x

> A real number.

## Return Values

> n | The hyperbolic sine of the argument.
> HUGE_VAL | Indicates that the argument is too large; `errno` is set to ERANGE.

# sleep

> Suspends the execution of the current process for at least the number of seconds indicated by its argument.

## Format

> #include <unistd.h>

> unsigned int sleep (unsigned seconds); (_DECC_V4_SOURCE)

> int sleep (unsigned seconds); (NOT _DECC_V4_SOURCE)

## Argument

> ### seconds

> The number of seconds.

## Description

> This function sleeps for the specified number of seconds, or until a signal is received, or until the process executes a call to SYS$WAKE.

> If a SIGALRM signal is generated, but blocked or ignored, the `sleep` function returns. For all other signals, a blocked or ignored signal does not cause `sleep` to return.

## Return Values

> x | The number of seconds that the process awoke early.
> 0 | If the process slept the full number of seconds specified by seconds

# sprintf

> Performs formatted output to a string in memory.

## Format

> #include <stdio.h>

> int sprintf (char *str, const char *format_spec, ...);

## Arguments

> ### str

> The address of the string that will receive the formatted output. It is assumed that this string is large enough to hold the output.

> ### format_spec

> A pointer to a character string that contains the format specification. For more information about format specifications and conversion characters, see Chapter 2.

> ### ...

> Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

> If no conversion specifications are given, you may omit the output sources. Otherwise, the function calls must have at least as many output sources as there are conversion specifications, and the conversion specifications must match the types of the output sources.

> Conversion specifications are matched to output sources in left-to-right order. Excess output pointers, if any, are ignored.

## Description

> A null character is automatically appended to the end of the output string. Consider the following example of a conversion specification:

>     #include <stdio.h>

>     main()
>     {
>        int  temp = 4, temp2 = 17;
>        char s[80];

>        sprintf(s, "The answers are %d, and %d.", temp, temp2);
>     }

> In this example, character string `s` has the following contents:

>     The answers are 4, and 17.

> For a complete description of the format specification and the output source, see Chapter 2.

## Return Value

> x | The number of characters placed in the output string, not including the final null character.
> Negative value | Indicates an output error occurred. The function sets `errno` . For a list of `errno` values set by this function, see `fprintf` in this section.

# sqrt

> Returns the square root of its argument.

## Format

> #include <math.h>

> double sqrt (double x);

## Argument

> ### x

> A real number.

## Description

> The argument and the returned value are both objects of type `double` .

## Return Values

> val | The square root of x, if x is nonnegative.
> 0 | Indicates that x is negative; `errno` is set to EDOM.

# srand

> Initializes the pseudorandom number generator `rand` .

## Format

> #include <math.h>

> void srand (unsigned int seed);

## Argument

> ### seed

> An unsigned integer.

## Description

> This function uses the argument as a seed for a new sequence of pseudorandom numbers to be returned by subsequent calls to `rand` .

> If `rand` is called before any calls to `srand` , the sequence of pseudorandom numbers is generated as if the seed were set to 1.

# srand48

> Initializes a 48-bit random number generator.

## Format

> #include <stdlib.h>

> void srand48 (long int seed_val);

## Arguments

> ### seed_val

> The initialization value to begin randomization. Changing this value changes the randomization pattern.

## Description

> This function initializes the random number generator. You can use this function in your program before calling the `drand48` , `lrand48` , or `mrand48` functions. (Although it is not recommended practice, constant default initializer values are supplied automatically if you call `drand48` , `lrand48` , or `mrand48` without calling an initialization function).

> The function works by generating a sequence of 48-bit integer values, Xi, according to the linear congruential formula:

>            Xn+1 = (aXn+c)mod m        n >= 0

> The argument m equals 248 , so 48-bit integer arithmetic is performed. Unless you invoke the `lcong48` function, the multiplier value a and the addend value c are:

>           a = 5DEECE66D16 = 2736731631558
>           c = B16 = 138

> The initializer function `srand48` sets the high-order 32 bits of Xi to the low-order 32 bits contained in its argument. The low-order 16 bits of Xi are set to the arbitrary value 330E _16 .

> See also `drand48` , `lrand48` , and `mrand48` in this section.

# srandom

> Initializes the pseudorandom number generator `random` .

## Format

> int srandom (unsigned seed);

## Arguments

> ### seed

> An initial seed value.

## Description

> This function uses the argument as a seed for a new sequence of pseudorandom numbers to be returned by subsequent calls to `random` . This function has virtually the same calling sequence and initialization properties as the `srand` function, but produce sequences that are more random.

> The `srandom` function initializes the current state with the initial seed value. 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` , `random` , `setstate` , and `initstate` in this section.

## Return Values

> 0 | Indicates success. Initializes the state seed.
> --1 | Indicates an error, further specified in the global `errno` .

# sscanf

> Reads input from a character string in memory, interpreting it according to the format specification.

## Format

> #include <stdio.h>

> int sscanf (const char *str, const char *format_spec, ...);

## Arguments

> ### str

> The address of the character string that provides the input text to `sscanf` .

> ### format_spec

> A pointer to a character string that contains the format specification. For more information about format specifications and conversion characters, see Chapter 2.

> ### ...

> Optional expressions whose resultant types correspond to conversion specifications given in the format specification.

> If no conversion specifications are given, you can omit the input pointers. Otherwise, the function calls must have at least as many input pointers as there are conversion specifications, and the conversion specifications must match the types of the input pointers.

> Conversion specifications are matched to input sources in left-to-right order. Excess input pointers, if any, are ignored.

## Description

> The following is an example of a conversion specification:

>     main ()
>     {
>        char str[] = "4 17";
>        int   temp,
>              temp2;

>        sscanf(str, "%d %d", &temp, &temp2);
>        printf("The answers are %d and %d.", temp, temp2);
>     }

> This example produces the following output:

>     $ RUN  EXAMPLE
>     The answers are 4 and 17.

> For a complete description of the format specification and the input pointers, see Chapter 2.

## Return Values

> x | The number of successfully matched and assigned input items.
> EOF | Indicates that a read error occurred before any conversion.The function sets `errno` . For a list of the values set by this function, see `fscanf` in this section.

# ssignal

> Allows you to specify the action to take when a particular signal is raised.

## Format

> #include <signal.h>

> void (*ssignal (int sig, void (*func) (int, ...))) (int, ...);

## Arguments

> ### sig

> A number or mnemonic associated with a signal. The symbolic constants for signal values are defined in the `<signal.h>` header file (see Chapter 4).

> ### func

> The action to take when the signal is raised, or the address of a function that is executed when the signal is raised.

## Description

> This function is equivalent to the `signal` function except for the return value on error conditions.

> Since the `signal` function is defined by the ANSI C standard and the `ssignal` function is not, use `signal` for greater portability.

> See Section 4.2 for more information on signal handling.

## Return Values

> x | The address of the function previously established as the action for the signal. The address may be the value SIG_DFL (0) or SIG_IGN (1).
> 0 | Indicates errors. For this reason, there is no way to know whether a return status of 0 indicates failure, or whether it indicates that a previous action was SIG_DFL (0).

# [w]standend

> Deactivate the boldface attribute for the specified window. The `standend` function operates on the stdscr window.

## Format

> #include <curses.h>

> int standend (void);

> int wstandend (WINDOW *win);

## Argument

> ### win

> A pointer to the window.

## Description

> The `standend` and `wstandend` functions are equivalent to `clrattr` and `wclrattr` called with the attribute _BOLD.

## Return Values

> OK | Indicates success.
> ERR | Indicates an error.

# [w]standout

> Activate the boldface attribute of the specified window. The `standout` function acts on the `stdscr` window.

## Format

> #include <curses.h>

> int standout (void);

> int wstandout (WINDOW *win);

## Argument

> ### win

> A pointer to the window.

## Description

> The `standout` and `wstandout` functions are equivalent to `setattr` and `wsetattr` called with the attribute _BOLD.

## Return Values

> OK | Indicates success.
> ERR | Indicates an error.

Previous | Next | Contents | Index

privacy and legal statement