[an error occurred while processing this directive]

HP OpenVMS Systems Documentation

HP C
Run-Time Library Reference Manual for OpenVMS Systems

Contents

Index

strtoul

Converts the initial portion of the string pointed to by nptr to an unsigned long integer.

Format

#include <stdlib.h>
unsigned long int strtoul (const char *nptr, char **endptr, int base);

Function Variants The strtoul function has variants named _strtoul32 and _strtoul64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Arguments

nptr
A pointer to the character string to be converted to an unsigned long .
endptr
The address of an object where the function can store a pointer to a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.
base
The value, 2 through 36, to use as the base for the conversion. Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.
If the base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

Return Values

x The converted value.

0 Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.

ULONG_MAX Indicates that the converted value would cause an overflow.

strtouq, strtoull (ALPHA, I64)

Convert the initial portion of the string pointed to by nptr to an unsigned __int64 integer. strtoull is a synonym for strtouq .

Format

#include <stdlib.h>
unsigned __int64 strtouq (const char *nptr, char **endptr, int base);
unsigned __int64 strtoull (const char *nptr, char **endptr, int base);

Function Variants These functions have variants named _strtouq32 , _strtoull32 and _strtouq64 , _strtoull64 for use with 32-bit and 64-bit pointer sizes, respectively. See Section 1.10 for more information on using pointer-size-specific functions.

Arguments

nptr
A pointer to the character string to be converted to an unsigned __int64 .
endptr
The address of an object where the function can store a pointer to a pointer to the first unrecognized character encountered in the conversion process (that is, the character that follows the last character in the string being converted). If endptr is a NULL pointer, the address of the first unrecognized character is not retained.
base
The value, 2 through 36, to use as the base for the conversion. Leading zeros after the optional sign are ignored, and 0x or 0X is ignored if the base is 16.
If the base is 0, the sequence of characters is interpreted by the same rules used to interpret an integer constant: after the optional sign, a leading 0 indicates octal conversion, a leading 0x or 0X indicates hexadecimal conversion, and any other combination of leading characters indicates decimal conversion.

Return Values

x The converted value.

0 Indicates that the string starts with an unrecognized character or that the value for base is invalid. If the string starts with an unrecognized character, * endptr is set to nptr.

__UINT64_MAX Indicates that the converted value would cause an overflow.

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

The strxfrm 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 strings 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 s2 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

The swab 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 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 .

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 .

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 an error. An input failure occurred before any conversion.

symlink (ALPHA, I64)

Creates a symbolic link containing the specified contents.

Format

#include <unistd.h>
int symlink (const char *link_contents, const char *link_name);

Arguments

link_contents
Contents of the symbolic link file, specified as a text string representing the pathname to which the symbolic link will point.
link_name
The text string representing the name of the symbolic link file.

Description

A symbolic link is a special kind of file that points to another file. It is a directory entry that associates a filename with a text string that is interpreted as a POSIX pathname when accessed by certain services. A symbolic link is implemented on OpenVMS systems as a file of organization SPECIAL and type SYMBOLIC_LINK.
The symlink function creates a symbolic link (link_name) containing the specified contents (link_contents). No attempt is made at link creation time to interpret the symbolic link contents.
See also readlink , unlink , realpath , lchown , and lstat .

Return Values

0 Successful completion

- 1 Indicates an error. errno is set to indicate the error:

EACCES -- Write permission is denied in the directory where the symbolic link is being created, or search permission is denied for a component of the path prefix of link_name.
EEXIST -- The link_name argument names an existing file or symbolic link.
ENAMETOOLONG -- The length of the link_name argument exceeds PATH_MAX, or a pathname component is longer than NAME_MAX, or the length of the link_contents argument is longer than SYMLINK_MAX.
ENOSPC -- The directory in which the entry for the new symbolic link is being placed cannot be extended because no space is left on the file system containing the directory, or the new symbolic link cannot be created because no space is left on the file system that would contain the link, or the file system is out of file-allocation resources.
Any errno value from creat , fsync , lstat , or write .

sysconf

Gets configurable system variables.

Format

#include <unistd.h>
long int sysconf (int name);

Argument

name
Specifies the system variable to be queried.

Description

The sysconf 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 new-line 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.

Other

N/A _SC_CPU_CHIP_TYPE Returns information for the processor type. See the description after this table.

Previous Next Contents Index

HP OpenVMS Systems Documentation

HP CRun-Time Library Reference Manual for OpenVMS Systems

strtoul

Format

Arguments

nptr

endptr

base

Return Values

strtouq, strtoull (ALPHA, I64)

Format

Arguments

nptr

endptr

base

Return Values

strxfrm

Format

Arguments

s1, s2

maxchar

Description

Return Value

Example

subwin

Format

Arguments

win

numlines

numcols

begin_y

begin_x

Description

Return Values

swab

Format

Arguments

src

dest

nbytes

Description

swprintf

Format

Arguments

s

n

format

...

Description

Return Values

swscanf

Format

Arguments

s

format

...

Description

Return Values

symlink (ALPHA, I64)

Format

Arguments

link_contents

link_name

Description

Return Values

sysconf

Format

Argument

name

Description

HP C
Run-Time Library Reference Manual for OpenVMS Systems