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

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.

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.

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

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.

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.