United States

Compaq C

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

Previous | Contents | Index

# strxfrm

> Changes a string such that the changed string can be passed to the `strcmp` function and produce the same result as passing the unchanged string to the `strcoll` function.

## Format

> #include <string.h>

> size_t strxfrm (char *s1, const char *s2, size_t maxchar);

## Arguments

> ### s1, s2

> Pointers to character strings.

> ### maxchar

> The maximum number of bytes (including the null terminator) to be stored in s1.

## Description

> This function transforms the string pointed to by `s2` , and stores the resulting string in the array pointed to by `s1` . No more than maxchar bytes, including the null terminator, are placed into the array pointed to by `s1` .

> If the value of `maxchar` is less than the required size to store the transformed string (including the terminating null), the contents of the array pointed to by `s1` is indeterminate. In such a case, the function returns the size of the transformed string.

> If `maxchar` is 0, then `s1` is allowed to be a NULL pointer, and the function returns the required size of the `s1` array before making the transformation.

> The string comparison functions, `strcoll` and `strcmp` , can produce different results given the same two string to compare. The reason for this is that `strcmp` does a straightforward comparison of the code point values of the characters in the strings, whereas `strcoll` uses the locale information to do the comparison. Depending on the locale, the `strcoll` comparison can be a multipass operation, which is slower than `strcmp` .

> The purpose of the `strxfrm` function is to transform strings in such a way that if you pass two transformed strings to the `strcmp` function, the result is the same as passing the two original strings to the `strcoll` function. The `strxfrm` function is useful in applications that need to do a large number of comparisons on the same strings using `strcoll` . In this case, it might be more efficient (depending on the locale) to transform the strings once using `strxfrm` , and then do comparisons using `strcmp` .

## Return Value

> .

> x | Length of the resulting string pointed to by s1, not including the terminating null character. No return value is reserved for error indication. However, the function can set `errno` to EINVAL -- The string pointed to by ws2 contains characters outside the domain of the collating sequence

## Example

>     /* This program verifies that two transformed strings when      */
>     /* passed through strxfrm and then compared, provide the same   */
>     /* result as if passed through strcoll without any              */
>     /* transformation.

>     #include <string.h>
>     #include <stdio.h>
>     #include <stdlib.h>
>     #include <locale.h>

>     #define  BUFF_SIZE  256

>     main()
>     {
>         char string1[BUFF_SIZE];
>         char string2[BUFF_SIZE];
>         int errno;
>         int coll_result;
>         int strcmp_result;
>         size_t strxfrm_result1;
>         size_t strxfrm_result2;

>         /* setlocale to French locale */

>         if (setlocale(LC_ALL, "fr_FR.ISO8859-1") == NULL) {
>             perror("setlocale");
>             exit(EXIT_FAILURE);
>         }

>         /* collate string 1 and string 2 and store the result */

>         errno = 0;
>         coll_result = strcoll("<a`>bcd", "abcz");
>         if (errno) {
>             perror("strcoll");
>             exit(EXIT_FAILURE);
>         }

>         else {
>             /* Transform the strings (using strxfrm) into string1   */
>             /* and string2                                          */

>             strxfrm_result1 = strxfrm(string1, "<a`>bcd", BUFF_SIZE);

>             if (strxfrm_result1 == ((size_t) - 1)) {
>                 perror("strxfrm");
>                 exit(EXIT_FAILURE);
>             }

>             else if (strxfrm_result1 > BUFF_SIZE) {
>                 perror("\n** String is too long **\n");
>                 exit(EXIT_FAILURE);
>             }

>             else {
>                 strxfrm_result2 = strxfrm(string2, "abcz", BUFF_SIZE);
>                 if (strxfrm_result2 == ((size_t) - 1)) {
>                     perror("strxfrm");
>                     exit(EXIT_FAILURE);
>                 }

>                 else if (strxfrm_result2 > BUFF_SIZE) {
>                     perror("\n** String is too long **\n");
>                     exit(EXIT_FAILURE);
>                 }

>                 /* Compare the two transformed strings and verify   */
>                 /* that the result is the same as the result from   */
>                 /* strcoll on the original strings                  */
>                 else {
>                     strcmp_result = strcmp(string1, string2);
>                     if (strcmp_result == 0 && (coll_result == 0)) {
>                         printf("\nReturn value from strcoll() and "
>                                 "return value from strcmp() are both zero.");
>                        printf("\nThe program was successful\n\n");
>                     }

>                     else if ((strcmp_result < 0) && (coll_result < 0)) {
>                         printf("\nReturn value from strcoll() and "
>                            "return value from strcmp() are less than zero.");
>                         printf("\nThe program successful\n\n");
>                     }

>                     else if ((strcmp_result > 0) && (coll_result > 0)) {
>                         printf("\nReturn value from strcoll() and return "
>                                " value from strcmp() are greater than zero.");
>                         printf("\nThe program was successful\n\n");
>                     }

>                     else {
>                         printf("** Error **\n");
>                         printf("\nReturn values are not of the same type");
>                     }
>                 }
>             }
>        }
>     }

Running the example program produces the following result:

    Return value from strcoll() and return value
                   from strcmp() are less than zero.
    The program was successful

# subwin

> Creates a new subwindow with numlines lines and numcols columns starting at the coordinates (begin_y,begin_x) on the terminal screen.

## Format

> #include <curses.h>

> WINDOW *subwin (WINDOW *win, int numlines, int numcols, int begin_y, int begin_x);

## Arguments

> ### win

> A pointer to the parent window.

> ### numlines

> The number of lines in the subwindow. If numlines is 0, then the function sets that dimension to LINES -- begin_y. To get a subwindow of dimensions LINES by COLS, use the following format:

>     subwin (win, 0, 0, 0, 0)

> ### numcols

> The number of columns in the subwindow. If numcols is 0, then the function sets that dimension to COLS -- begin_x. To get a subwindow of dimensions LINES by COLS, use the following format:

>     subwin (win, 0, 0, 0, 0)

> ### begin_y

> A window coordinate at which the subwindow is to be created.

> ### begin_x

> A window coordinate at which the subwindow is to be created.

## Description

> When creating the subwindow, begin_y and begin_x are relative to the entire terminal screen. If either numlines or numcols is 0, then the `subwin` function sets that dimension to (LINES -- begin_y) or (COLS -- begin_x), respectively.

> The window pointed to by win must be large enough to contain the entire area of the subwindow. Any changes made to either window within the coordinates of the subwindow appear on both windows.

## Return Values

> window pointer | A pointer to an instance of the structure window corresponding to the newly created subwindow.
> ERR | Indicates an error.

# swab

> Swaps bytes.

## Format

> #include <unistd.h>

> void swab (const void *src, void *dest, ssize_t nbytes);

## Arguments

> ### src

> A pointer to the location of the string to copy.

> ### dest

> A pointer to where you want the results copied.

> ### nbytes

> The number of bytes to copy. Make this argument an even value. When it is an odd value, the `swab` function uses nbytes --1 instead.

## Description

> This function copies the number of bytes specified by nbytes from the location pointed to by src to the array pointed to by dest. The function then exchanges adjacent bytes. If a copy takes place between objects that overlap, the result is undefined.

# swprintf

> Writes output to an array of wide characters under control of the wide-character format string.

## Format

> #include <wchar.h>

> int swprintf (wchar_t *s, size_t n, const wchar_t *format, ...);

## Arguments

> ### s

> A pointer to the resulting wide-character sequence.

> ### n

> The maximum number of wide characters that can be written to an array pointed to by s, including a terminating null wide character.

> ### format

> A pointer to a wide-character string containing the format specifications. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

> ### ...

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

> If no conversion specifications are given, the output sources can be omitted. Otherwise, the function calls must have exactly 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

> The `swprintf` function is equivalent to the `fwprintf` function, except that the first parameter specifies an array of wide characters instead of a stream.

> No more than n wide characters are written, including a terminating null wide character, which is always added (unless n is 0).

> See also `fwprintf` in this section.

## Return Values

> x | The number of wide characters written, not counting the terminating null wide character.
> Negative value | Indicates an error. Either n or more wide characters were requested to be written, or a conversion error occurred, in which case `errno` is set to EILSEQ.

# swscanf

> Reads input from a wide-character string under control of the wide-character format string.

## Format

> #include <wchar.h>

> int swscanf (const wchar_t *s, const wchar_t *format, ...);

## Arguments

> ### s

> A pointer to a wide-character string from which the input is to be obtained.

> ### format

> A pointer to a wide-character string containing the format specifications. For more information about format and conversion specifications and their corresponding arguments, see Chapter 2.

> ### ...

> Optional expressions whose results 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 exactly 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 `swscanf` function is equivalent to the `fwscanf` function, except that the first argument specifies a wide-character string rather than a stream. Reaching the end of the wide-character string is the same as encountering EOF for the `fwscanf` function.

> See also `fwscanf` in this section.

## Return Values

> x | The number of input items assigned, sometimes fewer than provided for, or even 0 in the event of an early matching failure.
> EOF | Indicates and error. An input failure occurred before any conversion.

# sysconf

> Gets configurable system variables.

## Format

> #include <unistd.h>

> long int sysconf (int name);

## Arguments

> ### name

> Specifies the system variable to be queried.

## Description

> This function provides a method for determining the current value of a configurable system limit or whether optional features are supported.

> You supply a symbolic constant in the name argument, and `sysconf` returns a value for the corresponding system variable:

> - The symbolic constants defined in the `<unistd.h>` header file.
> - The system variables are defined in the `<limits.h>` and `<unistd.h>` header files.

> Table REF-10 lists the system variables returned by the `sysconf` function, and the symbolic constants that you can supply as the name value.

> Table REF-10 SYSCONF Argument and Return Values
> System Variable Returned | Symbolic Constant for name | Meaning
> --- | --- | ---
> ISO POSIX-1
> ARG_MAX | _SC_ARG_MAX | The maximum length, in bytes, of the arguments for one of the `exec` functions, including environment data.
> CHILD_MAX | _SC_CHILD_MAX | The maximum number of simultaneous processes for each real user ID.
> CLK_TCK | _SC_CLK_TCK | The number of clock ticks per second. The value of CLK_TCK can be variable. Do not assume that CLK_TCK is a compile time constant.
> NGROUPS_MAX | _SC_NGROUPS_MAX | The maximum number of simultaneous supplementary group IDs for each process.
> OPEN_MAX | _SC_OPEN_MAX | The maximum number of files that one process can have open at one time.
> STREAM_MAX | _SC_STREAM_MAX | The number of streams that one process can have open at one time.
> TZNAME_MAX | _SC_TZNAME_MAX | The maximum number of bytes supported for the name of a time zone (not the length of the `TZ` environmental variable).
> _POSIX_JOB_CONTROL | _SC_JOB_CONTROL | This variable has a value of 1 if the system supports job control; otherwise, --1 is returned.
> _POSIX_SAVED_IDS | _SC_SAVED_IDS | This variable has a value of 1 if each process has a saved set user ID and a saved set group ID; otherwise, --1 is returned.
> _POSIX_VERSION | _SC_VERSION | The date of approval of the most current version of the POSIX-1 standard that the system supports. The date is a 6-digit number, with the first 4 digits signifying the year and the last 2 digits the month. If_POSIX_VERSION is not defined, --1 is returned. Different versions of the POSIX-1 standard are periodically approved by the IEEE Standards Board, and the date of approval is used to distinguish between different versions.
> ISO POSIX-2
> BC_BASE_MAX | _SC_BC_BASE_MAX | The maximum value allowed for the `obase` variable with the `bc` command.
> BC_DIM_MAX | _SC_BC_DIM_MAX | The maximum number of elements permitted in an array by the `bc` command.
> BC_SCALE_MAX | _SC_BC_SCALE_MAX | The maximum value allowed for the scale variable with the `bc` command.
> BC_STRING_MAX | _SC_BC_STRING_MAX | The maximum length of string constants accepted by the `bc` command.
> COLL_WEIGHTS_MAX | _SC_COLL_WEIGHTS_MAX | The maximum number of weights that can be assigned to an entry in the LC_COLLATE locale-dependent information in a locale definition file.
> EXPR_NEST_MAX | _SC_EXPR_NEST_MAX | The maximum number of expressions that you can nest within parentheses by the `expr` command.
> LINE_MAX | _SC_LINE_MAX | The maximum length, in bytes, of a command input line (either standard input or another file) when the utility is described as processing text files. The length includes room for the trailing newline character.
> RE_DUP_MAX | _SC_RE_DUP_MAX | The maximum number of repeated occurrences of a regular expression permitted when using the interval notation arguments, such as the m and n arguments with the `ed` command.
> _POSIX2_CHAR_TERM | _SC_2_CHAR_TERM | This variable has a value of 1 if the system supports at least one terminal type; otherwise, --1 is returned.
> _POSIX2_C_BIND | _SC_2_C_BIND | This variable has a value of 1 if the system supports the C language binding option; otherwise, --1 is returned.
> _POSIX2_C_DEV | _SC_2_C_DEV | This variable has a value of 1 if the system supports the optional C Language Development Utilities from the ISO POSIX-2 standard; otherwise, --1 is returned.
> _POSIX2_C_VERSION | _SC_2_C_VERSION | Integer value indicating the version of the ISO POSIX-2 standard (C language binding). It changes with each new version of the ISO POSIX-2 standard.
> _POSIX2_VERSION | _SC_2_VERSION | Integer value indicating the version of the ISO POSIX-2 standard (Commands). It changes with each new version of the ISO POSIX-2 standard.
> _POSIX2_FORT_DEV | _SC_2_FORT_DEV | The variable has a value of 1 if the system supports the FORTRAN Development Utilities Option from the ISO POSIX-2 standard; otherwise, --1 is returned.
> _POSIX2_FORT_RUN | _SC_2_FORT_RUN | The variable has a value of 1 if the system supports the FORTRAN Runtime Utilities Option from the ISO POSIX-2 standard; otherwise, --1 is returned.
> _POSIX2_LOCALEDEF | _SC_2_LOCALEDEF | The variable has a value of 1 if the system supports the creation of new locales with the `localedef` command; otherwise, --1 is returned.
> _POSIX2_SW_DEV | _SC_2_SW_DEV | The variable has a value of 1 if the system supports the Software Development Utilities Option from the ISO POSIX-2 standard; otherwise, --1 is returned.
> _POSIX2_UPE | _SC_2_UPE | The variable has a value of 1 if the system supports the User Portability Utilities Option; otherwise, --1 is returned.
> POSIX 1003.1c-1995
> _POSIX_THREADS | _SC_THREADS | This variable has a value of 1 if the system supports POSIX threads; otherwise, --1 is returned.
> _POSIX_THREAD_ATTR_STACKSIZE | _SC_THREAD_ATTR_STACKSIZE | This variable has a value of 1 if the system supports the POSIX threads stack size attribute; otherwise, --1 is returned.
> _POSIX_THREAD_PRIORITY_SCHEDULING | _SC_THREAD_PRIORITY_SCHEDULING | The 1003.1c implementation supports the realtime scheduling functions.
> _POSIX_THREAD_SAFE_FUNCTIONS | _SC_THREAD_SAFE_FUNCTIONS | TRUE if the implementation supports the thread-safe ANSI C functions in POSIX 1003.1c.
> PTHREAD_DESTRUCTOR_ITERATIONS | _SC_THREAD_DESTRUCTOR_ITERATIONS | When a thread terminates, DECthreads iterates through all non-NULL thread-specific data values in the thread, and calls a registered destructor routine (if any) for each. It is possible for a destructor routine to create new values for one or more thread-specific data keys. In that case, DECthreads goes through the entire process again. _SC_THREAD_DESTRUCTOR_ITERATIONS is the maximum number of times the implementation loops before it terminates the thread even if there are still non-NULL values.
> PTHREAD_KEYS_MAX | _SC_THREAD_KEYS_MAX | The maximum number of thread-specific data keys that an application can create.
> PTHREAD_STACK_MIN | _SC_THREAD_STACK_MIN | The minimum allowed size of a stack for a new thread. Any lower value specified for the "stacksize" thread attribute is rounded up.
> UINT_MAX | _SC_THREAD_THREADS_MAX | The maximum number of threads an application is allowed to create. Since DECthreads does not enforce any fixed limit, this value is --1.
> X/Open
> _XOPEN_VERSION | _SC_XOPEN_VERSION | An integer indicating the most current version of the X/OPEN standard that the system supports.
> PASS_MAX | _SC_PASS_MAX | Maximum number of significant bytes in a password (not including terminating null).
> XOPEN_CRYPT | _SC_XOPEN_CRYPT | This variable has a value of 1 if the system supports the X/Open Encryption Feature Group; otherwise, --1 is returned.
> XOPEN_ENH_I18N | _SC_XOPEN_ENH_I18N | This variable has a value of 1 if the system supports the X/Open enhanced Internationalization Feature Group; otherwise, --1 is returned.
> XOPEN_SHM | _SC_XOPEN_SHM | This variable has a value of 1 if the system supports the X/Open Shared Memory Feature Group; otherwise, --1 is returned.
> X/Open Extended
> ATEXIT_MAX | _SC_ATEXIT_MAX | The maximum number of functions that you can register with `atexit` per process.
> PAGESIZE | _SC_PAGESIZE | Size in bytes of a page.
> PAGE_SIZE | _SC_PAGE_SIZE | Same as PAGESIZE. If either PAGESIZE or PAGE_SIZE is defined, the other is defined with the same value.
> IOV_MAX | _SC_IOV_MAX | Maximum number of iovec structures that one process has available for use with `readv` or `writev` .
> XOPEN_UNIX | _SC_XOPEN_UNIX | This variable has a value of 1 if the system supports the X/Open CAE Specification, August 1994, System Interfaces and Headers, Issue 4, Version 2, (ISBN: 1-85912-037-7, C435); otherwise, --1 is returned.

## Return Values

> x | The current variable value on the system. The value does not change during the lifetime of the calling process.
> --1 | Indicates an error. If the value of the name argument is invalid, `errno` is set to indicate the error. If the value of the name argument is undefined, `errno` is unchanged.

Previous | Next | Contents | Index

privacy and legal statement