United States

Compaq C

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

Previous | Contents | Index

# 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:
>   1. LC_ALL
>   2. 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.
>   3. LANG
>   4. SYS$LC_ALL
>   5. 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.
>   6. 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

# 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

> Implemented for program portability and serves no function. It returns 0 (to indicate success).

## Format

> #include <unistd.h>

> int setuid (__uid_t member_number); (_DECC_V4_SOURCE)

> uid_t setuid (uid_t member_number); (NOT _DECC_V4_SOURCE)

## Argument

> ### member_number

> The member number.

## Description

> This function is implemented for program portability only and serves no function. It returns 0 to indicate success.

> Note (ALPHA ONLY) On OpenVMS Alpha systems, this function has been enhanced to take advantage of the new OpenVMS support for POSIX-style user, group, and session IDs available on a version of OpenVMS Alpha after Version 7.3. The new functionality, based on PERSONA VMS services, is the default on those versions of OpenVMS Alpha where the underlying operating system support is available. If the process has appropriate privileges, 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. To request the old behavior, define the DECC$GETJPI_BASED_UID logical name to "ENABLE":
>     $ DEFINE DECC$GETJPI_BASED_UID ENABLE

# 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.7.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.

> If the previous action for a specified signal had been established by `signal` , the values of the fields returned in the structure pointed to by the o_action argument of `sigaction` are unspecified, and in particular o_action->sa_handler is not necessarily the same value passed to `signal` . However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to `sigaction` by means of the action argument of `sigaction` ), the signal is handled as if the original call to `signal` were repeated.

> If `sigaction` fails, no new signal handler is installed.

> It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to SIG_DFL is ignored or causes an error to be returned with `errno` set to EINVAL.

> See Section 4.2 for more information on signal handling.

> Note The `sigvec` and `signal` functions are provided for compatibility to old UNIX systems; their function is a subset of that available with the `sigaction` function.

> See also `sigstack` , `sigvec` , `signal` , `wait` , `read` , and `write` , in this section.

## Return Values

> 0 | Indicates success.
> --1 | Indicates an error; A new signal handler is not installed. `errno` is set to one of the following values: EFAULT -- The action or o_action argument points to a location outside of the allocated address space of the process. EINVAL -- The sig argument is not a valid signal number. Or an attempt was made to ignore or supply a handler for the SIGKILL, SIGSTOP, and SIGCONT signals.

Previous | Next | Contents | Index

privacy and legal statement