VMS Help  —  CRTL
    The complete VSI C Run-Time Library (C RTL) needed for use with
    the VSI C compiler is distributed with the OpenVMS operating
    system, which runs on Intel[R] Itanium[R] processors.

    The C RTL provides routines to perform input/output, character
    and string handling, mathematical computations, memory
    allocation, error detection, subprocess creation, system access,
    and emulation of selected UNIX[R] features. These routines are
    provided both in shared image and object module library form.

    The C RTL contains XPG4-compliant internationalization support,
    providing functions to help you develop software that can run in
    different languages and cultures.

    This online help describes the C RTL routines available with this
    version of the OpenVMS system.

    For help on the socket routines used for writing Internet
    application programs for the TCP/IP Services protocol, use the
    following:

    $ HELP TCPIP_Services Programming_Interfaces Sockets_API

    Also see the "HP TCP/IP Services for OpenVMS" product
    documentation.

1  –  Feature-Test Macros

    Feature-test macros provide a means for writing portable
    programs. They ensure that the C RTL symbolic names used
    by a program do not clash with the symbolic names supplied by the
    implementation.

    The C RTL header files are coded to support the use of
    a number of feature-test macros. When an application defines a
    feature-test macro, the C RTL header files supply the
    symbols and prototypes defined by that feature-test macro and
    nothing else. If a program does not define such a macro, the
    C RTL header files define symbols without restriction.

    The feature-test macros supported by the C RTL fall into
    the following broad categories for controlling the visibility of
    symbols in header files according to the following:

    o  Standards

    o  Multiple-version support

    o  Compatibility

1.1  –  Standards Macros

    The C RTL implements parts of the following standards:

    o  X/Open CAE Specification, System Interfaces and Headers, Issue
       4, Version 2, also known as XPG4 V2.

    o  X/Open CAE Specification, System Interfaces and Headers, Issue
       4, also known as XPG4.

    o  Standard for Information Technology - Portable Operating
       System Interface (POSIX) - Part 1: System Application Program
       Interface (API)-Amendment 2: Threads Extension [C Language],
       also known as POSIX 1003.1c-1995 or IEEE 1003.1c-1995.

    o  ISO/IEC 9945-2:1993 - Information Technology - Portable
       Operating System Interface (POSIX) - Part 2: Shell and
       Utilities, also known as ISO POSIX-2.

    o  ISO/IEC 9945-1:1990 - Information Technology - Portable
       Operating System Interface (POSIX) - Part 1: System
       Application Programming Interface (API) (C Language), also
       known as ISO POSIX-1.

    o  ANSI/ISO/IEC 9899:1999 - The C99 standard, published by ISO in
       December, 1999 and adopted as an ANSI standard in April, 2000.

    o  ISO/IEC 9899:1990-1994 - Programming Languages - C, Amendment
       1: Integrity, also known as ISO C, Amendment 1.

    o  ISO/IEC 9899:1990 - Programming Languages - C, also known as
       ISO C. The normative part is the same as X3.159-1989, American
       National Standard for Information Systems - Programming
       Language C, also known as ANSI C.

1.2  –  Selecting a Standard

    You can define a feature-test macro to select each standard. You
    can do this either with a #define preprocessor directive in your
    C source before the inclusion of any header file, or with the
    /DEFINE qualifier on the CC command line.

    Features not defined by one of the previously named standards are
    considered VSI C extensions and are selected by not defining
    any standards-related, feature-test macros.

    If you do not explicitly define feature test macros to control
    header file definitions, you implicitly include all defined
    symbols as well as VSI C extensions.

1.2.1  –  XOPEN SOURCE EXTENDED

    Makes visible XPG4-extended features, including traditional UNIX
    based interfaces not previously adopted by X/Open.

    Standard Selected: XPG4 V2

    Other Standards Implied: XPG4, ISO POSIX-2, ISO POSIX-1, ANSI C

1.2.2  –  XOPEN SOURCE

    Makes visible XPG4 standard symbols and causes _POSIX_C_SOURCE
    to be set to 2 if it is not already defined with a value greater
    than 2.

    Notes:

    o  Where the ISO C Amendment 1 includes symbols not specified by
       XPG4, defining __STDC_VERSION__  == 199409 and _XOPEN_SOURCE
       (or _XOPEN_SOURCE_EXTENDED) selects both ISO C and XPG4 APIs.
       Conflicts that arise when compiling with both XPG4 and ISO C
       Amendment 1 resolve in favor of ISO C Amendment 1.

    o  Where XPG4 extends the ISO C Amendment 1, defining _XOPEN_
       SOURCE or _XOPEN_SOURCE_EXTENDED selects ISO C APIs as well as
       the XPG4 extensions available in the header file. This mode of
       compilation makes XPG4 extensions visible.

    Standard Selected: XPG4

    Other Standards Implied: XPG4, ISO POSIX-2, ISO POSIX-1, ANSI C

1.2.3  –  POSIX C SOURCE==199506

    Header files defined by ANSI C make visible those symbols
    required by IEEE 1003.1c-1995.

    Standard Selected: IEEE 1003.1c-1995

    Other Standards Implied: ISO POSIX-2, ISO POSIX-1, ANSI C

1.2.4  –  POSIX C SOURCE==2

    Header files defined by ANSI C make visible those symbols
    required by ISO POSIX-2 plus those required by ISO POSIX-1.

    Standard Selected: ISO POSIX-2

    Other Standards Implied: ISO POSIX-1, ANSI C

1.2.5  –  POSIX C SOURCE==1

    Header files defined by ANSI C make visible those symbols
    required by ISO POSIX-1.

    Standard Selected: ISO POSIX-1

    Other Standards Implied: ANSI C

1.2.6  –  STDC VERSION ==199409

    Makes ISO C Amendment 1 symbols visible.

    Standard Selected: ISO C Amendment 1

    Other Standards Implied: ANSI C

1.2.7  –  ANSI C SOURCE

    Makes ANSI C standard symbols visible.

    Standard Selected: ANSI C

    Other Standards Implied: None.

1.2.8  –  Interactions with the /STANDARD Qualifier

    The /STANDARD qualifier selects the dialect of the C language
    supported.

    With the exception of /STANDARD=ANSI89 and /STANDARD=ISOC94, the
    selection of C dialect and the selection of C RTL APIs to
    use are independent choices. All other values for /STANDARD cause
    the entire set of APIs to be available, including extensions.

    Specifying /STANDARD=ANSI89 restricts the default API set to the
    ANSI C set. In this case, to select a broader set of APIs, you
    must also specify the appropriate feature-test macro. To select
    the ANSI C dialect and all APIs, including extensions, undefine
    __HIDE_FORBIDDEN_NAMES before including any header file.

    Compiling with /STANDARD=ISOC94 sets __STDC_VERSION__  to
    199409. Conflicts that arise when compiling with both XPG4 and
    ISO C Amendment 1 resolve in favor of ISO C Amendment 1. XPG4
    extensions to ISO C Amendment 1 are selected by defining _XOPEN_
    SOURCE.

    The following examples help clarify these rules:

    o  The fdopen function is an ISO POSIX-1 extension to <stdio.h>.
       Therefore, <stdio.h> defines fdopen only if one or more of the
       following is true:

       -  The program including it is not compiled in strict ANSI C
          mode (/STANDARD=ANSI89).

       -  _POSIX_C_SOURCE is defined as 1 or greater.

       -  _XOPEN_SOURCE is defined.

       -  _XOPEN_SOURCE_EXTENDED is defined.

    o  The popen function is an ISO POSIX-2 extension to <stdio.h>.
       Therefore, <stdio.h> defines popen only if one or more of the
       following is true:

       -  The program including it is not compiled in strict ANSI C
          mode (/STANDARD=ANSI89).

       -  _POSIX_C_SOURCE is defined as 2 or greater.

       -  _XOPEN_SOURCE is defined.

       -  _XOPEN_SOURCE_EXTENDED is defined.

    o  The getw function is an X/Open extension to <stdio.h>.
       Therefore, <stdio.h> defines getw only if one or more of the
       following is true:

       -  The program is not compiled in strict ANSI C mode
          (/STANDARD=ANSI89).

       -  _XOPEN_SOURCE is defined.

       -  _XOPEN_SOURCE_EXTENDED is defined.

    o  The X/Open Extended symbolic constants _SC_PAGESIZE,
       _SC_PAGE_SIZE, _SC_ATEXIT_MAX, and _SC_IOV_MAX were added
       to <unistd.h> to support the sysconf function. However, these
       constants are not defined by _POSIX_C_SOURCE.

       The <unistd.h> header file defines these constants only if
       a program does not define _POSIX_C_SOURCE and does define
       _XOPEN_SOURCE_EXTENDED.

       If _POSIX_C_SOURCE is defined, these constants are not visible
       in <unistd.h>. Note that _POSIX_C_SOURCE is defined only for
       programs compiled in strict ANSI C mode.

    o  The fgetname function is a C RTL extension to
       <stdio.h>. Therefore, <stdio.h> defines fgetname only
       if the program is not compiled in strict ANSI C mode
       (/STANDARD=ANSI89).

    o  The macro _PTHREAD_KEYS_MAX is defined by POSIX 1003.1c-1995.
       This macro is made visible in <limits.h> when compiling for
       this standard with _POSIX_C_SOURCE == 199506 defined, or
       by default when compiling without any standards-defining,
       feature-test macros.

    o  The macro WCHAR_MAX defined in <wchar.h> is required by ISO C
       Amendment 1 but not by XPG4. Therefore:

       -  Compiling for ISO C Amendment 1 makes this symbol visible,
          but compiling for XPG4 compliance does not.

       -  Compiling for both ISO C Amendment 1 and XPG4 makes this
          symbol visible.

       Similarly, the functions wcsftime and wcstok in <wchar.h>
       are defined slightly differently by the ISO C Amendment 1 and
       XPG4:

       -  Compiling for ISO C Amendment 1 makes the ISO C Amendment 1
          prototypes visible.

       -  Compiling for XPG4 compliance makes the XPG4 prototypes
          visible.

       -  Compiling for both ISO C Amendment 1 and XPG4 selects the
          ISO C prototypes because conflicts resulting from this mode
          of compilation resolve in favor of ISO C.

       -  Compiling without any standard selecting feature test
          macros makes ISO C Amendment 1 features visible.

       In this example, compiling with no standard-selecting
       feature-test macros makes WCHAR_MAX and the ISO C Amendment 1
       prototypes for wcsftime and wcstok visible.

    o  The wcswidth and wcwidth functions are XPG4 extensions to
       ISO C Amendment 1. Their prototypes are in <wchar.h>.

       These symbols are visible if:

       -  Compiling for XPG4 compliance by defining _XOPEN_SOURCE or
          _XOPEN_SOURCE_EXTENDED.

       -  Compiling for DEC C Version 4.0 compatibility or on pre-
          OpenVMS Version 7.0 systems.

       -  Compiling with no standard-selecting feature-test macros.

       -  Compiling for both ISO C Amendment 1 and XPG4 compilance
          because these symbols are XPG4 extensions to ISO C
          Amendment 1.

       Compiling for strict ISO C Amendment 1 does not make them
       visible.

1.3  –  Multiple-Version-Support Macro

    By default, the header files enable APIs in the C RTL
    provided by the version of the operating system on which the
    compilation occurs. This is accomplished by the predefined
    setting of the __VMS_VER macro, as described in the VSI C
    User's Guide for OpenVMS Systems. For example, compiling on
    OpenVMS Version 6.2 causes only C RTL APIs from Version
    6.2 and earlier to be made available.

    Another example of the use of the __VMS_VER macro is support
    for the 64-bit versions of C RTL functions available
    with OpenVMS Alpha Version 7.0 and higher. In all header files,
    functions that provide 64-bit support are conditionalized so that
    they are visible only if __VMS_VER indicates a version of OpenVMS
    that is greater than or equal to 7.0.

    To target an older version of the operating system, do the
    following:

    1. Define a logical DECC$SHR to point to the old version of
       DECC$SHR. The compiler uses a table from DECC$SHR to perform
       routine name prefixing.

    2. Define __VMS_VER appropriately, either with the /DEFINE
       qualifier or with a combination of the #undef and #define
       preprocessor directives. With /DEFINE, you may need to disable
       the warning regarding redefinition of a predefined macro.

    Targeting a newer version of the operating system might not
    always be possible. For some versions, you can expect that the
    new DECC$SHR.EXE will require new features of the operating
    system that are not present. For such versions, the defining
    if the logical DECC$SHR in Step 1 would cause the compilation to
    fail.

    To override the value of __VMS_VER, define __VMS_VER_OVERRIDE  on
    the compiler command line. Defining __VMS_VER_OVERRIDE without a
    value sets __VMS_VER to the maximum value.

1.4  –  Compatibility Modes

    The following predefined macros are used to select header-file
    compatibility with previous versions of DEC C or the OpenVMS
    operating system:

    o  _DECC_V4_SOURCE

    o  _VMS_V6_SOURCE

    There are two types of incompatibilities that can be controlled
    in the header files:

    o  To conform to standards, some changes are source-code
       incompatible but binary compatible. To select DEC C Version
       4.0 source compatibility, use the _DECC_V4_SOURCE macro.

    o  Other changes to conform to standards introduce a binary or
       run-time incompatibility.

       In general, programs that recompile get new behaviors. In
       these cases, use the _VMS_V6_SOURCE feature test macro to
       retain previous behaviors.

       However, for the exit, kill, and wait functions, the OpenVMS
       Version 7.0 changes to make these routines ISO POSIX-1
       compliant were considered too incompatible to become the
       default. Therefore, in these cases the default behavior is
       the same as on pre-OpenVMS Version 7.0 systems. To access the
       versions of these routines that comply with ISO POSIX-1, use
       the _POSIX_EXIT feature test macro.

    The following examples help clarify the use of these macros:

    o  To conform to the ISO POSIX-1 standard, typedefs for the
       following have been added to <types.h>:

          dev_t         off_t
          gid_t         pid_t
          ino_t         size_t
          mode_t        ssize_t
          nlink_t       uid_t

       Previous development environments using a version of DEC C
       earlier than Version 5.2 may have compensated for the lack
       of these typedefs in <types.h> by adding them to another
       module. If this is the case on your system, then compiling
       with the <types.h> provided with DEC C Version 5.2 might cause
       compilation errors.

       To maintain your current environment and include the DEC C
       Version 5.2 <types.h>, compile with _DECC_V4_SOURCE defined.
       This will omit incompatible references from the DEC C Version
       5.2 headers. In <types.h>, for example, the previously listed
       typedefs will not be visible.

    o  As of OpenVMS Version 7.0, the C RTL getuid and
       geteuid functions are defined to return an OpenVMS UIC (user
       identification code) that contains both the group and member
       portions of the UIC. In previous versions of the DEC C RTL,
       these functions returned only the member number from the UIC
       code.

       Note that the prototypes for getuid and geteuid in <unistd.h>
       (as required by the ISO POSIX-1 standard) and in <unixlib.h>
       (for C RTL compatibility) have not changed. By default,
       newly compiled programs that call getuid and geteuid get
       the new definitions. That is, these functions will return
       an OpenVMS UIC.

       To let programs retain the pre-OpenVMS Version 7.0 behavior of
       getuid and geteuid, compile with the _VMS_V6_SOURCE feature-
       test macro defined.

    o  As of OpenVMS Version 7.0, the C RTL exit function is
       defined with ISO POSIX-1 semantics. As a result, the input
       status argument to exit takes a number between 0 and 255.
       (Prior to this, exit could take an OpenVMS condition code in
       its status parameter.)

       By default, the behavior for exit on OpenVMS systems is the
       same as before: exit accepts an OpenVMS condition code. To
       enable the ISO POSIX-1 compatible exit function, compile with
       the _POSIX_EXIT feature-test macro defined.

1.5  –  Curses and Socket Compatibility Macros

    The following feature-test macros are used to control the Curses
    and Socket subsets of the C RTL library:

    o  _BSD44_CURSES

       This macro selects the Curses package from the 4.4BSD Berkeley
       Software Distribution.

    o  _VMS_CURSES

       This macro selects a Curses package based on the VAX C
       compiler. This is the default Curses package.

    o  _SOCKADDR_LEN

       This macro is used to select 4.4BSD-compatible and XPG4 V2-
       compatible socket interfaces. These interfaces require support
       in your underlying TCP/IP software. Contact your TCP/IP vendor
       to inquire if the version of TCP/IP software you run supports
       4.4BSD sockets.

    Strict XPG4 V2 compliance requires the 4.4BSD-compatible socket
    interface. Therefore, if _XOPEN_SOURCE_EXTENDED is defined on
    OpenVMS Version 7.0 or higher, _SOCKADDR_LEN is defined to be 1.

    The following examples help clarify the use of these macros:

    o  Symbolic constants like AE, AL, AS, AM, BC, which represent
       pointers to termcap fields used by the BSD Curses package, are
       only visible in <curses.h> if _BSD44_CURSES is defined.

    o  The <socket.h> header file defines a 4.4BSD sockaddr structure
       only if _SOCKADDR_LEN or _XOPEN_SOURCE_EXTENDED is defined.
       Otherwise, <socket.h> defines a pre-4.4BSD sockaddr structure.
       If _SOCKADDR_LEN is defined and _XOPEN_SOURCE_EXTENDED is not
       defined,

       The <socket.h> header file also defines an osockaddr
       structure, which is a 4.3BSD sockaddr structure to be used
       for compatibility purposes. Since XPG4 V2 does not define
       an osockaddr structure, it is not visible in _XOPEN_SOURCE_
       EXTENDED mode.

1.6  –  2 GB File Size Macro

    The C RTL provides support for compiling applications to use file
    sizes and offsets that are 2 GB and larger. This is accomplished
    by allowing file offsets of 64-bit integers.

    The fseeko and ftello functions, which have the same behavior
    as fseek and ftell, accept or return values of type off_t, which
    allows for a 64-bit variant of off_t to be used.

    C RTL functions lseek, mmap, ftuncate, truncate, stat, fstat, and
    ftw can also accommodate a 64-bit file offset.

    The new 64-bit interfaces can be selected at compile time by
    defining the _LARGEFILE feature macro.

1.7  –  32-Bit UID and GID Macro (Integrity servers, Alpha)

    The C RTL supports 32-bit User Identification (UID) and Group
    Identification (GID). When an application is compiled to use
    32-bit UID/GID, the UID and GID are derived from the UIC as in
    previous versions of the operating system.

    To compile an application for 16-bit UID/GID support on systems
    that by default use 32-bit UIDs/GIDs, define the _DECC_SHORT_GID_
    T macro to 1.

    Not specifying _DECC_SHORT_GID_T provides long (32-bit) UID/GID.

    Compiling on older OpenVMS systems where long UID/GID is not
    supported, or compiling for legacy compatibility (_DECC_V4_SOURCE
    for VSI C Version 4 or _VMS_V6_SOURCE for OpenVMS Version 6),
    forces use of short (16-bit) UID/GID.

1.8  –  Standard-Compliant stat Structure (Integrity servers, Alpha)

    The C RTL supports an X/Open standard-compliant definition of
    the stat structure and associated definitions. To use these new
    definitions, applications must compile with the _USE_STD_STAT
    feature-test macro defined. Use of _USE_STD_STAT specifies long
    (32-bit) GIDs.

    When compiled with _USE_STD_STAT, the stat structure includes
    these changes:

    o  Type ino_t is defined as an unsigned quadword int. Without _
       USE_STD_STAT, it is an unsigned short.

    o  Type dev_t is defined as a 64-bit integer. Without _USE_STD_
       STAT, it is a 32-bit character pointer.

    o  Type off_t is defined as a 64-bit integer, as if the _
       LARGEFILE macro has been defined. Without _USE_STD_STAT, off_t
       is a 32-bit integer.

    o  Fields st_dev and st_rdev will have unique values per device.
       Without _USE_STD_STAT, uniqueness is not assured.

    o  Fields st_blksize and st_blocks are added. Without _USE_STD_
       STAT, these fields do not exist.

1.9  –  Using Legacy toupper and tolower Behavior (Integrity servers, Alpha)

    As of OpenVMS Version 8.3, to comply with the C99 ANSI standard
    and X/Open Specification, the _tolower and _toupper macros by
    default do not evaluate their parameter more than once. They
    simply call their respective tolower or toupper function. This
    avoids side effects (such as i++ or function calls) where the
    user can tell how many times an expression is evaluated.

    To retain the older, optimized behavior of the _tolower and _
    toupper macros, compile with /DEFINE=_FAST_TOUPPER. Then, as
    in previous releases, these macros optimize the call to avoid
    the overhead of a runtime call. However, the macro's parameter
    is evaluated more than once to determine how to calculate the
    result, possibly creating unwanted side effects.

1.10  –  Using Faster, Inlined Put and Get Functions (Integrity servers, Alpha)

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that sets the following I/O functions to use faster,
    inlined functions:

    fgetc
    fputc
    putc
    putchar
    fgetc_unlocked
    fputc_unlocked
    putc_unlocked
    putchar_unlocked

1.11  –  POSIX Style exit (Integrity servers, Alpha)

    The VSI C and C++ Version 7.1 and higher compilers have a
    /MAIN=POSIX_EXIT qualifier that defines the _POSIX_EXIT macro
    and causes the main program to call __posix_exit instead of exit
    when returning from the main program.

    This qualifier should be used with programs ported from UNIX that
    do not explicitly call exit and do not use OpenVMS specific exit
    codes.

    For older compilers, the following sample code can be used to
    force the existing main module to have a different name so that a
    simple main program will call it but force the exit status to be
    through the __posix_exit call.

    The replacement main function can be in a different module, so
    that /DEFINE="main=real_main" is all that is needed for modifying
    the build of the existing main function.

    #define _POSIX_EXIT 1

    #include <stdlib.h>

    int real_main(int argc, char **argv);

    /* Make sure POSIXized exit is used */
    int main(int argc, char **argv)
    {
    int ret_status;

       ret_status = real_main(argc, argv);

    exit (ret_status);
    }
    #define main real_main

    Unless your C program is intentionally using OpenVMS status codes
    for exit values, it is strongly recommended that both the _POSIX_
    EXIT macro be defined and, if needed, the /MAIN=POSIX_EXIT or the
    alternative main replacement be used so that DCL, BASH, and the
    accounting file get usable exit values.

2  –  Feature Logical Names

    The C RTL provides an extensive list of feature switches that
    can be set using DECC$ logical names. These switches affect the
    behavior of a C application at run time.

    The feature switches introduce new behaviors and also preserve
    old behaviors that have been deprecated.

    You enable most features by setting a logical name to ENABLE and
    disable a feature by setting the logical name to DISABLE:

    $ DEFINE DECC$feature ENABLE

    $ DEFINE DECC$feature DISABLE

    Some feature logical names can be set to a numeric value. For
    example:

    $ DEFINE DECC$PIPE_BUFFER_SIZE 32768

                                  NOTES

       o  Do not set C RTL feature logical names for the system.
          Set them only for the applications that need them,
          because other applications including OpenVMS components
          depend on the default behavior of these logical names.

       o  Older feature logicals from earlier releases of the
          C Run-Time Library were documented as supplying "any
          equivalence string" to enable a feature. While this was
          true at one time, we now strongly recommend that you use
          ENABLE for setting these feature logicals and DISABLE for
          disabling them. Failure to do so may produce unexpected
          results.

          The reason for this is twofold:

          -  In previous versions of the C RTL, any equivalence
             string, even DISABLE, may have enabled a feature
             logical.

          -  In subsequent and current versions of the C RTL, the
             following equivalence strings will disable a feature
             logical. Do not use them to enable a feature logical.

                DISABLE
                0 (zero)
                F
                FALSE
                N
                NO

             Any other string not on this list will enable a
             feature logical. The unintentionally misspelled string
             "DSABLE", for example, will enable a feature logical.

    The C RTL also provides several functions to manage feature
    logicals within your applications:

    decc$feature_get
    decc$feature_get_value
    decc$feature_get_index
    decc$feature_get_name
    decc$feature_set
    decc$feature_set_value
    decc$feature_show
    decc$feature_show_all

    See the reference section for more information on these
    functions.

    The C RTL feature logical names are listed below, grouped by the
    type of features they control:

       Feature Logical Name               Default
       ------- ------- ----               -------

       Performance Optimizations:

          DECC$ENABLE_GETENV_CACHE        DISABLE
          DECC$LOCALE_CACHE_SIZE          0
          DECC$TZ_CACHE_SIZE              2

       Legacy Behaviors:

          DECC$ALLOW_UNPRIVILEGED_NICE    DISABLE
          DECC$NO_ROOTED_SEARCH_LISTS     DISABLE
          DECC$PRINTF_USES_VAX_ROUND      DISABLE
          DECC$THREAD_DATA_AST_SAFE       DISABLE
          DECC$V62_RECORD_GENERATION      DISABLE
          DECC$WRITE_SHORT_RECORDS        DISABLE
          DECC$XPG4_STRPTIME              DISABLE

       File Attributes:

          DECC$DEFAULT_LRL                32767
          DECC$DEFAULT_UDF_RECORD         DISABLE
          DECC$FIXED_LENGTH_SEEK_TO_EOF   DISABLE
          DECC$ACL_ACCESS_CHECK           DISABLE

       Mailboxes:

          DECC$MAILBOX_CTX_STM            DISABLE

       Changes for UNIX Conformance:

          DECC$SELECT_IGNORES_INVALID_FD  DISABLE
          DECC$STRTOL_ERANGE              DISABLE
          DECC$VALIDATE_SIGNAL_IN_KILL    DISABLE

       General UNIX Enhancements:

          DECC$UNIX_LEVEL                 DISABLE
          DECC$ARGV_PARSE_STYLE           DISABLE
          DECC$PIPE_BUFFER_SIZE           512
          DECC$PIPE_BUFFER_QUOTA          512
          DECC$STREAM_PIPE                DISABLE
          DECC$POPEN_NO_CRLF_REC_ATTR     DISABLE
          DECC$STDIO_CTX_EOL              DISABLE
          DECC$USE_RAB64                  DISABLE
          DECC$GLOB_UNIX_STYLE            DISABLE

       Enhancements for UNIX Style Filenames:

          DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION  DISABLE
          DECC$EFS_CHARSET                  DISABLE
          DECC$ENABLE_TO_VMS_LOGNAME_CACHE  ENABLE
          DECC$FILENAME_ENCODING_UTF8       DISABLE
          DECC$FILENAME_UNIX_NO_VERSION     DISABLE
          DECC$FILENAME_UNIX_REPORT         DISABLE
          DECC$READDIR_DROPDOTNOTYPE        DISABLE
          DECC$RENAME_NO_INHERIT            DISABLE
          DECC$RENAME_ALLOW_DIR             DISABLE

       Enhancements for UNIX Style File Attributes:

          DECC$EFS_FILE_TIMESTAMPS        DISABLE
          DECC$EXEC_FILEATTR_INHERITANCE  DISABLE
          DECC$FILE_OWNER_UNIX            DISABLE
          DECC$FILE_PERMISSION_UNIX       DISABLE
          DECC$FILE_SHARING               DISABLE

       UNIX Compliance Mode:

          DECC$DETACHED_CHILD_PROCESS     DISABLE
          DECC$FILENAME_UNIX_ONLY         DISABLE
          DECC$POSIX_STYLE_UID            DISABLE
          DECC$USE_JPI$_CREATOR           DISABLE

       New Behaviors for POSIX Conformance:

          DECC$ALLOW_REMOVE_OPEN_FILES    DISABLE
          DECC$POSIX_SEEK_STREAM_FILE     DISABLE
          DECC$UMASK                      RMS default

       Filename Handling:

          DECC$POSIX_COMPLIANT_PATHNAMES  DISABLE

          DECC$DISABLE_POSIX_ROOT         ENABLE
          DECC$EFS_CASE_PRESERVE          DISABLE
          DECC$EFS_CASE_SPECIAL           DISABLE
          DECC$EFS_NO_DOTS_IN_DIRNAME     DISABLE
          DECC$READDIR_KEEPDOTDIR         DISABLE
          DECC$UNIX_PATH_BEFORE_LOGNAME   DISABLE

2.1  –  DECC$ACL_ACCESS_CHECK

    The DECC$ACL_ACCESS_CHECK feature logical controls the behavior
    of the access function.

    With DECC$ACL_ACCESS_CHECK enabled, the access function checks
    both UIC protection and OpenVMS Access Control Lists (ACLs).

    With DECC$ACL_ACCESS_CHECK disabled, the access function checks
    only UIC protection.

2.2  –  DECC$ALLOW_REMOVE_OPEN_FILES

    The DECC$ALLOW_REMOVE_OPEN_FILES feature logical controls the
    behavior of the remove function on open files. Ordinarily, the
    operation fails. However, POSIX conformance dictates that the
    operation succeed.

    With DECC$ALLOW_REMOVE_OPEN_FILES enabled, this POSIX conformant
    behavior is achieved.

2.3  –  DECC$ALLOW_UNPRIVILEGED_NICE

    With DECC$ALLOW_UNPRIVILEGED_NICE enabled, the nice function
    exhibits its legacy behavior of not checking the privilege of
    the calling process (that is, any user may lower the nice value
    to increase process priorities). Also, when the caller sets a
    priority above MAX_PRIORITY, the nice value is set to the base
    priority.

    With DECC$ALLOW_UNPRIVILEGED_NICE disabled, the nice function
    conforms to the X/Open standard of checking the privilege of the
    calling process (only users with ALTPRI privilege can lower the
    nice value to increase process priorities), and when the caller
    sets a priority above MAX_PRIORITY, the nice value is set to MAX_
    PRIORITY.

2.4  –  DECC$ARGV_PARSE_STYLE

    With DECC$ARGV_PARSE_STYLE enabled, case is preserved in command-
    line arguments when the process has been set up for extended DCL
    parsing using SET PROCESS/PARSE_STYLE=EXTENDED.

    DECC$ARGV_PARSE_STYLE must be defined externally as a logical
    name or set in a function called using the LIB$INITIALIZE
    mechanism because it is evaluated before function main is
    called.

2.5  –  DECC$DEFAULT_LRL

    DECC$DEFAULT_LRL specifies the default value for the RMS
    attribute for the longest record length. The default value 32767
    is the largest record size supported by RMS.

    Default: 32767

    Maximum: 32767

2.6  –  DECC$DEFAULT_UDF_RECORD

    With DECC$DEFAULT_UDF_RECORD enabled, file access mode defaults
    to RECORD instead of STREAM mode for all files except STREAMLF.

2.7  –  DECC$DETACHED_CHILD_PROCESS

    With DECC$DETACHED_CHILD_PROCESS enabled, child processes created
    using vfork and exec are created as detached processes instead of
    subprocesses.

    This feature has only limited support. In some cases the console
    cannot be shared between the parent process and the detached
    process, which can cause exec to fail.

2.8  –  DECC$DISABLE_POSIX_ROOT

    With DECC$DISABLE_POSIX_ROOT enabled, support for the POSIX root
    directory defined by SYS$POSIX_ROOT is disabled.

    With DECC$DISABLE_POSIX_ROOT disabled, the SYS$POSIX_ROOT logical
    name is interpreted as the equivalent of the file path "/". If
    a UNIX path starting with a slash (/)  is given and the value
    after the leading slash cannot be translated as a logical name,
    SYS$POSIX_ROOT is used as the parent directory for the specified
    UNIX file path.

    The C RTL supports a UNIX style root that behaves like a real
    directory. This allows such actions as:

    % cd /
    % mkdir /dirname
    % tar -xvf tarfile.tar /dirname
    % ls /

    Previously, the C RTL did not recognize "/" as a directory name.
    The normal processing for a file path starting with "/" was to
    interpret the first element as a logical name or device name. If
    this failed, there was special processing for the name /dev/null
    and names starting with /bin and /tmp:

    /dev/null       NLA0:
    /bin            SYS$SYSTEM:
    /tmp            SYS$SCRATCH:

    These behaviors are retained for compatibility purposes. In
    addition, support has been added to the C RTL for the logical
    name SYS$POSIX_ROOT as an equivalent to "/".

    To enable this feature for use by the C RTL, define SYS$POSIX_
    ROOT as a concealed logical name. For example:

    $ DEFINE/TRANSLATION=(CONCEALED,TERMINAL) SYS$POSIX_ROOT -
                                        "$1$DKA0:[SYS0.abc.]"

    To disable this feature:

    $ DEFINE DECC$DISABLE_POSIX_ROOT DISABLE

    Enabling SYS$POSIX_ROOT results in the following behavior:

    o  If the existing translation of a UNIX path starting with "/"
       fails and SYS$POSIX_ROOT is defined, the name is interpreted
       as if it starts with /sys$posix_root.

    o  When converting from an OpenVMS to a UNIX style filename,
       and the OpenVMS name starts with "SYS$POSIX_ROOT:", then
       the "SYS$POSIX_ROOT:" is removed. For example, SYS$POSIX_
       ROOT:[dirname] becomes /dirname. If the resulting name
       could be interpreted as a logical name or one of the special
       cases previously listed, the result is /./dirname instead of
       /dirname.

2.9  –  DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION

    With DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION enabled, the
    conversion routine decc$to_vms will only treat the first element
    of a UNIX style name as a logical name if there is a leading
    slash (/).

2.10  –  DECC$EFS_CASE_PRESERVE

    With DECC$EFS_CASE_PRESERVE enabled, case is preserved for
    filenames on ODS-5 disks.

    With DECC$EFS_CASE_PRESERVE disabled, UNIX style filenames are
    always reported in lowercase.

    However, note that enabling DECC$EFS_CASE_SPECIAL overrides the
    setting for DECC$EFS_CASE_PRESERVE.

2.11  –  DECC$EFS_CASE_SPECIAL

    With DECC$EFS_CASE_SPECIAL enabled, case is preserved only for
    filenames containing lowercase. If an element of a filename
    contains all uppercase letters, it is reported in all lowercase
    in UNIX style.

    When enabled, DECC$EFS_CASE_SPECIAL overrides the value of
    DECC$EFS_CASE_PRESERVE.

2.12  –  DECC$EFS_CHARSET

    With DECC$EFS_CHARSET enabled, UNIX names can contain ODS-5
    extended characters. Support includes multiple dots and all ASCII
    characters in the range 0 to 255, except the following:

    <NUL>
    /         *
    "         ?

    Unless DECC$FILENAME_UNIX_ONLY is enabled, some characters can be
    interpreted as OpenVMS characters depending on context. They are:

    :         ^
    [         ;
    <

    DECC$EFS_CHARSET might be necessary for existing applications
    that make assumptions about filenames based on the presence
    of certain characters, because the following nonstandard and
    undocumented C RTL extensions do not work when EFS extended
    character-set support is enabled:

    o  $HOME is interpreted as the user's login directory

       With DECC$EFS_CHARSET enabled, $HOME is treated literally and
       may be in an OpenVMS or UNIX style filename.

    o  ~name is interpreted as the login directory for user name

       With DECC$EFS_CHARSET enabled, ~name is treated literally and
       can be in an OpenVMS or UNIX style filename.

    o  Wild card regular expressions in the form [a-z]

       With DECC$EFS_CHARSET enabled, square brackets are acceptable
       in OpenVMS and UNIX style filenames. For instance, in a
       function such as open, abc[a-z]ef.txt is interpreted as a
       UNIX style name equivalent to the OpenVMS style name abc^[a-
       z^]ef.txt, and [a-z]bc is interpreted as an OpenVMS style name
       equivalent to the UNIX style name /sys$disk/a-z/bc.

    With DECC$EFS_CHARSET enabled, the following encoding for EFS
    extended characters is supported when converting from an OpenVMS
    style filename to a UNIX style filename:

    o  All ODS-2 compatible names

    o  All encoding for 8-bit characters, either as single byte or
       using two-digit hexadecimal form ^ab. In a UNIX path these are
       always represented as a single byte.

    o  Encoding for DEL (^7F)

    o  The following characters when preceded by a caret:

       space ! , _ & ' ( ) + @ { } ; # [ ] % ^ = $ - ~ .

    o  The following characters when not preceded by a caret:

       $  -  ~  .

    o  The implementation supports the conversion from OpenVMS to
       UNIX needed for functions readdir, ftw, getname, fgetname,
       getcwd, and others.

                                   NOTE

       There are some special cases in C RTL filename processing.
       For example:

       o  Pathnames ending in ^.dir are treated as directories, and
          when translated, these characters are truncated from the
          string.

       o  Pathnames begining with ^/ treat the next token as a
          logical name or a directory from the root.

       The following sample program shows these nuances:

       #include <stdio.h>
       #include <dirent.h>
       #include <unixlib.h>
       #include <string.h>
       main()
       {
         char adir[80];
         DIR *dir;
         struct dirent *dp;
         int decc_feature_efs_charset_index = 0;
         int decc_feature_efs_charset_default_val = 0;

         if (
             ( (decc_feature_efs_charset_index =
               decc$feature_get_index("DECC$EFS_CHARSET")) == -1 )
             ||
             ( (decc_feature_efs_charset_default_val =
   decc$feature_get_value(decc_feature_efs_charset_index, 0)) == -1 )
             ||
 ( (decc$feature_set_value(decc_feature_efs_charset_index, 1, TRUE) == -1))
            )
           {
             printf("Error setting up DECC$EFS_CHARSET macro\n");
           }

         strcpy(adir, "SYS$SYSDEVICE:[SSHTEST.TEST.a^,test^.dir^;22]");
         printf("\n\nFor %s\n", adir);
       mrb:  dir = opendir(adir);
         if(dir)
           {
             do
               {
                 dp = readdir(dir);
                 if(dp->d_name) printf("%s\n", dp->d_name);
               } while (dp);
           }

         closedir(dir);

         strcpy(adir, "SYS$SYSDEVICE:[SSHTEST.TEST.a^,test^.dir]");
         printf("\n\nFor %s\n", adir);
         dir = opendir(adir);
         if(dir)
           {
             do
               {
                 dp = readdir(dir);
                 if(dp->d_name) printf("%s\n", dp->d_name);
               } while (dp);
           }

         closedir(dir);

         strcpy(adir, "SYS$SYSDEVICE:[SSHTEST.TEST.a^\\test]");
         printf("\n\nFor %s\n", adir);
         dir = opendir(adir);
         if(dir)
           {
             do
               {
                 dp = readdir(dir);
                 if(dp->d_name) printf("%s\n", dp->d_name);
               } while (dp);
           }

         strcpy(adir, "SYS$SYSDEVICE:[SSHTEST.TEST.copies]");
         printf("\n\nFor %s\n", adir);
         dir = opendir(adir);
         if(dir)
           {
             do
               {
                 dp = readdir(dir);
                 if(dp->d_name) printf("%s\n", dp->d_name);
               } while (dp);
           }

         closedir(dir);

         strcpy(adir, "/SYS$SYSDEVICE/SSHTEST/TEST/copies");
         printf("\n\nFor %s\n", adir);
         dir = opendir(adir);
         if(dir)
           {
             do
               {
                 dp = readdir(dir);
                 if(dp->d_name) printf("%s\n", dp->d_name);
               } while (dp);
           }

         closedir(dir);

       }

2.13  –  DECC$EFS_FILE_TIMESTAMPS

    With DECC$EFS_FILE_TIMESTAMPS enabled, stat and fstat report
    new ODS-5 access time (st_atime), attribute revision time
    (st_ctime) and modification time (st_mtime) for files on ODS-5
    volumes that have the extended file times enabled using SET
    VOLUME/VOLUME=ACCESS_DATES.

    If DECC$EFS_FILE_TIMESTAMPS is disabled, or the volume is not
    ODS-5, or the volume does not have support for these additional
    times enabled, st_ctime continues to be the file creation time
    and st_atime the same as the st_mtime.

    The utime and utimes functions support these ODS-5 times in the
    same way as stat.

2.14  –  DECC$EFS_NO_DOTS_IN_DIRNAME

    With support for extended characters in filenames for ODS-5,
    a name such as NAME.EXT can be interpreted as NAME.EXT.DIR.
    Determining if directory [.name^.ext] exists adds overhead to
    UNIX name translation when support for extended character support
    in UNIX filenames is enabled.

    Enabling the DECC$EFS_NO_DOTS_IN_DIRNAME feature logical
    suppresses the interpretation of a filename containing dots as
    a directory name. With this logical enabled, NAME.EXT is assumed
    to be a filename; no check is made for directory [.name^.ext].

2.15  –  DECC$ENABLE_GETENV_CACHE

    The C RTL supplements the list of environment variables in the
    environ table with all logical names and DCL symbols available to
    the process.

    By default, whenever getenv is called for a name not in the
    environ table, an attempt is made to resolve this as a logical
    name and, if this fails, as a DCL symbol.

    With DECC$ENABLE_GETENV_CACHE enabled, once a logical name or
    DCL name has been successfully translated, its value is stored
    in a cache. When the same name is requested in a future call
    to getenv, the value is returned from the cache instead of
    reevaluating the logical name or DCL symbol.

2.16  –  DECC$ENABLE_TO_VMS_LOGNAME_CACHE

    Use the DECC$ENABLE_TO_VMS_LOGNAME_CACHE to improve the
    performance of UNIX name translation. The value is the life of
    each cache entry in seconds. The equivalence string ENABLE is
    evaluated as 1 second.

    Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to 1 to enable the cache
    with a 1-second life for each entry.

    Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to 2 to enable the cache
    with a 2-second life for each entry.

    Define DECC$ENABLE_TO_VMS_LOGNAME_CACHE to -1 to enable the cache
    without a cache entry expiration.

2.17  –  DECC$EXEC_FILEATTR_INHERITANCE

    The DECC$EXEC_FILEATTR_INHERITANCE feature logical affects child
    processes that are C programs.

    For versions of OpenVMS before Version 7.3-2, DECC$EXEC_FILEATTR_
    INHERITANCE is either enabled or disabled:

    o  With DECC$EXEC_FILEATTR_INHERITANCE enabled, the current file
       pointer and the file open mode is passed to the child process
       in exec calls.

    o  With this logical name disabled, the child process does not
       inherit append mode or the file position.

    For OpenVMS Version 7.3-2 and higher, DECC$EXEC_FILEATTR_
    INHERITANCE can be defined to 1 or 2, or be disabled:

    o  With DECC$EXEC_FILEATTR_INHERITANCE defined to 1, a child
       process inherits file positioning for all file access modes
       except append.

    o  With DECC$EXEC_FILEATTR_INHERITANCE defined to 2, a child
       process inherits file positioning for all file access modes
       including append.

    o  With DECC$EXEC_FILEATTR_INHERITANCE disabled, a child process
       does not inherit the file position for any access modes.

2.18  –  DECC$FILENAME_ENCODING_UTF8

    C RTL routines that deal with filenames now support filenames in
    UTF-8 encoding when given in UNIX style.

    For example, on an ODS-5 disk the OpenVMS DIRECTORY command
    supports a filename with the following characters:

    disk:[mydir]^U65E5^U672C^U8A9E.txt

    This filename contains three UCS-2 characters (call them xxx,
    yyy, and zzz for typographical purposes) meaning "day", "origin",
    and "language", respectively.

    With UTF-8 support enabled, a C program can now read the filename
    from the VMS directory and use that filename as an UTF-8 encoded
    string.

    For example, opendir("/disk/mydir") followed by a readdir will
    place the following into the d_name field of the supplied dirent
    structure:

    "\xE6\x97\xA5\xE6\x9C\xAC\xE8\xAA\x9E.txt"

    One of the following calls can then open this file:

    open("/disk/mydir/\xE6\x97\xA5\xE6\x9C\xAC\xE8\xAA\x9E.txt",O_RDWR,0)
    open("/disk/mydir/xxxyyyzzz.txt", O_RDWR,0)

    The "\xE6\x97\xA5" above is the byte stream E697A5, which
    represents the xxx character in UTF-8 encoding.

    This feature enhances the UNIX portability of international
    software that uses UTF-8 encoded filenames.

    The DECC$FILENAME_ENCODING_UTF8 feature logical controls whether
    or not the C RTL allows and correctly interprets Unicode UTF-8
    encoding for filenames given in UNIX style.

    This logical is undefined by default, and the C RTL behavior is
    to accept filenames as ASCII and Latin-1 format.

    This feature works only on ODS-5 disks. Therefore, to enable
    Unicode UTF-8 encoding, you must define both the DECC$FILENAME_
    ENCODING_UTF8 and DECC$EFS_CHARSET logicals to ENABLE.

2.19  –  DECC$FILENAME_UNIX_ONLY

    With DECC$FILENAME_UNIX_ONLY enabled, filenames are never
    interpreted as OpenVMS style names. This prevents any
    interpretation of the following as OpenVMS special characters:

    :   [   ^

2.20  –  DECC$FILENAME_UNIX_NO_VERSION

    With DECC$FILENAME_UNIX_NO_VERSION enabled, OpenVMS version
    numbers are not supported in UNIX style filenames.

    With DECC$FILENAME_UNIX_NO_VERSION disabled, in UNIX style names,
    version numbers are reported preceded by a period (.).

2.21  –  DECC$FILENAME_UNIX_REPORT

    With DECC$FILENAME_UNIX_REPORT enabled, all filenames are
    reported in UNIX style unless the caller specifically selects
    OpenVMS style. This applies to getpwnam, getpwuid, argv[0],
    getname, fgetname, and tempnam.

    With DECC$FILENAME_UNIX_REPORT disabled, unless specified in the
    function call, filenames are reported in OpenVMS style.

2.22  –  DECC$FILE_PERMISSION_UNIX

    With DECC$FILE_PERMISSION_UNIX enabled, the file permissions
    for new files and directories are set according to the file
    creation mode and umask. This includes mode 0777. When an earlier
    version of the file exists, the file permissions for the new file
    are inherited from the earlier version. This mode sets DELETE
    permission for a new directory when WRITE permission is enabled.

    With DECC$FILE_PERMISSION_UNIX disabled, modes 0 and 0777
    indicate using RMS default protection or protection from the
    previous version of the file. Permissions for new directories
    also follow OpenVMS rules, including disabling DELETE
    permissions.

2.23  –  DECC$FILE_SHARING

    With DECC$FILE_SHARING enabled, all files are opened with full
    sharing enabled (FAB$M_DEL | FAB$M_GET | FAB$M_PUT | FAB$M_UPD).
    This is set as a logical OR with any sharing mode specified by
    the caller.

2.24  –  DECC$FIXED_LENGTH_SEEK_TO_EOF

    With DECC$FIXED_LENGTH_SEEK_TO_EOF enabled, lseek, fseeko, and
    fseek with the direction parameter set to SEEK_END will position
    relative to the last byte in the file for files with fixed-length
    records.

    With DECC$FIXED_LENGTH_SEEK_TO_EOF disabled, lseek, fseek, and
    fseeko when called with SEEK_EOF on files with fixed-length
    records, will position relative to the end of the last record
    in the file.

2.25  –  DECC$GLOB_UNIX_STYLE

    Enabling DECC$GLOB_UNIX_STYLE selects the UNIX mode of the glob
    function, which uses UNIX style filenames and wildcards instead
    of OpenVMS style filenames and wildcards.

2.26  –  DECC$LOCALE_CACHE_SIZE

    DECC$LOCALE_CACHE_SIZE defines how much memory, in bytes, to
    allocate for caching locale data. The default value is 0, which
    disables the locale cache.

    Default: 0

    Maximum: 2147483647

2.27  –  DECC$MAILBOX_CTX_STM

    By default, an open on a local mailbox that is not a pipe treats
    mailbox records as having a record attribute of FAB$M_CR.

    With DECC$MAILBOX_CTX_STM enabled, the record attribute FAB$M_CR
    is not set.

2.28  –  DECC$NO_ROOTED_SEARCH_LISTS

    When the decc$to_vms function evaluates a UNIX style path string,
    if it determines the first element to be a logical name, then:

    o  For rooted logicals or devices, it appends ":[000000]" to the
       logical name.

       For example, if log1 is a rooted logical ($DEFINE LOG1
       [DIR_NAME.]) then /log1/filename.ext translates to
       LOG1:[000000]FILENAME.EXT.

    o  For nonrooted logicals, it appends just a colon (:)  to the
       logical name.

       For example, if log2 is a nonrooted logical ($ DEFINE
       LOG2 [DIR_NAME]), then /log2/filename.ext translates to
       LOG2:FILENAME.EXT.

    o  If the first element is a search-list logical, the translation
       proceeds by evaluating the first element in the search list,
       and translating the path as previously described.

    The preceding three cases lead to predictable, expected results.

    In the case where the first element is a search list that
    consists of a mixture of rooted and nonrooted logicals,
    translating paths as described previously can lead to different
    behavior from that of older versions of OpenVMS (before OpenVMS
    Version 7.3-1):

    o  Before OpenVMS Version 7.3-1, regardless of the contents of
       the logical, the decc$to_vms function appended only a colon
       (:).  For search lists that consisted of a mixture of rooted
       and nonrooted logicals, this resulted in certain expected
       behaviors.

    o  For OpenVMS Version 7.3-1 and later, if the first element
       of the mixed search list is a rooted logical, then decc$to_
       vms appends ":[000000]" to the logical name, resulting in
       different behavior from that of OpenVMS releases prior to
       Version 7.3-1.

    DECC$NO_ROOTED_SEARCH_LISTS controls how the decc$to_vms function
    resolves search-list logicals and provides a means to restore the
    OpenVMS behavior prior to Version 7.3-1.

    With DECC$NO_ROOTED_SEARCH_LISTS enabled:

    o  If a logical is detected in a file specification, and it is
       a search list, then a colon (:)  is appended when forming the
       OpenVMS file specification.

    o  If it is not a search list, the behavior is the same as with
       DECC$NO_ROOTED_SEARCH_LISTS disabled.

    Enabling this feature logical provides the pre-Version 7.3-1
    behavior for search list logicals.

    With DECC$NO_ROOTED_SEARCH_LISTS disabled:

    o  If a logical is detected in a file specification, and it is
       a rooted logical (or a search list whose first element is a
       rooted logical), then ":[000000]" is appended when forming the
       OpenVMS file specification.

    o  If it is a nonrooted logical (or a search list whose first
       element is a nonrooted logical), then just a colon (:)  is
       appended.

    Disabling this feature logical provides the behavior for OpenVMS
    Version 7.3-1 and later.

2.29  –  DECC$PIPE_BUFFER_QUOTA

    OpenVMS Version 7.3-2 adds an optional fourth argument of type
    int to the pipe function to specify the buffer quota of the
    pipe's mailbox. In previous OpenVMS versions, the buffer quota
    was equal to the buffer size.

    DECC$PIPE_BUFFER_QUOTA lets you specify a buffer quota to use
    for the pipe function if the optional fourth argument of that
    function is omitted.

    If the optional pipe fourth argument is omitted and DECC$PIPE_
    BUFFER_QUOTA is not defined, then the buffer quota defaults to
    the buffer size, as before.

    Default: 512

    Minimum: 512

    Maximum: 2147483647

2.30  –  DECC$PIPE_BUFFER_SIZE

    The system default buffer size of 512 bytes for pipe write
    operations can limit performance and generate extra line feeds
    when handling messages longer than 512 bytes.

    DECC$PIPE_BUFFER_SIZE allows a larger buffer size to be used for
    pipe functions such as pipe and popen. A value of 512 to 65535
    bytes can be specified.

    If DECC$PIPE_BUFFER_SIZE is not specified, the default buffer
    size 512 is used.

    Default: 512

    Minimum: 512

    Maximum: 65535

2.31  –  DECC$POPEN_NO_CRLF_REC_ATTR

    With DECC$POPEN_NO_CRLF_REC_ATTR disabled, a pipe opened with the
    popen function has its record attributes set to CR/LF carriage
    control (fab$b_rat |= FAB$M_CR). This is the default behavior.

    With DECC$POPEN_NO_CRLF_REC_ATTR enabled, CR/LF carriage control
    is prevented from being added to the pipe records. This is
    compatible with UNIX behavior, but be aware that enabling this
    feature might result in undesired behavior from other functions,
    such as gets, that rely on the carriage-return character.

2.32  –  DECC$POSIX_COMPLIANT_PATHNAMES

    With DECC$POSIX_COMPLIANT_PATHNAMES enabled, an application
    is allowed to present POSIX-compliant pathnames to any C RTL
    function that accepts a pathname.

    By default DECC$POSIX_COMPLIANT_PATHNAMES is disabled, and the
    usual C RTL behavior prevails. This disabled mode includes
    interpretation of pathnames as UNIX style specifications and
    uses rules that are different and unrelated to POSIX-compliant
    pathname processing.

    To enable DECC$POSIX_COMPLIANT_PATHNAMES, set it to one of the
    following values:

      1 All pathnames are designated as POSIX style.
      2 Pathnames that end in ":" or contain any of the bracket
        characters "[]<>", and that can be successfully parsed by
        the SYS$FILESCAN service, are designated as OpenVMS style.
        Otherwise, they are designated as POSIX style.
      3 The pathnames "." and "..", or pathnames that contain "/" are
        designated as POSIX style. Otherwise, they are designated as
        OpenVMS style.
      4 All pathnames are designated as OpenVMS style.

    See Chapter 12 of the VSI C Run-Time Library Reference Manual
    for OpenVMS Systems for more information on POSIX-compliant
    pathnames and symbolic links.

2.33  –  DECC$POSIX_SEEK_STREAM_FILE

    With DECC$POSIX_SEEK_STREAM_FILE enabled, positioning beyond
    end-of-file on STREAM files does not write to the file until the
    next write. If the write is beyond the current end-of-file, this
    positions beyond the old end-of-file, and the start position for
    the write is filled with zeros.

    With DECC$POSIX_SEEK_STREAM_FILE disabled, positioning beyond
    end-of-file will immediately write zeros to the file from the
    current end-of-file to the new position.

2.34  –  DECC$POSIX_STYLE_UID

    With DECC$POSIX_STYLE_UID enabled, 32-bit UIDs and GIDs are
    interpreted as POSIX style identifiers.

    With this logical name disabled, UIDs and GIDs are derived from
    the process UIC.

    This feature is only available on OpenVMS systems providing POSIX
    style UID and GID support.

2.35  –  DECC$PRINTF_USES_VAX_ROUND

    With DECC$PRINTF_USES_VAX_ROUND enabled, the F and E format
    specifiers of printf use VAX rounding rules for programs compiled
    with IEEE float.

2.36  –  DECC$READDIR_DROPDOTNOTYPE

    With DECC$READDIR_DROPDOTNOTYPE enabled, readdir when reporting
    files in UNIX style only reports the trailing period (.)  for
    files with no file type when the filename contains a period.

    With this logical name disabled, all files without a file type
    are reported with a trailing period.

2.37  –  DECC$READDIR_KEEPDOTDIR

    The default behavior when reporting files in UNIX style from
    readdir is to report directories without a file type.

    With DECC$READDIR_KEEPDOTDIR enabled, directories are reported in
    UNIX style with a file type of ".DIR".

2.38  –  DECC$RENAME_NO_INHERIT

    DECC$RENAME_NO_INHERIT provides more UNIX compliant behavior in
    the rename function. With DECC$RENAME_NO_INHERIT enabled, the
    following behaviors are enforced:

    o  If the old argument points to the pathname of a file that
       is not a directory, the new argument will not point to the
       pathname of a directory.

    o  The new argument cannot point to a directory that exists.

    o  If the old argument points to the pathname of a directory, the
       new argument will not point to the pathname of a file that is
       not a directory.

    o  The new name for the file does not inherit anything from
       the old name. The new name must be specified completely. For
       example:

       Renaming "A.A" to "B" yields "B"

    With this logical name disabled, you get the expected OpenVMS
    behavior. For example:

    Renaming "A.A" to "B" yields "B.A"

2.39  –  DECC$RENAME_ALLOW_DIR

    Enabling DECC$RENAME_ALLOW_DIR restores the prior OpenVMS
    behavior of the rename function by allowing conversion to a
    directory specification when the second argument is an ambiguous
    file specification passed as a logical name. The ambiguity is
    whether the logical name is a UNIX or OpenVMS file specification.
    Consider the following example with DECC$RENAME_ALLOW_DIR
    enabled:

    rename("file.ext", "logical_name")
                            /*where logical_name = dev:[dir.subdir]*/
                            /* and :[dir.subdir] exists.          */

    This results in:

    dev:[dir.subdir]file.ext

    This example renames a file from one directory into another
    directory, which is the same behavior as in legacy versions
    of OpenVMS (versions before 7.3-1). Also in this example, if
    dev:[dir.subdir] does not exist, rename returns an error.

    Disabling DECC$RENAME_ALLOW_DIR provides a more UNIX compliant
    conversion of the "logical_name" argument of rename. Consider the
    following example with DECC$RENAME_ALLOW_DIR disabled:

    rename("file.ext", "logical_name")
                        /* where logical_name = dev:[dir.subdir] */

    This results in:

    dev:[dir]subdir.ext

    This example renames the file using the subdir part of the
    "logical_name" argument as the new filename because on UNIX
    systems, renaming a file to a directory is not allowed. So
    rename internally converts the "logical_name" to a filename, and
    dev:[dir]subdir is the most reasonable conversion it can perform.

    This new feature switch has a side effect of causing rename to a
    directory to take precedence over rename to a file. Consider this
    example:

    rename ( "file1.ext", "dir2" )      /* dir2 is not a logical */

    With DECC$RENAME_ALLOW_DIR disabled, this example results in
    dir2.ext, regardless of whether or not subdirectory [.dir2]
    exists.

    With DECC$RENAME_ALLOW_DIR enabled, this example results in
    dir2.ext only if subdirectory [.dir2] does not exist. If
    subdirectory [.dir2] does exist, the result is [.dir2]file1.ext.

                                   NOTE

       If DECC$RENAME_NO_INHERIT is enabled, UNIX compliant
       behavior is expected, so DECC$RENAME_ALLOW_DIR is ignored,
       and renaming a file to a directory is not allowed.

2.40  –  DECC$SELECT_IGNORES_INVALID_FD

    With DECC$SELECT_IGNORES_INVALID_FD enabled, select fails with
    errno set to EBADF when an invalid file descriptor is specified
    in one of the descriptor sets.

    With DECC$SELECT_IGNORES_INVALID_FD disabled, select ignores
    invalid file descriptors.

2.41  –  DECC$STDIO_CTX_EOL

    With DECC$STDIO_CTX_EOL enabled, writing to stdout and stderr
    for stream access is deferred until a terminator is seen or the
    buffer is full.

    With DECC$STDIO_CTX_EOL disabled, each fwrite generates a
    separate write, which for mailbox and record files generates a
    separate record.

2.42  –  DECC$STREAM_PIPE

    With DECC$STREAM_PIPE enabled, the C RTL pipe function uses the
    more UNIX compatible stream I/O.

    With DECC$STREAM_PIPE disabled, pipe uses the OpenVMS legacy
    record I/O. This is the default.

2.43  –  DECC$STRTOL_ERANGE

    With DECC$STRTOL_ERANGE enabled, the strtol behavior for an
    ERANGE error is corrected to consume all remaining digits in
    the string.

    With DECC$STRTOL_ERANGE disabled, the legacy behavior of leaving
    the pointer at the failing digit is preserved.

2.44  –  DECC$THREAD_DATA_AST_SAFE

    The C RTL has a mode that allocates storage for thread-specific
    data allocated by threads at non-AST level separate for data
    allocated for ASTs. In this mode, each access to thread-
    specific data requires a call to LIB$AST_IN_PROG, which can add
    significant overhead when accessing thread-specific data in the
    C RTL.

    The alternate mode protects thread-specific data only if another
    function has it locked. This protects data that is in use within
    the C RTL, but does not protect the caller from an AST changing
    the data pointed to.

    This latter mode is now the C RTL default for the strtok, ecvt,
    and fcvt functions.

    You can select the legacy AST safe mode by enabling DECC$THREAD_
    DATA_AST_SAFE.

2.45  –  DECC$TZ_CACHE_SIZE

    DECC$TZ_CACHE_SIZE specifies the number of time zones that can be
    held in memory.

    Default: 2

    Maximum: 2147483647

2.46  –  DECC$UMASK

    DECC$UMASK specifies the default value for the permission mask
    umask. By default, a parent C program sets the umask from the RMS
    default permissions for the process. A child process inherits the
    parent's value for umask.

    To enter the value as an octal value, add the leading zero;
    otherwise, it is translated as a decimal value. For example:

    $ DEFINE DECC$UMASK 026

    Maximum: 0777

2.47  –  DECC$UNIX_LEVEL

    With the DECC$UNIX_LEVEL logical name, you can manage multiple
    C RTL feature logical names at once. By setting a value for
    DECC$UNIX_LEVEL from 1 to 100, you determine the default value
    for groups of feature logical names. The value you set has a
    cumulative effect: the higher the value, the more groups that
    are affected. Setting a value of 20, for example, enables all the
    feature logicals associated with a DECC$UNIX_LEVEL of 20, 10, and
    1.

    The principal logical names affecting UNIX like behavior are
    grouped as follows:

       1    General corrections
       10   Enhancements
       20   UNIX style filenames
       30   UNIX style file attributes
       90   Full UNIX behavior - No concessions to OpenVMS

    Level 30 is appropriate for UNIX like programs such as BASH and
    GNV.

    The DECC$UNIX_LEVEL values and associated groups of affected
    feature logical names are:

    General Corrections          (DECC$UNIX_LEVEL 1)

       DECC$FIXED_LENGTH_SEEK_TO_EOF   1
       DECC$POSIX_SEEK_STREAM_FILE     1
       DECC$SELECT_IGNORES_INVALID_FD  1
       DECC$STRTOL_ERANGE              1
       DECC$VALIDATE_SIGNAL_IN_KILL    1

    General Enhancements        (DECC$UNIX_LEVEL 10)

       DECC$ARGV_PARSE_STYLE           1
       DECC$EFS_CASE_PRESERVE          1
       DECC$STDIO_CTX_EOL              1
       DECC$PIPE_BUFFER_SIZE           4096
       DECC$USE_RAB64                  1

    UNIX style filenames       (DECC$UNIX_LEVEL 20)

       DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION 1
       DECC$EFS_CHARSET                1
       DECC$FILENAME_UNIX_NO_VERSION   1
       DECC$FILENAME_UNIX_REPORT       1
       DECC$READDIR_DROPDOTNOTYPE      1
       DECC$RENAME_NO_INHERIT          1
       DECC$GLOB_UNIX_STYLE

    UNIX like file attributes     (DECC$UNIX_LEVEL 30)

       DECC$EFS_FILE_TIMESTAMPS        1
       DECC$EXEC_FILEATTR_INHERITANCE  1
       DECC$FILE_OWNER_UNIX            1
       DECC$FILE_PERMISSION_UNIX       1
       DECC$FILE_SHARING               1

    UNIX compliant behavior       (DECC$UNIX_LEVEL 90)

       DECC$FILENAME_UNIX_ONLY         1
       DECC$POSIX_STYLE_UID            1
       DECC$USE_JPI$_CREATOR           1
       DECC$DETACHED_CHILD_PROCESS     1

                                  NOTES

       o  Defining a logical name for an individual feature logical
          supersedes the default value established by DECC$UNIX_
          LEVEL for that feature.

       o  Future revisions of the C RTL may add new feature
          logicals to a given DECC$UNIX_LEVEL. For applications
          that specify that UNIX level, the effect is to enable
          those new feature logicals by default.

2.48  –  DECC$UNIX_PATH_BEFORE_LOGNAME

    With DECC$UNIX_PATH_BEFORE_LOGNAME enabled, when translating
    a UNIX filename not starting with a leading slash (/), an
    attempt is made to match this to a file or directory in the
    current directory. If this is not found and the name is valid
    as a logical name in an OpenVMS filename, an attempt is made to
    translate the logical name and, if found, is used as part of the
    resulting filename.

    Enabling DECC$UNIX_PATH_BEFORE_LOGNAME overrides the setting for
    DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION.

2.49  –  DECC$USE_JPI$_CREATOR

    When enabled, DECC$USE_JPI$_CREATOR determines the parent process
    ID in getppid by calling $GETJPI using item JPI$_CREATOR instead
    of JPI$_OWNER.

    This feature is only available on systems supporting POSIX style
    session identifiers.

2.50  –  DECC$USE_RAB64

    With DECC$USE_RAB64 enabled, open functions allocate a RAB64
    structure instead of the traditional RAB structure.

    This provides latent support for file buffers in 64-bit memory.

2.51  –  DECC$VALIDATE_SIGNAL_IN_KILL

    With DECC$VALIDATE_SIGNAL_IN_KILL enabled, a signal value that
    is in the range 0 to _SIG_MAX but is not supported by the C RTL
    generates an error with errno set to EINVAL, which makes the
    behavior the same as for raise.

    With this logical name disabled, validation of signals is
    restricted to checking that the signal value is in the range 0 to
    _SIG_MAX. If sys$sigprc fails, errno is set based on sys$sigprc
    exit status.

2.52  –  DECC$V62_RECORD_GENERATION

    OpenVMS Versions 6.2 and higher can output record files using
    different rules.

    With DECC$V62_RECORD_GENERATION enabled, the output mechanism
    follows the rules used for OpenVMS Version 6.2.

2.53  –  DECC$WRITE_SHORT_RECORDS

    The DECC$WRITE_SHORT_RECORDS feature logical supports a previous
    change to the fwrite function (to accommodate writing records
    with size less than the maximum record size), while retaining
    the legacy way of writing records to a fixed-length file as the
    default behavior:

    With DECC$WRITE_SHORT_RECORDS enabled, short-sized records
    (records with size less than the maximum record size) written at
    EOF are padded with zeros to align records on record boundaries.
    This is the behavior seen in OpenVMS Version 7.3-1 and some ACRTL
    ECOs of that time period.

    With DECC$WRITE_SHORT_RECORDS disabled, the legacy behavior
    of writing records with no padding is implemented. This is the
    recommended and default behavior.

2.54  –  DECC$XPG4_STRPTIME

    XPG5 support for strptime introduces pivoting year support so
    that years in the range 0 to 68 are in the 21st century, and
    years in the range 69-99 are in the 20th century.

    With DECC$XPG4_STRPTIME enabled, XPG5 support for the pivoting
    year is disabled and all years in the range 0 to 99 are in the
    current century.

3  –  a64l

    Converts a character string to a long integer.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      long a64l  (const char *s);

3.1  –  Argument

 s

    Pointer to the character string that is to be converted to a long
    integer.

3.2  –  Description

    The a64l and l64a functions are used to maintain numbers stored
    in base-64 ASCII characters as follows:

    o  a64l converts a character string to a long integer.

    o  l64a converts a long integer to a character string.

    Each character used for storing a long integer represents a
    numeric value from 0 through 63. Up to six characters can be
    used to represent a long integer.

    The characters are translated as follows:

    o  A period (.)  represents 0.

    o  A slash (/)  represents 1.

    o  The numbers 0 through 9 represent 2 through 11.

    o  Uppercase letters A through Z represent 12 through 37.

    o  Lowercase letters a through z represent 38 through 63.

    The a64l function takes a pointer to a base-64 representation,
    in which the first digit is the least significant, and returns
    a corresponding long value. If the string pointed to by the s
    parameter exceeds six characters, a64l uses only the first six
    characters.

    If the first six characters of the string contain a null
    terminator, a64l uses only characters preceding the null
    terminator.

    The a64l function translates a character string from left to
    right with the least significant number on the left, decoding
    each character as a 6-bit base-64 number.

    If s is the NULL pointer or if the string pointed to by s was
    not generated by a previous call to l64a, the behavior of a64l is
    unspecified.

    See also l64a.

3.3  –  Return Values

    n                  Upon successful completion, the long value
                       resulting from conversion of the input string.
    0L                 Indicates that the string pointed to by s is
                       an empty string.

4  –  abort

    Sends the signal SIGABRT that terminates execution of the
    program.

    Format

      #include  <stdlib.h>

      void abort  (void);

5  –  abs

    Returns the absolute value of an integer.

    Format

      #include  <stdlib.h>

      int abs  (int x);

5.1  –  Argument

 x

    An integer.

5.2  –  Return Value

    x                  The absolute value of the input argument. If
                       the argument is LONG_MIN, abs returns LONG_
                       MIN because -LONG_MIN cannot fit in an int
                       variable.

6  –  access

    Checks a file to see whether a specified access mode is allowed.

                                   NOTE

       The access function does not accept network files as
       arguments.

    Format

      #include  <unistd.h>

      int access  (const char *file_spec, int mode);

6.1  –  Arguments

 file_spec

    A character string that gives an OpenVMS or UNIX style file
    specification. The usual defaults and logical name translations
    are applied to the file specification.

 mode

    Interpreted as shown in Interpretation of the mode Argument.

    Table REF-1 Interpretation of the mode Argument

    Mode
    Argument     Access Mode

    F_OK         Tests to see if the file exists
    X_OK         Execute
    W_OK         Write (implies delete access)
    R_OK         Read

    Combinations of access modes are indicated by ORing the values.
    For example, to check to see if a file has RWED access mode,
    invoke access as follows:

    access (file_spec, R_OK | W_OK | X_OK);

6.2  –  Description

    The access function checks a file to see whether a specified
    access mode is allowed. If the DECC$ACL_ACCESS_CHECK feature
    logical is enabled, this function checks OpenVMS Access Control
    Lists (ACLs) as well as the UIC protection.

6.3  –  Return Values

    0                  Indicates that the access is allowed.
    -1                 Indicates that the access is not allowed.

6.4  –  Example

        #include <unistd.h>
        #include <stdlib.h>
        #include <stdio.h>

        main()
        {
            if (access("sys$login:login.com", F_OK)) {
                perror("ACCESS - FAILED");
                exit(2);
            }
        }

7  –  acos

    Returns the arc cosine of its argument.

    Format

      #include  <math.h>

      double acos  (double x);

      float acosf  (float x); (Integrity servers, Alpha)

      long double acosl  (long double x); (Integrity servers, Alpha)

      double acosd  (double x); (Integrity servers, Alpha)

      float acosdf  (float x); (Integrity servers, Alpha)

      long double acosdl  (long double x);

                          (Integrity servers, Alpha)

7.1  –  Argument

 x

    A radian expressed as a real value in the domain [-1,1].

7.2  –  Description

    The acos functions compute the principal value of the arc cosine
    of x in the range [0,pi] radians for x in the domain [-1,1].

    The acosd functions compute the principal value of the arc cosine
    of x in the range [0,180] degrees for x in the domain [-1,1].

    For abs(x) > 1, the value of acos(x) is 0, and errno is set to
    EDOM.

8  –  acosh

    Returns the hyperbolic arc cosine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double acosh  (double x);

      float acoshf  (float x);

      long double acoshl  (long double x);

8.1  –  Argument

 x

    A radian expressed as a real value in the domain [1, +Infinity].

8.2  –  Description

    The acosh functions return the hyperbolic arc cosine of x for x
    in the domain [1, +Infinity], where acosh(x) = ln(x + sqrt(x**2 -
    1)).

    The acosh function is the inverse function of cosh where
    acosh(cosh(x)) = |x|.

    x < 1 is an invalid argument.

9  –  [w]addch

    Add a character to the window at the current position of the
    cursor.

    Format

      #include  <curses.h>

      int addch  (char ch);

      int waddch  (WINDOW *win, char ch);

9.1  –  Arguments

 win

    A pointer to the window.

 ch

    The character to be added. A new-line character (\n) clears the
    line to the end, and moves the cursor to the next line at the
    same x coordinate. A return character (\r) moves the cursor to
    the beginning of the line on the window. A tab character (\t)
    moves the cursor to the next tabstop within the window.

9.2  –  Description

    When the waddch function is used on a subwindow, it writes the
    character onto the underlying window as well.

    The addch routine performs the same function as waddch, but on
    the stdscr window.

    The cursor is moved after the character is written to the screen.

9.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that writing the character would
                       cause the screen to scroll illegally. For more
                       information, see the scrollok function.

10  –  [w]addstr

    Add the string pointed to by str to the window at the current
    position of the cursor.

    Format

      #include  <curses.h>

      int addstr  (char *str);

      int waddstr  (WINDOW *win, char *str);

10.1  –  Arguments

 win

    A pointer to the window.

 str

    A pointer to a character string.

10.2  –  Description

    When the waddstr function is used on a subwindow, the string is
    written onto the underlying window as well.

    The addstr routine performs the same function as waddstr, but on
    the stdscr window.

    The cursor position changes as a result of calling this routine.

10.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function causes the screen
                       to scroll illegally, but it places as much of
                       the string onto the window as possible. For
                       more information, see the scrollok function.

11  –  alarm

    Sends the signal SIGALRM (defined in the <signal.h> header file)
    to the invoking process after the number of seconds indicated by
    its argument has elapsed.

    Format

      #include  <unistd.h>

      unsigned int alarm  (unsigned int seconds); (ISO POSIX-1)

      int alarm  (unsigned int seconds); (Compatibility)

11.1  –  Argument

 seconds

    Has a maximum limit of LONG_MAX seconds.

11.2  –  Description

    Calling the alarm function with a 0 argument cancels any pending
    alarms.

    Unless it is intercepted or ignored, the signal generated by
    alarm terminates the process. Successive alarm calls reinitialize
    the alarm clock. Alarms are not stacked.

    Because the clock has a 1-second resolution, the signal may
    occur up to 1 second early. If the SIGALRM signal is intercepted,
    resumption of execution may be held up due to scheduling delays.

    When the SIGALRM signal is generated, a call to SYS$WAKE is
    generated whether or not the process is hibernating. The pending
    wake causes the current pause() to return immediately (after
    completing any function that catches the SIGALRM).

11.3  –  Return Value

    n                  The number of seconds remaining from a
                       previous alarm request.

12  –  asctime

    Converts a broken-down time in a tm structure into a 26-character
    string in the following form:

    Sun Sep 16 01:03:52 1984\n\0

    All fields have a constant width.

    Format

      #include  <time.h>

      char *asctime  (const struct tm *timeptr);

      char *asctime_r  (const struct tm *timeptr, char *buffer);

                                                  (ISO POSIX-1)

12.1  –  Arguments

 timeptr

    A pointer to a structure of type tm, which contains the broken-
    down time.

    The tm structure is defined in the <time.h> header file, and also
    shown in tm Structure in the description of localtime.

 buffer

    A pointer to a character array that is at least 26 bytes long.
    This array is used to store the generated date-and-time string.

12.2  –  Description

    The asctime and asctime_r functions convert the contents of tm
    into a 26-character string and returns a pointer to the string.

    The difference between asctime_r and asctime is that the former
    puts the result into a user-specified buffer. The latter puts
    the result into thread-specific static memory allocated by the
    C RTL, which can be overwritten by subsequent calls to
    ctime or asctime; you must make a copy if you want to save it.

    On success, asctime returns a pointer to the string; asctime_r
    returns its second argument. On failure, these functions return
    the NULL pointer.

    See the localtime function for a list of the members in tm.

                                   NOTE

       Generally speaking, UTC-based time functions can affect in-
       memory time-zone information, which is processwide data.
       However, if the system time zone remains the same during
       the execution of the application (which is the common case)
       and the cache of timezone files is enabled (which is the
       default), then the _r variant of the time functions asctime_
       r, ctime_r, gmtime_r and localtime_r, is both thread-safe
       and AST-reentrant.

       If, however, the system time zone can change during the
       execution of the application or the cache of timezone files
       is not enabled, then both variants of the UTC-based time
       functions belong to the third class of functions, which are
       neither thread-safe nor AST-reentrant.

12.3  –  Return Values

    x                  A pointer to the string, if successful.
    NULL               Indicates failure.

13  –  asin

    Returns the arc sine of its argument.

    Format

      #include  <math.h>

      double asin  (double x);

      float asinf  (float x); (Integrity servers, Alpha)

      long double asinl  (long double x); (Integrity servers, Alpha)

      double asind  (double x); (Integrity servers, Alpha)

      float asindf  (float x); (Integrity servers, Alpha)

      long double asindl  (long double x);

                          (Integrity servers, Alpha)

13.1  –  Argument

 x

    A radian expressed as a real number in the domain [-1,1].

13.2  –  Description

    The asin functions compute the principal value of the arc sine of
    x in the range [-pi/2,pi/2] radians for x in the domain [-1,1].

    The asind functions compute the principal value of the arc sine
    of x in the range [-90,90] degrees for x in the domain [-1,1].

    When abs(x) is greater than 1.0, the value of asin(x) is 0, and
    errno is set to EDOM.

14  –  asinh

    Returns the hyperbolic arc sine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double asinh  (double x);

      float asinhf  (float x);

      long double asinhl  (long double x);

14.1  –  Argument

 x

    A radian expressed as a real value in the domain [-Infinity,
    +Infinity].

14.2  –  Description

    The asinh functions return the hyperbolic arc sine of x for x
    in the domain [-Infinity, +Infinity], where asinh(x) = ln(x +
    sqrt(x**2 + 1)).

    The asinh function is the inverse function of sinh where
    asinh(sinh(x)) = x.

15  –  assert

    Used for implementing run-time diagnostics in programs.

    Format

      #include  <assert.h>

      void assert  (int expression);

15.1  –  Argument

 expression

    An expression that has an int type.

15.2  –  Description

    When assert is executed, if expression is false (that is, it
    evaluates to 0), assert writes information about the particular
    call that failed (including the text of the argument, the name of
    the source file, and the source line number; the latter two are,
    respectively, the values of the preprocessing macros __FILE__
    and __LINE__)  to the standard error file in an implementation-
    defined format. Then, it calls the abort function.

    The assert function writes a message in the following form:

    Assertion failed:  expression, file aaa, line nnn

    If expression is true (that is, it evaluates to nonzero) or if
    the signal SIGABRT is being ignored, assert returns no value.

                                   NOTE

       If a null character ('\0') is part of the expression being
       asserted, then only the text up to and including the null
       character is printed, since the null character effectively
       terminates the string being output.

    Compiling with the CC command qualifier /DEFINE=NDEBUG or with
    the preprocessor directive #define NDEBUG ahead of the #include
    assert statement causes the assert function to have no effect.

15.3  –  Example

        #include <stdio.h>
        #include <assert.h>

        main()
        {
            printf("Only this and the assert\n");
            assert(1 == 2);     /* expression is FALSE */

    /* abort should be called so the printf will not happen. */

            printf("FAIL abort did not execute");
        }

16  –  atan

    Format

      #include  <math.h>

      double atan  (double x);

      float atanf  (float x); (Integrity servers, Alpha)

      long double atanl  (long double x); (Integrity servers, Alpha)

      double atand  (double x); (Integrity servers, Alpha)

      float atandf  (float x); (Integrity servers, Alpha)

      long double atandl  (long double x);

                          (Integrity servers, Alpha)

16.1  –  Argument

 x

    A radian expressed as a real number.

16.2  –  Description

    The atan functions compute the principal value of the arc tangent
    of x in the range [-pi/2,pi/2] radians.

    The atand functions compute the principal value of the arc
    tangent of x in the range [-90,90] degrees.

17  –  atan2

    Format

      #include  <math.h>

      double atan2  (double y, double x);

      float atan2f  (float y, float x); (Integrity servers, Alpha)

      long double atan2l  (long double y, long double x);

                          (Integrity servers, Alpha)

      double atand2  (double y, double x);

                     (Integrity servers, Alpha)

      float atand2f  (float y, float x); (Integrity servers, Alpha)

      long double atand2l  (long double y, long double x);

                           (Integrity servers, Alpha)

17.1  –  Arguments

 y

    A radian expressed as a real number.

 x

    A radian expressed as a real number.

17.2  –  Description

    The atan2 functions compute the principal value of the arc
    tangent of y/x in the range [-pi,pi] radians. The sign of
    atan2 and atan2f is determined by the sign of y. The value of
    atan2(y,x) is computed as follows, where f is the number of
    fraction bits associated with the data type:

    Value of Input
    Arguments          Angle Returned

    x = 0 or y/x >     pi/2 * (sign y)
    2**(f+1)
    x > 0 and y/x <=   atan(y/x)
    2**(f+1)
    x < 0 and y/x <=   pi * (sign y) + atan(y/x)
    2**(f+1)

    The atand2 functions compute the principal value of the arc
    tangent of y/x in the range [-180,180] degrees. The sign of
    atand2 and atand2f is determined by the sign of y.

    The following are invalid arguments for the atan2 and atand2
    functions:

    Function                  Exceptional Argument

    atan2, atan2f, atan2l     x = y = 0
    atan2, atan2f, atan2l     |x| = |y| = Infinity
    atand2, atand2f, atand2l  x = y = 0
    atand2, atand2f, atand2l  |x| = |y| = Infinity

18  –  atanh

    Returns the hyperbolic arc tangent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double atanh  (double x);

      float atanhf  (float x);

      long double atanhl  (long double x);

18.1  –  Argument

 x

    A radian expressed as a real value in the domain [-1,1].

18.2  –  Description

    The atanh functions return the hyperbolic arc tangent of x.
    The atanh function is the inverse function of tanh where
    atanh(tanh(x)) = x.

    |x| > 1 is an invalid argument.

19  –  atexit

    Registers a function that is called without arguments at program
    termination.

    Format

      #include  <stdlib.h>

      int atexit  (void (*func) (void));

19.1  –  Argument

 func

    A pointer to the function to be registered.

19.2  –  Return Values

    0                  Indicates that the registration has succeeded.
    nonzero            Indicates failure.

19.3  –  Restriction

    The longjmp function cannot be executed from within the handler,
    because the destination address of the longjmp no longer exists.

19.4  –  Example

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

        static void hw(void);

        main()
        {
            atexit(hw);
        }

        static void hw()
        {
                puts("Hello, world\n");
        }

      Running this example produces the following output:

        Hello, world

20  –  atof

    Converts an ASCII character string to a double-precision number.

    Format

      #include  <stdlib.h>

      double atof  (const char *nptr);

20.1  –  Argument

 nptr

    A pointer to the character string to be converted to a double-
    precision number. The string is interpreted by the same rules
    that are used to interpret floating constants.

20.2  –  Description

    The string to be converted has the following format:

    [white-spaces][+|-]digits[radix-character][digits][e|E[+|-]integer]

    Where radix-character is defined in the current locale.

    The first unrecognized character ends the conversion.

    This function is equivalent to strtod(nptr, (char**) NULL).

20.3  –  Return Values

    x                  The converted value.
    0                  Indicates an underflow or the conversion could
                       not be performed. The function sets errno to
                       ERANGE or EINVAL, respectively.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.

21  –  atoi,atol

    Convert strings of ASCII characters to the appropriate numeric
    values.

    Format

      #include  <stdlib.h>

      int atoi  (const char *nptr);

      long int atol  (const char *nptr);

21.1  –  Argument

 nptr

    A pointer to the character string to be converted to a numeric
    value.

21.2  –  Description

    The atoi and atol functions convert the initial portion of a
    string to its decimal int or long int value, respectively. The
    atoi and atol functions do not account for overflows resulting
    from the conversion. The string to be converted has the following
    format:

    [white-spaces][+|-]digits

    The function call atol (str) is equivalent to strtol (str,
    (char**)NULL, 10), and the function call atoi (str) is equivalent
    to (int) strtol (str, (char**)NULL, 10), except, in both cases,
    for the behavior on error.

21.3  –  Return Value

    n                  The converted value.

22  –  atoq,atoll

    Convert strings of ASCII characters to the appropriate numeric
    values. atoll is a synonym for atoq.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      __int64 atoq  (const char *nptr);

      __int64 atoll  (const char *nptr);

22.1  –  Argument

 nptr

    A pointer to the character string to be converted to a numeric
    value.

22.2  –  Description

    The atoq (or atoll) function converts the initial portion of
    a string to its decimal __int64 value. This function does not
    account for overflows resulting from the conversion. The string
    to be converted has the following format:

    [white-spaces][+|-]digits

    The function call atoq (str) is equivalent to strtoq (str,
    (char**)NULL, 10), except for the behavior on error.

22.3  –  Return Value

    n                  The converted value.

23  –  basename

    Returns the last component of a pathname.

    Format

      #include  <libgen.h>

      char *basename  (char *path);

23.1  –  Function Variants

    The basename function has variants named _basename32 and
    _basename64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

23.2  –  Argument

 path

    A UNIX style pathname from which the base pathname is extracted.

23.3  –  Description

    The basename function takes the UNIX style pathname pointed to
    by path and returns a pointer to the pathname's final component,
    deleting any trailing slash (/)  characters.

    If path consists entirely of the slash (/)  character, the
    function returns a pointer to the string "/".

    If path is a NULL pointer or points to an empty string, the
    function returns a pointer to the string ".".

    The basename function can modify the string pointed to by path.

23.4  –  Return Values

    x                  A pointer to the final component of path.
    "/"                If path consists entirely of the '/'
                       character.
    "."                If path is a NULL pointer or points to an
                       empty string.

24  –  bcmp

    Compares byte strings.

    Format

      #include  <strings.h>

      void bcmp  (const void *string1, const void *string2, size_t length);

24.1  –  Arguments

 string1, string2

    The byte strings to be compared.

 length

    The length (in bytes) of the strings.

24.2  –  Description

    The bcmp function compares the byte string in string1 against the
    byte string in string2.

    Unlike the string functions, there is no checking for null bytes.
    Zero-length strings are always identical.

    Note that bcmp is equivalent to memcmp, which is defined by
    the ANSI C Standard. Therefore, using memcmp is recommended for
    portable programs.

24.3  –  Return Values

    0                  The strings are identical.
    Nonzero            The strings are not identical.

25  –  bcopy

    Copies byte strings.

    Format

      #include  <strings.h>

      void bcopy  (const void *source, void *destination, size_t length);

25.1  –  Arguments

 source

    Pointer to the source string.

 destination

    Pointer to the destination string.

 length

    The length (in bytes) of the string.

25.2  –  Description

    The bcopy function operates on variable-length strings of bytes.
    It copies the value of the length argument, in bytes, from the
    string in the source argument to the string in the destination
    argument.

    Unlike the string functions, there is no checking for null bytes.
    If the length argument is 0 (zero), no bytes are copied.

    Note that bcopy is equivalent to memcpy, which is defined by
    the ANSI C Standard. Therefore, using memcpy is recommended for
    portable programs.

26  –  box

    Draws a box around the window using the character vert as the
    character for drawing the vertical lines of the rectangle, and
    hor for drawing the horizontal lines of the rectangle.

    Format

      #include  <curses.h>

      int box  (WINDOW *win, char vert, char hor);

26.1  –  Arguments

 win

    The address of the window.

 vert

    The character for the vertical edges of the window.

 hor

    The character for the horizontal edges of the window.

26.2  –  Description

    The box function copies boxes drawn on subwindows onto the
    underlying window. Use caution when using functions such as
    overlay and overwrite with boxed subwindows. Such functions copy
    the box onto the underlying window.

26.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

27  –  brk

    Determines the lowest virtual address that is not used with the
    program.

    Format

      #include  <stdlib.h>

      void *brk  (unsigned long int addr);

27.1  –  Argument

 addr

    The lowest address, which the function rounds up to the next
    multiple of the page size. This rounded address is called the
    break address.

27.2  –  Description

    An address that is greater than or equal to the break address
    and less than the stack pointer is considered to be outside the
    program's address space. Attempts to reference it will cause
    access violations.

    When a program is executed, the break address is set to the
    highest location defined by the program and data storage areas.
    Consequently, brk is needed only by programs that have growing
    data areas.

27.3  –  Return Values

    n                  The new break address.
    (void *)(-1)       Indicates that the program is requesting too
                       much memory. errno and vaxc$errno are updated.

27.4  –  Restriction

    Unlike other C library implementations, the C RTL memory
    allocation functions (such as malloc) do not rely on brk or
    sbrk to manage the program heap space. Consequently, on OpenVMS
    systems, calling brk or sbrk can interfere with memory allocation
    routines. The brk and sbrk functions are provided only for
    compatibility purposes.

28  –  bsearch

    Performs a binary search. It searches an array of sorted objects
    for a specified object.

    Format

      #include  <stdlib.h>

      void *bsearch  (const void *key, const void *base, size_t
                      nmemb, size_t size, int (*compar)
                     (const void *, const void *));

28.1  –  Function Variants

    The bsearch function has variants named _bsearch32 and _bsearch64
    for use with 32-bit and 64-bit pointer sizes, respectively.

28.2  –  Arguments

 key

    A pointer to the object to be sought in the array. This pointer
    should be of type pointer-to-object and cast to type pointer-to-
    void.

 base

    A pointer to the initial member of the array. This pointer should
    be of type pointer-to-object and cast to type pointer-to-void.

 nmemb

    The number of objects in the array.

 size

    The size of an object, in bytes.

 compar

    A pointer to the comparison function.

28.3  –  Description

    The array must first be sorted in increasing order according to
    the specified comparison function pointed to by compar.

    Two arguments are passed to the comparison function pointed to
    by compar. The two arguments point to the objects being compared.
    Depending on whether the first argument is less than, equal to,
    or greater than the second argument, the comparison function must
    return an integer less than, equal to, or greater than 0.

    It is not necessary for the comparison function (compar) to
    compare every byte in the array. Therefore, the objects in the
    array can contain arbitrary data in addition to the data being
    compared.

    Since it is declared as type pointer-to-void, the value returned
    must be cast or assigned into type pointer-to-object.

28.4  –  Return Values

    x                  A pointer to the matching member of the array
                       or a null pointer if no match is found.
    NULL               Indicates that the key cannot be found in the
                       array.

28.5  –  Example

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

 #define SSIZE 30

 extern int compare();  /* prototype for comparison function */

 int array[SSIZE] = {30, 1, 29, 2, 28, 3, 27, 4, 26, 5,
                     24, 6, 23, 7, 22, 8, 21, 9, 20, 10,
                     19, 11, 18, 12, 17, 13, 16, 14, 15, 25};

  /*  This program takes an unsorted array, sorts it using qsort, */
  /*  and then calls bsearch for each element in the array,       */
  /*  making sure that bsearch returns the correct element.       */

 main()
 {
     int i;
     int failure = FALSE;
     int *rkey;

     qsort(array, SSIZE, sizeof (array[0]), &compare);

     /* search for each element */
     for (i = 0; i < SSIZE - 1; i++) {
         /* search array element i */
         rkey = bsearch((array + i), array, SSIZE,
                         sizeof(array[0]), &compare);
         /* check for successful search */
         if (&array[i] != rkey) {
             printf("Not in array, array element %d\n", i);
             failure = TRUE;
             break;
         }
     }
     if (!failure)
         printf("All elements successfully found!\n");
 }

  /*  Simple comparison routine.  */
  /*                              */
  /*  Returns:  = 0 if a == b     */
  /*            < 0 if a < b      */
  /*            > 0 if a > b      */

 int compare(int *a, int *b)
 {
     return (*a - *b);
 }

      This example program outputs the following:

        All elements successfully found!

29  –  btowc

    Converts a one-byte multibyte character to a wide character in
    the initial shift state.

    Format

      #include  <wchar.h>

      wint_t btowc  (int c);

29.1  –  Argument

 c

    The character to be converted to a wide-character representation.

29.2  –  Description

    The btowc function determines whether (unsigned char)c is a valid
    one-byte multibyte character in the initial shift state, and if
    so, returns a wide-character representation of that character.

29.3  –  Return Values

    x                  The wide-character representation of unsigned
                       char c.
    WEOF               Indicates an error. The c argument has the
                       value EOF or does not constitute a valid one-
                       byte multibyte character in the initial shift
                       state.

30  –  bzero

    Copies null characters into byte strings.

    Format

      #include  <strings.h>

      void bzero  (void *string, size_t length);

30.1  –  Arguments

 string

    Specifies the byte string into which you want to copy null
    characters.

 length

    Specifies the length (in bytes) of the string.

30.2  –  Description

    The bzero function copies null characters ('\0') into the byte
    string pointed to by string for length bytes. If length is 0
    (zero), then no bytes are copied.

31  –  cabs

    Returns the absolute value of a complex number.

    Format

      #include  <math.h>

      double cabs  (cabs_t z);

      float cabsf  (cabsf_t z); (Integrity servers, Alpha)

      long double cabsl  (cabsl_t z); (Integrity servers, Alpha)

31.1  –  Argument

 z

    A structure of type cabs_t, cabsf_t, or cabsl_t. These types are
    defined in the <math.h> header file as follows:

    typedef struct {double x,y;} cabs_t;

    typedef struct { float x, y; } cabsf_t; (Integrity servers, Alpha)
    typedef struct { long double x, y; } cabsl_t; (Integrity servers, Alpha)

31.2  –  Description

    The cabs functions return the absolute value of a complex number
    by computing the Euclidean distance between its two points as the
    square root of their respective squares:

    sqrt(x2 + y2)

    On overflow, the return value is undefined.

    The cabs, cabsf, and cabsl functions are equivalent to the hypot,
    hypotf, and hypotl functions, respectively.

32  –  cacos

    Returns the complex arc cosine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex cacos  (double complex z);

      float complex cacosf  (float complex z);

      long double complex cacosl  (long double complex z);

32.1  –  Argument

 z

    A complex value.

32.2  –  Description

    The cacos functions compute the complex arc cosine of z, with
    branch cuts outside the interval [-1, +1] along the real axis.

32.3  –  Return Values

    n                  The complex arc cosine value, in the range
                       of a strip mathematically unbounded along the
                       imaginary axis and in the interval [0, &#960;]
                       along the real axis.

33  –  cacosh

    Returns the complex arc hyperbolic cosine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex cacosh  (double complex z);

      float complex cacoshf  (float complex z);

      long double complex cacoshl  (long double complex z);

33.1  –  Argument

 z

    A complex value.

33.2  –  Description

    The cacosh functions compute the complex arc hyperbolic cosine of
    z, with a branch cut at values less than 1 along the real axis.

33.3  –  Return Values

    n                  The complex arc hyperbolic cosine value, in
                       the range of a half-strip of non-negative
                       values along the real axis and in the interval
                       [-i&#960;, +i&#960;] along the imaginary axis.

34  –  calloc

    Allocates an area of zeroed memory. This function is AST-
    reentrant.

    Format

      #include  <stdlib.h>

      void *calloc  (size_t number, size_t size);

34.1  –  Function Variants

    The calloc function has variants named _calloc32 and _calloc64
    for use with 32-bit and 64-bit pointer sizes, respectively.

34.2  –  Arguments

 number

    The number of items to be allocated.

 size

    The size of each item.

34.3  –  Description

    The calloc function initializes the items to 0. The maximum
    amount of memory allocated at once is limited to 0xFFFFD000.

    See also malloc and realloc.

34.4  –  Return Values

    x                  The address of the first byte, which
                       is aligned on a quadword boundary
                       (Alpha only) or an octaword boundary
                       (Integrity servers(ONLY)) .
    NULL               Indicates an inability to allocate the space.

35  –  carg

    Returns the phase angle of its complex argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double carg  (double complex z);

      float cargf  (float complex z);

      long double cargl  (long double complex z);

35.1  –  Argument

 z

    A complex value.

35.2  –  Description

    The carg functions compute the argument (also called phase angle)
    of z, with a branch cut along the negative real axis.

35.3  –  Return Values

    n                  The value of the argument of z, in the
                       interval [-&#960;, +&#960;].

36  –  casin

    Returns the complex arc sine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex casin  (double complex z);

      float complex casinf  (float complex z);

      long double complex casinl  (long double complex z);

36.1  –  Argument

 z

    A complex value.

36.2  –  Description

    The casin functions compute the complex arc sine of z, with
    branch cuts outside the interval [-1, +1] along the real axis.

36.3  –  Return Values

    n                  The complex arc sine value, in the range of
                       a strip mathematically unbounded along the
                       imaginary axis and in the interval [-&#960;/2,
                       +&#960;/2] along the real axis.

37  –  casinh

    Returns the complex arc hyperbolic sine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex casinh  (double complex z);

      float complex casinhf  (float complex z);

      long double complex casinhl  (long double complex z);

37.1  –  Argument

 z

    A complex value.

37.2  –  Description

    The casinh functions compute the complex arc hyperbolic sine
    of z, with branch cuts outside the interval [-i, +i] along the
    imaginary axis.

37.3  –  Return Values

    n                  The complex arc hyperbolic sine value, in the
                       range of a strip mathematically unbounded
                       along the real axis and in the interval
                       [-i&#960;/2, +i&#960;/2] along the imaginary
                       axis.

38  –  catan

    Returns the complex arc tangent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex catan  (double complex z);

      float complex catanf  (float complex z);

      long double complex catanl  (long double complex z);

38.1  –  Argument

 z

    A complex value.

38.2  –  Description

    The catan functions compute the complex arc tangent of z, with
    branch cuts outside the interval [-i, +i] along the imaginary
    axis.

38.3  –  Return Values

    n                  The complex arc tangent value, in the range
                       of a strip mathematically unbounded along the
                       imaginary axis and in the interval [-&#960;/2,
                       +&#960;/2] along the real axis.

39  –  catanh

    Returns the complex arc hyperbolic tangent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex catanh  (double complex z);

      float complex catanhf  (float complex z);

      long double complex catanhl  (long double complex z);

39.1  –  Argument

 z

    A complex value.

39.2  –  Description

    The catanh functions compute the complex arc hyperbolic tangent
    of z, with branch cuts outside the interval [-1, +1] along the
    imaginary axis.

39.3  –  Return Values

    n                  The complex arc hyperbolic tangent value, in
                       the range of a strip mathematically unbounded
                       along the real axis and in the interval
                       [-i&#960;/2, +i&#960;/2] along the imaginary
                       axis.

40  –  catclose

    Closes a message catalog.

    Format

      #include  <nl_types.h>

      int catclose  (nl_catd catd);

40.1  –  Argument

 catd

    A message catalog descriptor. This is returned by a successful
    call to catopen.

40.2  –  Description

    The catclose function closes the message catalog referenced by
    catd and frees the catalog file descriptor.

40.3  –  Return Values

    0                  Indicates that the catalog was successfully
                       closed.
    -1                 Indicates that an error occurred. The function
                       sets errno to the following value:

                       o  EBADF - The catalog descriptor is not
                          valid.

41  –  catgets

    Retrieves a message from a message catalog.

    Format

      #include  <nl_types.h>

      char *catgets  (nl_catd catd, int set_id, int msg_id, const char *s);

41.1  –  Function Variants

    The catgets function has variants named _catgets32 and _catgets64
    for use with 32-bit and 64-bit pointer sizes, respectively.

41.2  –  Arguments

 catd

    A message catalog descriptor. This is returned by a successful
    call to catopen.

 set_id

    An integer set identifier.

 msg_id

    An integer message identifier.

 s

    A pointer to a default message string that is returned by the
    function if the message cannot be retrieved.

41.3  –  Description

    The catgets function retrieves a message identified by set_id
    and msg_id, in the message catalog catd. The message is stored in
    a message buffer in the nl_catd structure, which is overwritten
    by subsequent calls to catgets. If a message string needs to
    be preserved, it should be copied to another location by the
    program.

41.4  –  Return Values

    x                  Pointer to the retrieved message.
    s                  Pointer to the default message string.
                       Indicates that the function is not able
                       to retrieve the requested message from
                       the catalog. This condition can arise if
                       the requested pair (set_d, msg_id) does
                       not represent an existing message from the
                       open catalog, or it indicates that an error
                       occurred. If an error occurred, the function
                       sets errno to one of the following values:

                       o  EBADF - The catalog descriptor is not
                          valid.

                       o  EVMSRR - An OpenVMS I/O read error;
                          the OpenVMS error code can be found in
                          vaxc$errno.

41.5  –  Example

 #include <nl_types.h>
 #include <locale.h>
 #include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <unixio.h>

  /* This test makes use of all the message catalog routines. catopen  */
  /* opens the catalog ready for reading, then each of the three       */
  /* messages in the catalog are extracted in turn using catgets and   */
  /* printed out. catclose closes the catalog after use.               */
  /* The catalog source file used to create the catalog is as follows: */
  /* $ This is a message file
  * $
  * $quote "
  * $ another comment line
  * $set 1
  * 1 "First set, first message"
  * 2 "second message - This long message uses a backslash \
  * for continuation."
  * $set 2
  * 1 "Second set, first message"                                      */

 char *default_msg = "this is the first message.";

 main()
 {
   nl_catd catalog;
   int msg1,
       msg2,
       retval;

   char *cat = "sys$disk:[]catgets_example.cat"; /*Force local catalog*/

   char *msgtxt;

   char string[128];

   /* Create the message test catalog */

   system("gencat catgets_example.msgx catgets_example.cat") ;

   if ((catalog = catopen(cat, 0)) == (nl_catd) - 1) {
       perror("catopen");
       exit(EXIT_FAILURE);
   }

   msgtxt = catgets(catalog, 1, 1, default_msg);
   printf("%s\n", msgtxt);

   msgtxt = catgets(catalog, 1, 2, default_msg);
   printf("%s\n", msgtxt);

   msgtxt = catgets(catalog, 2, 1, default_msg);
   printf("%s\n", msgtxt);

   if ((retval = catclose(catalog)) == -1) {
       perror("catclose");
       exit(EXIT_FAILURE);
   }

   delete("catgets_example.cat;") ;  /* Remove the test catalog */
 }

      Running the example program produces the following result:

        First set, first message
        second message - This long message uses a backslash for
                                                  continuation.
        Second set, first message

42  –  catopen

    Opens a message catalog.

    Format

      #include  <nl_types.h>

      nl_catd catopen  (const char *name, int oflag);

42.1  –  Arguments

 name

    The name of the message catalog to open.

 oflag

    An object of type int that determines whether the locale set for
    the LC_MESSAGES category in the current program's locale or the
    logical name LANG is used to search for the catalog file.

42.2  –  Description

    The catopen function opens the message catalog identified by
    name.

    If name contains a colon (:),  a square opening bracket ([), or
    an angle bracket (<),  or is defined as a logical name, then it
    is assumed that name is the complete file specification of the
    catalog.

    If it does not include these characters, catopen assumes that
    name is a logical name pointing to an existing catalog file. If
    name is not a logical name, then the logical name NLSPATH is used
    to define the file specification of the message catalog. NLSPATH
    is defined in the user's process. If the NLSPATH logical name is
    not defined, or no message catalog can be opened in any of the
    components specified by the NLSPATH, then the SYS$NLSPATH logical
    name is used to search for a message catalog file.

    Both NLSPATH and SYS$NLSPATH are comma-separated lists of
    templates. The catopen function uses each template to construct a
    file specification. For example, NLSPATH could be defined as:

 DEFINE NLSPATH SYS$SYSROOT:[SYS$I18N.MSG]%N.CAT,SYS$COMMON:[SYSMSG]%N.CAT

    In this example, catopen first searches the directory
    SYS$SYSROOT:[SYS$I18N.MSG] for the named catalog. If the named
    catalog is not found there, the directory SYS$COMMON:[SYSMSG] is
    searched. The catalog name is constructed by substituting %N with
    the name passed to catopen, and adding the .cat suffix. %N is
    known as a substitution field. The following substitution fields
    are valid:

    Field Meaning

    %N    Substitute the name passed to catopen
    %L    Substitute the locale name.

          The period (.)  and at-sign (@)  characters in the locale
          name are replaced by an underscore (_)  character.

          For example, the "zh_CN.dechanzi@radical" locale name
          results in a substitution of ZH_CN_DECHANZI_RADICAL.
    %l    Substitute the language part of the locale name. For
          example, the language part of the en_GB.ISO8859-1 locale
          name is en.
    %t    Substitute the territory part of the locale name. For
          example, the territory part of the en_GB.ISO8859-1 locale
          is GB.
    %c    Substitute the codeset name from the locale name. For
          example, the codeset name of the en_GB.ISO8859-1 locale
          name is ISO8859-1.

    If the oflag argument is set to NL_CAT_LOCALE, then the
    current locale as defined for the LC_MESSAGES category is
    used to determine the substitution for the %L, %l, %t, and %c
    substitution fields. If the oflag argument is set to 0, then the
    value of the LANG environment variable is used as a locale name
    to determine the substitution for these fields. Note that using
    NL_CAT_LOCALE conforms to the XPG4 specification while a value of
    0 (zero) exists for the purpose of preserving XPG3 compatibility.
    Note also, that catopen uses the value of the LANG environment
    variable without checking whether the program's locale can be set
    using this value. That is, catopen does not check whether this
    value can serve as a valid locale argument in the setlocale call.

    If the substitution value is not defined, an empty string is
    substituted.

    A leading comma or two adjacent commas (,,) is equivalent to
    specifying %N. For example,

    DEFINE NLSPATH ",%N.CAT,SYS$COMMON:[SYSMSG.%L]%N.CAT"

    In this example, catopen searches in the following locations in
    the order shown:

    1. name (in the current directory)

    2. name.cat (in the current directory)

    3. SYS$COMMON:[SYSMSG.locale_name]name.cat

42.3  –  Return Values

    x                  A message catalog file descriptor. Indicates
                       the call was successful. This descriptor is
                       used in calls to catgets and catclose.
    (nl_catd) -1       Indicates an error occurred. The function sets
                       errno to one of the following values:

                       o  EACCES - Insufficient privilege or file
                          protection violation, or file currently
                          locked by another user.

                       o  EMFILE - Process channel count exceeded.

                       o  ENAMETOOLONG - The full file specification
                          for message catalog is too long

                       o  ENOENT - Unable to find the requested
                          message catalog.

                       o  ENOMEM - Insufficient memory available.

                       o  ENOTDIR - Part of the name argument is not
                          a valid directory.

                       o  EVMSERR - An error occurred that does not
                          match any errno value. Check the value of
                          vaxc$errno.

43  –  cbrt

    Returns the rounded cube root of y.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double cbrt  (double y);

      float cbrtf  (float y);

      long double cbrtl  (long double y);

43.1  –  Argument

 y

    A real number.

44  –  ccos

    Returns the complex cosine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex ccos  (double complex z);

      float complex ccosf  (float complex z);

      long double complex ccosl  (long double complex z);

44.1  –  Argument

 z

    A complex value.

44.2  –  Description

    The ccos functions return the complex cosine of z.

44.3  –  Return Values

    x                  The complex cosine value.

45  –  ccosh

    Returns the complex hyperbolic cosine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex ccosh  (double complex z);

      float complex ccoshf  (float complex z);

      long double complex ccoshl  (long double complex z);

45.1  –  Argument

 z

    A complex value.

45.2  –  Description

    The ccosh functions return the complex hyperbolic cosine of z.

45.3  –  Return Values

    x                  The complex hyperbolic cosine value.

46  –  ceil

    Returns the smallest integer that is greater than or equal to its
    argument.

    Format

      #include  <math.h>

      double ceil  (double x);

      float ceilf  (float x); (Integrity servers, Alpha)

      long double ceill  (long double x); (Integrity servers, Alpha)

46.1  –  Argument

 x

    A real value.

46.2  –  Return Value

    n                  The smallest integer greater than or equal to
                       the function argument.

47  –  cexp

    Returns the complex exponent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex cexp  (double complex z);

      float complex cexpf  (float complex z);

      long double complex cexpl  (long double complex z);

47.1  –  Argument

 z

    A complex value.

47.2  –  Description

    The cexp functions compute the complex exponential value of
    z, defined as e**z, where e is the constant used as a base for
    natural logarithms.

47.3  –  Return Values

    x                  The complex exponential value of the argument.

48  –  cfree

    Makes available for reallocation the area allocated by a previous
    calloc, malloc, or realloc call. This function is AST-reentrant.

    Format

      #include  <stdlib.h>

      void cfree  (void *ptr);

48.1  –  Argument

 ptr

    The address returned by a previous call to malloc, calloc, or
    realloc.

48.2  –  Description

    The contents of the deallocated area are unchanged.

    In VSI C for OpenVMS Systems, the free and cfree functions
    are equivalent. Some other C implementations use free with malloc
    or realloc, and cfree with calloc. However, since the ANSI C
    standard does not include cfree, using free may be preferable.

    See also free.

49  –  chdir

    Changes the default directory.

    Format

      #include  <unistd.h>

      int chdir  (const char *dir_spec); (ISO POSIX-1)

      int chdir  (const char *dir_spec, . . . ); (DEC C Extension)

49.1  –  Arguments

 dir_spec

    A null-terminated character string naming a directory in either
    an OpenVMS or UNIX style specification.

  . . .

    This argument is an VSI C extension available when not
    defining any of the standards-related feature-test macros and not
    compiling in strict ANSI C mode (/STANDARD=ANSI89). The argument
    is an optional flag of type int that is significant only when
    calling chdir from USER mode.

    If the value of the flag is 1, the new directory is effective
    across images. If the value is not 1, the original default
    directory is restored when the image exits.

49.2  –  Description

    The chdir function changes the default directory. The change can
    be permanent or temporary. Permanent means that the new directory
    remains as the default directory after the image exits. Temporary
    means that on image exit, the default is set to whatever it was
    before the execution of the image.

    There are two ways of making the change permanent:

    o  Call chdir from USER mode with the second argument set to 1.

    o  Call chdir from SUPERVISOR or EXECUTIVE mode, regardless of
       the value of the second argument.

    Otherwise, the change is temporary.

49.3  –  Return Values

    0                  Indicates that the directory is successfully
                       changed to the given name.
    -1                 Indicates that the change attempt has failed.

50  –  chmod

    Changes the file protection of a file.

    Format

      #include  <stat.h>

      int chmod  (const char *file_spec, mode_t mode);

50.1  –  Arguments

 file_spec

    The name of an OpenVMS or UNIX style file specification.

 mode

    A file protection. Modes are constructed by performing a bitwise
    OR on any of the values shown in File Protection Values and Their
    Meanings.

    Table REF-2 File Protection Values and Their Meanings

    Value  Privilege

    0400   OWNER:READ
    0200   OWNER:WRITE
    0100   OWNER:EXECUTE
    0040   GROUP:READ
    0020   GROUP:WRITE
    0010   GROUP:EXECUTE
    0004   WORLD:READ
    0002   WORLD:WRITE
    0001   WORLD:EXECUTE

    When you supply a mode value of 0, the chmod function gives the
    file the user's default file protection.

    The system is given the same privileges as the owner. A WRITE
    privilege also implies a DELETE privilege.

50.2  –  Description

    You must have a WRITE privilege for the file specified to change
    the mode.

    The C RTL does not support the S_ISVTX bit. Setting the S_ISVTX
    mode has no effect.

50.3  –  Return Values

    0                  Indicates that the mode is successfully
                       changed.
    -1                 Indicates that the change attempt has failed.

51  –  chown

    Changes the user ID and group ID of the specified file.

    Format

      #include  <unistd.h>

      int chown  (const char *file_spec, uid_t owner, gid_t group);

51.1  –  Arguments

 file_spec

    The address of an ASCII filename.

 owner

    The new user ID of the file.

 group

    The new group ID of the file.

51.2  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure.

52  –  cimag

    Returns the imaginary part of its complex argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double cimag  (double complex z);

      float cimagf  (float complex z);

      long double cimagl  (long double complex z);

52.1  –  Argument

 z

    A complex value.

52.2  –  Description

    The cimag functions return the imaginary part of z as a real
    number.

52.3  –  Return Values

    x                  The imaginary part value.

53  –  [w]clear

    Erase the contents of the specified window and reset the cursor
    to coordinates (0,0). The clear function acts on the stdscr
    window.

    Format

      #include  <curses.h>

      int clear();

      int wclear  (WINDOW *win);

53.1  –  Argument

 win

    A pointer to the window.

53.2  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

54  –  clearerr

    Resets the error and end-of-file indicators for a file (so that
    ferror and feof will not return a nonzero value).

    Format

      #include  <stdio.h>

      void clearerr  (FILE *file_ptr);

54.1  –  Argument

 file_ptr

    A file pointer.

55  –  clearerr_unlocked

    Same as the clearerr function, except used only within a scope
    protected by flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      void clearerr_unlocked  (FILE *file_ptr);

55.1  –  Argument

 file_ptr

    A file pointer.

55.2  –  Description

    The reentrant version of the clearerr function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, clearerr_unlocked can be used to avoid the overhead. The
    clearerr_unlocked macro is functionally identical to the clearerr
    macro, except that it is not required to be implemented in a
    thread-safe manner. The clearerr_unlocked function can be safely
    used only within a scope that is protected by the flockfile and
    funlockfile functions used as a pair. The caller must ensure that
    the stream is locked before clearerr_unlocked is used.

    See also flockfile, ftrylockfile, and funlockfile.

56  –  clearok

    Sets the clear flag for the window.

    Format

      #include  <curses.h>

      clearok  (WINDOW *win, bool boolf);

56.1  –  Arguments

 win

    The entire size of the terminal screen. You can use the windows
    stdscr and curscr with clearok.

 boolf

    A Boolean value of TRUE or FALSE. If the argument is TRUE, this
    forces a clearscreen to be printed on the next call to refresh,
    or stops the screen from being cleared if boolf is FALSE.

    The type bool is defined in the <curses.h> header file as
    follows:

    #define bool int

56.2  –  Description

    Unlike the clear function, the clearok function does not alter
    the contents of the window. If the win argument is curscr, the
    next call to refresh causes a clearscreen, even if the window
    passed to refresh is not a window the size of the entire terminal
    screen.

57  –  clock

    Determines the CPU time (in 10-millisecond units) used since the
    beginning of the process. The time reported is the sum of the
    user and system times of the calling process and any terminated
    child processes for which the calling process has executed wait
    or system.

    Format

      #include  <time.h>

      clock_t clock  (void);

57.1  –  Description

    The value returned by the clock function must be divided by the
    value of the CLK_TCK, as defined in the standard header file
    <time.h>, to obtain the time in seconds.

    The type clock_t is defined in the <time.h> header file as
    follows:

    typedef long int clock_t;

    Only the accumulated times for child processes running a C main
    program or a program that calls VAXC$CRTL_INIT or DECC$CRTL_INIT
    are included.

    A typical usage of the clock function is to call it after a
    program does its initial setup, and then again after the program
    executes the code to be timed. Then subtract the two values to
    give elapsed CPU time.

57.2  –  Return Values

    n                  The processor time used.
    -1                 Indicates that the processor time used is not
                       available.

58  –  clock_getres

    Gets the resolution for the specified clock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <time.h>

      int clock_getres  (clockid_t clock_id, struct timespec *res);

58.1  –  Arguments

 clock_id

    The clock type used to obtain the resolution. The CLOCK_REALTIME
    clock is supported and represents the TIME-OF-DAY clock for the
    system.

 res

    A pointer to the timespec data structure that receives the value
    of the clock's resolution.

58.2  –  Description

    The clock_getres function obtains the resolution value for the
    specified clock. Clock resolutions are implementation-dependent
    and cannot be set by a process.

    If the res argument is not NULL, the resolution of the specified
    clock is stored in the location pointed to by res.

    If res is NULL, the clock resolution is not stored.

    If the time argument (tp) of clock_settime is not a multiple of
    res, then the value is truncated to a multiple of res.

    On success, the function returns 0.

    On failure, the function returns -1 and sets errno to indicate
    the error.

    See also clock_gettime, clock_settime, time, and ctime.

58.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure; errno is set to the
                       following value:

                       o  EINVAL - The clock_id argument does not
                          specify a known clock.

59  –  clock_gettime

    Returns the current time (in seconds and nanoseconds) for the
    specified clock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <time.h>

      int clock_gettime  (clockid_t clock_id, struct timespec *tp);

59.1  –  Arguments

 clock_id

    The clock type used to obtain the time for the clock that is
    set. The CLOCK_REALTIME clock is supported and represents the
    TIME-OF-DAY clock for the system.

 tp

    A pointer to a timespec data structure.

59.2  –  Description

    The clock_gettime function returns the current tp value for the
    specified clock, clock_id.

    On success, the function returns 0.

    On failure, the function returns -1 and sets errno to indicate
    the error.

    See also clock_getres, clock_settime, time, and ctime.

59.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure; errno is set to the
                       following value:

                       o  EINVAL - The clock_id argument does not
                          specify a known clock, or the tp argument
                          specifies a nanosecond value less than 0 or
                          greater than or equal to 1 billion.

60  –  clock_settime

    Sets the specified clock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <time.h>

      int clock_settime  (clockid_t clock_id, const struct timespec *tp);

60.1  –  Arguments

 clock_id

    The clock type used for the clock that is to be set. The CLOCK_
    REALTIME clock is supported and represents the TIME-OF-DAY clock
    for the system.

 tp

    A pointer to a timespec data structure.

60.2  –  Description

    The clock_settime function sets the specified clock, clock_id,
    to the value specified by tp. Time values that are between two
    consecutive non-negative integer multiples of the resolution of
    the specified clock are truncated down to the smaller multiple of
    the resolution.

    A clock can be systemwide (that is, visible to all processes)
    or per-process (measuring time that is meaningful only within a
    process).

    The CLOCK_REALTIME clock, defined in <time.h>, represents the
    realtime clock for the system. For this clock, the values
    specified by clock_settime and returned by clock_gettime
    represent the amount of time elapsed, in seconds and nanoseconds,
    since the Epoch. The Epoch is defined as 00:00:00:00 January 1,
    1970 Greenwich Mean Time (GMT).

    You must have OPER, LOG_IO, and SYSPRV privileges to use the
    clock_settime function.

    On success, the function returns 0.

    On failure, the function returns -1 and sets errno to indicate
    the error.

    See also clock_getres, clock_gettime, time, and ctime.

60.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure; errno is set to the
                       following value:

                       o  EINVAL - The clock_id argument does not
                          specify a known clock, or the tp argument
                          is outside the range for the given clock_id
                          or specifies a nanosecond value less than 0
                          or greater than or equal to 1 billion.

                       o  EPERM - The requesting process does not
                          have the appropriate privilege to set the
                          specified clock.

61  –  clog

    Returns the complex natural (base e) logarithm of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex clog  (double complex z);

      float complex clogf  (float complex z);

      long double complex clogl  (long double complex z);

61.1  –  Argument

 z

    A complex value.

61.2  –  Description

    The clog functions return the complex natural (base e) logarithm
    of z, with a branch cut along the negative real axis.

61.3  –  Return Values

    x                  The complex natural logarithm value in the
                       range of a strip mathematically unbounded
                       along the real axis and in the interval [-
                       i&#960;, +i&#960;] along the imaginary axis.

62  –  close

    Closes the file associated with a file descriptor.

    Format

      #include  <unistd.h>

      int close  (int file_desc);

62.1  –  Argument

 file_desc

    A file descriptor.

62.2  –  Description

    The close function tries to write buffered data by using an
    implicit call to fflush. If the write fails (because the disk
    is full or the user's quota was exceeded, for example), close
    continues executing. It closes the OpenVMS channel, deallocates
    any buffers, and releases the memory associated with the file
    descriptor (or FILE pointer). Any buffered data is lost, and the
    file descriptor (or FILE pointer) no longer refers to the file.

    If your program needs to recover from errors when flushing
    buffered data, it should make an explicit call to fsync (or
    fflush) before calling close.

62.3  –  Return Values

    0                  Indicates that the file is properly closed.
    -1                 Indicates that the file descriptor is
                       undefined or an error occurred while the file
                       was being closed (for example, if the buffered
                       data cannot be written out).

62.4  –  Example

        #include <unistd.h>

        int fd;
           .
           .
           .
        fd = open ("student.dat", 1);
           .
           .
           .
        close(fd);

63  –  closedir

    Closes directories.

    Format

      #include  <dirent.h>

      int closedir  (DIR *dir_pointer);

63.1  –  Argument

 dir_pointer

    Pointer to the dir structure of an open directory.

63.2  –  Description

    The closedir function closes a directory stream and frees
    the structure associated with the dir_pointer argument. Upon
    return, the value of dir_pointer does not necessarily point to an
    accessible object of the type DIR.

    The type DIR, which is defined in the <dirent.h> header file,
    represents a directory stream that is an ordered sequence of
    all the directory entries in a particular directory. Directory
    entries represent files. You can remove files from or add files
    to a directory asynchronously to the operation of the readdir
    function.

                                   NOTE

       An open directory must always be closed with the closedir
       function to ensure that the next attempt to open the
       directory is successful.

63.3  –  Example

      The following example shows how to search a directory for the
      entry name, using the opendir, readdir, and closedir functions:

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

        #define FOUND     1
        #define NOT_FOUND 0

        static int dir_example(const char *name, unsigned int unix_style)
        {
            DIR *dir_pointer;
            struct dirent *dp;

            if ( unix_style )
                dir_pointer = opendir(".");
            else
                dir_pointer = opendir(getenv("PATH"));

            if ( !dir_pointer ) {
                perror("opendir");
                return NOT_FOUND;
            }

            /* Note, that if opendir() was called with UNIX style file  */
            /* spec like ".", readdir() will return only a single       */
            /* version of each file in the directory. In this case the  */
            /* name returned in d_name member of the dirent structure   */
            /* will contain only file name and file extension fields,   */
            /* both lowercased like "foo.bar".                          */

            /* If opendir() was called with OpenVMS style file spec,    */
            /* readdir() will return every version of each file in the  */
            /* directory. In this case the name returned in d_name      */
            /* member of the dirent structure will contain file name,   */
            /* file extension and file version fields. All in upper     */
            /* case, like "FOO.BAR;1".                                  */

            for ( dp = readdir(dir_pointer);
                  dp && strcmp(dp->d_name, name);
                  dp = readdir(dir_pointer) )
                ;

            closedir(dir_pointer);

            if ( dp != NULL )
                return FOUND;
            else
                return NOT_FOUND;
        }

        int main(void)
        {
           char *filename = "foo.bar";
           FILE *fp;

           remove(filename);

           if ( !(fp = fopen(filename, "w")) ) {
                perror("fopen");
                return (EXIT_FAILURE);
           }

           if ( dir_example( "FOO.BAR;1", 0 ) == FOUND )
                puts("OpenVMS style: found");
           else
                puts("OpenVMS style: not found");

           if ( dir_example( "foo.bar", 1 ) == FOUND )
                puts("UNIX style: found");
           else
                puts("UNIX style: not found");

           fclose(fp);
           remove(filename);
           return( EXIT_SUCCESS );
        }

63.4  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error and is further specified in
                       the global errno.

64  –  [w]clrattr

    Deactivate the video display attribute attr within the window.
    The clrattr function acts on the stdscr window.

    Format

      #include  <curses.h>

      int clrattr  (int attr);

      int wclrattr  (WINDOW *win, int attr);

64.1  –  Arguments

 win

    A pointer to the window.

 attr

    Video display attributes that can be blinking, boldface, reverse
    video, and underlining; they are represented by the defined
    constants _BLINK, _BOLD, _REVERSE, and _UNDERLINE. To clear
    multiple attributes, separate them with a bitwise OR operator
    (|) as follows:

    clrattr(_BLINK | _UNDERLINE);

64.2  –  Description

    These functions are specific to VSI C for OpenVMS Systems and
    are not portable.

64.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

65  –  [w]clrtobot

    Erase the contents of the window from the current position of the
    cursor to the bottom of the window. The clrtobot function acts on
    the stdscr window.

    Format

      #include  <curses.h>

      int clrtobot();

      int wclrtobot  (WINDOW *win);

65.1  –  Argument

 win

    A pointer to the window.

65.2  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

66  –  [w]clrtoeol

    Erase the contents of the window from the current cursor position
    to the end of the line on the specified window. The clrtoeol
    function acts on the stdscr window.

    Format

      #include  <curses.h>

      int clrtoeol();

      int wclrtoeol  (WINDOW *win);

66.1  –  Argument

 win

    A pointer to the window.

66.2  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

67  –  confstr

    Determines the current value of a specified system variable
    defined by a string value.

    Format

      #include  <unistd.h>

      size_t confstr  (int name, char *buf, size_t len);

67.1  –  Arguments

 name

    The system variable setting. Valid values for the name argument
    are the _CS_X names defined in the <unistd.h> header file.

 buf

    Pointer to the buffer where the confstr function copies the name
    value.

 len

    The size of the buffer storing the name value.

67.2  –  Description

    The confstr function allows an application to determine the
    current setting of certain system parameters, limits, or options
    that are defined by a string value. The function is mainly used
    by applications to find the system default value for the PATH
    environment variable.

    If the following conditions are true, then the confstr function
    copies that value into a len-byte buffer pointed to by buf:

    o  The len argument can be 0 (zero).

    o  The name argument has a system-defined value.

    o  The buf argument is not a NULL pointer.

    If the returned string is longer than len bytes, including the
    terminating null, then the confstr function truncates the string
    to len - 1 bytes and adds a terminating null to the result. The
    application can detect that the string was truncated by comparing
    the value returned by the confstr function with the value of the
    len argument.

    The <limits.h> header file contains system-defined limits. The
    <unistd.h> header file contains system-defined environmental
    variables.

    Also, confstr supports the following three HP-UX symbolic
    constants, which are added to header file <unistd.h>:

    o  _CS_MACHINE_IDENT

    o  _CS_PARTITION_IDENT

    o  _CS_MACHINE_SERIAL

67.3  –  Example

      To find out how big a buffer is needed to store the string
      value of name, enter:

         confstr(_CS_PATH, NULL, (size_t) 0)

      The confstr function returns the size of the buffer necessary.

67.4  –  Return Values

    0                  Indicates an error. When the specified name
                       value:

                       o  Is invalid, errno is set to EINVAL.

                       o  Does not have a system-defined value, errno
                          is not set.

    n                  The size of the buffer needed to hold the
                       value.

                       o  When the value of the name argument is
                          system-defined, confstr returns the size of
                          the buffer needed to hold the entire value.
                          If this return value is greater than the
                          len value, the string returned as the buf
                          value is truncated.

                       o  When the value of the len argument is set
                          to 0 or the buf value is NULL, confstr
                          returns the size of the buffer needed to
                          hold the entire system-defined value. The
                          string value is not copied.

68  –  conj

    Returns the complex conjugate of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex conj  (double complex z);

      float complex conjf  (float complex z);

      long double complex conjl  (long double complex z);

68.1  –  Argument

 z

    A complex value.

68.2  –  Description

    The conj functions return the complex conjugate of z, by
    reversing the sign of its imaginary part.

68.3  –  Return Values

    x                  The complex conjugate value.

69  –  copysign

    Returns x with the same sign as y.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double copysign  (double x, double y);

      float copysignf  (float x, float y);

                       (Integrity servers, Alpha)

      long double copysignl  (long double x, long double y);

                             (Integrity servers, Alpha)

69.1  –  Arguments

 x

    A real value.

 y

    A real value.

69.2  –  Description

    The copysign functions return x with the same sign as y. IEEE 754
    requires copysign(x,NaN), copysignf(x,NaN), and copysignl(x,NaN)
    to return +x or -x.

69.3  –  Return Value

    x                  The value of x with the same sign as y.

70  –  cos

    Returns the cosine of its radian argument.

    Format

      #include  <math.h>

      double cos  (double x);

      float cosf  (float x); (Integrity servers, Alpha)

      long double cosl  (long double x); (Integrity servers, Alpha)

      double cosd  (double x); (Integrity servers, Alpha)

      float cosdf  (float x); (Integrity servers, Alpha)

      long double cosdl  (long double x); (Integrity servers, Alpha)

70.1  –  Argument

 x

    A radian expressed as a real value.

70.2  –  Description

    The cos functions return the cosine of their argument, measured
    in radians.

    The cosd functions return the cosine of their argument, measured
    in degrees.

    |x| = Infinity is an invalid argument.

70.3  –  Return Values

    x                  The cosine of the argument.
    HUGE_VAL           Indicates that the argument is too large;
                       errno is set to ERANGE.

71  –  cosh

    Returns the hyperbolic cosine of its radian argument.

    Format

      #include  <math.h>

      double cosh  (double x);

      float coshf  (float x); (Integrity servers, Alpha)

      long double coshl  (long double x); (Integrity servers, Alpha)

71.1  –  Argument

 x

    A radian expressed as a real number.

71.2  –  Description

    The cosh functions return the hyperbolic cosine of x and are
    defined as (e**x + e**(-x))/2.

71.3  –  Return Values

    x                  The hyperbolic cosine of the argument.
    HUGE_VAL           Indicates that the argument is too large;
                       errno is set to ERANGE.

72  –  cot

    Returns the cotangent of its radian argument.

    Format

      #include  <math.h>

      double cot  (double x);

      float cotf  (float x); (Integrity servers, Alpha)

      long double cotl  (long double x); (Integrity servers, Alpha)

      double cotd  (double x); (Integrity servers, Alpha)

      float cotdf  (float x); (Integrity servers, Alpha)

      long double cotdl  (long double x); (Integrity servers, Alpha)

72.1  –  Argument

 x

    A radian expressed as a real number.

72.2  –  Description

    The cot functions return the cotangent of their argument,
    measured in radians.

    The cotd functions return the cotangent of their argument,
    measured in degrees.

    x = 0 is an invalid argument.

72.3  –  Return Values

    x                  The cotangent of the argument.
    HUGE_VAL           Indicates that the argument is zero; errno is
                       set to ERANGE.

73  –  cpow

    Returns the complex power function x**y.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex cpow  (double complex x, double complex y);

      float complex cpowf  (float complex x, float complex y);

      long double complex cpowl  (long double complex x, long double complex y);

73.1  –  Argument

 x

    A complex value.

 y

    A complex value.

73.2  –  Description

    The cpow functions return the complex power function x**y, with a
    branch cut for the first parameter along the negative real axis.

73.3  –  Return Values

    x                  The complex power function value.

74  –  cproj

    Returns a projection of its argument onto the Riemann sphere.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex cproj  (double complex z);

      float complex cprojf  (float complex z);

      long double complex cprojl  (long double complex z);

74.1  –  Argument

 z

    A complex value.

74.2  –  Description

    The cproj functions compute and return a projection of z onto
    the Riemann sphere: z projects to z, except that all complex
    infinities (even those with one infinite part and one NaN part)
    project to positive infinity on the real axis. If z has an
    infinite part, then cproj(z) is equivalent to:

    INFINITY + I * copysign(0.0, cimag(z))

74.3  –  Return Values

    x                  The value of the projection onto the Riemann
                       sphere.

75  –  creal

    Returns the real part of its complex argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double creal  (double complex z);

      float crealf  (float complex z);

      long double creall  (long double complex z);

75.1  –  Argument

 z

    A complex value.

75.2  –  Description

    The creal functions return the real part of z.

75.3  –  Return Values

    x                  The real part value.

76  –  creat

    Creates a new file.

    Format

      #include  <fcntl.h>

      int creat  (const char *file_spec, mode_t mode); (ISO POSIX-1)

      int creat  (const char *file_spec, mode_t mode, . . . );
                                            (DEC C Extension)

76.1  –  Arguments

 file_spec

    A null-terminated string containing any valid file specification.

 mode

    An unsigned value that specifies the file-protection mode. The
    compiler performs a bitwise AND operation on the mode and the
    complement of the current protection mode.

    You can construct modes by using the bitwise OR operator (|)  to
    create mode combinations. The modes are:

    0400   OWNER:READ
    0200   OWNER:WRITE
    0100   OWNER:EXECUTE
    0040   GROUP:READ
    0020   GROUP:WRITE
    0010   GROUP:EXECUTE
    0004   WORLD:READ
    0002   WORLD:WRITE
    0001   WORLD:EXECUTE

    The system is given the same privileges as the owner. A WRITE
    privilege implies a DELETE privilege.

                                   NOTE

       To create files with OpenVMS RMS default protections using
       the UNIX system-call functions umask, mkdir, creat, and
       open, call mkdir, creat, and open with a file-protection
       mode argument of 0777 in a program that never specifically
       calls umask. These default protections include correctly
       establishing protections based on ACLs, previous versions of
       files, and so on.

       In programs that do vfork/exec calls, the new process image
       inherits whether umask has ever been called or not from
       the calling process image. The umask setting and whether
       the umask function has ever been called are both inherited
       attributes.

  . . .

    An optional argument list of character strings of the following
    form:

    "keyword = value", . . . ,"keyword = value"

    Or in the case of "acc" or "err", this form:

    "keyword"

    Here, keyword is an RMS field in the file access block (FAB) or
    record access block (RAB); value is valid for assignment to that
    field. Some fields permit you to specify more than one value. In
    these cases, the values are separated by commas.

    The RMS callback keywords "acc" and "err" are the only keywords
    that do not take values. Instead, they are followed by a pointer
    to the callback routine to be used, followed by a pointer to a
    user-specified value to be used as the first argument of the
    callback routine. For example, to set up an access callback
    routine called acc_callback whose first argument is a pointer
    to the integer variable first_arg in a call to open, you can use
    the following statement:

    open("file.dat", O_RDONLY, 0 ,"acc", acc_callback, &first_arg)

    The second and third arguments to the callback routine must be
    pointers to a FAB and RAB, respectively, and the routine must
    have a return type of int. If the callback returns a value less
    than 0, the open, creat, or fopen fails. The error callback can
    correct the error condition and return a status greater than
    or equal to 0 to continue the creat call. Assuming the previous
    open statement, the function prototype for acc_callback would be
    similar to the following statement:

    #include <rms.h>

    int acc_callback(int *first_arg, struct FAB *fab, struct RAB *rab);

    FAB and RAB are defined in the <rms.h> header file, and the
    actual pointers passed to the routine are pointers to the RAB
    and FAB being used to open the file file.dat.

    If an access callback routine is established, then it will be
    called in the open-type routine immediately before the call to
    the RMS function sys$create or sys$open. If an error callback
    routine is established and an error status is returned from the
    sys$create or sys$open function, then the callback routine will
    be invoked immediately after the status is checked and the error
    value is discovered.

                                   NOTE

       Any manipulation of the RAB or FAB in a callback function
       could lead to serious problems in later calls to the
       C RTL I/O functions.

    RMS Valid Keywords and Values describes the RMS keywords and
    values.

    Table REF-3 RMS Valid Keywords and Values

    Keyword        Value    Description

    "acc"          callback Access callback routine.
    "alq = n"      decimal  Allocation quantity.
    "bls = n"      decimal  Block size.
    "ctx = bin"    string   No translation of '\n' to the terminal.
                            Use this for writing binary data to
                            files.
    "ctx = cvt"    string   Negates a previous setting of
                            "ctx=nocvt". This is the default.
    "ctx =         string   No conversion of Fortran carriage-control
    nocvt"                  bytes.
    "ctx = rec"    string   Forces record mode access.
    "ctx = stm"    string   Forces stream mode access.
    "ctx =         string   Causes records to be written only when
    xplct"                  explicitly specified by a call to fflush,
                            close, or fclose.
    "deq = n"      decimal  Default extension quantity.
    "dna =         string   Default file-name string.
    filespec"
    "err"          callback Error callback routine.
    "fop = val,             File-processing options:
    val , . . . "
                   ctg      Contiguous.
                   cbt      Contiguous-best-try.
                   dfw      Deferred write; only applicable to files
                            opened for shared access.
                   dlt      Delete file on close.
                   tef      Truncate at end-of-file.
                   cif      Create if nonexistent.
                   sup      Supersede.
                   scf      Submit as command file on close.
                   spl      Spool to system printer on close.
                   tmd      Temporary delete.
                   tmp      Temporary (no file directory).
                   nef      Not end-of-file.
                   rck      Read check compare operation.
                   wck      Write check compare operation.
                   mxv      Maximize version number.
                   rwo      Rewind file on open.
                   pos      Current position.
                   rwc      Rewind file on close.
                   sqo      File can only be processed in a
                            sequential manner.
    "fsz = n"      decimal  Fixed header size.
    "gbc = n"      decimal  The requested number of global buffers
                            for a file.
    "mbc = n"      decimal  Multiblock count.
    "mbf = n"      decimal  Multibuffer count.
    "mrs = n"      decimal  Maximum record size.
    "pmt=usr-      string   Prompts for terminal input. Any RMS input
    prmpt"                  from a terminal device will be preceded
                            by "usr-prmpt" when this option and
                            "rop=pmt" are specified.
    "rat = val,             Record attributes:
    val . . . "
                   cr       Carriage-return control.
                   blk      Disallow records to span block
                   ftn      boundaries.
                   none     Fortran print control.
                   prn      Explicitly forces no carriage control.
                            Print file format.
    "rfm = val"             Record format:
                   fix      Fixed-length record format.
                   stm      RMS stream record format.
                   stmlf    Stream format with line-feed terminator.
                   stmcr    Stream format with carriage-return
                            terminator.
                   var      Variable-length record format.
                   vfc      Variable-length record with fixed
                   udf      control.
                            Undefined.
    "rop = val,             Record-processing operations:
    val . . . "
                   asy      Asynchronous I/O.
                   cco      Cancels Ctrl/O (used with Terminal I/O).
                   cvt      Capitalizes characters on a read from the
                            terminal.
                   eof      Positions the record stream to the end-
                            of-file for the connect operation only.
                   nlk      Do not lock record.
                   pmt      Enables use of the prompt specified
                            by "pmt=usr-prmpt" on input from the
                            terminal.
                   pta      Eliminates any information in the type-
                            ahead buffer on a read from the terminal.
                   rea      Locks record for a read operation for
                            this process, while allowing other
                            accessors to read the record.
                   rlk      Locks record for write.
                   rne      Suppresses echoing of input data on the
                            screen as it is entered on the keyboard.
                   rnf      Indicates that Ctrl/U, Ctrl/R, and DELETE
                            are not to be considered control commands
                            on terminal input, but are to be passed
                            to the application program.
                   rrl      Reads regardless of lock.
                   syncsts  Returns a success status of RMS$_SYNCH if
                            the requested service completes its task
                            immediately.
                   tmo      Timeout I/O.
                   tpt      Allows put/write services using
                            sequential record access mode to occur
                            at any point in the file, truncating the
                            file at that point.
                   ulk      Prohibits RMS from automatically
                            unlocking records.
                   wat      Wait until record is available, if
                            currently locked by another stream.
                   rah      Read ahead.
                   wbh      Write behind.
    "rtv=n"        decimal  The number of retrieval pointers that RMS
                            has to maintain in memory (0 to 127,255).
    "shr = val,             File sharing options:
    val, . . . "
                   del      Allows users to delete.
                   get      Allows users to read.
                   mse      Allows multistream connects.
                   nil      Prohibits file sharing.
                   put      Allows users to write.
                   upd      Allows users to update.
                   upi      Allows one or more writers.
                   nql      No query locking (file level).
    "tmo = n"      decimal  I/O timeout value.

    In addition to these options, any option that takes a key value
    (such as "fop" or "rat") can be negated by prefixing the value
    with "no". For example, specify "fop=notmp" to clear the "tmp"
    bit in the "fop" field.

                                  NOTES

       o  While these options provide much flexibility and
          functionality, many of them can also cause severe
          problems if not used correctly.

       o  You cannot share the default VSI C for OpenVMS stream
          file I/O. If you wish to share files, you must specify
          "ctx=rec" to force record access mode. You must also
          specify the appropriate "shr" options depending on the
          type of access you want.

       o  If you intend to share a file opened for append, you must
          specify appropriate share and record-locking options, to
          allow other accessors to read the record. The reason for
          doing this: the file is positioned at the end-of-file by
          reading records in a loop until end-of-file is reached.

    For more information on these options, see the OpenVMS Record
    Management Services Reference Manual.

76.2  –  Description

    The C RTL opens the new file for reading and writing, and
    returns the corresponding file descriptor.

    If the file exists:

    o  A version number one greater than any existing version is
       assigned to the newly created file.

    o  By default, the new file inherits certain attributes from
       the existing version of the file unless those attributes are
       specified in the creat call. The following attributes are
       inherited:

       -  Record format (FAB$B_RFM)

       -  Maximum record size (FAB$W_MRS)

       -  Carriage control (FAB$B_RAT)

       -  File protection

    o  When a new version of a file is created, and the named file
       already exists as a symbolic link, the file to which the
       symbolic link refers is created.

    If the file did not previously exist:

    o  It is given the file protection that results from performing
       a bitwise AND on the mode argument and the complement of the
       current protection mask.

    o  It defaults to stream format with line-feed record separator
       and implied carriage-return attributes.

    See also open, close, read, write, and lseek in this section.

76.3  –  Return Values

    n                  A file descriptor.
    -1                 Indicates errors, including protection
                       violations, undefined directories, and
                       conflicting file attributes.

77  –  [no]crmode

    In the UNIX system environment, the crmode and nocrmode functions
    set and unset the terminal from cbreak mode. In cbreak mode, a
    single input character can be processed without pressing Return.
    This mode of single-character input is only supported with the
    Curses input routine getch.

    Format

      #include  <curses.h>

      crmode()

      nocrmode()

77.1  –  Example

        /* Program to demonstrate the use of crmod() and curses */

        #include <curses.h>

        main()
        {
            WINDOW *win1;
            char vert = '.',
                 hor = '.',
                 str[80];

            /*  Initialize standard screen, turn echo off.  */
            initscr();
            noecho();

            /*  Define a user window.  */
            win1 = newwin(22, 78, 1, 1);

            /*  Turn on reverse video and draw a box on border.  */
            setattr(_REVERSE);
            box(stdscr, vert, hor);
            mvwaddstr(win1, 2, 2, "Test cbreak input");
            refresh();
            wrefresh(win1);

            /*  Set cbreak, do some input, and output it.  */
            crmode();
            getch();
            nocrmode(); /* Turn off cbreak. */
            mvwaddstr(win1, 5, 5, str);
            mvwaddstr(win1, 7, 7, "Type something to clear the screen");
            wrefresh(win1);

            /*  Get another character, then delete the window.  */
            getch();
            wclear(win1);
            touchwin(stdscr);
            endwin();
        }

      In this example, the first call to getch returns as soon as one
      character is entered, because crmode was called before getch
      was called. The second time getch is called, it waits until the
      Return key is pressed before processing the character entered,
      because nocrmode was called before getch was called the second
      time.

78  –  crypt

    The password encryption function.

    Format

      #include  <unistd.h>

      #include  <stdlib.h>

      char *crypt  (const char *key, const char *salt;)

78.1  –  Function Variants

    The crypt function has variants named _crypt32 and _crypt64 for
    use with 32-bit and 64-bit pointer sizes, respectively.

78.2  –  Argument

 key

    A user's typed password.

 salt

    A 2-character string.

78.3  –  Description

    The crypt function generates an encoded version of a password.
    It is based on the NBS Data Encryption Standard, with variations
    intended to frustrate use of hardware implementations of the DES
    for key search.

    The first argument to crypt is normally a user's typed password.
    The second is a 2-character string chosen from the set [a-zA-Z0-
    9./]. The salt string is used to perturb the DES algorithm in one
    of 4096 different ways, after which the password is used as the
    key to encrypt repeatedly a constant string. The returned value
    points to the encrypted password, in the same alphabet as the
    salt. The first two characters are the salt itself.

    The return value from crypt points to a static data area whose
    content is overwritten by each call.

    See also encrypt and setkey.

78.4  –  Return Value

    pointer            Pointer to the encrypted password.

79  –  csin

    Returns the complex sine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex csin  (double complex z);

      float complex csinf  (float complex z);

      long double complex csinl  (long double complex z);

79.1  –  Argument

 z

    A complex value.

79.2  –  Description

    The csin functions compute the complex sine value of z.

79.3  –  Return Values

    x                  The complex sine value.

    Returns the complex hyperbolic sine of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex csinh  (double complex z);

      float complex csinhf  (float complex z);

      long double complex csinhl  (long double complex z);

79.4  –  Argument

 z

    A complex value.

79.5  –  Description

    The csinh functions compute the complex hyperbolic sine of z.

79.6  –  Return Values

    x                  The complex hyperbolic sine value.

80  –  csqrt

    Returns the complex square root of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex csqrt  (double complex z);

      float complex csqrtf  (float complex z);

      long double complex csqrtl  (long double complex z);

80.1  –  Argument

 z

    A complex value.

80.2  –  Description

    The csqrt functions compute the complex square root of z, with a
    branch cut along the negative real axis.

80.3  –  Return Values

    x                  The complex square root value in the range of
                       the right half-plane (including the imaginary
                       axis).

81  –  ctan

    Returns the complex tangent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex ctan  (double complex z);

      float complex ctanf  (float complex z);

      long double complex ctanl  (long double complex z);

81.1  –  Argument

 z

    A complex value.

81.2  –  Description

    The ctan functions compute the complex tangent value of z.

81.3  –  Return Values

    x                  The complex tangent value.

82  –  ctanh

    Returns the complex hyperbolic tangent of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <complex.h>

      double complex ctanh  (double complex z);

      float complex ctanhf  (float complex z);

      long double complex ctanhl  (long double complex z);

82.1  –  Argument

 z

    A complex value.

82.2  –  Description

    The ctanh functions compute the complex hyperbolic tangent value
    of z.

82.3  –  Return Values

    x                  The complex hyperbolic tangent value.

83  –  ctermid

    Returns a character string giving the equivalence string of
    SYS$COMMAND. This is the name of the controlling terminal.

    Format

      #include  <stdio.h>

      char *ctermid  (char *str);

83.1  –  Function Variants

    The ctermid function has variants named _ctermid32 and _ctermid64
    for use with 32-bit and 64-bit pointer sizes, respectively.

83.2  –  Argument

 str

    Must be a pointer to an array of characters. If this argument is
    NULL, the filename is stored internally and might be overwritten
    by the next ctermid call. Otherwise, the filename is stored
    beginning at the location indicated by the argument. The argument
    must point to a storage area of length L_ctermid (defined by the
    <stdio.h> header file).

83.3  –  Return Value

    pointer            Points to a character string.

84  –  ctime

    Converts a time in seconds, since 00:00:00 January 1, 1970, to an
    ASCII string in the form generated by the asctime function.

    Format

      #include  <time.h>

      char *ctime  (const time_t *bintim);

      char *ctime_r  (const time_t *bintim, char *buffer);
                           (ISO POSIX-1)

84.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to
    this function that is equivalent to the behavior before OpenVMS
    Version 7.0.

84.2  –  Arguments

 bintim

    A pointer to a variable that specifies the time value (in
    seconds) to be converted.

 buffer

    A pointer to a character array that is at least 26 bytes long.
    This array is used to store the generated date-and-time string.

84.3  –  Description

    The ctime and ctime_r functions convert the time pointed to by
    bintim into a 26-character string, and return a pointer to the
    string.

    The difference between the ctime_r and ctime functions is that
    the former puts its result into a user-specified buffer. The
    latter puts its result into thread-specific static memory
    allocated by the C RTL, which can be overwritten by
    subsequent calls to ctime or asctime; you must make a copy if
    you want to save it.

    On success, ctime returns a pointer to the string; ctime_r
    returns its second argument. On failure, these functions return
    the NULL pointer.

    The type time_t is defined in the <time.h> header file as
    follows:

    typedef long int time_t

    The ctime function behaves as if it called tzset.

                                   NOTE

       Generally speaking, UTC-based time functions can affect in-
       memory time-zone information, which is processwide data.
       However, if the system time zone remains the same during
       the execution of the application (which is the common case)
       and the cache of timezone files is enabled (which is the
       default), then the _r variant of the time functions asctime_
       r, ctime_r, gmtime_r, and localtime_r, is both thread-safe
       and AST-reentrant.

       If, however, the system time zone can change during the
       execution of the application or the cache of timezone files
       is not enabled, then both variants of the UTC-based time
       functions belong to the third class of functions, which are
       neither thread-safe nor AST-reentrant.

84.4  –  Return Values

    x                  A pointer to the 26-character ASCII string, if
                       successful.
    NULL               Indicates failure.

85  –  cuserid

    Returns a pointer to a character string containing the name of
    the user initiating the current process.

    Format

      #include  <unistd.h> (X/Open, POSIX-1)

      #include  <stdio.h> (X/Open)

      char *cuserid  (char *str);

85.1  –  Function Variants

    The cuserid function has variants named _cuserid32 and _cuserid64
    for use with 32-bit and 64-bit pointer sizes, respectively.

85.2  –  Argument

 str

    If this argument is NULL, the user name is stored internally. If
    the argument is not NULL, it points to a storage area of length
    L_cuserid (defined by the <stdio.h> header file), and the name is
    written into that storage. If the user name is a null string, the
    function returns NULL.

85.3  –  Return Values

    pointer            Points to a string.
    NULL               If the user name is a null string.

86  –  DECC$CRTL_INIT

    Allows you to call the C RTL from other languages or to
    use the C RTL when your main function is not in C. It
    initializes the run-time environment and establishes both an exit
    and condition handler. VAXC$CRTL_INIT is a synonym for DECC$CRTL_
    INIT. Either name invokes the same routine.

    Format

      #include  <signal.h>

      void DECC$CRTL_INIT(void);

86.1  –  Description

    The following example shows a Pascal program that calls the
    C RTL using the DECC$CRTL_INIT function:

    $ PASCAL EXAMPLE1
    $ LINK EXAMPLE1
    $ TY EXAMPLE1.PAS
    PROGRAM TESTC(input, output);
    PROCEDURE DECC$CRTL_INIT; extern;
    BEGIN
       DECC$CRTL_INIT;
    END

    A shareable image need only call this function if it contains
    an VSI C function for signal handling, environment variables,
    I/O, exit handling, a default file protection mask, or if it is a
    child process that should inherit context.

    Although many of the initialization activities are performed only
    once, DECC$CRTL_INIT can safely be called multiple times.

    At least one frame in the current call stack must have that
    handler established for OpenVMS exceptions to get mapped to UNIX
    signals.

87  –  decc$feature_get

    Calls decc$feature_get_value with a character-string feature
    name, rather than an index.

    Format

      #include  <unixlib.h>

      int decc$feature_get  (const char *name, int mode);

87.1  –  Argument

 name

    Pointer to a character string passed as a name in the list of
    supported features.

 mode

    An integer indicating which feature value to return. The values
    for mode are:

       __FEATURE_MODE_DEFVAL        Default value
       __FEATURE_MODE_CURVAL        Current value
       __FEATURE_MODE_MINVAL        Minimum value
       __FEATURE_MODE_MAXVAL        Maximum value
       __FEATURE_MODE_INIT_STATE    Initialization state

87.2  –  Description

    The decc$feature_get function allows you to call the
    decc$feature_get_value function with a character-string feature
    name, rather than an index into an internal C RTL table.

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get_value, decc$feature_get_index,
    decc$feature_get_name, decc$feature_set, decc$feature_set_value,
    decc$feature_show, and decc$feature_show_all.

87.3  –  Return Values

    n                  An integer corresponding to the specified name
                       and mode arguments.
    -1                 Indicates an error; errno is set.

88  –  decc$feature_get_index

    Returns an index for accessing feature values.

    Format

      #include  <unixlib.h>

      int decc$feature_get_index  (char *name);

88.1  –  Argument

 name

    Pointer to a character string passed as a name in the list of
    supported features.

88.2  –  Description

    The decc$feature_get_index function looks up the string passed
    as name in the list of supported features. If the name is found,
    decc$feature_get_index returns a (nonnegative) index that can
    be used to set or retrieve the values for the feature. The
    comparison for name is case insensitive.

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get, decc$feature_get_value, decc$feature_
    get_name, decc$feature_set, decc$feature_set_value, decc$feature_
    show, and decc$feature_show_all.

88.3  –  Return Values

    n                  A nonnegative index that can be used to set or
                       retrieve the specified values for the feature.
    -1                 Indicates an error; errno is set.

89  –  decc$feature_get_name

    Returns a feature name.

    Format

      #include  <unixlib.h>

      char *decc$feature_get_name  (int index);

89.1  –  Argument

 index

    An integer value from 0 to the highest allocated feature.

89.2  –  Description

    The decc$feature_get_name function returns a pointer to a null-
    terminated string containing the name of the feature for the
    entry specified by index. The index value can be 0 to the highest
    allocated feature. If there is no feature corresponding to the
    index value, then the function returns a NULL pointer.

    On error, NULL is returned and errno is set to indicate the
    error.

    See also decc$feature_get, decc$feature_get_index, decc$feature_
    get_value, decc$feature_set, decc$feature_set_value,
    decc$feature_show, and decc$feature_show_all.

89.3  –  Return Values

    x                  Pointer to a null-terminated string containing
                       the name of the feature for the entry
                       specified by index.
    NULL               Indicates an error; errno is set.

90  –  decc$feature_get_value

    Returns a feature value specified by the index and mode
    arguments.

    Format

      #include  <unixlib.h>

      int decc$feature_get_value  (int index, int mode);

90.1  –  Arguments

 index

    An integer value from 0 to the highest allocated feature.

 mode

    An integer indicating which feature value to return. The values
    for mode are:

       __FEATURE_MODE_DEFVAL        Default value
       __FEATURE_MODE_CURVAL        Current value
       __FEATURE_MODE_MINVAL        Minimum value
       __FEATURE_MODE_MAXVAL        Maximum value
       __FEATURE_MODE_INIT_STATE    Initialization state

90.2  –  Description

    The decc$feature_get_value function retrieves a value for the
    feature specified by index. The mode determines which value is
    returned.

    The default value is what is used if not set by a logical name or
    overridden by a call to decc$feature_set_value.

    If mode = 4, then the initialization state is returned. Values
    for the initialization state are:

       0 not initialized
       1 set by logical name
       2 forced by decc$feature_set_value
       -1-initialized to default value

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get, decc$feature_get_index, decc$feature_
    get_name, decc$feature_set, decc$feature_set_value, decc$feature_
    show, and decc$feature_show_all.

90.3  –  Return Values

    n                  An integer corresponding to the specified
                       index and mode arguments.
    -1                 Indicates an error; errno is set.

91  –  decc$feature_set

    Calls decc$feature_set_value with a character-string feature
    name, rather than an index.

    Format

      #include  <unixlib.h>

      int decc$feature_set  (const char *name, int mode, int value);

91.1  –  Argument

 name

    Pointer to a character string passed as a name in the list of
    supported features.

 mode

    An integer indicating which feature value to return. The values
    for mode are:

       __FEATURE_MODE_DEFVAL        Default value
       __FEATURE_MODE_CURVAL        Current value
       __FEATURE_MODE_MINVAL        Minimum value
       __FEATURE_MODE_MAXVAL        Maximum value
       __FEATURE_MODE_INIT_STATE    Initialization state

 value

    The feature value to be set.

91.2  –  Description

    The decc$feature_set function allows you to call the
    decc$feature_set_value function with a character-string feature
    name, rather than an index into an internal C RTL table.

    If successful, the function returns the previous value.

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_set_value, decc$feature_get, decc$feature_
    get_index, decc$feature_get_name, decc$feature_get_value.
    decc$feature_show, and decc$feature_show_all.

91.3  –  Return Values

    n                  The previous feature value.
    -1                 Indicates an error; errno is set.

92  –  decc$feature_set_value

    Sets the default value or the current value for the feature
    specified by index.

    Format

      #include  <unixlib.h>

      int decc$feature_set_value  (int index, int mode, int value);

92.1  –  Arguments

 index

    An integer value from 0 to the highest allocated feature.

 mode

    An integer indicating whether to set the default or current
    feature value. The values for mode are:

       0 default value
       1 current value

 value

    The feature value to be set.

92.2  –  Description

    The decc$feature_set_value function sets the default value or
    the current value (as determined by the mode argument) for the
    feature specified by index.

    If this function is successful, it returns the previous value.

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get, decc$feature_get_index, decc$feature_
    get_name, decc$feature_get_value, decc$feature_set, decc$feature_
    show, and decc$feature_show_all.

92.3  –  Return Values

    n                  The previous feature value.
    -1                 Indicates an error; errno is set.

93  –  decc$feature_show

    Displays all feature values for the specified feature name.

    Format

      #include  <unixlib.h>

      int decc$feature_show  (const char *name);

93.1  –  Argument

 name

    Pointer to a character string passed as a name in the list of
    supported features.

93.2  –  Description

    The decc$feature_show function displays to stdout all values for
    the specified feature name. For example:

    --------- C RTL Feature Name ---------   Cur  Def  Min  Max  Ini

    DECC$V62_RECORD_GENERATION                0    0    0    1    -1

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get, decc$feature_get_index, decc$feature_
    get_name, decc$feature_get_value, decc$feature_set, decc$feature_
    set_value, and decc$feature_show_all.

93.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set.

94  –  decc$feature_show_all

    Displays all feature values for all feature names.

    Format

      #include  <unixlib.h>

      int decc$feature_show_all  (void);

94.1  –  Description

    The decc$feature_show_all function displays to stdout all values
    for all feature names.

    On error, -1 is returned and errno is set to indicate the error.

    See also decc$feature_get, decc$feature_get_index, decc$feature_
    get_name, decc$feature_get_value, decc$feature_set, decc$feature_
    set_value, and decc$feature_show.

94.2  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set.

95  –  decc$fix_time

    Converts OpenVMS binary system times to UNIX binary times.

    Format

      #include  <unixlib.h>

      unsigned int decc$fix_time  (void *vms_time);

95.1  –  Argument

 vms_time

    The address of a quadword containing an OpenVMS binary time:

    unsigned int quadword[2];
    unsigned int *vms_time = quadword;

95.2  –  Description

    The decc$fix_time routine converts an OpenVMS binary system time
    (a 64-bit quadword containing the number of 100-nanosecond ticks
    since 00:00 November 17, 1858) to a UNIX binary time (a longword
    containing the number of seconds since 00:00 January 1, 1970).
    This routine is useful for converting binary times returned by
    OpenVMS system services and RMS services to the format used by
    some C RTL routines, such as ctime and localtime.

95.3  –  Return Values

    x                  A longword containing the number of seconds
                       since 00:00 January 1, 1970.
    (unsigned          Indicates an error. Be aware, that a return
    int)(-1)           value of (unsigned int)(-1) can also represent
                       a valid date of Sun Feb 7 06:28:15 2106.

95.4  –  Example

        #include <unixlib.h>
        #include <stdio.h>
        #include <starlet.h>  /* OpenVMS specific SYS$ routines)  */

        main()
        {
        unsigned int current_vms_time[2];
        /*quadword for OpenVMS time*/
        unsigned int number_of_seconds;   /* number of seconds     */

        /* first get the current system time */
        sys$gettim(&current_vms_time[0]);

        /* fix the time */
        number_of_seconds = decc$fix_time(&current_vms_time[0]);

        printf("Number of seconds since 00:00 January 1, 1970 = %d",
                number_of_seconds);
        }

      This example shows how to use the decc$fix_time routine in
      VSI C. It also shows the use of the SYS$GETTIM system
      service.

96  –  decc$from_vms

    Converts OpenVMS file specifications to UNIX style file
    specifications.

    Format

      #include  <unixlib.h>

      int decc$from_vms  (const char *vms_filespec, int
                         action_routine, int wild_flag);

96.1  –  Arguments

 vms_filespec

    The address of a null-terminated string containing a name in
    OpenVMS file specification format.

 action_routine

    The address of a routine that takes as its only argument a null-
    terminated string containing the translation of the given OpenVMS
    filename to a valid UNIX style filename.

    If the action_routine returns a nonzero value (TRUE), file
    translation continues. If it returns a zero value (FALSE), no
    further file translation takes place.

 wild_flag

    Either 0 or 1, passed by value. If a 0 is specified, wildcards
    found in vms_filespec are not expanded. Otherwise, wildcards
    are expanded and each one is passed to action_routine. Only
    expanded filenames that correspond to existing UNIX style files
    are included.

96.2  –  Description

    The decc$from_vms routine converts the given OpenVMS file
    specification into the equivalent UNIX style file specification.
    It allows you to specify OpenVMS wildcards, which are translated
    into a list of corresponding existing files in UNIX style file
    specification format.

96.3  –  Return Value

    x                  The number of filenames that result from the
                       specified OpenVMS file specification.

96.4  –  Example

        /* This example must be run as a foreign command        */
        /* and be supplied with an OpenVMS file specification.  */

        #include <unixlib.h>
        #include <stdio.h>

        int main(int argc, char *argv[])
        {
            int number_found;           /* number of files found */
            int print_name();           /* name printer          */

            printf("Translating: %s\n", argv[1]);
            number_found = decc$from_vms(argv[1], print_name, 1);
            printf("\n%d files found", number_found);
        }

        /* print the name on each line */
        print_name(char *name)
        {
            printf("\n%s", name);
            /* will continue as long as success status is returned */
            return (1);
        }

      This example shows how to use the decc$from_vms routine in
      VSI C. It produces a simple form of the ls command that
      lists existing files that match an OpenVMS file specification
      supplied on the command line. The matching files are displayed
      in UNIX style file specification format.

97  –  decc$match_wild

    Matches a string to a pattern.

    Format

      #include  <unixlib.h>

      int decc$match_wild  (char *test_string, char *string_pattern);

97.1  –  Arguments

 test_string

    The address of a null-terminated string.

 string_pattern

    The address of a string containing the pattern to be matched.
    This pattern can contain wildcards (such as asterisks (*),
    question marks (?),  and percent signs (%) as well as regular
    expressions (such as the range [a-z]).

97.2  –  Description

    The decc$match_wild routine determines whether the specified
    test string is a member of the set of strings specified by the
    pattern.

97.3  –  Return Values

    1 (TRUE)           The string matches the pattern.
    0 (FALSE)          The string does not match the pattern.

97.4  –  Example

        /* Define as a foreign command and then provide */
        /* two arguments: test_string, string_pattern.  */

        #include <unixlib.h>
        #include <stdio.h>
        int main(int argc, char *argv[])
        {
            if (decc$match_wild(argv[1], argv[2]))
                printf("\n%s matches %s", argv[1], argv[2]);
            else
                printf("\n%s does not match %s", argv[1], argv[2]);
        }

98  –  decc$record_read

    Reads a record from a file.

    Format

      #include  <stdio.h>

      int decc$record_read  (FILE *fp, void *buffer, int nbytes);

98.1  –  Arguments

 fp

    A file pointer. The specified file pointer must refer to a file
    currently opened for reading.

 buffer

    The address of contiguous storage in which the input data is
    placed.

 nbytes

    The maximum number of bytes involved in the read operation.

98.2  –  Description

    The decc$record_read function is specific to OpenVMS systems and
    should not be used when writing portable applications.

    This function is equivalent to the read function, except that the
    first argument is a file pointer, not a file descriptor.

98.3  –  Return Values

    x                  The number of characters read.
    -1                 Indicates a read error, including physical
                       input errors, illegal buffer addresses,
                       protection violations, undefined file
                       descriptors, and so forth.

99  –  decc$record_write

    Writes a record to a file.

    Format

      #include  <stdio.h>

      int decc$record_write  (FILE *fp, void *buffer, int nbytes);

99.1  –  Arguments

 fp

    A file pointer. The specified file pointer must refer to a file
    currently opened for writing or updating.

 buffer

    The address of contiguous storage from which the output data is
    taken.

 nbytes

    The maximum number of bytes involved in the write operation.

99.2  –  Description

    The decc$record_write function is specific to OpenVMS systems and
    should not be used when writing portable applications.

    This function is equivalent to the write function, except that
    the first argument is a file pointer, not a file descriptor.

99.3  –  Return Values

    x                  The number of bytes written.
    -1                 Indicates errors, including undefined file
                       descriptors, illegal buffer addresses, and
                       physical I/O errors.

100  –  decc$set_child_default_dir

    Sets the default directory for a child process spawned by a
    function from the exec family of functions.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unixlib.h>

      int decc$set_child_default_dir  (const char *default_dir);

100.1  –  Arguments

 default_dir

    The default directory specification for child processes, or NULL.

100.2  –  Description

    By default, child processes created by one of the exec family of
    functions inherit the default (working) directory of their parent
    process.

    The decc$set_child_default_dir function lets you set the
    default directory for a child process. After calling decc$set_
    child_default_dir, newly spawned child processes have their
    default directory set to default_dir as they begin execution.
    The default_dir argument must represent a valid directory
    specification, or results of the call are unpredictable
    (subsequent calls to the child process might fail without
    notification). Both OpenVMS and UNIX style file specifications
    are supported for this function call.

    You can reestablish the default behavior by specifying default_
    dir as NULL. Subsequently, newly created child processes will
    inherit their parent's working directory.

100.3  –  Return Values

    0                  Successful completion. The new inherited
                       default directory was established.
    -1                 Indicates failure. No new default directory
                       was established for child processes. The
                       function sets errno to one of the following
                       values:

                       o  ENOMEM - Insufficient memory

                       o  ENAMETOOLONG - default_dir is too long to
                          issue the required SET DEFAULT command.

101  –  decc$set_child_standard_streams

    For a child spawned by a function from the exec family of
    functions, associates specified file descriptors with a child's
    standard streams: stdin, stdout, and stderr.

    Format

      #include  <unixlib.h>

      int decc$set_child_standard_streams  (int fd1, int fd2, int fd3);

101.1  –  Arguments

 fd1

    The file associated with this file descriptor in the parent
    process is associated with file descriptor number 0 (stdin) in
    the child process. If -1 is specified, the file associated with
    the parent's file descriptor number 0 is used (the default).

 fd2

    The file associated with this file descriptor in the parent
    process is associated with file descriptor number 1 (stdout) in
    the child process. If -1 is specified, the file associated with
    the parent's file descriptor number 1 is used (the default).

 fd3

    The file associated with this file descriptor in the parent
    process is associated with file descriptor number 2 (stderr) in
    the child process. If -1 is specified, the file associated with
    the parent's file descriptor number 2 is used (the default).

101.2  –  Description

    The decc$set_child_standard_streams function allows mapping of
    specified file descriptors to the child's stdin/stdout/stderr
    streams, thereby compensating, to a certain degree, the lack of a
    real fork function on OpenVMS systems.

    On UNIX systems, the code between fork and exec is executed in
    the context of the child process:

    parent:
      create pipes p1, p2 and p3
      fork
    child:

      map stdin to p1  like dup2(p1, stdin);
      map stdout to p2 like dup2(p2, stdout);
      map stderr to p3 like dup2(p3, stderr);

      exec (child reads from stdin and writes to stdout and stderr)
      exit
    parent:
      communicates with the child using pipes

    On OpenVMS systems, the same task could be achieved as follows:

    parent:
      create pipes p1, p2 and p3
      decc$set_child_standard_streams(p1, p2, p3);
      vfork
      exec (child reads from stdin and writes to stdout and stderr)
    parent:
      communicates with the child using pipes

    Once established through the call to decc$set_child_standard_
    streams, the mapping of the child's standard streams remains in
    effect until explicitly disabled by one of the following calls:

    decc$set_child_standard_streams(-1, -1, -1);

    Or:

    decc$set_child_standard_streams(0, 1, 2);

    Usually, the child process inherits all its parent's open file
    descriptors. However, if file descriptor number n was specified
    in the call to decc$set_child_standard_streams, it is not
    inherited by the child process as file descriptor number n;
    instead, it becomes one of the child's standard streams.

                                  NOTES

       o  Standard streams can be redirected only to pipes.

       o  If the parent process redefines the DCL DEFINE command,
          this redefinition is not in effect in a subprocess with
          user-defined channels. The subprocess always sees the
          standard DCL DEFINE command.

       o  It is the responsibility of the parent process to consume
          all the output written by the child process to stdout and
          stderr. Depending on how the subprocess writes to stdout
          and stderr-in wait or nowait mode-the subprocess might be
          placed in LEF state waiting for the reader. For example,
          DCL writes to SYS$OUTPUT and SYS$ERROR in a wait mode,
          so a child process executing a DCL command procedure will
          wait until all the output is read by the parent process.

          Recommendation: Read the pipes associated with the child
          process' stdout and stderr in a loop until an EOF message
          is received, or declare write attention ASTs on these
          mailboxes.

       o  The amount of data written to SYS$OUTPUT depends on the
          verification status of the process (SET VERIFY/NOVERIFY
          command); the subprocess inherits the verification status
          of the parent process. It is the caller's responsibility
          to set the verification status of the parent process to
          match the expected amount of data written to SYS$OUTPUT
          by the subprocess.

       o  Some applications, like DTM, define SYS$ERROR as
          SYS$OUTPUT. If stderr is not redefined by the caller,
          it is set in the subprocess as the parent's SYS$ERROR,
          which in this case translates to the parent's SYS$OUTPUT.

          If the caller redefines stdout to a pipe and does not
          redefine stderr, output sent to stderr goes to the pipe
          associated with stdout, and the amount of data written
          to this mailbox may be more than expected. Although
          redefinition of any subset of standard channels is
          supported, it is always safe to explicitly redefine all
          of them (or at least stdout and stderr) to avoid this
          situation.

       o  For a child process executing a DCL command procedure,
          SYS$COMMAND is set to the pipe specified for the child's
          stdin so that the parent process can feed the child
          requesting data from SYS$COMMAND through the pipe. For
          DCL command procedures, it is impossible to pass data
          from the parent to the child by means of the child's
          SYS$INPUT because for a command procedure, DCL defines
          SYS$INPUT as the command file itself.

101.3  –  Return Values

    x                  The number of file descriptors set for the
                       child. This number does not include file
                       descriptors specified as -1 in the call.
    -1                 indicates that an invalid file descriptor was
                       specified; errno is set to EBADF.

101.4  –  Example

        parent.c

        #include <stdio.h>
        #include <string.h>
        #include <unistd.h>

        int decc$set_child_standard_streams(int, int, int);

        main()
        {
            int fdin[2], fdout[2], fderr[2];
            char msg[] = "parent writing to child's stdin";
            char buf[80];
            int nbytes;

            pipe(fdin);
            pipe(fdout);
            pipe(fderr);

            if ( vfork() == 0 ) {
           decc$set_child_standard_streams(fdin[0], fdout[1], fderr[1]);
              execl( "child", "child" );
            }
            else {
                write(fdin[1], msg, sizeof(msg));
                nbytes = read(fdout[0], buf, sizeof(buf));
                buf[nbytes] = '\0';
                puts(buf);
                nbytes = read(fderr[0], buf, sizeof(buf));
                buf[nbytes] = '\0';
                puts(buf);
            }
        }

        child.c

        #include <stdio.h>
        #include <unistd.h>

        main()
        {
            char msg[] = "child writing to stderr";
            char buf[80];
            int nbytes;

            nbytes = read(0, buf, sizeof(buf));
            write(1, buf, nbytes);
            write(2, msg, sizeof(msg));
        }

        child.com

        $ read sys$command s
        $ write sys$output s
        $ write sys$error "child writing to stderr"

      This example program returns the following for both child.c and
      child.com:

        $ run parent
        parent writing to child's stdin
        child writing to stderr

      Note that in order to activate child.com, you must explicitly
      specify execl("child.com", ...) in the parent.c program.

102  –  decc$set_reentrancy

    Controls the type of reentrancy that reentrant C RTL
    routines will exhibit.

    Format

      #include  <reentrancy.h>

      int decc$set_reentrancy  (int type);

102.1  –  Argument

 type

    The type of reentrancy desired. Use one of the following values:

    o  C$C_MULTITHREAD - Designed to be used in conjunction with the
       DECthreads product. It performs DECthreads locking and never
       disables ASTs. DECthreads must be available on your system to
       use this form of reentrancy.

    o  C$C_AST - Uses the __TESTBITSSI (Integrity servers, Alpha)
       built-in function to perform simple locking around critical
       sections of RTL code, and it may additionally disable
       asynchronous system traps (ASTs) in locked regions of
       code. This type of locking should be used when AST code
       contains calls to C RTL I/O routines, or when the user
       application disables ASTs.

    o  C$C_TOLERANT - Uses the
       __TESTBITSSI (Integrity servers, Alpha)  built-in function
       to perform simple locking around critical sections of RTL
       code, but ASTs are not disabled. This type of locking should
       be used when ASTs are used and must be delivered immediately.
       TOLERANT is the default reentrancy type.

    o  C$C_NONE - Gives optimal performance in the C RTL, but
       does absolutely no locking around critical sections of RTL
       code. It should only be used in a single-threaded environment
       when there is no chance that the thread of execution will be
       interrupted by an AST that would call the C RTL.

    The reentrancy type can be raised but never lowered. The ordering
    of reentrancy types from low to high is C$C_NONE, C$C_TOLERANT,
    C$C_AST and C$C_MULTITHREAD. For example, once an application
    is set to multithread, a call to set the reentrancy to AST is
    ignored. A call to decc$set_reentrancy that attempts to lower the
    reentrancy type returns a value of -1.

102.2  –  Description

    Use the decc$set_reentrancy function to change the type of
    reentrancy exhibited by reentrant routines.

    decc$set_reentrancy must be called exclusively at the non-AST
    level.

    In an application using DECthreads, DECthreads automatically sets
    the reentrancy to multithread.

102.3  –  Return Value

    type               The type of reentrancy used before this call.
    -1                 The reentrancy was set to a lower type.

103  –  decc$to_vms

    Converts UNIX style file specifications to OpenVMS file
    specifications.

    Format

      #include  <unixlib.h>

      int decc$to_vms  (const char *unix_style_filespec,
                       int (*action_routine)
                       (char *OpenVMS_style_filespec, int type_of_file),
                       int allow_wild, int no_directory);

103.1  –  Arguments

 unix_style_filespec

    The address of a null-terminated string containing a name in UNIX
    style file specification format.

 action_routine

    The address of a routine called by decc$to_vms that accepts the
    following arguments:

    o  A pointer to a null-terminated string that is the result of
       the translation to OpenVMS format.

    o  An integer that has one of the following values:

       Value               Translation

       0 (DECC$K_FOREIGN)  A file on a remote system that is not
                           running the OpenVMS or VAXELN operating
                           system.
       1 (DECC$K_FILE)     The translation is a file.
       2 (DECC$K_          The OpenVMS translation of the UNIX style
       DIRECTORY)          filename is a directory.

       These values can be defined symbolically with the symbols
       DECC$K_FOREIGN, DECC$K_FILE, and DECC$K_DIRECTORY. See the
       example for more information.

    If action_routine returns a nonzero value (TRUE), file
    translation continues. If it returns a 0 value (FALSE), no
    further file translation takes place.

 allow_wild

    Either 0 or 1, passed by value. If a 0 is specified, wildcards
    found in unix_style_filespec are not expanded. Otherwise,
    wildcards are expanded and each one is passed to action_routine.
    Only expanded filenames that correspond to existing OpenVMS files
    are included.

 no_directory

    An integer that has one of the following values:

    Value            Translation

    0                Directory allowed.
    1                Prevent expansion of the string as a directory
                     name.
    2                Forced to be a directory name.

103.2  –  Description

    The decc$to_vms function converts the given UNIX style file
    specification into the equivalent OpenVMS file specification
    (in all uppercase letters). It allows you to specify UNIX style
    wildcards, which are translated into a list of corresponding
    OpenVMS files.

    Note that the following feature logicals can affect the behavior
    of decc$to_vms:

       DECC$DISABLE_TO_VMS_LOGNAME_TRANSLATION
       DECC$NO_ROOTED_SEARCH_LISTS

103.3  –  Return Value

    x                  The number of filenames that result from the
                       specified UNIX style file specification.

103.4  –  Example

        /* Translate "UNIX" wildcard file names to OpenVMS names.*/
        /* Define as a foreign command and provide the name as   */
        /* an argument.                                          */

        #include <unixlib.h>
        #include <stdio.h>
        int print_name(char *, int);
        int main(int argc, char *argv[])
        {
            int number_found;           /* number of files found */

            printf("Translating: %s\n", argv[1]);

            number_found = decc$to_vms(argv[1], print_name, 1, 0);
            printf("%d files found\n", number_found);
        }

        /* action routine that prints name and type on each line */

        int print_name(char *name, int type)
        {
            if (type == DECC$K_DIRECTORY)
                printf("directory: %s\n", name);
            else if (type == DECC$K_FOREIGN)
                printf("remote non-VMS: %s\n", name);
            else
                printf("file:        %s\n", name);

        /* Translation continues as long as success status is returned */
            return (1);
        }

      This example shows how to use the decc$to_vms routine in
      VSI C. It takes a UNIX style file specification argument
      and displays, in OpenVMS file specification format, the name of
      each existing file that matches it.

104  –  decc$translate_vms

    Translates OpenVMS file specifications to UNIX style file
    specifications.

    Format

      #include  <unixlib.h>

      char *decc$translate_vms  (const char *vms_filespec);

104.1  –  Argument

 vms_filespec

    The address of a null-terminated string containing a name in
    OpenVMS file specification format.

104.2  –  Description

    The decc$translate_vms function translates the given OpenVMS file
    specification into the equivalent UNIX style file specification,
    whether or not the file exists. The translated name string is
    stored in a thread-specific memory, which is overwritten by each
    call to decc$translate_vms from the same thread.

    This function differs from the decc$from_vms function, which does
    the conversion for existing files only.

104.3  –  Return Values

    x                  The address of a null-terminated string
                       containing a name in UNIX style file
                       specification format.
    0                  Indicates that the filename is null or
                       syntactically incorrect.
    -1                 Indicates that the file specification contains
                       an ellipsis (for example, [ . . . ]a.dat), but
                       is otherwise correct. You cannot translate
                       the OpenVMS ellipsis syntax into a valid UNIX
                       style file specification.

104.4  –  Example

        /* Demonstrate translation of a "UNIX" name to OpenVMS  */
        /* form, define a foreign command, and pass the name as */
        /* the argument.                                        */

        #include <unixlib.h>
        #include <stdio.h>

        int main(int argc, char *argv[])
        {
            char *ptr;                      /* translation result */

            ptr = decc$translate_vms( argv[1] );

            if ((int) ptr == 0 || (int) ptr == -1)

                printf( "could not translate %s\n", argv[1]);
            else
                printf( "%s is translated to %s\n", argv[1], ptr );
        }

105  –  decc$validate_wchar

    Confirms that its argument is a valid wide character in the
    current program's locale.

    Format

      #include  <unistd.h>

      int decc$validate_wchar  (wchar_t wc);

105.1  –  Argument

 wc

    Wide character to be validated.

105.2  –  Description

    The decc$validate_wchar function provides a convenient way to
    verify whether a specified argument of wchar_t type is a valid
    wide character in the current program's locale.

    One reason to call decc$validate_wchar is that the isw* wide-
    character classification functions and macros do not validate
    their argument before dereferencing the classmask array
    describing character properties. Passing an isw* function a value
    that exceeds the maximum wide-character value for the current
    program's locale can result in an attempt to access memory beyond
    the allocated classmask array.

    A standard way to validate a wide character is to call the wctomb
    function, but this way is less convenient because it requires
    declaring a multibyte character array of sufficient size and
    passing it to wctomb.

105.3  –  Return Values

    1                  Indicates that the specified wide character
                       is a valid wide character in the current
                       program's locale.
    0                  Indicates that the specified wide character
                       is not a valid wide character in the current
                       program's locale. errno is not set.

106  –  decc$write_eof_to_mbx

    Writes an end-of-file message to the mailbox.

    Format

      #include  <unistd.h>

      int decc$write_eof_to_mbx  (int fd);

106.1  –  Argument

 fd

    File descriptor associated with the mailbox.

106.2  –  Description

    The decc$write_eof_to_mbx function writes end-of-file message to
    the mailbox.

    For a mailbox that is not a pipe, the write function called with
    an nbytes argument value of 0 sends an end-of-file message to the
    mailbox. For a pipe, however, the only way to write an end-of-
    file message to the mailbox is to close the pipe.

    If the child's standard input is redirected to a pipe through a
    call to the decc$set_child_standard_streams function, the parent
    process can call decc$write_eof_to_mbx for this pipe to send an
    EOF message to the child. It has the same effect as if the child
    read the data from a terminal, and Ctrl/Z was pressed.

    After a call to decc$write_eof_to_mbx, the pipe can be reused
    for communication with another child, for example. This is
    the purpose of decc$write_eof_to_mbx: to allow reuse of the
    pipe instead of having to close it just to send an end-of-file
    message.

106.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure; errno and vaxc$errno are
                       set according to the failure status returned
                       by SYS$QIOW.

106.4  –  Example

        /*      decc$write_eof_to_mbx_example.c         */

        #include <errno.h>
        #include <stdio.h>
        #include <string.h>

        #include <fcntl.h>
        #include <unistd.h>
        #include <unixio.h>

        #include <descrip.h>
        #include <ssdef.h>
        #include <starlet.h>

        int decc$write_eof_to_mbx( int );

        main()
        {
          int status, nbytes, failed = 0;
          int fd, fd2[2];
          short int channel;
          $DESCRIPTOR(mbxname_dsc, "TEST_MBX");
          char c;

          /* first try a mailbox created by SYS$CREMBX        */

        status = sys$crembx(0, &channel, 0, 0, 0, 0, &mbxname_dsc, 0, 0);
        if ( status != SS$_NORMAL ) {
             printf("sys$crembx failed: %s\n",strerror(EVMSERR, status));
             failed = 1;
          }

         if ( (fd = open(mbxname_dsc.dsc$a_pointer, O_RDWR, 0)) == -1) {
              perror("? open mailbox");
              failed = 1;
          }

          if ( decc$write_eof_to_mbx(fd) == -1 ) {
              perror("?  decc$write_eof_to_mbx to mailbox");
              failed = 1;
          }

          if ( (nbytes = read(fd, &c, 1)) != 0 || errno != 0 ) {
              perror("? read mailbox");
              printf("? nbytes = %d\n", nbytes);
              failed = 1;
          }

          if ( close(fd) == -1 ) {
              perror("? close mailbox");
              failed = 1;
          }

          /* Now do the same thing with a pipe                */

          errno = 0;           /* Clear errno for consistency */

          if ( pipe(fd2) == -1 ) {
              perror("? opening pipe");
              failed = 1;
          }

          if ( decc$write_eof_to_mbx(fd2[1]) == -1 ) {
              perror("? decc$write_eof_to_mbx to pipe");
              failed = 1;
          }

          if ( (nbytes = read(fd2[0], &c, 1)) != 0 || errno != 0 ) {
              perror("? read pipe");
              printf("? nbytes = %d\n", nbytes);
              failed = 1;
          }

          /* Close both file descriptors involved with the pipe    */

          if ( close(fd2[0]) == -1 ) {
              perror("close(fd2[0])");
              failed = 1;
          }

          if ( close(fd2[1]) == -1 ) {
              perror("close(fd2[1])");
              failed = 1;
          }

          if ( failed )
              puts("?Example program failed");
          else
              puts("Example ran to completion");
        }

      This example program produces the following result:

        Example ran to completion

107  –  [w]delch

    Delete the character on the specified window at the current
    position of the cursor. The delch function operates on the stdscr
    window.

    Format

      #include  <curses.h>

      int delch();

      int wdelch  (WINDOW *win);

107.1  –  Argument

 win

    A pointer to the window.

107.2  –  Description

    All of the characters to the right of the cursor on the same line
    are shifted to the left, and a blank character is appended to the
    end of the line.

107.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

108  –  delete

    Deletes a file.

    Format

      #include  <unixio.h>

      int delete  (const char *file_spec);

108.1  –  Argument

 file_spec

    A pointer to the string that is an OpenVMS or UNIX style file
    specification. The file specification can include a wildcard in
    its version number (but not in any other part of the file spec).
    So, for example, files of the form filename.txt;* can be deleted.

108.2  –  Description

    If you specify a directory in the filename and it is a search
    list that contains an error, VSI C for OpenVMS Systems
    interprets it as a file error.

    When delete is used to delete a symbolic link, the link itself is
    deleted, not the file to which it refers.

    The remove and delete functions are functionally equivalent in
    the C RTL.

    See also remove.

                                   NOTE

       The delete routine is not available to C++ programmers
       because it conflicts with the C++ reserved word delete.
       C++ programmers should use the ANSI/ISO C standard function
       remove instead.

108.3  –  Return Values

    0                  Indicates success.
    nonzero value      Indicates that the operation has failed.

109  –  [w]deleteln

    Delete the line at the current position of the cursor. The
    deleteln function acts on the stdscr window.

    Format

      #include  <curses.h>

      int deleteln();

      int wdeleteln  (WINDOW *win);

109.1  –  Argument

 win

    A pointer to the window.

109.2  –  Description

    Every line below the deleted line moves up, and the bottom line
    becomes blank. The current (y,x) coordinates of the cursor remain
    unchanged.

109.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

110  –  delwin

    Deletes the specified window from memory.

    Format

      #include  <curses.h>

      int delwin  (WINDOW *win);

110.1  –  Argument

 win

    A pointer to the window.

110.2  –  Description

    If the window being deleted contains a subwindow, the subwindow
    is invalidated. Delete subwindows before deleting their parent.
    The delwin function refreshes all windows covered by the deleted
    window.

110.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

111  –  difftime

    Computes the difference, in seconds, between the two times
    specified by the time1 and time2 arguments.

    Format

      #include  <time.h>

      double difftime  (time_t time2, time_t time1);

111.1  –  Arguments

 time2

    A time value of type time_t.

 time1

    A time value of type time_t.

111.2  –  Description

    The type time_t is defined in the <time.h> header file as
    follows:

    typedef unsigned long int time_t

111.3  –  Return Value

    n                  time2 - time1 in seconds expressed as a
                       double.

112  –  dirname

    Reports the parent directory name of a file pathname.

    Format

      #include  <libgen.h>

      char *dirname  (char *path);

112.1  –  Function Variants

    The dirname function has variants named _dirname32 and _dirname64
    for use with 32-bit and 64-bit pointer sizes, respectively.

112.2  –  Argument

 path

    The file pathname.

112.3  –  Description

    The dirname function takes a pointer to a character string that
    contains a UNIX pathname and returns a pointer to a string that
    is a pathname of the parent directory of that file. Trailing
    slash (/)  characters in the path are not counted as part of the
    path.

    This function returns a pointer to the string "." (dot), when the
    path argument:

    o  Does not contain a slash (/).

    o  Is a NULL pointer.

    o  Points to an empty string.

    The dirname function can modify the string pointed to by the path
    argument.

    The dirname and basename functions together yield a complete
    pathname. The expression dirname(path) obtains the pathname of
    the directory where basename(path) is found.

    See also basename.

112.4  –  Return Values

    x                  A pointer to a string that is the parent
                       directory of the path argument.
    "."                The path argument:

                       o  Does not contain a slash (/).

                       o  Is a NULL pointer.

                       o  Points to an empty string.

112.5  –  Example

      Using the dirname function, the following example reads a
      pathname, changes the current working directory to the parent
      directory, and opens a file.

            char path [MAXPATHLEN], *pathcopy;
            int fd;

            fgets(path, MAXPATHLEN, stdin);
            pathcopy = strdup(path);
            chdir(dirname(pathcopy));
            fd = open(basename(path), O_RDONLY);

113  –  div

    Returns the quotient and the remainder after the division of its
    arguments.

    Format

      #include  <stdlib.h>

      div_t div  (int numer, int denom);

113.1  –  Arguments

 numer

    A numerator of type int.

 denom

    A denominator of type int.

113.2  –  Description

    The type div_t is defined in the standard header file <stdlib.h>
    as follows:

    typedef struct
            {
                 int   quot, rem;
            } div_t;

114  –  dlclose

    Deallocates the address space for a shared library.

    Format

      #include  <dlfcn.h>

      void dlclose  (void *handle);

114.1  –  Argument

 handle

    Pointer to the shared library.

114.2  –  Description

    The dlclose function deallocates the address space allocated by
    the C RTL for the handle.

    There is no way on OpenVMS systems to unload a shareable image
    dynamically loaded by the LIB$FIND_IMAGE_SYMBOL routine, which
    is the routine called by the dlsym function. In other words,
    there is no way on OpenVMS systems to release the address space
    occupied by the shareable image brought into memory by dlsym.

115  –  dlerror

    Returns a string describing the last error that occurred from a
    call to dlopen, dlclose, or dlsym.

    Format

      #include  <dlfcn.h>

      char *dlerror  (void);

115.1  –  Return Value

    x                  A string describing the last error that
                       occurred from a call to dlopen, dlclose, or
                       dlsym.

116  –  dlopen

    Provides an interface to the dynamic library loader to allow
    shareable images to be loaded and called at run time.

    Format

      #include  <dlfcn.h>

      void *dlopen  (char *pathname, int mode);

116.1  –  Arguments

 pathname

    The name of the shareable image. This name is saved for
    subsequent use by the dlsym function.

 mode

    This argument is ignored on OpenVMS systems.

116.2  –  Description

    The dlopen function provides an interface to the dynamic library
    loader to allow shareable images to be loaded and called at run
    time.

    This function does not load a shareable image but rather saves
    its pathname argument for subsequent use by the dlsym function.
    dlsym is the function that actually loads the shareable image
    through a call to LIB$FIND_IMAGE_SYMBOL.

    The pathname argument of the dlopen function must be the name
    of the shareable image. This name is passed as-is by the dlsym
    function to the LIB$FIND_IMAGE_SYMBOL routine as the filename
    argument. No image-name argument is specified in the call
    to LIB$FIND_IMAGE_SYMBOL, so default file specification of
    SYS$SHARE:.EXE is applied to the image name.

    The dlopen function returns a handle that is used by a dlsym or
    dlclose call. If an error occurs, a NULL pointer is returned.

116.3  –  Return Values

    x                  A handle to be used by a dlsym or dlclose
                       call.
    NULL               Indicates an error.

117  –  dlsym

    Returns the address of the symbol name found in a shareable
    image.

    Format

      #include  <dlfcn.h>

      void *dlsym  (void *handle, char *name);

117.1  –  Arguments

 handle

    Pointer to the shareable image.

 name

    Pointer to the symbol name.

117.2  –  Description

    The dlsym function returns the address of the symbol name found
    in the shareable image corresponding to handle. If the symbol is
    not found, a NULL pointer is returned.

    As of OpenVMS Version 7.3-2, library symbols containing
    lowercase characters can be loaded using the dlsym function. More
    generally, the functions that dynamically load libraries (dlopen,
    dlsym, dlclose, dlerror) are enhanced to provide the following
    capabilities:

    o  Support for libraries with mixed-case symbol names

    o  Ability to pass a full file path to dlopen

    o  Validation of the specified library name

117.3  –  Return Values

    x                  Address of the symbol name found.
    NULL               Indicates that the symbol was not found.

118  –  drand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit, nonnegative, double-precision floating-point
    values.

    Format

      #include  <stdlib.h>

      double drand48  (void);

118.1  –  Description

    The drand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    It returns nonnegative, double-precision, floating-point values
    uniformly distributed over the range of y values such that 0.0 
    y < 1.0.

    Before you call drand48, use either srand48, seed48, or lcong48
    to initialize the random-number generator. You must initialize
    prior to invoking the drand48 function because it stores the last
    48-bit Xi generated into an internal buffer. (Although it is not
    recommended, constant default initializer values are supplied
    automatically if the drand48, lrand48, or mrand48 functions are
    called without first calling an initialization function.)

    The drand48 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 lcong48, the multiplier value a
    and the addend value c are:

         a = 5DEECE66D16 = 2736731631558

         c = B16 = 138

    The values returned by drand48 are computed by first generating
    the next 48-bit Xi in the sequence. Then the appropriate bits,
    according to the type of returned data item, are copied from the
    high-order (most significant) bits of Xi and transformed into the
    returned value.

    See also srand48, seed48, lcong48, lrand48, and mrand48.

118.2  –  Return Value

    n                  A nonnegative, double-precision, floating-
                       point value.

119  –  dup,dup2

    Allocate a new descriptor that refers to a file specified by a
    file descriptor returned by open, creat, or pipe.

    Format

      #include  <unistd.h>

      int dup  (int file_desc1);

      int dup2  (int file_desc1, int file_desc2);

119.1  –  Arguments

 file_desc1

    The file descriptor being duplicated.

 file_desc2

    The new file descriptor to be assigned to the file designated by
    file_desc1.

119.2  –  Description

    The dup function causes a previously unallocated descriptor to
    refer to its argument, while the dup2 function causes its second
    argument to refer to the same file as its first argument.

    The argument file_desc1 is invalid if it does not describe an
    open file; file_desc2 is invalid if the new file descriptor
    cannot be allocated. If file_desc2 is connected to an open file,
    that file is closed.

119.3  –  Return Values

    n                  The new file descriptor.
    -1                 Indicates that an invalid argument was passed
                       to the function.

120  –  [no]echo

    Set the terminal so that characters may or may not be echoed on
    the terminal screen. This mode of single-character input is only
    supported with Curses.

    Format

      #include  <curses.h>

      void echo  (void);

      void noecho  (void);

120.1  –  Description

    The noecho function may be helpful when accepting input from the
    terminal screen with wgetch and wgetstr; it prevents the input
    characters from being written onto the screen.

121  –  ecvt

    Converts its argument to a null-terminated string of ASCII digits
    and returns the address of the string. The string is stored in a
    thread-specific memory location created by the C RTL.

    Format

      #include  <stdlib.h>

      char *ecvt  (double value, int ndigits, int *decpt, int *sign);

121.1  –  Arguments

 value

    An object of type double that is converted to a null-terminated
    string of ASCII digits.

 ndigits

    The number of ASCII digits to be used in the converted string.

 decpt

    The position of the decimal point relative to the first character
    in the returned string. A negative int value means that the
    decimal point is decpt number of spaces to the left of the
    returned digits (the spaces being filled with zeros). A 0 value
    means that the decimal point is immediately to the left of the
    first digit in the returned string.

 sign

    An integer value that indicates whether the value argument is
    positive or negative. If value is negative, the function places
    a nonzero value at the address specified by sign. Otherwise, the
    function assigns 0 to the address specified by sign.

121.2  –  Description

    The ecvt function converts value to a null-terminated string
    of length ndigits, and returns a pointer to it. The resulting
    low-order digit is rounded to the correct digit for outputting
    ndigits digits in C E-format. The decpt argument is assigned the
    position of the decimal point relative to the first character in
    the string.

    Repeated calls to the ecvt function overwrite any existing
    string.

    The ecvt, fcvt, and gcvt functions represent the following
    special values specified in the IEEE Standard for floating-point
    arithmetic:

    Value         Representation

    Quiet NaN     NaNQ
    Signalling    NaNS
    NaN
    +Infinity     Infinity
    -Infinity     -Infinity

    The sign associated with each of these values is stored into the
    sign argument. In IEEE floating-point representation, a value
    of 0 (zero) can be positive or negative, as set by the sign
    argument.

    See also gcvt and fcvt.

121.3  –  Return Value

    x                  The value of the converted string.

122  –  encrypt

    Encrypts a string using the key generated by the setkey function.

    Format

      #include  <unistd.h>

      #include  <stdlib.h>

      void encrypt  (char *block[64], int edflag;)

122.1  –  Argument

 block

    A character array of length 64 containing 0s and 1s.

 edflag

    An integer. If edflag is 0, the argument is encrypted; if
    nonzero, it is decrypted.

122.2  –  Description

    The encrypt function encrypts a string using the key generated by
    the setkey function.

    The first argument to encrypt is a character array of length 64
    containing 0s and 1s. The argument array is modified in place
    to a similar array representing the bits of the argument after
    having been subjected to the DES algorithm using the key set by
    setkey.

    The second argument, edflag, determines whether the first
    argument is encrypted or decrypted: if edflag is 0, the first
    argument array is encrypted; if nonzero, it is decrypted.

    No value is returned.

    See also crypt and setkey.

122.3  –  Return Value

    pointer            Pointer to the encrypted password.

123  –  endgrent

    Closes the group database when processing is complete.

    Format

      #include  <grp.h>

      void endgrent  (void);

123.1  –  Description

    The endgrent function closes the group database.

    This function is always successful. No value is returned, and
    errno is not set.

124  –  endpwent

    Closes the user database and any private stream used by getpwent.

    Format

      #include  <pwd.h>

      void endpwent  (void);

124.1  –  Description

    The endpwent function closes the user database and any private
    stream used by getpwent.

    No value is returned. If an I/O error occurred, the function sets
    errno to EIO.

    See also getpwent, getpwuid, getpwnam, and setpwent.

125  –  endwin

    Clears the terminal screen and frees any virtual memory allocated
    to Curses data structures.

    Format

      #include  <curses.h>

      void endwin  (void);

125.1  –  Description

    A program that calls Curses functions must call the endwin
    function before exiting to restore the previous environment of
    the terminal screen.

126  –  erand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit nonnegative, double-precision, floating-point
    values.

    Format

      #include  <stdlib.h>

      double erand48  (unsigned short int xsubi[3]);

126.1  –  Argument

 xsubi

    An array of three short ints, which form a 48-bit integer when
    concatenated together.

126.2  –  Description

    The erand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    It returns nonnegative, double-precision, floating-point values
    uniformly distributed over the range of y values, such that 0.0
    <= y < 1.0.

    The erand48 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 erand48 function requires that the calling program pass an
    array as the xsubi argument. For the first call, the array must
    be initialized to the value of the pseudorandom-number sequence.
    Unlike the drand48 function, it is not necessary to call an
    initialization function prior to the first call.

    By using different arguments, the erand48 function allows
    separate modules of a large program to generate several
    independent sequences of pseudorandom numbers; for example, the
    sequence of numbers that one module generates does not depend
    upon how many times the function is called by other modules.

126.3  –  Return Value

    n                  A nonnegative, double-precision, floating-
                       point value.

127  –  [w]erase

    Erases the window by painting it with blanks. The erase function
    acts on the stdscr window.

    Format

      #include  <curses.h>

      int erase();

      int werase  (WINDOW *win);

127.1  –  Argument

 win

    A pointer to the window.

127.2  –  Description

    Both the erase and werase functions leave the cursor at the
    current position on the terminal screen after completion; they
    do not return the cursor to the home coordinates of (0,0).

127.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

128  –  erf

    Returns the error function of its argument.

    Format

      #include  <math.h>

      double erf  (double x);

      float erff  (float x); (Integrity servers, Alpha)

      long double erfl  (long double x); (Integrity servers, Alpha)

      double erfc  (double x); (Integrity servers, Alpha)

      float erfcf  (float x); (Integrity servers, Alpha)

      long double erfcl  (long double x); (Integrity servers, Alpha)

128.1  –  Argument

 x

    A radian expressed as a real number.

128.2  –  Description

    The erf functions return the error function of x, where erf(x),
    erff(x), and erfl(x) equal 2/sqrt(pi) times the area under the
    curve e**(-t**2) between 0 and x.

    The erfc functions return (1.0 - erf(x)). The erfc function can
    result in an underflow as x gets large.

128.3  –  Return Values

    x                  The value of the error function (erf) or
                       complementary error function (erfc).
    NaN                x is NaN; errno is set to EDOM.
    0                  Underflow occurred; errno is set to ERANGE.

129  –  execl

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execl  (const char *file_spec, const char *arg0, . . . ,
                 (char *)0); (ISO POSIX-1)

      int execl  (char *file_spec, . . . ); (Compatibility)

129.1  –  Arguments

 file_spec

    The full file specification of a new image to be activated in the
    child process.

 arg0, ...

    A sequence of pointers to null-terminated character strings.

    If the POSIX-1 format is used, at least one argument must be
    present and must point to a string that is the same as the new
    process filename (or its last component). (This pointer can also
    be the NULL pointer, but then execle would accomplish nothing.)
    The last pointer must be the NULL pointer. This is also the
    convention if the compatibility format is used.

129.2  –  Description

    To understand how the exec functions operate, consider how
    the OpenVMS system calls any VSI C program, as shown in the
    following syntax:

    int main (int argc, char *argv[], char *envp[]);

    The identifier argc is the argument count; argv is an array
    of argument strings. The first member of the array (argv[0])
    contains the name of the image. The arguments are placed in
    subsequent elements of the array. The last element of the array
    is always the NULL pointer.

    An exec function calls a child process in the same way that
    the run-time system calls any other VSI C program. The exec
    functions pass the name of the image to be activated in the
    child; this value is placed in argv[0]. However, the functions
    differ in the way they pass arguments and environment information
    to the child:

    o  Arguments can be passed in separate character strings (execl,
       execle, and execlp) or in an array of character strings
       (execv, execve, and execvp).

    o  The environment can be explicitly passed in an array (execle
       and execve) or taken from the parent's environment (execl,
       execv, execlp, and execvp).

    If vfork was called before invoking an exec function, then when
    the exec function completes, control is returned to the parent
    process at the point of the vfork call. If vfork was not called,
    the exec function waits until the child has completed execution
    and then exits the parent process. See vfork.

129.3  –  Return Value

    -1                 Indicates failure.

130  –  execle

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execle  (char *file_spec, char *arg0, . . . , (char *)0,
                  char *envp[]); (ISO POSIX-1)

      int execle  (char *file_spec, . . . ); (Compatibility)

130.1  –  Arguments

 file_spec

    The full file specification of a new image to be activated in the
    child process.

 arg0, ...

    A sequence of pointers to null-terminated character strings.

    If the POSIX-1 format is used, at least one argument must be
    present and must point to a string that is the same as the new
    process filename (or its last component). (This pointer can also
    be the NULL pointer, but then execle would accomplish nothing.)
    The last pointer must be the NULL pointer. This is also the
    convention if the compatibility format is used.

 envp

    An array of strings that specifies the program's environment.
    Each string in envp has the following form:

    name = value

    The name can be one of the following names and the value is a
    null-terminated string to be associated with the name:

    o  HOME-Your login directory

    o  TERM-The type of terminal being used

    o  PATH-The default device and directory

    o  USER-The name of the user who initiated the process

    The last element in envp must be the NULL pointer.

    When the operating system executes the program, it places a copy
    of the current environment vector (envp) in the external variable
    environ.

130.2  –  Description

    See execl for a description of how the exec functions operate.

130.3  –  Return Value

    -1                 Indicates failure.

131  –  execlp

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execlp  (const char *file_name, const char *arg0, . . . ,
                  (char *)0); (ISO POSIX-1)

      int execlp  (char *file_name, . . . ); (Compatibility)

131.1  –  Arguments

 file_name

    The filename of a new image to be activated in the child process.
    The device and directory specification for the file is obtained
    by searching the VAXC$PATH environment name.

 argn

    A sequence of pointers to null-terminated character strings. By
    convention, at least one argument must be present and must point
    to a string that is the same as the new process filename (or its
    last component).

  . . .

    A sequence of pointers to strings. At least one pointer must
    exist to terminate the list. This pointer must be the NULL
    pointer.

131.2  –  Description

    See execl for a description of how the exec functions operate.

131.3  –  Return Value

    -1                 Indicates failure.

132  –  execv

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execv  (char *file_spec, char *argv[]);

132.1  –  Arguments

 file_spec

    The full file specification of a new image to be activated in the
    child process.

 argv

    An array of pointers to null-terminated character strings.
    These strings constitute the argument list available to the new
    process. By convention, argv[0] must point to a string that is
    the same as the new process filename (or its last component).
    argv is terminated by a NULL pointer.

132.2  –  Description

    See execl for a description of how the exec functions operate.

132.3  –  Return Value

    -1                 Indicates failure.

133  –  execve

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execve  (const char *file_spec, char *argv[], char *envp[]);

133.1  –  Arguments

 file_spec

    The full file specification of a new image to be activated in the
    child process.

 argv

    An array of pointers to null-terminated character strings.
    These strings constitute the argument list available to the new
    process. By convention, argv[0] must point to a string that is
    the same as the new process filename (or its last component).
    argv is terminated by a NULL pointer.

 envp

    An array of strings that specifies the program's environment.
    Each string in envp has the following form:

    name = value

    The name can be one of the following names and the value is a
    null-terminated string to be associated with the name:

    o  HOME-Your login directory

    o  TERM-The type of terminal being used

    o  PATH-The default device and directory

    o  USER-The name of the user who initiated the process

    The last element in envp must be the NULL pointer.

    When the operating system executes the program, it places a copy
    of the current environment vector (envp) in the external variable
    environ.

133.2  –  Description

    See execl for a description of how the exec functions operate.

133.3  –  Return Value

    -1                 Indicates failure.

134  –  execvp

    Passes the name of an image to be activated in a child process.
    This function is nonreentrant.

    Format

      #include  <unistd.h>

      int execvp  (const char *file_name, char *argv[]);

134.1  –  Arguments

 file_name

    The filename of a new image to be activated in the child process.
    The device and directory specification for the file is obtained
    by searching the environment name VAXC$PATH.

 argv

    An array of pointers to null-terminated character strings.
    These strings constitute the argument list available to the new
    process. By convention, argv[0] must point to a string that is
    the same as the new process filename (or its last component).
    argv is terminated by a NULL pointer.

134.2  –  Description

    See execl for a description of how the exec functions operate.

134.3  –  Return Value

    -1                 Indicates failure.

135  –  exit,_exit

    Terminate execution of the program from which they are called.
    These functions are nonreentrant.

    Format

      #include  <stdlib.h>

      void exit  (int status);

      #include  <unistd.h>

      void _exit  (int status);

135.1  –  Argument

 status

    For non-POSIX behavior, a status value of EXIT_SUCCESS (1), EXIT_
    FAILURE (2), or a number from 3 to 255, as follows:

    o  A status value of 0, 1 or EXIT_SUCCESS is translated to the
       OpenVMS SS$_NORMAL status code to return the OpenVMS success
       value.

    o  A status value of 2 or EXIT_FAILURE is translated to an error-
       level exit status. The status value is passed to the parent
       process.

    o  Any other status value is left the same.

    For POSIX behavior:

    o  A status value of 0 is translated to the OpenVMS SS$_NORMAL
       status code to return the OpenVMS success value.

    o  Any other status is returned to the parent process as an
       OpenVMS message symbol with facility set to C, severity
       set to success, and with the status in the message number
       field. For more information on the format of message symbols,
       see "message code" in the VSI OpenVMS Command Definition,
       Librarian, and Message Utilities Manual.

    To get POSIX behavior, include <unistd.h> and compile with the
    _POSIX_EXIT feature-test macro set (either with /DEFINE=_POSIX_
    EXIT, or with #define _POSIX_EXIT at the top of your file, before
    any file inclusions). This behavior is available only on OpenVMS
    Version 7.0 and higher systems.

135.2  –  Description

    If the process was invoked by DCL, the status is interpreted by
    DCL, and a message is displayed.

    If the process was a child process created using vfork or an exec
    function, then the child process exits and control returns to the
    parent. The two functions are identical; the _exit function is
    retained for reasons of compatibility with VAX C.

    The exit and _exit functions make use of the $EXIT system
    service. If your process is being invoked by the RUN command
    using any of the hibernation and scheduled wakeup qualifiers, the
    process might not correctly return to hibernation state when an
    exit or _exit call is made.

    The C compiler command-line qualifier /[NO]MAIN=POSIX_EXIT can be
    used to direct the compiler to call __posix_exit instead of exit
    when returning from main. The default is /NOMAIN.

    Beginning with OpenVMS Version 8.3, C RTL contains a fix for
    the problem in which a call to _exit after a failed execl really
    exits but must not.

    In the OpenVMS implementation of vfork, a child process is not
    actually started as it is started on most UNIX systems. However,
    the C RTL creates some internal data structures intended to mimic
    child-process functionality (called the "child context").

    A bug occurred whereby after a vfork while in the child context,
    a call to an exec function justifiably fails, then calls _exit.
    On UNIX systems, after the failed exec call, the child process
    continues to execute. A subsequent call to _exit terminates
    the child. In the OpenVMS implementation, after the failed exec
    call, the child context terminates. A subsequent call to _exit
    terminates the parent. The C RTL fix is enabled by a feature
    logical switch, DECC$EXIT_AFTER_ FAILED_EXEC. Enabling this
    feature logical allows the child context to continue execution.

    With DECC$EXIT_AFTER_FAILED_EXEC disabled or not defined, the
    current behavior remains the default.

                                   NOTE

       EXIT_SUCCESS and EXIT_FAILURE are portable across any
       ANSI C compiler to indicate success or failure. On OpenVMS
       systems, they are mapped to OpenVMS condition codes with
       the severity set to success or failure, respectively. Values
       in the range of 3 to 255 can be used by a child process to
       communicate a small amount of data to the parent. The parent
       retrieves this data using the wait, wait3, wait4, or waitpid
       functions.

136  –  exp

    Returns the base e raised to the power of the argument.

    Format

      #include  <math.h>

      double exp  (double x);

      float expf  (float x); (Integrity servers, Alpha)

      long double expl  (long double x); (Integrity servers, Alpha)

      double expm1  (double x); (Integrity servers, Alpha)

      float expm1f  (float x); (Integrity servers, Alpha)

      long double expm1l  (long double x);
                          (Integrity servers, Alpha)

136.1  –  Argument

 x

    A real value.

136.2  –  Description

    The exp functions compute the value of the exponential function,
    defined as e**x, where e is the constant used as a base for
    natural logarithms.

    The expm1 functions compute exp(x) - 1 accurately, even for tiny
    x.

    If an overflow occurs, the exp functions return the largest
    possible floating-point value and set errno to ERANGE. The
    constant HUGE_VAL is defined in the <math.h> header file to be
    the largest possible floating-point value.

136.3  –  Return Values

    x                  The exponential value of the argument.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    0                  Underflow occurred; errno is set to ERANGE.
    NaN                x is NaN; errno is set to EDOM.

137  –  exp2

    Returns the value of 2 raised to the power of the argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double exp2  (double x);

      float exp2f  (float x);

      long double exp2l  (long double x); )

137.1  –  Argument

 x

    A real value.

137.2  –  Description

    The exp2 functions compute the base-2 exponential of x.

    If an overflow occurs, the exp functions return the largest
    possible floating-point value and set errno to ERANGE. The
    constant HUGE_VAL is defined in the <math.h> header file to be
    the largest possible floating-point value.

137.3  –  Return Values

    n                  2**x.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    1                  x is +0 or -0; errno is set to ERANGE.
    0                  x is -Inf or underflow occurred; errno is set
                       to ERANGE.
    x                  x is +Inf; errno is set to ERANGE.
    NaN                x is NaN; errno is set to EDOM.

138  –  fabs

    Returns the absolute value of its argument.

    Format

      #include  <math.h>

      double fabs  (double x);

      float fabsf  (float x); (Integrity servers, Alpha)

      long double fabsl  (long double x); (Integrity servers, Alpha)

138.1  –  Argument

 x

    A real value.

138.2  –  Return Value

    x                  The absolute value of the argument.

139  –  fchmod

    Changes file access permissions.

    Format

      #include  <stat.h>

      int fchmod  (int fildes, mode_t mode);

139.1  –  Arguments

 fildes

    An open file descriptor.

 mode

    The bit pattern that determines the access permissions.

139.2  –  Description

    The fchmod function is equivalent to the chmod function, except
    that the file whose permissions are changed is specified by a
    file descriptor (fildes) rather than a filename.

139.3  –  Return Values

    0                  Indicates that the mode is successfully
                       changed.
    -1                 Indicates that the change attempt has failed.

140  –  fchown

    Changes the owner and group of a file.

    Format

      #include  <unistd.h>

      int fchown  (int fildes, uid_t owner, gid_t group);

140.1  –  Arguments

 fildes

    An open file descriptor.

 owner

    A user ID corresponding to the new owner of the file.

 group

    A group ID corresponding to the group of the file.

140.2  –  Description

    The fchown function has the same effect as chown except that the
    file whose owner and group are to be changed is specified by the
    file descriptor fildes.

140.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure. The function sets errno to
                       one of the following values:

                       The fchown function will fail if:

                       o  EBADF - The fildes argument is not an open
                          file descriptor.

                       o  EPERM - The effective user ID does not
                          match the owner of the file, or the process
                          does not have appropriate privilege.

                       o  EROFS - The file referred to by fildes
                          resides on a read-only file system.

                       The fchown function may fail if:

                       o  EINVAL - The owner or group ID is not a
                          value supported by the implementation.

                       o  EIO - A physical I/O error has occurred.

                       o  EINTR - The fchown function was interrupted
                          by a signal that was intercepted.

141  –  fclose

    Closes a file by flushing any buffers associated with the file
    control block and freeing the file control block and buffers
    previously associated with the file pointer.

    Format

      #include  <stdio.h>

      int fclose  (FILE *file_ptr);

141.1  –  Argument

 file_ptr

    A pointer to the file to be closed.

141.2  –  Description

    When a program terminates normally, the fclose function is
    automatically called for all open files.

    The fclose function tries to write buffered data by using an
    implicit call to fflush.

    If the write fails (because the disk is full or the user's quota
    is exceeded, for example), fclose continues executing. It closes
    the OpenVMS channel, deallocates any buffers, and releases the
    memory associated with the file descriptor (or FILE pointer). Any
    buffered data is lost, and the file descriptor (or FILE pointer)
    no longer refers to the file.

    If your program needs to recover from errors when flushing
    buffered data, it should make an explicit call to fsync (or
    fflush) before calling fclose.

141.3  –  Return Values

    0                  Indicates success.
    EOF                Indicates that the file control block is not
                       associated with an open file.

142  –  fcntl

    Performs controlling operations on an open file.

    Format

      #include  <sys/types.h>

      #include  <unistd.h>

      #include  <fcntl.h>

      int fcntl  (int file_desc, int request [, int arg]);

      int fcntl  (int file_desc, int request [, struct flock *arg]);

142.1  –  Arguments

 file_desc

    An open file descriptor obtained from a successful open, fcntl,
    or pipe function.

 request

    The operation to be performed.

 arg

    A variable that depends on the value of the request argument.

    For a request of F_DUPFD, F_SETFD, or F_SETFL, specify arg as an
    int.

    For a request of F_GETFD and F_GETFL, do not specify arg.

    For a request of F_GETLK, F_SETLK, or F_SETLKW specify arg as a
    pointer to a flock structure.

142.2  –  Description

    The fcntl function performs controlling operations on the open
    file specified by the file_desc argument.

    The values for the request argument are defined in the header
    file <fcntl.h>, and include the following:

    F_DUPFD      Returns a new file descriptor that is the lowest
                 numbered available (that is, not already open)
                 file descriptor greater than or equal to the third
                 argument (arg) taken as an integer of type int.

                 The new file descriptor refers to the same file as
                 the original file descriptor (file_desc). The FD_
                 CLOEXEC flag associated with the new file descriptor
                 is cleared to keep the file open across calls to one
                 of the exec functions.

                 The following two calls are equivalent:

                 fid = dup(file_desc);

                 fid = fcntl(file_desc, F_DUPFD, 0);

                 Consider the following call:

                 fid = dup2(file_desc, arg);

                 It is similar (but not equivalent) to:

                 close(arg);
                 fid = fcntl(file_desc, F_DUPFD, arg);
    F_GETFD      Gets the value of the close-on-exec flag associated
                 with the file descriptor file_desc. File descriptor
                 flags are associated with a single file descriptor
                 and do not affect other file descriptors that refer
                 to the same file. The arg argument should not be
                 specified.
    F_SETFD      Sets the close-on-exec flag associated with file_
                 desc to the value of the third argument, taken as
                 type int.

                 If the third argument is 0, the file remains open
                 across the exec functions, which means that a child
                 process spawned by the exec function inherits this
                 file descriptor from the parent.

                 If the third argument is FD_CLOEXEC, the file is
                 closed on successful execution of the next exec
                 function, which means that the child process spawned
                 by the exec function will not inherit this file
                 descriptor from the parent.
    F_GETFL      Gets the file status flags and file access modes,
                 defined in <fcntl.h>, for the file description
                 associated with file_desc. The file access modes
                 can be extracted from the return value using the
                 mask O_ACCMODE, which is defined in <fcntl.h>. File
                 status flags and file access modes are associated
                 with the file description and do not affect other
                 file descriptors that refer to the same file with
                 different open file descriptions.
    F_SETFL      Sets the file status flags, defined in <fcntl.h>,
                 for the file description associated with file_desc
                 from the corresponding bits in the third argument,
                 arg, taken as type int. Bits corresponding to the
                 file access mode and the file creation flags,
                 as defined in <fcntl.h>, that are set in arg
                 are ignored. If any bits in arg other than those
                 mentioned here are changed by the application, the
                 result is unspecified.

                 Note: The only status bit recognized is O_APPEND.
                 Support for O_APPEND is not standard-compliant.
                 The X/Open standard states that "File status flags
                 and file access modes are associated with the file
                 description and do not affect other file descriptors
                 that refer to the same file with different open
                 file descriptions." However, because the append bit
                 is stored in the FCB, all file descriptors using
                 the same FCB are using the same append flag, so
                 that setting this flag with fcntl(F_SETFL) will
                 affect all files sharing the FCB; that is, all files
                 duplicated from the same file descriptor.

    Record Locking Requests

    F_GETLK      Gets the first lock that blocks the lock description
                 pointed to by the arg parameter, taken as a pointer
                 to type struct flock. The information retrieved
                 overwrites the information passed to the fcntl
                 function in the flock structure. If no lock is found
                 that would prevent this lock from being created,
                 then the structure is left unchanged except for the
                 lock type, which is set to F_UNLCK.
    F_SETLK      Sets or clears a file segment lock according to
                 the lock description pointed to by arg, taken as
                 a pointer to type struct flock. F_SETLK is used to
                 establish shared locks (F_RDLCK), or exclusive locks
                 (F_WRLCK), as well as remove either type of lock (F_
                 UNLCK). If a shared (read) or exclusive (write)
                 lock cannot be set, the fcntl function returns
                 immediately with a value of -1.

                 An unlock (F_UNLCK) request in which the l_len of
                 the flock structure is nonzero and the offset of the
                 last byte of the requested segment is the maximum
                 value for an object of type off_t, when the process
                 has an existing lock in which l_len is 0 and which
                 includes the last byte of the requested segment,
                 is treated as a request to unlock from the start
                 of the requested segment with an l_len equal to 0.
                 Otherwise, an unlock (F_UNLCK) request attempts to
                 unlock only the requested file.
    F_SETLKW     Same as F_SETLK except that if a shared or exclusive
                 lock is blocked by other locks, the process will
                 wait until it is unblocked. If a signal is received
                 while fcntl is waiting for a region, the function
                 is interrupted, -1 is returned, and errno is set to
                 EINTR.

    File Locking

    The C RTL supports byte-range file locking using the F_GETLK,
    F_SETLK, and F_SETLKW commands of the fcntl function, as defined
    in the X/Open specification. Byte-range file locking is supported
    across OpenVMS clusters. You can only use offsets that fit into
    32-bit unsigned integers.

    When a shared lock is set on a segment of a file, other processes
    on the cluster are able to set shared locks on that segment or
    a portion of it. A shared lock prevents any other process from
    setting an exclusive lock on any portion of the protected area.
    A request for a shared lock fails if the file descriptor was not
    opened with read access.

    An exclusive lock prevents any other process on the cluster from
    setting a shared lock or an exclusive lock on any portion of the
    protected area. A request for an exclusive lock fails if the file
    descriptor was not opened with write access.

    The flock structure describes the type (l_type), starting offset
    (l_whence), relative offset (l_start), size (l_len) and process
    ID (l_pid) of the segment of the file to be affected.

    The value of l_whence is set to SEEK_SET, SEEK_CUR or SEEK_END,
    to indicate that the relative offset l_start bytes is measured
    from the start of the file, from the current position, or from
    the end of the file, respectively. The value of l_len is the
    number of consecutive bytes to be locked. The l_len value may be
    negative (where the definition of off_t permits negative values
    of l_len). The l_pid field is only used with F_GETLK to return
    the process ID of the process holding a blocking lock. After a
    successful F_GETLK request, the value of l_whence becomes SEEK_
    SET.

    If l_len is positive, the area affected starts at l_start and
    ends at l_start + l_len - 1. If l_len is negative, the area
    affected starts at l_start + l_len and ends at l_start - 1. Locks
    may start and extend beyond the current end of a file, but may
    not be negative relative to the beginning of the file. If l_len
    is set to 0 (zero), a lock may be set to always extend to the
    largest possible value of the file offset for that file. If such
    a lock also has l_start set to 0 (zero) and l_whence is set to
    SEEK_SET, the whole file is locked.

    Changing or unlocking a portion from the middle of a larger
    locked segment leaves a smaller segment at either end. Locking
    a segment that is already locked by the calling process causes
    the old lock type to be removed and the new lock type to take
    effect.

    All locks associated with a file for a given process are removed
    when a file descriptor for that file is closed by that process
    or the process holding that file descriptor terminates. Locks are
    not inherited by a child process.

    If the request argument is F_SETLKW, the lock is blocked by
    some lock from another process, and putting the calling process
    to sleep to wait for that lock to become free would cause a
    deadlock, then the application will hang.

142.3  –  Return Values

    n                  Upon successful completion, the value returned
                       depends on the value of the request argument
                       as follows:

                       o  F_DUPFD - Returns a new file descriptor.

                       o  F_GETFD - Returns FD_CLOEXEC or 0.

                       o  F_SETFD, F_GETLK, F_SETLK, F_UNLCK - Return
                          a value other than -1.

    -1                 Indicates that an error occurred. The function
                       sets errno to one of the following values:

                       o  EACCES - The request argument is F_SETLK;
                          the type of lock (l_type) is a shared (F_
                          RDLCK) or exclusive (F_WRLCK) lock, and the
                          segment of a file to be locked is already
                          exclusive-locked by another process; or
                          the type is an exclusive (F_WRLCK) lock and
                          the some portion of the segment of a file
                          to be locked is already shared-locked or
                          exclusive-locked by another process.

                       o  EBADF - The file_desc argument is not a
                          valid open file descriptor and the arg
                          argument is negative or greater than or
                          equal to the per-process limit.

                          The request parameter is F_SETLK or F_
                          SETLKW, the type of lock (l_type) is a
                          shared lock (F_RDLCK), and file_desc is not
                          a valid file descriptor open for reading.

                          The type of lock (l_type) is an exclusive
                          lock (F_WRLCK), and file_desc is not a
                          valid file descriptor open for writing.

                       o  EFAULT - The arg argument is an invalid
                          address.

                       o  EINVAL - The request argument is F_DUPFD
                          and arg is negative or greater than or
                          equal to OPEN_MAX.

                          Either the OPEN_MAX value or the per-
                          process soft descriptor limit is checked.

                          An illegal value was provided for the
                          request argument.

                          The request argument is F_GETLK, F_SETLK,
                          or F_SETLKW and the data pointed to by arg
                          is invalid, or file_desc refers to a file
                          that does not support locking.

                       o  EMFILE - The request argument is F_DUPFD
                          and too many or OPEN_MAX file descriptors
                          are currently open in the calling process,
                          or no file descriptors greater than or
                          equal to arg are available.

                          Either the OPEN_MAX value or the per-
                          process soft descriptor limit is checked.

                       o  EOVERFLOW - One of the values to be
                          returned cannot be represented correctly.

                          The request argument is F_GETLK, F_SETLK,
                          or F_SETLKW and the smallest or, if l_
                          len is nonzero, the largest offset of any
                          byte in the requested segment cannot be
                          represented correctly in an object of type
                          off_t.

                       o  EINTR - The request argument is F_SETLKW,
                          and the function was interrupted by a
                          signal.

                       o  ENOLCK - The request argument is F_SETLK or
                          F_SETLKW, and satisfying the lock or unlock
                          request would exceed the configurable
                          system limit of NLOCK_RECORD.

                       o  ENOMEM - The system was unable to allocate
                          memory for the requested file descriptor.

143  –  fcvt

    Converts its argument to a null-terminated string of ASCII digits
    and returns the address of the string. The string is stored in a
    thread-specific location created by the C RTL.

    Format

      #include  <stdlib.h>

      char *fcvt  (double value, int ndigits, int *decpt, int *sign);

143.1  –  Arguments

 value

    An object of type double that is converted to a null-terminated
    string of ASCII digits.

 ndigits

    The number of ASCII digits after the decimal point to be used in
    the converted string.

 decpt

    The position of the decimal point relative to the first character
    in the returned string. The returned string does not contain the
    actual decimal point. A negative int value means that the decimal
    point is decpt number of spaces to the left of the returned
    digits (the spaces are filled with zeros). A 0 value means that
    the decimal point is immediately to the left of the first digit
    in the returned string.

 sign

    An integer value that indicates whether the value argument is
    positive or negative. If value is negative, the fcvt function
    places a nonzero value at the address specified by sign.
    Otherwise, the functions assign 0 to the address specified by
    sign.

143.2  –  Description

    The fcvt function converts value to a null-terminated string and
    returns a pointer to it. The resulting low-order digit is rounded
    to the correct digit for outputting ndigits digits in C F-format.
    The decpt argument is assigned the position of the decimal point
    relative to the first character in the string.

    In C F-format, ndigits is the number of digits desired after the
    decimal point. Very large numbers produce a very long string of
    digits before the decimal point, and ndigit of digits after the
    decimal point. For large numbers, it is preferable to use the
    gcvt or ecvt function so that E-format is used.

    Repeated calls to the fcvt function overwrite any existing
    string.

    The ecvt, fcvt, and gcvt functions represent the following
    special values specified in the IEEE Standard for floating-point
    arithmetic:

    Value         Representation

    Quiet NaN     NaNQ
    Signalling    NaNS
    NaN
    +Infinity     Infinity
    -Infinity     -Infinity

    The sign associated with each of these values is stored into the
    sign argument. In IEEE floating-point representation, a value
    of 0 (zero) can be positive or negative, as set by the sign
    argument.

    See also gcvt and ecvt.

143.3  –  Return Value

    x                  A pointer to the converted string.

144  –  fdim

    Determines the positive difference between its arguments.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double fdim  (double x, double y);

      float fdimf  (float x, float y);

      long double fdiml  (long double x, long double y);

144.1  –  Argument

 x

    A real value.

 y

    A real value.

144.2  –  Description

    The fdim functions determine the positive difference between
    their arguments. If x is greater than y, x - y is returned. If x
    is less than or equal to y, +0 is returned.

144.3  –  Return Values

    n                  Upon success, the positive difference value.
    HUGE_VAL           If x - y is positive and overflows; errno is
                       set to ERANGE.
    0                  If x - y is positive and underflows; errno is
                       set to ERANGE.
    NaN                x or y is NaN; errno is set to EDOM.

145  –  fdopen

    Associates a file pointer with a file descriptor returned by an
    open, creat, dup, dup2, or pipe function.

    Format

      #include  <stdio.h>

      FILE *fdopen  (int file_desc, char *a_mode);

145.1  –  Arguments

 file_desc

    The file descriptor returned by open, creat, dup, dup2, or pipe.

 a_mode

    The access mode indicator. See the fopen function for a
    description. Note that the access mode specified must agree
    with the mode used to originally open the file. This includes
    binary/text access mode ("b" mode on fdopen and the "ctx=bin"
    option on creat or open).

145.2  –  Description

    The fdopen function allows you to access a file, originally
    opened by one of the UNIX I/O functions, with Standard I/O
    functions. Ordinarily, a file can be accessed by either a file
    descriptor or by a file pointer, but not both, depending on the
    way you open it.

145.3  –  Return Values

    pointer            Indicates that the operation has succeeded.
    NULL               Indicates that an error has occurred.

146  –  feof

    Tests a file to see if the end-of-file has been reached.

    Format

      #include  <stdio.h>

      int feof  (FILE *file_ptr);

146.1  –  Argument

 file_ptr

    A file pointer.

146.2  –  Return Values

    nonzero integer    Indicates that the end-of-file has been
                       reached.
    0                  Indicates that the end-of-file has not been
                       reached.

147  –  feof_unlocked

    Same as feof, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int feof_unlocked  (FILE *file_ptr);

147.1  –  Argument

 file_ptr

    A file pointer.

147.2  –  Description

    The reentrant version of the feof function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, feof_unlocked can be used to avoid the overhead. The feof_
    unlocked function is functionally identical to the feof function,
    except that it is not required to be implemented in a thread-
    safe manner. The feof_unlocked function can be safely used only
    within a scope that is protected by the flockfile and funlockfile
    functions used as a pair. The caller must ensure that the stream
    is locked before feof_unlocked is used.

    See also flockfile, ftrylockfile, and funlockfile.

147.3  –  Return Values

    nonzero integer    Indicates end-of-file has been reached.
    0                  Indicates end-of-file has not been reached.

148  –  ferror

    Returns a nonzero integer if an error occurred while reading or
    writing a file.

    Format

      #include  <stdio.h>

      int ferror  (FILE *file_ptr);

148.1  –  Argument

 file_ptr

    A file pointer.

148.2  –  Description

    A call to ferror continues to return a nonzero integer until the
    file is closed or until clearerr is called.

148.3  –  Return Values

    0                  Indicates success.
    nonzero integer    Indicates that an error has occurred.

149  –  ferror_unlocked

    Same as ferror, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int ferror_unlocked  (FILE *file_ptr);

149.1  –  Argument

 file_ptr

    A file pointer.

149.2  –  Description

    The reentrant version of the ferror function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, ferror_unlocked can be used to avoid the overhead. The
    ferror_unlocked function is functionally identical to the ferror
    function, except that it is not required to be implemented in a
    thread-safe manner. The ferror_unlocked function can be safely
    used only within a scope that is protected by the flockfile and
    funlockfile functions used as a pair. The caller must ensure that
    the stream is locked before ferror_unlocked is used.

    See also flockfile, ftrylockfile, and funlockfile.

149.3  –  Return Values

    0                  Indicates success.
    nonzero integer    Indicates that an error has occurred.

150  –  fflush

    Writes out any buffered information for the specified file.

    Format

      #include  <stdio.h>

      int fflush  (FILE *file_ptr);

150.1  –  Argument

 file_ptr

    A file pointer. If this argument is a NULL pointer, all buffers
    associated with all currently open files are flushed.

150.2  –  Description

    The output files are normally buffered only if they are not
    directed to a terminal, except for stderr, which is not buffered
    by default.

    The fflush function flushes the C RTL buffers. However,
    RMS has its own buffers. The fflush function does not guarantee
    that the file will be written to disk. (See the description of
    fsync for a way to flush buffers to disk.)

    If the file pointed to by file_ptr was opened in record mode
    and if there is unwritten data in the buffer, then fflush always
    generates a record.

150.3  –  Return Values

    0                  Indicates that the operation is successful.
    EOF                Indicates that the buffered data cannot be
                       written to the file, or that the file control
                       block is not associated with an output file.

151  –  ffs

    Finds the index of the first bit set in a string.

    Format

      #include  <strings.h>

      int ffs  (int iteger);

151.1  –  Argument

 integer

    The integer to be examined for the first bit set.

151.2  –  Description

    The ffs function finds the first bit set (beginning with the
    least significant bit) and returns the index of that bit. Bits
    are numbered starting at 1 (the least significant bit).

151.3  –  Return Values

    x                  The index of the first bit set.
    0                  If index is 0.

152  –  fgetc

    Returns the next character from a specified file.

    Format

      #include  <stdio.h>

      int fgetc  (FILE *file_ptr);

152.1  –  Argument

 file_ptr

    A pointer to the file to be accessed.

152.2  –  Description

    The fgetc function returns the next character from the specified
    file.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also the fgetc_unlocked function and the getc macro.

152.3  –  Return Values

    x                  The returned character.
    EOF                Indicates the end-of-file or an error.

153  –  fgetc_unlocked

    Same as the fgetc function, except used only within a scope
    protected by flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int fgetc_unlocked  (FILE *file_ptr);

153.1  –  Argument

 file_ptr

    A file pointer.

153.2  –  Description

    The reentrant version of the fgetc function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, fgetc_unlocked can be used to avoid the overhead. The
    fgetc_unlocked function is functionally identical to the fgetc
    function, except that fgetc_unlocked can be safely used only
    within a scope that is protected by the flockfile and funlockfile
    functions used as a pair. The caller must ensure that the stream
    is locked before fgetc_unlocked is used.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also getc_unlocked, flockfile, ftrylockfile, and funlockfile.

153.3  –  Return Values

    n                  The returned character.
    EOF                Indicates the end-of-file or an error.

154  –  fgetname

    Returns the file specification associated with a file pointer.

    Format

      #include  <stdio.h>

      char *fgetname  (FILE *file_ptr, char *buffer, . . . );

154.1  –  Function Variants

    The fgetname function has variants named _fgetname32 and _
    fgetname64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

154.2  –  Arguments

 file_ptr

    A file pointer.

 buffer

    A pointer to a character string that is large enough to hold the
    file specification.

  . . .

    An optional additional argument that can be either 1 or 0. If you
    specify 1, the fgetname function returns the file specification
    in OpenVMS format. If you specify 0, fgetname returns the file
    specification in UNIX style format. If you do not specify this
    argument, fgetname returns the filename according to your current
    command language interpreter.

154.3  –  Description

    The fgetname function places the file specification at the
    address given in the buffer. The buffer should be an array large
    enough to contain a fully qualified file specification (the
    maximum length is 256 characters).

154.4  –  Return Values

    n                  The address of the buffer.
    0                  Indicates an error.

154.5  –  Restriction

    The fgetname function is specific to the C RTL and is not
    portable.

155  –  fgetpos

    Stores the current file position for a given file.

    Format

      #include  <stdio.h>

      int fgetpos  (FILE *stream, fpos_t *pos);

155.1  –  Arguments

 stream

    A file pointer.

 pos

    A pointer to an implementation-defined structure. The fgetpos
    function fills this structure with information that can be used
    on subsequent calls to fsetpos.

155.2  –  Description

    The fgetpos function stores the current value of the file
    position indicator for the stream pointed to by stream into the
    object pointed to by pos.

155.3  –  Return Values

    0                  Indicates successful completion.
    -1                 Indicates that there are errors.

155.4  –  Example

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

        main()
        {
            FILE *fp;
            int stat,
                i;
            int character;
            char ch,
                 c_ptr[130],
                 d_ptr[130];
            fpos_t posit;

            /* Open a file for writing.  */

            if ((fp = fopen("file.dat", "w+")) == NULL) {
                perror("open");
                exit(1);
            }

           /* Get the beginning position in the file.  */

            if (fgetpos(fp, &posit) != 0)
                perror("fgetpos");

            /* Write some data to the file. */

            if (fprintf(fp, "this is a test\n") == 0) {
                perror("fprintf");
                exit(1);
            }

            /* Set the file position back to the beginning. */

            if (fsetpos(fp, &posit) != 0)
                perror("fsetpos");

            fgets(c_ptr, 130, fp);
            puts(c_ptr);        /* Should be "this is a test."  */

            /* Close the file. */

            if (fclose(fp) != 0) {
                perror("close");
                exit(1);
            }

        }

156  –  fgets

    Reads a line from the specified file, up to one less than the
    specified maximum number of characters or up to and including the
    new-line character, whichever comes first. The function stores
    the string in str.

    Format

      #include  <stdio.h>

      char *fgets  (char *str, int maxchar, FILE *file_ptr);

156.1  –  Function Variants

    The fgets function has variants named _fgets32 and _fgets64 for
    use with 32-bit and 64-bit pointer sizes, respectively.

156.2  –  Arguments

 str

    A pointer to a character string that is large enough to hold the
    information fetched from the file.

 maxchar

    The maximum number of characters to fetch.

 file_ptr

    A file pointer.

156.3  –  Description

    The fgets function terminates the line with a null character
    (\0). Unlike gets, fgets places the new-line character that
    terminates the input line into the user buffer if more than
    maxchar characters have not already been fetched.

    When the file pointed to by file_ptr is opened in record
    mode, fgets treats the end of a record the same as a new-line
    character, so it reads up to and including a new-line character
    or to the end of the record.

156.4  –  Return Values

    x                  Pointer to str.
    NULL               Indicates the end-of-file or an error. The
                       contents of str are undefined if a read error
                       occurs.

156.5  –  Example

        #include <stdio.h>
        #include <stdlib.h>
        #include <unixio.h>

        main()
        {
            FILE *fp;
            char c_ptr[130];

            /* Create a dummy data file  */

            if ((fp = fopen("file.dat", "w+")) == NULL) {
                perror("open");
                exit(1);
            }

            fprintf(fp, "this is a test\n") ;
            fclose(fp) ;

            /* Open a file with some data -"this is a test"   */

            if ((fp = fopen("file.dat", "r+")) == NULL) {
               perror("open error") ;
                exit(1);
            }

            fgets(c_ptr, 130, fp);
            puts(c_ptr);        /* Display what fgets got.  */
            fclose(fp);

            delete("file.dat") ;
        }

157  –  fgetwc

    Reads the next character from a specified file, and converts it
    to a wide-character code.

    Format

      #include  <wchar.h>

      wint_t fgetwc  (FILE *file_ptr);

157.1  –  Argument

 file_ptr

    A pointer to the file to be accessed.

157.2  –  Description

    Upon successful completion, the fgetwc function returns the wide-
    character code read from the file pointed to by file_ptr and
    converted to type wint_t. If the file is at end-of-file, the
    end-of-file indicator is set, and WEOF is returned. If an I/O
    read error occurred, then the error indicator is set, and WEOF is
    returned.

    Applications can use ferror or feof to distinguish between an
    error condition and an end-of-file condition.

157.3  –  Return Values

    x                  The wide-character code of the character read.
    WEOF               Indicates the end-of-file or an error. If a
                       read error occurs, the function sets errno to
                       one of the following:

                       o  EALREADY - An operation is already in
                          progress on the same file.

                       o  EBADF - The file descriptor is not valid.

                       o  EILSEQ - Invalid character detected.

158  –  fgetws

    Reads a line of wide characters from a specified file.

    Format

      #include  <wchar.h>

      wchar_t *fgetws  (wchar_t *wstr, int maxchar, FILE *file_ptr);

158.1  –  Function Variants

    The fgetws function has variants named _fgetws32 and _fgetws64
    for use with 32-bit and 64-bit pointer sizes, respectively.

158.2  –  Arguments

 wstr

    A pointer to a wide-character string large enough to hold the
    information fetched from the file.

 maxchar

    The maximum number of wide characters to fetch.

 file_ptr

    A file pointer.

158.3  –  Description

    The fgetws function reads wide characters from the specified file
    and stores them in the array pointed to by wstr. The function
    reads up to maxchar-1 characters or until the new-line character
    is read, converted, and transferred to wstr, or until an end-
    of-file condition is encountered. The function terminates the
    line with a null wide character. fgetws places the new-line that
    terminates the input line into the user buffer, unless maxchar
    characters have already been fetched.

158.4  –  Return Values

    x                  Pointer to wstr.
    NULL               Indicates the end-of-file or an error. The
                       contents of wstr are undefined if a read
                       error occurs. If a read error occurs, the
                       function sets errno. For a list of possible
                       errno values, see fgetwc.

158.5  –  Example

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

        main()
        {
            wchar_t wstr[80],
                   *ret;
            FILE *fp;

            /* Create a dummy data file  */

            if ((fp = fopen("file.dat", "w+")) == NULL) {
                perror("open");
                exit(1);
            }

            fprintf(fp, "this is a test\n") ;
            fclose(fp) ;

           /* Open a test file containing : "this is a test" */

            if ((fp = fopen("file.dat", "r")) == (FILE *) NULL) {
                perror("File open error");
                exit(EXIT_FAILURE);
            }

            ret = fgetws(wstr, 80, fp);
            if (ret == (wchar_t *) NULL) {
                perror("fgetws failure");
                exit(EXIT_FAILURE);
            }

            fputws(wstr, stdout);
            fclose(fp);
            delete("file.dat");
        }

159  –  fileno

    Returns the file descriptor associated with the specified file
    pointer.

    Format

      #include  <stdio.h>

      int fileno  (FILE *file_ptr);

159.1  –  Argument

 file_ptr

    A file pointer.

159.2  –  Description

    If you are using version 5.2 or lower of the C compiler, undefine
    the fileno macro:

    #if defined(fileno)
    #undef fileno
    #endif

159.3  –  Return Values

    x                  Integer file descriptor.
    -1                 Indicates an error.

160  –  finite

    Returns the integer value 1 (True) when its argument is a finite
    number, or 0 (False) if not.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      int finite  (double x);

      int finitef  (float x);

      int double finitel  (long double x);

160.1  –  Argument

 x

    A real value.

160.2  –  Description

    The finite functions return 1 when -Infinity < x < +Infinity.
    They return 0 when |x| = Infinity, or x is a NaN.

161  –  flockfile

    Locks a stdio stream.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      void flockfile  (FILE *file_ptr);

161.1  –  Argument

 file_ptr

    A file pointer.

161.2  –  Description

    The flockfile function locks a stdio stream so that a thread can
    have exclusive use of that stream for multiple I/O operations.
    Use the flockfile function for a thread that wants to ensure
    that the output of several printf functions, for example, is not
    garbled by another thread also trying to use printf.

    File pointers passed are assumed to be valid; flockfile will
    perform locking even on invalid file pointers. Also, the
    funlockfile function will not fail if the calling thread does
    not own a lock on the file pointer passed.

    Matching flockfile and funlockfile calls can be nested. If the
    stream has been locked recursively, it will remain locked until
    the last matching funlockfile is called.

    All C RTL file-pointer I/O functions lock their file pointers as
    if calling flockfile and funlockfile.

    See also ftrylockfile and funlockfile.

162  –  floor

    Returns the largest integer less than or equal to the argument.

    Format

      #include  <math.h>

      double floor  (double x);

      float floorf  (float x); (Integrity servers, Alpha)

      long double floorl  (long double x);

                          (Integrity servers, Alpha)

162.1  –  Argument

 x

    A real value.

162.2  –  Return Value

    n                  The largest integer less than or equal to the
                       argument.

163  –  fma

    Computes (x * y) + z, rounded as one ternary operation.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double fma  (double x, double y, double z);

      float fmaf  (float x, float y, float z);

      long double fmal  (long double x, long double y, long double z);

163.1  –  Argument

 x,y,z

    Real values.

163.2  –  Description

    The fma functions compute (x * y) + z, rounded as one ternary
    operation: the value is computed as if to infinite precision and
    rounded once to the result format, according to the rounding mode
    characterized by the value of FLT_ROUNDS.

163.3  –  Return Values

    n                  Upon success, (x * y) + z, rounded as one
                       ternary operation.
    NaN                x or y is NaN; errno is set to EDOM.

164  –  fmax

    Returns the maximum numeric value of its arguments.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double fmax  (double x, double y);

      float fmaxf  (float x, float y);

      long double fmaxl  (long double x, long double y);

164.1  –  Argument

 x

    A real value.

 y

    A real value.

164.2  –  Description

    The fmax functions determine the maximum numeric value of their
    arguments. NaN arguments are treated as missing data: if one
    argument is a NaN and the other numeric, then the numeric value
    is returned.

164.3  –  Return Values

    n                  Upon success, the maximum numeric value of the
                       arguments. If just one argument is a NaN, the
                       other argument is returned.
    NaN                Both x and y are NaNs.

165  –  fmin

    Returns the minimum numeric value of its arguments.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double fmin  (double x, double y);

      float fminf  (float x, float y);

      long double fminl  (long double x, long double y);

165.1  –  Argument

 x

    A real value.

 y

    A real value.

165.2  –  Description

    The fmin functions determine the minimum numeric value of their
    arguments. NaN arguments are treated as missing data: if one
    argument is a NaN and the other numeric, then the numeric value
    is returned.

165.3  –  Return Values

    n                  Upon success, the minimum numeric value of the
                       arguments. If just one argument is a NaN, the
                       other argument is returned.
    NaN                Both x and y are NaNs.

166  –  fmod

    Computes the floating-point remainder.

    Format

      #include  <math.h>

      double fmod  (double x, double y);

      float fmodf  (float x, float y); (Integrity servers, Alpha)

      long double fmodl  (long double x, long double y);
                         (Integrity servers, Alpha)

166.1  –  Arguments

 x

    A real value.

 y

    A real value.

166.2  –  Description

    The fmod functions return the floating-point remainder of the
    first argument divided by the second. If the second argument is
    0, the function returns 0.

166.3  –  Return Values

    x                  The value f, which has the same sign as the
                       argument x, such that x == i * y + f for some
                       integer i, where the magnitude of f is less
                       than the magnitude of y.
    0                  Indicates that y is 0.

167  –  fopen

    Opens a file by returning the address of a FILE structure.

    Format

      #include  <stdio.h>

      FILE *fopen  (const char *file_spec, const char *a_mode);
                   (ANSI C)

      FILE *fopen  (const char *file_spec, const char
                   *a_mode, . . . ); (DEC C Extension)

167.1  –  Arguments

 file_spec

    A character string containing a valid file specification.

 a_mode

    The access mode indicator. Use one of the following character
    strings: "r", "w", "a", "r+", "w+", "rb", "r+b", "rb+", "wb",
    "w+b", "wb+", "ab", "a+b", "ab+", or "a+".

    These access modes have the following effects:

    o  "r" opens an existing file for reading.

    o  "w" creates a new file, if necessary, and opens the file for
       writing. If the file exists, it creates a new file with the
       same name and a higher version number.

    o  "a" opens the file for append access. An existing file is
       positioned at the end-of-file, and data is written there. If
       the file does not exist, the C RTL creates it.

    The update access modes allow a file to be opened for both
    reading and writing. When used with existing files, "r+" and
    "a+" differ only in the initial positioning within the file. The
    modes are:

    o  "r+" opens an existing file for read update access. It is
       opened for reading, positioned first at the beginning-of-file,
       but writing is also allowed.

    o  "w+" opens a new file for write update access.

    o  "a+" opens a file for append update access. The file is first
       positioned at the end-of-file (writing). If the file does not
       exist, the C RTL creates it.

    o  "b" means binary access mode. In this case, no conversion of
       carriage-control information is attempted.

  . . .

    Optional file attribute arguments. The file attribute arguments
    are the same as those used in the creat function. For more
    information, see the creat function.

167.2  –  Description

    If a version of the file exists, a new file created with fopen
    inherits certain attributes from the existing file unless
    those attributes are specified in the fopen call. The following
    attributes are inherited:

       Record format
       Maximum record size
       Carriage control
       File protection

    If you specify a directory in the filename and it is a search
    list that contains an error, VSI C for OpenVMS Systems
    interprets it as a file open error.

    The file control block can be freed with the fclose function, or
    by default on normal program termination.

167.3  –  Return Values

    x                  File pointer.
    NULL               Indicates an error. The constant NULL is
                       defined in the <stdio.h> header file to be
                       the NULL pointer value. The function returns
                       NULL to signal the following errors:

                       o  File protection violations

                       o  Attempts to open a nonexistent file for
                          read access

                       o  Failure to open the specified file

168  –  fp_class

    Determines the class of IEEE floating-point values.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      int fp_class  (double x);

      int fp_classf  (float x);

      int fp_classl  (long double x);

168.1  –  Argument

 x

    An IEEE floating-point number.

168.2  –  Description

    The fp_class functions determine the class of the specified IEEE
    floating-point number, returning a constant from the <fp_class.h>
    header file. They never cause an exception, even for signaling
    NaNs (Not-a-Number). These functions implement the recommended
    class(x) function in the appendix of the IEEE 754-1985 standard
    for binary floating-point arithmetic. The constants in <fp_
    class.h> refer to the following classes of values:

    FP_SNAN           Signaling NaN (Not-a-Number)
    FP_QNAN           Quiet NaN
    FP_POS_INF        +Infinity
    FP_NEG_INF        -Infinity
    FP_POS_NORM       positive normalized
    FP_NEG_NORM       negative normalized
    FP_POS_DENORM     positive denormalized
    FP_NEG_DENORM     negative denormalized
    FP_POS_ZERO       +0.0 (positive zero)
    FP_NEG_ZERO       -0.0 (negative zero)

168.3  –  Return Value

    x                  A constant from the <fp_class.h> header file.

169  –  fpathconf

    Retrieves file implementation characteristics.

    Format

      #include  <unistd.h>

      long int fpathconf  (int filedes, int name);

169.1  –  Arguments

 filedes

    An open file descriptor.

 name

    The configuration attribute to query. If this attribute is
    not applicable to the file specified by the filesdes argument,
    fpathconf returns an error.

169.2  –  Description

    The fpathconf function allows an application to retrieve the
    characteristics of operations supported by the file system
    underlying the filenamed by the filesdes argument. Read, write,
    or execute permission of the named file is not required, but you
    must be able to search all directories in the path leading to the
    file.

    Symbolic values for the name argument are defined in the
    <unistd.h> header file as follows:

    _PC_LINK_MAX   The maximum number of links to the file. If the
                   filedes argument refers to a directory, the value
                   returned applies to the directory itself.
    _PC_MAX_       The maximum number of bytes in a canonical input
    CANON          line. This is applicable only to terminal devices.
    _PC_MAX_       The number of types allowed in an input queue.
    INPUT          This is applicable only to terminal devices.
    _PC_NAME_MAX   Maximum number of bytes in a filename (not
                   including a terminating null). The byte range
                   value is between 13 and 255. This is applicable
                   only to a directory file. The value returned
                   applies to filenames within the directory.
    _PC_PATH_MAX   Maximum number of bytes in a pathname (not
                   including a terminating null). The value is never
                   larger than 65,535. This is applicable only to a
                   directory file. The value returned is the maximum
                   length of a relative pathname when the specified
                   directory is the working directory.
    _PC_PIPE_BUF   Maximum number of bytes guaranteed to be written
                   atomically. This is applicable only to a FIFO. The
                   value returned applies to the referenced object.
                   If the path argument refers to a directory, the
                   value returned applies to any FIFO that exists or
                   can be created within the directory.
    _PC_CHOWN_     The value returned applies to any files (other
    RESTRICTED     than directories) that exist or can be created
                   within the directory. This is applicable only to a
                   directory file.
    _PC_NO_TRUNC   Returns 1 if supplying a component name longer
                   than allowed by NAME_MAX causes an error. Returns
                   0 (zero) if long component names are truncated.
                   This is applicable only to a directory file.
    _PC_VDISABLE   This is always 0 (zero); no disabling character
                   is defined. This is applicable only to a terminal
                   device.

169.3  –  Return Values

    x                  The resultant value for the configuration
                       attribute specified in the name argument.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EINVAL - The name argument specifies an
                          unknown or inapplicable characteristic.

                       o  EBADF - the filedes argument is not a valid
                          file descriptor.

170  –  fprintf

    Performs formatted output to a specified file.

    Format

      #include  <stdio.h>

      int fprintf  (FILE *file_ptr, const char *format_spec, . . . );

170.1  –  Arguments

 file_ptr

    A pointer to the file to which the output is directed.

 format_spec

    A pointer to a character string that contains the format
    specification.

  . . .

    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. Any excess output sources are ignored.

170.2  –  Example

      An example of a conversion specification follows:

        #include <stdio.h>

        main()
        {
           int  temp = 4, temp2 = 17;

           fprintf(stdout, "The answers are %d, and %d.", temp, temp2);
        }

      This example outputs the following to the stdout file:

        The answers are 4, and 17.

170.3  –  Return Values

    x                  The number of bytes written, excluding the
                       null terminator.
    Negative value     Indicates an error. The function sets errno to
                       one of the following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This might indicate that conversion to a
                          numeric value failed because of overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

171  –  fputc

    Writes a character to a specified file.

    Format

      #include  <stdio.h>

      int fputc  (int character, FILE *file_ptr);

171.1  –  Arguments

 character

    An object of type int.

 file_ptr

    A file pointer.

171.2  –  Description

    The fputc function writes a single character to the specified
    file and returns the character.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also the fputc_unlocked function and the putc macro.

171.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    EOF                Indicates an output error.

172  –  fputc_unlocked

    Same as the fputc function, except used only within a scope
    protected by flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int fputc_unlocked  (int character, FILE *file_ptr);

172.1  –  Arguments

 character

    The character to be written. An object of type int.

 file_ptr

    A file pointer.

172.2  –  Description

    See the putc_unlocked macro.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also flockfile, ftrylockfile, and funlockfile.

172.3  –  Return Values

    n                  The returned character.
    EOF                Indicates the end-of-file or an error.

173  –  fputs

    Writes a character string to a file without copying the string's
    null terminator (\0).

    Format

      #include  <stdio.h>

      int fputs  (const char *str, FILE *file_ptr);

173.1  –  Arguments

 str

    A pointer to a character string.

 file_ptr

    A file pointer.

173.2  –  Description

    Unlike puts, the fputs function does not append a new-line
    character to the output string.

    See also puts.

173.3  –  Return Values

    Nonnegative value  Indicates success.
    EOF                Indicates an error.

174  –  fputwc

    Converts a wide character to its corresponding multibyte value,
    and writes the result to a specified file.

    Format

      #include  <wchar.h>

      wint_t fputwc  (wint_t wc, FILE *file_ptr);

174.1  –  Arguments

 wc

    An object of type wint_t.

 file_ptr

    A file pointer.

174.2  –  Description

    The fputwc function writes a wide character to a file and returns
    the character.

    See also putwc.

174.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    WEOF               Indicates an output error. The function sets
                       errno to the following:

                       o  EILSEQ - Invalid wide-character code
                          detected.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

175  –  fputws

    Writes a wide-character string to a file without copying the
    null-terminating character.

    Format

      #include  <wchar.h>

      int fputws  (const wchar_t *wstr, FILE *file_ptr);

175.1  –  Arguments

 wstr

    A pointer to a wide-character string.

 file_ptr

    A file pointer.

175.2  –  Description

    The fputws function converts the specified wide-character string
    to a multibyte character string and writes it to the specified
    file. The function does not append a terminating null byte
    corresponding to the null wide-character to the output string.

175.3  –  Return Values

    Nonnegative value  Indicates success.
    -1                 Indicates an error. The function sets errno.
                       For a list of the values, see fputwc.

176  –  fread

    Reads a specified number of items from the file.

    Format

      #include  <stdio.h>

      size_t fread  (void *ptr, size_t size_of_item, size_t
                    number_items, FILE *file_ptr);

176.1  –  Arguments

 ptr

    A pointer to the location, within memory, where you place the
    information being read. The type of the object pointed to is
    determined by the type of the item being read.

 size_of_item

    The size of the items being read, in bytes.

 number_items

    The number of items to be read.

 file_ptr

    A pointer that indicates the file from which the items are to be
    read.

176.2  –  Description

    The type size_t is defined in the header file <stdio.h> as
    follows:

    typedef unsigned int size_t

    The reading begins at the current location in the file. The items
    read are placed in storage beginning at the location given by
    the first argument. You must also specify the size of an item, in
    bytes.

    If the file pointed to by file_ptr was opened in record mode,
    fread will read size_of_item multiplied by number_items bytes
    from the file. That is, it does not necessarily read number_items
    records.

176.3  –  Return Values

    n                  The number of bytes read divided by size_of_
                       item.
    0                  Indicates the end-of-file or an error.

177  –  free

    Makes available for reallocation the area allocated by a previous
    calloc, malloc, or realloc call.

    Format

      #include  <stdlib.h>

      void free  (void *ptr);

177.1  –  Argument

 ptr

    The address returned by a previous call to malloc, calloc, or
    realloc. If ptr is a NULL pointer, no action occurs.

177.2  –  Description

    The ANSI C standard defines free as not returning a value;
    therefore, the function prototype for free is declared with
    a return type of void. However, since a free can fail, and
    since previous versions of the C RTL have declared free
    to return an int, the implementation of free does return 0 on
    success and -1 on failure.

178  –  freopen

    Substitutes the filenamed by a file specification for the open
    file addressed by a file pointer. The latter file is closed.

    Format

      #include  <stdio.h>

      FILE *freopen  (const char *file_spec, const char *a_mode, FILE
                     *file_ptr, . . . );

178.1  –  Arguments

 file_spec

    A pointer to a string that contains a valid OpenVMS or UNIX
    style file specification. After the function call, the given
    file pointer is associated with this file.

 a_mode

    The access mode indicator. See the fopen function for a
    description.

 file_ptr

    A file pointer.

  . . .

    Optional file attribute arguments. The file attribute arguments
    are the same as those used in the creat function.

178.2  –  Description

    The freopen function is typically used to associate one of the
    predefined names stdin, stdout, or stderr with a file.

178.3  –  Return Values

    file_ptr           The file pointer, if freopen is successful.
    NULL               Indicates an error.

179  –  frexp

    Calculates the fractional and exponent parts of a floating-point
    value.

    Format

      #include  <math.h>

      double frexp  (double value, int *eptr);

      float frexpf  (float value, int *eptr);
                    (Integrity servers, Alpha)

      long double frexpl (long double value, int *eptr);
                          (Integrity servers, Alpha)

179.1  –  Arguments

 value

    A floating-point number of type double, float, or long double.

 eptr

    A pointer to an int where frexp places the exponent.

179.2  –  Description

    The frexp functions break the floating-point number (value) into
    a normalized fraction and an integral power of 2, as follows:

    value = fraction * (2exp)

    The fractional part is returned as the return value. The exponent
    is placed in the integer variable pointed to by eptr.

179.3  –  Example

        #include <math.h>

        main ()
        {
           double val = 16.0, fraction;
           int exp;

           fraction = frexp(val, &exp);
           printf("fraction = %f\n",fraction);
           printf("exp = %d\n",exp);

        }

      In this example, frexp converts the value 16 to .5 * 2 . The

      example produces the following output:

        fraction = 0.500000
        exp = 5

      |value| = Infinity or NaN is an invalid argument.

179.4  –  Return Values

    x                  The fractional part of value.
    0                  Both parts of the result are 0.
    NaN                If value is NaN, NaN is returned, errno
                       is set to EDOM, and the value of *eptr is
                       unspecified.
    value              If |value| = Infinity, value is returned,
                       errno is set to EDOM, and the value of *eptr
                       is unspecified.

180  –  fscanf

    Performs formatted input from a specified file, interpreting it
    according to the format specification.

    Format

      #include  <stdio.h>

      int fscanf  (FILE *file_ptr, const char *format_spec, . . . );

180.1  –  Arguments

 file_ptr

    A pointer to the file that provides input text.

 format_spec

    A pointer to a character string that contains the format
    specification.

  . . .

    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.

180.2  –  Description

    An example of a conversion specification follows:

    #include <stdio.h>

    main ()
    {
       int   temp, temp2;

       fscanf(stdin, "%d %d", &temp, &temp2);
       printf("The answers are %d, and %d.", temp, temp2);
    }

    Consider a file, designated by stdin, with the following
    contents:

    4 17

    The example conversion specification produces the following
    result:

    The answers are 4, and 17.

180.3  –  Return Values

    x                  The number of successfully matched and
                       assigned input items.
    EOF                Indicates that the end-of-file was encountered
                       or a read error occurred. If a read error
                       occurs, the function sets errno to one of the
                       following:

                       o  EILSEQ - Invalid character detected.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This can indicate that conversion to a
                          numeric value failed due to overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

181  –  fseek

    Positions the file to the specified byte offset in the file.

    Format

      #include  <stdio.h>

      int fseek  (FILE *file_ptr, long int offset, int direction);

181.1  –  Arguments

 file_ptr

    A file pointer.

 offset

    The offset, specified in bytes.

 direction

    An integer indicating the position to which the offset is added
    to calculate the new position. The new position is the beginning
    of the file if direction is SEEK_SET, the current value of the
    file position indicator if direction is SEEK_CUR, or end-of-file
    if direction is SEEK_END.

181.2  –  Description

    The fseek function can position a fixed-length record-access
    file with no carriage control or a stream-access file on any
    byte offset, but can position all other files only on record
    boundaries.

    The available Standard I/O functions position a variable-length
    or VFC record file at its first byte, at the end-of-file, or on
    a record boundary. Therefore, the arguments given to fseek must
    specify any of the following:

    o  The beginning or end of the file

    o  A 0 offset from the current position (an arbitrary record
       boundary)

    o  The position returned by a previous, valid ftell call

    See the fgetpos and fsetpos functions for a portable way to seek
    to arbitrary locations with these types of record files.

                                 CAUTION

       If, while accessing a stream file, you seek beyond the
       end-of-file and then write to the file, the fseek function
       creates a hole by filling the skipped bytes with zeros.

       In general, for record files, fseek should only be directed
       to an absolute position that was returned by a previous
       valid call to ftell, or to the beginning or end of a file.
       If a call to fseek does not satisfy these conditions, the
       results are unpredictable.

    See also open, creat, dup, dup2, and lseek.

181.3  –  Return Values

    0                  Indicates successful seeks.
    -1                 Indicates improper seeks.

182  –  fseeko

    Positions the file to the specified byte offset in the file.
    Equivalent to fseek.

    Format

      #include  <stdio.h>

      int fseeko  (FILE *file_ptr, off_t offset, int direction);

182.1  –  Arguments

 file_ptr

    A file pointer.

 offset

    The offset, specified in bytes. The off_t data type is either a
    32-bit or 64-bit integer. The 64-bit interface allows for file
    sizes greater than 2 GB, and can be selected at compile time by
    defining the _LARGEFILE feature-test macro as follows:

    CC/DEFINE=_LARGEFILE

 direction

    An integer indicating the position to which the offset is added
    to calculate the new position. The new position is the beginning
    of the file if direction is SEEK_SET, the current value of the
    file position indicator if direction is SEEK_CUR, or end-of-file
    if direction is SEEK_END.

182.2  –  Description

    The fseeko function is identical to the fseek function, except
    that the offset argument is of type off_t instead of long int.

183  –  fsetpos

    Sets the file position indicator for a given file.

    Format

      #include  <stdio.h>

      int fsetpos  (FILE *stream, const fpos_t *pos);

183.1  –  Arguments

 stream

    A file pointer.

 pos

    A pointer to an implementation-defined structure. The fgetpos
    function fills this structure with information that can be used
    on subsequent calls to fsetpos.

183.2  –  Description

    Call the fgetpos function before using the fsetpos function.

183.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error.

184  –  fstat

    Accesses information about the file specified by the file
    descriptor.

    Format

      #include  <stat.h>

      int fstat  (int file_desc, struct stat *buffer);

184.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    fstat function that is equivalent to the behavior before OpenVMS
    Version 7.0.

184.2  –  Arguments

 file_desc

    A file descriptor.

 buffer

    A pointer to a structure of type stat_t, which is defined in the
    <stat.h> header file. The argument receives information about
    that particular file. The members of the structure pointed to by
    buffer are:

    Member       Type        Definition

    st_dev       dev_t       Pointer to a physical device name
    st_ino[3]    ino_t       Three words to receive the file ID
    st_mode      mode_t      File "mode" (prot, dir, . . . )
    st_nlink     nlink_t     For UNIX system compatibility only
    st_uid       uid_t       Owner user ID
    st_gid       gid_t       Group member: from st_uid
    st_rdev      dev_t       UNIX system compatibility - always 0
    st_size      off_t       File size, in bytes. For st_size to
                             report a correct value, you need to
                             flush both the C RTL and RMS buffers.
    st_atime     time_t      File access time; always the same as
                             st_mtime
    st_mtime     time_t      Last modification time
    st_ctime     time_t      File creation time
    st_fab_rfm   char        Record format
    st_fab_rat   char        Record attributes
    st_fab_fsz   char        Fixed header size
    st_fab_mrs   unsigned    Record size

    The types dev_t, ino_t, off_t, mode_t, nlink_t, uid_t, gid_t, and
    time_t, are defined in the <stat.h> header file. However, when
    compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_
    t, ino_t, and off_t are defined.

    The off_t data type is either a 32-bit or 64-bit integer. The 64-
    bit interface allows for file sizes greater than 2 GB, and can be
    selected at compile time by defining the _LARGEFILE feature-test
    macro as follows:

    CC/DEFINE=_LARGEFILE

    As of OpenVMS Version 7.0, times are given in seconds since the
    Epoch (00:00:00 GMT, January 1, 1970).

    The st_mode structure member is the status information mode and
    is defined in the <stat.h> header file. The st_mode bits follow:

    Bits     Constant  Definition

    0170000  S_IFMT    Type of file
    0040000  S_IFDIR   Directory
    0020000  S_IFCHR   Character special
    0060000  S_IFBLK   Block special
    0100000  S_IFREG   Regular
    0030000  S_IFMPC   Multiplexed char special
    0070000  S_IFMPB   Multiplexed block special
    0004000  S_ISUID   Set user ID on execution
    0002000  S_ISGID   Set group ID on execution
    0001000  S_ISVTX   Save swapped text even after use
    0000400  S_IREAD   Read permission, owner
    0000200  S_IWRITE  Write permission, owner
    0000100  S_IEXEC   Execute/search permission, owner

184.3  –  Description

    The fstat function does not work on remote network files.

    Be aware that for the stat_t structure member st_size to report a
    correct value, you need to flush both the C RTL and RMS buffers.

                     NOTE (Integrity servers, Alpha)

       On OpenVMS Alpha and Integrity server systems, the stat,
       fstat, utime, and utimes functions have been enhanced to
       take advantage of the new file-system support for POSIX
       compliant file timestamps.

       This support is available only on ODS-5 devices on OpenVMS
       Alpha and Integrity servers systems beginning with a version
       of OpenVMS Alpha after Version 7.3.

       Before this change, the stat and fstat functions were
       setting the values of the st_ctime, st_mtime, and st_atime
       fields based on the following file attributes:

          st_ctime - ATR$C_CREDATE (file creation time)
          st_mtime - ATR$C_REVDATE (file revision time)
          st_atime - was always set to st_mtime because no support
          for file access time was available

       Also, for the file-modification time, utime and utimes were
       modifying the ATR$C_REVDATE file attribute, and ignoring the
       file-access-time argument.

       After the change, for a file on an ODS-5 device, the stat
       and fstat functions set the values of the st_ctime, st_
       mtime, and st_atime fields based on the following new file
       attributes:

          st_ctime - ATR$C_ATTDATE (last attribute modification
          time)
          st_mtime - ATR$C_MODDATE (last data modification time)
          st_atime - ATR$C_ACCDATE (last access time)

       If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat
       and fstat functions set st_atime to st_mtime.

       For the file-modification time, the utime and utimes
       functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
       file attributes. For the file-access time, these functions
       modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
       MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
       has no effect.

       For compatibility, the old behavior of stat, fstat, utime,
       and utimes remains the default, regardless of the kind of
       device.

       The new behavior must be explicitly enabled at run time
       by defining the DECC$EFS_FILE_TIMESTAMPS logical name to
       "ENABLE" before invoking the application. Setting this
       logical does not affect the behavior of stat, fstat, utime
       and utimes for files on an ODS-2 device.

184.4  –  Return Values

    0                  Indicates successful completion.
    -1                 Indicates an error other than a protection
                       violation.
    -2                 Indicates a protection violation.

185  –  fstatvfs

    Gets information about a device containing the specified file.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <statvfs.h>

      int fstatvfs  (int filedes, struct statvfs *buffer);

185.1  –  Arguments

 filedes

    File descriptor obtained from a successful open or fcntl function
    call.

 buffer

    Pointer to a statvfs structure to hold the returned information.

185.2  –  Description

    The fstatvfs function returns descriptive information about the
    device containing the specified file. Read, write, or execute
    permission of the specified file is not required. The returned
    information is in the format of a statvfs structure, which is
    defined in the <statvfs.h> header file and contains the following
    members:

       unsigned long f_bsize - Preferred block size.

       unsigned long f_frsize - Fundamental block size.

       fsblkcnt_t f_blocks - Total number of blocks in units of f_
       frsize.

       fsblkcnt_t f_bfree - Total number of free blocks. If f_bfree
       would assume a meaningless value due to the misreporting of
       free block count by $GETDVI for a DFS disk, then f_bfree is
       set to the maximum block count.

       fsblkcnt_t f_bavail - Number of free blocks available. Set to
       the unused portion of the caller's disk quota.

       fsfilcnt_t f_files - Total file (inode) count.

       fsfilcnt_t f_ffree - Free file (inode) count. For OpenVMS
       systems, this value is calculated as freeblocks/clustersize.

       fsfilcnt_t f_favail - Free file (inode) count nonprivileged.
       Set to f_ffree.

       unsigned long f_fsid - File system identifier. This identifier
       is based on the allocation-class device name. This gives a
       unique value based on device, as long as the device is locally
       mounted.

       unsigned long f_flag - Bit mask representing one or more of
       the following flags:

          ST_RONLY - The volume is read-only.
          ST_NOSUID - The volume has protected subsystems enabled.

       unsigned long f_namemax - Maximum length of a filename.
       char f_basetype[64] - Device-type name.
       char f_fstr[64] - Logical volume name.
       char __reserved[64] - Media type name.

    Upon successful completion, fstatvfs returns 0 (zero). Otherwise,
    it returns -1 and sets errno to indicate the error.

    See also statvfs.

185.3  –  Return Value

    0                  Successful completion.
    -1                 Indicates an error. errno is set to one of the
                       following:

                       o  EBADF - The file descriptor parameter
                          contains an invalid value.

                       o  EIO - An I/O error occurred while reading
                          the device.

                       o  EINTR - A signal was intercepted during
                          execution of the function.

                       o  EOVERFLOW - One of the values to be
                          returned cannot be represented correctly
                          in the structure pointed to by buffer.

186  –  fsync

    Flushes data all the way to the disk.

    Format

      #include  <unistd.h>

      int fsync  (int fd);

186.1  –  Argument

 fd

    A file descriptor corresponding to an open file.

186.2  –  Description

    The fsync function behaves much like the fflush function. The
    primary difference between the two is that fsync flushes data
    all the way to the disk while fflush flushes data only as far as
    the underlying RMS buffers. Also, with fflush, you can flush all
    buffers at once; with fsync you cannot.

186.3  –  Return Values

    0                  Indicates successful completion.
    -1                 Indicates an error.

187  –  ftell

    Returns the current byte offset to the specified stream file.

    Format

      #include  <stdio.h>

      long int ftell  (FILE *file_ptr);

187.1  –  Argument

 file_ptr

    A file pointer.

187.2  –  Description

    The ftell function measures the byte offset from the beginning of
    the file.

    For variable-length files, VFC files, or any file with carriage-
    control attributes, if the file is opened in record mode, then
    ftell returns the starting position of the current record, not
    the current byte offset.

    When using record files, the ftell function ignores any
    characters that have been pushed back using either ungetc or
    ungetwc. This behavior does not occur if stream files are being
    used.

    For a portable way to measure the exact offset for any type of
    file, see the fgetpos function.

187.3  –  Return Values

    n                  The current offset.
    EOF                Indicates an error.

188  –  ftello

    Returns the current byte offset to the specified stream file.
    This function is equivalent to ftell.

    Format

      #include  <stdio.h>

      off_t ftello  (FILE *file_ptr);

188.1  –  Argument

 file_ptr

    A file pointer.

188.2  –  Description

    The ftello function is identical to the ftell function, except
    that the return value is of type off_t instead of long int.

    The off_t data type is either a 64-bit or 32-bit integer. The 64-
    bit interface allows for file sizes greater than 2 GB, and can be
    selected at compile time by defining the _LARGEFILE feature-test
    macro as follows:

    CC/DEFINE=_LARGEFILE

189  –  ftime

    Returns the elapsed time since 00:00:00, January 1, 1970, in the
    structure pointed at by timeptr.

    Format

      #include  <timeb.h>

      int ftime  (struct timeb *timeptr);

189.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    ftime function that is equivalent to the behavior before OpenVMS
    Version 7.0.

189.2  –  Argument

 timeptr

    A pointer to the structure timeb_t.

189.3  –  Description

    The typedef timeb_t refers to the following structure defined in
    the <timeb.h> header file:

    typedef struct timeb
       {
          time_t         time;
          unsigned short millitm;
          short          timezone;
          short          dstflag;
       };

    The member time gives the time in seconds.

    The member millitm gives the fractional time in milliseconds.

    After a call to ftime, the timezone and dstflag members of the
    timeb structure have the values of the global variables timezone
    and dstflag, respectively. See the description of the tzset
    function for timezone and dstflag global variables.

189.4  –  Return Values

    0                  Successful execution. The timeb_t structure is
                       filled in.
    -1                 Indicates an error. Failure might indicate
                       that the system's time-differential factor
                       (that is, the difference between the system
                       time and UTC time) is not set correctly.

                       If the value of the SYS$TIMEZONE_DIFFERENTIAL
                       logical is wrong, the function fails with
                       errno set to EINVAL.

190  –  ftok

    Generates a standard interprocess communication key that is
    usable in subsequent calls to semget.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <ipc.h>

      key_t ftok  (const char *path_name, int project_id);

190.1  –  Argument

 path_name

    the pathname of an existing file that is accessible to the
    process.

 project_id

    a value that uniquely identifies a project.

190.2  –  Description

    The ftok function returns a key, based on the path_name and
    project_id parameters, that is usable in subsequent calls to the
    semget function. The ftok function returns the same key for all
    paths that name the same file, when called with the same project_
    id parameter. Different keys are returned for the same file if
    different project_id parameters are used, or if paths are used
    that name different files existing on the same file system at the
    same time. If a file named by path_name is removed and recreated
    with the same name, the ftok function may return a different key
    than the original one.

    Only the low order 8 bits of project_id are significant. The
    behavior of ftok is unspecified if these bits are 0.

    For maximum portability, project_id must be a single-byte
    character.

    Upon successful completion, the ftok function returns a key.
    Otherwise, it returns the value (key_t)-1 and sets errno to
    indicate the error.

190.3  –  Return Values

    n                  Upon successful completion, the ftok function
                       returns a key.
    (key_t)-1          Indicates an error. The function sets errno
                       to:

                       o  EACCESS - Search permission is denied for a
                          component of the path_name parameter.

191  –  ftruncate

    Truncates a file to a specified length.

    Format

      #include  <unistd.h>

      int ftruncate  (int filedes, off_t length);

191.1  –  Arguments

 filedes

    The descriptor of a file that must be open for writing.

 length

    The new length of the file, in bytes. The off_t data type is
    either a 32-bit or 64-bit integer. The 64-bit interface allows
    for file sizes greater than 2 GB, and can be selected at compile
    time by defining the _LARGEFILE feature-test macro as follows:

    CC/DEFINE=_LARGEFILE

191.2  –  Description

    The ftruncate function truncates a file at the specified
    position. For record files, the position must be a record
    boundary. Also, the files must be local, regular files.

    If the file was previously larger than length, extra data is
    lost. If the file was previously shorter than length, bytes
    between the old and new lengths are read as zeros.

191.3  –  Return Values

    0                  Indicates success.
    -1                 An error occurred; errno is set to indicate
                       the error.

192  –  ftrylockfile

    Acquires ownership of a stdio (FILE*) object.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int ftrylockfile  (FILE *file_ptr);

192.1  –  Argument

 file_ptr

    A file pointer.

192.2  –  Description

    The ftrylockfile function is used by a thread to acquire
    ownership of a stdio (FILE*) object, if the object is available.
    The ftrylockfile function is a non-blocking version of flockfile.

    The ftrylockfile function returns zero for success and nonzero to
    indicate that the lock cannot be acquired.

    See also flockfile and funlockfile.

192.3  –  Return Values

    0                  Indicates success.
    nonzero            Indicates the lock cannot be acquired.

193  –  ftw

    Walks a file tree.

    Format

      #include  <ftw.h>

      int ftw  (const char *path, int(*function)(const char *, const
               struct stat *, int), int depth);

193.1  –  Arguments

 path

    The directory hierarchy to be searched.

 function

    The function to be invoked for each file in the directory
    hierarchy.

 depth

    The maximum number of directory streams or file descriptors, or
    both, available for use by ftw. This argument should be in the
    range of 1 to OPEN_MAX.

193.2  –  Description

    The ftw function recursively searches the directory hierarchy
    that descends from the directory specified by the path argument.
    The path argument can be specified in OpenVMS style or UNIX
    style.

    For each file in the hierarchy, ftw calls the function specified
    by the function argument, passes it a pointer to a null-
    terminated character string containing the name of the file, a
    pointer to a stat structure containing information about the
    file, and an integer.

    The integer identifies the file type. Possible values, defined in
    <ftw.h> are:

    FTW_F          Regular file.
    FTW_D          Directory.
    FTW_DNR        Directory that cannot be read.
    FTW_NS         A file on which stat could not successfully be
                   executed.

    If the integer is FTW_DNR, then the files and subdirectories
    contained in that directory are not processed.

    If the integer is FTW_NS, then the stat structure contents are
    meaningless. For example, a file in a directory for which you
    have read permission but not execute (search) permission can
    cause the function argument to pass FTW_NS.

    The ftw function finishes processing a directory before
    processing any of its files or subdirectories.

    The ftw function continues the search until:

    o  The directory hierarchy specified by the path argument is
       completed.

    o  An invocation of the function specified by the function
       argument returns a nonzero value.

    o  An error (such as an I/O error) is detected within the ftw
       function.

    Because the ftw function is recursive, it is possible for it
    to terminate with a memory fault because of stack overflow when
    applied to very deep file structures.

    The ftw function uses the malloc function to allocate dynamic
    storage during its operation. If ftw is forcibly terminated,
    as with a call to longjmp from the function pointed to by the
    function argument, ftw has no chance to free that storage. It
    remains allocated.

    A safe way to handle interrupts is to store the fact that
    an interrupt has occurred, and arrange to have the function
    specified by the function argument return a nonzero value the
    next time it is called.

                                  NOTES

       o  The ftw function is reentrant; make sure that the
          function supplied as argument function is also reentrant.

       o  The C RTL supports a standard-compliant definition of the
          stat structure and associated definitions. To use them,
          compile your application with the _USE_STD_STAT feature-
          test macro defined. See the <stat.h> header file on your
          system for more information.

       o  The ftw function supports UNIX style path name
          specifications.

    See also malloc, longjump, and stat.

193.3  –  Return Values

    0                  Indicates success.
    x                  Indicates that the function specified by
                       the function argument stops its search, and
                       returns the value that was returned by the
                       function.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - Search permission is denied for
                          any component of the path argument or read
                          permission is denied for the path argument.

                       o  ENAMETOOLONG - The length of the path
                          string exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX while
                          [_POSIX_NO_TRUNC] is in effect.

                       o  ENOENT - The path argument points to the
                          name of a file that does not exist or
                          points to an empty string.

                       o  ENOMEM - There is insufficient memory for
                          this operation.

                       Also, if the function pointed to by the
                       function argument encounters an error, errno
                       can be set accordingly.

194  –  funlockfile

    Unlocks a stdio stream.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      void funlockfile  (FILE *file_ptr);

194.1  –  Argument

 file_ptr

    A file pointer.

194.2  –  Description

    The funlockfile function unlocks a stdio stream, causing the
    thread that had been holding the lock to relinquish exclusive use
    of the stream.

    File pointers passed are assumed to be valid; flockfile will
    perform locking even on invalid file pointers. Also, the
    funlockfile function will not fail if the calling thread does
    not own a lock on the file pointer passed.

    Matching flockfile and funlockfile calls can be nested. If the
    stream has been locked recursively, it will remain locked until
    the last matching funlockfile is called.

    All C RTL file-pointer I/O functions lock their file pointers as
    if calling flockfile and funlockfile.

    See also flockfile and ftrylockfile.

195  –  fwait

    Waits for I/O on a specific file to complete.

    Format

      #include  <stdio.h>

      int fwait  (FILE *fp);

195.1  –  Argument

 fp

    A file pointer corresponding to an open file.

195.2  –  Description

    The fwait function is used primarily to wait for completion of
    pending asynchronous I/O.

195.3  –  Return Values

    0                  Indicates successful completion.
    -1                 Indicates an error.

196  –  fwide

    Determines and sets the orientation of a stream.

    Format

      #include  <wchar.h>

      int fwide  (FILE *stream, int mode);

196.1  –  Arguments

 stream

    A file pointer.

 mode

    A value that specifies the desired orientation of the stream.

196.2  –  Description

    The fwide function determines the orientation of the stream
    pointed to by stream and sets the orientation of a nonoriented
    stream according to the mode argument in the following way:

    If the mode
    argument is:     Then the fwide function:

    greater than     makes the stream wide-oriented.
    zero
    less than zero   makes the stream byte-oriented.
    zero             does not alter the orientation of the stream.

    If the orientation of the stream has already been set, fwide does
    not alter it. Because no error status is defined for fwide, the
    calling application should check errno if fwide returns a 0.

196.3  –  Return Values

    > 0                After the call, the stream is wide-oriented.
    < 0                After the call, the stream is byte-oriented.
    0                  After the call, the stream has no orientation
                       or a stream argument is invalid; the function
                       sets errno.

197  –  fwprintf

    Writes output to the stream under control of the wide-character
    format string.

    Format

      #include  <wchar.h>

      int fwprintf  (FILE *stream, const wchar_t *format, . . . );

197.1  –  Arguments

 stream

    A file pointer.

 format

    A pointer to a wide-character string containing the format
    specifications.

  . . .

    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. Any excess output sources are ignored.

197.2  –  Description

    The fwprintf function writes output to the stream pointed to by
    stream under control of the wide-character string pointed to by
    format, which specifies how to convert subsequent arguments to
    output. If there are insufficient arguments for the format, the
    behavior is undefined. If the format is exhausted while arguments
    remain, the excess arguments are evaluated, but are otherwise
    ignored. The fwprintf function returns when it encounters the end
    of the format string.

    The format argument is composed of zero or more directives that
    include:

    o  Ordinary wide characters (not the percent sign (%))

    o  Conversion specifications

197.3  –  Return Values

    n                  The number of wide characters written.
    Negative value     Indicates an error. The function sets errno to
                       one of the following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This might indicate that conversion to a
                          numeric value failed because of overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

197.4  –  Example

      The following example shows how to print a date and time in the
      form "Sunday, July 3, 10:02", followed by pi to five decimal
      places:

        #include <math.h>
        #include <stdio.h>
        #include <wchar.h>
        /* . . . */
        wchar_t *weekday, *month; /* pointers to wide-character strings */
        int day, hours, min;
        fwprintf(stdout, L"%ls, %ls %d, %.2d:%.2d\n",
           weekday, month, day, hour, min);
        fwprintf(stdout, L"pi = %.5f\n", 4 * atan(1.0));

198  –  fwrite

    Writes a specified number of items to the file.

    Format

      #include  <stdio.h>

      size_t fwrite  (const void *ptr, size_t size_of_item, size_t
                     number_items, FILE *file_ptr);

198.1  –  Arguments

 ptr

    A pointer to the memory location from which information is being
    written. The type of the object pointed to is determined by the
    type of the item being written.

 size_of_item

    The size, in bytes, of the items being written.

 number_items

    The number of items to be written.

 file_ptr

    A file pointer that indicates the file to which the items are
    being written.

198.2  –  Description

    The type size_t is defined in the header file <stdio.h> as
    follows:

    typedef unsigned int size_t

    The writing begins at the current location in the file. The items
    are written from storage beginning at the location given by the
    first argument. You must also specify the size of an item, in
    bytes.

    If the file pointed to by file_ptr is a record file, the fwrite
    function outputs at least number_items records, each of length
    size_of_item.

198.3  –  Return Value

    x                  The number of items written. The number of
                       records written depends upon the maximum
                       record size of the file.

199  –  fwscanf

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

    Format

      #include  <wchar.h>

      int fwscanf  (FILE *stream, const wchar_t *format, . . . );

199.1  –  Arguments

 stream

    A file pointer.

 format

    A pointer to a wide-character string containing the format
    specification.

  . . .

    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.

199.2  –  Description

    The fwscanf function reads input from the stream pointed to by
    stream under the control of the wide-character string pointed
    to by format. If there are insufficient arguments for the
    format, the behavior is undefined. If the format is exhausted
    while arguments remain, the excess arguments are evaluated, but
    otherwise ignored.

    The format is composed of zero or more directives that include:

    o  One or more white-space wide characters.

    o  An ordinary wide character (neither a percent (%))  nor a
       white-space wide character).

    o  Conversion specifications.

    Each conversion specification is introduced by the wide character
    %.

    If the stream pointed to by the stream argument has no
    orientation, fwscanf makes the stream wide-oriented.

199.3  –  Return Values

    n                  The number of input items assigned, sometimes
                       fewer than provided for, or even zero, in the
                       event of an early matching failure.
    EOF                Indicates an error; input failure occurs
                       before any conversion.

200  –  gcvt

    Converts its argument to a null-terminated string of ASCII digits
    and returns the address of the string.

    Format

      #include  <stdlib.h>

      char *gcvt  (double value, int ndigit, char *buffer);

200.1  –  Function Variants

    The gcvt function has variants named _gcvt32 and _gcvt64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

200.2  –  Arguments

 value

    An object of type double that is converted to a null-terminated
    string of ASCII digits.

 ndigit

    The number of ASCII digits to use in the converted string. If
    ndigit is less than 6, the value of 6 is used.

 buffer

    A storage location to hold the converted string.

200.3  –  Description

    The gcvt function places the converted string in a buffer and
    returns the address of the buffer. If possible, gcvt produces
    ndigit significant digits in F-format, or if not possible, in
    E-format. Trailing zeros are suppressed.

    The ecvt, fcvt, and gcvt functions represent the following
    special values specified in the IEEE Standard for floating-point
    arithmetic:

    Value         Representation

    Quiet NaN     NaNQ
    Signalling    NaNS
    NaN
    +Infinity     Infinity
    -Infinity     -Infinity

    The sign associated with each of these values is stored into the
    sign argument. In IEEE floating-point representation, a value
    of 0 (zero) can be positive or negative, as set by the sign
    argument.

    See also fcvt and ecvt.

200.4  –  Return Value

    x                  The address of the buffer.

201  –  getc

    Returns the next character from a specified file.

    Format

      #include  <stdio.h>

      int getc  (FILE *file_ptr);

201.1  –  Argument

 file_ptr

    A pointer to the file to be accessed.

201.2  –  Description

    The getc macro returns the next byte from the input stream
    specified by the file_ptr parameter and moves the file pointer,
    if defined, ahead one byte in the input stream.

    Since getc is a macro, a file pointer argument with side effects
    (for example, getc (*f++)) might be evaluated incorrectly.
    In such a case, use the fgetc function instead. See the fgetc
    function.

    See also getc_unlocked.

201.3  –  Return Values

    n                  The returned character.
    EOF                Indicates the end-of-file or an error.

202  –  getc_unlocked

    Same as getc, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int getc_unlocked  (FILE *file_ptr);

202.1  –  Argument

 file_ptr

    A file pointer.

202.2  –  Description

    The reentrant version of the getc macro is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, getc_unlocked can be used to avoid the overhead. The getc_
    unlocked macro is functionally identical to the getc macro,
    except that it is not required to be implemented in a thread-
    safe manner. The getc_unlocked macro can be safely used only
    within a scope that is protected by the flockfile and funlockfile
    functions used as a pair. The caller must ensure that the stream
    is locked before getc_unlocked is used.

    Since getc_unlocked is a macro, a file pointer argument with side
    effects might be evaluated incorrectly. In such a case, use the
    fgetc_unlocked function instead.

    See also flockfile, ftrylockfile, and funlockfile.

202.3  –  Return Values

    n                  The returned character.
    EOF                Indicates the end-of-file or an error.

203  –  [w]getch

    Get a character from the terminal screen and echo it on the
    specified window. The getch function echoes the character on
    the stdscr window.

    Format

      #include  <curses.h>

      char getch();

      char wgetch  (WINDOW *win);

203.1  –  Argument

 win

    A pointer to the window.

203.2  –  Description

    The getch and wgetch functions refresh the specified window
    before fetching a character. For more information, see the
    scrollok function.

203.3  –  Return Values

    x                  The returned character.
    ERR                Indicates that the function makes the screen
                       scroll illegally.

204  –  getchar

    Reads a single character from the standard input (stdin).

    Format

      #include  <stdio.h>

      int getchar  (void);

204.1  –  Description

    The getchar function is identical to fgetc(stdin).

    See also getchar_unlocked.

204.2  –  Return Values

    x                  The next character from stdin, converted to
                       int.
    EOF                Indicates the end-of-file or an error.

205  –  getchar_unlocked

    Same as getchar, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int getchar_unlocked  (void);

205.1  –  Description

    The reentrant version of the getchar function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the input stream. The unlocked version of
    this call, getchar_unlocked can be used to avoid the overhead.
    The getchar_unlocked function is functionally identical to
    the getchar function, except that it is not required to be
    implemented in a thread-safe manner. The getchar_unlocked
    function can be safely used only within a scope that is protected
    by the flockfile and funlockfile functions used as a pair. The
    caller must ensure that the stream is locked before getchar_
    unlocked is used.

    See also flockfile, ftrylockfile, and funlockfile.

205.2  –  Return Values

    x                  The next character from stdin, converted to
                       int.
    EOF                Indicates the end-of-file or an error.

206  –  getclock

    Gets the current value of the systemwide clock.

    Format

      #include  <timers.h>

      int getclock  (int clktyp, struct timespec *tp);

206.1  –  Arguments

 clktyp

    The type of systemwide clock.

 tp

    Pointer to a timespec structure space where the current value of
    the systemwide clock is stored.

206.2  –  Description

    The getclock function sets the current value of the clock
    specified by clktyp into the location pointed to by tp.

    The clktyp argument is given as a symbolic constant name,
    as defined in the <timers.h> header file. Only the TIMEOFDAY
    symbolic constant, which specifies the normal time-of-day clock
    to access for systemwide time, is supported.

    For the clock specified by TIMEOFDAY, the value returned by
    this function is the elapsed time since the Epoch. The Epoch
    is referenced to 00:00:00 UTC (Coordinated Universal Time) 1 Jan
    1970.

    The getclock function returns a timespec structure, which is
    defined in the <timers.h> header file as follows:

     struct  timespec {

      unsigned long  tv_sec   /* Elapsed time in seconds since the Epoch*/
      long           tv_nsec  /* Elapsed time as a fraction of a second */
                              /* since the Epoch (in nanoseconds)       */

     };

206.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EINVAL - The clktyp argument does not
                          specify a known systemwide clock.

                          Or, the value of SYS$TIMEZONE_DIFFERENTIAL
                          logical is wrong.

                       o  EIO - An error occurred when the systemwide
                          clock specified by the clktyp argument was
                          accessed.

207  –  getcwd

    Returns a pointer to the file specification for the current
    working directory.

    Format

      #include  <unistd.h>

      char *getcwd  (char *buffer, size_t size); (ISO POSIX-1)

      char *getcwd  (char *buffer, unsigned int size, . . . );
                      (DEC C Extension)

207.1  –  Function Variants

    The getcwd function has variants named _getcwd32 and _getcwd64
    for use with 32-bit and 64-bit pointer sizes, respectively.

207.2  –  Arguments

 buffer

    Pointer to a character string large enough to hold the directory
    specification.

    If buffer is a NULL pointer, getcwd obtains size bytes of space
    using malloc. In this case, you can use the pointer returned by
    getcwd as the argument in a subsequent call to free.

 size

    The length of the directory specification to be returned.

  . . .

    An optional argument that can be either 1 or 0. If you specify 1,
    the directory specification is returned in OpenVMS format. If you
    specify 0, the directory specification (pathname) is returned in
    UNIX style format. If you omit this argument, getcwd returns the
    filename according to your current command-language interpreter
    (CLI).

207.3  –  Return Values

    x                  A pointer to the file specification.
    NULL               Indicates an error.

208  –  getdtablesize

    Gets the total number of file descriptors that a process can have
    open simultaneously.

    Format

      #include  <unistd.h>

      int getdtablesize  (void);

208.1  –  Description

    The getdtablesize function returns the total number of file
    descriptors that a process can have open simultaneously. Each
    process is limited to a fixed number of open file descriptors.

    The number of file descriptors that a process can have open is
    the minumum of the following:

    o  C RTL open file limit-65535 on OpenVMS Alpha and
       Integrity servers.

    o  SYSGEN CHANNELCNT parameter-permanent I/O channel count.

    o  Process open file quota FILLM parameter-number of open files
       that can be opened by a process at one time.

208.2  –  Return Values

    x                  The number of file descriptors that a process
                       can have open simultaneously.
    -1                 Indicates an error.

209  –  getegid

    With POSIX IDs disabled, this function is equivalent to getgid
    and returns the group number from the user identification code
    (UIC).

    With POSIX IDs enabled, this function returns the effective group
    ID of the calling process.

    Format

      #include  <unistd.h>

      gid_t getegid  (void);

209.1  –  Description

    The getegid function can be used with POSIX style identifiers
    (IDs) or with UIC-based identifiers.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX style IDs disabled, the getegid and getgid functions
    are equivalent and return the group number from the current UIC.
    For example, if the UIC is [313,031], 313 is the group number.

    With POSIX style IDs enabled, getegid returns the effective group
    ID of the calling process, and getgid returns the real group ID
    of the calling process. The real group ID is specified at login
    time. The effective group ID is more transient, and determines
    additional access permission during execution of a set-group-ID
    process. It is for such processes that the getgid function is
    most useful.

    The getegid function is always successful; no return value is
    reserved to indicate an error.

    See also geteuid and getuid.

209.2  –  Return Value

    x                  The effective group ID (POSIX IDs enabled),
                       or the group number from the UIC (POSIX IDs
                       disabled).

210  –  getenv

    Searches the environment array for the current process and
    returns the value associated with a specified environment name.

    Format

      #include  <stdlib.h>

      char *getenv  (const char *name);

210.1  –  Argument

 name

    One of the following values:

    o  HOME-Your login directory

    o  TERM-The type of terminal being used

    o  PATH-The default device and directory

    o  USER-The name of the user who initiated the process

    o  Logical name or command-language interpreter (CLI) symbolic
       name

    o  An environment variable set with setenv or putenv

    The case of the specified name is important.

210.2  –  Description

    In certain situations, the getenv function attempts to perform a
    logical name translation on the user-specified argument:

    1. If the argument to getenv does not match any of the
       environment strings present in your environment array, getenv
       attempts to translate your argument as a logical name by
       searching the logical name tables indicated by the LNM$FILE_
       DEV logical, as is done for file processing.

       getenv first does a case-sensitive lookup. If that fails, it
       does a case-insensitive lookup. In most instances, logical
       names are defined in uppercase, but getenv can also find
       logical names that include lowercase letters.

       getenv does not perform iterative logical name translation.

    2. If the logical name is a search list with multiple equivalence
       values, the returned value points to the first equivalence
       value. For example:

       $ DEFINE A B,C

       ptr = getenv("A");

       A returns a pointer to "B".

    3. If no logical name exists, getenv attempts to translate the
       argument string as a CLI symbol. If it succeeds, it returns
       the translated symbol text. If it fails, the return value is
       NULL.

       getenv does not perform iterative CLI translation.

    If your CLI is the DEC/Shell, the function does not attempt a
    logical name translation since Shell environment symbols are
    implemented as DCL symbols.

                                  NOTES

       o  In OpenVMS Version 7.1, a cache of OpenVMS environment
          variables (that is, logical names and DCL symbols)
          was added to the getenv function to avoid the library
          making repeated calls to translate a logical name or
          to obtain the value of a DCL symbol. By default, the
          cache is disabled. If your application does not need to
          track changes in OpenVMS environment variables that can
          occur during its execution, the cache can be enabled
          by enabling the DECC$ENABLE_GETENV_CACHE logical before
          invoking the application.

       o  Do not use the setenv, getenv, and putenv functions
          to manipulate symbols and logicals. Instead use the
          OpenVMS library calls lib$set_logical, lib$get_logical,
          lib$set_symbol, and lib$get_symbol. The *env functions
          deliberately provide UNIX behavior, and are not a
          substitute for these OpenVMS runtime library calls.

          OpenVMS DCL symbols, not logical names, are the closest
          analog to environment variables on UNIX systems. While
          getenv is a mechanism to retrieve either a logical name
          or a symbol, it maintains an internal cache of values for
          use with setenv and subsequent getenv calls. The setenv
          function does not write or create DCL symbols or OpenVMS
          logical names.

          This is consistent with UNIX behavior. On UNIX systems,
          setenv does not change or create any symbols that will be
          visible in the shell after the program exits.

210.3  –  Return Values

    x                  Pointer to an array containing the translated
                       symbol. An equivalence name is returned at
                       index zero.
    NULL               Indicates that the translation failed.

211  –  geteuid

    With POSIX IDs disabled, this function is equivalent to getuid
    and returns the member number (in OpenVMS terms) from the user
    identification code (UIC).

    With POSIX IDs enabled, this function returns the effective user
    ID.

    Format

      #include  <unistd.h>

      uid_t geteuid  (void);

211.1  –  Description

    The geteuid function can be used with POSIX style identifiers
    (IDs) or with UIC-based identifiers.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX style IDs disabled (the default), the geteuid and
    getuid functions are equivalent and return the member number from
    the current UIC as follows:

    o  For programs compiled with the _VMS_V6_SOURCE feature-
       test macro or programs that do not include the <unistd.h>
       header file, the getuid and geteuid functions return the
       member number of the OpenVMS UIC. For example, if the UIC
       is [313,31], then the member number, 31, is returned.

    o  For programs compiled without the _VMS_V6_SOURCE feature-
       test macro that do include the <unistd.h> header file, the
       full UIC is returned in decimal after converting the octal
       representation to decimal. For example, if the UIC is [313,
       31] then 13303833 is returned. (13303833 = 25 + 203 * 65536;
       Octal 31 = 25 decimal; Octal 313 = 203 decimal.)

    With POSIX style IDs enabled, geteuid returns the effective user
    ID of the calling process, and getuid returns the real user ID of
    the calling process.

    See also getegid and getgid.

211.2  –  Return Value

    x                  The effective user ID (POSIX IDs enabled), or
                       the member number from the current UIC or the
                       full UIC (POSIX IDs disabled).

212  –  getgid

    With POSIX IDs disabled, this function is equivalent to getegid
    and returns the group number from the user identification code
    (UIC).

    With POSIX IDs enabled, this function returns the real group ID.

    Format

      #include  <unistd.h>

      gid_t getgid  (void);

212.1  –  Description

    The getgid function can be used with POSIX style identifiers or
    with UIC-based identifiers.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX style IDs disabled (the default), the getegid and
    getgid functions are equivalent and return the group number from
    the current UIC. For example, if the UIC is [313,031], 313 is the
    group number.

    With POSIX style IDs enabled, getegid returns the effective group
    ID of the calling process, and getgid returns the real group ID
    of the calling process. The real group ID is specified at login
    time. The effective group ID is more transient, and determines
    additional access permission during execution of a set-group-ID
    process. It is for such processes that the getgid function is
    most useful.

    See also geteuid and getuid.

212.2  –  Return Value

    x                  The real group ID (POSIX IDs enabled), or the
                       group number from the current UIC (POSIX IDs
                       disabled).

    Gets a group database entry.

213  –  getgrent

    Gets a group database entry.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <grp.h>

      struct group *getgrent  (void);

213.1  –  Description

    The getgrent function returns the next group in the sequential
    search, returning a pointer to a structure containing the broken-
    out fields of an entry in the group database.

    When first called, getgrent returns a pointer to a group
    structure containing the first entry in the group database.
    Thereafter, it returns a pointer to the next group structure
    in the group database, so successive calls can be used to search
    the entire database.

    If an end-of-file or an error is encountered on reading, getgrent
    returns a NULL pointer and sets errno.

213.2  –  Return Values

    x                  Pointer to a group structure, if successful.
    NULL               Indicates that an error occurred. The function
                       sets errno to one of the following values:

                       o  EACCES - The user process does not have
                          appropriate privileges enabled to access
                          the user authorization file.

                       o  EINTR - A signal was intercepted during the
                          operation.

                       o  EIO - Indicates that an I/O error occurred.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

214  –  getgrgid

    Gets a group database entry for a group ID.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <types.h>

      #include  <grp.h>

      struct group *getgrgid  (gid_t gid);

214.1  –  Argument

 gid

    The group ID of the group for which the group database entry is
    to be retrieved.

214.2  –  Description

    The getgrgid function searches the group database for an entry
    with a matching gid and returns a pointer to the group structure
    containing the matching entry.

214.3  –  Return Values

    x                  Pointer to a valid group structure containing
                       a matching entry.
    NULL               An error occurred.

                       Note: The return value points to a static area
                       that is overwritten by subsequent calls to
                       getgrent, getgrgid, or getgrnam.

                       On error, the function sets errno to one of
                       the following values:

                       o  EACCES - The user process does not have
                          appropriate privileges enabled to access
                          the user authorization file.

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getgrgid.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

                       Applications checking for error situations
                       must set errno to 0 before calling getgrgid.
                       If errno is set on return, an error has
                       occurred.

215  –  getgrgid_r

    Gets a group database entry for a group ID.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <types.h>

      #include  <grp.h>

      int getgrgid_r  (gid_t gid, struct group *grp, char *buffer,
                      size_t bufsize, struct group **result);

215.1  –  Arguments

 gid

    The group ID of the group for which the group database entry is
    to be retrieved.

 grp

    Storage area to hold the retrieved group structure.

 buffer

    The working buffer that is able to hold the longest group entry
    in the database.

 bufsize

    The length, in characters, of buffer.

 result

    Upon successful return, result points to the retrieved group
    structure.

    Upon unsuccessful return, result is set to NULL.

215.2  –  Description

    The getgrgid_r function updates the group structure pointed to
    by grp and stores a pointer to that structure at the location
    pointed to by result. The structure contains an entry from the
    group database with a matching gid. Storage referenced by the
    group structure is allocated from the memory provided with the
    buffer argument, which is bufsize characters in size. The maximum
    size needed for this buffer can be determined with the _SC_GETGR_
    R_SIZE_MAX parameter of the sysconf function. On error or if the
    requested entry is not found, a NULL pointer is returned at the
    location pointed to by result.

215.3  –  Return Values

    0                  Successful completion.
    x                  On error, the function sets the return value
                       to one of the following:

                       o  EACCES - The user process does not have
                          appropriate privileges enabled to access
                          the user authorization file.

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getgrgid.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

                       o  ERANGE - Insufficient storage was supplied
                          through the buffer and bufsize arguments
                          to contain the data to be referenced by the
                          resulting group structure.

216  –  getgrnam

    Gets a group database entry for a name.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <types.h>

      #include  <grp.h>

      struct group *getgrnam  (const char *name);

216.1  –  Argument

 name

    The group name of the group for which the group database entry is
    to be retrieved.

216.2  –  Description

    The getgrnam function searches the group database for an
    entry with a matching name, and returns a pointer to the group
    structure containing the matching entry.

216.3  –  Return Values

    x                  Pointer to a valid group structure containing
                       a matching entry.
    NULL               Indicates an error.

                       Note: The return value points to a static area
                       which is overwritten by subsequent calls to
                       getgrent, getgrgid, or getgrnam.

                       On error, the function sets the return value
                       to one of the following:

                       o  EACCES - The user process does not have
                          appropriate privileges enabled to access
                          the user authorization file.

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getgrnam.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

                       Applications wishing to check for error
                       situations should set errno to 0 before
                       calling getgrnam. If errno is set on return,
                       an error occurred.

217  –  getgrnam_r

    Gets a group database entry for a name.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <types.h>

      #include  <grp.h>

      int getgrnam_r  (const char *name, struct group *grp,
                      char *buffer, size_t bufsize, struct group
                      **result);

217.1  –  Arguments

 name

    The group name of the group for which the group database entry is
    to be retrieved.

 grp

    Storage area to hold the retrieved group structure.

 buffer

    The working buffer that is able to hold the longest group entry
    in the database.

 bufsize

    The length, in characters, of buffer.

 result

    Upon successful return, result points to the retrieved group
    structure.

    Upon unsuccessful return, result is set to NULL.

217.2  –  Description

    The getgrnam_r function updates the group structure pointed to
    by grp and stores a pointer to that structure at the location
    pointed to by result. The structure contains an entry from the
    group database with a matching name. Storage referenced by the
    group structure is allocated from the memory provided with the
    buffer argument, which is bufsize characters in size. The maximum
    size needed for this buffer can be determined with the _SC_GETGR_
    R_SIZE_MAX parameter of the sysconf function. On error or if the
    requested entry is not found, a NULL pointer is returned at the
    location pointed to by result.

217.3  –  Return Values

    0                  Successful completion.
    x                  On error, the function sets the return value
                       to one of the following:

                       o  EACCES - The user process does not have
                          appropriate privileges enabled to access
                          the user authorization file.

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getgrnam.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

                       o  ERANGE - Insufficient storage was supplied
                          through the buffer and bufsize arguments
                          to contain the data to be referenced by the
                          resulting group structure.

218  –  getgroups

    Gets the current supplementary group IDs of the calling process.

    Format

      #include  <unistd.h>

      int getgroups  (int gidsetsize, gid_t grouplist[]);

218.1  –  Arguments

 gidsetsize

    Indicates the number of entries that can be stored in the array
    pointed to by the grouplist parameter.

 grouplist

    Points to the array in which the supplementary group IDs of
    the process are stored. The effective group ID of the process
    is not returned by the getgroups function if it is not also a
    supplementary group ID of the calling process.

218.2  –  Description

    The getgroups function gets the current supplementary group IDs
    of the calling process. The list is stored in the array pointed
    to by the grouplist parameter. The gidsetsize parameter indicates
    the number of entries that can be stored in this array.

    The getgroups function never returns more IDs than the value
    indicated by the sysconf parameter _SC_NGROUPS_MAX.

    See also getgid and setsid.

218.3  –  Return Value

    n                  The number of elements stored in the array
                       pointed to by the grouplist parameter.
    -1                 Indicates failure. errno might be set to one
                       of the following values:

                       o  EFAULT - The gidsetsize and grouplist
                          parameters specify an array that is
                          partially or completely outside of the
                          allocated address space of the process.

                       o  EINVAL - The gidsetsize parameter is
                          nonzero and smaller than the number of
                          supplementary group IDs.

219  –  getitimer

    Returns the value of interval timers.

    Format

      #include  <time.h>

      int getitimer  (int which, struct itimerval *value);

219.1  –  Arguments

 which

    The type of interval timer. The C RTL supports only
    ITIMER_REAL.

 value

    Pointer to an itimerval structure whose members specify a timer
    interval and the time left to the end of the interval.

219.2  –  Description

    The getitimer function returns the current value for the timer
    specified by the which argument in the structure pointed to by
    value.

    A timer value is defined by the itimerval structure:

           struct itimerval {
                   struct  timeval it_interval;
                   struct  timeval it_value;
           };

    The following table lists the values for the itimerval structure
    members:

    itimerval Member
    Value              Meaning

    it_interval = 0    Disables a timer after its next expiration and
                       assumes it_value is nonzero.
    it_interval =      Specifies a value used in reloading it_value
    nonzero            when the timer expires.
    it_value = 0       Disables a timer.
    it_value =         Indicates the time to the next timer
    nonzero            expiration.

    Time values smaller than the resolution of the system clock are
    rounded up to this resolution.

    The C RTL provides each process with one interval timer,
    defined in the <time.h> header file as ITIMER_REAL. This timer
    decrements in real time and delivers a SIGALRM signal when the
    timer expires.

219.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to EINVAL
                       (The value argument specified a time that was
                       too large to handle.)

220  –  getlogin

    Gets the login name.

    Format

      #include  <unistd.h>

      char *getlogin  (void);

      int *getlogin_r  (char *name, size_t namesize);

220.1  –  Description

    The getlogin function returns the login name of the user
    associated with the current session. If getlogin returns a non-
    null pointer, then that pointer points to the name that the user
    logged in under, even if there are several login names with the
    same user ID.

    The getlogin_r function is the reentrant version of getlogin.
    Upon successful completion, getlogin_r returns 0 and puts the
    name associated by the login activity with the controlling
    terminal of the current process in the character array pointed
    to by name. The array is namesize characters long and should
    have space for the name and the terminating null character. The
    maximum size of the login name is LOGIN_NAME_MAX.

    If getlogin_r is successful, name points to the name the user
    used at login, even if there are several login names with the
    same user ID.

220.2  –  Return Values

    x                  Upon successful completion, getlogin returns
                       a pointer to a null-terminated string in a
                       static buffer.
    0                  Indicates successful completion of getlogin_r.
    NULL               Indicates an error; errno is set.

221  –  getname

    Returns the file specification associated with a file descriptor.

    Format

      #include  <unixio.h>

      char *getname  (int file_desc, char *buffer, . . . );

221.1  –  Function Variants

    The getname function has variants named _getname32 and _getname64
    for use with 32-bit and 64-bit pointer sizes, respectively.

221.2  –  Arguments

 file_desc

    A file descriptor.

 buffer

    A pointer to a character string that is large enough to hold the
    file specification.

  . . .

    An optional argument that can be either 1 or 0. If you specify
    1, the getname function returns the file specification in OpenVMS
    format. If you specify 0, the getname function returns the file
    specification in UNIX style format. If you omit this argument,
    the getname function returns the filename according to your
    current command-language interpreter (CLI).

221.3  –  Description

    The getname function places the file specification into the
    area pointed to by buffer and returns that address. The area
    pointed to by buffer should be an array large enough to contain
    a fully qualified file specification (the maximum length is 256
    characters).

221.4  –  Return Values

    x                  The address passed in the buffer argument.
    0                  Indicates an error.

222  –  getopt

    A command-line parser that can be used by applications that
    follow UNIX command-line conventions.

    Format

      #include  <unistd.h> (X/Open, POSIX-1)

      #include  <stdio.h> (X/Open, POSIX-2)

      int getopt  (int argc, char * const argv[], const char *optstring);

      extern  char *optarg;

      extern  int optind, opterr, optopt;

222.1  –  Arguments

 argc

    The argument count as passed to main.

 argv

    The argument array as passed to main.

 optstring

    A string of recognized option characters. If a character is
    followed by a colon, the option takes an argument.

222.2  –  Description

    The variable optind is the index of the next element of the
    argv vector to be processed. It is initialized to 1 by the
    system, and it is updated by getopt when it finishes with each
    element of argv. When an element of argv contains multiple option
    characters, it is unspecified how getopt determines which options
    have already been processed.

    The getopt function returns the next option character (if one is
    found) from argv that matches a character in optstring, if there
    is one that matches. If the option takes an argument, getopt sets
    the variable optarg to point to the option-argument as follows:

    o  If the option was the last character in the string pointed to
       by an element of argv, then optarg contains the next element
       of argv, and optind is incremented by 2. If the resulting
       value of optind is not less than argc, getopt returns an
       error, indicating a missing option-argument.

    o  Otherwise, optarg points to the string following the option
       character in that element of argv, and optind is incremented
       by 1.

    If one of the following is true, getopt returns -1 without
    changing optind:

       argv[optind] is a NULL pointer
       *argv[optind] is not the character -
       argv[optind] points to the string "-"

    If argv[optind] points to the string "- -" getopt returns -1
    after incrementing optind.

    If getopt encounters an option character not contained in
    optstring, the question-mark character (?)  is returned.

    If getopt detects a missing argument, the colon character (:)
    is returned if the first character of optstring is a colon;
    otherwise, a question-mark character is returned.

    In either of the previous two cases, getopt sets the variable
    optopt to the option character that caused the error. If the
    application has not set the variable opterr to 0 and the first
    character of optstring is not a colon, getopt also prints a
    diagnostic message to stderr.

222.3  –  Return Values

    x                  The next option character specified on the
                       command line.

                       A colon is returned if getopt detects a
                       missing argument and the first character of
                       optstring is a colon.

                       A question mark is returned if getopt
                       encounters an option character not in
                       optstring or detects a missing argument and
                       the first character of optstring is not a
                       colon.
    -1                 When all command-line options are parsed.

222.4  –  Example

      The following example shows how you might process the arguments
      for a utility that can take the mutually exclusive options a
      and b and the options f and o, both of which require arguments:

 #include <unistd.h>

 int main (int argc, char *argv[ ])
 {
          int c;
          int bflg, aflg, errflg;
          char *ifile;
          char *ofile;
          extern char *optarg;
          extern int optind, optopt;
          .
          .
          .
          while ((c = getopt(argc, argv, ":abf:o:)) != -1) {

                 switch (c) {
                 case 'a':
                         if (bflg)
                                 errflg++;
                         else
                                 aflg++;
                         break;
                 case 'b':
                         if (aflg)
                                errflg++;
                         else {
                                bflg++;
                                bproc();
                         }

                         break;
                 case 'f':
                         ifile = optarg;
                         break;
                 case 'o':
                         ofile = optarg;
                         break;
                 case ':':      /* -f or -o without operand */
                         fprintf (stderr,
                          "Option -%c requires an operand\n"' optopt);
                         errflg++;
                         break;
                 case '?':
                         fprintf (stderr,
                                 "Unrecognized option -%c\n"' optopt);
                         errflg++;
                 }
          }
          if (errflg) {
                 fprintf (stderr, "usage: ...");
                 exit(2);
          }
          for ( ; optind < argc; optind++)  {
                 if (access(argv[optind], R_OK)) {
          .
          .
          .
 }

      This sample code accepts any of the following as equivalent:

        cmd -ao arg path path
        cmd -a -o arg path path
        cmd -o arg -a path path
        cmd -a -o arg -- path path
        cmd -a -oarg path path
        cmd -aoarg path path

223  –  getpagesize

    Gets the system page size.

    Format

      #include  <unistd.h>

      int getpagesize  (void);

223.1  –  Description

    The getpagesize function returns the number of bytes in a page.
    The system page size is useful for specifying arguments to memory
    management system calls.

    The page size is a system page size and is not necessarily the
    same as the underlying hardware page size.

223.2  –  Return Value

    x                  Always indicates success. Returns the number
                       of bytes in a page.

224  –  getpgid

    Gets the process group ID for a process.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      pid_t getpgid  (pid_t pid);

224.1  –  Argument

 pid

    The process ID for which the group ID is being requested.

224.2  –  Description

    The getpgid function returns the process group ID of the process
    specified by pid. If pid is 0, the getpgid function returns the
    process group ID of the calling process.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

224.3  –  Return Values

    x                  The process group ID of the session leader of
                       the specified process.
    (pid_t)-1          Indicates an error. The function sets errno to
                       one of the following values:

                       o  EPERM - The process specified by pid is
                          not in the same session as the calling
                          process, and the implementation does not
                          allow access to the process group ID of
                          that process from the calling process.

                       o  ESRCH - There is no process with a process
                          ID of pid.

                       o  EINVAL - The value of pid is invalid.

225  –  getpgrp

    Gets the process group ID of the calling process.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      pid_t getpgrp  (void);

225.1  –  Description

    The getpgrp function returns the process group ID of the calling
    process.

    The getpgrp function is always successful, and no return value is
    reserved to indicate an error.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

225.2  –  Return Values

    x                  The process group ID of the calling process.

226  –  getpid

    Returns the process ID of the current process.

    Format

      #include  <unistd.h>

      pid_t getpid  (void);

226.1  –  Return Value

    x                  The process ID of the current process.

227  –  getppid

    Returns the parent process ID of the calling process.

    Format

      #include  <unistd.h>

      pid_t getppid  (void);

227.1  –  Return Values

    x                  The parent process ID.
    0                  Indicates that the calling process does not
                       have a parent process.

228  –  getpwent

    Accesses user entry information in the user database, returning a
    pointer to a passwd structure.

    Format

      #include  <pwd.h>

      struct passwd *getpwent  (void);

228.1  –  Function Variants

    The getpwent function has variants named __32_getpwent and
    __64_getpwent for use with 32-bit and 64-bit pointer sizes,
    respectively.

228.2  –  Description

    The getpwent function returns a pointer to a structure containing
    fields whose values are derived from an entry in the user
    database. Entries in the database are accessed sequentially by
    getpwent. When first called, getpwent returns a pointer to a
    passwd structure containing the first entry in the user database.
    Thereafter, it returns a pointer to a passwd structure containing
    the next entry in the user database. Successive calls can be used
    to search the entire user database.

    The passwd structure is defined in the <pwd.h> header file as
    follows:

    pw_name    The name of the user.
    pw_uid     The ID of the user.
    pw_gid     The group ID of the principle group of the user.
    pw_dir     The home directory of the user.
    pw_shell   The initial program for the user.

    If an end-of-file or an error is encountered on reading, getpwent
    returns a NULL pointer.

    Because getpwent accesses the user authorization file (SYSUAF)
    directly, the process must have appropriate privileges enabled or
    the function will fail.

                                  NOTES

       All information generated by the getpwent function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

       Password file entries that are too long are ignored.

228.3  –  Return Values

    x                  Pointer to a passwd structure, if successful.
    NULL               Indicates an end-of-file or error occurred.
                       The function sets errno to one of the
                       following values:

                       o  EIO - Indicates that an I/O error occurred
                          or the user does not have appropriate
                          privileges enabled to access the user
                          authorization file (SYSUAF).

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

229  –  getpwnam

    The getpwnam function returns information about a user database
    entry for the specified name.

    The getpwnam_r function is a reentrant version of getpwnam.

    Format

      #include  <pwd.h>

      struct passwd *getpwnam  (const char *name); (ISO POSIX-1)

      struct passwd *getpwnam  (const char *name, . . . );
                               (DEC C Extension)

      int getpwnam_r  (const char *name, struct passwd *pwd,
                      char *buffer, size_t bufsize, struct
                      passwd **result); (ISO POSIX-1),
                      (Integrity servers, Alpha)

      int getpwnam_r  (const char *name, struct passwd *pwd,
                      char *buffer, size_t bufsize, struct
                      passwd **result, . . . ); (DEC C Extension),
                      (Integrity servers, Alpha)

229.1  –  Function Variants

    The getpwnam and getpwnam_r functions have variants named __32_
    getpwnam, _getpwnam_r32 and __64_getpwnam, _getpwnam_r64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

229.2  –  Arguments

 name

    The name of the user for which the attributes are to be read.

 pwd

    The address of a passwd structure into which the function writes
    its results.

 buffer

    A working buffer for the result argument that is able to hold the
    largest entry in the passwd structure. Storage referenced by the
    passwd structure is allocated from the memory provided with the
    buffer argument, which is bufsize characters in length.

 bufsize

    The length of the character array that buffer points to.

 result

    Upon successful return, is set to pwd. Upon unsuccessful return,
    the result is set to NULL.

  . . .

    An optional argument that can be either 1 or 0. If you specify
    1, the directory specification is returned in OpenVMS format. If
    you specify 0, the directory specification (pathname) is returned
    in UNIX style format. If you omit this argument, the function
    returns the directory specification according to your current
    command-language interpreter.

229.3  –  Description

    The getpwnam function searches the user database for an entry
    with the specified name. The function returns the first user
    entry in the database with the pw_name member of the passwd
    structure that matches the name argument.

    The passwd structure is defined in the <pwd.h> header file as
    follows:

    pw_name    The user's login name.
    pw_uid     The numerical user ID.
    pw_gid     The numerical group ID.
    pw_dir     The home directory of the user.
    pw_shell   The initial program for the user.

                                   NOTE

       All information generated by the getpwnam function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

    The getpwnam_r function is the reentrant version of getpwnam.
    The getpwnam_r function updates the passwd structure pointed to
    by pwd and stores a pointer to that structure at the location
    pointed to by result. The structure will contain an entry from
    the user database that matches the specified name. Storage
    referenced by the structure is allocated from the memory provided
    with the buffer argument, which is bufsize characters in length.
    The maximum size needed for this buffer can be determined with
    the _SC_GETPW_R_SIZE_MAX parameter of the sysconf function. On
    error or if the requested entry is not found, a NULL pointer is
    returned at the location pointed to by result.

    Applications wishing to check for error situations should set
    errno to 0 before calling getpwnam. If getpwnam returns a NULL
    pointer and errno is nonzero, an error occurred.

229.4  –  Return Values

    x                  getpwnam returns a pointer to a valid passwd
                       structure, if a matching entry is found.
    NULL               getpwnam returns NULL if an error occurred
                       or a the specified entry was not found. errno
                       is set to indicate the error. The getpwnam
                       function may fail if:

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getpwnam.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

    0                  When successful, getpwnam_r returns 0 and
                       stores a pointer to the updated passwd
                       structure at the location pointed to by
                       result.
    0                  When unsuccessful (on error or if the
                       requested entry is not found), getpwnam_r
                       returns 0 and stores a NULL pointer at the
                       location pointed to by result. The getpwnam_r
                       function may fail if:

                       o  ERANGE - Insufficient storage was supplied
                          through buffer and bufsize to contain the
                          data to be referenced by the resulting
                          passwd structure.

229.5  –  Example

      When building a sample program with /def=_USE_STD_STAT, you can
      observe the following:

      o  When the DECC$POSIX_STYLE_UID logical is enabled:

         -  For a system, that supports POSIX style identifiers:

            - getpwnam_r API reads information from the TCP/IP proxy
            database and fills UID and GID with values from the
            TCP/IP proxy database.

            - getgrgid_r API returns gr_name and gr_mem from
            the right's database associated with GID returned by
            getpwnam_r API.

         -  System with no support for POSIX style identifiers,
            getpwnam_r fills GID and UID with SYSGEN parameters as
            "DEFUID" and "DEFGID".

      o  When the DECC$POSIX_STYLE_UID logical is not defined:

         getpwnam function returns information about a user database
         entry for the specified name, which is specified in
         SYSUAF.DAT

        #include <unistd>  // getuid()
        #include <pwd>     // getpwuid_r()
        #include <grp>
        #include <errno.h>
        #include <stdio.h>
        #include <string.h>

        main()
        {

        struct passwd pwd2;
        const unsigned int PWD_BUFF_SIZE = 1024;
        const unsigned int GRP_BUFF_SIZE = 1024;

        struct passwd *p_passwd;
        struct passwd *result;
        struct group *grpresult;
        struct group grp;
        char pwdBuffer[PWD_BUFF_SIZE],*name;
        char grpBuffer[GRP_BUFF_SIZE];
        char buf[PWD_BUFF_SIZE];

        gid_t gid;
        uid_t uid;

        int status;
        p_passwd = getpwnam("user1");
        uid=p_passwd->pw_uid;
        gid=p_passwd->pw_gid;

        printf("User id is %u\n", uid);
        printf("Group id is %u\n", gid);

        status = getpwnam_r("user1", &pwd2, pwdBuffer, PWD_BUFF_SIZE, &result);

        gid = pwd2.pw_gid;

        status = getgrgid_r(gid, &grp, grpBuffer, GRP_BUFF_SIZE, &grpresult);

        gid=grp.gr_gid; name=grp.gr_name;

        strcpy(name,grp.gr_name);

        printf("Group id is %u\n", gid);
        printf("Group name is %s\n", name);

        }

      Running the example program with /def=_USE_STD_STAT produces
      the following result:

      o  When the DECC$POSIX_STYLE_UID logical is NOT enabled, prints
         uid as 11010118 (result of 65536*168+ 70) and gid as 168
         with group name as RTL.

      o  When the DECC$POSIX_STYLE_UID logical is enabled and POSIX
         style identifiers are supported, prints uid as 70, gid as
         168 with group name as FOR_POSIX_TEST (retrieved from TCP/IP
         proxy database).

      o  When the DECC$POSIX_STYLE_UID logical is enabled, but POSIX
         style identifiers are not supported, prints uid as DEFUID,
         gid as DEFGID with group name as invalid buffer.

230  –  getpwuid

    The getpwuid function returns information about a user database
    entry for the specified uid.

    The getpwuid_r function is a reentrant version of getpwuid.

    These functions are OpenVMS Alpha only.

    Format

      #include  <pwd.h>

      struct passwd *getpwuid  (uid_t uid); (ISO POSIX-1)

      struct passwd *getpwuid  (uid_t uid, . . . ); (DEC C Extension)

      int getpwuid_r  (uid_t uid, struct passwd *pwd, char *buffer,
                      size_t bufsize, struct passwd **result);
                     (ISO POSIX-1)

      int getpwuid_r  (uid_t uid, struct passwd *pwd, char *buffer,
                      size_t bufsize, struct passwd **result, . . . );
                      (DEC C Extension)

230.1  –  Function Variants

    The getpwuid and getpwuid_r functions have variants named __32_
    getpwuid, _getpwuid_r32 and __64_getpwuid, _getpwuid_r64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

230.2  –  Arguments

 uid

    The user ID (UID) for which the attributes are to be read.

 pwd

    The location where the retrieved passwd structure is to be
    placed.

 buffer

    A working buffer for the result argument that is able to hold the
    entry in the passwd structure. Storage referenced by the passwd
    structure is allocated from the memory provided with the buffer
    argument, which is bufsize characters in size.

 bufsize

    The length of the character array that buffer points to.

 result

    Upon successful return, result is set to pwd. Upon unsuccessful
    return, result is set to NULL.

  . . .

    An optional argument that can be either 1 or 0. If you specify
    1, the directory specification is returned in OpenVMS format. If
    you specify 0, the directory specification (pathname) is returned
    in UNIX style format. If you omit this argument, the function
    returns the directory specification according to your current
    command-language interpreter.

230.3  –  Description

    The getpwuid function searches the user database for an entry
    with the specified uid. The function returns the first user entry
    in the database with a pw_uid member of the passwd structure that
    matches the uid argument.

    The passwd structure is defined in the <pwd.h> header file as
    follows:

    pw_name    The user's login name.
    pw_uid     The numerical user ID.
    pw_gid     The numerical group ID.
    pw_dir     The home directory of the user.
    pw_shell   The initial program for the user.

                                   NOTE

       All information generated by the getpwuid function is stored
       in a per-thread static area and is overwritten on subsequent
       calls to the function.

    The getpwuid_r function is the reentrant version of getpwuid.
    The getpwuid_r function updates the passwd structure pointed to
    by pwd and stores a pointer to that structure at the location
    pointed to by result. The structure will contain an entry from
    the user database with a matching uid. Storage referenced by the
    structure is allocated from the memory provided with the buffer
    argument, which is bufsize characters in size. The maximum size
    needed for this buffer can be determined with the _SC_GETPW_R_
    SIZE_MAX parameter of the sysconf function. On error or if the
    requested entry is not found, a NULL pointer is returned at the
    location pointed to by result.

    Applications wishing to check for error situations should set
    errno to 0 before calling getpwuid. If getpwuid returns a NULL
    pointer and errno is nonzero, an error occurred.

    See also getuid to know how UIC is represented.

230.4  –  Return Values

    x                  getpwuid returns a pointer to a valid passwd
                       structure, if a matching entry is found.
    NULL               getpwuid returns NULL if an error occurred or
                       a matching entry was not found. errno is set
                       to indicate the error. The getpwuid function
                       may fail if:

                       o  EIO - An I/O error has occurred.

                       o  EINTR - A signal was intercepted during
                          getpwnam.

                       o  EMFILE - OPEN_MAX file descriptors are
                          currently open in the calling process.

                       o  ENFILE - The maximum allowable number of
                          files is currently open in the system.

    0                  When successful, getpwuid_r returns 0 and
                       stores a pointer to the updated passwd
                       structure at the location pointed to by
                       result.
    0                  When unsuccessful (on error or if the
                       requested entry is not found), getpwuid_r
                       returns 0 and stores a NULL pointer at the
                       location pointed to by result. The getpwuid_r
                       function may fail if:

                       o  ERANGE - Insufficient storage was supplied
                          through buffer and bufsize to contain the
                          data to be referenced by the resulting
                          passwd structure.

231  –  gets

    Reads a line from the standard input (stdin).

    Format

      #include  <stdio.h>

      char *gets  (char *str);

231.1  –  Function Variants

    The gets function has variants named _gets32 and _gets64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

231.2  –  Argument

 str

    A pointer to a character string that is large enough to hold the
    information fetched from stdin.

231.3  –  Description

    The new-line character (\n)  that ends the line is replaced by
    the function with an ASCII null character (\0).

    When stdin is opened in record mode, gets treats the end of a
    record the same as a new-line character and, therefore, reads
    up to and including a new-line character or to the end of the
    record.

231.4  –  Return Values

    x                  A pointer to the str argument.
    NULL               Indicates that an error has occurred or that
                       the end-of-file was encountered before a new-
                       line character was encountered. The contents
                       of str are undefined if a read error occurs.

232  –  getsid

    Gets the process group ID of the session leader.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      pid_t getsid  (pid_t pid);

232.1  –  Argument

 pid

    The process ID of the process whose session leader process group
    ID is being requested.

232.2  –  Description

    The getsid function obtains the process group ID of the process
    that is the session leader of the process specified by pid. If
    pid is (pid_t)0, it specifies the calling process.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

232.3  –  Return Values

    x                  The process group ID of the session leader of
                       the specified process.
    (pid_t)-1          Indicates an error. The function sets errno to
                       one of the following values:

                       o  EPERM - The process specified by pid is
                          not in the same session as the calling
                          process, and the implementation does not
                          allow access to the process group ID of
                          the session leader of that process from the
                          calling process.

                       o  ESRCH - There is no process with a process
                          ID of pid.

233  –  [w]getstr

    Get a string from the terminal screen, store it in the variable
    str, and echo it on the specified window. The getstr function
    works on the stdscr window.

    Format

      #include  <curses.h>

      int getstr  (char *str);

      int wgetstr  (WINDOW *win, char *str);

233.1  –  Arguments

 win

    A pointer to the window.

 str

    Must be large enough to hold the character string fetched from
    the window.

233.2  –  Description

    The getstr and wgetstr functions refresh the specified window
    before fetching a string. The new-line terminator is stripped
    from the fetched string. For more information, see the scrollok
    function.

233.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally.

234  –  gettimeofday

    Gets the date and time.

    Format

      #include  <time.h>

      int gettimeofday  (struct timeval *tp, void *tzp);

234.1  –  Arguments

 tp

    Pointer to a timeval structure, defined in the <time.h> header
    file.

 tzp

    A NULL pointer. If this argument is not a NULL pointer, it is
    ignored.

234.2  –  Description

    The gettimeofday function gets the current time (expressed as
    seconds and microseconds) since 00::00 Coordinated Universal
    Time, January 1, 1970. The current time is stored in the timeval
    structure pointed to by the tp argument.

    The tzp argument is intended to hold time-zone information set
    by the kernel. However, because the OpenVMS kernel does not
    set time-zone information, the tzp argument should be NULL. If
    it is not NULL, it is ignored. This function is supported for
    compatibility with BSD programs.

    If the value of the SYS$TIMEZONE_DIFFERENTIAL logical is wrong,
    the function fails with errno set to EINVAL.

234.3  –  Return Values

    0                  Indicates success.
    -1                 An error occurred. errno is set to indicate
                       the error.

235  –  getuid

    With POSIX IDs disabled, this function is equivalent to geteuid
    and returns the member number (in OpenVMS terms) from the user
    identification code (UIC).

    With POSIX IDs enabled, returns the real user ID.

    Format

      #include  <unistd.h>

      uid_t getuid  (void);

235.1  –  Description

    The getuid function can be used with POSIX style identifiers or
    with UIC-based identifiers.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX style IDs disabled (the default), the geteuid and
    getuid functions are equivalent and return the member number from
    the current UIC as follows:

    o  For programs compiled with the _VMS_V6_SOURCE feature-
       test macro or programs that do not include the <unistd.h>
       header file, the getuid and geteuid functions return the
       member number of the OpenVMS UIC. For example, if the UIC
       is [313,31], then the member number, 31, is returned.

    o  For programs compiled without the _VMS_V6_SOURCE feature-
       test macro that do include the <unistd.h> header file, the
       full UIC is returned in decimal after converting the octal
       representation to decimal. For example, if the UIC is [313,
       31] then 13303833 is returned. (13303833 = 25 + 203 * 65536;
       Octal 31 = 25 decimal; Octal 313 = 203 decimal.)

    With POSIX style IDs enabled, geteuid returns the effective user
    ID of the calling process, and getuid returns the real user ID of
    the calling process.

    See also getegid and getgid.

235.2  –  Return Value

    x                  The real user ID (POSIX IDs enabled), or the
                       member number from the current UIC or the full
                       UIC (POSIX IDs disabled).

236  –  getw

    Returns characters from a specified file.

    Format

      #include  <stdio.h>

      int getw  (FILE *file_ptr);

236.1  –  Argument

 file_ptr

    A pointer to the file to be accessed.

236.2  –  Description

    The getw function returns the next four characters from the
    specified input file as an int.

236.3  –  Return Values

    x                  The next four characters, in an int.
    EOF                Indicates that the end-of-file was encountered
                       during the retrieval of any of the four
                       characters and all four characters were
                       lost. Since EOF is an acceptable integer,
                       use feof and ferror to check the success of
                       the function.

237  –  getwc

    Reads the next character from a specified file, and converts it
    to a wide-character code.

    Format

      #include  <wchar.h>

      wint_t getwc  (FILE *file_ptr);

237.1  –  Argument

 file_ptr

    A pointer to the file to be accessed.

237.2  –  Description

    Since getwc is implemented as a macro, a file pointer argument
    with side effects (for example getwc (*f++)) might be evaluated
    incorrectly. In such a case, use the fgetwc function instead. See
    the fgetwc function.

237.3  –  Return Values

    n                  The returned character.
    WEOF               Indicates the end-of-file or an error. If an
                       error occurs, the function sets errno. For a
                       list of the values set by this function, see
                       fgetwc.

238  –  getwchar

    Reads a single wide character from the standard input (stdin).

    Format

      #include  <wchar.h>

      wint_t getwchar  (void);

238.1  –  Description

    The getwchar function is identical to fgetwc(stdin).

238.2  –  Return Values

    x                  The next character from stdin, converted to
                       wint_t.
    WEOF               Indicates the end-of-file or an error. If an
                       error occurs, the function sets errno. For a
                       list of the values set by this function, see
                       fgetwc.

239  –  getyx

    Puts the (y,x) coordinates of the current cursor position on win
    in the variables y and x.

    Format

      #include  <curses.h>

      getyx  (WINDOW *win, int y, int x);

239.1  –  Arguments

 win

    Must be a pointer to the window.

 y

    Must be a valid lvalue.

 x

    Must be a valid lvalue.

240  –  glob

    Returns a list of existing files for a user supplied pathname
    (with optional wildcards).

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <glob.h>

      int glob  (const char *pattern, int flags, int (*errfunc)(const
                char *epath, int eerrno), glob_t *pglob);

240.1  –  Function Variants

    The glob function has variants named _glob32 and _glob64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

240.2  –  Arguments

 pattern

    The pattern string to match with accessible files and pathnames.
    This pattern can have wildcards.

 flags

    Controls the customizable behavior of the glob function.

 errfunc

    An optional function that, if specified, is called when the glob
    function detects an error condition, or if not specified, is
    NULL.

 epath

    First argument of the optional errfunc function, epath is the
    pathname that failed because a directory could not be opened or
    read.

 eerrno

    Second argument of the optional errfunc function, eerrno is the
    errno value from a failure specified by the epath argument as set
    by the opendir, readdir, or stat functions.

 pglob

    Pointer to a glob_t structure that returns the matching
    accessible existing filenames. The structure is allocated by the
    caller. The array of structures containing the located filenames
    that match the pattern argument are stored by the glob function
    into the structure. The last entry is a NULL pointer.

    The structure type glob_t is defined in the <glob.h> header file
    and includes at least the following members:

    size_t   gl_pathc    //Count of paths matched by pattern.
    char **  gl_pathv    //Pointer to a list of matched pathnames.
    size_t   gl_offs     //Slots to reserve at the beginning of gl_pathv.

240.3  –  Description

    The glob function constructs a list of accessible files that
    match the pattern argument.

    The glob function operates in one of two modes: UNIX mode or
    OpenVMS mode.

    You can select UNIX mode explicitly by enabling the feature
    logical DECC$GLOB_UNIX_STYLE, which is disabled by default.

    The glob function defaults to OpenVMS mode unless one of the
    following conditions is met (in which case glob uses UNIX mode):

    o  The DECC$GLOB_UNIX_STYLE is enabled.

    o  The DECC$FILENAME_UNIX_ONLY feature logical is enabled.

    o  The glob function checks the specified pattern for pathname
       indications, such as directory delimiters, and determines it
       to be a UNIX style pathname.

    OpenVMS mode

    This mode allows an OpenVMS programmer to give an OpenVMS style
    pattern to the glob function and get expected OpenVMS style
    output. The OpenVMS style pattern is what a user would expect
    from DCL commands or as input to the SYS$PARSE and SYS$SEARCH
    system routines.

    In this mode, you can use any of the expected OpenVMS wildcards
    (see the OpenVMS documentation for additional information).

    OpenVMS mode does not support the UNIX wildcard ?, or [] pattern
    matching. OpenVMS users expect [] to be available as directory
    delimiters.

    Some additional behavior differences between OpenVMS mode and
    UNIX mode:

    o  OpenVMS mode outputs full file specifications, not relative
       ones, as in UNIX mode.

    o  The GLOB_MARK flag is ignored in OpenVMS mode because it
       is not meaningful to append a slash (/)  to a directory on
       OpenVMS.

    For example:

    Sample pattern input      Sample output

    [.SUBDIR1]A.TXT           DEV:[DIR.SUBDIR1]A.TXT;1
    [.SUB*]%.*                DEV:[DIR.SUBDIR1]A.TXT;1

    UNIX mode

    You can enable this mode explicitly with:

    $ DEFINE DECC$GLOB_UNIX_STYLE ENABLE

    UNIX mode is also enabled if the DECC$FILENAME_UNIX_ONLY feature
    logical is set, or if the glob function determines that the
    specified pattern looks like a UNIX style pathname.

    In UNIX mode, the glob function follows the X/Open specification
    where possible.

    For example:

    Sample pattern input      Sample output

    ./a/b/c                   ./a/b/c
    ./?/b/*                   ./a/b/c
    [a-c]                     c

    Standard Description

    The glob function matches all accessible pathnames against this
    pattern and develops a list of all pathnames that match. To
    have access to a pathname, the glob function requires search
    permission on every component of a pathname except the last, and
    read permission on each directory of any filename component of
    the pattern argument.

    The glob function stores the number of matched pathnames and a
    pointer to a list of pointers to pathnames in the pglob argument.
    The pathnames are sorted, based on the setting of the LC_COLLATE
    category in the current locale. The first pointer after the last
    pathname is NULL. If the pattern does not match any pathnames,
    the returned number of matched pathnames is 0.

    It is the caller's responsibility to create the structure pointed
    to by the pglob argument. The glob function allocates other space
    as needed. The globfree function frees any space associated with
    the pglob argument as a result of a previous call to the glob
    function.

    The flags argument is used to control the behavior of the glob
    function. The flags value is the bitwise inclusive OR (|) of any
    of the following constants, which are defined in the <glob.h>
    header file:

    GLOB_APPEND  Appends pathnames located with this call to any
                 pathnames previously located.
    GLOB_DOOFFS  Uses the gl_offs structure to specify the number
                 of NULL pointers to add to the beginning of the gl_
                 pathv component of the pglob argument.
    GLOB_ERR     Causes the glob function to return when it
                 encounters a directory that it cannot open or
                 read. If the GLOB_ERR flag is not set, the glob
                 function continues to find matches if it encounters
                 a directory that it cannot open or read.
    GLOB_MARK    Specifies that each pathname that is a directory
                 should have a slash (/)  appended. GLOB_MARK is
                 ignored in OpenVMS mode because it is not meaningful
                 to append a slash to a directory on OpenVMS systems.
    GLOB_        If the pattern argument does not match any pathname,
    NOCHECK      then the glob function returns a list consisting
                 only of the pattern argument, and the number of
                 matched pathnames is 1.
    GLOB_        If the GLOB_NOESCAPE flag is set, a backslash (\)
    NOESCAPE     cannot be used to escape metacharacters.

    The GLOB_APPEND flag can be used to append a new set of pathnames
    to those found in a previous call to the glob function. The
    following rules apply when two or more calls to the glob function
    are made with the same value of the pglob argument, and without
    intervening calls to the globfree function:

    o  If the application sets the GLOB_DOOFFS flag in the first call
       to the glob function, then it is also set in the second call,
       and the value of the gl_offs field of the pglob argument is
       not modified between the calls.

    o  If the application did not set the GLOB_DOOFFS flag in the
       first call to the glob function, then it is not set in the
       second call.

    o  After the second call, pglob->gl_pathv points to a list
       containing the following:

       -  Zero or more NULLs, as specified by the GLOB_DOOFFS flag
          and pglob->gl_offs.

       -  Pointers to the pathnames that were in the pglob->gl_pathv
          list before the call, in the same order as after the first
          call to the glob function.

       -  Pointers to the new pathnames generated by the second call,
          in the specified order.

    o  The count returned in the pglob->gl_offs argument is the total
       number of pathnames from the two calls.

    o  The application should not modify the pglob->gl_pathc or
       pglob->gl_pathv fields between the two calls.

    On successful completion, the glob function returns a value of 0
    (zero). The pglob->gl_pathc field returns the number of matched
    pathnames and the pglob->gl_pathv field contains a pointer to
    a NULL-terminated list of matched and sorted pathnames. If the
    number of matched pathnames in the pglob->gl_pathc argument is 0
    (zero), the pointer in the pglob->gl_pathv argument is undefined.

    If the glob function terminates because of an error, the function
    returns one of the nonzero constants GLOB_ABORTED, GLOB_NOMATCH,
    or GLOB_NOSPACE, defined in the <glob.h> header file. In this
    case, the pglob argument values are still set as defined above.

    If, during the search, a directory is encountered that cannot
    be opened or read and the errfunc argument value is not NULL,
    the glob function calls errfunc with the two arguments epath and
    eerno:

       epath-The pathname that failed because a directory could not
       be opened or read.
       eerno-The errno value from a failure specified by the epath
       argument as set by the opendir, readdir, or stat functions.

    If errfunc is called and returns nonzero, or if the GLOB_ERR flag
    is set in flags, the glob function stops the scan and returns
    GLOB_ABORTED after setting the pglob argument to reflect the
    pathnames already scanned. If GLOB_ERR is not set and either
    errfunc is NULL or errfunc returns zero, the error is ignored.

    No errno values are returned.

    See also globfree, readdir, and stat.

240.4  –  Return Values

    0                  Successful completion.
    GLOB_ABORTED       The scan was stopped because GLOB_ERROR was
                       set or errfunc returned a nonzero value.
    GLOB_NOMATCH       The pattern does not match any existing
                       pathname, and GLOB_NOCHECK was not set in
                       flags.
    GLOB_NOSPACE       An attempt to allocate memory failed.

241  –  globfree

    Frees any space associated with the pglob argument resulting from
    a previous call to the glob function.

    Format

      #include  <glob.h>

      void globfree  (glob_t *pglob);

241.1  –  Function Variants

    The globfree function has variants named _globfree32 and _
    globfree64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

241.2  –  Argument

 pglob

    Pointer to a previously allocated glob_t structure.

241.3  –  Description

    The globfree function frees any space associated with the pglob
    argument resulting from a previous call to the glob function. The
    globfree function returns no value.

242  –  gmtime

    Converts time units to the broken-down UTC time.

    Format

      #include  <time.h>

      struct tm *gmtime  (const time_t *timer);

      struct tm *gmtime_r  (const time_t *timer, struct tm *result);
                           (ISO POSIX-1)

242.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to
    the gmtime_r function that is equivalent to the behavior before
    OpenVMS Version 7.0.

242.2  –  Arguments

 timer

    Points to a variable that specifies a time value in seconds since
    the Epoch.

 result

    A pointer to a tm structure where the result is stored.

    The tm structure is defined in the <time.h> header, and is also
    shown in tm Structure in the description of localtime.

242.3  –  Description

    The gmtime and gmtime_r functions convert the time (in seconds
    since the Epoch) pointed to by timer into a broken-down time,
    expressed as Coordinated Universal Time (UTC), and store it in a
    tm structure.

    The difference between the gmtime_r and gmtime functions is that
    the former puts the result into a user-specified tm structure
    where the result is stored. The latter puts the result into
    thread-specific static memory allocated by the C RTL,
    and which is overwritten by subsequent calls to gmtime; you must
    make a copy if you want to save it.

    On success, gmtime returns a pointer to the tm structure; gmtime_
    r returns its second argument. On failure, these functions return
    the NULL pointer.

                                   NOTE

       Generally speaking, UTC-based time functions can affect in-
       memory time-zone information, which is processwide data.
       However, if the system time zone remains the same during
       the execution of the application (which is the common case)
       and the cache of timezone files is enabled (which is the
       default), then the _r variant of the time functions asctime_
       r, ctime_r, gmtime_r and localtime_r, is both thread-safe
       and AST-reentrant.

       If, however, the system time zone can change during the
       execution of the application or the cache of timezone files
       is not enabled, then both variants of the UTC-based time
       functions belong to the third class of functions, which are
       neither thread-safe nor AST-reentrant.

242.4  –  Return Values

    x                  Pointer to a tm structure.
    NULL               Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The timer argument is NULL.

243  –  gsignal

    Generates a specified software signal, which invokes the action
    routine established by a signal, ssignal, or sigvec function.

    Format

      #include  <signal.h>

      int gsignal  (int sig [, int sigcode]);

243.1  –  Arguments

 sig

    The signal to be generated.

 sigcode

    An optional signal code. For example, signal SIGFPE-the
    arithmetic trap signal-has 10 different codes, each representing
    a different type of arithmetic trap.

    The signal codes can be represented by mnemonics or numbers. The
    arithmetic trap codes are represented by the numbers 1 to 10, but
    the SIGILL codes are represented by the numbers 0 to 2. The code
    values are defined in the <signal.h> header file.

243.2  –  Description

    Calling the gsignal function has one of the following results:

    o  If gsignal specifies a sig argument that is outside the range
       defined in the <signal.h> header file, then gsignal returns 0
       and sets errno to EINVAL.

    o  If signal, ssignal, or sigvec establishes SIG_DFL (default
       action) for the signal, then gsignal does not return. The
       image is exited with the OpenVMS error code corresponding to
       the signal.

    o  If signal, ssignal, or sigvec establishes SIG_IGN (ignore
       signal) as the action for the signal, then gsignal returns its
       argument, sig.

    o  signal, ssignal, or sigvec must be used to establish an action
       routine for the signal. That function is called and its return
       value is returned by gsignal.

    See the Error and Signal Handling chapter of the C RTL Reference
    Manual for more information.

    See also raise, signal, ssignal, and sigvec.

243.3  –  Return Values

    0                  Indicates a sig argument that is outside the
                       range defined in the <signal.h> header file;
                       errno is set to EINVAL.
    sig                Indicates that SIG_IGN (ignore signal) has
                       been established as the action for the signal.
    x                  Indicates that signal, ssignal, or sigvec has
                       established an action function for the signal.
                       That function is called, and its return value
                       is returned by gsignal.

244  –  hypot

    Returns the length of the hypotenuse of a right triangle.

    Format

      #include  <math.h>

      double hypot  (double x, double y);

      float hypotf  (float x, float y); (Integrity servers, Alpha)

      long double hypotl  (long double x, long double y);
                          (Integrity servers, Alpha)

244.1  –  Arguments

 x

    A real value.

 y

    A real value.

244.2  –  Description

    The hypot functions return the length of the hypotenuse of a
    right triangle, where x and y represent the perpendicular sides
    of the triangle. The length is calculated as:

    sqrt(x2 + y2)

    On overflow, the return value is undefined, and errno is set to
    ERANGE.

244.3  –  Return Values

    x                  The length of the hypotenuse.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    0                  Underflow occurred; errno is set to ERANGE.
    NaN                x or y is NaN; errno is set to EDOM.

245  –  iconv

    Converts characters coded in one codeset to characters coded in
    another codeset.

    Format

      #include  <iconv.h>

      size_t iconv  (iconv_t cd, const char **inbuf, size_t
                    *inbytesleft, char **outbuf, size_t
                    *outbytesleft);

245.1  –  Arguments

 cd

    A conversion descriptor. This is returned by a successful call to
    iconv_open.

 inbuf

    A pointer to a variable that points to the first character in the
    input buffer.

 inbytesleft

    Initially, this argument is a pointer to a variable that
    indicates the number of bytes to the end of the input buffer
    (inbuf). When the conversion is completed, the variable indicates
    the number of bytes in inbuf not converted.

 outbuf

    A pointer to a variable that points to the first available byte
    in the output buffer. The output buffer contains the converted
    characters.

 outbytesleft

    Initially, this argument is a pointer to a variable that
    indicates the number of bytes to the end of the output buffer
    (outbuf). When the conversion is completed, the variable
    indicates the number of bytes left in outbuf.

245.2  –  Description

    The iconv function converts characters in the buffer pointed
    to by inbuf to characters in another code set. The resulting
    characters are stored in the buffer pointed to by outbuf. The
    conversion type is specified by the conversion descriptor cd.
    This descriptor is returned from a successful call to iconv_open.

    If an invalid character is found in the input buffer, the
    conversion stops after the last successful conversion. The
    variable pointed to by inbytesleft is updated to reflect the
    number of bytes in the input buffer that are not converted. The
    variable pointed to by outbytesleft is updated to reflect the
    number of bytes remaining in the output buffer.

245.3  –  Return Values

    x                  Number of nonidentical conversions performed.
                       Indicates successful conversion. In most
                       cases, 0 is returned.
    (size_t) -1        Indicates an error condition. The function
                       sets errno to one of the following:

                       o  EBADF - The cd argument is not a valid
                          conversion descriptor.

                       o  EILSEQ - The conversion stops when an
                          invalid character detected.

                       o  E2BIG - The conversion stops because of
                          insufficient space in the output buffer.

                       o  EINVAL - The conversion stops because of
                          an incomplete character at the end of the
                          input buffer.

246  –  iconv_close

    Deallocates a specified conversion descriptor and the resources
    allocated to the descriptor.

    Format

      #include  <iconv.h>

      int iconv_close  (iconv_t cd);

246.1  –  Argument

 cd

    The conversion descriptor to be deallocated. A conversion
    descriptor is returned by a successful call to iconv_open.

246.2  –  Return Values

    0                  Indicates that the conversion descriptor was
                       successfully deallocated.
    -1                 Indicates an error occurred. The function sets
                       errno to one of the following:

                       o  EBADF - The cd argument is not a valid
                          conversion descriptor.

                       o  EVMSERR - Nontranslatable OpenVMS error
                          occur. vaxc$errno contains the VMS error
                          code.

247  –  iconv_open

    Allocates a conversion descriptor for a specified codeset
    conversion.

    Format

      #include  <iconv.h>

      iconv_t iconv_open  (const char *tocode, const char *fromcode);

247.1  –  Arguments

 tocode

    The name of the codeset to which characters are converted.

 fromcode

    The name of the source codeset. See the "Developing International
    Software" chapter of the VSI C RTL Reference Manual for
    information on obtaining a list of currently available codesets
    or for details on adding new codesets.

247.2  –  Return Values

    x                  A conversion descriptor. Indicates the call
                       was successful. This descriptor is used in
                       subsequent calls to iconv
    (iconv_t) -1       Indicates an error occurred. The function sets
                       errno to one of the following:

                       o  EMFILE - The process does not have enough
                          I/O channels to open a file.

                       o  ENOMEM - Insufficient space is available.

                       o  EINVAL - The conversion specified by
                          fromcode and tocode is not supported.

                       o  EVMSERR - Nontranslatable OpenVMS error
                          occur. vaxc$errno contains the OpenVMS
                          error code. A value of SS$_BADCHKSUM in
                          vaxc$errno indicates that a conversion
                          table file was found, but its contents is
                          corrupted. A value of SS$_IDMISMATCH in
                          vaxc$errno indicates that the conversion
                          table file version does not match the
                          version of the C Run-Time Library.

247.3  –  Example

        #include <stdio.h>
        #include <iconv.h>
        #include <errno.h>

        int main()
        {
          /* Declare variables to be used                      */

          char fromcodeset[30];
          char tocodeset[30];
          int iconv_opened;
          iconv_t iconv_struct;       /* Iconv descriptor      */

          /* Initialize variables                              */

          sprintf(fromcodeset, "DECHANYU");
          sprintf(tocodeset, "EUCTW");
          iconv_opened = FALSE;

          /* Attempt to create a conversion descriptor for the */
          /* codesets specified. If the return value from      */
          /* iconv_open is -1 then an error has occurred.      */
          /*  Check the value of errno.                        */

          if ((iconv_struct = iconv_open(tocodeset, fromcodeset))

              /* Check the value of errno                      */

              switch (errno) {
              case EMFILE:
              case ENFILE:
                  printf("Too many iconv conversion files open\n");
                  break;

              case ENOMEM:
                  printf("Not enough memory\n");
                  break;

              case EINVAL:
                  printf("Unsupported conversion\n");
                  break;

              default:
                  printf("Unexpected error from iconv_open\n");
                  break;
             }
          }
          else

              /* Successfully allocated a conversion descriptor   */

              iconv_opened = TRUE;

          /*  Was a conversion descriptor allocated               */

           if (iconv_opened) {

              /* Attempt to deallocate the conversion descriptor. */
              /* If iconv_close returns -1 then an error has      */
              /* occurred.                                        */

              if (iconv_close(iconv_struct) == -1) {

                  /* An error occurred. Check the value of errno  */

                  switch (errno) {
                  case EBADF:
                      printf("Conversion descriptor is invalid\n");
                      break;
                  default:
                      printf("Unexpected error from iconv_close\n");
                      break;
                  }
              }
          }
          return (EXIT_FAILURE);
        }

248  –  ilogb

    Returns the exponent part of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      int ilogb  (double x);

      int ilogbf  (float x);

      int ilogbl  (long double x);

248.1  –  Argument

 x

    A real value.

248.2  –  Description

    The ilogb functions return the exponent part of their argument
    x. Formally, the return value is the integral part of logr|x| as
    a signed integral value, for nonzero x, where r is the radix of
    the machine's floating-point arithmetic, which is the value of
    FLT_RADIX defined in <float.h>.

248.3  –  Return Values

    n                  Upon success, the exponent part of x as a
                       signed integer value. These functions are
                       equivalent to calling the corresponding logb
                       function and casting the returned value to
                       type int.

249  –  [w]inch

    Return the character at the current cursor position on the
    specified window without making changes to the window. The inch
    function acts on the stdscr window.

    Format

      #include  <curses.h>

      char inch();

      char winch  (WINDOW *win);

249.1  –  Argument

 win

    A pointer to the window.

249.2  –  Return Values

    x                  The returned character.
    ERR                Indicates an input error.

250  –  index

    Searches for a character in a string.

    Format

      #include  <strings.h>

      char *index  (const char *s, int c);

250.1  –  Function Variants

    The index function has variants named _index32 and _index64 for
    use with 32-bit and 64-bit pointer sizes, respectively.

250.2  –  Arguments

 s

    The string to search.

 c

    The character to search for.

250.3  –  Description

    The index function is identical to the strchr function, and is
    provided for compatibility with some UNIX implementations.

251  –  initscr

    Initializes the terminal-type data and all screen functions. You
    must call initscr before using any of the curses functions.

    Format

      #include  <curses.h>

      void initscr  (void);

251.1  –  Description

    The OpenVMS Curses version of the initscr function clears the
    screen before doing the initialization. The BSD-based Curses
    version does not.

252  –  initstate

    Initializes random-number generators.

    Format

      #include  <stdlib.h>

      char *initstate  (unsigned int seed, char *state, int size);

252.1  –  Arguments

 seed

    An initial seed value.

 state

    Pointer to an array of state information.

 size

    The size of the state information array.

252.2  –  Description

    The initstate function initializes random-number generators. It
    lets you initialize, for future use, a state array passed as an
    argument. The size, in bytes, of the state array is used by the
    initstate function to decide how sophisticated a random-number
    generator to use; the larger the state array, the more random the
    numbers.

    Values for the amount of state information are 8, 32, 64, 128,
    and 256 bytes. Amounts less than 8 bytes generate an error, while
    other amounts are rounded down to the nearest known value.

    The seed argument specifies a starting point for the random-
    number sequence and provides for restarting at the same point.
    The initstate function returns a pointer to the previous state
    information array.

    Once you initialize a state, the setstate function allows rapid
    switching between states. The array defined by the state argument
    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:

    o  Use the initstate function with the desired seed argument,
       state array, and size of the array.

    o  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 setstate, srandom, and random.

252.3  –  Return Values

    x                  A pointer to the previous state array
                       information.
    0                  Indicates an error. Call made with less than 8
                       bytes of state information. Further specified
                       in the global errno.

253  –  [w]insch

    Insert a character at the current cursor position in the
    specified window. The insch function acts on the stdscr window.

    Format

      #include  <curses.h>

      int insch  (char ch);

      int winsch  (WINDOW *win, char ch);

253.1  –  Arguments

 win

    A pointer to the window.

 ch

    The character to be inserted.

253.2  –  Description

    After the character is inserted, each character on the line
    shifts to the right, and the last character in the line is
    deleted. For more information, see the scrollok function.

253.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally.

254  –  [w]insertln

    Insert a line above the line containing the current cursor
    position. The insertln function acts on the stdscr window.

    Format

      #include  <curses.h>

      int insertln();

      int winsertln  (WINDOW *win);

254.1  –  Argument

 win

    A pointer to the window.

254.2  –  Description

    The current line and every line below it shifts down, and the
    bottom line disappears. The inserted line is blank and the
    current (y,x) coordinates remain the same. For more information,
    see the scrollok function.

254.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally.

255  –  [w]insstr

    Insert a string at the current cursor position in the specified
    window. The insstr function acts on the stdscr window.

    Format

      #include  <curses.h>

      int insstr  (char *str);

      int winsstr  (WINDOW *win, char *str);

255.1  –  Arguments

 win

    A pointer to the window.

 str

    A pointer to the string to be inserted.

255.2  –  Description

    Each character after the string shifts to the right, and the last
    character disappears. These functions are specific to VSI C
    for OpenVMS Systems and are not portable.

255.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally. For more information, see
                       the scrollok function.

256  –  isalnum

    Indicates if a character is classed either as alphabetic or as a
    digit in the program's current locale.

    Format

      #include  <ctype.h>

      int isalnum  (int character);

256.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

256.2  –  Return Values

    nonzero            If alphanumeric.
    0                  If not alphanumeric.

257  –  isalpha

    Indicates if a character is classed as an alphabetic character in
    the program's current locale.

    Format

      #include  <ctype.h>

      int isalpha  (int character);

257.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

257.2  –  Return Values

    nonzero            If alphabetic.
    0                  If not alphabetic.

258  –  isapipe

    Indicates if a specified file descriptor is associated with a
    pipe.

    Format

      #include  <unixio.h>

      int isapipe  (int file_desc);

258.1  –  Argument

 file_desc

    A file descriptor.

258.2  –  Description

    For more information about pipes, see the "Subprocess Functions"
    chapter of the VSI C RTL Reference Manual.

258.3  –  Return Values

    1                  Indicates an association with a pipe.
    0                  Indicates no association with a pipe.
    -1                 Indicates an error (for example, if the file
                       descriptor is not associated with an open
                       file).

259  –  isascii

    Indicates if a character is an ASCII character.

    Format

      #include  <ctype.h>

      int isascii  (int character);

259.1  –  Argument

 character

    An object of type char.

259.2  –  Return Values

    nonzero            If ASCII.
    0                  If not ASCII.

260  –  isatty

    Indicates if a specified file descriptor is associated with a
    terminal.

    Format

      #include  <unistd.h>

      int isatty  (int file_desc);

260.1  –  Argument

 file_desc

    A file descriptor.

260.2  –  Return Values

    1                  If the file descriptor is associated with a
                       terminal.
    0                  If the file descriptor is not associated with
                       a terminal.
    -1                 Indicates an error (for example, if the file
                       descriptor is not associated with an open
                       file).

261  –  iscntrl

    Indicates if a character is classed as a control character in the
    program's current locale.

    Format

      #include  <ctype.h>

      int iscntrl  (int character);

261.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

261.2  –  Return Values

    nonzero            If a control character.
    0                  If not a control character.

262  –  isdigit

    Indicates if a character is classed as a digit in the program's
    current locale.

    Format

      #include  <ctype.h>

      int isdigit  (int character);

262.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

262.2  –  Return Values

    nonzero            If a decimal digit.
    0                  If not a decimal digit.

263  –  isgraph

    Indicates if a character is classed as a graphic character in the
    program's current locale.

    Format

      #include  <ctype.h>

      int isgraph  (int character);

263.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

263.2  –  Return Values

    nonzero            If a graphic character.
    0                  If not a graphic character.

264  –  islower

    Indicates if a character is classed as a lowercase character in
    the program's current locale.

    Format

      #include  <ctype.h>

      int islower  (int character);

264.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

264.2  –  Return Values

    nonzero            If a lowercase alphabetic character.
    0                  If not a lowercase alphabetic character.

265  –  isnan

    Test for a NaN. Returns 1 if the argument is NaN; 0 if not.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      int isnan  (double x);

      int isnanf  (float x);

      int isnanl  (long double x);

265.1  –  Argument

 x

    A real value.

265.2  –  Description

    The isnan functions return the integer value 1 (TRUE) if x is NaN
    (the IEEE floating point reserved not-a-number value); otherwise,
    they return the value 0 (FALSE).

266  –  isprint

    Indicates if a character is classed as a printing character in
    the program's current locale.

    Format

      #include  <ctype.h>

      int isprint  (int character);

266.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

266.2  –  Return Values

    nonzero            If a printing character.
    0                  If not a printing character.

267  –  ispunct

    Indicates if a character is classed as a punctuation character in
    the program's current locale.

    Format

      #include  <ctype.h>

      int ispunct  (int character);

267.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

267.2  –  Return Values

    nonzero            If a punctuation character.
    0                  If not a punctuation character.

268  –  isspace

    Indicates if a character is classed as white space in the
    program's current locale; that is, if it is an ASCII space, tab
    (horizontal or vertical), carriage-return, form-feed, or new-line
    character.

    Format

      #include  <ctype.h>

      int isspace  (int character);

268.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

268.2  –  Return Values

    nonzero            If a white-space character.
    0                  If not a white-space character.

269  –  isupper

    Indicates if a character is classed as an uppercase character in
    the program's current locale.

    Format

      #include  <ctype.h>

      int isupper  (int character);

269.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char or must equal the value of the
    macro EOF. If it has any other value, the behavior is undefined.

269.2  –  Return Values

    nonzero            If an uppercase alphabetic character.
    0                  If not an uppercase alphabetic character.

270  –  iswalnum

    Indicates if a wide character is classed either as alphabetic or
    as a digit in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswalnum  (wint_t wc);

270.1  –  Argument

 wc

    An object of type wint_t. The value of character must be
    representable as a wchar_t in the current locale, or must equal
    the value of the macro WEOF. If it has any other value, the
    behavior is undefined.

270.2  –  Return Values

    nonzero            If alphanumeric.
    0                  If not alphanumeric.

271  –  iswalpha

    Indicates if a wide character is classed as an alphabetic
    character in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswalpha  (wint_t wc);

271.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

271.2  –  Return Values

    nonzero            If alphabetic.
    0                  If not alphabetic.

272  –  iswcntrl

    Indicates if a wide character is classed as a control character
    in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswcntrl  (wint_t wc);

272.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

272.2  –  Return Values

    nonzero            If a control character.
    0                  If not a control character.

273  –  iswctype

    Indicates if a wide character has a specified property.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswctype  (wint_t wc, wctype_t wc_prop);

273.1  –  Arguments

 wc

    An object of type wint_t. The value of wc must be representable
    as a valid wide-character code in the current locale, or must
    equal the value of the macro WEOF. If it has any other value, the
    behavior is undefined.

 wc_prop

    A valid property name in the current locale. This is set up by
    calling the wctype function.

273.2  –  Description

    The iswctype function tests whether wc has the character-class
    property wc_prop. Set wc_prop by calling the wctype function.

    See also wctype.

273.3  –  Return Values

    nonzero            If the character has the property wc_prop.
    0                  If the character does not have the property
                       wc_prop.

273.4  –  Example

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

        /* This test will set up the "upper" character class using      */
        /* wctype() and then verify whether the characters 'a' and 'A'  */
        /* are members of this class                                    */

        #include <stdlib.h>

        main()
        {

            wchar_t w_char1,
                    w_char2;
            wctype_t ret_val;

            char *char1 = "a";
            char *char2 = "A";

            ret_val = wctype("upper");

            /* Convert char1 to wide-character format - w_char1 */

            if (mbtowc(&w_char1, char1, 1) == -1) {
               perror("mbtowc");
                exit(EXIT_FAILURE);
            }

            if (iswctype((wint_t) w_char1, ret_val))
                printf("[%C] is a member of the character class upper\n",
                        w_char1);
            else
             printf("[%C] is not a member of the character class upper\n",
                      w_char1);

            /* Convert char2 to wide-character format - w_char2 */

            if (mbtowc(&w_char2, char2, 1) == -1) {
                perror("mbtowc");
                exit(EXIT_FAILURE);
            }

            if (iswctype((wint_t) w_char2, ret_val))
                printf("[%C] is a member of the character class upper\n",
                        w_char2);
            else
             printf("[%C] is not a member of the character class upper\n",
                        w_char2);
        }

      Running the example program produces the following result:

        [a] is not a member of the character class upper
        [A] is a member of the character class upper

274  –  iswdigit

    Indicates if a wide character is classed as a digit in the
    program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswdigit  (wint_t wc);

274.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

274.2  –  Return Values

    nonzero            If a decimal digit.
    0                  If not a decimal digit.

275  –  iswgraph

    Indicates if a wide character is classed as a graphic character
    in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswgraph  (wint_t wc);

275.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

275.2  –  Return Values

    nonzero            If a graphic character.
    0                  If not a graphic character.

276  –  iswlower

    Indicates if a wide character is classed as a lowercase character
    in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswlower  (wint_t wc);

276.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

276.2  –  Return Values

    nonzero            If a lowercase character.
    0                  If not a lowercase character.

277  –  iswprint

    Indicates if a wide character is classed as a printing character
    in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswprint  (wint_t wc);

277.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

277.2  –  Return Values

    nonzero            If a printing character.
    0                  If not a printing character.

278  –  iswpunct

    Indicates if a wide character is classed as a punctuation
    character in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswpunct  (wint_t wc);

278.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

278.2  –  Return Values

    nonzero            If a punctuation character.
    0                  If not a punctuation character.

279  –  iswspace

    Indicates if a wide character is classed as a space character in
    the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswspace  (wint_t wc);

279.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

279.2  –  Return Values

    nonzero            If a white-space character.
    0                  If not a white-space character.

280  –  iswupper

    Indicates if a wide character is classed as an uppercase
    character in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswupper  (wint_t wc);

280.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

280.2  –  Return Values

    nonzero            If an uppercase character.
    0                  If not an uppercase character.

281  –  iswxdigit

    Indicates if a wide character is a hexadecimal digit (0 to 9, A
    to F, or a to f) in the program's current locale.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int iswxdigit  (wint_t wc);

281.1  –  Argument

 wc

    An object of type wint_t. The value of wc must be representable
    as a wchar_t in the current locale, or must equal the value
    of the macro WEOF. If it has any other value, the behavior is
    undefined.

281.2  –  Return Values

    nonzero            If a hexadecimal digit.
    0                  If not a hexadecimal digit.

282  –  isxdigit

    Indicates if a character is a hexadecimal digit (0 to 9, A to F,
    or a to f) in the program's current locale.

    Format

      #include  <ctype.h>

      int isxdigit  (int character);

282.1  –  Argument

 character

    An object of type int. The value of character must be
    representable as an unsigned char in the current locale, or must
    equal the value of the macro EOF. If it has any other value, the
    behavior is undefined.

282.2  –  Return Values

    nonzero            If a hexadecimal digit.
    0                  If not a hexadecimal digit.

283  –  j0,j1,jn

    Compute Bessel functions of the first kind.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double j0  (double x);

      float j0f  (float x);

      long double j0l  (long double x);

      double j1  (double x);

      float j1f  (float x);

      long double j1l  (long double x);

      double jn  (int n, double x);

      float jnf  (int n, float x);

      long double jnl  (int n, long double x);

283.1  –  Arguments

 x

    A real value.

 n

    An integer.

283.2  –  Description

    The j0 functions return the value of the Bessel function of the
    first kind of order 0.

    The j1 functions return the value of the Bessel function of the
    first kind of order 1.

    The jn functions return the value of the Bessel function of the
    first kind of order n.

    The j1 and jn functions can result in an underflow as x gets
    small. The largest value of x for which this occurs is a function
    of n.

283.3  –  Return Values

    x                  The relevant Bessel value of x of the first
                       kind.
    0                  The value of the x argument is too large, or
                       underflow occurred; errno is set to ERANGE.
    NaN                x is NaN; errno is set to EDOM.

284  –  jrand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit signed, long integers.

    Format

      #include  <stdlib.h>

      long int jrand48  (unsigned short int xsubi[3]);

284.1  –  Argument

 xsubi

    An array of three short ints that form a 48-bit integer when
    concatenated together.

284.2  –  Description

    The jrand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    The function returns signed long integers uniformly distributed
    over the range of y values, such that -231 

    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 jrand48 function requires that the calling program pass an
    array as the xsubi argument, which for the first call must be
    initialized to the initial value of the pseudorandom-number
    sequence. Unlike the drand48 function, it is not necessary to
    call an initialization function prior to the first call.

    By using different arguments, jrand48 allows separate modules
    of a large program to generate several independent sequences of
    pseudorandom numbers. For example, the sequence of numbers that
    one module generates does not depend upon how many times the
    function is called by other modules.

284.3  –  Return Value

    n                  Signed, long integers uniformly distributed
                       over the range -231 

285  –  kill

    Sends a signal to the process specified by a process ID.

    Format

      #include  <signal.h>

      int kill  (int pid, int sig);

285.1  –  Arguments

 pid

    The process ID.

 sig

    The signal code.

285.2  –  Description

    The kill function is restricted to C and C++ programs that
    include the main function.

    The kill function sends a signal to a process, as if the process
    had called raise. If the signal is not trapped or ignored by the
    target program, the program exits.

    OpenVMS VAX and Alpha implement different rules about what
    process you are allowed to send signals to. A program always has
    privileges to send a signal to a child started with vfork/exec.
    For other processes, the results are determined by the OpenVMS
    security model for your system.

    Because of an OpenVMS restriction, the kill function cannot
    deliver a signal to a target process that runs an image installed
    with privileges.

    Unless you have system privileges, the sending and receiving
    processes must have the same user identification code (UIC).

    On OpenVMS systems before Version 7.0, kill treats a signal value
    of 0 as if SIGKILL were specified.

    For OpenVMS Version 7.0 and higher systems, if you include
    <stdlib.h> and compile with the _POSIX_EXIT feature-test macro
    set, then:

    o  If the signal value is 0, kill validates the process ID but
       does not send any signals.

    o  If the process ID is not valid, kill returns -1 and sets errno
       to ESRCH.

285.3  –  Return Values

    0                  Indicates that kill was successfully queued.
    -1                 Indicates errors. The receiving process may
                       have a different UIC and you are not a system
                       user, or the receiving process does not exist.

286  –  l64a

    Converts a long integer to a character string.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      char *l64a  (long l);

286.1  –  Argument

 l

    A long integer that is to be converted to a character string.

286.2  –  Description

    The a64l and l64a functions are used to maintain numbers stored
    in base-64 ASCII characters:

    o  a64l converts a character string to a long integer.

    o  l64a converts a long integer to a character string.

    Each character used to store a long integer represents a numeric
    value from 0 through 63. Up to six characters can be used to
    represent a long integer.

    The characters are translated as follows:

    o  A period (.)  represents 0.

    o  A slash (/)  represents 1.

    o  The numbers 0 through 9 represent 2 through 11.

    o  Uppercase letters A through Z represent 12 through 37.

    o  Lowercase letters a through z represent 38 through 63.

    The l64a function takes a long integer and returns a pointer to a
    corresponding base-64 notation of the least significant 32 bits.

    The value returned by l64a is a pointer to a thread-specific
    buffer whose contents are overwritten on subsequent calls from
    the same

    See also a64l.

286.3  –  Return Value

    x                  Upon successful completion, a pointer to
                       the corresponding base-64 ASCII character-
                       string notation. If the l parameter is 0, l64a
                       returns a pointer to an empty string.

287  –  labs

    Returns the absolute value of an integer as a long int.

    Format

      #include  <stdlib.h>

      long int labs  (long int j);

287.1  –  Argument

 j

    A value of type long int.

288  –  lchown

    Changes the user and group ownership of the specified file.

    Format

      #include  <unistd.h>

      int lchown  (const char *file_path, uid_t file_owner, gid_t
                  file_group);

288.1  –  Arguments

 file_path

    The name of the file for which you want to change the owner and
    group IDs.

 file_owner

    The new user ID for the file.

 file_group

    The new group ID for the file.

288.2  –  Description

    The lchown function changes the owner and/or group of the
    specified file (file_path). If the file is a symbolic link, the
    owner of the symbolic link is modified (in contrast to chown
    which would modify the file that the symbolic link points to).

    See also symlink, unlink, readlink, realpath, and lstat.

288.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. errno is set to any errno
                       value returned by chown.

289  –  lcong48

    Initializes a 48-bit uniformly distributed pseudorandom-number
    sequence.

    Format

      #include  <stdlib.h>

      void lcong48  (unsigned short int param[7]);

289.1  –  Argument

 param

    An array that in turn specifies the initial Xi, the multiplier
    value a, and the addend value c.

289.2  –  Description

    The lcong48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    You can use lcong48 to initialize the random number generator
    before you call any of the following functions:

       drand48
       lrand48
       mrand48

    The lcong48 function specifies the initial Xi value, the
    multiplier value a, and the addend value c. The param array
    elements specify the following:

    param[0-   Xi
    2]
    param[3-   Multiplier a value
    5]
    param[6]   16-bit addend c value

    After lcong48 has been called, a subsequent call to either
    srand48 or seed48 restores the standard a and c as specified
    previously.

    The lcong48 function does not return a value.

    See also drand48, lrand48, mrand48, srand48, and seed48.

290  –  ldexp

    Returns its first argument multiplied by 2 raised to the power of
    its second argument; that is, x(2n).

    Format

      #include  <math.h>

      double ldexp  (double x, int n);

      float ldexp  (float x, int n); (Integrity servers, Alpha)

      long double ldexp  (long double x, int n);
                         (Integrity servers, Alpha)

290.1  –  Arguments

 x

    A base value of type double, float, or long double that is to be
    multiplied by 2n.

 n

    The integer exponent value to which 2 is raised.

290.2  –  Return Values

    x(2n)              The first argument multiplied by 2 raised to

                       the power of the second argument.
    0                  Underflow occurred; errno is set to ERANGE.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    NaN                x is NaN; errno is set to EDOM.

291  –  ldiv

    Returns the quotient and the remainder after the division of its
    arguments.

    Format

      #include  <stdlib.h>

      ldiv_t ldiv  (long int numer, long int denom);

291.1  –  Arguments

 numer

    A numerator of type long int.

 denom

    A denominator of type long int.

291.2  –  Description

    The type ldiv_t is defined in the <stdlib.h> header file as
    follows:

    typedef struct
            {
                 long   quot, rem;
            } ldiv_t;

    See also div.

292  –  leaveok

    Signals Curses to leave the cursor at the current coordinates
    after an update to the window.

    Format

      #include  <curses.h>

      leaveok  (WINDOW *win, bool boolf);

292.1  –  Arguments

 win

    A pointer to the window.

 boolf

    A Boolean TRUE or FALSE value. If boolf is TRUE, the cursor
    remains in place after the last update and the coordinate setting
    on win changes accordingly. If boolf is FALSE, the cursor moves
    to the currently specified (y,x) coordinates of win.

292.2  –  Description

    The leaveok function defaults to moving the cursor to the current
    coordinates of win. The bool type is defined in the <curses.h>
    header file as follows:

    #define bool int

293  –  lgamma

    Computes the logarithm of the gamma function.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double lgamma  (double x);

      float lgammaf  (float x);

      long double lgammal  (long double x);

293.1  –  Argument

 x

    A real number. x cannot be 0, a negative integer, or Infinity.

293.2  –  Description

    The lgamma functions return the logarithm of the absolute value
    of gamma of x, or ln(|G(x)|), where G is the gamma function.

    The sign of gamma of x is returned in the external integer
    variable signgam. The x argument cannot be 0, a negative integer,
    or Infinity.

293.3  –  Return Values

    x                  The logarithmic gamma of the x argument.
    -HUGE_VAL          The x argument is a negative integer; errno is
                       set to ERANGE.
    NaN                The x argument is NaN; errno is set to EDOM.
    0                  Underflow occurred; errno is set to ERANGE.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.

294  –  link

    Creates a new link (directory entry) for an existing file. This
    function is supported only on volumes that have hard link counts
    enabled.

    Format

      #include  <unistd.h>

      link  (const char *path1, const char *path2);

294.1  –  Arguments

 path1

    Pointer to a pathname naming an existing file.

 path2

    Pointer to a pathname naming the new directory entry to be
    created.

294.2  –  Description

    The link function atomically creates a new link for the existing
    file, and the link count of the file is incremented by one.

    The link function can be used on directory files.

    If link fails, no link is created and the link count of the file
    remains unchanged.

294.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EEXIST - The link named by path2 exists.

                       o  EFTYPE - Wildcards appear in either path1
                          or path2.

                       o  EINVAL - One or both arguments specify a
                          syntactically invalid pathname.

                       o  ENAMETOOLONG - The length of path1 or path2
                          exceeds PATH_MAX, or a pathname component
                          is longer than NAME_MAX.

                       o  EXDEV - The link named by path2 and
                          the filenamed by path1 are on different
                          devices.

295  –  localeconv

    Sets the members of a structure of type struct lconv with values
    appropriate for formatting numeric quantities according to the
    rules of the current locale.

    Format

      #include  <locale.h>

      struct lconv *localeconv  (void);

295.1  –  Description

    The localeconv function returns a pointer to the lconv structure
    defined in the <locale.h> header file. This structure should
    not be modified by the program. It is overwritten by calls to
    localeconv, or by calls to the setlocale function that change the
    LC_NUMERIC, LC_MONETARY, or LC_ALL categories.

    The members of the structure are:

    Member                 Description

    char *decimal_point    The radix character.
    char *thousands_sep    The character used to separate groups of
                           digits.
    char *grouping         The string that defines how digits are
                           grouped in nonmonetary values.
    char *int_curr_symbol  The international currency symbol.
    char *currency_symbol  The local currency symbol.
    char *mon_decimal_     The radix character used to format
    point                  monetary values.
    char *mon_thousands_   The character used to separate groups of
    sep                    digits in monetary values.
    char *mon_grouping     The string that defines how digits are
                           grouped in a monetary value.
    char *positive_sign    The string used to indicate a nonnegative
                           monetary value.
    char *negative_sign    The string used to indicate a negative
                           monetary value.
    char int_frac_digits   The number of digits displayed after
                           the radix character in a monetary value
                           formatted with the international currency
                           symbol.
    char frac_digits       The number of digits displayed after the
                           radix character in a monetary value.
    char p_cs_precedes     For positive monetary values, this is
                           set to 1 if the local or international
                           currency symbol precedes the number, and
                           it is set to 0 if the symbol succeeds the
                           number.
    char p_sep_by_space    For positive monetary values, this is
                           set to 0 if there is no space between the
                           currency symbol and the number. It is set
                           to 1 if there is a space, and it is set to
                           2 if there is a space between the symbol
                           and the sign string.
    char n_cs_precedes     For negative monetary values, this is
                           set to 1 if the local or international
                           currency symbol precedes the number, and
                           it is set to 0 if the symbol succeeds the
                           number.
    char n_sep_by_space    For negative monetary values, this is
                           set to 0 if there is no space between the
                           currency symbol and the number. It is set
                           to 1 if there is a space, and it is set to
                           2 if there is a space between the symbol
                           and the sign string.
    char p_sign_posn       An integer used to indicate where the
                           positive_sign string should be placed for
                           a nonnegative monetary quantity.
    char n_sign_posn       An integer used to indicate where the
                           negative_sign string should be placed for
                           a negative monetary quantity.

    Members of the structure of type char* are pointers to strings,
    any of which (except decimal_point) can point to "", indicating
    that the associated value is not available in the current locale
    or is zero length. Members of the structure of type char are
    positive numbers, any of which can be CHAR_MAX, indicating that
    the associated value is not available in the current locale.
    CHAR_MAX is defined in the <limits.h> header file.

    Be aware that the value of the CHAR_MAX macro in the <limits.h>
    header depends on whether the program is compiled with the
    /UNSIGNED_CHAR qualifier:

    o  Use the CHAR_MAX macro as an indicator of a nonavailable value
       in the current locale only if the program is compiled without
       /UNSIGNED_CHAR (/NOUNSIGNED_CHAR is the default).

    o  If the program is compiled with /UNSIGNED_CHAR, use the SCHAR_
       MAX macro instead of the CHAR_MAX macro.

    In /NOUNSIGNED_CHAR mode, the values of CHAR_MAX and SCHAR_MAX
    are the same; therefore, comparison with SCHAR_MAX gives correct
    results regardless of the /[NO]UNSIGNED_CHAR mode used.

    The members grouping and mon_grouping point to a string that
    defines the size of each group of digits when formatting a
    number. Each group size is separated by a semicolon (;). For
    example, if grouping points to the string 5;3 and the thousands_
    sep character is a comma (,), the number 123450000 would be
    formatted as 1,234,50000.

    The elements of grouping and mon_grouping are interpreted as
    follows:

    Value      Interpretation

    CHAR_MAX   No further grouping is performed.
    0          The previous element is to be used repeatedly for the
               remainder of the digits.
    other      The integer value is the number of digits that comprise
               the current group. The next element is examined to
               determine the size of the next group of digits before
               the current group.

    The values of p_sign_posn and n_sign_posn are interpreted as
    follows:

    Value    Interpretation

    0        Parentheses surround the number and currency symbol.
    1        The sign string precedes the number and currency symbol.
    2        The sign string succeeds the number and currency symbol.
    3        The sign string immediately precedes the number and
             currency symbol.
    4        The sign string immediately succeeds the number and
             currency symbol.

295.2  –  Return Value

    x                  Pointer to the lconv structure.

295.3  –  Example

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

        /* The following test program will set up the British English   */
        /* locale, and then extract the International Currency symbol   */
        /* and the International Fractional Digits fields for this      */
        /* locale and print them.                                       */

        int main()
        {
            /* Declare variables                                        */

            char *return_val;
            struct lconv *lconv_ptr;

            /* Load a locale                                            */

            return_val = (char *) setlocale(LC_ALL, "en_GB.iso8859-1");

            /* Did the locale load successfully?                        */

            if (return_val == NULL) {

                /* It failed to load the locale                         */
               printf("ERROR : The locale is unknown");
                exit(EXIT_FAILURE);
            }

            /*  Get the lconv structure from the locale                 */

            lconv_ptr = (struct lconv *) localeconv();

            /* Compare the international currency symbol string with an */
            /* empty string. If they are equal, then the international  */
            /* currency symbol is not defined in the locale.            */

            if (strcmp(lconv_ptr->int_curr_symbol, "")) {
                printf("International Currency Symbol = %s\n",
                       lconv_ptr->int_curr_symbol);
            }
            else {
                printf("International Currency Symbol =");
                printf("[Not available in this locale]\n");
            }

            /* Compare International Fractional Digits with CHAR_MAX.   */
            /* If they are equal, then International Fractional Digits  */
            /* are not defined in this locale.                          */

            if ((unsigned char) (lconv_ptr->int_frac_digits) != CHAR_MAX) {
                printf("International Fractional Digits = %d\n",
                       lconv_ptr->int_frac_digits);
            }
            else {
                printf("International Fractional Digits =");
                printf("[Not available in this locale]\n");
            }
        }

      Running the example program produces the following result:

        International Currency Symbol = GBP
        International Fractional Digits = 2

296  –  localtime

    Convert a time value to broken-down local time.

    Format

      #include  <time.h>

      struct tm *localtime  (const time_t *timer);

      struct tm *localtime_r  (const time_t *timer, struct tm *result);
                                   (ISO POSIX-1)

296.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    localtime_r function that is equivalent to the behavior before
    OpenVMS Version 7.0.

296.2  –  Arguments

 timer

    A pointer to a time in seconds since the Epoch. You can generate
    this time by using the time function or you can supply a time.

 result

    A pointer to a tm structure where the result is stored. The tm
    structure is defined in the <time.h> header file, and is also
    shown in tm Structure.

296.3  –  Description

    The localtime and localtime_r functions convert the time (in
    seconds since the Epoch) pointed to by timer into a broken-down
    time, expressed as a local time, and store it in a tm structure.

    The difference between the localtime_r and localtime functions
    is that the former stores the result into a user-specified tm
    structure. The latter stores the result into thread-specific
    static memory allocated by the C RTL, and which is
    overwritten by subsequent calls to localtime; you must make a
    copy if you want to save it.

    On success, localtime returns a pointer to the tm structure;
    localtime_r returns its second argument. On failure, these
    functions return the NULL pointer.

    The tm structure is defined in the <time.h> header file and
    described in tm Structure.

    Table REF-4 tm Structure

    int tm_sec;      Seconds after the minute (0-60)
    int tm_min;      Minutes after the hour (0-59)
    int tm_hour;     Hours since midnight (0-23)
    int tm_mday;     Day of the month (1-31)
    int tm_mon;      Months since January (1-11)
    int tm_year;     Years since 1900
    int tm_wday;     Days since Sunday (0-6)
    int tm_yday;     Days since January 1 (0-365)
    int tm_isdst;    Daylight Savings Time flag

                     o  tm_isdst = 0 for Standard Time

                     o  tm_isdst = 1 for Daylight Time

    long tm_gmtoff;  Seconds east of Greenwich (negative values
                     indicate seconds west of Greenwich)
    char *tm_zone;   Time zone string, for example "GMT"

    The type time_t is defined in the <time.h> header file as
    follows:

    typedef long int time_t

                                   NOTE

       Generally speaking, UTC-based time functions can affect in-
       memory time-zone information, which is processwide data.
       However, if the system time zone remains the same during
       the execution of the application (which is the common case)
       and the cache of timezone files is enabled (which is the
       default), then the _r variant of the time functions asctime_
       r, ctime_r, gmtime_r and localtime_r, is both thread-safe
       and AST-reentrant.

       If, however, the system time zone can change during the
       execution of the application or the cache of timezone files
       is not enabled, then both variants of the UTC-based time
       functions belong to the third class of functions, which are
       neither thread-safe nor AST-reentrant.

296.4  –  Return Values

    x                  Pointer to a tm structure.
    NULL               Indicates failure.

297  –  log,log2,log10

    Return the logarithm of their arguments.

    Format

      #include  <math.h>

      double log  (double x);

      float logf  (float x); (Integrity servers, Alpha)

      long double logl  (long double x); (Integrity servers, Alpha)

      double log2  (double x); (Integrity servers, Alpha)

      float log2f  (float x); (Integrity servers, Alpha)

      long double log2l  (long double x); (Integrity servers, Alpha)

      double log10  (double x);

      float log10f  (float x); (Integrity servers, Alpha)

      long double log10l  (long double x);
                          (Integrity servers, Alpha)

297.1  –  Argument

 x

    A real number.

297.2  –  Description

    The log functions compute the natural (base e) logarithm of x.

    The log2 functions compute the base 2 logarithm of x.

    The log10 functions compute the common (base 10) logarithm of x.

297.3  –  Return Values

    x                  The logarithm of the argument (in the
                       appropriate base).
    -HUGE_VAL          x is 0 (errno is set to ERANGE), or x is
                       negative (errno is set to EDOM).
    NaN                x is NaN; errno is set to EDOM.

298  –  log1p

    Computes ln(1+y) accurately.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double log1p  (double y);

      float log1pf  (float y);

      long double log1pl  (long double y);

298.1  –  Argument

 y

    A real number greater than -1.

298.2  –  Description

    The log1p functions compute ln(1+y) accurately, even for tiny y.

298.3  –  Return Values

    x                  The natural logarithm of (1+y).
    -HUGE_VAL          y is less than -1 (errno is set to EDOM), or y
    NaN                y is NaN; errno is set to EDOM.

299  –  logb

    Returns the radix-independent exponent of the argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double logb  (double x);

      float logbf  (float x);

      long double logbl  (long double x);

299.1  –  Argument

 x

    A nonzero, real number.

299.2  –  Description

    The logb functions return the exponent of x, which is the
    integral part of log(2)|x|, as a signed floating-point value,
    for nonzero x.

299.3  –  Return Values

    x                  The exponent of x.
    -HUGE_VAL          x = 0.0; errno is set to EDOM.
    +Infinity          x is +Infinity or -Infinity.
    NaN                y is NaN; errno is set to EDOM.

300  –  longjmp

    Provides a way to transfer control from a nested series of
    function invocations back to a predefined point without returning
    normally; that is, by not using a series of return statements.
    The longjmp function restores the context of the environment
    buffer.

    Format

      #include  <setjmp.h>

      void longjmp  (jmp_buf env, int value);

300.1  –  Arguments

 env

    The environment buffer, which must be an array of integers long
    enough to hold the register context of the calling function.
    The type jmp_buf is defined in the <setjmp.h> header file. The
    contents of the general-purpose registers, including the program
    counter (PC), are stored in the buffer.

 value

    Passed from longjmp to setjmp, and then becomes the subsequent
    return value of the setjmp call. If value is passed as 0, it is
    converted to 1.

300.2  –  Description

    When setjmp is first called, it returns the value 0. If longjmp
    is then called, naming the same environment as the call to
    setjmp, control is returned to the setjmp call as if it had
    returned normally a second time. The return value of setjmp in
    this second return is the value you supply in the longjmp call.
    To preserve the true value of setjmp, the function calling setjmp
    must not be called again until the associated longjmp is called.

    The setjmp function preserves the hardware general-purpose
    registers, and the longjmp function restores them. After a
    longjmp, all variables have their values as of the time of the
    longjmp except for local automatic variables not marked volatile.
    These variables have indeterminate values.

    The setjmp and longjmp functions rely on the OpenVMS condition-
    handling facility to effect a nonlocal goto with a signal
    handler. The longjmp function is implemented by generating a
    C RTL specified signal and allowing the OpenVMS condition-
    handling facility to unwind back to the desired destination.
    The C RTL must be in control of signal handling for any
    VSI C image.

    For VSI C to be in control of signal handling, you must
    establish all exception handlers through a call to the
    VAXC$ESTABLISH function (rather than LIB$ESTABLISH).

                                   NOTE

       The C RTL provides nonstandard decc$setjmp and decc$fast_
       longjmp functions for Alpha and Integrity server systems.
       To use these nonstandard functions instead of the standard
       ones, a program must be compiled with the __FAST_SETJMP or
       __UNIX_SETJMP macros defined.

       Unlike the standard longjmp function, the decc$fast_longjmp
       function does not convert its second argument from 0 to 1.
       After a call to decc$fast_longjmp, a corresponding setjmp
       function returns with the exact value of the second argument
       specified in the decc$fast_longjmp call.

300.3  –  Restrictions

    You cannot invoke the longjmp function from an OpenVMS condition
    handler. However, you may invoke longjmp from a signal handler
    that has been established for any signal supported by the
    C RTL, subject to the following nesting restrictions:

    o  The longjmp function will not work if invoked from nested
       signal handlers. The result of the longjmp function, when
       invoked from a signal handler that has been entered as a
       result of an exception generated in another signal handler,
       is undefined.

    o  Do not invoke the setjmp function from a signal handler unless
       the associated longjmp is to be issued before the handling of
       that signal is completed.

    o  Do not invoke the longjmp function from within an exit handler
       (established with atexit or SYS$DCLEXH). Exit handlers are
       invoked after image tear-down, so the destination address of
       the longjmp no longer exists.

    o  Invoking longjmp from within a signal handler to return to
       the main thread of execution might leave your program in
       an inconsistent state. Possible side effects include the
       inability to perform I/O or to receive any more UNIX signals.

301  –  longname

    Returns the full name of the terminal.

    Format

      #include  <curses.h>

      void longname  (char *termbuf, char *name);

301.1  –  Function Variants

    The longname function has variants named _longname32 and
    _longname64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

301.2  –  Arguments

 termbuf

    A string containing the name of the terminal.

 name

    A character-string buffer with a minimum length of 64 characters.

301.3  –  Description

    The terminal name is in a readable format so that you can
    double-check to be sure that Curses has correctly identified
    your terminal. The dummy argument termbuf is required for UNIX
    software compatibility and serves no function in the OpenVMS
    environment. If portability is a concern, you must write a set
    of dummy routines to perform the functionality provided by the
    database termcap in the UNIX system environment.

302  –  lrand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit signed long integers.

    Format

      #include  <stdlib.h>

      long int lrand48  (void);

302.1  –  Description

    The lrand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    It returns nonnegative, long integers uniformly distributed over
    the range of y values such that 0 

    Before you call the lrand48 function use either srand48, seed48,
    or lcong48 to initialize the random-number generator. You must
    initialize prior to invoking the lrand48 function, because it
    stores the last 48-bit Xi generated into an internal buffer.
    (Although it is not recommended, constant default initializer
    values are supplied automatically if the drand48, lrand48,
    or mrand48 functions are called without first 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 value returned by the lrand48 function is computed by
    first generating the next 48-bit Xi in the sequence. Then the
    appropriate bits, according to the type of data item to be
    returned, are copied from the high-order (most significant) bits
    of Xi and transformed into the returned value.

    See also drand48, lcong48, mrand48, seed48, and srand48.

302.2  –  Return Value

    n                  Signed nonnegative long integers uniformly
                       distributed over the range 0 

303  –  lrint

    Rounds to the nearest integer value, rounding according to the
    current rounding direction.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      long lrint  (double x);

      long lrintf  (float x);

      long lrintl  (long double x);

303.1  –  Argument

 x

    A real value.

303.2  –  Description

    The lrint functions return the rounded integer value of x,
    rounded according to the current rounding direction.

303.3  –  Return Values

    n                  Upon success, the rounded integer value.

304  –  lround

    Rounds to the nearest integer value, rounding halfway cases away
    from zero regardless of the current rounding direction.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      long lround  (double x);

      long lroundf  (float x);

      long lroundl  (long double x);

304.1  –  Argument

 x

    A real value.

304.2  –  Description

    The lround functions return the rounded integer value of x, with
    halfway cases rounded away from zero regardless of the current
    rounding direction.

304.3  –  Return Values

    n                  Upon success, the rounded integer value.

305  –  lseek

    Positions a file to an arbitrary byte position and returns the
    new position.

    Format

      #include  <unistd.h>

      off_t lseek  (int file_desc, off_t offset, int direction);

305.1  –  Arguments

 file_desc

    An integer returned by open, creat, dup, or dup2.

 offset

    The offset, specified in bytes. The off_t data type is either a
    32-bit or a 64-bit integer. The 64-bit interface allows for file
    sizes greater than 2 GB, and can be selected at compile time by
    defining the _LARGEFILE feature-test macro as follows:

    CC/DEFINE=_LARGEFILE

 direction

    An integer indicating whether the offset is to be measured
    forward from the beginning of the file (direction=SEEK_SET),
    forward from the current position (direction=SEEK_CUR), or
    backward from the end of the file (direction=SEEK_END).

305.2  –  Description

    The lseek function can position a fixed-length record-access
    file with no carriage control or a stream-access file on any
    byte offset, but can position all other files only on record
    boundaries.

    The available Standard I/O functions position a record file at
    its first byte, at the end-of-file, or on a record boundary.
    Therefore, the arguments given to lseek must specify either
    the beginning or end of the file, a 0 offset from the current
    position (an arbitrary record boundary), or the position returned
    by a previous, valid lseek call.

    This function returns the new file position as an integer of type
    off_t which, like the offset argument, is either a 64-bit integer
    if _LARGEFILE is defined, or a 32-bit integer if not.

    For a portable way to position an arbitrary byte location with
    any type of file, see the fgetpos and fsetpos functions.

                                 CAUTION

       If, while accessing a stream file, you seek beyond the
       end-of-file and then write to the file, the lseek function
       creates a hole by filling the skipped bytes with zeros.

       In general, for record files, lseek should only be directed
       to an absolute position that was returned by a previous
       valid call to lseek or to the beginning or end of a file.
       If a call to lseek does not satisfy these conditions, the
       results are unpredictable.

    See also open, creat, dup, dup2, and fseek.

305.3  –  Return Values

    x                  The new file position.
    -1                 Indicates that the file descriptor is
                       undefined, or a seek was attempted before
                       the beginning of the file.

306  –  lstat

    Retrieves information about the specified file.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sys/stat.h>

      int lstat  (const char *restrict file_path, struct stat
                 *restrict user_buffer);

306.1  –  Arguments

 file_path

    The name of the file for which you want to retrieve information.

 user_buffer

    The stat structure in which information is returned.

306.2  –  Description

    The lstat function retrieves information about the specified file
    (file_path). If the file is a symbolic link, information about
    the link itself is returned (in contrast to stat, which returns
    information about the file that the symbolic link points to).

    See also symlink, unlink, readlink, realpath, and lchown.

306.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. errno is set to any errno
                       value returned by stat.

307  –  lwait

    Waits for I/O on a specific file to complete.

    Format

      #include  <stdio.h>

      int lwait  (int fd);

307.1  –  Argument

 fd

    A file descriptor corresponding to an open file.

307.2  –  Description

    The lwait function is used primarily to wait for completion of
    pending asynchronous I/O.

307.3  –  Return Values

    0                  Indicates successful completion.
    -1                 Indicates an error.

308  –  malloc

    Allocates an area of memory. These functions are AST-reentrant.

    Format

      #include  <stdlib.h>

      void *malloc  (size_t size);

308.1  –  Function Variants

    The malloc function has variants named _malloc32 and _malloc64
    for use with 32-bit and 64-bit pointer sizes, respectively.

308.2  –  Argument

 size

    The total number of bytes to be allocated.

308.3  –  Description

    The malloc function allocates a contiguous area of memory whose
    size, in bytes, is supplied as an argument. The space is not
    initialized.

                                   NOTE

       The malloc routines call the system routine LIB$VM_MALLOC.
       Because LIB$VM_MALLOC is designed as a general-purpose
       routine to allocate memory, it is called upon in a wide
       array of scenarios to allocate and reallocate blocks
       efficiently. The most common usage is the management of
       smaller blocks of memory, and the most important aspect of
       memory allocation under these circumstances is efficiency.

       LIB$VM_MALLOC makes use of its own free space to satisfy
       requests, once the heap storage is consumed by splitting
       large blocks and merging adjacent blocks. Memory can still
       become fragmented, leaving unused blocks. Once heap storage
       is consumed, LIB$VM_MALLOC manages its own free space and
       merged blocks to satisfy requests, but varying sizes of
       memory allocations can cause blocks to be left unused.

       Because LIB$VM_MALLOC cannot be made to satisfy all
       situations in the best possible manner, perform your own
       memory management if you have special memory usage needs.
       This assures the best use of memory for your particular
       application.

       The OpenVMS Programming Concepts Manual explains the several
       memory allocation routines that are available. They are
       grouped into three levels of hierarchy:

       1. At the highest level are the RTL Heap Management Routines
          LIB$GET_VM and LIB$FREE_VM, which provide a mechanism
          for allocating and freeing blocks of memory of arbitrary
          size. Also at this level are the routines based on the
          concept of zones, such as LIB$CREATE_VM_ZONE, and so on.

       2. At the next level are the RTL Page Management routines
          LIB$GET_VM_PAGE and LIB$FREE_VM_PAGE, which allocate a
          specified number of contiguous pages.

       3. At the lowest level are the Memory Management System
          Services, such as $CRETVA and $EXPREG, that provide
          extensive control over address space allocation. At this
          level, you must manage the allocation precisely.

    The maximum amount of memory allocated at once is limited to
    0xFFFFD000.

308.4  –  Return Values

    x                  The address of the first byte, which
                       is aligned on a quadword boundary
                       (Alpha only) or an octaword boundary
                       (Integrity servers(ONLY)) .
    NULL               Indicates that the function is unable to
                       allocate enough memory. errno is set to
                       ENOMEM.

309  –  mblen

    Determines the number of bytes comprising a multibyte character.

    Format

      #include  <stdlib.h>

      int mblen  (const char *s, size_t n);

309.1  –  Arguments

 s

    A pointer to the multibyte character.

 n

    The maximum number of bytes that comprise the multibyte
    character.

309.2  –  Description

    If the character is n bytes or less, the mblen function returns
    the number of bytes comprising the multibyte character pointed
    to by s. If the character is greater than n bytes, the function
    returns -1 to indicate an error.

    This function is affected by the LC_CTYPE category of the
    program's current locale.

309.3  –  Return Values

    x                  The number of bytes that comprise the
                       multibyte character, if the next n or fewer
                       bytes form a valid character.
    0                  If s is NULL or a pointer to the NULL
                       character.
    -1                 Indicates an error. The function sets errno to
                       EILSEQ - Invalid character detected.

310  –  mbrlen

    Determines the number of bytes comprising a multibyte character.

    Format

      #include  <wchar.h>

      size_t mbrlen  (const char *s, size_t n, mbstate_t *ps);

310.1  –  Arguments

 s

    A pointer to a multibyte character.

 n

    The maximum number of bytes that comprise the multibyte
    character.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

310.2  –  Description

    The mbrlen function is equivalent to the call:

        mbrtowc(NULL, s, n, ps != NULL ? ps : &internal)

    Where internal is the mbstate_t object for the mbrlen function.

    If the multibyte character pointed to by s is of n bytes or less,
    the function returns the number of bytes comprising the character
    (including any shift sequences).

    If either an encoding error occurs or the next n bytes contribute
    to an incomplete but potentially valid multibyte character, the
    function returns -1 or -2, respectively.

    See also mbrtowc.

310.3  –  Return Values

    x                  The number of bytes comprising the multibyte
                       character.
    0                  Indicates that s is a NULL pointer or a
                       pointer to a null byte.
    -1                 Indicates an encoding error, in which case
                       the next n or fewer bytes do not contribute
                       to a complete and valid multibyte character.
                       errno is set to EILSEQ; the conversion state
                       is undefined.
    -2                 Indicates an incomplete but potentially valid
                       multibyte character (all n bytes have been
                       processed).

311  –  mbrtowc

    Converts a multibyte character to its wide-character
    representation.

    Format

      #include  <wchar.h>

      size_t mbrtowc  (wchar_t *pwc, const char *s, size_t n,
                      mbstate_t *ps);

311.1  –  Arguments

 pwc

    A pointer to the resulting wide-character code.

 s

    A pointer to a multibyte character.

 n

    The maximum number of bytes that comprise the multibyte
    character.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

311.2  –  Description

    If s is a NULL pointer, mbrtowc is equivalent to the call:

        mbrtowc(NULL, "", 1, ps)

    In this case, the values of pwc and n are ignored.

    If s is not a NULL pointer, mbrtowc inspects at most n bytes
    beginning with the byte pointed to by s to determine the
    number of bytes needed to complete the next multibyte character
    (including any shift sequences).

    If the function determines that the next multibyte character
    is completed, it determines the value of the corresponding wide
    character and then, if pwc is not a NULL pointer, stores that
    value in the object pointed to by pwc. If the corresponding
    wide character is the null wide character, the resulting state
    described is the initial conversion state.

    If mbrtowc is called as a counting function, which means that pwc
    is a NULL pointer and s is neither a NULL pointer nor a pointer
    to a null byte, the value of the internal mbstate_t object will
    remain unchanged.

311.3  –  Return Values

    x                  The number of bytes comprising the multibyte
                       character.
    0                  The next n or fewer bytes complete the
                       multibyte character that corresponds to the
                       null wide character (which is the value stored
                       if pwc is not a NULL pointer). The wide-
                       character code corresponding to a null byte
                       is zero.
    -1                 Indicates an encoding error. The next n or
                       fewer bytes do not contribute to a complete
                       and valid multibyte character. errno is set to
                       EILSEQ. The conversion state is undefined.
    -2                 Indicates an incomplete but potentially valid
                       multibyte character (all n bytes have been
                       processed).

312  –  mbstowcs

    Converts a sequence of multibyte characters into a sequence of
    corresponding wide-character codes.

    Format

      #include  <stdlib.h>

      size_t mbstowcs  (wchar_t *pwcs, const char *s, size_t n);

312.1  –  Arguments

 pwcs

    A pointer to the array containing the resulting sequence of wide-
    character codes.

 s

    A pointer to the array of multibyte characters.

 n

    The maximum number of wide-character codes that can be stored in
    the array pointed to by pwcs.

312.2  –  Description

    The mbstowcs function converts a sequence of multibyte characters
    from the array pointed to by s to a sequence of wide-character
    codes that are stored into the array pointed to by pwcs, up to a
    maximum of n codes.

    This function is affected by the LC_CTYPE category of the
    program's current locale. If copying takes place between objects
    that overlap, the behavior is undefined.

312.3  –  Return Values

    x                  The number of array elements modified or
                       required, not included any terminating zero
                       code. The array will not be zero-terminated
                       if the value returned is n. If pwcs is the
                       NULL pointer, mbstowcs returns the number
                       of elements required for the wide-character
                       array.
    (size_t) -1        Indicates that an error occurred. The function
                       sets errno to EILSEQ - Invalid character
                       detected.

313  –  mbtowc

    Converts a multibyte character to its wide-character equivalent.

    Format

      #include  <stdlib.h>

      int mbtowc  (wchar_t *pwc, const char *s, size_t n);

313.1  –  Arguments

 pwc

    A pointer to the resulting wide-character code.

 s

    A pointer to the multibyte character.

 n

    The maximum number of bytes that comprise the next multibyte
    character.

313.2  –  Description

    If the character is n or fewer bytes, the mbtowc function
    converts the multibyte character pointed to by s to its wide-
    character equivalent. If the character is invalid or greater than
    n bytes, the function returns -1 to indicate an error.

    If pwc is a NULL pointer and s is not a null pointer, the
    function determines the number of bytes that constitute the
    multibyte character pointed to by s (regardless of the value
    of n).

    This function is affected by the LC_CTYPE category of the
    program's current locale.

313.3  –  Return Values

    x                  The number of bytes that comprise the valid
                       character pointed to by s.
    0                  If s is either a NULL pointer or a pointer to
                       the null byte.
    -1                 Indicates an error. The function sets errno to
                       EILSEQ - Invalid character detected.

314  –  mbsinit

    Determines whether an mbstate_t object decribes an initial
    conversion state.

    Format

      #include  <wchar.h>

      int mbsinit  (const mbstate_t *ps);

314.1  –  Argument

 ps

    A pointer to the mbstate_t object. mbstate_t is an opaque
    datatype intended to keep the conversion state for the state-
    dependent codesets.

314.2  –  Description

    If ps is not a NULL pointer, the mbsinit function determines
    whether the mbstate_t object pointed to by ps describes an
    initial conversion state. A zero mbstate_t object always
    describes an initial conversion state.

314.3  –  Return Values

    nonzero            The ps argument is a NULL pointer, or the
                       mbstate_t object pointed to by ps describes an
                       initial conversion state.
    0                  The mbstate_t object pointed to by ps does not
                       describe an initial conversion state.

315  –  mbsrtowcs

    Converts a sequence of multibyte characters to a sequence of
    corresponding wide-character codes.

    Format

      #include  <wchar.h>

      size_t mbsrtowcs  (wchar_t *dst, const char **src, size_t len,
                        mbstate_t *ps);

315.1  –  Function Variants

    The mbsrtowcs function has variants named _mbsrtowcs32 and
    _mbsrtowcs64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

315.2  –  Arguments

 dst

    A pointer to the destination array containing the resulting
    sequence of wide-character codes.

 src

    An address of the pointer to an array containing a sequence of
    multibyte characters to be converted.

 len

    The maximum number of wide character codes that can be stored in
    the array pointed to by dst.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

315.3  –  Description

    The mbsrtowcs function converts a sequence of multibyte
    characters, beginning in the conversion state described by the
    object pointed to by ps, from the array indirectly pointed to by
    src, into a sequence of corresponding wide characters.

    If dst is not a NULL pointer, the converted characters are stored
    into the array pointed to by dst. Conversion continues up to and
    including a terminating null character, which is also stored.

    Conversion stops earlier for one of the following reasons:

    o  A sequence of bytes is encountered that does not form a valid
       multibyte character.

    o  If dst is not a NULL pointer, when len codes have been stored
       into the array pointed to by dst.

    If dst is not a NULL pointer, the pointer object pointed to by
    src is assigned either a NULL pointer (if the conversion stopped
    because of reaching a terminating null wide character), or the
    address just beyond the last multibyte character converted (if
    any). If conversion stopped because of reaching a terminating
    null wide character, the resulting state described is the initial
    conversion state.

315.4  –  Return Values

    n                  The number of multibyte characters
                       successfully converted, sequence, not
                       including the terminating null (if any).
    -1                 Indicates an error. A sequence of bytes that
                       do not form valid multibyte character was
                       encountered. errno is set to EILSEQ; the
                       conversion state is undefined.

316  –  memccpy

    Copies characters sequentially between strings in memory areas.

    Format

      #include  <string.h>

      void *memccpy  (void *dest, void *source, int c, size_t n);

316.1  –  Function Variants

    The memccpy function has variants named _memccpy32 and _memccpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

316.2  –  Arguments

 dest

    A pointer to the location of a destination string.

 source

    A pointer to the location of a source string.

 c

    A character that you want to search for.

 n

    The number of charcter you want to copy.

316.3  –  Description

    The memccpy function operates on strings in memory areas. A
    memory area is a group of contiguous characters bound by a count
    and not terminated by a null character. The function does not
    check for overflow of the receiving memory area. The memccpy
    function is defined in the <string.h> header file.

    The memccpy function sequentially copies characters from the
    location pointed to by source into the location pointed to by
    dest until one of the following occurs:

    o  The character specified by c (converted to an unsigned char)
       is copied.

    o  The number of characters specified by n is copied.

316.4  –  Return Values

    x                  A pointer to the character following the
                       character specified by c in the string pointed
                       to by dest.
    NULL               Indicates an error. The character c is not
                       found after scanning n characters in the
                       string.

317  –  memchr

    Locates the first occurrence of the specified byte within the
    initial size bytes of a given object.

    Format

      #include  <string.h>

      void *memchr  (const void *s1, int c, size_t size);

317.1  –  Function Variants

    The memchr function has variants named _memchr32 and _memchr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

317.2  –  Arguments

 s1

    A pointer to the object to be searched.

 c

    The byte value to be located.

 size

    The length of the object to be searched.

    If size is zero, memchr returns NULL.

317.3  –  Description

    Unlike strchr, the memchr function does not stop when it
    encounters a null character.

317.4  –  Return Values

    pointer            A pointer to the first occurrence of the byte.
    NULL               Indicates that the specified byte does not
                       occur in the object.

318  –  memcmp

    Compares two objects, byte by byte. The compare operation starts
    with the first byte in each object.

    Format

      #include  <string.h>

      int memcmp  (const void *s1, const void *s2, size_t size);

318.1  –  Arguments

 s1

    A pointer to the first object.

 s2

    A pointer to the second object.

 size

    The length of the objects to be compared.

    If size is zero, the two objects are considered equal.

318.2  –  Description

    The memcmp function uses native byte comparison. The sign of
    the value returned is determined by the sign of the difference
    between the values of the first pair of unlike bytes in the
    objects being compared. Unlike the strcmp function, the memcmp
    function does not stop when a null character is encountered.

318.3  –  Return Value

    x                  An integer less than, equal to, or greater
                       than 0, depending on whether the lexical value
                       of the first object is less than, equal to, or
                       greater than that of the second object.

319  –  memcpy

    Copies a specified number of bytes from one object to another.

    Format

      #include  <string.h>

      void *memcpy  (void *dest, const void *source, size_t size);

319.1  –  Function Variants

    The memcpy function has variants named _memcpy32 and _memcpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

319.2  –  Arguments

 dest

    A pointer to the destination object.

 source

    A pointer to the source object.

 size

    The length of the object to be copied.

319.3  –  Description

    The memcpy function copies size bytes from the object pointed
    to by source to the object pointed to by dest; it does not check
    for the overflow of the receiving memory area (dest). Unlike the
    strcpy function, the memcpy function does not stop when a null
    character is encountered.

319.4  –  Return Value

    x                  The value of dest.

320  –  memmove

    Copies a specified number of bytes from one object to another.

    Format

      #include  <string.h>

      void *memmove  (void *dest, const void *source, size_t size);

320.1  –  Function Variants

    The memmove function has variants named _memmove32 and _memmove64
    for use with 32-bit and 64-bit pointer sizes, respectively.

320.2  –  Arguments

 dest

    A pointer to the destination object.

 source

    A pointer to the source object.

 size

    The length of the object to be copied.

320.3  –  Description

    In VSI C for OpenVMS Systems, memmove and memcpy perform the
    same function. Programs that require portability should use
    memmove if the area pointed at by dest could overlap the area
    pointed at by source.

320.4  –  Return Value

    x                  The value of dest.

320.5  –  Example

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

        main()
        {
           char pdest[14] = "hello   there";
           char *psource = "you are there";

           memmove(pdest, psource, 7);
           printf("%s\n", pdest);
        }

      This example produces the following output:

        you are there

321  –  memset

    Sets a specified number of bytes in a given object to a given
    value.

    Format

      #include  <string.h>

      void *memset  (void *s, int value, size_t size);

321.1  –  Function Variants

    The memset function has variants named _memset32 and _memset64
    for use with 32-bit and 64-bit pointer sizes, respectively.

321.2  –  Arguments

 s

    An array pointer.

 value

    The value to be placed in s.

 size

    The number of bytes to be placed in s.

321.3  –  Description

    The memset function copies value (converted to an unsigned char)
    into each of the first size characters of the object pointed to
    by s.

    This function returns s. It does not check for the overflow of
    the receiving memory area pointed to by s.

321.4  –  Return Value

    x                  The value of s.

322  –  mkdir

    Creates a directory.

    Format

      #include  <stat.h>

      int mkdir  (const char *dir_spec, mode_t mode); (ISO POSIX-1)

      int mkdir  (const char *dir_spec, mode_t mode, . . . );
                 (DEC C Extension)

322.1  –  Arguments

 dir_spec

    A valid OpenVMS or UNIX style directory specification that may
    contain a device name. For example:

    DBA0:[BAY.WINDOWS]     /*    OpenVMS      */
    /dba0/bay/windows      /*   UNIX style    */

    This specification cannot contain a node name, filename, file
    extension, file version, or a wildcard character. The same
    restriction applies to the UNIX style directory specifications.

 mode

    A file protection. See the chmod function in this section for
    information about the specific file protections.

    The file protection of the new directory is derived from the
    mode argument, the process's file protection mask (see the umask
    function), and the parent-directory default protections.

    In a manner consistent with the OpenVMS behavior for creating
    directories, mkdir never applies delete access to the directory.
    An application that needs to set delete access should use an
    explicit call to chmod to set write permission.

    See the Description section of this function for more information
    about how the file protection is set for the newly created
    directory.

  . . .

    Represents the following optional arguments. These arguments have
    fixed position in the argument list, and cannot be arbitrarily
    placed.

       unsigned int uic
       The user identification code (UIC) that identifies the
       owner of the created directory. If this argument is 0, the
       C RTL gives the created directory the UIC of the parent
       directory. If this argument is not specified, the C RTL
       gives the created directory your UIC. This optional argument
       is specific to the C RTL and is not portable.

       unsigned short max_versions
       The maximum number of file versions to be retained in the
       created directory. The system automatically purges the
       directory keeping, at most, max_versions number of every file.

       If this argument is 0, the C RTL does not place a limit
       on the maximum number of file versions.

       If this argument is not specified, the C RTL gives
       the created directory the default version limit of the parent
       directory.

       This optional argument is specific to the C RTL and is
       not portable.

       unsigned short r_v_number
       The volume (device) on which to place the created directory
       if the device is part of a volume set. If this argument is
       not specified, the C RTL arbitrarily places the created
       directory within the volume set. This optional argument is
       specific to the C RTL and is not portable.

322.2  –  Description

    If dir_spec specifies a path that includes directories, which
    do not exist, intermediate directories are also created.
    This differs from the behavior of the UNIX system where these
    intermediate directories must exist and will not be created.

    If you do not specify any optional arguments, the C RTL
    gives the directory your UIC and the default version limit of the
    parent directory, and arbitrarily places the directory within the
    volume set. You cannot get the default behavior for the uic or
    max_versions arguments if you specify any arguments after them.

                                   NOTE

       The way to create files with OpenVMS RMS default protections
       using the UNIX system-call functions umask, mkdir, creat,
       and open is to call mkdir, creat, and open with a file-
       protection mode argument of 0777 in a program that never
       specifically calls umask. These default protections include
       correctly establishing protections based on ACLs, previous
       versions of files, and so on.

       In programs that do vfork/exec calls, the new process image
       inherits whether umask has ever been called or not from
       the calling process image. The umask setting and whether
       the umask function has ever been called are both inherited
       attributes.

    The file protection supplied by the mode argument is modified by
    the process's file protection mask in such a way that the file
    protection for the new directory is set to the bitwise AND of the
    mode argument and the complement of the file protection mask.

    Default file protections are supplied to the new directory
    from the parent-directory such that if a protection value bit
    in the new directory is zero, then the value of this bit is
    inherited from the parent directory. However, bits in the parent
    directory's file protection that indicate delete access do not
    cause corresponding bits to be set in the new directory's file
    protection.

322.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure.

322.4  –  Examples

    1.umask (0002); /* turn world write access off */

      mkdir ("sys$disk:[.parentdir.childdir]", 0222);
                                 /* turn write access on */

      Parent directory file protection: System:RWD, Owner:RWD,
                                           Group:R, World:R

      The file protection derived from the combination of the mode
      argument and the file protection mask set by umask is (0222)
      & ~(0002), which is 0220. When the parent directory defaults
      are applied to this protection, the protection for the new
      directory becomes:

        File protection:    System:RWD, Owner:RWD, Group:RWD, World:R

    2.umask (0000);

      mkdir ("sys$disk:[.parentdir.childdir]", 0444);
                                 /* turn read access on */

      Parent directory file protection: System:RWD, Owner:RWD,
                                          Group:RWD, World:RWD

      The file protection derived from the combination of the mode
      argument and the file protection mask set by umask is (0444)
      & ~(0000), which is 0444. When the parent directory defaults
      are applied to this protection, the protection for the new
      directory is:

        File protection:    System:RW, Owner:RW, Group:RW, World:RW

      Note that delete access is not inherited.

323  –  mkstemp

    Constructs a unique filename.

    Format

      #include  <stdlib.h>

      int mkstemp  (char *template);

323.1  –  Argument

 template

    A pointer to a string that is replaced with a unique filename.
    The string in the template argument must be a filename with six
    trailing Xs.

323.2  –  Description

    The mkstemp function replaces the six trailing Xs of the string
    pointed to by template with a unique set of characters, and
    returns a file descriptor for the file open for reading and
    writing.

    The string pointed to by template should look like a filename
    with six trailing X's. The mkstemp function replaces each X with
    a character from the portable file-name character set, making
    sure not to duplicate an existing filename.

    If the string pointed to by template does not contain six
    trailing Xs, -1 is returned.

323.3  –  Return Values

    x                  An open file descriptor.
    -1                 Indicates an error. (The string pointed to by
                       template does not contain six trailing Xs.)

324  –  mktemp

    Creates a unique filename from a template.

    Format

      #include  <stdlib.h>

      char *mktemp  (char *template);

324.1  –  Function Variants

    The mktemp function has variants named _mktemp32 and _mktemp64
    for use with 32-bit and 64-bit pointer sizes, respectively.

324.2  –  Argument

 template

    A pointer to a buffer containing a user-defined template. You
    supply the template in the form, namXXXXXX. The six trailing Xs
    are replaced by a unique series of characters. You may supply
    the first three characters. Because the template argument is
    overwritten, do not specify a string literal (const object).

324.3  –  Description

    The use of mktemp is not recommended for new applications. See
    the tmpnam and mkstemp functions for the preferable alternatives.

324.4  –  Return Value

    x                  A pointer to the template, with the template
                       modified to contain the created filename. If
                       this value is a pointer to a null string, it
                       indicates that a unique filename cannot be
                       created.

325  –  mktime

    Converts a local-time structure to a time, in seconds, since the
    Epoch.

    Format

      #include  <time.h>

      time_t mktime  (struct tm *timeptr);

325.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    mktime function that is equivalent to the behavior before OpenVMS
    Version 7.0.

325.2  –  Argument

 timeptr

    A pointer to the local-time structure.

325.3  –  Description

    The mktime function converts a local-time structure (struct tm)
    pointed to by timeptr, to a time in seconds since the Epoch (a
    time_t variable), in the same manner as the values returned by
    the time function.

    The original values of the tm_wday and tm_yday components of
    the structure are ignored, and the original values of the other
    components are not restricted to the ranges defined in <time.h>.
    Upon successful completion, the tm_wday and tm_yday components of
    the structure are set appropriately, and the other components are
    set to represent the specified time, with their values forced to
    the normal range.

    If the local time cannot be encoded, then mktime returns the
    value (time_t)(-1).

    The time_t type is defined in the <time.h> header file as
    follows:

    typedef unsigned long int time_t;

    Local time-zone information is set as if mktime called tzset.

    If the tm_isdst field in the local-time structure pointed to
    by timeptr is positive, mktime initially presumes that Daylight
    Savings Time (DST) is in effect for the specified time.

    If tm_isdst is 0, mktime initially presumes that DST is not in
    effect.

    If tm_isdst is negative, mktime attempts to determine whether or
    not DST is in effect for the specified time.

325.4  –  Return Values

    x                  The specified calendar time encoded as a value
                       of type time_t.
    (time_t)(-1)       If the local time cannot be encoded.

                       Be aware that a return value of (time_t)(-1)
                       can also represent the valid date: Sun Feb 7
                       06:28:15 2106.

326  –  mmap

    Maps file system object into virtual memory. This function is
    reentrant.

    Format

      #include  <types.h>

      #include  <mman.h>

      void mmap  (void *addr, size_t len, int prot, int flags, int
                 filedes, off_t off); (X/Open, POSIX-1)

      void mmap  (void *addr, size_t len, int prot, int flags, int
                 filedes, off_t off ...); (DEC C Extension)

326.1  –  Function Variants

    The mmap function has variants named _mmap32 and _mmap64 for use
    with 32-bit and 64-bit pointer sizes, respectively.

326.2  –  Arguments

 addr

    The starting address of the new region (must be the page
    boundary).

 len

    The length, in bytes, of the new region.

 prot

    Access permission, as defined in the <mman.h> header file.
    Specify either PROT_NONE, PROT_READ, or PROT_WRITE.

 flags

    Attributes of the mapped region as the results of a bitwise-
    inclusive OR operation on any combination of the following:

    o  MAP_FILE or MAP_ANONYMOUS

    o  MAP_VARIABLE or MAP_FIXED

    o  MAP_SHARED or MAP_PRIVATE

 filedes

    The file that you want to map to the new mapped file region
    returned by the open function.

 off

    The offset, specified in bytes. The off_t data type is either a
    64-bit or 32-bit integer. The 64-bit interface allows for file
    sizes greater than 2 GB, and can be selected at compile time by
    defining the _LARGEFILE feature-test macro as follows:

    CC/DEFINE=_LARGEFILE

  . . .

    An optional integer specifying additional flags for the
    SYS$CRMPSC system service for MAP_SHARED. This optional argument
    (VSI C Extension) of the mmap function was introduced in
    OpenVMS Version 7.2.

326.3  –  Description

    The mmap function creates a new mapped file region, a new private
    region, or a new shared memory region.

    Your application must ensure correct synchronization when using
    mmap in conjunction with any other file access method, such as
    read and write, and standard input/output.

    Before calling mmap, the calling application must also ensure
    that all bytes in the range [off, off+len] are written to the
    file (using the fsync function, for example). If this requirement
    is not met, mmap fails with errno set to ENXIO (No such device or
    address).

    The addr and len arguments specify the requested starting address
    and length, in bytes, for the new region. The address is a
    multiple of the page size returned by sysconf(_SC_PAGE_SIZE).

    If the len argument is not a multiple of the page size returned
    by sysconf(_SC_PAGE_SIZE), then the result of any reference to
    an address between the end of the region and the end of the page
    containing the end of the region is undefined.

    The flags argument specifies attributes of the mapped region.
    Values for flags are constructed by a bitwise-inclusive OR
    operation on the flags from the following list of symbolic names
    defined in the <mman.h> header file:

    MAP_FILE         Create a mapped file region.
    MAP_ANONYMOUS    Create an unnamed memory region.
    MAP_VARIABLE     Place region at the computed address.
    MAP_FIXED        Place region at fixed address.
    MAP_SHARED       Share changes.
    MAP_PRIVATE      Changes are private.

    The MAP_FILE and MAP_ANONYMOUS flags control whether the region
    you want to map is a mapped file region or an anonymous shared
    memory region. One of these flags must be selected.

    If MAP_FILE is set in the flags argument:

    o  A new mapped file region is created, mapping the file
       associated with the filedes argument.

    o  The off argument specifies the file byte offset where the
       mapping starts. This offset must be a multiple of the page
       size returned by sysconf(_SC_PAGE_SIZE).

    o  If the end of the mapped file region is beyond the end of the
       file, the result of any reference to an address in the mapped
       file region corresponding to an offset beyond the end of the
       file is unspecified.

    If MAP_ANONYMOUS is set in the flags argument:

    o  A new memory region is created and initialized to all zeros.

    o  The filedes argument is ignored.

    The new region is placed at the requested address if the
    requested address is not null and it is possible to place the
    region at this address. When the requested address is null or
    the region cannot be placed at the requested address, the MAP_
    VARIABLE and MAP_FIXED flags control the placement of the region.
    One of these flags must be selected.

    If MAP_VARIABLE is set in the flags argument:

    o  If the requested address is null or if it is not possible for
       the system to place the region at the requested address, the
       region is placed at an address selected by the system.

    If MAP_FIXED is set in the flags argument:

    o  If the requested address is not null, the mmap function
       succeeds even if the requested address is already part of
       another region. (If the address is within an existing region,
       the effect on the pages within that region and within the area
       of the overlap produced by the two regions is the same as if
       they were unmapped. In other words, whatever is mapped between
       addr and addr + len is unmapped.)

    o  If the requested address is null and MAP_FIXED is specified,
       the results are undefined.

    The MAP_PRIVATE and MAP_SHARED flags control the visibility of
    modifications to the mapped file or shared memory region. One of
    these flags must be selected.

    If MAP_SHARED is set in the flags argument:

    o  If the region is a mapped region, modifications to the region
       are visible to other processes that mapped the same region
       using MAP_SHARED.

    o  If the region is a mapped file region, modifications to the
       region are written to the file. (Note that the modifications
       are not immediately written to the file because of buffer
       cache delay; that is, the write to the file does not occur
       until there is a need to reuse the buffer cache. If the
       modifications must be written to the file immediately, use
       the msync function to ensure that this is done.)

    If MAP_PRIVATE is set in the flags argument:

    o  Modifications to the mapped region by the calling process are
       not visible to other processes that mapped the same region
       using either MAP_PRIVATE or MAP_SHARED.

    o  Modifications to the mapped region by the calling process are
       not written to the file.

    It is unspecified whether modifications by processes that mapped
    the region using MAP_SHARED are visible to other processes that
    mapped the same region using MAP_PRIVATE.

    The prot argument specifies access permissions for the mapped
    region. Specify one of the following:

    PROT_NONE      No access
    PROT_READ      Read-only
    PROT_WRITE     Read/Write access

    After the successful completion of the mmap function, you can
    close the filedes argument without effect on the mapped region or
    on the contents of the mapped file. Each mapped region creates a
    file reference, similar to an open file descriptor, that prevents
    the file data from being deallocated.

                                   NOTE

       The following rules apply to OpenVMS specific file
       references:

       o  Because of the additional file reference, if filedes is
          not opened for file sharing, mmap reopens it with file
          sharing enabled.

       o  The additional file reference that remains for mapped
          regions implies that a later open, fopen, or create call
          to the file that is mapped must specify file sharing.

    Modifications made to the file using the write function are
    visible to mapped regions, and modifications to a mapped region
    are visible with the read function.

                                   NOTE

       Beginning with OpenVMS Version 7.2, while processing a MAP_
       SHARED request, the mmap function constructs the flags
       argument of the SYS$CRMPSC service as a bitwise inclusive
       OR of those bits it sets by itself to fulfill the MAP_
       SHARED request and those bits specified by the caller in
       the optional argument.

       By default, for MAP_SHARED the mmap function creates a
       temporary group global section. The optional mmap argument
       provides the caller with direct access to the features of
       the SYS$CRMPSC system service.

       Using the optional argument, the caller can create, for
       example, a system global section (SEC$M_SYSGBL bit) or
       permanent global section (SEC$M_PERM bit). For example,
       to create a system permanent global section, the caller
       can specify (SEC$M_SYSGBL | SEC$M_PERM) in the optional
       argument.

       The mmap function does not check or set any privileges.
       It is the responsibility of the caller to set appropriate
       privileges, such as SYSGBL privilege for SEC$M_SYSGBL, and
       PRMGBL for SEC$M_PERM, before calling mmap with the optional
       argument.

    See also read, write, open, fopen, creat, and sysconf.

326.4  –  Return Values

    x                  The address where the mapping is placed.
    MAP_FAILED         Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - The file referred to by filedes
                          is not open for read access, or the file
                          is not open for write access and PROT_WRITE
                          was set for a MAP_SHARED mapping operation.

                       o  EBADF - The filedes argument is not a valid
                          file descriptor.

                       o  EINVAL -The flags or prot argument is
                          invalid, or the addr argument or off
                          argument is not a multiple of the page
                          size returned by sysconf(_SC_PAGE_SIZE).

                       o  ENODEV - The file descriptor filedes refers
                          to an object that cannot be mapped, such as
                          a terminal.

                       o  ENOMEM - There is not enough address space
                          to map len bytes.

                       o  ENXIO - The addresses specified by the
                          range [off, off + len] are invalid for
                          filedes.

                       o  EFAULT - The addr argument is an invalid
                          address.

327  –  modf

    Decomposes a floating-point number.

    Format

      #include  <math.h>

      double modf  (double x, double *iptr);

      float modff  (float x, float *iptr);
                   (Integrity servers, Alpha)

      long double modfl  (long double x, long double *iptr);
                         (Integrity servers, Alpha)

327.1  –  Arguments

 x

    An object of type double, float, or long double.

 iptr

    A pointer to an object of type double, float, or long double to
    match the type of x.

327.2  –  Description

    The modf functions decompose their first argument x into a
    positive fractional part f and an integer part i, each of which
    has the same sign as x.

    The functions return f and assign i to the object pointed to by
    the second argument (iptr).

327.3  –  Return Values

    x                  The fractional part of the argument x.
    NaN                x is NaN; errno is set to EDOM and *iptr is
                       set to NaN.
    0                  Underflow occurred; errno is set to ERANGE.

328  –  [w]move

    Change the current cursor position on the specified window to the
    coordinates (y,x). The move function acts on the stdscr window.

    Format

      #include  <curses.h>

      int move  (int y, int x);

      int wmove  (WINDOW *win, int y, int x);

328.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

328.2  –  Description

    For more information, see the scrollok function in this section.

328.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally.

329  –  mprotect

    Modifies access protections of memory mapping. This function is
    reentrant.

    Format

      #include  <mman.h>

      int mprotect  (void *addr, size_t len, int prot);

329.1  –  Arguments

 addr

    The address of the region that you want to modify.

 len

    The length, in bytes, of the region that you want to modify.

 prot

    Access permission, as defined in the <mman.h> header file.
    Specify either PROT_NONE, PROT_READ, or PROT_WRITE.

329.2  –  Description

    The mprotect function modifies the access protection of a mapped
    file or shared memory region.

    The addr and len arguments specify the address and length, in
    bytes, of the region that you want to modify. The len argument
    must be a multiple of the page size as returned by sysconf(_SC_
    PAGE_SIZE). If len is not a multiple of the page size as returned
    by sysconf(_SC_PAGE_SIZE), the length of the region is rounded up
    to the next multiple of the page size.

    The prot argument specifies access permissions for the mapped
    region. Specify one of the following:

    PROT_NONE      No access
    PROT_READ      Read-only
    PROT_WRITE     Read/Write access

    The mprotect function does not modify the access permission of
    any region that lies outside of the specified region, except that
    the effect on addresses between the end of the region, and the
    end of the page containing the end of the region, is unspecified.

    If the mprotect function fails under a condition other than that
    specified by EINVAL, the access protection of some of the pages
    in the range [addr, addr + len] can change. Suppose the error
    occurs on some page at an addr2; mprotect can modify protections
    of all whole pages in the range [addr, addr2].

    See also sysconf.

329.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EACCESS - The prot argument specifies a
                          protection that conflicts with the access
                          permission set for the underlying file.

                       o  EINVAL - The prot argument is invalid, or
                          the addr argument is not a multiple of the
                          page size as returned by sysconf(_SC_PAGE_
                          SIZE).

                       o  EFAULT - The range [addr, addr + len]
                          includes an invalid address.

330  –  mrand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit signed long integers.

    Format

      #include  <stdlib.h>

      long int mrand48  (void);

330.1  –  Description

    The mrand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    It returns signed long integers uniformly distributed over the
    range of y values such that -231 

    Before you call the mrand48 function, use either srand48,
    seed48, or lcong48 to initialize the random-number generator.
    You must initialize the mrand48 function prior to invoking it,
    because it stores the last 48-bit Xi generated into an internal
    buffer. (Although it is not recommended, constant default
    initializer values are supplied automatically if the drand48,
    lrand48, or mrand48 functions are called without first 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 values returned by the mrand48 function is computed by
    first generating the next 48-bit Xi in the sequence. Then the
    appropriate bits, according to the type of returned data item,
    are copied from the high-order (most significant) bits of Xi and
    transformed into the returned value.

    See also drand48, lrand48, lcong48, seed48, and srand48.

330.2  –  Return Value

    n                  Returns signed long integers uniformly
                       distributed over the range -231 

331  –  msync

    Synchronizes a mapped file.

    Format

      #include  <mman.h>

      int msync  (void *addr, size_t len, int flags);

331.1  –  Arguments

 addr

    The address of the region that you want to synchronize.

 len

    The length, in bytes, of the region that you want to synchronize.

 flags

    One of the following symbolic constants defined in the <mman.h>
    header file:

    MS_SYNC        Synchronous cache flush
    MS_ASYNC       Asynchronous cache flush
    MS_            Invalidate cashed pages
    INVALIDATE

331.2  –  Description

    The msync function controls the caching operations of a mapped
    file region. Use msync to:

    o  Ensure that modified pages in the region transfer to the
       underlying storage device of the file.

    o  Control the visibility of modifications with respect to file
       system operations.

    The addr and len arguments specify the region to be synchronized.
    The len argument must be a multiple of the page size as returned
    by sysconf(_SC_PAGE_SIZE); otherwise, the length of the region is
    rounded up to the next multiple of the page size.

    If the flags argument is set to:

    flags Argument   Then the msync Function...

    MS_SYNC          Does not return until the system completes all
                     I/O operations.
    MS_ASYNC         Returns after the system schedules all I/O
                     operations.
    MS_INVALIDATE    Invalidates all cached copies of the pages. The
                     operating system must obtain new copies of the
                     pages from the file system the next time the
                     application references them.

    After a successful call to the msync function with the flags
    argument set to:

    o  MS_SYNC - All previous modifications to the mapped region
       are visible to processes using the read argument. Previous
       modifications to the file using the write function are lost.

    o  MS_INVALIDATE - All previous modifications to the file using
       the write function are visible to the mapped region. Previous
       direct modifications to the mapped region are lost.

    See also read, write, and sysconf.

331.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EIO - An I/O error occurred while reading
                          from or writing to the file system.

                       o  ENOMEM - The range specified by
                          [addr, addr + len] is invalid for a
                          process's address space, or the range
                          specifies one or more unmapped pages.

                       o  EINVAL - The addr argument is not a
                          multiple of the page size as returned by
                          sysconf(_SC_PAGE_SIZE).

                       o  EFAULT - The range [addr, addr + len]
                          includes an invalid address.

332  –  munmap

    Unmaps a mapped region. This function is reentrant.

    Format

      #include  <mman.h>

      int munmap  (void *addr, size_t len);

332.1  –  Arguments

 addr

    The address of the region that you want to unmap.

 len

    The length, in bytes, of that region the you want to unmap.

332.2  –  Description

    The munmap function unmaps a mapped file or shared memory region.

    The addr and len arguments specify the address and length, in
    bytes, respectively, of the region to be unmapped.

    The len argument must be a multiple of the page size as returned
    by sysconf(_SC_PAGE_SIZE); otherwise, the length of the region is
    rounded up to the next multiple of the page size.

    The result of using an address that lies in an unmapped region
    and not in any subsequently mapped region is undefined.

    See also sysconf.

332.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  ENIVAL - The addr argument is not a
                          multiple of the page size as returned by
                          sysconf(_SC_PAGE_SIZE).

                       o  EFAULT - The range [addr, addr + len]
                          includes an invalid address.

333  –  mv[w]addch

    Move the cursor to coordinates (y,x) and add a character to the
    specified window.

    Format

      #include  <curses.h>

      int mvaddch  (int y, int x, char ch);

      int mvwaddch  (WINDOW *win, int y, int x, char ch);

333.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

 ch

    If this argument is a new-line character (\n), the mvaddch and
    mvwaddch functions clear the line to the end, and move the cursor
    to the next line at the same x coordinate. A carriage return (\r)
    moves the cursor to the beginning of the specified line. A tab
    (\t) moves the cursor to the next tabstop within the window.

333.2  –  Description

    This routine performs the same function as mvwaddch, but on the
    stdscr window.

    When mvwaddch is used on a subwindow, it writes the character
    onto the underlying window as well.

333.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that writing the character would
                       cause the screen to scroll illegally. For more
                       information, see the scrollok function.

334  –  mv[w]addstr

    Move the cursor to coordinates (y,x) and add the specified
    string, to which str points, to the specified window.

    Format

      #include  <curses.h>

      int mvaddstr  (int y, int x, char *str);

      int mvwaddstr  (WINDOW *win, int y, int x, char *str);

334.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

 str

    A pointer to the character string.

334.2  –  Description

    This routine performs the same function as mvwaddstr, but on the
    stdscr window.

    When mvwaddstr is used on a subwindow, the string is written onto
    the underlying window as well.

334.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function causes the screen
                       to scroll illegally, but it places as much of
                       the string onto the window as possible. For
                       more information, see the scrollok function.

335  –  mvcur

    Moves the terminal's cursor from (lasty,lastx) to (newy,newx).

    Format

      #include  <curses.h>

      int mvcur  (int lasty, int lastx, int newy, int newx);

335.1  –  Arguments

 lasty

    The cursor position.

 lastx

    The cursor position.

 newy

    The resulting cursor position.

 newx

    The resulting cursor position.

335.2  –  Description

    In VSI C for OpenVMS Systems, mvcur and move perform the same
    function.

    See also move.

335.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that moving the window placed part
                       or all of the window off the edge of the
                       terminal screen. The terminal screen remains
                       unaltered.

336  –  mv[w]delch

    Move the cursor to coordinates (y,x) and delete the character
    on the specified window. The mvdelch function acts on the stdscr
    window.

    Format

      #include  <curses.h>

      int mvdelch  (int y, int x);

      int mvwdelch  (WINDOW *win, int y, int x);

336.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

336.2  –  Description

    Each of the following characters on the same line shifts to the
    left, and the last character becomes blank.

336.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that deleting the character would
                       cause the screen to scroll illegally. For more
                       information, see the scrollok function.

337  –  mv[w]getch

    Move the cursor to coordinates (y,x), get a character from the
    terminal screen, and echo it on the specified window. The mvgetch
    function acts on the stdscr window.

    Format

      #include  <curses.h>

      int mvgetch  (int y, int x);

      int mvwgetch  (WINDOW *win, int y, int x);

337.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

337.2  –  Description

    The mvgetch and mvwgetch functions refresh the specified window
    before fetching the character.

337.3  –  Return Values

    x                  The returned character.
    ERR                Indicates that the function causes the screen
                       to scroll illegally. For more information, see
                       the scrollok function in this section.

338  –  mv[w]getstr

    Move the cursor to coordinates (y,x), get a string from the
    terminal screen, store it in the variable str (which must be
    large enough to contain the string), and echo it on the specified
    window. The mvgetstr function acts on the stdscr window.

    Format

      #include  <curses.h>

      int mvgetstr  (int y, int x, char *str);

      int mvwgetstr  (WINDOW *win, int y, int x, char *str);

338.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

 str

    The string that is displayed.

338.2  –  Description

    The mvgetstr and mvwgetstr functions strip the new-line
    terminator (\n) from the string.

338.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function causes the screen
                       to scroll illegally.

339  –  mv[w]inch

    Move the cursor to coordinates (y,x) and return the character on
    the specified window without making changes to the window. The
    mvinch function acts on the stdscr window.

    Format

      #include  <curses.h>

      int mvinch  (int y, int x);

      int mvwinch  (WINDOW *win, int y, int x);

339.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

339.2  –  Return Values

    x                  The returned character.
    ERR                Indicates an input error.

340  –  mv[w]insch

    Move the cursor to coordinates (y,x) and insert the character
    ch into the specified window. The mvinsch function acts on the
    stdscr window.

    Format

      #include  <curses.h>

      int mvinsch  (int y, int x, char ch);

      int mvwinsch  (WINDOW *win, int y, int x, char ch);

340.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

 ch

    The character to be inserted at the window's coordinates.

340.2  –  Description

    After the character is inserted, each character on the line
    shifts to the right, and the last character on the line is
    deleted.

340.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally. For more information, see
                       the scrollok function in this section.

341  –  mv[w]insstr

    Move the cursor to coordinates (y,x) and insert the specified
    string into the specified window. The mvinsstr function acts on
    the stdscr window.

    Format

      #include  <curses.h>

      int mvinsstr  (int y, int x, char *str);

      int mvwinsstr  (WINDOW *win, int y, int x, char *str);

341.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

 str

    The string that is displayed.

341.2  –  Description

    Each character after the string shifts to the right, and the last
    character disappears. The mvinsstr and mvwinsstr functions are
    specific to VSI C for OpenVMS Systems and are not portable.

341.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the screen
                       scroll illegally. For more information, see
                       the scrollok function.

342  –  mvwin

    Moves the starting position of the window to the specified (y,x)
    coordinates.

    Format

      #include  <curses.h>

      mvwin  (WINDOW *win, int y, int x);

342.1  –  Arguments

 win

    A pointer to the window.

 y

    A window coordinate.

 x

    A window coordinate.

342.2  –  Description

    When moving subwindows, the mvwin function does not rewrite the
    contents of the subwindow on the underlying window at the new
    position. If you write anything to the subwindow after the move,
    the function also writes to the underlying window.

342.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that moving the window put part or
                       all of the window off the edge of the terminal
                       screen. The terminal screen remains unaltered.

343  –  nanosleep

    High-resolution sleep (REALTIME). Suspends a process (or thread
    in a threaded program) from execution for the specified timer
    interval.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <time.h>

      int nanosleep  (const struct timespec *rqtp, struct timespec *rmtp);

343.1  –  Arguments

 rqtp

    A pointer to the timespec data structure that defines the time
    interval during which the calling process or thread is suspended.

 rmtp

    A pointer to the timespec data structure that receives the amount
    of time remaining in the previously requested interval, or zero
    if the full interval has elapsed.

343.2  –  Description

    The nanosleep function suspends a process or thread until one of
    the following conditions is met:

    o  The time interval specified by the rqtp argument has elapsed.

    o  A signal is delivered to the calling process and the action
       is to invoke a signal-catching function or to terminate the
       process.

    The suspension time may be longer than requested because the
    argument value is rounded up to an integer multiple of the sleep
    resolution or because of the scheduling of other activity by the
    system. Except when interrupted by a signal, the suspension time
    is not less than the time specified by the rqtp argument (as
    measured by the system clock, CLOCK_REALTIME).

    The use of the nanosleep function has no effect on the action or
    blockage of any signal.

    If the requested time has elapsed, the call was successful and
    the nanosleep function returns zero.

    On failure, the nanosleep function returns -1 and sets errno
    to indicate the failure. The function fails if it has been
    interrupted by a signal, or if the rqtp argument specified
    a nanosecond value less than 0 or greater than or equal to 1
    billion.

    If the rmtp argument is non-NULL, the timespec structure it
    references is updated to contain the amount of time remaining in
    the interval (the requested time minus the time actually slept).

    If the rmtp argument is NULL, the remaining time is not returned.

    See also clock_getres, clock_gettime, clock_settime, and sleep.

343.3  –  Return Values

    0                  Indicates success. The requested time has
                       elapsed.
    -1                 Indicates failure. The function call was
                       unsuccessful or was interrupted by a signal;
                       errno is set to one of the following values:

                       o  EINTR - The nanosleep function was
                          interrupted by a signal.

                       o  EINVAL - The rqtp argument specified a
                          nanosecond value less than 0 or greater
                          than or equal to 1 billion.

344  –  newwin

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

    Format

      #include  <curses.h>

      WINDOW *newwin  (int numlines, int numcols, int begin_y, int
                      begin_x);

344.1  –  Arguments

 numlines

    If it is 0, the newwin function sets that dimension to LINES
    (begin_y). To get a new window of dimensions LINES by COLS, use
    the following line:

    newwin (0, 0, 0, 0)

 numcols

    If it is 0, the newwin function sets that dimension to COLS
    (begin_x). Therefore, to get a new window of dimensions LINES
    by COLS, use the following line:

    newwin (0, 0, 0, 0)

 begin_y

    A window coordinate.

 begin_x

    A window coordinate.

344.2  –  Return Values

    x                  The address of the allocated window.
    ERR                Indicates an error.

345  –  nextafter

    Returns the next machine-representable number following x in the
    direction of y.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double nextafter  (double x, double y);

      float nextafterf  (float x, float y);

      long double nextafterl  (long double x, long double y);

345.1  –  Arguments

 x

    A real number.

 y

    A real number.

345.2  –  Description

    The nextafter functions return the next machine-representable
    floating-point number following x in the direction of y. If
    y is less than x, nextafter returns the largest representable
    floating-point number less than x.

345.3  –  Return Values

    n                  The next representable floating-point value
                       following x in the direction of y.
    HUGE_VAL           Overflow; errno is set to ERANGE.
    NaN                x or y is NaN; errno is set to EDOM.

346  –  nexttoward

    Equivalent to the nextafter function, with exceptions noted in
    the Description.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double nexttoward  (double x, long double y);

      float nexttowardf  (float x, long double y);

      long double nexttowardl  (long double x, long double y);

346.1  –  Arguments

 x

    A real number.

 y

    A real number.

346.2  –  Description

    The nexttoward functions are equivalent to the corresponding
    nextafter functions, except that the second parameter has type
    long double and the functions return y converted to the type of
    the function if x equals y.

346.3  –  Return Values

    n                  The next representable floating-point value
                       following x in the direction of y.
    y (of the type x)  If x equals y.
    HUGE_VAL           Overflow; errno is set to ERANGE.
    NaN                x or y is NaN; errno is set to EDOM.

347  –  nice

    Increases or decreases process priority relative to the process
    current priority by the amount of the argument. This function is
    nonreentrant.

    Format

      #include  <unistd.h>

      int nice  (int increment);

347.1  –  Argument

 increment

    As a positive argument, decreases priority; as a negative
    argument, increases priority. Issuing nice(0) restores the
    base priority. The resulting priority cannot be less than 1,
    or greater than the process's base priority. If it is, the nice
    function quietly does nothing.

347.2  –  Description

    When a process calls the vfork function, the resulting child
    inherits the parent's priority.

    With the DECC$ALLOW_UNPRIVILEGED_NICE feature logical enabled,
    the nice function exhibits its legacy behavior of not checking
    the privilege of the calling process (that is, any user may lower
    the nice value to increase process priorities). Also, when the
    caller sets a priority above MAX_PRIORITY, the nice value is set
    to the base priority.

    With DECC$ALLOW_UNPRIVILEGED_NICE disabled, the nice function
    conforms to the X/Open standard of checking the privilege of the
    calling process (only users with ALTPRI privilege can lower the
    nice value to increase process priorities), and when the caller
    sets a priority above MAX_PRIORITY, the nice value is set to MAX_
    PRIORITY.

    See also vfork.

347.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure.

348  –  nint

    Returns the nearest integral value to the argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double nint  (double x);

      float nintf  (float x,);

      long double nintl  (long double x);

348.1  –  Argument

 x

    A real number.

348.2  –  Description

    The nint functions return the nearest integral value to x,
    except halfway cases are rounded to the integral value larger
    in magnitude. This corresponds to the Fortran generic intrinsic
    function nint.

348.3  –  Return Values

    n                  The nearest integral value to x.
    NaN                x is NaN; errno is set to EDOM.

349  –  [no]nl

    The nl and nonl functions are provided only for UNIX software
    compatibility and have no function in the OpenVMS environment.

    Format

      #include  <curses.h>

      void nl  (void);

      void nonl  (void);

350  –  nl_langinfo

    Returns a pointer to a string that contains information obtained
    from the program's current locale.

    Format

      #include  <langinfo.h>

      char *nl_langinfo  (nl_item item);

350.1  –  Argument

 item

    The name of a constant that specifies the information required.
    These constants are defined in <langinfo.h>.

    The following constants are valid:

    Constant     Category     Description

    D_T_FMT      LC_TIME      String for formatting date and time
    D_FMT        LC_TIME      String for formatting date
    T_FMT        LC_TIME      String for formatting time
    T_FMT_AMPM   LC_TIME      Time format with AM/PM string
    AM_STR       LC_TIME      String that represents AM in 12-hour
                              clock notation
    PM_STR       LC_TIME      String that represents PM in 12-hour
                              clock notation
    DAY_1        LC_TIME      The name of the first day of the week
     . . .
    DAY_7        LC_TIME      The name of the seventh day of the week
    ABDAY_1      LC_TIME      The abbreviated name of the first day
                              of the week
     . . .
    ABDAY_7      LC_TIME      The abbreviated name of the seventh day
                              of the week
    MON_1        LC_TIME      The name of the first month in the year
     . . .
    MON_12       LC_TIME      The name of the twelfth month in the
                              year
    ABMON_1      LC_TIME      The abbreviated name of the first month
                              in the year
     . . .
    ABMON_12     LC_TIME      The abbreviated name of the twelfth
                              month in the year
    ERA          LC_TIME      Era description strings
    ERA_D_FMT    LC_TIME      Era date format string
    ERA_T_FMT    LC_TIME      Era time format
    ERA_D_T_FMT  LC_TIME      Era date and time format
    ALT_DIGITS   LC_TIME      Alternative symbols for digits
    RADIXCHAR    LC_NUMERIC   The radix character
    THOUSEP      LC_NUMERIC   The character used to separate groups
                              of digits in nonmonetary values
    YESEXP       LC_MESSAGES  The expression for affirmative
                              responses to yes/no questions
    NOEXP        LC_MESSAGES  The expression for negative responses
                              to yes/no questions
    CRNCYSTR     LC_MONETARY  The currency symbol. It is preceded by
                              one of the following:

                              o  A minus (-)  if the symbol is to
                                 appear before the value

                              o  A plus (+)  if the symbol is to
                                 appear after the value

                              o  A period (.)  if the symbol replaces
                                 the radix character

    CODESET      LC_CTYPE     Codeset name

350.2  –  Description

    If the current locale does not have language information defined,
    the function returns information from the C locale. The program
    should not modify the string returned by the function. This
    string might be overwritten by subsequent calls to nl_langinfo.

    If the setlocale function is called after a call to nl_langinfo,
    then the pointer returned by the previous call to nl_langinfo
    will be unspecified. In this case, the nl_langinfo function
    should be called again.

350.3  –  Return Value

    x                  Pointer to the string containing the requested
                       information. If item is invalid, the function
                       returns an empty string.

350.4  –  Example

        #include <stdio.h>
        #include <locale.h>
        #include <langinfo.h>

        /* This test sets up the British English locale, and then       */
        /* inquires on the data and time format, first day of the week, */
        /* and abbreviated first day of the week.                       */

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

        int main()
        {
            char *return_val;
            char *nl_ptr;

            /* set the locale, with user supplied locale name  */

            return_val = setlocale(LC_ALL, "en_gb.iso8859-1");
            if (return_val == NULL) {
                printf("ERROR : The locale is unknown");
                exit(1);
            }
            printf("+----------------------------------------+\n");

            /* Get the date and time format from the locale.  */

            printf("D_T_FMT = ");

            /*  Compare the returned string from nl_langinfo with */
            /*  an empty string.                                  */

            if (!strcmp((nl_ptr = (char *) nl_langinfo(D_T_FMT)), "")) {

          /* The string returned was empty this could mean that either */
          /* 1) The locale does not contain a value for this item      */
          /* 2) The value for this item is an empty string             */

                printf("nl_langinfo returned an empty string\n");
            }
            else {
                /* Display the date and time format  */

                printf("%s\n", nl_ptr);
            }

        /* Get the full name for the first day of the week from locale */
           printf("DAY_1 = ");

          /*  Compare the returned string from nl_langinfo with */
          /*  an empty string.                                  */

            if (!strcmp((nl_ptr = (char *) nl_langinfo(DAY_1)), "")) {

          /* The string returned was empty this could mean that either */
          /*    1) The locale does not contain a value for the first   */
          /*       day of the week                                     */
          /*    2) The value for the first day of the week is          */
          /*       an empty string                                     */

                printf("nl_langinfo returned an empty string\n");
            }

            else {
             /* Display the full name of the first day of the week     */

                printf("%s\n", nl_ptr);
            }
  /* Get the abbreviated name for the first day of the week from locale*/

            printf("ABDAY_1 = ");

         /* Compare the returned string from nl_
 langinfo with an empty */
         /* string.                                                    */

            if (!strcmp((nl_ptr = (char *) nl_langinfo(ABDAY_1)), "")) {

         /* The string returned was empty this could mean that either  */
         /*    1) The locale does not contain a value for the first    */
         /*       day of the week                                      */
         /*    2) The value for the first day of the week is an        */
         /*       empty string                                         */

                printf("nl_langinfo returned an empty string\n");
            }

            else {

         /* Display the abbreviated name of the first day of the week  */

                printf("%s\n", nl_ptr);
           }
        }

      Running the example program produces the following result:

        +----------------------------------------+
        D_T_FMT = %a %e %b %H:%M:%S %Y
        DAY_1 = Sunday
        ABDAY_1 = Sun

351  –  nrand48

    Generates uniformly distributed pseudorandom-number sequences.
    Returns 48-bit signed long integers.

    Format

      #include  <stdlib.h>

      long int nrand48  (unsigned short int xsubi[3]);

351.1  –  Argument

 xsubi

    An array of three short ints that, when concatenated together,
    form a 48-bit integer.

351.2  –  Description

    The nrand48 function generates pseudorandom numbers using the
    linear congruential algorithm and 48-bit integer arithmetic.

    The nrand48 function returns nonnegative, long integers uniformly
    distributed over the range of y values, such that 0 

    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 nrand48 function requires that the calling program pass an
    array as the xsubi argument, which for the first call must be
    initialized to the initial value of the pseudorandom-number
    sequence. Unlike the drand48 function, it is not necessary to
    call an initialization function prior to the first call.

    By using different arguments, the nrand48 function allows
    separate modules of a large program to generate several
    independent sequences of pseudorandom numbers. For example, the
    sequence of numbers that one module generates does not depend
    upon how many times the functions are called by other modules.

351.3  –  Return Value

    n                  Returns nonnegative, long integers over the
                       range 0 

352  –  open

    Opens a file for reading, writing, or editing. It positions the
    file at its beginning (byte 0).

    Format

      #include  <fcntl.h>

      int open  (const char *file_spec, int flags, mode_t mode);
                (ANSI C)

      int open  (const char *file_spec, int flags, . . . );
                (DEC C Extension)

352.1  –  Arguments

 file_spec

    A null-terminated character string containing a valid file
    specification. If you specify a directory in the file_spec and
    it is a search list that contains an error, VSI C interprets
    it as a file open error.

    If the file_spec parameter refers to a symbolic link, the open
    function opens the file pointed to by the symbolic link.

 flags

    The following values are defined in the <fcntl.h> header file:

    O_RDONLY   Open for reading only
    O_WRONLY   Open for writing only
    O_RDWR     Open for reading and writing
    O_NDELAY   Open for asynchronous input
    O_APPEND   Append on each write
    O_CREAT    Create a file if it does not exist
    O_TRUNC    Create a new version of this file
    O_EXCL     Error if attempting to create existing file

    These flags are set using the bitwise OR operator (|)  to
    separate specified flags.

    Opening a file with O_APPEND causes each write on the file to
    be appended to the end. (In contrast, with the VAX C RTL the
    behavior of files opened in append mode was to start at EOF and,
    thereafter, write at the current file position.)

    If O_TRUNC is specified and the file exists, open creates a new
    file by incrementing the version number by 1, leaving the old
    version in existence.

    If O_CREAT is set and the named file does not exist, the C RTL
    creates it with any attributes specified in the fourth and
    subsequent arguments ( . . . ). If O_EXCL is set with O_CREAT and
    the named file exists, the attempted open returns an error.

 mode

    An unsigned value that specifies the file-protection mode. The
    compiler performs a bitwise AND operation on the mode and the
    complement of the current protection mode.

    You can construct modes by using the bitwise OR operator (|)  to
    separate specified modes. The modes are:

    0400   OWNER:READ
    0200   OWNER:WRITE
    0100   OWNER:EXECUTE
    0040   GROUP:READ
    0020   GROUP:WRITE
    0010   GROUP:EXECUTE
    0004   WORLD:READ
    0002   WORLD:WRITE
    0001   WORLD:EXECUTE

    The system is given the same access privileges as the owner. A
    WRITE privilege also implies a DELETE privilege.

  . . .

    Optional file attribute arguments. The file attribute arguments
    are the same as those used in the creat function. For more
    information, see the creat function.

352.2  –  Description

    If a version of the file exists, a new file created with open
    inherits certain attributes from the existing file unless
    those attributes are specified in the open call. The following
    attributes are inherited: record format, maximum record size,
    carriage control, and file protection.

                                  NOTES

       o  If you intend to do random writing to a file, the file
          must be opened for update by specifying a flags value of
          O_RDWR.

       o  To create files with OpenVMS RMS default protections
          by using the UNIX system-call functions umask, mkdir,
          creat, and open, call mkdir, creat, and open with a
          file-protection mode argument of 0777 in a program that
          never specifically calls umask. These default protections
          include correctly establishing protections based on ACLs,
          previous versions of files, and so on.

          In programs that do vfork/exec calls, the new process
          image inherits whether umask has ever been called or not
          from the calling process image. The umask setting and
          whether the umask function has ever been called are both
          inherited attributes.

    See also creat, read, write, close, dup, dup2, and lseek.

352.3  –  Return Values

    x                  A nonnegative file descriptor number.
    -1                 Indicates that the file does not exist, that
                       it is protected against reading or writing, or
                       that it cannot be opened for another reason.

352.4  –  Example

        #include <unixio.h>
        #include <fcntl.h>
        #include <stdlib.h>

        main()
        {
            int file,
                stat;
            int flags;

            flags = O_
 RDWR;  /*  Open for read and write,            */
                             /*  with user default file protection,  */
                             /*  with max fixed record size of 2048, */
                             /*  and a block size of 2048 bytes.     */

        file=open("file.dat", flags, 0, "rfm=fix", "mrs=2048", "bls=2048");
            if (file == -1)
                perror("OPEN error"), exit(1);

            close(file);
        }

353  –  opendir

    Opens a specified directory.

    Format

      #include  <dirent.h>

      DIR *opendir  (const char *dir_name);

353.1  –  Argument

 dir_name

    The name of the directory to be opened.

353.2  –  Description

    The opendir function opens the directory specified by dir_name
    and associates a directory stream with it. The dir_name argument
    can be specified in OpenVMS style or UNIX style. The directory
    stream is positioned at the first entry. The type DIR, defined
    in the <dirent.h> header file, represents a directory stream.
    A directory stream is an ordered sequence of all the directory
    entries in a particular directory.

    The opendir function also returns a pointer to identify the
    directory stream in subsequent operations. The NULL pointer is
    returned when the directory named by dir_name cannot be accessed,
    or when not enough memory is available to hold the entire stream.

                                  NOTES

       o  An open directory must always be closed with the closedir
          function to ensure that the next attempt to open that
          directory is successful. The opendir function should be
          used with readdir, closedir, and rewinddir to examine the
          contents of the directory.

       o  The opendir function supports UNIX style path name
          specifications.

353.3  –  Example

      See the program example in the description of closedir.

353.4  –  Return Values

    x                  A pointer to an object of type DIR.
    NULL               Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - Search permission is denied
                          for any component of dir_name or read
                          permission is denied for dir_name.

                       o  ENAMETOOLONG - The length of the dir_name
                          string exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX.

                       o  ENOENT - The dir_name argument points to
                          the name of a file that does not exist, or
                          is an empty string.

354  –  overlay

    Nondestructively superimposes win1 on win2. The function writes
    the contents of win1 that will fit onto win2 beginning at the
    starting coordinates of both windows. Blanks on win1 leave
    the contents of the corresponding space on win2 unaltered. The
    overlay function copies as much of a window's box as possible.

    Format

      #include  <curses.h>

      int overlay  (WINDOW *win1, WINDOW *win2);

354.1  –  Arguments

 win1

    A pointer to the window.

 win2

    A pointer to the window.

354.2  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

355  –  overwrite

    Destructively writes the contents of win1 on win2.

    Format

      #include  <curses.h>

      int overwrite  (WINDOW *win1, WINDOW *win2);

355.1  –  Arguments

 win1

    A pointer to the window.

 win2

    A pointer to the window.

355.2  –  Description

    The overwrite function writes the contents of win1 that will fit
    onto win2 beginning at the starting coordinates of both windows.
    Blanks on win1 are written on win2 as blanks. This function
    copies as much of a window's box as possible.

355.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates failure.

356  –  pathconf

    Retrieves file implementation characteristics.

    Format

      #include  <unistd.h>

      long int pathconf  (const char *path, int name);

356.1  –  Arguments

 path

    The pathname of a file or directory.

 name

    The configuration attribute to query. If this attribute is
    not applicable to the file specified by the path argument, the
    pathconf function returns an error.

356.2  –  Description

    The pathconf function allows an application to determine the
    characteristics of operations supported by the file system
    underlying the filenamed by path. Read, write, or execute
    permission of the named file is not required, but you must be
    able to search all directories in the path leading to the file.

    Symbolic values for the name argument are defined in the
    <unistd.h> header file, as follows:

    _PC_LINK_MAX    The maximum number of links to the file. If the
                    path argument refers to a directory, the value
                    returned applies to the directory itself.
    _PC_MAX_CANON   The maximum number of bytes in a canonical
                    input line. This is applicable only to terminal
                    devices.
    _PC_MAX_INPUT   The number of types allowed in an input queue.
                    This is applicable only to terminal devices.
    _PC_NAME_MAX    Maximum number of bytes in a filename (not
                    including a terminating null). The byte range
                    value is between 13 and 255. This is applicable
                    only to a directory file. The value returned
                    applies to filenames within the directory.
    _PC_PATH_MAX    Maximum number of bytes in a pathname (not
                    including a terminating null). The value is never
                    larger than 65,535. This is applicable only to a
                    directory file. The value returned is the maximum
                    length of a relative pathname when the specified
                    directory is the working directory.
    _PC_PIPE_BUF    Maximum number of bytes guaranteed to be written
                    atomically. This is applicable only to a FIFO.
                    The value returned applies to the referenced
                    object. If the path argument refers to a
                    directory, the value returned applies to any
                    FIFO that exists or can be created within the
                    directory.
    _PC_CHOWN_      This is applicable only to a directory file. The
    RESTRICTED      value returned applies to any files (other than
                    directories) that exist or can be created within
                    the directory.
    _PC_NO_TRUNC    Returns 1 if supplying a component name longer
                    than allowed by NAME_MAX causes an error. Returns
                    0 (zero) if long component names are truncated.
                    This is applicable only to a directory file.
    _PC_VDISABLE    This is always 0 (zero); no disabling character
                    is defined. This is applicable only to a terminal
                    device.

356.3  –  Return Values

    x                  Resultant value of the configuration attribute
                       specified in name.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  EACCES - Search permission is denied for a
                          component of the path prefix.

                       o  EINVAL - The name argument specifies an
                          unknown or inapplicable characteristic.

                       o  EFAULT - The path argument is an invalid
                          address.

                       o  ENAMETOOLONG - The length of the path
                          string exceeds PATH_MAX or a pathname
                          component is longer than NAME_MAX.

                       o  ENOENT - The named file does not exist
                          or the path argument points to an empty
                          string.

                       o  ENOTDI - A component of the path prefix is
                          not a directory.

357  –  pause

    Suspends the calling process until delivery of a signal whose
    action is either to execute a signal-catching function or to
    terminate the process.

    Format

      #include  <unistd.h>

      int pause  (void);

357.1  –  Description

    The pause function suspends the calling process until delivery
    of a signal whose action is either to execute a signal-catching
    function or to terminate the process.

    If the action is to terminate the process, pause does not return.

    If the action is to execute a signal-catching function, pause
    returns after the signal-catching function returns.

357.2  –  Return Value

                       Since the pause function suspends process
                       execution indefinitely unless interrupted by
                       a signal, there is no successful completion
                       return value.
    -1                 In cases where pause returns, the return value
                       is -1, and errno is set to EINTR.

358  –  pclose

    Closes a pipe to a process.

    Format

      #include  <stdio.h>

      int pclose  (FILE *stream);

358.1  –  Arguments

 stream

    A pointer to a FILE structure for an open pipe returned by a
    previous call to the popen function.

358.2  –  Description

    The pclose function closes a pipe between the calling program and
    a shell command to be executed. Use pclose to close any stream
    you have opened with popen. The pclose function waits for the
    associated process to end, and then returns the exit status of
    the command. See the description of waitpid for information on
    interpreting the exit status.

    Beginning with OpenVMS Version 7.3-1, when compiled with the
    _VMS_WAIT macro defined, the pclose function returns the OpenVMS
    completion code of the child process.

    See also popen.

358.3  –  Return Values

    x                  Exit status of child.
    -1                 Indicates an error. The stream argument is not
                       associated with a popen function. errno is set
                       to the following:

                       o  ECHILD - cannot obtain the status of the
                          child process.

359  –  perror

    Writes a short error message to stderr describing the current
    value of errno.

    Format

      #include  <stdio.h>

      void perror  (const char *str);

359.1  –  Argument

 str

    Usually the name of the program that caused the error.

359.2  –  Description

    The perror function uses the error number in the external
    variable errno to retrieve the appropriate locale-dependent
    error message. The function writes out the message as follows:
    str (a user-supplied prefix to the error message), followed by a
    colon and a space, followed by the message itself, followed by a
    new-line character.

    See also strerror.

359.3  –  Example

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

        main(argc, argv)
            int argc;
            char *argv[];
        {
            FILE *fp;

            fp = fopen(argv[1], "r");   /* Open an input file. */
            if (fp == NULL) {

                /* If the fopen call failed, perror prints out a        */
                /* diagnostic:                                          */
                /*                                                      */
                /*  "open: <error message>"                             */
                /*  This error message provides a diagnostic explaining */
                /*  the cause of the failure.                           */

                perror("open");
                exit(EXIT_FAILURE);
            }
            else
                fclose(fd) ;
        }

360  –  pipe

    Creates a temporary mailbox that can be used to read and write
    data between a parent and child process. The channels through
    which the processes communicate are called a pipe.

    Format

      #include  <unistd.h>

      int pipe  (int array_fdscptr[2]); (ISO POSIX-1)

      int pipe  (int array_fdscptr[2], . . . ); (DEC C Extension)

360.1  –  Arguments

 array_fdscptr

    An array of file descriptors. A pipe is implemented as an
    array of file descriptors associated with a mailbox. These
    mailbox descriptors are special in that these are the only file
    descriptors which, when passed to the isapipe function, will
    return 1.

    The file descriptors are allocated in the following way:

    o  The first available file descriptor is assigned to writing,
       and the next available file descriptor is assigned to reading.

    o  The file descriptors are then placed in the array in reverse
       order; element 0 contains the file descriptor for reading, and
       element 1 contains the file descriptor for writing.

  . . .

    Represents three optional, positional arguments, flag, bufsize,
    and bufquota:

 flag

    An optional argument used as a bitmask.

    If either the O_NDELAY or O_NONBLOCK bit is set, the I/O
    operations to the mailbox through array_fdscptr file descriptors
    terminate immediately, rather than waiting for another process.

    If, for example, the O_NDELAY bit is set and the child issues
    a read request to the mailbox before the parent has put any
    data into it, the read terminates immediately with 0 status.
    If neither the O_NDELAY nor O_NONBLOCK bit is set, the child
    will be waiting on the read until the parent writes any data into
    the mailbox. This is the default behavior if no flag argument is
    specified.

    The values of O_NDELAY and O_NONBLOCK are defined in the
    <fcntl.h> header file. Any other bits in the flag argument are
    ignored. You must specify this argument if the second optional,
    positional argument bufsize is specified. If the flag argument
    is needed only to allow specification of the bufsize argument,
    specify flag as 0.

 bufsize

    Optional argument of type int that specifies the size of the
    mailbox, in bytes. Specify a value from 512 to 65535.

    If you specify 0 or omit this argument, the operating system
    creates a mailbox with a default size of 512 bytes.

    If you specify a value less than 0 or larger than 65535, the
    results are unpredictable.

    If you do specify this argument, be sure to precede it with a
    flag argument.

    The DECC$PIPE_BUFFER_SIZE feature logical can also be used to
    specify the size of the mailbox. If bufsize is supplied, it takes
    precedence over the value of DECC$PIPE_BUFFER_SIZE. Otherwise,
    the value of DECC$PIPE_BUFFER_SIZE is used.

    If neither bufsize nor DECC$PIPE_BUFFER_SIZE is specified, the
    default buffer size of 512 is used.

 bufquota

    Optional argument of type int that specifies the buffer quota of
    the pipe's mailbox. Specify a value from 512 to 2147483647.

    OpenVMS Version 7.3-2 added this argument. In previous OpenVMS
    versions, the buffer quota was equal to the buffer size.

    The DECC$PIPE_BUFFER_QUOTA feature logical can also be used to
    specify the buffer quota. If the optional bufquota argument of
    the pipe function is supplied, it takes precedence over the value
    of DECC$PIPE_BUFFER_QUOTA. Otherwise, the value of DECC$PIPE_
    BUFFER_QUOTA is used.

    If neither bufquota nor DECC$PIPE_BUFFER_QUOTA is specified, then
    the buffer quota defaults to the buffer size.

360.2  –  Description

    The mailbox used for the pipe is a temporary mailbox. The mailbox
    is not deleted until all processes that have open channels to
    that mailbox close those channels. The last process that closes a
    pipe writes a message to the mailbox, indicating the end-of-file.

    The mailbox is created by using the $CREMBX system service,
    specifying the following characteristics:

    o  A maximum message length of 512 characters

    o  A buffer quota of 512 characters

    o  A protection mask granting all privileges to USER and GROUP
       and no privileges to SYSTEM or WORLD

    The buffer quota of 512 characters implies that you cannot write
    more than 512 characters to the mailbox before all or part of the
    mailbox is read. Since a mailbox record is slightly larger than
    the data part of the message that it contains, not all of the
    512 characters can be used for message data. You can increase the
    size of the buffer by specifying an alternative size using the
    optional, third argument to the pipe function. A pipe under the
    OpenVMS system is a stream-oriented file with no carriage-control
    attributes. It is fully buffered by default in the C RTL.
    A mailbox used as a pipe is different than a mailbox created by
    the application. A mailbox created by the application defaults
    to a record-oriented file with carriage return, carriage control.
    Additionally, writing a zero-length record to a mailbox writes an
    EOF, as does each close of the mailbox. For a pipe, only the last
    close of a pipe writes an EOF.

    The pipe is created by the parent process before vfork and
    an exec function are called. By calling pipe first, the child
    inherits the open file descriptors for the pipe. You can then use
    the getname function to return the name of the mailbox associated
    with the pipe, if this information is desired. The mailbox name
    returned by getname has the format _MBAnnnn: (Alpha only) or _
    MBAnnnnn: (Integrity servers(ONLY)) , where nnnn or nnnnn is a
    unique number.

    Both the parent and the child need to know in advance which file
    descriptors will be allocated for the pipe. This information
    cannot be retrieved at run time. Therefore, it is important to
    understand how file descriptors are used in any VSI C for
    OpenVMS program.

    File descriptors 0, 1, and 2 are open in a VSI C for OpenVMS
    program for stdin (SYS$INPUT), stdout (SYS$OUTPUT), and stderr
    (SYS$ERROR), respectively. Therefore, if no other files are open
    when pipe is called, pipe assigns file descriptor 3 for writing
    and file descriptor 4 for reading. In the array returned by pipe,
    4 is placed in element 0 and 3 is placed in element 1.

    If other files have been opened, pipe assigns the first
    available file descriptor for writing and the next available
    file descriptor for reading. In this case, the pipe does not
    necessarily use adjacent file descriptors. For example, assume
    that two files have been opened and assigned to file descriptors
    3 and 4 and the first file is then closed. If pipe is called at
    this point, file descriptor 3 is assigned for writing and file
    descriptor 5 is assigned for reading. Element 0 of the array will
    contain 5 and element 1 will contain 3.

    In large applications that do large amounts of I/O, it gets
    more difficult to predict which file descriptors are going to
    be assigned to a pipe; and, unless the child knows which file
    descriptors are being used, it will not be able to read and write
    successfully from and to the pipe.

    One way to be sure that the correct file descriptors are being
    used is to use the following procedure:

    1. Choose two descriptor numbers that will be known to both the
       parent and the child. The numbers should be high enough to
       account for any I/O that might be done before the pipe is
       created.

    2. Call pipe in the parent at some point before calling an exec
       function.

    3. In the parent, use dup2 to assign the file descriptors
       returned by pipe to the file descriptors you chose. This now
       reserves those file descriptors for the pipe; any subsequent
       I/O will not interfere with the pipe.

    You can read and write through the pipe using the UNIX I/O
    functions read and write, specifying the appropriate file
    descriptors. As an alternative, you can issue fdopen calls to
    associate file pointers with these file descriptors so that you
    can use the Standard I/O functions (fread and fwrite).

    Two separate file descriptors are used for reading from and
    writing to the pipe, but only one mailbox is used so some I/O
    synchronization is required. For example, assume that the parent
    writes a message to the pipe. If the parent is the first process
    to read from the pipe, then it will read its own message back as
    shown in Reading and Writing to a Pipe.

                                   NOTE

       For added UNIX portability, you can use the following
       feature logicals to control the behavior of the C RTL pipe
       implementation:

       o  Define the DECC$STREAM_PIPE feature logical name to
          ENABLE to direct the pipe function to use stream I/O
          instead of record I/O.

       o  Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical
          to ENABLE to prevent CR/LF carriage control from being
          added to pipe records for pipes opened with the popen
          function. Be aware that enabling this feature might
          result in undesired behavior from other functions such
          as gets that rely on the carriage-return character.

    Figure REF-1  Reading and Writing to a Pipe

360.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error.

361  –  poll

    Provides users with a mechanism for multiplexing input/output
    over a set of file descriptors that reference open streams.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <poll.h>

      int poll  (struct pollfd filedes [], nfds_t nfds, int timeout);

361.1  –  Argument

 filedes

    Points to an array of pollfd structures, one for each file
    descriptor of interest. Each pollfd structure includes the
    following members:

       int fd - The file descriptor
       int events - The requested conditions
       int revents - The reported conditions

 nfds

    The number of pollfd structures in the filedes array.

 timeout

    The maximum length of time (in milliseconds) to wait for at least
    one of the specified events to occur.

361.2  –  Description

    The poll function provides users with a mechanism for
    multiplexing input/output over a set of file descriptors that
    reference open streams. For each member of the array pointed
    to by filedes, poll examines the given file descriptor for the
    event(s) specified in events. The poll function identifies those
    streams on which an application can send or receive messages, or
    on which certain events have occurred.

    The filedes parameter specifies the file descriptor to be
    examined and the events of interest for each file descriptor.
    It is a pointer to an array of pollfd structures. The fd member
    of each pollfd structure specifies an open file descriptor. The
    poll function uses the events member to determine what conditions
    to report for this file descriptor. If one or more of these
    conditions is true, the poll function sets the associated revents
    member.

    The events and revents members of each pollfd structure are
    bitmasks. The calling process sets the events bitmask, and poll
    sets the revents bitmasks. These bitmasks contain inclusive
    ORed combinations of condition options. The following condition
    options are defined:

       POLLERR - An error has occurred on the file descriptor. This
       option is only valid in the revents bitmask; it is not used in
       the events member.

       For STREAMS devices, if an error occurs on the file descriptor
       and the device is also disconnected, poll returns POLLERR;
       POLLERR takes precedence over POLLHUP.

       POLLHUP - The device has been disconnected. This event
       is mutually exclusive with POLLOUT; a stream can never be
       writable if a hangup occurred. However, this event and POLLIN,
       POLLRDNORM, POLLRDBAND or POLLPRI are not mutually exclusive.
       This option is only valid in the revents bitmask; it is
       ignored in the events member.

       POLLIN - Data other than high-priority data may be read
       without blocking. This option is set in revents even if the
       message is of zero length. In revents, this option is mutually
       exclusive with POLLPRI.

       POLLNVAL - The value specified for fd is invalid. This option
       is only valid in the revents member; it is ignored in the
       events member.

       POLLOUT - Normal (priority band equals 0) data may be written
       without blocking.

       POLLPRI - High-priority data may be received without blocking.
       This option is set in revents even if the message is of zero
       length. In revents, this option is mutually exclusive with
       POLLIN.

       POLLRDBAND - Data from a nonzero priority band may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLRDNORM - Normal data (priority band equals 0) may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLWRBAND - Priority data (priority band greater than 0)
       may be written. This event only examines bands that have been
       written to at least once.

       POLLWRNORM - Same as POLLOUT.

    The poll function ignores any pollfd structure whose fd member
    is less than 0 (zero). If the fd member of all pollfd structures
    is less than 0, the poll function will return 0 and have no other
    results.

    The conditions indicated by POLLNORM and POLLOUT are true if and
    only if at least one byte of data can be read or written without
    blocking. There are two exceptions: regular files, which always
    poll true for POLLNORM and POLLOUT, and pipes, when the rules
    for the operation specify to return zero in order to indicate
    end-of-file.

    The condition options POLLERR, POLLHUP, and POLLNVAL are always
    set in revents if the conditions they indicate are true for the
    specified file descriptor, whether or not these options are set
    in events.

    For each call to the poll function, the set of reportable
    conditions for each file descriptor consists of those conditions
    that are always reported, together with any further conditions
    for which options are set in events. If any reportable condition
    is true for any file descriptor, the poll function will return
    with options set in revents for each true condition for that file
    descriptor.

    If no reportable condition is true for any of the file
    descriptors, the poll function waits up to timeout milliseconds
    for a reportable condition to become true. If, in that time
    interval, a reportable condition becomes true for any of the file
    descriptors, poll reports the condition in the file descriptor's
    associated revents member and returns. If no reportable condition
    becomes true, poll returns without setting any revents bitmasks.

    If the timeout parameter is a value of -1, the poll function does
    not return until at least one specified event has occurred. If
    the value of the timeout parameter is 0 (zero), the poll function
    does not wait for an event to occur but returns immediately, even
    if no specified event has occurred.

    The behavior of the poll function is not affected by whether
    the O_NONBLOCK option is set on any of the specified file
    descriptors.

    The poll function supports regular files, terminal and pseudo-
    terminal devices, STREAMS-based files, FIFOs, and pipes. The
    behavior of poll on elements of file descriptors that refer to
    other types of files is unspecified.

    For sockets, a file descriptor for a socket that is listening for
    connections indicates it is ready for reading after connections
    are available. A file descriptor for a socket that is connecting
    asynchronously indicates it is ready for writing after a
    connection is established.

361.3  –  Return Values

    n                  Upon successful completion, a nonnegative
                       value is returned, indicating the number of
                       file descriptors for which poll has set the
                       revents bitmask.
    0                  poll has timed out and has not set any of the
                       revents bitmasks.
    -1                 An error occurred. errno is set to indicate
                       the error:

                       o  EAGAIN - Allocation of internal data
                          structures failed. A later call to the
                          poll function might complete successfully.

                       o  EINTR - A signal was intercepted during the
                          poll function, and the signal handler was
                          installed with an indication that functions
                          are not to be restarted.

                       o  EINVAL - The nfds parameter is greater than
                          OPEN_MAX, or one of the fd members refers
                          to a stream or multiplexer that is linked
                          (directly or indirectly) downstream from a
                          multiplexer.

362  –  popen

    Initiates a pipe to a process.

    Format

      #include  <stdio.h>

      FILE *popen  (const char *command, const char *type);

362.1  –  Arguments

 command

    A pointer to a null-terminated string containing a shell command
    line.

 type

    A pointer to a null-terminated string containing an I/O mode.
    Because open files are shared, you can use a type r command as
    an input filter and a type w command as an output filter. Specify
    one of the following values for the type argument:

    o  r-the calling program can read from the standard output of the
       command by reading from the returned file stream.

    o  w-the calling program can write to the standard input of the
       command by writing to the returned file stream.

362.2  –  Description

    The popen function creates a pipe between the calling program
    and a shell command awaiting execution. It returns a pointer to a
    FILE structure for the stream.

    The popen function uses the value of the DECC$PIPE_BUFFER_SIZE
    feature logical to set the buffer size of the mailbox it creates
    for the pipe. You can specify a DECC$PIPE_BUFFER_SIZE value of
    512 to 65024 bytes. If DECC$PIPE_BUFFER_SIZE is not specified,
    the default buffer size of 512 is used.

                                  NOTES

       o  When you use the popen function to invoke an output
          filter, beware of possible deadlock caused by output
          data remaining in the program buffer. You can avoid this
          by either using the setvbuf function to ensure that the
          output stream is unbuffered, or the fflush function to
          ensure that all buffered data is flushed before calling
          the pclose function.

       o  For added UNIX portability, you can use the following
          feature logicals to control the behavior of the C RTL
          pipe implementation:

          -  Define the DECC$STREAM_PIPE feature logical name to
             ENABLE to direct the pipe function to use stream I/O
             instead of record I/O.

          -  Define the DECC$POPEN_NO_CRLF_REC_ATTR feature logical
             to ENABLE to prevent CR/LF carriage control from being
             added to pipe records for pipes opened with the popen
             function. Be aware that enabling this feature might
             result in undesired behavior from other functions such
             as gets that rely on the carriage-return character.

    See also fflush, pclose, and setvbuf.

362.3  –  Return Values

    x                  A pointer to the FILE structure for the opened
                       stream.
    NULL               Indicates an error. Unable to create files or
                       processes.

363  –  pow

    Returns the first argument raised to the power of the second
    argument.

    Format

      #include  <math.h>

      double pow  (double x, double y);

      float powf  (float x, float y); (Integrity servers, Alpha)

      long double powl  (long double x, long double y);
                        (Integrity servers, Alpha)

363.1  –  Arguments

 x

    A floating-point base to be raised to an exponent y.

 y

    The exponent to which the base x is to be raised.

363.2  –  Description

    The pow functions raise a floating-point base x to a floating-
    point exponent y. The value of pow(x,y) is computed as e**(y
    ln(x)) for positive x.

    If x is 0 and y is negative, HUGE_VAL is returned and errno is
    set to ERANGE or EDOM.

363.3  –  Return Values

    x                  The result of the first argument raised to the
                       power of the second.
    1.0                The base is 0 and the exponent is 0.
    HUGE_VAL           The result overflowed; errno is set to ERANGE.
    HUGE_VAL           The base is 0 and the exponent is negative;
                       errno is set to ERANGE or EDOM.

363.4  –  Example

        #include <stdio.h>
        #include <math.h>
        #include <errno.h>

        main()
        {
            double x;

            errno = 0;

            x = pow(-3.0, 2.0);
            printf("%d, %f\n", errno, x);
        }

      This example program outputs the following:

        0, 9.000000

364  –  pread

    Reads bytes from a given position within a file without changing
    the file pointer.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      ssize_t pread  (int file_desc, void *buffer, size_t nbytes,

                     off_t offset);

364.1  –  Arguments

 file_desc

    A file descriptor that refers to a file currently opened for
    reading.

 buffer

    The address of contiguous storage in which the input data is
    placed.

 nbytes

    The maximum number of bytes involved in the read operation.

 offset

    The offset for the desired position inside the file.

364.2  –  Description

    The pread function performs the same action as read, except that
    it reads from a given position in the file without changing the
    file pointer. The first three arguments to pread are the same as
    for read, with the addition of a fourth argument offset for the
    desired position inside the file. An attempt to perform a pread
    on a file that is incapable of seeking results in an error.

364.3  –  Return Values

    n                  The number of bytes read.
    -1                 Upon failure, the file pointer remains
                       unchanged and pread sets errno to one of the
                       following values:

                       o  EINVAL - The offset argument is invalid.
                          The value is negative.

                       o  EOVERFLOW - The file is a regular file, and
                          an attempt was made to read or write at or
                          beyond the offset maximum associated with
                          the file.

                       o  ENXIO - A request was outside the
                          capabilities of the device.

                       o  ESPIPE - fildes is associated with a pipe
                          or FIFO.

365  –  printf

    Performs formatted output from the standard output (stdout).

    Format

      #include  <stdio.h>

      int printf  (const char *format_spec, . . . );

365.1  –  Arguments

 format_spec

    Characters to be written literally to the output or converted as
    specified in the . . . arguments.

  . . .

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

365.2  –  Return Values

    x                  The number of bytes written.
    Negative value     Indicates that an output error occurred.
                       The function sets errno. For a list of errno
                       values set by this function, see fprintf.

366  –  [w]printw

    Perform a printf in the specified window, starting at the current
    position of the cursor. The printw function acts on the stdscr
    window.

    Format

      #include  <curses.h>

      printw  (char *format_spec, . . . );

      int wprintw  (WINDOW *win, char *format_spec, . . . );

366.1  –  Arguments

 win

    A pointer to the window.

 format_spec

    A pointer to the format specification string.

  . . .

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

366.2  –  Description

    The formatting specification (format_spec) and the other
    arguments are identical to those used with the printf function.

    The printw and wprintw functions format and then print the
    resultant string to the window using the addstr function. For
    more information, see the printf and scrollok functions in this
    section.

366.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the window
                       scroll illegally.

367  –  putc

    The putc macro writes a single character to a specified file.

    Format

      #include  <stdio.h>

      int putc  (int character, FILE *file_ptr);

367.1  –  Arguments

 character

    The character to be written.

 file_ptr

    A file pointer to the output stream.

367.2  –  Description

    The putc macro writes the byte character (converted to an
    unsigned char) to the output specified by the file_ptr parameter.
    The byte is written at the position at which the file pointer
    is currently pointing (if defined) and advances the indicator
    appropriately. If the file cannot support positioning requests,
    or if the output stream was opened with append mode, the byte is
    appended to the output stream.

    Since putc is a macro, a file pointer argument with side effects
    (for example, putc (ch, *f++)) might be evaluated incorrectly. In
    such a case, use the fputc function instead.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also putc_unlocked.

367.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    EOF                Indicates output errors.

368  –  putc_unlocked

    Same as putc, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int putc_unlocked  (int character, FILE *file_ptr);

368.1  –  Argument

 character

    The character to be written.

 file_ptr

    A file pointer to the output stream.

368.2  –  Description

    The reentrant version of the putc macro is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the stream. The unlocked version of this
    call, putc_unlocked can be used to avoid the overhead. The putc_
    unlocked macro is functionally identical to the putc macro,
    except that it is not required to be implemented in a thread-
    safe manner. The putc_unlocked macro can be safely used only
    within a scope that is protected by the flockfile and funlockfile
    functions used as a pair. The caller must ensure that the stream
    is locked before putc_unlocked is used.

    Since putc_unlocked is a macro, a file pointer argument with side
    effects might be evaluated incorrectly. In such a case, use the
    fputc_unlocked function instead.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also flockfile, ftrylockfile, and funlockfile.

368.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    EOF                Indicates the end-of-file or an error.

369  –  putchar

    Writes a single character to the standard output (stdout) and
    returns the character.

    Format

      #include  <stdio.h>

      int putchar  (int character);

369.1  –  Argument

 character

    An object of type int.

369.2  –  Description

    The putchar function is identical to fputc (character, stdout).

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

369.3  –  Return Values

    character          Indicates success.
    EOF                Indicates output errors.

370  –  putchar_unlocked

    Same as putchar, except used only within a scope protected by
    flockfile and funlockfile.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int putchar_unlocked  (int character);

370.1  –  Argument

 character

    An object of type int.

370.2  –  Description

    The reentrant version of the putchar function is locked against
    multiple threads calling it simultaneously. This incurs overhead
    to ensure integrity of the output stream. The unlocked version of
    this call, putchar_unlocked can be used to avoid the overhead.
    The putchar_unlocked function is functionally identical to
    the putchar function, except that it is not required to be
    implemented in a thread-safe manner. The putchar_unlocked
    function can be safely used only within a scope that is protected
    by the flockfile and funlockfile functions used as a pair. The
    caller must ensure that the stream is locked before putchar_
    unlocked is used.

    Compiling with the __UNIX_PUTC macro defined enables an
    optimization that uses a faster, inlined version of this
    function.

    See also flockfile, ftrylockfile, and funlockfile.

370.3  –  Return Values

    x                  The next character from stdin, converted to
                       int.
    EOF                Indicates the end-of-file or an error.

371  –  putenv

    Sets an environmental variable.

    Format

      #include  <stdlib.h>

      int putenv  (const char *string);

371.1  –  Argument

 string

    A pointer to a name=value string.

371.2  –  Description

    The putenv function sets the value of an environment variable
    by altering an existing variable or by creating a new one. The
    string argument points to a string of the form name=value, where
    name is the environment variable and value is the new value for
    it.

    The string pointed to by string becomes part of the environment,
    so altering the string changes the environment. When a new
    string-defining name is passed to putenv, the space used by
    string is no longer used.

                                  NOTES

       o  The putenv function manipulates the environment pointed
          to by the environ external variable, and can be used with
          getenv. However, the third argument to the main function
          (the environment pointer), is not changed.

          The putenv function uses the malloc function to enlarge
          the environment.

          A potential error is to call putenv with an automatic
          variable as the argument, then exit the calling function
          while string is still part of the environment.

       o  Do not use the setenv, getenv, and putenv functions
          to manipulate symbols and logicals. Instead, use the
          OpenVMS library calls lib$set_logical, lib$get_logical,
          lib$set_symbol, and lib$get_symbol. The *env functions
          deliberately provide UNIX behavior, and are not a
          substitute for these OpenVMS runtime library calls.

          OpenVMS DCL symbols, not logical names, are the closest
          analog to environment variables on UNIX systems. While
          getenv is a mechanism to retrieve either a logical name
          or a symbol, it maintains an internal cache of values for
          use with setenv and subsequent getenv calls. The setenv
          function does not write or create DCL symbols or OpenVMS
          logical names.

          This is consistent with UNIX behavior. On UNIX systems,
          setenv does not change or create any symbols that will be
          visible in the shell after the program exits.

371.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error. errno is set to ENOMEM-
                       Not enough memory available to expand the
                       environment list.

371.4  –  Restriction

    The putenv function cannot take a 64-bit address.

372  –  puts

    Writes a character string to the standard output (stdout)
    followed by a new-line character.

    Format

      #include  <stdio.h>

      int puts  (const char *str);

372.1  –  Argument

 str

    A pointer to a character string.

372.2  –  Description

    The puts function does not copy the terminating null character to
    the output stream.

372.3  –  Return Values

    Nonnegative value  Indicates success.
    EOF                Indicates output errors.

373  –  putw

    Writes characters to a specified file.

    Format

      #include  <stdio.h>

      int putw  (int integer, FILE *file_ptr);

373.1  –  Arguments

 integer

    An object of type int or long.

 file_ptr

    A file pointer.

373.2  –  Description

    The putw function writes four characters to the output file as an
    int. No conversion is performed.

373.3  –  Return Values

    integer            Indicates success.
    EOF                Indicates output errors.

374  –  putwc

    Converts a wide character to its corresponding multibyte value,
    and writes the result to a specified file.

    Format

      #include  <wchar.h>

      wint_t putwc  (wint_t wc, FILE *file_ptr);

374.1  –  Arguments

 wc

    An object of type wint_t.

 file_ptr

    A file pointer.

374.2  –  Description

    Since putwc might be implemented as a macro, a file pointer
    argument with side effects (for example putwc (wc, *f++)) might
    be evaluated incorrectly. In such a case, use the fputwc function
    instead.

    See also fputwc.

374.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    WEOF               Indicates an output error. The function sets
                       errno. For a list of the errno values set by
                       this function, see fputwc.

375  –  putwchar

    Writes a wide character to the standard output (stdout) and
    returns the character.

    Format

      #include  <wchar.h>

      wint_t putwchar  (wint_t wc);

375.1  –  Arguments

 wc

    An object of type wint_t.

375.2  –  Description

    The putwchar function is identical to fputwc(wc, stdout).

375.3  –  Return Values

    x                  The character written to the file. Indicates
                       success.
    WEOF               Indicates an output error. The function sets
                       errno. For a list of the errno values set by
                       this function, see fputwc.

376  –  pwrite

    Writes into a given position within a file without changing the
    file pointer.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      ssize_t pwrite  (int file_desc, const void *buffer, size_t
                      nbytes, off_t offset);

376.1  –  Arguments

 file_desc

    A file descriptor that refers to a file currently opened for
    writing or updating.

 buffer

    The address of contiguous storage from which the output data is
    taken.

 nbytes

    The maximum number of bytes involved in the write operation.

 offset

    The offset for the desired position inside the file.

376.2  –  Description

    The pwrite function performs the same action as write, except
    that it writes into a given position in the file without changing
    the file pointer. The first three arguments to pwrite are the
    same as for write, with the addition of a fourth argument offset
    for the desired position inside the file.

376.3  –  Return Values

    n                  The number of bytes written.
    -1                 Upon failure, the file pointer remains
                       unchanged and pwrite sets errno to one of
                       the following values:

                       o  EINVAL - The offset argument is invalid.
                          The value is negative.

                       o  ESPIPE - fildes is associated with a pipe
                          or FIFO.

377  –  qabs,llabs

    Returns the absolute value of an integer as an __int64. llabs is
    a synonym for qabs.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      __int64 qabs  (__int64  j);

      __int64 llabs  (__int64  j);

377.1  –  Argument

 j

    A value of type __int64.

378  –  qdiv,lldiv

    Returns the quotient and the remainder after the division of its
    arguments. lldiv is a synonym for qdiv.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      qdiv_t qdiv  (__int64 numer, __int64  denom);

      lldiv_t lldiv  (__int64 numer, __int64  denom);

378.1  –  Arguments

 numer

    A numerator of type __int64.

 denom

    A denominator of type __int64.

378.2  –  Description

    The types qdiv_t and lldiv_t are defined in the <stdlib.h> header
    file as follows:

    typedef struct
             {
             __int64 quot, rem;
             } qdiv_t, lldiv_t;

379  –  qsort

    Sorts an array of objects in place. It implements the quick-sort
    algorithm.

    Format

      #include  <stdlib.h>

      void qsort  (void *base, size_t nmemb, size_t size, int
                  (*compar) (const void *, const void *));

379.1  –  Function Variants

    The qsort function has variants named _qsort32 and _qsort64 for
    use with 32-bit and 64-bit pointer sizes, respectively.

379.2  –  Arguments

 base

    A pointer to the first member of the array. The pointer should be
    of type pointer-to-element and cast to type pointer-to-character.

 nmemb

    The number of objects in the array.

 size

    The size of an object, in bytes.

 compar

    A pointer to the comparison function.

379.3  –  Description

    Two arguments are passed to the comparison function pointed to
    by compar. The two arguments point to the objects being compared.
    Depending on whether the first argument is less than, equal to,
    or greater than the second argument, the comparison function
    returns an integer less then, equal to, or greater than 0.

    The comparison function compar need not compare every byte, so
    arbitrary data might be contained in the objects in addition to
    the values being compared.

    The order in the output of two objects that compare as equal is
    unpredictable.

380  –  raise

    Generates a specified software signal. Generating a signal causes
    the action routine established by the signal, ssignal, or sigvec
    function to be invoked.

    Format

      #include  <signal.h>

      int raise  (int sig); (ANSI C)

      int raise  (int sig[, int sigcode]); (DEC C Extension)

380.1  –  Arguments

 sig

    The signal to be generated.

 sigcode

    An optional signal code, available only when not compiling in
    strict ANSI C mode. For example, signal SIGFPE-the arithmetic
    trap signal-has 10 different codes, each representing a different
    type of arithmetic trap.

    The signal codes can be represented by mnemonics or numbers. The
    arithmetic trap codes are represented by the numbers 1 to 10;
    the SIGILL codes are represented by the numbers 0 to 2. The code
    values are defined in the <signal.h> header file.

380.2  –  Description

    Calling the raise function has one of the following results:

    o  If raise specifies a sig argument that is outside the range
       defined in the <signal.h> header file, then the raise function
       returns 0, and the errno variable is set to EINVAL.

    o  If signal, ssignal, or sigvec establishes SIG_DFL (default
       action) for the signal, then the functions do not return. The
       image is exited with the OpenVMS error code corresponding to
       the signal.

    o  If signal, ssignal, or sigvec establishes SIG_IGN (ignore
       signal) as the action for the signal, then raise returns its
       argument, sig.

    o  signal, ssignal, or sigvec must establish an action function
       for the signal. That function is called and its return value
       is returned by raise.

    See also gsignal, signal, ssignal, and sigvec.

380.3  –  Return Values

    0                  If successful.
    nonzero            If unsuccessful.

381  –  rand

    Returns pseudorandom numbers in the range 0 to 2[31] - 1.

    Format

      #include  <stdlib.h>

      int rand  (void);

      int rand_r  (unsigned int seed); (Integrity servers, Alpha)

381.1  –  Argument

 seed

    An initial seed value.

381.2  –  Description

    The rand function computes a sequence of pseudorandom integers in
    the range 0 to {RAND_MAX} with a period of at least 2[32].

    The rand_r function computes a sequence of pseudorandom integers
    in the range 0 to {RAND_MAX}. The value of the {RAND_MAX} macro
    will be at least 32767.

    If rand_r is called with the same initial value for the object
    pointed to by seed and that object is not modified between
    successive returns and calls to rand_r, the same sequence is
    generated.

    See also srand.

    For other random-number algorithms, see random and all the *48
    functions.

381.3  –  Return Value

    n                  A pseudorandom number.

382  –  random

    Generates pseudorandom numbers in a more random sequence.

    Format

      #include  <stdlib.h>

      long int random  (void);

382.1  –  Description

    The random function is a random-number generator that has
    virtually the same calling sequence and initialization properties
    as the rand function, but produces sequences that are more
    random. The low 12 bits generated by rand go through a cyclic
    pattern. All bits generated by random are usable. For example,
    random() &1 produces a random binary value.

    The random function uses a nonlinear, additive-feedback, random-
    number generator employing a default state-array size of 31
    integers to return successive pseudorandom numbers in the range
    from 0 to 231 - 1. The period of this random-number generator is

    approximately 16*(231 -1). The size of the state array determines

    the period of the random-number generator. Increasing the state
    array size increases the period.

    With a full 256 bytes of state information, the period of the
    random-number generator is greater than 269, and is sufficient

    for most purposes.

    Like the rand function, the random function produces by default a
    sequence of numbers that you can duplicate by calling the srandom
    function with a value of 1 as the seed. 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, srandom, setstate, and initstate.

382.2  –  Return Value

    n                  A random number.

383  –  [no]raw

    Raw mode only works with the Curses input routines [w]getch
    and [w]getstr. Raw mode is not supported with the C RTL
    emulation of UNIX I/O, Terminal I/O, or Standard I/O.

    Format

      #include  <curses.h>

      raw()

      noraw()

383.1  –  Description

    Raw mode reads are satisfied on one of two conditions: after
    a minimum number (5) of characters are input at the terminal
    or after waiting a fixed time (10 seconds) from receipt of any
    characters from the terminal.

383.2  –  Example

        /* Example of standard and raw input in Curses package. */

        #include <curses.h>

        main()
        {
            WINDOW *win1;
            char vert = '.',
                 hor = '.',
                 str[80];

            /* Initialize standard screen, turn echo off.  */

            initscr();
            noecho();

            /* Define a user window.  */

            win1 = newwin(22, 78, 1, 1);
            leaveok(win1, TRUE);
            leaveok(stdscr, TRUE);

            box(stdscr, vert, hor);

            /* Reset the video, refresh(redraw) both windows. */

            mvwaddstr(win1, 2, 2, "Test line terminated input");
            wrefresh(win1);

            /* Do some input and output it. */
            nocrmode();
            wgetstr(win1, str);

            mvwaddstr(win1, 5, 5, str);
            mvwaddstr(win1, 7, 7, "Type something to clear screen");
            wrefresh(win1);

            /* Get another character then delete the window. */

            wgetch(win1);
            wclear(win1);

            mvwaddstr(win1, 2, 2, "Test raw input");
            wrefresh(win1);

            /* Do some raw input 5 chars or timeout and output it. */
            raw();
            getstr(str);
            noraw();
            mvwaddstr(win1, 5, 5, str);
            mvwaddstr(win1, 7, 7, "Raw input completed");
            wrefresh(win1);

            endwin();
        }

384  –  read

    Reads bytes from a file and places them in a buffer.

    Format

      #include  <unistd.h>

      ssize_t read  (int file_desc, void *buffer, size_t nbytes);
                    (ISO POSIX-1)

      int read  (int file_desc, void *buffer, int nbytes);
                (Compatibility)

384.1  –  Arguments

 file_desc

    A file descriptor. The specified file descriptor must refer to a
    file currently opened for reading.

 buffer

    The address of contiguous storage in which the input data is
    placed.

 nbytes

    The maximum number of bytes involved in the read operation.

384.2  –  Description

    The read function returns the number of bytes read. The return
    value does not necessarily equal nbytes. For example, if the
    input is from a terminal, at most one line of characters is read.

                                   NOTE

       The read function does not span record boundaries in a
       record file and, therefore, reads at most one record. A
       separate read must be done for each record.

384.3  –  Return Values

    n                  The number of bytes read.
    -1                 Indicates a read error, including physical
                       input errors, illegal buffer addresses,
                       protection violations, undefined file
                       descriptors, and so forth.

384.4  –  Example

        #include <unistd.h>
        #include <stdlib.h>
        #include <stdio.h>
        #include <fcntl.h>

        main()
        {
            int fd,
                i;
            char buf[10];
            FILE *fp ;          /* Temporary STDIO file */

            /* Create a dummy data file  */

            if ((fp = fopen("test.txt", "w+")) == NULL) {
                perror("open");
                exit(1);
            }
            fputs("XYZ\n",fp) ;
            fclose(fp) ;

            /* And now practice "read" */

            if ((fd = open("test.txt", O_RDWR, 0, "shr=upd")) <= 0) {
                perror("open");
                exit(0);
            }

            /* Read 2 characters into buf.  */

            if ((i = read(fd, buf, 2)) < 0) {
                perror("read");
                exit(0);
            }

            /* Print out what was read.  */

            if (i > 0)
                printf("buf='%c%c'\n", buf[0], buf[1]);

            close(fd);
        }

385  –  readdir

    Finds entries in a directory.

    Format

      #include  <dirent.h>

      struct dirent *readdir  (DIR *dir_pointer);

      int readdir_r  (DIR *dir_pointer, struct dirent *entry, struct
                     dirent **result);

385.1  –  Arguments

 dir_pointer

    A pointer to the dir structure of an open directory.

 entry

    A pointer to a dirent structure that will be initialized with the
    directory entry at the current position of the specified stream.

 result

    Upon successful completion, the location where a pointer to entry
    is stored.

385.2  –  Description

    The readdir function returns a pointer to a structure
    representing the directory entry at the current position in the
    directory stream specified by dir_pointer, and positions the
    directory stream at the next entry. It returns a NULL pointer
    upon reaching the end of the directory stream. The dirent
    structure defined in the <dirent.h> header file describes a
    directory entry.

    The type DIR defined in the <dirent.h> header file represents a
    directory stream. A directory stream is an ordered sequence of
    all the directory entries in a particular directory. Directory
    entries represent files. You can remove files from or add files
    to a directory asynchronously to the operation of the readdir
    function.

    The pointer returned by the readdir function points to data
    that you can overwrite by another call to readdir on the same
    directory stream. This data is not overwritten by another call to
    readdir on a different directory stream.

    If a file is removed from or added to the directory after
    the most recent call to the opendir or rewinddir function, a
    subsequent call to the readdir function might not return an entry
    for that file.

    When it reaches the end of the directory, or when it detects an
    invalid seekdir operation, the readdir function returns the null
    value.

    An attempt to seek to an invalid location causes the readdir
    function to return the null value the next time it is called. A
    previous telldir function call returns the position.

    The readdir_r function is a reentrant version of readdir. In
    addition to dir_pointer, you must specify a pointer to a dirent
    structure in which the current directory entry of the specified
    stream is returned.

    If the operation is successful, readdir_r returns 0 and stores
    one of the following two pointers in result:

    o  Pointer to entry if the entry was found

    o  NULL pointer if the end of the directory stream was reached

    The storage pointed to by entry must be large enough for a dirent
    with an array of char d_name member containing at least NAME_MAX
    + 1 elements.

    If an error occurred, an error value is returned that indicates
    the cause of the error.

    Applications wishing to check for error situations should set
    errno to 0 before calling readdir. If errno is set to nonzero on
    return, then an error occurred.

385.3  –  Example

      See the description of closedir for an example.

385.4  –  Return Values

    x                  On successful completion of readdir, a pointer
                       to an object of type struct dirent.
    0                  Successful completion of readdir_r.
    x                  On error, an error value (readdir_r only).
    NULL               An error occurred or end of the directory
                       stream (readdir_r only). If an error occurred,
                       errno is set to a value indicating the cause.

386  –  readlink

    Reads the contents of the specified symbolic link and places them
    into a user-supplied buffer.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      ssize_t readlink  (const char *restrict link_name, char
                        *restrict user_buffer, size_t buffer_size);

386.1  –  Arguments

 link_name

    Pointer to the text string representing the name of the symbolic
    link file.

 user_buffer

    Pointer to the user buffer.

 buffer_size

    Size of the user buffer.

386.2  –  Description

    The readlink function reads the contents of the specified
    symbolic link (link_name) and places them into a user-supplied
    buffer (user_buffer) of size (buffer_size).

    See also symlink, unlink, realpath, lchown, and lstat.

386.3  –  Return Values

    n                  Upon successful completion, the count of bytes
                       placed in the user_buffer
    -1                 Indicates an error. The buffer is unchanged,
                       and errno is set to indicate the error:

                       o  EACCES - Read permission is denied in the
                          directory where the symbolic link is being
                          read, or search permission is denied for a
                          component of the path prefix of link_name.

                       o  ENAMETOOLONG - The length of the link_name
                          argument exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX.

                       o  Any errno value from close, open, or read.

387  –  readv

    Reads from a file.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sys/uio.h>

      ssize_t readv  (int file_desc, const struct iovec *iov, int iovcnt);

      ssize_t _readv64  (int file_desc, struct __iovec64 *iov, int iovcnt);

387.1  –  Function Variants

    The readv function has variants named _readv32 and _readv64 for
    use with 32-bit and 64-bit pointer sizes, respectively.

387.2  –  Arguments

 file_desc

    A file descriptor. A file descriptor that must refer to a file
    currently opened for reading.

 iov

    Array of iovec structures into which the input data is placed.

 iovcnt

    The number of buffers specified by the members of the iov array.

387.3  –  Description

    The readv function is equivalent to read, but places the input
    data into the iovcnt buffers specified by the members of the iov
    array: iov[0], iov[1], ..., iov[iovcnt-1]. The iovcnt argument is
    valid if it is greater than 0 and less than or equal to IOV_MAX.

    Each iovec entry specifies the base address and length of an area
    in memory where data should be placed. The readv function always
    fills an area completely before proceeding to the next.

    Upon successful completion, readv marks for update the st_atime
    field of the file.

    If the Synchronized Input and Output option is supported:

          If the O_DSYNC and O_RSYNC bits have been set, read
          I/O operations on the file descriptor will complete
          as defined by synchronized I/O data integrity
          completion.

          If the O_SYNC and O_RSYNC bits have been set, read
          I/O operations on the file descriptor will complete
          as defined by synchronized I/O file integrity
          completion.

    If the Shared Memory Objects option is supported:

          If file_desc refers to a shared memory object, the
          result of the read function is unspecified.

    For regular files, no data transfer occurs past the offset
    maximum established in the open file description associated with
    file_desc.

387.4  –  Return Values

    n                  The number of bytes read.
    -1                 Indicates a read error. The function sets
                       errno to one of the following values:

                       o  EAGAIN - The O_NONBLOCK flag is set for the
                          file descriptor, and the process would be
                          delayed.

                       o  EBADF - The file_desc argument is not a
                          valid file descriptor open for reading.

                       o  EBADMSG - The file is a STREAM file that is
                          set to control-normal mode, and the message
                          waiting to be read includes a control part.

                       o  EINTER - The read operation was terminated
                          because of the receipt of a signal, and no
                          data was transferred.

                       o  EINVAL - The STREAM or multiplexer
                          referenced by file_desc is linked
                          (directly or indirectly) downstream from
                          a multiplexer.

                          OR

                          The sum of the iov_len values in the iov
                          array overflowed an ssize_t.

                       o  EIO - A physical I/O error has occurred.

                          OR

                          The process is a member of a background
                          process attempting to read from its
                          controlling terminal, the process is
                          ignoring or blocking the SIGTTIN signal,
                          or the process group is orphaned.

                       o  EISDIR - The file_desc argument refers to a
                          directory, and the implementation does not
                          allow the directory to be read using read,
                          pread or readv. Use the readdir function
                          instead.

                       o  EOVERFLOW - The file is a regular file,
                          nbyte is greater than 0, and the starting
                          position is before the end-of-file and is
                          greater than or equal to the offset maximum
                          established in the open file description
                          associated with file_desc.

                       The readv function may fail if:

                       o  EINVAL - The iovcnt argument was less than
                          or equal to 0, or greater than IOV_MAX.

388  –  realloc

    Changes the size of the area pointed to by the first argument to
    the number of bytes given by the second argument. These functions
    are AST-reentrant.

    Format

      #include  <stdlib.h>

      void *realloc  (void *ptr, size_t size);

388.1  –  Function Variants

    The realloc function has variants named _realloc32 and _realloc64
    for use with 32-bit and 64-bit pointer sizes, respectively.

388.2  –  Arguments

 ptr

    Points to an allocated area, or can be NULL.

 size

    The new size of the allocated area.

388.3  –  Description

    If ptr is the NULL pointer, the behavior of the realloc function
    is identical to the malloc function.

    The contents of the area are unchanged up to the lesser of the
    old and new sizes. The ANSI C Standard states that, "If the
    new size is larger than the old size, the value of the newly
    allocated portion of memory is indeterminate." For compatibility
    with old implementations, VSI C initializes the newly
    allocated memory to 0.

    For efficiency, the previous actual allocation could have been
    larger than the requested size. If it was allocated with malloc,
    the value of the portion of memory between the previous requested
    allocation and the actual allocation is indeterminate. If it was
    allocated with calloc, that same memory was initialized to 0. If
    your application relies on realloc initializing memory to 0, then
    use calloc instead of malloc to perform the initial allocation.
    The maximum amount of memory allocated at once is limited to
    0xFFFFD000.

    See also free, cfree, calloc, and malloc.

388.4  –  Return Values

    x                  The address of the area, quadword-
                       aligned (Alpha only) or octaword-aligned
                       (Integrity servers(ONLY)) . The address is
                       returned because the area may have to be moved
                       to a new address to reallocate enough space.
                       If the area was moved, the space previously
                       occupied is freed.
    NULL               Indicates that space cannot be reallocated
                       (for example, if there is not enough room).

389  –  realpath

    Returns an absolute pathname from the POSIX root.

    Format

      #include  <stdlib.h>

      char realpath  (const char *restrict file_name, char *restrict
                     resolved_name);

389.1  –  Arguments

 file_name

    Pointer to the text string representing the name of the file for
    which you want the absolute path.

 resolved name

    Pointer to the generated absolute path stored as a null-
    terminated string.

389.2  –  Description

    The realpath function returns an absolute pathname from the
    POSIX root. The generated pathname is stored as a null-terminated
    string, up to a maximum of PATH_MAX bytes, in the buffer pointed
    to by resolved_name.

    The realpath function is supported only in POSIX-compliant modes
    (that is, with DECC$POSIX_COMPLIANT_PATHNAMES defined to one of
    the allowed values).

    See also symlink, unlink, readlink, lchown, and lstat.

389.3  –  Return Values

    x                  Upon successful completion, a pointer to the
                       resolved_name.
    NULL               Indicates an error. A null pointer is
                       returned, the contents of the buffer pointed
                       to by resolved_name are undefined, and errno
                       is set to indicate the error:

                       o  ENAMETOOLONG - The length of the file_name
                          argument exceeds PATH_MAX, or a pathname
                          component is longer than NAME_MAX.

                       o  ENOENT - A component of file_name does not
                          name an existing file, or file_name points
                          to an empty string.

                       o  Any errno value from chdir or stat.

390  –  [w]refresh

    Repaint the specified window on the terminal screen. The refresh
    function acts on the stdscr window.

    Format

      #include  <curses.h>

      int refresh();

      int wrefresh  (WINDOW *win);

390.1  –  Argument

 win

    A pointer to the window.

390.2  –  Description

    The result of this process is that the portion of the window not
    occluded by subwindows or other windows appears on the terminal
    screen. To see the entire occluded window on the terminal screen,
    call the touchwin function instead of the refresh or wrefresh
    function.

    See also touchwin.

390.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

391  –  remainder

    Returns the floating-point remainder r = x - n*y) when y is
    nonzero.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double remainder  (double x, double y);

      float remainderf  (float x, float y);

      long double remainderl  (long double x, long double y);

391.1  –  Argument

 x

    A real number.

 y

    A real number.

391.2  –  Description

    These functions return the floating-point remainder r = x - n*y)
    when y is nonzero. The value n is the integral value nearest the
    exact value x/y. That is, n = rint(x/y).

    When |n - x/y| = 1/2, the value n is chosen to be even.

    The behavior of the remainder function is independent of the
    rounding mode.

    The remainder functions are functionally equivalent to the remquo
    functions.

391.3  –  Return Values

    r                  Upon successful completion, these functions
                       return the floating-point remainder r = x - ny
                       when y is nonzero.
    Nan                If x or y is Nan.

392  –  remquo

    Returns the floating-point remainder r = x - n*y) when y is
    nonzero.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double remquo  (double x, double y, int * quo);

      float remquof  (float x, float y, int * quo);

      long double remquol  (long double x, long double y, int * quo);

392.1  –  Argument

 x

    A real number.

 y

    A real number.

 quo

392.2  –  Description

    The remquo(), remquof(),  and remquol() functions compute
    the same remainder as the remainder(), remainderf(),  and
    remainderl() functions, respectively. In the object pointed to
    by quo, they store a value whose sign is the sign of x/y and
    whose magnitude is congruent modulo 2n to the magnitude of the
    integral quotient of x/y, where n is an implementation-defined
    integer greater than or equal to 3.

    The remquo functions are functionally equivalent to the remainder
    functions.

392.3  –  Return Values

    r                  Upon successful completion, these functions
                       return the floating-point remainder r = x - ny
                       when y is nonzero.
    Nan                If x or y is Nan.

393  –  remove

    Deletes a file.

    Format

      #include  <stdio.h>

      int remove  (const char *file_spec);

393.1  –  Argument

 file_spec

    A pointer to the string that is an OpenVMS or a UNIX style file
    specification. The file specification can include a wildcard
    in its version number. So, for example, files of the form
    filename.txt;* can be deleted.

393.2  –  Description

    If you specify a directory in the filename and it is a search
    list that contains an error, VSI C for OpenVMS Systems
    interprets it as a file error.

                                   NOTE

       The DECC$ALLOW_REMOVE_OPEN_FILES feature logical controls
       the behavior of the remove function on open files.
       Ordinarily, the operation fails. However, POSIX conformance
       dictates that the operation succeed.

       With DECC$ALLOW_REMOVE_OPEN_FILES enabled, this POSIX
       conformant behavior is achieved.

    When remove is used to delete a symbolic link, the link itself is
    deleted, not the file to which it refers.

    The remove and delete functions are functionally equivalent in
    the C RTL.

    See also delete.

393.3  –  Return Values

    0                  Indicates success.
    nonzero value      Indicates failure.

394  –  rename

    Gives a new name to an existing file.

    Format

      #include  <stdio.h>

      int rename  (const char *old_file_spec, const char
                  *new_file_spec);

394.1  –  Arguments

 old_file_spec

    A pointer to a string that is the existing name of the file to be
    renamed.

 new_file_spec

    A pointer to a string that is to be the new name of the file.

394.2  –  Description

    If you try to rename a file that is currently open, the behavior
    is undefined. You cannot rename a file from one physical device
    to another. Both the old and new file specifications must reside
    on the same device.

    If the new_file_spec does not contain a file extension, the
    file extension of old_file_spec is used. To rename a file to
    have no file extension, new_file_spec must contain a period
    (.)  For example, the following renames SYS$DISK:[]FILE.DAT to
    SYS$DISK:[]FILE1.DAT:

    rename("file.dat", "file1");

    However, the following renames SYS$DISK:[]FILE.DAT to
    SYS$DISK:[]FILE1:

    rename("file.dat", "file1.");

                                   NOTE

       Because the rename function does special processing of the
       file extension, the caller must be careful when specifying
       the name of the renamed file in a call to a C Run-Time
       Library function that accepts a file-name argument. For
       example, after the following call to the rename function,
       the new file should be opened as fopen("bar.dat",...):

       rename("foo.dat", "bar");

    The rename function is affected by the setting of the
    DECC$RENAME_NO_INHERIT and DECC$RENAME_ALLOW_DIR feature logicals
    as follows:

    o  DECC$RENAME_NO_INHERIT provides more UNIX compliant behavior
       in rename, and affects whether or not the new name for the
       file inherits anything (like file type) from the old name or
       must be specified completely.

    o  DECC$RENAME_ALLOW_DIR lets you choose between the previous
       OpenVMS behavior of allowing the renaming of a file from one
       directory to another, or the more UNIX compliant behavior of
       not allowing the renaming of a file to a directory.

    Also see the C RTL help for feature logicals DECC$RENAME_NO_
    INHERIT and DECC$RENAME_ALLOW_DIR.

394.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure. The function sets errno to
                       one of the following values:

                       o  EISDIR - The new argument points to a
                          directory, and the old argument points
                          to a file that is not a directory.

                       o  EEXIST - The new argument points to a
                          directory that already exists.

                       o  ENOTDIR - The old argument names a
                          directory, and new argument names a non-
                          directory file.

                       o  ENOENT - The old argument points to a file,
                          directory, or device that does not exist.

                          Or the new argument points to a nonexisting
                          directory path or device.

395  –  rewind

    Sets the file to its beginning.

    Format

      #include  <stdio.h>

      void rewind  (FILE *file_ptr); (ISO POSIX-1)

      int rewind  (FILE *file_ptr); (DEC C Extension)

395.1  –  Argument

 file_ptr

    A file pointer.

395.2  –  Description

    The rewind function is equivalent to fseek (file_ptr, 0, SEEK_
    SET). You can use the rewind function with either record or
    stream files.

    A successful call to rewind clears the error indicator for the
    file.

    The ANSI C standard defines rewind as not returning a value;
    therefore, the function prototype for rewind is declared with a
    return type of void. However, since a rewind can fail, and since
    previous versions of the C RTL have declared rewind to
    return an int, the code for rewind does return 0 on success and
    -1 on failure.

    See also fseek.

396  –  rewinddir

    Resets the position of the specified directory stream to the
    beginning of a directory.

    Format

      #include  <dirent.h>

      void rewinddir  (DIR *dir_pointer);

396.1  –  Argument

 dir_pointer

    A pointer to the dir structure of an open directory.

396.2  –  Description

    The rewinddir function resets the position of the specified
    directory stream to the beginning of the directory. It also
    causes the directory stream to refer to the current state of the
    corresponding directory, the same as using the opendir function.
    If the dir_pointer argument does not refer to a directory stream,
    the effect is undefined.

    The type DIR, defined in the <dirent.h> header file, represents
    a directory stream. A directory stream is an ordered sequence of
    all the directory entries in a particular directory. Directory
    entries represent files.

    See also opendir.

397  –  rindex

    Searches for a character in a string.

    Format

      #include  <strings.h>

      char *rindex  (const char *s, int c);

397.1  –  Function Variants

    The rindex function has variants named _rindex32 and _rindex64
    for use with 32-bit and 64-bit pointer sizes, respectively.

397.2  –  Arguments

 s

    The string to search.

 c

    The character to search for.

397.3  –  Description

    The rindex function is identical to the strchr function, and is
    provided for compatibility with some UNIX implementations.

398  –  rint

    Rounds its argument to an integral value according to the current
    IEEE rounding direction specified by the user.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double rint  (double x);

      float rintf  (float x,);

      long double rintl  (long double x);

398.1  –  Argument

 x

    A real number.

398.2  –  Description

    The rint functions return the nearest integral value to x in
    the direction of the current IEEE rounding mode specified on the
    /ROUNDING_MODE command-line qualifier.

    If the current rounding mode rounds toward negative Infinity,
    then rint is identical to floor. If the current rounding mode
    rounds toward positive Infinity, then rint is identical to ceil.

    If |x| = Infinity, rint returns x.

398.3  –  Return Values

    n                  The nearest integral value to x in the
                       direction of the current IEEE rounding mode.
    NaN                x is NaN; errno is set to EDOM.

399  –  rmdir

    Removes a directory file.

    Format

      #include  <unistd.h>

      int rmdir  (const char *path);

399.1  –  Argument

 path

    A directory pathname.

399.2  –  Description

    The rmdir function removes a directory file whose name is
    specified in the path argument. The directory is removed only
    if it is empty.

    If path names a symbolic link, then rmdir fails and sets errno to
    ENOTDIR.

399.3  –  Restriction

    When using OpenVMS format names, the path argument must be in the
    form directory.dir.

399.4  –  Return Values

    0                  Indicates success.
    -1                 An error occurred; errno is set to indicate
                       the error.

400  –  sbrk

    Determines the lowest virtual address that is not used with the
    program.

    Format

      #include  <unistd.h>

      void *sbrk  (long int incr);

400.1  –  Argument

 incr

    The number of bytes to add to the current break address.

400.2  –  Description

    The sbrk function adds the number of bytes specified by its
    argument to the current break address and returns the old break
    address.

    When a program is executed, the break address is set to the
    highest location defined by the program and data storage areas.
    Consequently, sbrk is needed only by programs that have growing
    data areas.

    sbrk(0) returns the current break address.

400.3  –  Return Values

    x                  The old break address.
    (void *)(-1)       Indicates that the program is requesting too
                       much memory.

400.4  –  Restriction

    Unlike other C library implementations, the C RTL memory
    allocation functions (such as malloc) do not rely on brk or
    sbrk to manage the program heap space. Consequently, on OpenVMS
    systems, calling brk or sbrk can interfere with memory allocation
    routines. The brk and sbrk functions are provided only for
    compatibility purposes.

401  –  scalb

    Returns the exponent of a floating-point number.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double scalb  (double x, double n);

      float scalbf  (float x, float n);

      long double scalbl  (long double x, long double n);

401.1  –  Arguments

 x

    A nonzero floating-point number.

 n

    An integer.

401.2  –  Description

    The scalb functions return x*(2**n) for integer n.

401.3  –  Return Values

    x                  On successful completion, x*(2**n) is
                       returned.
    HUGE_VAL           On overflow, scalb returns HUGE_VAL (according
                       to the sign of x) and sets errno to ERANGE.
    0                  Underflow occurred; errno is set to ERANGE.
    x                  x is Infinity.
    NaN                x or n is NaN; errno is set to EDOM.

402  –  scanf

    Performs formatted input from the standard input (stdin),
    interpreting it according to the format specification.

    Format

      #include  <stdio.h>

      int scanf  (const char *format_spec, . . . );

402.1  –  Arguments

 format_spec

    Pointer to a string containing the format specification. The
    format specification consists of characters to be taken literally
    from the input or converted and placed in memory at the specified
    input sources.

  . . .

    Optional expressions that are pointers to objects whose resultant
    types correspond to conversion specifications given in the format
    specification.

    If no conversion specifications are given, you can omit these
    input pointers. Otherwise, the function call 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.

402.2  –  Return Values

    x                  The number of successfully matched and
                       assigned input items.
    EOF                Indicates that a read error occurred prior to
                       any successful conversions. The function sets
                       errno. For a list of errno values set by this
                       function, see fscanf.

403  –  [w]scanw

    Perform a scanf on the window. The scanw function acts on the
    stdscr window.

    Format

      #include  <curses.h>

      int scanw  (char *format_spec, . . . );

      int wscanw  (WINDOW *win, char *format_spec, . . . );

403.1  –  Arguments

 win

    A pointer to the window.

 format_spec

    A pointer to the format specification string.

  . . .

    Optional expressions that are pointers to objects whose resultant
    types correspond to conversion specifications given in the format
    specification. If no conversion specifications are given, you may
    omit these input pointers.

    Otherwise, the function call 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.

403.2  –  Description

    The formatting specification (format_spec) and the other
    arguments are identical to those used with the scanf function.

    The scanw and wscanw functions accept, format, and return a line
    of text from the terminal screen. For more information, see the
    scrollok and scanf functions.

403.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates that the function makes the
                       screen scroll illegally or that the scan was
                       unsuccessful.

404  –  scroll

    Moves all the lines on the window up one line. The top line
    scrolls off the window and the bottom line becomes blank.

    Format

      #include  <curses.h>

      int scroll  (WINDOW *win);

404.1  –  Argument

 win

    A pointer to the window.

404.2  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

405  –  scrollok

    Sets the scroll flag for the specified window.

    Format

      #include  <curses.h>

      scrollok  (WINDOW *win, bool boolf);

405.1  –  Arguments

 win

    A pointer to the window.

 boolf

    A Boolean TRUE or FALSE value. If boolf is FALSE, scrolling
    is not allowed. This is the default setting. The bool type is
    defined in the <curses.h> header file as follows:

    #define bool int

406  –  seed48

    Initializes a 48-bit random-number generator.

    Format

      #include  <stdlib.h>

      unsigned short *seed48  (unsigned short seed_16v[3]);

406.1  –  Argument

 seed_16v

    An array of three unsigned short ints that form a 48-bit seed
    value.

406.2  –  Description

    The seed48 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 seed48 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 seed48:

    o  Sets the value of Xi to the 48-bit value specified in the
       array pointed to by seed_16v.

    o  Returns a pointer to a 48-bit internal buffer that contains
       the previous value of Xi, used only by seed48.

    The returned pointer allows you to restart the pseudorandom
    sequence at a given point. Use the pointer to copy the previous
    Xi value into a temporary array. To resume where the original
    sequence left off, you can call seed48 with a pointer to this
    array.

    See also drand48, lrand48, and mrand48.

406.3  –  Return Value

    x                  A pointer to a 48-bit internal buffer.

407  –  seekdir

    Sets the position of a directory stream.

    Format

      #include  <dirent.h>

      void seekdir  (DIR *dir_pointer, long int location);

407.1  –  Arguments

 dir_pointer

    A pointer to the dir structure of an open directory.

 location

    The number of an entry relative to the start of the directory.

407.2  –  Description

    The seekdir function sets the position of the next readdir
    operation on the directory stream specified by dir_pointer to
    the position specified by location. The value of location should
    be returned from an earlier call to telldir.

    If the value of location was not returned by a call to the
    telldir function, or if there was an intervening call to the
    rewinddir function on this directory stream, the effect is
    unspecified.

    The type DIR, defined in the <dirent.h> header file, represents
    a directory stream. A directory stream is an ordered sequence of
    all the directory entries in a particular directory. Directory
    entries represent files. You can remove files from or add files
    to a directory asynchronously to the operation of the readdir
    function.

    See readdir, rewinddir, and telldir.

408  –  sem_close

    Deallocates the specified named semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_close  (sem_t *sem);

408.1  –  Argument

 sem

    The semaphore to be closed. Use the sem argument returned by the
    previous call to sem_open.

408.2  –  Description

    The sem_close function makes a semaphore available for reuse
    by deallocating any system resources allocated for use by the
    current process for the named semaphore indicated by sem.

    If the semaphore has not been removed with a call to sem_unlink,
    sem_close does not change the current state of the semaphore.

    If the semaphore has been removed with a call to sem_unlink after
    the most recent call to sem_open with O_CREAT, the semaphore is
    no longer available after all processes that opened the semaphore
    close it.

408.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The sem argument is not a valid
                          semaphore descriptor.

                       o  ENOSYS - The function is not implemented.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

409  –  semctl

    Semaphore control operations

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sem.h>

      int semctl  (int semid, int semnum, int cmd, . . . );

409.1  –  Argument

 semid

    A semaphore set identifier, a positive integer. It is created
    by the semget function and used to identify the semaphore set on
    which to perform the control operation.

 semnum

    Semaphore number, a non-negative integer. It identifies a
    semaphore within the semaphore set on which to perform the
    control operation.

 cmd

    The control operation to perform on the semaphore.

  . . .

    Optional fourth argument of type union semun, which depends on
    the control operation requested in cmd.

409.2  –  Description

    The semctl function provides a variety of semaphore control
    operations as specified by cmd. The fourth argument is optional
    and depends upon the operation requested. If required, it is of
    type union semun, which is explicitly declared as:

    union semun {
        int val;
        struct semid_ds *buf;
        unsigned short  *array;
    } arg;

    The following semaphore control operations as specified by cmd
    are executed with respect to the semaphore specified by semid and
    semnum. The level of permission required for each operation is
    shown with each command. The symbolic names for the values of cmd
    are defined in the <sem.h> header:

    o  GETVAL

       Returns the value of semval. Requires read permission.

    o  SETVAL

       Sets the value of semval to arg.val, where arg is the value
       of the fourth argument to semctl. When this command is
       successfully executed, the semadj value corresponding to the
       specified semaphore in all processes is cleared. Requires
       alter permission.

    o  GETPID

       Returns the value of sempid; requires read permission.

    o  GETNCNT

       Returns the value of semncnt; requires read permission.

    o  GETZCNT

       Returns the value of semzcnt; requires read permission.

    The following values of cmd operate on each semval in the set of
    semaphores:

    o  GETALL

       Returns the value of semval for each semaphore in the
       semaphore set and places it into the array pointed to by
       arg.array, where arg is the fourth argument to semctl;
       requires read permission.

    o  SETALL

       Sets the value of semval for each semaphore in the semaphore
       set according to the array pointed to by arg.array, where
       arg is the fourth argument to semctl. When this command is
       successfully executed, the semadj values corresponding to each
       specified semaphore in all processes are cleared. Requires
       alter permission.

    The following values of cmd are also available:

    o  IPC_STAT

       Places the current value of each member of the semid_ds data
       structure associated with semid into the structure pointed to
       by arg.buf, where arg is the fourth argument to semctl. The
       contents of this structure are defined in <sem.h>. Requires
       read permission.

    o  IPC_SET

       Sets the value of the following members of the semid_ds data
       structure associated with semid to the corresponding value
       found in the structure pointed to by arg.buf, where arg is the
       fourth argument to semctl:

       sem_perm.uid
       sem_perm.gid
       sem_perm.mode

       The mode bits specified in The Open Group Base Specifications
       IPC General Description section are copied into the
       corresponding bits of the sem_perm.mode associated with semid.
       The stored values of any other bits are unspecified.

       This command can only be executed by a process that has an
       effective user ID equal to either that of a process with
       appropriate privileges or to the value of sem_perm.cuid or
       sem_perm.uid in the semid_ds data structure associated with
       semid.

    o  IPC_RMID

       Removes the semaphore identifier specified by semid from
       the system and destroys the set of semaphores and semid_ds
       data structure associated with it. This command can only be
       executed by a process that has an effective user ID equal to
       either that of a process with appropriate privileges or to the
       value of sem_perm.cuid or sem_perm.uid in the semid_ds data
       structure associated with semid.

409.3  –  Return Values

    n or 0             Upon successful completion, the value returned
                       by the function depends on cmd as follows:

                       o  GETVAL - The value of semval

                       o  GETPID - The value of sempid

                       o  GETNCNT - The value of semncnt

                       o  GETZCNT - The value of semzcnt

                       o  All others - 0

    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EACCES - Operation permission is denied to
                          the calling process.

                       o  EFAULT - The arguments passed to the
                          function are not accessible.

                       o  EINVAL - The value of semid is not a valid
                          semaphore identifier, or the value of
                          semnum is less than zero or greater than
                          or equal to sem_nsems, or the value of cmd
                          is not a valid command.

                       o  EPERM - The argument cmd is equal to IPC_
                          RMID or IPC_SET and the effective user ID
                          of the calling process is not equal to that
                          of a process with appropriate privileges
                          and it is not equal to the value of sem_
                          perm.cuid or sem_perm.uid in the data
                          structure associated with semid.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

410  –  sem_destroy

    Destroys an unnamed semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_destroy  (sem_t *sem);

410.1  –  Argument

 sem

    The unnamed semaphore to be destroyed. Use the sem argument that
    was supplied to, and filled in by, the previous call to sem_init.

410.2  –  Description

    The sem_destroy function destroys an unnamed semaphore indicated
    by sem. Only a semaphore created using sem_init may be destroyed
    using sem_destroy.

    The potential for deadlock exists if a process calls sem_destroy
    for a semaphore while there is a pending sem_wait, because a
    process may be waiting for a poster that has not yet opened the
    semaphore.

410.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno
                       to one of the following values, without
                       destroying the semaphore indicated by the
                       sem argument:

                       o  EINVAL - The sem argument is not a valid
                          semaphore.

                       o  ENOSYS - The function is not implemented.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

                       o  EBUSY - The processes are blocked on the
                          semaphore.

411  –  semget

    Gets a set of semaphores.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sem.h>

      int semget  (key_t key, int nsems, int semflg);

411.1  –  Argument

 key

    The key for which the associated semaphore identifier is
    returned.

 nsems

    Value used to initialize the sem_nsems member of the semid_ds
    data structure. See the description.

 semflg

    Flag used to initialize the low-order 9 bits of the sem_perm.mode
    member of the semid_ds data structure associated with the new
    semaphore. See the description.

 value

    The initial value to be given to the semaphore. This argument is
    used only when the semaphore is being created.

411.2  –  Description

    The semget function returns the semaphore identifier associated
    with key.

    A semaphore identifier with its associated semid_ds data
    structure and its associated set of nsems semaphores (see
    the <sys/sem.h> header file) is created for key if one of the
    following is true:

    o  The key argument is equal to IPC_PRIVATE.

    o  The key argument does not already have a semaphore identifier
       associated with it and (semflg &IPC_CREAT) is nonzero.

    When it is created, the semid_ds data structure associated with
    the new semaphore identifier is initialized as follows:

    o  In the operation permissions structure sem_perm.cuid, sem_
       perm.uid, sem_perm.cgid, and sem_perm.gid are set equal to the
       effective user ID and effective group ID, respectively, of the
       calling process.

    o  The low-order 9 bits of sem_perm.mode are set equal to the
       low-order 9 bits of the semflg argument.

    o  The variable sem_nsems is set equal to the value of the nsems
       argument.

    o  The variable sem_otime is set equal to 0 and the variable sem_
       ctime is set equal to the current time.

    o  The data structure associated with each semaphore in the
       set does not need to be initialized. You can use the semctl
       function with the command SETVAL or SETALL to initialize each
       semaphore.

411.3  –  Return Values

    n                  Successful completion. The function returns a
                       non-negative integer semaphore identifier.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EACCES - A semaphore identifier exists for
                          key, but operation permission as specified
                          by the low-order 9 bits of semflg was not
                          granted.

                       o  EEXIST - A semaphore identifier exists
                          for key but ((semflg &IPC_CREAT) &&(semflg
                          &IPC_EXCL)) is nonzero.

                       o  EFAULT - The arguments passed to the
                          function are not accessible.

                       o  EINVAL - The value of nsems is either
                          less than or equal to 0 or greater than
                          the system-imposed limit, or a semaphore
                          identifier exists for key, but the number
                          of semaphores in the set associated with it
                          is less than nsems and nsems is not equal
                          to 0.

                       o  ENOENT - A semaphore identifier does not
                          exist for key and (semflg &IPC_CREAT) is
                          equal to 0.

                       o  ENOSPC - A semaphore identifier is to be
                          created but the system-imposed limit on
                          the maximum number of allowed semaphores
                          system-wide will be exceeded.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

412  –  sem_getvalue

    Gets the value of a specified semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_getvalue  (sem_t *sem, int *sval);

412.1  –  Argument

 sem

    The semaphore for which a value is to be returned.

 sval

    The location to be updated with the value of the semaphore
    indicated by the sem argument.

412.2  –  Description

    The sem_getvalue function updates a location referenced by the
    sval argument with the value of semaphore sem. The updated value
    represents an actual semaphore value that occurred during the
    call, but may not be the actual value of the semaphore at the
    time that the value is returned to the calling process.

    If the semaphore is locked, the value returned will either be
    zero or a negative number indicating the number of processes
    waiting for the semaphore at some time during the call.

412.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The sem argument is not a valid
                          semaphore.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

413  –  sem_init

    Initializes an unnamed semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_init  (sem_t *sem, int pshared, unsigned int value );

413.1  –  Argument

 sem

    The location to receive the descriptor of the initialized
    semaphore.

 pshared

    A value indicating whether the semaphore should be sharable
    between the creating process and its descendants (nonzero value)
    or not (zero).

                                   NOTE

       The value for pshared must be zero between threads because
       this release does not support unnamed semaphores to be
       shared across processes.

 value

    The initial value to be given to the semaphore.

413.2  –  Description

    The sem_init function creates a new counting semaphore with a
    specific value. A semaphore is used to limit access to a critical
    resource. When a process requires access to the resource without
    interference from other processes, it attempts to establish
    a connection with the associated semaphore. If the semaphore
    value is greater than zero, the connection is established and the
    semaphore value is decremented by one. If the semaphore value is
    less than or equal to zero, the process attempting to access the
    resource is blocked and must wait for another process to release
    the semaphore and increment the semaphore value.

    The sem_init function establishes a connection between an
    unnamed semaphore and a process; the sem_wait and sem_trywait
    functions lock the semaphore; and the sem_post function unlocks
    the semaphore. Use the sem_destroy function to deallocate system
    resources allocated to the process for use with the semaphore.
    You can use the sem_getvalue function to obtain the value of a
    semaphore.

    A semaphore created by a call to the sem_init function remains
    valid until the semaphore is removed by a call to the sem_destroy
    function.

413.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The value argument exceeds {SEM_
                          VALUE_MAX}.

                       o  ENOSYS - The function is not implemented.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

414  –  sem_open

    Opens/creates a named semaphore for use by a process.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      sem_t *sem_open  (const char *name, int ooption...) ;

414.1  –  Argument

 name

    a string naming the semaphore object.

 ooption

    Specifies whether the semaphore is to be created (O_CREAT option
    bit set) or only opened (O_CREAT option bit clear). If O_CREAT is
    set, the O_EXCL option bit may additionally be set to specify
    that the call should fail if a semaphore of the same name
    already exists. The O_CREAT and O_EXCL options are defined in
    the <fcntl.h> header file.

 mode

    The semaphore's permission bits. This argument is used only when
    the semaphore is being created.

 value

    The initial value to be given to the semaphore. This argument is
    used only when the semaphore is being created.

414.2  –  Description

    Use the sem_open function to establish the connection between a
    named semaphore and a process. Subsequently, the calling process
    can reference the semaphore by using the address returned from
    the call. The semaphore is available in subsequent calls to sem_
    wait, sem_trywait, sem_post, and sem_getvalue functions. The
    semaphore remains usable by the process until the semaphore is
    closed by a successful call to the sem_close function.

    The O_CREAT option bit in the ooption parameter controls whether
    the semaphore is created or only opened by the call to sem_open.

    A created semaphore's user ID is set to the user ID of the
    calling process and its group ID is set to a system default group
    or to the group ID of the process. The semaphore's permission
    bits are set to the value of the mode argument, except for those
    set in the file mode creation mask of the process.

    After a semaphore is created, other processes can open the
    semaphore by calling sem_open with the same value for the name
    argument.

414.3  –  Return Values

    sem                Successful completion. The function opens
                       the semaphore and returns the semaphore's
                       descriptor.
    sem_failed         Indicates an error. The function sets errno to
                       one of the following values:

                       o  EACCES-The named semaphore exists and
                          the permissions specified by ooption are
                          denied, or the named semaphore does not
                          exist and the permissions specified by
                          ooption are denied.

                       o  EEXIST-O_CREAT and O_EXCL are set, and the
                          named semaphore already exists.

                       o  EINVAL-The sem_open operation is not
                          supported for the given name. Or, O_CREAT
                          was specified in ooption and value was
                          greater than {SEM_VALUE_MAX}.

                       o  EMFILE-Too many semaphore descriptors or
                          file descriptors are currently in use by
                          this process.

                       o  ENAMETOOLONG-The length of the name string
                          exceeds {PATH_MAX}, or a pathname component
                          is longer than {NAME_MAX} while {_POSIX_NO_
                          TRUNC} is in effect.

                       o  ENFILE-Too many semaphores are currently
                          open in the system. ENOENT O_CREAT is
                          not set, and the named semaphore does not
                          exist.

                       o  ENOSPC-Insufficient space exists for the
                          creation of a new named semaphore.

                       o  EVMSERR-OpenVMS specific nontranslatable
                          error code.

415  –  semop

    Performs operations on semaphores in a semaphore set.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sem.h>

      int semop  (int semid, struct sembuf *sops, size_t nsops);

415.1  –  Argument

 semid

    Semaphore set identifier.

 sops

    Pointer to a user-defined array of semaphore operation (sembuf)
    structures.

 nsops

    Number of sembuf structures in the sops array.

415.2  –  Description

    The semop function performs operations on semaphores in the
    semaphore set specified by semid. These operations are supplied
    in a user-defined array of semaphore operation sembuf structures
    specified by sops. Each sembuf structure includes the following
    member variables:

    struct sembuf {            /* semaphore operation structure */
      unsigned short sem_num;  /* semaphore number */
               short sem_op;   /* semaphore operation */
               short sem_flg;  /* operation flags SEM_UNDO and IPC_NOWAIT */

    Each semaphore operation specified by the sem_op variable is
    performed on the corresponding semaphore specified by the semid
    function argument and the sem_num variable.

    The sem_op variable specifies one of three semaphore operations:

    1. If sem_op is a negative integer and the calling process has
       change permission, one of the following occurs:

       o  If semval (see <sem.h>) is greater than or equal to the
          absolute value of sem_op, the absolute value of sem_op
          is subtracted from semval. Also, if (sem_flg &SEM_UNDO)
          is non-zero, the absolute value of sem_op is added to the
          calling process' semadj value for the specified semaphore.

       o  If semval is less than the absolute value of sem_op
          and (sem_flg &IPC_NOWAIT) is nonzero, semop returns
          immediately.

       o  If semval is less than the absolute value of sem_op and
          (sem_flg &IPC_NOWAIT) is 0, semop increments the semncnt
          associated with the specified semaphore and suspends
          execution of the calling thread until one of the following
          conditions occurs:

          -  The value of semval becomes greater than or equal to the
             absolute value of sem_op. When this occurs, the value
             of semncnt associated with the specified semaphore is
             decremented, the absolute value of sem_op is subtracted
             from semval and, if (sem_flg &SEM_UNDO) is nonzero,
             the absolute value of sem_op is added to the calling
             process' semadj value for the specified semaphore.

          -  The semid for which the calling thread is awaiting
             action is removed from the system. When this occurs,
             errno is set equal to EIDRM and -1 is returned.

          -  The calling thread receives a signal that is to be
             intercepted. When this occurs, the value of semncnt
             associated with the specified semaphore is decremented,
             and the calling thread is resumes execution in the
             manner prescribed in sigaction.

    2. If sem_op is a positive integer and the calling process has
       change permission, the value of sem_op is added to semval
       and, if (sem_flg &SEM_UNDO) is nonzero, the value of sem_op
       is subtracted from the calling process' semadj value for the
       specified semaphore.

    3. If sem_op is 0 and the calling process has read permission,
       one of the following occurs:

       o  If semval is 0, semop returns immediately.

       o  If semval is nonzero and (sem_flg &IPC_NOWAIT) is nonzero,
          semop returns immediately.

       o  If semval is nonzero and (sem_flg &IPC_NOWAIT) is 0, semop
          increments the semzcnt associated with the specified
          semaphore and suspends execution of the calling thread
          until one of the following occurs:

          -  The value of semval becomes 0, at which time the value
             of semzcnt associated with the specified semaphore is
             decremented.

          -  The semid for which the calling thread is awaiting
             action is removed from the system. When this occurs,
             errno is set equal to EIDRM and -1 is returned.

          -  The calling thread receives a signal that is to be
             intercepted. When this occurs, the value of semzcnt
             associated with the specified semaphore is decremented,
             and the calling thread resumes execution in the manner
             prescribed in sigaction.

    On successful completion, the value of sempid for each semaphore
    specified in the array pointed to by sops is set equal to the
    process ID of the calling process.

415.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  E2BIG - The value of nsops is greater than
                          the system-imposed maximum.

                       o  EACCES - Operation permission is denied to
                          the calling process.

                       o  EAGAIN - The operation would result in
                          suspension of the calling process but (sem_
                          flg &IPC_NOWAIT) is nonzero.

                       o  EFAULT - The arguments passed to the
                          function are not accessible.

                       o  EFBIG - The value of sem_num is less than
                          0 or greater than or equal to the number
                          of semaphores in the set associated with
                          semid.

                       o  EIDRM - The semaphore identifier semid is
                          removed from the system.

                       o  EINVAL - The value of semid is not a valid
                          semaphore identifier, or the number of
                          individual semaphores for which the calling
                          process requests a SEM_UNDO would exceed
                          the system-imposed limit.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

416  –  sem_post

    Unlocks a semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_post  (sem_t *sem);

416.1  –  Argument

 sem

    The semaphore to be unlocked.

416.2  –  Description

    The sem_post function unlocks the specified semaphore by
    performing the semaphore unlock operation on that semaphore. The
    appropriate function (sem_open for named semaphores or sem_init
    for unnamed semaphores) must be called for a semaphore before
    you can call the locking and unlocking functions, sem_wait, sem_
    trywait, and sem_post.

    If the semaphore value after a sem_post function is positive, no
    processes were blocked waiting for the semaphore to be unlocked;
    the semaphore value is incremented. If the semaphore value after
    a sem_post function is zero, one of the processes blocked waiting
    for the semaphore is allowed to return successfully from its call
    to sem_wait.

    If more than one process is blocked while waiting for the
    semaphore, only one process is unblocked and the state of
    the semaphore remains unchanged when the sem_post function
    returns. The process to be unblocked is selected according to
    the scheduling policies and priorities of all blocked processes.
    If the scheduling policy is SCHED_FIFO or SCHED_RR, the highest-
    priority waiting process is unblocked. If more than one process
    of that priority is blocked, then the process that has waited the
    longest is unblocked.

    The sem_post function can be called from a signal-catching
    function.

416.3  –  Return Values

    0                  Successful completion. The sem_post function
                       performs a semaphore unlock operation,
                       unblocking a process.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The sem argument is not a valid
                          semaphore.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

417  –  sem_timedwait

    Performs a semaphore lock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      #include  <time.h>

      int sem_timedwait  (sem_t *sem, const struct timespec
                         *abs_timeout);

417.1  –  Argument

 sem

    The semaphore to be locked.

 abs_timeout

    The absolute time after which the timeout expires.

417.2  –  Description

    The sem_timedwait function locks the semaphore referenced by
    sem as in the sem_wait function. But if the semaphore cannot be
    locked without waiting for another process or thread to unlock
    the semaphore by performing a sem_post function, this wait
    terminates when the specified timeout expires.

    The timeout expires when the absolute time specified by abs_
    timeout passes, as measured by the clock on which timeouts are
    based (that is, when the value of that clock equals or exceeds
    abs_timeout, or if the absolute time specified by abs_timeout has
    already been passed at the time of the call.

    The function will not fail with a timeout if the semaphore can be
    locked immediately. The validity of abs_timeout does not need to
    be checked if the semaphore can be locked immediately.

417.3  –  Return Values

    0                  Successful completion. The function executes
                       the semaphore lock operation.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  ETIMEDOUT - The semaphore could not
                          be locked before the specified timeout
                          expired.

                       o  EINVAL - The sem argument does not refer to
                          a valid semaphore. Or the process or thread
                          would have blocked, and the abs_timeout
                          parameter specified a nanoseconds field
                          value less than zero or greater than or
                          equal to 1000 million.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

418  –  sem_trywait

    Conditionally performs a semaphore lock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_trywait  (sem_t *sem);

418.1  –  Argument

 sem

    The semaphore to be locked.

418.2  –  Description

    The sem_trywait function locks a semaphore only if the semaphore
    is currently not locked. If the semaphore value is zero, the sem_
    trywait function returns without locking the semaphore.

    The sem_wait and sem_trywait functions help ensure that the
    resource associated with the semaphore cannot be accessed by
    other processes. The semaphore remains locked until the process
    unlocks it with a call to the sem_post function.

    Use the sem_wait function instead of the sem_trywait function if
    the process should wait for access to the semaphore.

418.3  –  Return Values

    0                  Successful completion. The function executes
                       the semaphore lock operation.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EAGAIN - The semaphore was already locked
                          and cannot be locked by the sem_trywait
                          operation.

                       o  EINVAL - The sem argument does not refer to
                          a valid semaphore.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

419  –  sem_unlink

    Removes the specified named semaphore.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_unlink  (const char *name);

419.1  –  Argument

 name

    The name of the semaphore to remove.

419.2  –  Description

    The sem_unlink function removes a semaphore named by the name
    string. If the semaphore is referenced by other processes, sem_
    unlink does not change the state of the semaphore.

    If other processes have the semaphore open when sem_unlink is
    called, the semaphore is not destroyed until all references to
    the semaphore have been destroyed by calls to sem_close. The sem_
    unlink function returns immediately; it does not wait until all
    references have been destroyed.

    Calls to sem_open to recreate or reconnect to the semaphore refer
    to a new semaphore after sem_unlink is called.

419.3  –  Return Values

    0                  Successful completion. The function executes
                       the semaphore unlink operation.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EACCESS - Permission is denied to unlink
                          the named semaphore.

                       o  ENAMETOOLONG - The length of the path
                          name exceeds PSEM_MAX_PATHNAME defined
                          in semaphore.h.

                       o  ENOENT - The named semaphore does not
                          exist.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

420  –  sem_wait

    Performs a semaphore lock.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <semaphore.h>

      int sem_wait  (sem_t *sem);

420.1  –  Argument

 sem

    The semaphore to be locked.

420.2  –  Description

    The sem_wait function locks the semaphore referenced by sem by
    performing a semaphore lock operation on it. If the semaphore
    value is zero, the sem_wait function blocks until it either locks
    the semaphore or is interrupted by a signal.

    The sem_wait and sem_trywait functions help ensure that the
    resource associated with the semaphore cannot be accessed by
    other processes. The semaphore remains locked until the process
    unlocks it with a call to the sem_post function.

    Use the sem_wait function instead of the sem_trywait function if
    the process should wait for access to the semaphore.

420.3  –  Return Values

    0                  Successful completion. The function executes
                       the semaphore lock operation.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINTR - A signal interrupted this function.

                       o  EVMSERR - OpenVMS specific nontranslatable
                          error code.

421  –  [w]setattr

    Activate the video display attribute attr within the window. The
    setattr function acts on the stdscr window.

    Format

      #include  <curses.h>

      int setattr  (int attr);

      int wsetattr  (WINDOW *win, int attr);

421.1  –  Arguments

 win

    A pointer to the window.

 attr

    One of a set of video display attributes, which are blinking,
    boldface, reverse video, and underlining, and are represented by
    the defined constants _BLINK, _BOLD, _REVERSE, and _UNDERLINE,
    respectively. You can set multiple attributes by separating them
    with a bitwise OR operator (|) as follows:

    setattr(_BLINK | _UNDERLINE);

421.2  –  Description

    The setattr and wsetattr functions are specific to VSI C for
    OpenVMS Systems and are not portable.

421.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

422  –  setbuf

    Associates a new buffer with an input or output file and
    potentially modifies the buffering behavior.

    Format

      #include  <stdio.h>

      void setbuf  (FILE *file_ptr, char *buffer);

422.1  –  Arguments

 file_ptr

    A file pointer.

 buffer

    A pointer to a character array or a NULL pointer.

422.2  –  Description

    You can use the setbuf function after the specified file is
    opened but before any I/O operations are performed.

    If buffer is a NULL pointer, then the call is equivalent to a
    call to setvbuf with the same file_ptr, a NULL buffer pointer, a
    buffering type of _IONBF (no buffering), and a buffer size of 0.

    If buffer is not a NULL pointer, then the call is equivalent to a
    call to setvbuf with the same file_ptr, the same buffer pointer,
    a buffering type of _IOFBF, and a buffer size given by the value
    BUFSIZ (defined in <stdio.h>). Therefore, use BUFSIZ to allocate
    the buffer argument used in the call to setbuf. For example:

    #include <stdio.h>
       .
       .
       .
    char my_buf[BUFSIZ];
       .
       .
       .
    setbuf(stdout, my_buf);
       .
       .
       .

    User programs must not depend on the contents of buffer once I/O
    has been performed on the stream. The C RTL might or might
    not use buffer for any given I/O operation.

    The setbuf function originally allowed programmers to substitute
    larger buffers in place of the system default buffers in obsolete
    versions of UNIX. The large default buffer sizes in modern
    implementations of C make the use of this function unnecessary
    most of the time. The setbuf function is retained in the ANSI C
    standard for compatibility with old programs. New programs should
    use setvbuf instead, because it allows the programmer to bind the
    buffer size at run time instead of compile time, and it returns a
    result value that can be tested.

423  –  setenv

    Inserts or resets the environment variable specified by name in
    the current environment list.

    Format

      #include  <stdlib.h>

      int setenv  (const char *name, const char *value, int
                  overwrite);

423.1  –  Arguments

 name

    A variable name in the environment variable list.

 value

    The value for the environment variable.

 overwrite

    A value of 0 or 1 indicating whether to reset the environment
    variable, if it exists.

423.2  –  Description

    The setenv function inserts or resets the environment variable
    name in the current environment list. If the variable name does
    not exist in the list, it is inserted with the value argument. If
    the variable does exist, the overwrite argument is tested. When
    the overwrite argument value is:

    o  0 then the variable is not reset.

    o  1 then the variable is reset to value.

                                   NOTE

       Do not use the setenv, getenv, and putenv functions to
       manipulate symbols and logicals. Instead, use the OpenVMS
       library calls lib$set_logical, lib$get_logical, lib$set_
       symbol, and lib$get_symbol. The *env functions deliberately
       provide UNIX behavior, and are not a substitute for these
       OpenVMS runtime library calls.

       OpenVMS DCL symbols, not logical names, are the closest
       analog to environment variables on UNIX systems. While
       getenv is a mechanism to retrieve either a logical name
       or a symbol, it maintains an internal cache of values for
       use with setenv and subsequent getenv calls. The setenv
       function does not write or create DCL symbols or OpenVMS
       logical names.

       This is consistent with UNIX behavior. On UNIX systems,
       setenv does not change or create any symbols that will be
       visible in the shell after the program exits.

423.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error. errno is set to ENOMEM-
                       Not enough memory available to expand the
                       environment list.

424  –  seteuid

    Sets the process's effective user ID.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int seteuid  (uid_t euid);

424.1  –  Argument

 euid

    The value to which you want the effective user ID set.

424.2  –  Description

    If the process has the IMPERSONATE privilege, the seteuid
    function sets the process's effective user ID.

    An unprivileged process can set the effective user ID only if the
    euid argument is equal to either the real, effective, or saved
    user ID of the process.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

    See also getuid to know how UIC is represented.

424.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The value of the euid argument is
                          invalid and not supported.

                       o  EPERM - The process does not have the
                          IMPERSONATE privilege, and euid does not
                          match the real user ID or the saved set-
                          user-ID.

425  –  setgid

    With POSIX IDs disabled, setgid is implemented for program
    portability and serves no function. It returns 0 (to indicate
    success).

    With POSIX IDs enabled, setgid sets the group IDs.

    Format

      #include  <types.h>

      #include  <unistd.h>

      int setgid  (__gid_t gid); (_DECC_V4_SOURCE)

      int setgid  (gid_t gid); (not _DECC_V4_SOURCE)

425.1  –  Argument

 gid

    The value to which you want the group IDs set.

425.2  –  Description

    The setgid function can be used with POSIX style identifiers
    enabled or disabled.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX IDs disabled, the setgid function is implemented for
    program portability and serves no function. It returns 0 (to
    indicate success).

    With POSIX style IDs enabled:

    o  If the process has the IMPERSONATE privilege, the setgid
       function sets the real group ID, effective group ID, and the
       saved set-group-ID to gid.

    o  If the process does not have appropriate privileges but gid is
       equal to the real group ID or to the saved set-group-ID, then
       the setgid function sets the effective group ID to gid. The
       real group ID and saved set-group-ID remain unchanged.

    o  Any supplementary group IDs of the calling process remain
       unchanged.

425.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The value of the gid argument
                          is invalid and not supported by the
                          implementation.

                       o  EPERM - The process does not have
                          appropriate privileges and gid does not
                          match the real group ID or the saved set-
                          group-ID.

426  –  setgrent

    Rewinds the group database.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <grp.h>

      void setgrent  (void);

426.1  –  Description

    The setgrent function effectively rewinds the group database to
    allow repeated searches.

    This function is always successful. No value is returned, and
    errno is not set.

427  –  setitimer

    Sets the value of interval timers.

    Format

      #include  <time.h>

      int setitimer  (int which, struct itimerval *value, struct
                     itimerval *ovalue);

427.1  –  Arguments

 which

    The type of interval timer. The C RTL only supports
    ITIMER_REAL.

 value

    A pointer to an itimerval structure whose members specify a timer
    interval and the time left to the end of the interval.

 ovalue

    A pointer to an itimerval structure whose members specify a
    current timer interval and the time left to the end of the
    interval.

427.2  –  Description

    The setitimer function sets the timer specified by which to the
    value specified by value, returning the previous value of the
    timer if ovalue is nonzero.

    A timer value is defined by the itimerval structure:

           struct itimerval {
                   struct  timeval it_interval;
                   struct  timeval it_value;
           };

    The value of the itimerval structure members are: as follows

    itimerval Member
    Value              Meaning

    it_interval = 0    Disables a timer after its next expiration
                       (assumes it_value is nonzero).
    it_interval =      Specifies a value used in reloading it_value
    nonzero            when the timer expires.
    it_value = 0       Disables a timer.
    it_value =         Indicates the time to the next timer
    nonzero            expiration.

    Time values smaller than the resolution of the system clock are
    rounded up to this resolution.

    The getitimer function provides one interval timer, defined in
    the <time.h> header file as ITIMER_REAL. This timer decrements in
    real time. When the timer expires, it delivers a SIGALARM signal.

                                   NOTE

       The interaction between setitimer and any of alarm, sleep,
       or usleep is unspecified.

427.3  –  Return Values

    0                  Indicates success.
    -1                 An error occurred; errno is set to indicate
                       the error.

428  –  setjmp

    Provides a way to transfer control from a nested series of
    function invocations back to a predefined point without returning
    normally. It does not use a series of return statements. The
    setjmp function saves the context of the calling function in an
    environment buffer.

    Format

      #include  <setjmp.h>

      int setjmp  (jmp_buf env);

428.1  –  Argument

 env

    The environment buffer, which must be an array of integers long
    enough to hold the register context of the calling function.
    The type jmp_buf is defined in the <setjmp.h> header file. The
    contents of the general-purpose registers, including the program
    counter (PC), are stored in the buffer.

428.2  –  Description

    When setjmp is first called, it returns the value 0. If longjmp
    is then called, naming the same environment as the call to
    setjmp, control is returned to the setjmp call as if it had
    returned normally a second time. The return value of setjmp in
    this second return is the value supplied by you in the longjmp
    call. To preserve the true value of setjmp, the function calling
    setjmp must not be called again until the associated longjmp is
    called.

    The setjmp function preserves the hardware general-purpose
    registers, and the longjmp function restores them. After a
    longjmp, all variables have their values as of the time of the
    longjmp except for local automatic variables not marked volatile.
    These variables have indeterminate values.

    The setjmp and longjmp functions rely on the OpenVMS
    condition-handling facility to effect a nonlocal goto with
    a signal handler. The longjmp function is implemented by
    generating a C RTL specified signal that allows the
    OpenVMS condition-handling facility to unwind back to the desired
    destination.

    The C RTL must be in control of signal handling for any
    VSI C image. For VSI C to be in control of signal handling,
    you must establish all exception handlers through a call to the
    VAXC$ESTABLISH function.

                                   NOTE

       The C RTL provides nonstandard decc$setjmp and decc$fast_
       longjmp functions for Alpha and Integrity server systems. To
       use these nonstandard functions instead of the standard
       ones, a program must be compiled with __FAST_SETJMP or
       __UNIX_SETJMP macros defined.

       Unlike the standard longjmp function, the decc$fast_longjmp
       function does not convert its second argument from 0 to 1.
       After a call to decc$fast_longjmp, a corresponding setjmp
       function returns with the exact value of the second argument
       specified in the decc$fast_longjmp call.

428.3  –  Restrictions

    You cannot invoke the longjmp function from an OpenVMS condition
    handler. However, you may invoke longjmp from a signal handler
    that has been established for any signal supported by the
    C RTL, subject to the following nesting restrictions:

    o  The longjmp function will not work if you invoke it from
       nested signal handlers. The result of the longjmp function,
       when invoked from a signal handler that has been entered as a
       result of an exception generated in another signal handler, is
       undefined.

    o  Do not invoke the setjmp function from a signal handler unless
       the associated longjmp is to be issued before the handling of
       that signal is completed.

    o  Do not invoke the longjmp function from within an exit handler
       (established with atexit or SYS$DCLEXH). Exit handlers are
       invoked after image tear-down, so the destination address of
       the longjmp no longer exists.

    o  Invoking longjmp from within a signal handler to return to
       the main thread of execution might leave your program in
       an inconsistent state. Possible side effects include the
       inability to perform I/O or to receive any more UNIX signals.
       Use siglongjmp instead.

428.4  –  Return Values

    See the
    Description
    section.

429  –  setkey

    Sets an encoding key for use by the encrypt function.

    Format

      #include  <unistd.h>

      #include  <stdlib.h>

      void setkey  (const char *key;)

429.1  –  Argument

 key

    A character array of length 64 containing 0s and 1s.

429.2  –  Description

    The argument of setkey is a character array of length 64
    containing only the characters with numerical value 0 and 1.
    If this string is divided into groups of 8, the low-order bit in
    each group is ignored, leading to a 56-bit key which is set into
    the machine.

    No value is returned.

    See also crypt and encrypt.

430  –  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);

430.1  –  Arguments

 category

    The name of the category. Specify LC_ALL to change or query the
    entire locale. Other valid category names are:

    o  LC_COLLATE

    o  LC_CTYPE

    o  LC_MESSAGES

    o  LC_MONETARY

    o  LC_NUMERIC

    o  LC_TIME

 locale

    Pointer to a string that specifies the locale.

430.2  –  Description

    The setlocale 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:

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

    o  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
       is 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.

    o  "C"

       Specifies the C locale. If a program does not call setlocale,
       the C locale is the default.

    o  "POSIX"

       This is the same as the C locale.

    o  ""

       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.

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

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

430.3  –  Return Values

    x                  Pointer to a string describing the locale.
    NULL               Indicates an error occurred; errno is set.

430.4  –  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 successful\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 successful\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 successful\n");
        }

      Running the example program produces the following result:

        setlocale (LC_ALL, "POSIX") call was successful

        setlocale (LC_ALL, "junk.junk_codeset")
        returned error: no such file or directory

        setlocale (LC_ALL, "sys$login:login.com")
        returned error: nontranslatable vms error code: 0x35C07C
        %c-f-localebad, not a locale file

431  –  setpgid

    Sets the process group ID for job control.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int setpgid  (pid_t pid, pid_t pgid);

431.1  –  Arguments

 pid

    The process ID for which the process group ID is to be set.

 pgid

    The value to which the process group ID is set.

431.2  –  Description

    The setpgid function is used either to join an existing process
    group or create a new process group within the session of the
    calling process. The process group ID of a session leader will
    not change.

    Upon successful completion, the process group ID of the process
    with a process ID of pid is set to pgid. As a special case, if
    pid is 0, the process ID of the calling process is used. Also, if
    pgid is 0, the process group ID of the indicated process is used.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

431.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EACCES - The value of the pid argument
                          matches the process ID of a child process
                          of the calling process and the child
                          process has successfully executed one of
                          the exec functions.

                       o  EINVAL - The value of the pgid argument is
                          less than 0, or is not a value supported by
                          the implementation.

                       o  EPERM - The process indicated by the pid
                          argument is a session leader. The value
                          of the pid argument matches the process ID
                          of a child process of the calling process,
                          and the child process is not in the same
                          session as the calling process. The value
                          of the pgid argument is valid but does
                          not match the process ID of the process
                          indicated by the pid argument, and there
                          is no process with a process group ID that
                          matches the value of the pgid argument in
                          the same session as the calling process.

                       o  ESRCH - The value of the pid argument does
                          not match the process ID of the calling
                          process or of a child process of the
                          calling process.

432  –  setpgrp

    Sets the process group ID.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      pid_t setpgrp  (void);

432.1  –  Description

    If the calling process is not already a session leader, setpgrp
    sets the process group ID of the calling process to the process
    ID of the calling process. If setpgrp creates a new session, then
    the new session has no controlling terminal.

    The setpgrp function has no effect when the calling process is a
    session leader.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

432.2  –  Return Value

    x                  The process group ID of the calling process.

433  –  setpwent

    Rewinds the user database.

    Format

      #include  <pwd.h>

      void setpwent  (void);

433.1  –  Description

    The setpwent function effectively rewinds the user database to
    allow repeated searches.

    No value is returned, but errno is set to EIO if an I/O error
    occurred.

    See also getpwent.

434  –  setregid

    Sets the real and effective group IDs.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int setregid  (gid_t rgid, gid_t egid);

434.1  –  Arguments

 rgid

    The value to which you want the real group ID set.

 egid

    The value to which you want the effective group ID set.

434.2  –  Description

    The setregid function is used to set the real and effective group
    IDs of the calling process. If rgid is -1, the real group ID
    is not changed; if egid is -1, the effective group ID is not
    changed. The real and effective group IDs can be set to different
    values in the same call.

    Only a process with the IMPERSONATE privilege can set the real
    group ID and the effective group ID to any valid value.

    A nonprivileged process can set either the real group ID to the
    saved set-group-ID from an exec function, or the effective group
    ID to the saved set-group-ID or the real group ID.

    Any supplementary group IDs of the calling process remain
    unchanged.

    If a set-group-ID process sets its effective group ID to its real
    group ID, it can still set its effective group ID back to the
    saved set-group-ID.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

434.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. Neither of the group IDs
                       is changed, and errno is set to one of the
                       following values:

                       o  EINVAL - The value of the rgid or egid
                          argument is invalid or out-of-range.

                       o  EPERM - The process does not have the
                          IMPERSONATE privilege, and a change
                          other than changing the real group ID to
                          the saved set-group-ID, or changing the
                          effective group ID to the real group ID or
                          the saved group ID, was requested.

435  –  setreuid

    Sets the user IDs.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int setreuid  (uid_t ruid, uid_t euid);

435.1  –  Arguments

 ruid

    The value to which you want the real user ID set.

 euid

    The value to which you want the effective user ID set.

435.2  –  Description

    The setreuid function sets the real and effective user IDs of
    the current process to the values specified by the ruid and euid
    arguments. If ruid or euid is -1, the corresponding effective or
    real user ID of the current process is left unchanged.

    A process with the IMPERSONATE privilege can set either ID to any
    value. An unprivileged process can set the effective user ID only
    if the euid argument is equal to either the real, effective, or
    saved user ID of the process.

    It is unspecified whether a process without the IMPERSONATE
    privilege is permitted to change the real user ID to match the
    current real, effective, or saved user ID of the process.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

    See also getuid to know how UIC is represented.

435.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The value of the ruid or euid
                          argument is invalid or out of range.

                       o  EPERM - The current process does not have
                          the IMPERSONATE privilege, and either an
                          attempt was made to change the effective
                          user ID to a value other than the real user
                          ID or the saved set-user-ID, or an attempt
                          was made to change the real user ID to a
                          value not permitted by the implementation.

436  –  setsid

    Creates a session and sets the process group ID.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      pid_t setsid  (void);

436.1  –  Description

    The setsid function creates a new session if the calling process
    is not a process group leader. Upon return, the calling process
    is the session leader of this new session and the process
    group leader of a new process group, and it has no controlling
    terminal. The process group ID of the calling process is set
    equal to the process ID of the calling process. The calling
    process is the only process in the new process group and the
    only process in the new session.

    This function requires that long (32-bit) UID/GID support be
    enabled. See 32-Bit UID and GID Macro (Integrity servers, Alpha)
    for more information.

436.2  –  Return Values

    x                  The process group ID of the calling process.
    (pid_t)-1          Indicates an error. The function sets errno to
                       the following value:

                       o  EPERM - The calling process is already a
                          process group leader, or the process group
                          ID of a process other than the calling
                          process matches the process ID of the
                          calling process.

437  –  setstate

    Restarts and changes random-number generators.

    Format

      char *setstate  (char *state;)

437.1  –  Argument

 state

    Points to the array of state information.

437.2  –  Description

    The setstate 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:

    o  Use the initstate function, with the desired seed, state
       array, and size of the array.

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

437.3  –  Return Values

    x                  A pointer to the previous state array
                       information.
    0                  Indicates an error. The state information is
                       damaged, and errno is set to the following
                       value:

                       o  EINVAL-The state argument is invalid.

438  –  setuid

    With POSIX IDs disabled, implemented for program portability and
    serves no function. It returns 0 (to indicate success).

    With POSIX IDs enabled, sets the user IDs.

    Format

      #include  <types.h>

      #include  <unistd.h>

      int setuid  (__uid_t uid); (_DECC_V4_SOURCE)

      uid_t setuid  (uid_t uid); (not _DECC_V4_SOURCE)

438.1  –  Argument

 uid

    The value to which you want the user IDs set.

438.2  –  Description

    The setuid function can be used with POSIX style identifiers
    enabled or disabled.

    POSIX style IDs are supported on OpenVMS Version 7.3-2 and
    higher.

    With POSIX IDs disabled (the default), the setuid function is
    implemented for program portability and serves no function. It
    returns 0 (to indicate success).

    With POSIX style IDs enabled:

    o  If the process has the IMPERSONATE privilege, the setuid
       function sets the real user ID, effective user ID, and the
       saved set-user-ID to uid.

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

    See also getuid to know how UIC is represented.

438.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - The value of the uid argument
                          is invalid and not supported by the
                          implementation.

                       o  EPERM - The process does not have
                          appropriate privileges and uid does not
                          match the real user ID or the saved set-
                          user-ID.

439  –  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);

439.1  –  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>: _IOFBF or _IOLBF.

 size

    The number of bytes to be used in buffer by the C RTL for
    buffering this file. The buffer size must be a minimum of 8192
    bytes and a maximum of 32767 bytes.

439.2  –  Description

    You can use the setvbuf function after the file is opened but
    before any I/O operations are performed.

    The C RTL provides the following types of ANSI-conforming file
    buffering:

    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 _IOLBF and _IOFBF defined in <stdio.h> for the
    type argument to specify line-buffered and fully buffered I/O,
    respectively.

    If file_ptr specifies a terminal device, the C RTL uses
    line-buffered I/O; otherwise, it uses fully buffered I/O.

    Please note that the previously documented value _IONBF is not
    supported.

    The C RTL automatically allocates a buffer to use for each
    I/O stream, so there are several buffer allocation possibilities:

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

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

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

439.3  –  Return Values

    0                  Indicates success.
    nonzero value      Indicates that an invalid input value was
                       specified for type or file_ptr, or because
                       file_ptr is being used by another thread.

440  –  shm_open

    Opens a shared memory object.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sys/mman.h>

      int shm_open  (const char *name, int oflag, mode_t mode);

440.1  –  Argument

 name

    Pointer to a string naming a shared memory object.

 oflag

    Specifies options that define file status and file access modes.
    This argument is constructed from the bitwise inclusive OR of
    zero or more of the options defined in the <fcntl.h> header file.

 mode

    The shared memory object's permission bits. This argument is used
    only when the shared memory object is being created.

440.2  –  Description

    The shm_open function establishes a connection between a shared
    memory object and a file descriptor. It creates an open file
    description that refers to the shared memory object and a file
    descriptor that refers to that open file description. The file
    descriptor is used by other functions to refer to that shared
    memory object. The name argument points to a string naming a
    shared memory object. The name can be a pathname, in which case
    other processes referring to the same pathname refer to the same
    shared memory object.

    When a shared memory object is created, its state and all data
    associated with it persist until the shared memory is unlinked.

    The shm_open function returns a file descriptor for the shared
    memory object that is the lowest numbered file descriptor not
    currently open for that process.

    The file status flags and file access modes of the open file
    description are set according to the value of oflag, and can have
    zero or more of the following values:

       O_RDONLY - Open for read access only.

       O_RDWR - Open for read or write access.

       O_CREAT - Create the shared memory if the memory object does
       not exist already. The user ID and group ID of the shared
       memory object are identical to those of the calling process.
       The shared memory object's permission bits are set to the
       value of mode, except those set in the file mode creation mask
       of the process.

       O_EXCL - Prevent the opening of a shared memory object if O_
       CREAT is set and the shared memory object already exists. Use
       this option only in combination with O_CREAT.

       O_TRUNC - Truncate the shared memory object to zero length if
       it is successfully opened for read or write access (O_RDWR).

    The initial contents of the shared memory object are binary
    zeros.

440.3  –  Return Values

    n                  Upon success, a nonnegative integer
                       representing the lowest numbered unused file
                       descriptor. The file descriptor points to the
                       shared memory object.
    -1                 Indicates failure. errno is set to indicate
                       the error:

                       o  EACCES - Permission to create the shared
                          memory object is denied, or the shared
                          memory object exists and the permissions
                          specified by oflag are denied, or O_TRUNC
                          is specified and write permission is
                          denied.

                       o  EEXIST - O_CREAT and O_EXCL are set, but
                          the named shared memory object already
                          exists.

                       o  EINTR - A signal has interrupted the shm_
                          open operation.

                       o  EINVAL - The shm_open operation is not
                          supported for the given name.

                       o  EMFILE - Too many file descriptors are
                          currently in use by this process.

                       o  ENAMETOOLONG - The length of the name
                          argument exceeds PATH_MAX or a pathname
                          component is longer than NAME_MAX.

                       o  ENFILE - Too many shared memory objects are
                          currently open in the system.

                       o  ENOENT - O_CREAT is not set and the named
                          shared memory object does not exist.

                       o  ENOSPC - Memory space for creation of the
                          new shared memory object is insufficient.

441  –  shm_unlink

    Removes a shared memory object.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <sys/mman.h>

      int shm_unlink  (const char *name);

441.1  –  Argument

 name

    Pointer to a string naming the shared memory object to remove.

441.2  –  Description

    The shm_unlink function removes the name of the shared memory
    object named by the string pointed to by name.

    If one or more references to the shared memory object exist
    when the object is unlinked, the name is removed before shm_
    unlink returns, but the removal of the memory object contents is
    postponed until all open and map references to the shared memory
    object have been removed.

    Even if the object continues to exist after the last shm_unlink,
    reuse of the name subsequently causes shm_unlink to behave as
    if no shared memory object with this name exists (that is, shm_
    open will fail if O_CREAT is not set, or will create a new shared
    memory object if O_CREAT is set).

441.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates failure, the named shared memory
                       object is not changed by the function call,
                       and errno is set to indicate the error:

                       o  EACCES - Permission is denied to unlink the
                          named shared memory object.

                       o  ENAMETOOLONG - The length of the name
                          argument exceeds PATH_MAX or a pathname
                          component is longer than NAME_MAX.

                       o  ENOENT - The named shared memory object
                          does not exist.

442  –  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);

442.1  –  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.

442.2  –  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:

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

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

    o  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_        This member can contain the following values:
    handler
               o  SIG_DFL - Specifies the default action taken when
                  the signal is delivered.

               o  SIG_IGN - Specifies that the signal has no effect on
                  the receiving process.

               o  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 intercepted.
    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 intercepted 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 intercepted or ignored to SIG_DFL is
    ignored or causes an error to be returned with errno set to
    EINVAL.

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual 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 sigvec, signal, wait, read, and write.

442.3  –  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:

                       o  EFAULT - The action or o_action argument
                          points to a location outside of the
                          allocated address space of the process.

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

443  –  sigaddset

    Adds the specified individual signal.

    Format

      #include  <signal.h>

      int sigaddset  (sigset_t *set, int sig_number);

443.1  –  Arguments

 set

    The signal set.

 sig_number

    The individual signal.

443.2  –  Description

    The sigaddset function manipulates sets of signals. This function
    operates on data objects that you can address by the application,
    not on any set of signals known to the system. For example, this
    function does not operate on the set blocked from delivery to a
    process or the set pending for a process.

    The sigaddset function adds the individual signal specified by
    sig_number from the signal set specified by set.

443.3  –  Example

      The following example shows how to generate and use a signal
      mask that blocks only the SIGINT signal from delivery:

               #include <signal.h>
               int return_value;
               sigset_t newset;
                 . . .
               sigemptyset(&newset);
               sigaddset(&newset, SIGINT);
               return_value = sigprocmask (SIG_SETMASK, &newset, NULL);

443.4  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of sig_number is not a
                          valid signal number.

444  –  sigblock

    Adds the signals in mask to the current set of signals being
    blocked from delivery.

    Format

      #include  <signal.h>

      int sigblock  (int mask);

444.1  –  Argument

 mask

    The signals to be blocked.

444.2  –  Description

    Signal i is blocked if the i - 1 bit in mask is a 1. For example,
    to add the protection-violation signal to the set of blocked
    signals, use the following line:

    sigblock(1 << (SIGBUS - 1));

    You can express signals in mnemonics (such as SIGBUS for a
    protection violation) or numbers as defined in the <signal.h>
    header file, and you can express combinations of signals by using
    the bitwise OR operator (|).

444.3  –  Return Value

    x                  Indicates the previous set of masked signals.

445  –  sigdelset

    Deletes a specified individual signal.

    Format

      #include  <signal.h>

      int sigdelset  (sigset_t *set, int sig_number;)

445.1  –  Arguments

 set

    The signal set.

 sig_number

    The individual signal.

445.2  –  Description

    The sigdelset function deletes the individual signal specified by
    sig_number from the signal set specified by set.

    This function operates on data objects that you can address by
    the application, not on any set of signals known to the system.
    For example, this function does not operate on the set blocked
    from delivery to a process or the set pending for a process.

445.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of sig_number is not a
                          valid signal number.

446  –  sigemptyset

    Initializes the signal set to exclude all signals.

    Format

      #include  <signal.h>

      int sigemptyset  (sigset_t *set);

446.1  –  Argument

 set

    The signal set.

446.2  –  Description

    The sigemptyset function initializes the signal set pointed to
    by set such that you exclude all signals. A call to sigemptyset
    or sigfillset must be made at least once for each object of type
    sigset_t prior to any other use of that object.

    This function operates on data objects that you can address by
    the application, not on any set of signals known to the system.
    For example, this function does not operate on the set blocked
    from delivery to a process or the set pending for a process.

    See also sigfillset.

446.3  –  Example

      The following example shows how to generate and use a signal
      mask that blocks only the SIGINT signal from delivery:

               #include <signal.h>
               int return_value;
               sigset_t newset;
                 . . .
               sigemptyset(&newset);
               sigaddset(&newset, SIGINT);
               return_value = sigprocmask (SIG_SETMASK, &newset, NULL);

446.4  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; the global errno is set to
                       indicate the error.

447  –  sigfillset

    Initializes the signal set to include all signals.

    Format

      #include  <signal.h>

      int sigfillset  (sigset_t *set);

447.1  –  Argument

 set

    The signal set.

447.2  –  Description

    The sigfillset function initializes the signal set pointed to
    by set such that you include all signals. A call to sigemptyset
    or sigfillset must be made at least once for each object of type
    sigset_t prior to any other use of that object.

    This function operates on data objects that you can address by
    the application, not on any set of signals known to the system.
    For example, this function does not operate on the set blocked
    from delivery to a process or the set pending for a process.

    See also sigemptyset.

447.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of the sig_number
                          argument is not a valid signal number.

448  –  sighold

    Adds the specified signal to the calling process's signal mask.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sighold  (int signal);

448.1  –  Argument

 signal

    The specified signal. The signal argument can be assigned any of
    the signals defined in the <signal.h> header file, except SIGKILL
    and SIGSTOP.

448.2  –  Description

    The sighold, sigrelse, and sigignore functions provide simplified
    signal management:

    o  The sighold function adds signal to the calling process's
       signal mask.

    o  The sigrelse function removes signal from the calling
       process's signal mask.

    o  The sigignore function sets the disposition of signal to SIG_
       IGN.

    The sighold function, in conjunction with sigrelse and sigpause,
    can be used to establish critical regions of code that require
    the delivery of a signal to be temporarily deferred.

    Upon success, the sighold function returns a value of 0.
    Otherwise, a value of -1 is returned, and errno is set to
    indicate the error.

                                   NOTE

       These interfaces are provided for compatibility only. New
       programs should use sigaction and sigprocmask to control the
       disposition of signals.

448.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of the signal argument
                          is either an invalid signal number or
                          SIGKILL.

449  –  sigignore

    Sets the disposition of the specified signal to SIG_IGN.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sigignore  (int signal);

449.1  –  Argument

 signal

    The specified signal. The signal argument can be assigned any of
    the signals defined in the <signal.h> header file, except SIGKILL
    and SIGSTOP.

449.2  –  Description

    The sighold, sigrelse, and sigignore functions provide simplified
    signal management:

    o  The sighold function adds signal to the calling process's
       signal mask.

    o  The sigrelse function removes signal from the calling
       process's signal mask.

    o  The sigignore function sets the disposition of signal to SIG_
       IGN.

    The sighold function, in conjunction with sigrelse and sigpause,
    can be used to establish critical regions of code that require
    the delivery of a signal to be temporarily deferred.

    Upon success, the sigignore function returns a value of 0.
    Otherwise, a value of -1 is returned, and errno is set to
    indicate the error.

                                   NOTE

       These interfaces are provided for compatibility only. New
       programs should use sigaction and sigprocmask to control the
       disposition of signals.

449.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of the signal argument
                          is either an invalid signal number or
                          SIGKILL, or an attempt is made to catch
                          a signal that cannot be intercepted or to
                          ignore a signal that cannot be ignored.

450  –  sigismember

    Tests whether a specified signal is a member of the signal set.

    Format

      #include  <signal.h>

      int sigismember  (const sigset_t *set, int sig_number);

450.1  –  Arguments

 set

    The signal set.

 sig_number

    The individual signal.

450.2  –  Description

    The sigismember function tests whether sig_number is a member of
    the signal set pointed to by set.

    This function operates on data objects that you can address by
    the application, not on any set of signals known to the system.
    For example, this function does not operate on the set blocked
    from delivery to a process or the set pending for a process.

450.3  –  Return Values

    1                  Indicates success. The specified signal is a
                       member of the specified set.
    0                  Indicates an error. The specified signal is
                       not a member of the specified set.

451  –  siglongjmp

    Nonlocal goto with signal handling.

    Format

      #include  <setjmp.h>

      void siglongjmp  (sigjmp_buf env, int value);

451.1  –  Arguments

 env

    An address for a sigjmp_buf structure.

 value

    A nonzero value.

451.2  –  Description

    The siglongjmp function restores the environment saved by the
    most recent call to sigsetjmp in the same process with the
    corresponding sigjmp_buf argument.

    All accessible objects have values when siglongjmp is called,
    with one exception: values of objects of automatic storage
    duration that changed between the sigsetjmp call and siglongjmp
    call are indeterminate.

    Because it bypasses the usual function call and return
    mechanisms, siglongjmp executes correctly during interrupts,
    signals, and any of their associated functions. However, if you
    invoke siglongjmp from a nested signal handler (for example,
    from a function invoked as a result of a signal raised during the
    handling of another signal), the behavior is undefined.

    The siglongjmp function restores the saved signal mask only if
    you initialize the env argument by a call to sigsetjmp with a
    nonzero savemask argument.

    After siglongjmp is completed, program execution continues
    as if the corresponding call of sigsetjmp just returned the
    value specified by value. The siglongjmp function cannot cause
    sigsetjmp to return 0 (zero); if value is 0, sigsetjmp returns 1

    See also sigsetjmp.

452  –  sigmask

    Constructs the mask for a given signal number.

    Format

      #include  <signal.h>

      int sigmask  (signum);

452.1  –  Argument

 signum

    The signal number for which the mask is to be constructed.

452.2  –  Description

    The sigmask function is used to construct the mask for a given
    signum. This mask can be used with the sigblock function.

452.3  –  Return Value

    x                  The mask constructed for signum

453  –  signal

    Allows you to specify the way in which the signal sig is to be
    handled: use the default handling for the signal, ignore the
    signal, or call the signal handler at the address specified.

    Format

      #include  <signal.h>

      void  (*signal (int sig, void (*func) (int))) (int);

453.1  –  Arguments

 sig

    The number or mnemonic associated with a signal. This argument
    is usually one of the mnemonics defined in the <signal.h> header
    file.

 func

    Either the action to take when the signal is raised, or the
    address of a function needed to handle the signal.

453.2  –  Description

    If func is the constant SIG_DFL, the action for the given
    signal is reset to the default action, which is to terminate
    the receiving process. If the argument is SIG_IGN, the signal is
    ignored. Not all signals can be ignored.

    If func is neither SIG_DFL nor SIG_IGN, it specifies the address
    of a signal-handling function. When the signal is raised, the
    addressed function is called with sig as its argument. When the
    addressed function returns, the interrupted process continues
    at the point of interruption. (This is called catching a signal.
    Signals are reset to SIG_DFL after they are intercepted, except
    as shown in the Error and Signal Handling chapter of the VSI C RTL
    Reference Manual.

    You must call the signal function each time you want to catch a
    signal.

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

    To cause an OpenVMS exception or a signal to generate a UNIX
    style signal, OpenVMS condition handlers must return SS$_RESIGNAL
    upon receiving any exception that they do not want to handle.
    Returning SS$_CONTINUE prevents the correct generation of a UNIX
    style signal.

453.3  –  Return Values

    x                  The address of the function previously
                       established to handle the signal.
    SIG_ERR            Indicates that the sig argument is out of
                       range.

454  –  sigpause

    Assigns mask to the current set of masked signals and then waits
    for a signal.

    Format

      #include  <signal.h>

      int sigpause  (int mask);

454.1  –  Argument

 mask

    The signals to be blocked.

454.2  –  Description

    See the sigblock function for information about the mask
    argument.

    When control returns to sigpause, the function restores the
    previous set of masked signals, sets errno to EINTR, and returns
    -1 to indicate an interrupt. The value EINTR is defined in the
    <errno.h> header file.

454.3  –  Return Value

    -1                 Indicates an interrupt. errno is set to EINTR.

455  –  sigpending

    Examines pending signals.

    Format

      #include  <signal.h>

      int sigpending  (sigset_t *set);

455.1  –  Argument

 set

    A pointer to a sigset_t structure.

455.2  –  Description

    The sigpending function stores the set of signals that are
    blocked from delivery and pending to the calling process in the
    location pointed to by the set argument.

    Call either the sigemptyset or the sigfillset function at least
    once for each object of type sigset_t prior to any other use of
    that object. If you do not initialize an object in this way and
    supply an argument to the sigpending function, the result is
    undefined.

    See also sigemptyset and sigfillset in this section.

455.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  SIGSEGV - Bad mask argument.

456  –  sigprocmask

    Sets the current signal mask.

    Format

      #include  <signal.h>

      int sigprocmask  (int how, const sigset_t *set, sigset_t *o_set);

456.1  –  Arguments

 how

    An integer value that indicates how to change the set of masked
    signals. Use one of the following values:

    SIG_BLOCK     The resulting set is the union of the current set
                  and the signal set pointed to by the set argument.
    SIG_UNBLOCK   The resulting set is the intersection of the
                  current set and the complement of the signal set
                  pointed to by the set argument.
    SIG_SETMASK   The resulting set is the signal set pointed to by
                  the set argument.

 set

    The signal set. If the value of the set argument is:

    o  Not NULL - It points to a set of signals used to change the
       currently blocked set.

    o  NULL - The value of the how argument is not significant, and
       the process signal mask is unchanged, so you can use the call
       to inquire about currently blocked signals.

 o_set

    A non-NULL pointer to the location where the signal mask in
    effect at the time of the call is stored.

456.2  –  Description

    The sigprocmask function is used to examine or change the signal
    mask of the calling process.

    Typically, use the sigprocmask SIG_BLOCK value to block signals
    during a critical section of code, then use the sigprocmask SIG_
    SETMASK value to restore the mask to the previous value returned
    by the sigprocmask SIG_BLOCK value.

    If there are any unblocked signals pending after the call to the
    sigprocmask function, at least one of those signals is delivered
    before the sigprocmask function returns.

    You cannot block SIGKILL or SIGSTOP signals with the sigprocmask
    function. If a program attempts to block one of these signals,
    the sigprocmask function gives no indication of the error.

456.3  –  Example

      The following example shows how to set the signal mask to block
      only the SIGINT signal from delivery:

          #include <signal.h>

          int return_value;
          sigset_t newset;
           . . .
          sigemptyset(&newset);
          sigaddset(&newset, SIGINT);
          return_value = sigprocmask (SIG_SETMASK, &newset, NULL);

456.4  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error. The signal mask of the
                       process is unchanged. errno is set to one of
                       the following values:

                       o  EINVAL - The value of the how argument is
                          not equal to one of the defined values.

                       o  EFAULT - The set or o_set argument points
                          to a location outside the allocated address
                          space of the process.

457  –  sigrelse

    Removes the specified signal from the calling process's signal
    mask.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sigrelse  (int signal);

457.1  –  Argument

 signal

    The specified signal. The signal argument can be assigned any of
    the signals defined in the <signal.h> header file, except SIGKILL
    and SIGSTOP.

457.2  –  Description

    The sighold, sigrelse, and sigignore functions provide simplified
    signal management:

    o  The sighold function adds signal to the calling process's
       signal mask.

    o  The sigrelse function removes signal from the calling
       process's signal mask.

    o  The sigignore function sets the disposition of signal to SIG_
       IGN.

    The sighold function, in conjunction with sigrelse and sigpause,
    can be used to establish critical regions of code that require
    the delivery of a signal to be temporarily deferred.

    Upon success, the sigrelse function returns a value of 0.
    Otherwise, a value of -1 is returned, and errno is set to
    indicate the error.

                                   NOTE

       These interfaces are provided for compatibility only. New
       programs should use sigaction and sigprocmask to control the
       disposition of signals.

457.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno is set to the
                       following value:

                       o  EINVAL - The value of the signal argument
                          is either an invalid signal number or
                          SIGKILL.

458  –  sigsetjmp

    Sets a jump point for a nonlocal goto.

    Format

      #include  <setjmp.h>

      init sigsetjmp  (sigjmp_buf env, int savemask);

458.1  –  Arguments

 env

    An address for a sigjmp_buf structure.

 savemask

    An integer value that specifies whether you need to save the
    current signal mask.

458.2  –  Description

    The sigsetjmp function saves its calling environment in its env
    argument for later use by the siglongjmp function.

    If the value of savemask is not 0 (zero), sigsetjmp also
    saves the process's current signal mask as part of the calling
    environment.

    See also siglongjmp.

458.3  –  Restrictions

    You cannot invoke the longjmp function from an OpenVMS condition
    handler. However, you may invoke longjmp from a signal handler
    that has been established for any signal supported by the
    C RTL, subject to the following nesting restrictions:

    o  The longjmp function will not work if you invoke it from
       nested signal handlers. The result of the longjmp function,
       when invoked from a signal handler that has been entered as a
       result of an exception generated in another signal handler, is
       undefined.

    o  Do not invoke the sigsetjmp function from a signal handler
       unless the associated longjmp is to be issued before the
       handling of that signal is completed.

    o  Do not invoke the longjmp function from within an exit handler
       (established with atexit or SYS$DCLEXH). Exit handlers are
       invoked after image tear-down, so the destination address of
       the longjmp no longer exists.

    o  Invoking longjmp from within a signal handler to return to
       the main thread of execution might leave your program in
       an inconsistent state. Possible side effects include the
       inability to perform I/O or to receive any more UNIX signals.
       Use siglongjmp instead.

458.4  –  Return Values

    0                  Indicates success.
    nonzero            The return is a call to the siglongjmp
                       function.

459  –  sigsetmask

    Establishes those signals that are blocked from delivery.

    Format

      #include  <signal.h>

      int sigsetmask  (int mask);

459.1  –  Argument

 mask

    The signals to be blocked.

459.2  –  Description

    See the sigblock function for information about the mask
    argument.

459.3  –  Return Value

    x                  The previous set of masked signals.

460  –  sigsuspend

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

    Format

      #include  <signal.h>

      int sigsuspend  (const sigset_t *signal_mask);

460.1  –  Argument

 signal_mask

    A pointer to a set of signals.

460.2  –  Description

    The sigsuspend 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 intercepted 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.

461  –  sigtimedwait

    Suspends a calling thread and waits for queued signals to arrive.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sigtimedwait  (const sigset_t set, siginfo_t *info, const
                        struct timespec *timeout);

461.1  –  Arguments

 set

    The set of signals to wait for.

 info

    Pointer to a siginfo structure that is receiving data describing
    the signal, including any application-defined data specified when
    the signal was posted.

 timeout

    A timeout for the wait. If timeout is NULL, the argument is
    ignored.

461.2  –  Description

    The sigtimedwait function behaves the same as the sigwaitinfo
    function except that if none of the signals specified by set are
    pending, sigtimedwait waits for the time interval specified in
    the timespec structure referenced by timeout. If the timespec
    structure pointed to by timeout is zero-valued and if none of the
    signals specified by set are pending, then sigtimedwait returns
    immediately with an error.

    See also sigwait and sigwaitinfo.

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

461.3  –  Return Values

    x                  Upon successful completion, the signal number
                       selected is returned.
    -1                 Indicates that an error occurred; errno is set
                       to one of the following values:

                       o  EINVAL - The timeout argument specified a
                          tv_nsec value less than 0 or greater than
                          or equal to 1 billion.

                       o  EINTR - The wait was interrupted by an
                          unblocked, intercepted signal.

                       o  EAGAIN - No signal specified by set was
                          generated within the specified timeout
                          period.

462  –  sigvec

    Permanently assigns a handler for a specific signal.

    Format

      #include  <signal.h>

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

462.1  –  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.

462.2  –  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:

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

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

462.3  –  Return Values

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

463  –  sigwait

    Suspends a calling thread and waits for queued signals to arrive.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sigwait  (const sigset_t set, int *sig);

463.1  –  Arguments

 set

    The set of signals to wait for.

 sig

    Returns the signal number of the selected signal.

463.2  –  Description

    The sigwait function suspends the calling thread until at least
    one of the signals in the set argument is in the caller's set
    of pending signals. When this happens, one of those signals
    is automatically selected and removed from the set of pending
    signals. The signal number identifying that signal is then
    returned in the location referenced by sig.

    The effect is unspecified if any signals in the set argument are
    not blocked when the sigwait function is called.

    The set argument is created using the set manipulation functions
    sigemptyset, sigfillset, sigaddset, and sigdelset.

    If, while the sigwait function is waiting, a signal occurs that
    is eligible for delivery (that is, not blocked by the signal
    mask), that signal is handled asynchronously and the wait is
    interrupted.

    See also sigtimedwait and sigwaitinfo.

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

463.3  –  Return Values

    0                  Upon successful completion, sigwait stores the
                       signal number of the received signal at the
                       location referenced by sig and returns 0.
    nonzero            Indicates that an error occurred; errno is set
                       to the following value:

                       o  EINVAL - The set argument contains an
                          invalid or unsupported signal number.

464  –  sigwaitinfo

    Suspends a calling thread and waits for queued signals to arrive.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <signal.h>

      int sigwaitinfo  (const sigset_t set, siginfo_t *info);

464.1  –  Arguments

 set

    The set of signals to wait for.

 info

    Pointer to a siginfo structure that is receiving data describing
    the signal, including any application-defined data specified when
    the signal was posted.

464.2  –  Description

    The sigwaitinfo function behaves the same as the sigwait function
    if the info argument is NULL.

    If the info argument is non-NULL, the sigwaitinfo function
    behaves the same as sigwait, except that the selected signal
    number is stored in the si_signo member of the siginfo structure,
    and the cause of the signal is stored in the si_code member.
    If any value is queued to the selected signal, the first such
    queued value is dequeued and the value is stored in the si_value
    member of info. The system resource used to queue the signal is
    released and made available to queue other signals. If no value
    is queued, the content of the si_value member is undefined. If no
    further signals are queued for the selected signal, the pending
    indication for that signal is reset.

    See also sigtimedwait and sigwait.

    See the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

464.3  –  Return Values

    x                  Upon successful completion, the signal number
                       selected is returned.
    -1                 Indicates that an error occurred; errno is set
                       to one of the following values:

                       o  EINVAL - The set argument contains an
                          invalid or unsupported signal number.

                       o  EINTR - The wait was interrupted by an
                          unblocked, intercepted signal.

465  –  sin

    Returns the sine of its radian argument.

    Format

      #include  <math.h>

      double sin  (double x);

      float sinf  (float x); (Integrity servers, Alpha)

      long double sinl  (long double x); (Integrity servers, Alpha)

      double sind  (double x); (Integrity servers, Alpha)

      float sindf  (float x); (Integrity servers, Alpha)

      long double sindl  (long double x); (Integrity servers, Alpha)

465.1  –  Argument

 x

    A radian expressed as a floating-point number.

465.2  –  Description

    The sin functions compute the sine of x measured in radians.

    The sind functions compute the sine of x measured in degrees.

465.3  –  Return Values

    x                  The sine of the argument.
    NaN                x = Infinity or NaN; errno is set to EDOM.
    0                  Underflow occurred; errno is set to ERANGE.

466  –  sinh

    Returns the hyperbolic sine of its argument.

    Format

      #include  <math.h>

      double sinh  (double x);

      float sinhf  (float x); (Integrity servers, Alpha)

      long double sinhl  (long double x); (Integrity servers, Alpha)

466.1  –  Argument

 x

    A real number.

466.2  –  Return Values

    n                  The hyperbolic sine of the argument.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    0                  Underflow occurred; errno is set to ERANGE.
    NaN                x is NaN; errno is set to EDOM.

467  –  sleep

    Suspends the execution of the current process (or thread in a
    threaded program) 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)

467.1  –  Argument

 seconds

    The number of seconds.

467.2  –  Description

    The sleep function sleeps for the specified number of seconds, or
    until a signal is received, or until the process (or thread in a
    threaded program) 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.

467.3  –  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.

468  –  snprintf

    Performs formatted output to a string in memory.

    Format

      #include  <stdio.h>

      int snprintf  (char *str, size_t n, const char
                    *format_spec, . . . );

468.1  –  Arguments

 str

    The address of the string that will receive the formatted output.

 n

    The size of the buffer referred to by str.

 format_spec

    A pointer to a character string that contains the format
    specification.

  . . .

    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.

468.2  –  Description

    The snprintf function is identical to the sprintf function with
    the addition of the n argument, which specifies the size of the
    buffer referred to by str.

    On successful completion, snprintf returns the number of bytes
    (excluding the terminating null byte) that would be written to
    str if n is sufficiently large.

    If n is 0, nothing is written, the number of bytes (excluding the
    terminating null) that would be written if n were sufficiently
    large are returned, and str might be a NULL pointer. Otherwise,
    output bytes beyond the n - 1st are discarded instead of being
    written to the array, and a null byte is written at the end of
    the bytes actually written into the array.

    If an output error is encountered, a negative value is returned.

468.3  –  Return Values

    x                  The number of bytes (excluding the terminating
                       null byte) that would be written to str if n
                       is sufficiently large.
    Negative value     Indicates an output error occurred. The
                       function sets errno. For a list of errno
                       values set by this function, see fprintf.

469  –  sprintf

    Performs formatted output to a string in memory.

    Format

      #include  <stdio.h>

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

469.1  –  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.

  . . .

    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.

469.2  –  Description

    The sprintf function places output followed by the null character
    (\0) in consecutive bytes starting at *str. The user must ensure
    that enough space is available.

    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.

469.3  –  Return Values

    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.

470  –  sqrt

    Returns the square root of its argument.

    Format

      #include  <math.h>

      double sqrt  (double x);

      float sqrtf  (float x); (Integrity servers, Alpha)

      long double sqrtl  (long double x); (Integrity servers, Alpha)

470.1  –  Argument

 x

    A real number.

470.2  –  Return Values

    val                The square root of x, if x is nonnegative.
    0                  x is negative; errno is set to EDOM.
    NaN                x is NaN; errno is set to EDOM.

471  –  srand

    Initializes the pseudorandom-number generator rand.

    Format

      #include  <stdlib.h>

      void srand  (unsigned int seed);

471.1  –  Argument

 seed

    An unsigned integer.

471.2  –  Description

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

    If srand is then called with the same seed value, the sequence of
    pseudorandom numbers is repeated.

    If rand is called before any calls to srand, the same sequence of
    pseudorandom numbers is generated as when srand is first called
    with a seed value of 1.

472  –  srand48

    Initializes a 48-bit random-number generator.

    Format

      #include  <stdlib.h>

      void srand48  (long int seed_val);

472.1  –  Argument

 seed_val

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

472.2  –  Description

    The srand48 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 automatically
    supplied 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 330E16.

    See also drand48, lrand48, and mrand48.

473  –  srandom

    Initializes the pseudorandom-number generator random.

    Format

      #include  <stdlib.h>

      int srandom  (unsigned seed);

473.1  –  Argument

 seed

    An initial seed value.

473.2  –  Description

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

473.3  –  Return Values

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

474  –  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, . . . );

474.1  –  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.

  . . .

    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.

474.2  –  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.

474.3  –  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.

475  –  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, . . . );

475.1  –  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 the Error and Signal Handling chapter of the VSI C RTL
    Reference Manual.

 func

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

475.2  –  Description

    The ssignal 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 the "Error and Signal Handling" chapter of the VSI C RTL
    Reference Manual for more information on signal handling.

475.3  –  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).

476  –  [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);

476.1  –  Argument

 win

    A pointer to the window.

476.2  –  Description

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

476.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

477  –  [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);

477.1  –  Argument

 win

    A pointer to the window.

477.2  –  Description

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

477.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

478  –  stat

    Accesses information about the specified file.

    Format

      #include  <stat.h>

      int stat  (const char *file_spec, struct stat *buffer);
                (ISO POSIX-1)

      int stat  (const char *file_spec, struct stat *buffer, . . . );
                (DEC C Extension)

478.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    stat function that is equivalent to the behavior before OpenVMS
    Version 7.0.

    Compiling with the _USE_STD_STAT feature-test macro defined
    enables a variant of the stat function that uses an X/Open
    standard-compliant definition of the stat structure. The _USE_
    STD_STAT feature-test macro is mutually exclusive with the _DECC_
    V4_SOURCE and _VMS_V6_SOURCE macros.

478.2  –  Arguments

 file_spec

    A valid OpenVMS or UNIX style file specification (no wildcards).
    Read, write, or execute permission of the named file is not
    required, but you must be able to reach all directories listed
    in the file specification leading to the file.

 buffer

    A pointer to a structure of type stat. For convenience, a typedef
    stat_t is defined as struct stat in the <stat.h> header file.

    This argument receives information about the particular file. The
    members of the structure pointed to by buffer are described in
    the Description section.

  . . .

    An optional default file-name string.

    This is the only optional RMS keyword that can be specified for
    the stat function. See the description of the creat function for
    the full list of optional RMS keywords and their values.

478.3  –  Description

    When the _USE_STD_STAT feature-test macro is not enabled, the
    legacy stat structure is used. When _USE_STD_STAT is enabled, the
    X/Open standard-compliant stat structure is used.

    Legacy stat Structure

    With the _USE_STD_STAT feature-test macro defined to DISABLE, the
    following legacy stat structure is used:

    Member       Type        Definition

    st_dev       dev_t       Pointer to the physical device name
    st_ino[3]    ino_t       Three words to receive the file ID
    st_mode      mode_t      File "mode" (prot, dir, . . . )
    st_nlink     nlink_t     For UNIX system compatibility only
    st_uid       uid_t       Owner user ID
    st_gid       gid_t       Group member: from st_uid
    st_rdev      dev_t       UNIX system compatibility - always 0
    st_size      off_t       File size, in bytes. For st_size to
                             report a correct value, you need to
                             flush both the C RTL and RMS buffers.
    st_atime     time_t      File access time; always the same as
                             st_mtime
    st_mtime     time_t      Last modification time
    st_ctime     time_t      File creation time
    st_fab_rfm   char        Record format
    st_fab_rat   char        Record attributes
    st_fab_fsz   char        Fixed header size
    st_fab_mrs   unsigned    Record size

    The types dev_t, ino_t, off_t, mode_t, nlink_t, uid_t, gid_t, and
    time_t, are defined in the <stat.h> header file. However, when
    compiling for compatibility (/DEFINE=_DECC_V4_SOURCE), only dev_
    t, ino_t, and off_t are defined.

    The off_t data type is either a 32-bit or 64-bit integer. The 64-
    bit interface allows for file sizes greater than 2 GB, and can be
    selected at compile time by defining the _LARGEFILE feature-test
    macro as follows:

    CC/DEFINE=_LARGEFILE

    As of OpenVMS Version 7.0, times are given in seconds since the
    Epoch (00:00:00 GMT, January 1, 1970).

    The st_mode structure member is the status information mode
    defined in the <stat.h> header file. The st_mode bits are
    described as follows:

    Bits     Constant   Definition

    0170000  S_IFMT     Type of file
    0040000  S_IFDIR    Directory
    0020000  S_IFCHR    Character special
    0060000  S_IFBLK    Block special
    0100000  S_IFREG    Regular
    0030000  S_IFMPC    Multiplexed char special
    0070000  S_IFMPB    Multiplexed block special
    0004000  S_ISUID    Set user ID on execution
    0002000  S_ISGID    Set group ID on execution
    0001000  S_ISVTX    Save swapped text even after use
    0000400  S_IREAD    Read permission, owner
    0000200  S_IWRITE   Write permission, owner
    0000100  S_IEXEC    Execute/search permission, owner

    The stat function does not work on remote network files.

    If the file is a record file, the st_size field includes
    carriage-control information. Consequently, the st_size value
    will not correspond to the number of characters that can be read
    from the file.

    Also be aware that for st_size to report a correct value, you
    need to flush both the C RTL and RMS buffers.

    Standard-Compliant stat Structure

    With OpenVMS Version 8.2, the _USE_STD_STAT feature-test macro
    and standard-compliant stat structure are introduced in support
    of UNIX compatibility.

    With _USE_STD_STAT defined to ENABLE, you get the following
    behavior:

    o  Old struct stat definitions

       Old definitions of struct stat are obsolete. You must
       recompile your applications to access the new features.
       Existing applications will continue to access the old
       definitions and functions unless they are recompiled to use
       the new features.

    o  Function variants

       Calls to stat, fstat, lstat, and ftw accept pointers to
       structures of the new type. Calls to these functions are
       mapped to the new library entries __std_stat, __std_fstat,
       __std_lstat, and __std_ftw,  respectively.

    o  Compatibilities with other feature macros

       _DECC_V4_SOURCE source-code compatibility is not supported.
       You must not enable _DECC_V4_SOURCE and _USE_STD_STAT at the
       same time.

       _VMS_V6_SOURCE binary compatibility is not supported. You must
       not enable _VMS_V6_SOURCE and _USE_STD_STAT at the same time.
       As a result, only UTC (rather than local-time) is supported
       for the time_t fields.

    o  Type changes

       The following type changes are in effect:

       -  32-bit gid type gid_t is used. _DECC_SHORT_GID_T is
          unsupported.

       -  _LARGEFILE offsets are used. off_t is forced to 64 bits.

       -  Type ino_t, representing the file number, is an unsigned
          int quadword (64 bits). Previously, it was an unsigned
          short.

       -  Type dev_t, representing the device id, is an unsigned int
          quadword (64 bits). Previously, it was a 32-bit character
          pointer. The new type is standard because it is arithmetic.

       -  Types blksize_t and blkcnt_t are added and defined as
          unsigned int quadwords (64 bits).

    o  Structure member Changes

       -  Two members are added to struct stat:

          blksize_t   st_blksize;
          blkcnt_t    st_blocks;

          According to the X/Open standard, st_blksize is the
          filesystem-specific preferred I/O blocksize for this file.
          On OpenVMS systems, st_blksize is set to the device buffer
          size multiplied by the disk cluster size. st_blocks is set
          to the allocated size of the file, in blocks. The blocksize
          used to calculate st_blocks is not necessarily the same as
          st_blksize and, in most cases, will not be the same.

       -  In struct stat, member st_ino is of type ino_t. In previous
          C RTL versions, it was of type ino_t [3] (array of 3 ino_
          t). Since ino_t has changed from a word to a quadword,
          the size of this member has increased by one word. The
          principal significance of this change is that it makes st_
          ino a scalar, which is how most open source applications
          define it.

       -  The new definition of ino_t also affects applications
          that include the <dirent.h> header file. In struct dirent,
          member d_ino changes in the same way as the st_ino member
          of struct stat in <stat.h>.

       -  Several macros that are not part of any standard were
          introduced in <stat.h> to facilitate access to the
          constituent parts of ino_t values:

             S_INO_NUM(ino), S_INO_SEQ(ino), and S_INO_RVN(ino)
             return the FILES-11 file number, sequence number, and
             relative volume number of ino, respectively, as unsigned
             shorts.

             S_INO_RVN_RVN(ino) returns the byte of the RVN field
             containing the relative volume number;

             S_INO_RVN_NMX(ino) returns the byte of the RVN field
             containing the file number extension.

          Although individual components can be broken out like this,
          they are not part of the X/Open standard and should not be
          relied on in portable applications.

    o  Semantic changes

       Values of type dev_t are now unique for each device across
       clusters. An algorithm based on device name and allocation
       class or SCSSYSTEMID (for single-pathed devices) calculates
       the device id value having these characteristics, an X/Open
       standard requirement. Typically, the combination of file
       number and device id uniquely identifies a file in a cluster.

       This change affects stat structure members st_dev and st_rdev.
       For compatibility with previous releases, st_rdev is set to
       either 0 or st_dev.

                     NOTE (Integrity servers, Alpha)

       On OpenVMS Alpha and Integrity server systems, the stat,
       fstat, utime, and utimes functions have been enhanced to
       take advantage of the new file-system support for POSIX
       compliant file timestamps.

       This support is available only on ODS-5 devices on OpenVMS
       Alpha systems beginning with a version of OpenVMS Alpha
       after Version 7.3.

       Before this change, the stat and fstat functions were
       setting the values of the st_ctime, st_mtime, and st_atime
       fields based on the following file attributes:

          st_ctime - ATR$C_CREDATE (file creation time)
          st_mtime - ATR$C_REVDATE (file revision time)
          st_atime - was always set to st_mtime because no support
          for file access time was available

       Also, for the file-modification time, utime and utimes were
       modifying the ATR$C_REVDATE file attribute, and ignoring the
       file-access-time argument.

       After the change, for a file on an ODS-5 device, the stat
       and fstat functions set the values of the st_ctime, st_
       mtime, and st_atime fields based on the following new file
       attributes:

          st_ctime - ATR$C_ATTDATE (last attribute modification
          time)
          st_mtime - ATR$C_MODDATE (last data modification time)
          st_atime - ATR$C_ACCDATE (last access time)

       If ATR$C_ACCDATE is zero, as on an ODS-2 device, the stat
       and fstat functions set st_atime to st_mtime.

       For the file-modification time, the utime and utimes
       functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
       file attributes. For the file-access time, these functions
       modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
       MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
       has no effect.

       For compatibility, the old behavior of stat, fstat, utime,
       and utimes remains the default, regardless of the kind of
       device.

       The new behavior must be explicitly enabled by defining
       the DECC$EFS_FILE_TIMESTAMPS logical name to ENABLE before
       invoking the application. Setting this logical does not
       affect the behavior of stat, fstat, utime, and utimes for
       files on an ODS-2 device.

478.4  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error other than a privilege
                       violation; errno is set to indicate the error.
    -2                 Indicates a privilege violation.

479  –  statvfs

    Gets information about a device containing the specified file.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <statvfs.h>

      int statvfs  (const char *restrict path, struct statvfs
                   *restrict buffer);

479.1  –  Arguments

 path

    Any file on a mounted device.

 buffer

    Pointer to a statvfs structure to hold the returned information.

479.2  –  Description

    The statvfs function returns descriptive information about the
    device containing the specified file. Read, write, or execute
    permission of the specified file is not required. The returned
    information is in the format of a statvfs structure, which is
    defined in the <statvfs.h> header file and contains the following
    members:

       unsigned long f_bsize - Preferred block size.

       unsigned long f_frsize - Fundamental block size.

       fsblkcnt_t f_blocks - Total number of blocks in units of f_
       frsize.

       fsblkcnt_t f_bfree - Total number of free blocks. If f_bfree
       would assume a meaningless value due to the misreporting of
       free block count by $GETDVI for a DFS disk, then f_bfree is
       set to the maximum block count.

       fsblkcnt_t f_bavail - Number of free blocks available. Set to
       the unused portion of the caller's disk quota.

       fsfilcnt_t f_files - Total number of file serial numbers (for
       example, inodes).

       fsfilcnt_t f_ffree - Total number of free file serial
       numbers. For OpenVMS systems, this value is calculated as
       freeblocks/clustersize.

       fsfilcnt_t f_favail - Number of file serial numbers available
       to a non-privileged process (0 for OpenVMS systems).

       unsigned long f_fsid - File system identifier. This identifier
       is based on the allocation-class device name. This gives a
       unique value based on device, as long as the device is locally
       mounted.

       unsigned long f_flag - Bit mask representing one or more of
       the following flags:

          ST_RONLY - The volume is read-only.
          ST_NOSUID - The volume has protected subsystems enabled.

       unsigned long f_namemax - Maximum length of a filename.
       char f_basetype[64] - Device-type name.
       char f_fstr[64] - Logical volume name.
       char __reserved[64] - Media type name.

    Upon successful completion, statvfs returns 0 (zero). Otherwise,
    it returns -1 and sets errno to indicate the error.

    See also fstatvfs.

479.3  –  Return Value

    0                  Successful completion.
    -1                 Indicates an error. errno is set to one of the
                       following:

                       o  EACCES - Search permission is denied for a
                          component of the path prefix.

                       o  EIO - An I/O error occurred while reading
                          the device.

                       o  EINTR - A signal was intercepted during
                          execution of the function.

                       o  EOVERFLOW - One of the values to be
                          returned cannot be represented correctly
                          in the structure pointed to by buffer.

                       o  ENAMETOOLONG - The length of a component
                          of the path parameter exceeds NAME_MAX, or
                          the length of the path parameter exceeds
                          PATH_MAX.

                       o  ENOENT - A component of path does not
                          name an existing file, or path is an empty
                          string.

                       o  ENOTDIR - A component of the path prefix of
                          the path parameter is not a directory.

480  –  strcasecmp

    Does a case-insensitive comparison of two 7-bit ASCII strings.

    Format

      #include  <strings.h>

      int strcasecmp  (const char *s1, const char *s2);

480.1  –  Arguments

 s1

    The first of two strings to compare.

 s2

    The second of two strings to compare.

480.2  –  Description

    The strcasecmp function is case-insensitive. The returned
    lexicographic difference reflects a conversion to lowercase.

    The strcasecmp function works for 7-bit ASCII compares only. Do
    not use this function for internationalized applications.

480.3  –  Return Value

    n                  An integer value greater than, equal to, or
                       less than 0 (zero), depending on whether the
                       s1 string is greater than, equal to, or less
                       than the s2 string.

481  –  strcat

    Concatenates str_2, including the terminating null character, to
    the end of str_1.

    Format

      #include  <string.h>

      char *strcat  (char *str_1, const char *str_2);

481.1  –  Function Variants

    The strcat function has variants named _strcat32 and _strcat64
    for use with 32-bit and 64-bit pointer sizes, respectively.

481.2  –  Arguments

 str_1, str_2

    Pointers to null-terminated character strings.

481.3  –  Description

    See strncat.

481.4  –  Return Value

    x                  The address of the first argument, str_1,
                       which is assumed to be large enough to hold
                       the concatenated result.

481.5  –  Example

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

        /* This program concatenates two strings using the strcat       */
        /* function, and then manually compares the result of strcat    */
        /* to the expected result.                                      */

        #define S1LENGTH 10
        #define S2LENGTH 8

        main()
        {
            static char s1buf[S1LENGTH + S2LENGTH] = "abcmnexyz";
            static char s2buf[] = " orthis";
            static char test1[] = "abcmnexyz orthis";

            int i;
            char *status;

            /* Take static buffer s1buf, concatenate static buffer      */
            /* s2buf to it, and compare the answer in s1buf with the    */
            /* static answer in test1.                                  */

            status = strcat(s1buf, s2buf);
            for (i = 0; i <= S1LENGTH + S2LENGTH - 2; i++) {
                /* Check for correct returned string.   */

                if (test1[i] != s1buf[i])
                    printf("error in strcat");
            }
        }

482  –  strchr

    Returns the address of the first occurrence of a given character
    in a null-terminated string.

    Format

      #include  <string.h>

      char *strchr  (const char *str, int character);

482.1  –  Function Variants

    The strchr function has variants named _strchr32 and _strchr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

482.2  –  Arguments

 str

    A pointer to a null-terminated character string.

 character

    An object of type int.

482.3  –  Description

    This function returns the address of the first occurrence of a
    given character in a null-terminated string. The terminating null
    character is considered to be part of the string.

    Compare with strrchr, which returns the address of the last
    occurrence of a given character in a null-terminated string.

482.4  –  Return Values

    x                  The address of the first occurrence of the
                       specified character.
    NULL               Indicates that the character does not occur in
                       the string.

482.5  –  Example

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

        main()
        {

            static char s1buf[] = "abcdefghijkl lkjihgfedcba";

            int i;

            char *status;

        /*  This program checks the strchr function by incrementally   */
        /*  going through a string that ascends to the middle and then */
        /*  descends towards the end.                                  */

            for (i = 0; s1buf[i] != '\0' && s1buf[i] != ' '; i++) {
                status = strchr(s1buf, s1buf[i]);

        /* Check for pointer to leftmost character - test 1.           */

                if (status != &s1buf[i])
                    printf("error in strchr");
            }
        }

483  –  strcmp

    Compares two ASCII character strings and returns a negative,
    0, or positive integer, indicating that the ASCII values of the
    individual characters in the first string are less than, equal
    to, or greater than the values in the second string.

    Format

      #include  <string.h>

      int strcmp  (const char *str_1, const char *str_2);

483.1  –  Arguments

 str_1, str_2

    Pointers to character strings.

483.2  –  Description

    The strings are compared until a null character is encountered or
    until the strings differ.

483.3  –  Return Values

    < 0                Indicates that str_1 is less than str_2.
    > 0                Indicates that str_1 is greater than str_2.

484  –  strcoll

    Compares two strings and returns an integer that indicates if
    the strings differ and how they differ. The function uses the
    collating information in the LC_COLLATE category of the current
    locale to determine how the comparison is performed.

    Format

      #include  <string.h>

      int strcoll  (const char *s1, const char *s2);

484.1  –  Arguments

 s1, s2

    Pointers to character strings.

484.2  –  Description

    The strcoll function, unlike strcmp, compares two strings in a
    locale-dependent manner. Because no value is reserved for error
    indication, the application must check for one by setting errno
    to 0 before the function call and testing it after the call.

    See also strxfrm.

484.3  –  Return Values

    < 0                Indicates that s1 is less than s2.
    > 0                Indicates that s1 is greater than s2.

485  –  strcpy

    Copies all of source, including the terminating null character,
    into dest.

    Format

      #include  <string.h>

      char *strcpy  (char *dest, const char *source);

485.1  –  Function Variants

    The strcpy function has variants named _strcpy32 and _strcpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

485.2  –  Arguments

 dest

    Pointer to the destination character string.

 source

    Pointer to the source character string.

485.3  –  Description

    The strcpy function copies source into dest, and stops after
    copying source's null character.

    The behavior of this function is undefined if the area pointed to
    by dest overlaps the area pointed to by source.

485.4  –  Return Value

    x                  The address of dest.

486  –  strcspn

    Returns the length of the prefix of a string that consists
    entirely of characters not in a specified set of characters.

    Format

      #include  <string.h>

      size_t strcspn  (const char *str, const char *charset);

486.1  –  Arguments

 str

    A pointer to a character string. If this character string is a
    null string, 0 is returned.

 charset

    A pointer to a character string containing the set of characters.

486.2  –  Description

    The strcspn function scans the characters in the string, stops
    when it encounters a character found in charset, and returns the
    length of the string's initial segment formed by characters not
    found in charset.

    If none of the characters match in the character strings pointed
    to by str and charset, strcspn returns the length of string.

486.3  –  Return Value

    x                  The length of the segment.

487  –  strdup

    Duplicates the specified string.

    Format

      #include  <string.h>

      char *strdup  (const char *s1);

487.1  –  Function Variants

    The strdup function has variants named _strdup32 and _strdup64
    for use with 32-bit and 64-bit pointer sizes, respectively.

487.2  –  Argument

 s1

    The string to be duplicated.

487.3  –  Description

    The strdup function returns a pointer to a string that is an
    exact duplicate of the string pointed to by s1. The malloc
    function is used to allocate space for the new string. The strdup
    function is provided for compatibility with existing systems.

487.4  –  Return Values

    x                  A pointer to the resulting string.
    NULL               Indicates an error.

488  –  strerror

    Maps the error number in error_code to a locale-dependent error
    message string.

    Format

      #include  <string.h>

      char *strerror  (int error_code); (ANSI C)

      char *strerror  (int error_code[, int vms_error_code]);
                      (DEC C Extension)

488.1  –  Arguments

 error_code

    An error code.

 vms_error_code

    An OpenVMS error code.

488.2  –  Description

    The strerror function uses the error number in error_code to
    retrieve the appropriate locale-dependent error message. The
    contents of the error message strings are determined by the LC_
    MESSAGES category of the program's current locale.

    When a program is not compiled with any standards-related
    feature-test macros, strerror has a second argument (vms_error_
    code), which is used in the following way:

    o  If error_code is EVMSERR and there is a second argument, then
       that second argument is used as the vaxc$errno value.

    o  If error_code is EVMSERR and there is no second argument, look
       at vaxc$errno to get the OpenVMS error condition.

    See the Example section.

    Use of the second argument is not included in the ANSI C
    definition of strerror and is, therefore, not portable.

    Because no return value is reserved to indicate an error,
    applications should set the value of errno to 0, call strerror,
    and then test the value of errno; a nonzero value indicates an
    error condition.

488.3  –  Return Value

    x                  A pointer to a buffer containing the
                       appropriate error message. Do not modify
                       this buffer in your programs. Moreover, calls
                       to the strerror function may overwrite this
                       buffer with a new message.

488.4  –  Example

        #include <stdio.h>
        #include <errno.h>
        #include <string.h>
        #include <stdlib.h>
        #include <ssdef.h>

        main()
        {
            puts(strerror(EVMSERR));
            errno = EVMSERR;
            vaxc$errno = SS$_LINKEXIT;
            puts(strerror(errno));
            puts(strerror(EVMSERR, SS$_ABORT));
            exit(1);
        }

    Running this example produces the following output:

    nontranslatable vms error code: <none>
    network partner exited
    abort

489  –  strfmon

    Converts a number of monetary values into a string. The
    conversion is controlled by a format string.

    Format

      #include  <monetary.h>

      ssize_t strfmon  (char *s, size_t maxsize, const char
                       *format, . . . );

489.1  –  Arguments

 s

    A pointer to the resultant string.

 maxsize

    The maximum number of bytes to be stored in the resultant string.

 format

    A pointer to a string that controls the format of the output
    string.

  . . .

    The monetary values of type double that are to be formatted for
    the output string. There should be as many values as there are
    conversion specifications in the format string pointed to by
    format. The function fails if there are insufficient values.
    Excess arguments are ignored.

489.2  –  Description

    The strfmon function creates a string pointed to by s, using the
    monetary values supplied. A maximum of maxsize bytes is copied to
    s.

    The format string pointed to by format consists of ordinary
    characters and conversion specifications. All ordinary characters
    are copied unchanged to the output string. A conversion
    specification defines how one of the monetary values supplied
    is formatted in the output string.

    A conversion specification consists of a percent character
    (%), followed by a number of optional characters (see Optional
    Characters in strfmon Conversion Specifications), and concluding
    with a conversion specifier (see strfmon Conversion Specifiers).

    If any of the optional characters listed in Optional Characters
    in strfmon Conversion Specifications is included in a conversion
    specification, they must appear in the order shown.

    Table REF-5 Optional Characters in strfmon Conversion
                Specifications

    Character     Meaning

                  left precision is specified. The default numeric
                  fill character is the space character. The fill
                  character must be representable as a single byte
                  in order to work with precision and width count.
                  This conversion specifier is ignored unless a
                  left precision is specified, and it does not
                  affect width filling, which always uses the space
                  character.
    ^             Do not use separator characters to format the
                  number. By default, the digits are grouped
                  according to the mon_grouping field in the LC_
                  MONETARY category of the current locale.
    +             Add the string specified by the positive_sign
                  or negative_sign fields in the current locale.
                  If p_sign_posn or n_sign_posn is set to 0, then
                  parentheses are used by default to indicate
                  negative values. Otherwise, sign strings are used
                  to indicate the sign of the value. You cannot use a
                  + and a ( in the same conversion specification.
    (             Enclose negative values within parentheses. The
                  default is taken from the p_sign_posn and n_sign_
                  posn fields in the current locale. If p_sign_
                  posn or n_sign_posn is set to 0, then parentheses
                  are used by default to indicate negative values.
                  Otherwise, sign strings are used to indicate the
                  sign of the value. You cannot use a + and ( in the
                  same conversion specification.
    !             Suppress the currency symbol. By default, the
                  currency symbol is included.
    -             Left-justify the value within the field. By
                  default, values are right-justified.
    field width   A decimal integer that specifies the minimum
                  field width in which to align the result of the
                  conversion. The default field width is the smallest
                  field that can contain the result.
    #left_        A # followed by a decimal integer specifies
    precision     the number of digits to the left of the radix
                  character. Extra positions are filled by the
                  fill character. By default the precision is the
                  smallest required for the argument. If grouping
                  is not suppressed with the ^ conversion specifier,
                  and if grouping is defined for the current locale,
                  grouping separators are inserted before any fill
                  characters are added. Grouping separators are
                  not applied to fill characters even if the fill
                  character is defined as a digit.
    .right_       A period (.) followed by a decimal integer
    precision     specifies the number of digits to the right of
                  the radix character. Extra positions are filled
                  with zeros. The amount is rounded to this number
                  of decimal places. If the right precision is zero,
                  the radix character is not included in the output.
                  By default the right precision is defined by the
                  frac_digits or int_frac_digits field of the current
                  locale.

    Table REF-6 strfmon Conversion Specifiers

    SpecifierMeaning

    i        Use the international currency symbol defined by the
             int_currency_symbol field in the current locale, unless
             the currency symbol has been suppressed.
    n        Use the local currency symbol defined by the currency_
             symbol field in the current locale, unless the currency
             symbol has been suppressed.
    %        Output a % character. The conversion specification must
             be %%; none of the optional characters is valid with
             this specifier.

489.3  –  Return Values

    x                  The number of bytes written to the string
                       pointed to by s, not including the null-
                       terminating character.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       o  EINVAL - A conversion specification is
                          syntactically incorrect.

                       o  E2BIG - Processing the complete format
                          string would produce more than maxsize
                          bytes.

489.4  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <locale.h>
        #include <monetary.h>
        #include <errno.h>

        #define MAX_BUF_SIZE 124

        main()
        {
          size_t ret;
          char buffer[MAX_BUF_SIZE];
          double amount = 102593421;

         /* Display a monetary amount using the en_US.ISO8859-1 */
         /* locale and a range of different display formats.    */

          if (setlocale(LC_ALL, "en_US.ISO8859-1") == (char *) NULL) {
              perror("setlocale");
              exit(EXIT_FAILURE);
          }
          ret = strfmon(buffer, MAX_BUF_
 SIZE, "International: %i\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %n\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %=*#10n\n", amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:     %(n\n", -1 * amount);
          printf(buffer);

          ret = strfmon(buffer, MAX_BUF_
 SIZE, "National:      %^!n\n", amount);
          printf(buffer);
        }

    Running the example program produces the following result:

    International: USD 102,593,421.00
    National:      $102,593,421.00
    National:      $**102,593,421.00
    National:      ($102,593,421.00)
    National:      102593421.00

490  –  strftime

    Uses date and time information stored in a tm structure to create
    an output string. The format of the output string is controlled
    by a format string.

    Format

      #include  <time.h>

      size_t strftime  (char *s, size_t maxsize, const char *format,
                       const struct tm *timeptr);

490.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to
    the strftime function that is equivalent to the behavior before
    OpenVMS Version 7.0.

490.2  –  Arguments

 s

    A pointer to the resultant string.

 maxsize

    The maximum number of bytes to be stored in the resultant string,
    including the null terminator.

 format

    A pointer to a string that controls the format of the output
    string.

 timeptr

    A pointer to the local time (tm) structure. The tm structure is
    defined in the <time.h> header file.

490.3  –  Description

    The strftime function uses data in the structure pointed to
    by timeptr to create the string pointed to by s. A maximum of
    maxsize bytes is copied to s.

    The format string consists of zero or more conversion
    specifications and ordinary characters. All ordinary characters
    (including the terminating null character) are copied unchanged
    into the output string. A conversion specification defines how
    data in the tm structure is formatted in the output string.

    A conversion specification consists of a percent (%) character
    followed by one or more optional characters (see Optional
    Elements of strftime Conversion Specifications), and concluding
    with a conversion specifier (see strftime Conversion Specifiers).
    If any of the optional characters listed in Optional Elements
    of strftime Conversion Specifications are specified, they must
    appear in the order shown in the table.

    The strftime function behaves as if it called tzset.

    Table REF-7 Optional Elements of strftime Conversion
                Specifications

    Element    Meaning

    -          Optional with the field width to specify that the field
               is left-justified and padded with spaces. This cannot
               be used with the 0 element.
    0          Optional with the field width to specify that the field
               is right-justified and padded with zeros. This cannot
               be used with the - element.
    field      A decimal integer that specifies the maximum field
    width      width
    .precision A decimal integer that specifies the precision of data
               in a field.

               For the d, H, I, j, m, M, o, S, U, w, W, y, and Y
               conversion specifiers, the precision specifier is the
               minimum number of digits to appear in the field. If
               the conversion specification has fewer digits than that
               specified by the precision, leading zeros are added.

               For the a, A, b, B, c, D, E, h, n, N, p, r, t, T,
               x, X, Z, and % conversion specifiers, the precision
               specifier is the maximum number of characters to appear
               in the field. If the conversion specification has
               more characters than that specified by the precision,
               characters are truncated on the right.

               The default precision for the d, H, I, m, M, o, S, U,
               w, W, y and Y conversion specifiers is 2; the default
               precision for the j conversion specifier is 3.

    Note that the list of conversion specifications in Optional
    Elements of strftime Conversion Specifications are extensions
    to the XPG4 specification.

    strftime Conversion Specifiers lists the conversion specifiers.
    The strftime function uses fields in the LC_TIME category of
    the program's current locale to provide a value. For example, if
    %B is specified, the function accesses the mon field in LC_TIME
    to find the full month name for the month specified in the tm
    structure. The result of using invalid conversion specifiers is
    undefined.

    Table REF-8 strftime Conversion Specifiers

    Specifier  Replaced by

    a          The locale's abbreviated weekday name
    A          The locale's full weekday name
    b          The locale's abbreviated month name
    B          The locale's full month name
    c          The locale's appropriate date and time representation
    C          The century number (the year divided by 100 and
               truncated to an integer) as a decimal number (00 -
               99)
    d          The day of the month as a decimal number (01 - 31)
    D          Same as %m/%d/%y
    e          The day of the month as a decimal number (1 - 31) in a
               2-digit field with the leading space character fill
    Ec         The locale's alternative date and time representation
    EC         The name of the base year (period) in the locale's
               alternative representation
    Ex         The locale's alternative date representation
    EX         The locale's alternative time representation
    Ey         The offset from the base year (%EC) in the locale's
               alternative representation
    EY         The locale's full alternative year representation
    h          Same as %b
    H          The hour (24-hour clock) as a decimal number (00 - 23)
    I          The hour (12-hour clock) as a decimal number (01 - 12)
    j          The day of the year as a decimal number (001 - 366)
    m          The month as a decimal number (01 - 12)
    M          The minute as a decimal number (00 - 59)
    n          The new-line character
    Od         The day of the month using the locale's alternative
               numeric symbols
    Oe         The date of the month using the locale's alternative
               numeric symbols
    OH         The hour (24-hour clock) using the locale's alternative
               numeric symbols
    OI         The hour (12-hour clock) using the locale's alternative
               numeric symbols
    Om         The month using the locale's alternative numeric
               symbols
    OM         The minutes using the locale's alternative numeric
               symbols
    OS         The seconds using the locale's alternative numeric
               symbols
    Ou         The weekday as a number in the locale's alternative
               representation (Monday=1)
    OU         The week number of the year (Sunday as the first day
               of the week) using the locale's alternative numeric
               symbols
    OV         The week number of the year (Monday as the first day
               of the week) as a decimal number (01 - 53) using the
               locale's alternative numeric symbols. If the week
               containing January 1 has four or more days in the
               new year, it is considered as week 1. Otherwise, it
               is considered as week 53 of the previous year, and the
               next week is week 1.
    Ow         The weekday as a number (Sunday=0) using the locale's
               alternative numeric symbols
    OW         The week number of the year (Monday as the first day
               of the week) using the locale's alternative numeric
               symbols
    Oy         The year without the century using the locale's
               alternative numeric symbols
    p          The locale's equivalent of the AM/PM designations
               associated with a 12-hour clock
    r          The time in AM/PM notation
    R          The time in 24-hour notation (%H:%M)
    S          The second as a decimal number (00 - 61)
    t          The tab character
    T          The time (%H:%M:%S)
    u          The weekday as a decimal number between 1 and 7
               (Monday=1)
    U          The week number of the year (the first Sunday as the
               first day of week 1) as a decimal number (00 - 53)
    V          The week number of the year (Monday as the first day
               of the week) as a decimal number (00 - 53). If the
               week containing January 1 has four or more days in the
               new year, it is considered as week 1. Otherwise, it
               is considered as week 53 of the previous year, and the
               next week is week 1.
    w          The weekday as a decimal number (0 [Sunday] - 6)
    W          The week number of the year (the first Monday as the
               first day of week 1) as a decimal number (00 - 53)
    x          The locale's appropriate date representation
    X          The locale's appropriate time representation
    y          The year without century as a decimal number (00 - 99)
    Y          The year with century as a decimal number
    Z          Time-zone name or abbreviation. If time-zone
               information is not available, no character is output.
    %          Literal % character.

490.4  –  Return Values

    x                  The number of characters placed into the array
                       pointed to by s, not including the terminating
                       null character.
    0                  Indicates an error occurred. The contents of
                       the array are indeterminate.

490.5  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <time.h>
        #include <locale.h>
        #include <errno.h>

        #define NUM_OF_DATES  7
        #define BUF_SIZE 256

        /* This program formats a number of different dates, once */
        /* using the C locale and then using the fr_FR.ISO8859-1  */
        /* locale. Date and time formatting is done using strftime(). */

        main()
        {
            int count,
                i;
            char buffer[BUF_SIZE];
            struct tm *tm_ptr;
            time_t time_list[NUM_OF_DATES] =
            {500, 68200000, 694223999, 694224000,
             704900000, 705000000, 705900000};

            /* Display dates using the C locale */
            printf("\nUsing the C locale:\n\n");

            setlocale(LC_ALL, "C");

            for (i = 0; i < NUM_OF_DATES; i++) {
                /* Convert to a tm structure */
                tm_ptr = localtime(&time_list[i]);

                /* Format the date and time */
                count = strftime(buffer, BUF_SIZE,
                       "Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr);
                if (count == 0) {
                    perror("strftime");
                    exit(EXIT_FAILURE);
                }

                /* Print the result */
               printf(buffer);
            }

            /* Display dates using the fr_FR.ISO8859-1 locale */
            printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n");

            setlocale(LC_ALL, "fr_FR.ISO8859-1");

            for (i = 0; i < NUM_OF_DATES; i++) {
                /* Convert to a tm structure */
                tm_ptr = localtime(&time_list[i]);

                /* Format the date and time */
                count = strftime(buffer, BUF_SIZE,
                       "Date: %A %d %B %Y%nTime: %T%n%n", tm_ptr);
                if (count == 0) {
                    perror("strftime");
                    exit(EXIT_FAILURE);
                }

                /* Print the result */
                printf(buffer);
            }
        }

    Running the example program produces the following result:

    Using the C locale:

    Date: Thursday 01 January 1970
    Time: 00:08:20

    Date: Tuesday 29 February 1972
    Time: 08:26:40

    Date: Tuesday 31 December 1991
    Time: 23:59:59

    Date: Wednesday 01 January 1992
    Time: 00:00:00

    Date: Sunday 03 May 1992
    Time: 13:33:20

    Date: Monday 04 May 1992
    Time: 17:20:00

    Date: Friday 15 May 1992
    Time: 03:20:00

    Using the fr_FR.ISO8859-1 locale:

    Date: jeudi 01 janvier 1970
    Time: 00:08:20

    Date: mardi 29 février 1972
    Time: 08:26:40

    Date: mardi 31 décembre 1991
    Time: 23:59:59

    Date: mercredi 01 janvier 1992
    Time: 00:00:00

    Date: dimanche 03 mai 1992
    Time: 13:33:20

    Date: lundi 04 mai 1992
    Time: 17:20:00

    Date: vendredi 15 mai 1992
    Time: 03:20:00

491  –  strlen

    Returns the length of a string of ASCII characters. The returned
    length does not include the terminating null character (\0).

    Format

      #include  <string.h>

      size_t strlen  (const char *str);

491.1  –  Argument

 str

    A pointer to the character string.

491.2  –  Return Value

    x                  The length of the string.

492  –  strncasecmp

    Does a case-insensitive comparison between two 7-bit ASCII
    strings.

    Format

      #include  <strings.h>

      int strncasecmp  (const char *s1, const char *s2, size_t n);

492.1  –  Arguments

 s1

    The first of two strings to compare.

 s2

    The second of two strings to compare.

 n

    The maximum number of bytes in a string to compare.

492.2  –  Description

    The strncasecmp function is case-insensitive. The returned
    lexicographic difference reflects a conversion to lowercase.
    The strncasecmp function is similar to the strcasecmp function,
    but also compares size. If the size specified by n is read before
    a NULL, the comparison stops.

    The strcasecmp function works for 7-bit ASCII compares only. Do
    not use this function for internationalized applications.

492.3  –  Return Value

    n                  An integer value greater than, equal to, or
                       less than 0 (zero), depending on whether s1 is
                       greater than, equal to, or less than s2.

493  –  strncat

    Appends not more than maxchar characters from str_2 to the end of
    str_1.

    Format

      #include  <string.h>

      char *strncat  (char *str_1, const char *str_2, size_t
                     maxchar);

493.1  –  Function Variants

    The strncat function has variants named _strncat32 and _strncat64
    for use with 32-bit and 64-bit pointer sizes, respectively.

493.2  –  Arguments

 str_1, str_2

    Pointers to null-terminated character strings.

 maxchar

    The number of characters to concatenate from str_2, unless
    strncat first encounters a null terminator in str_2. If maxchar
    is 0, no characters are copied from str_2.

493.3  –  Description

    A null character is always appended to the result of the strncat
    function. If strncat reaches the specified maximum, it sets the
    next byte in str_1 to the null character.

493.4  –  Return Value

    x                  The address of the first argument, str_1,
                       which is assumed to be large enough to hold
                       the concatenated result.

494  –  strncmp

    Compares not more than maxchar characters of two ASCII character
    strings and returns a negative, 0, or positive integer,
    indicating that the ASCII values of the individual characters
    in the first string are less than, equal to, or greater than the
    values in the second string.

    Format

      #include  <string.h>

      int strncmp  (const char *str_1, const char *str_2, size_t
                   maxchar);

494.1  –  Arguments

 str_1, str_2

    Pointers to character strings.

 maxchar

    The maximum number of characters (beginning with the first) to
    search in both str_1 and str_2. If maxchar is 0, no comparison is
    performed and 0 is returned (the strings are considered equal).

494.2  –  Description

    The strncmp function compares no more than maxchar characters
    from the string pointed to by str_1 to the string pointed
    to by str_2. The strings are compared until a null character
    is encountered, the strings differ, or maxchar is reached.
    Characters that follow a difference or a null character are not
    compared.

494.3  –  Return Values

    < 0                Indicates that str_1 is less than str_2.
    > 0                Indicates that str_1 is greater than str_2.

494.4  –  Examples

    1.#include <string.h>

      #include <stdio.h>

      main()
      {
          printf( "%d\n", strncmp("abcde", "abc", 3));
      }

      When linked and executed, this example returns 0, because the
      first 3 characters of the 2 strings are equal:

        $ run tmp
        0

    2.#include <string.h>

      #include <stdio.h>

          main()
          {
              printf( "%d\n", strncmp("abcde", "abc", 4));
          }

      When linked and executed, this example returns a value greater
      than 0 because the first 4 characters of the 2 strings are not
      equal (The "d" in the first string is not equal to the null
      character in the second):

        $ run tmp
                100

495  –  strncpy

    Copies not more than maxchar characters from source into dest.

    Format

      #include  <string.h>

      char *strncpy  (char *dest, const char *source, size_t
                     maxchar);

495.1  –  Function Variants

    The strncpy function has variants named _strncpy32 and _strncpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

495.2  –  Arguments

 dest

    Pointer to the destination character string.

 source

    Pointer to the source character string.

 maxchar

    The maximum number of characters to copy from source to dest up
    to but not including the null terminator of source.

495.3  –  Description

    The strncpy function copies no more than maxchar characters from
    source to dest, up to but not including the null terminator of
    source. If source contains less than maxchar characters, dest
    is padded with null characters. If source contains greater than
    or equal to maxchar characters, as many characters as possible
    are copied to dest. Be aware that the dest argument might not be
    terminated by a null character after a call to strncpy.

495.4  –  Return Value

    x                  The address of dest.

496  –  strnlen

    Returns the number of bytes in a string.

    Format

      #include  <string.h>

      size_t strnlen  (const char *s, size_t n);

496.1  –  Arguments

 s

    Pointer to the string.

 n

    The maximum number of characters to examine.

496.2  –  Description

    The strnlen function returns the number of bytes in the string
    pointed to by s. The string length value does not include the
    terminating null character. The strnlen function counts bytes
    until the first null byte or until n bytes have been examined.

496.3  –  Return Value

    n                  The length of the string.

497  –  strpbrk

    Searches a string for the occurrence of one of a specified set of
    characters.

    Format

      #include  <string.h>

      char *strpbrk  (const char *str, const char *charset);

497.1  –  Function Variants

    The strpbrk function has variants named _strpbrk32 and _strpbrk64
    for use with 32-bit and 64-bit pointer sizes, respectively.

497.2  –  Arguments

 str

    A pointer to a character string. If this character string is a
    null string, 0 is returned.

 charset

    A pointer to a character string containing the set of characters
    for which the function will search.

497.3  –  Description

    The strpbrk function scans the characters in the string, stops
    when it encounters a character found in charset, and returns the
    address of the first character in the string that appears in the
    character set.

497.4  –  Return Values

    x                  The address of the first character in the
                       string that is in the set.
    NULL               Indicates that no character is in the set.

498  –  strptime

    Converts a character string into date and time values that are
    stored in a tm structure. Conversion is controlled by a format
    string.

    Format

      #include  <time.h>

      char *strptime  (const char *buf, const char *format, struct tm
                      *timeptr);

498.1  –  Function Variants

    The strptime function has variants named _strptime32 and _
    strptime64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

498.2  –  Arguments

 buf

    A pointer to the character string to convert.

 format

    A pointer to the string that defines how the input string is
    converted.

 timeptr

    A pointer to the local time structure. The tm structure is
    defined in the <time.h> header file.

498.3  –  Description

    The strptime function converts the string pointed to by buf into
    values that are stored in the structure pointed to by timeptr.
    The string pointed to by format defines how the conversion is
    performed.

    The strptime function modifies only those fields in the tm
    structure that have corresponding conversion specifications
    in the format. In particular, strptime never sets the tm_isdst
    member of the tm structure.

    The format string consists of zero or more directives. A
    directive is composed of one of the following:

    o  One or more white-space characters (as defined by the isspace
       function). This directive causes the function to read input up
       to the first character that is not a white-space character.

    o  Any character other than the percent character (%) or a white-
       space character. This directive causes the function to read
       the next character. The character read must be the same as the
       character that comprises the directive. If the character is
       different, the function fails.

    o  A conversion specification. A conversion specification defines
       how characters in the input string are interpreted as values
       that are then stored in the tm structure. A conversion
       specification consists of a percent (%) character followed
       by a conversion specifier. strptime Conversion Specifications
       lists the valid conversion specifications.

    The strptime function uses fields in the LC_TIME category of the
    program's current locale to provide a value.

                                   NOTE

       To be compliant with X/Open CAE Specification System
       Interfaces and Headers Issue 5 (commonly known as XPG5), the
       strptime function processes the "%y" directive differently
       than in previous versions of the C RTL.

       With Version 6.4 and higher of the C compiler, for a two-
       digit year within the century if no century is specified,
       "%y" directive values range from:

       o  69 to 99 refer to years in the twentieth century (1969 to
          1999 inclusive)

       o  00 to 68 refer to years in the twenty-first century (2000
          to 2068 inclusive)

       In previous (XPG4-compliant) versions of the C RTL,
       strptime interpreted a two-digit year with no century
       specified as a year within the twentieth century.

       The XPG5-compliant strptime is now the default version in
       the C RTL.

       To obtain the old, XPG4-compliant strptime function
       behavior, specify one of the following:

       o  Define the DECC$XPG4_STRPTIME logical name as follows:

          $ DEFINE DECC$XPG4_STRPTIME ENABLE

          or:

       o  Call the XPG4 strptime directly as the function
          decc$strptime_xpg4.

       To return to using the XPG5 strptime version, DEASSIGN the
       DECC$XPG4_STRPTIME logical name:

       $ DEASSIGN DECC$XPG4_STRPTIME

    Table REF-9 strptime Conversion Specifications

    SpecificaReplaced by

    %a       The weekday name. This is either the abbreviated or the
             full name.
    %A       Same as %a.
    %b       The month name. This is either the abbreviated or the
             full name.
    %B       Same as %b.
    %c       The date and time using the locale's date format.
    %Ec      The locale's alternative date and time representation.
    %C       The century number (the year divided by 100 and
             truncated to an integer) as a decimal number (00 - 99).
             Leading zeros are permitted.
    %EC      The name of the base year (period) in the locale's
             alternative representation.
    %d       The day of the month as a decimal number (01 - 31).
             Leading zeros are permitted.
    %Od      The day of the month using the locale's alternative
             numeric symbols.
    %D       Same as %m/%d/%y.
    %e       Same as %d.
    %Oe      The date of the month using the locale's alternative
             numeric symbols.
    %h       Same as %b.
    %H       The hour (24-hour clock) as a decimal number (00 - 23).
             Leading zeros are permitted.
    %OH      The hour (24-hour clock) using the locale's alternative
             numeric symbols.
    %I       The hour (12-hour clock) as a decimal number (01 - 12).
             Leading zeros are permitted.
    %OI      The hour (12-hour clock) using the locale's alternative
             numeric symbols.
    %j       The day of the year as a decimal number (001 - 366).
    %m       The month as a decimal number (01 - 12). Leading zeros
             are permitted.
    %Om      The month using the locale's alternative numeric
             symbols.
    %M       The minute as a decimal number (00 - 59). Leading zeros
             are permitted.
    %OM      The minutes using the locale's alternative numeric
             symbols.
    %n       Any white-space character.
    %p       The locale's equivalent of the AM/PM designations
             associated with a 12-hour clock.
    %r       The time in AM/PM notation (%I:%M:%S %p).
    %R       The time in 24-hour notation (%H:%M).
    %S       The second as a decimal number (00 - 61). Leading zeros
             are permitted.
    %OS      The seconds using the locale's alternative numeric
             symbols.
    %t       Any white-space character.
    %T       The time (%H:%M:%S).
    %U       The week number of the year (the first Sunday as the
             first day of week 1) as a decimal number (00 - 53).
             Leading zeros are permitted.
    %OU      The week number of the year (Sunday as the first day
             of the week) using the locale's alternative numeric
             symbols.
    %w       The weekday as a decimal number (0 [Sunday] - 6).
             Leading zeros are permitted.
    %Ow      The weekday as a number (Sunday=0) using the locale's
             alternative numeric symbols.
    %W       The week number of the year (the first Monday as the
             first day of week 1) as a decimal number (00 - 53).
             Leading zeros are permitted.
    %OW      The week number of the year (Monday as the first day
             of the week) using the locale's alternative numeric
             symbols.
    %x       The locale's appropriate date representation.
    %Ex      The locale's alternative date representation.
    %EX      The locale's alternative time representation.
    %X       The locale's appropriate time representation.
    %y       The year without century as a decimal number (00 - 99).
    %Ey      The offset from the base year (%EC) in the locale's
             alternative representation.
    %Oy      The year without the century using the locale's
             alternative numeric symbols.
    %Y       The year with century as a decimal number.
    %EY      The locale's full alternative year representation.
    %%       Literal % character.

498.4  –  Return Values

    x                  A pointer to the character following the last
                       character parsed.
    NULL               Indicates that an error occurred. The contents
                       of the tm structure are undefined.

498.5  –  Example

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

        #define NUM_OF_DATES  7
        #define BUF_SIZE 256

        /* This program takes a number of date and time strings and     */
        /* converts them into tm structs using strptime().  These tm    */
        /* structs are then passed to strftime() which will reverse the */
        /* process.  The resulting strings are then compared with the   */
        /* originals and if a difference is found then an error is      */
        /* displayed.                                                   */

        main()
        {
        int count,
            i;
        char buffer[BUF_SIZE];
        char *ret_val;
        struct tm time_struct;
        char dates[NUM_OF_DATES][BUF_SIZE] =
        {
            "Thursday 01 January 1970 00:08:20",
            "Tuesday 29 February 1972 08:26:40",
            "Tuesday 31 December 1991 23:59:59",
            "Wednesday 01 January 1992 00:00:00",
            "Sunday 03 May 1992 13:33:20",
            "Monday 04 May 1992 17:20:00",
            "Friday 15 May 1992 03:20:00"};

        for (i = 0; i < NUM_OF_DATES; i++) {
            /* Convert to a tm structure */
         ret_val = strptime(dates[i], "%A %d %B %Y %T", &time_struct);

            /* Check the return value */
            if (ret_val == (char *) NULL) {
                perror("strptime");
                exit(EXIT_FAILURE);
            }

            /* Convert the time structure back to a formatted string */
        count = strftime(buffer, BUF_SIZE, "%A %d %B %Y %T",&time_struct);

            /* Check the return value */
            if (count == 0) {
                perror("strftime");
                exit(EXIT_FAILURE);
            }

            /* Check the result */
            if (strcmp(buffer, dates[i]) != 0) {
            printf("Error: Converted string differs from the original\n");
            }
            else {
                printf("Successfully converted <%s>\n", dates[i]);
            }
         }
        }

    Running the example program produces the following result:

    Successfully converted <Thursday 01 January 1970 00:08:20>
    Successfully converted <Tuesday 29 February 1972 08:26:40>
    Successfully converted <Tuesday 31 December 1991 23:59:59>
    Successfully converted <Wednesday 01 January 1992 00:00:00>
    Successfully converted <Sunday 03 May 1992 13:33:20>
    Successfully converted <Monday 04 May 1992 17:20:00>
    Successfully converted <Friday 15 May 1992 03:20:00>

499  –  strrchr

    Returns the address of the last occurrence of a given character
    in a null-terminated string.

    Format

      #include  <string.h>

      char *strrchr  (const char *str, int character);

499.1  –  Function Variants

    The strrchr function has variants named _strrchr32 and _strrchr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

499.2  –  Arguments

 str

    A pointer to a null-terminated character string.

 character

    An object of type int.

499.3  –  Description

    This function returns the address of the last occurrence of a
    given character in a null-terminated string. The terminating null
    character is considered to be part of the string.

    Compare with strchr, which returns the address of the first
    occurrence of a given character in a null-terminated string.

499.4  –  Return Values

    x                  The address of the last occurrence of the
                       specified character.
    NULL               Indicates that the character does not occur in
                       the string.

500  –  strsep

    Separates strings.

    Format

      #include  <string.h>

      char *strsep  (char **stringp, char *delim);

500.1  –  Function Variants

    The strsep function has variants named _strsep32 and _strsep64
    for use with 32-bit and 64-bit pointer sizes, respectively.

500.2  –  Arguments

 stringp

    A pointer to a pointer to a character string.

 delim

    A pointer to a string containing characters to be used as
    delimiters.

500.3  –  Description

    The strsep function locates in stringp, the first occurrence of
    any character in delim (or the terminating '\0' character) and
    replaces it with a '\0'. The location of the next character after
    the delimiter character (or NULL, if the end of the string is
    reached) is stored in the stringp argument. The original value of
    the stringp argument is returned.

    You can detect an "empty" field; one caused by two adjacent
    delimiter characters, by comparing the location referenced by
    the pointer returned in the stringp argument to '\0'.

    The stringp argument is initially NULL, strsep returns NULL.

500.4  –  Return Values

    x                  The address of the string pointed to by
                       stringp.
    NULL               Indicates that stringp is NULL.

500.5  –  Example

      The following example uses strsep to parse a string, containing
      token delimited by white space, into an argument vector:

        char **ap, **argv[10], *inputstring;

        for (ap = argv; (*ap = strsep(&inputstring, " \t")) != NULL;)
             if (**ap != '\0')
                 ++ap;

501  –  strspn

    Returns the length of the prefix of a string that consists
    entirely of characters from a set of characters.

    Format

      #include  <string.h>

      size_t strspn  (const char *str, const char *charset);

501.1  –  Arguments

 str

    A pointer to a character string. If this string is a null string,
    0 is returned.

 charset

    A pointer to a character string containing the characters for
    which the function will search.

501.2  –  Description

    The strspn function scans the characters in the string, stops
    when it encounters a character not found in charset, and returns
    the length of the string's initial segment formed by characters
    found in charset.

501.3  –  Return Value

    x                  The length of the segment.

502  –  strstr

    Locates the first occurrence in the string pointed to by s1 of
    the sequence of characters in the string pointed to by s2.

    Format

      #include  <string.h>

      char *strstr  (const char *s1, const char *s2);

502.1  –  Function Variants

    The strstr function has variants named _strstr32 and _strstr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

502.2  –  Arguments

 s1, s2

    Pointers to character strings.

502.3  –  Return Values

    Pointer            A pointer to the located string.
    NULL               Indicates that the string was not found.

502.4  –  Example

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

        main()
        {
            static char lookin[]="that this is a test was at the end";

            putchar('\n');
            printf("String: %s\n", &lookin[0] );
            putchar('\n');
            printf("Addr: %s\n", &lookin[0] );
            printf("this: %s\n", strstr( &lookin[0] ,"this") );
            printf("that: %s\n", strstr( &lookin[0] , "that" ) );
            printf("NULL: %s\n", strstr( &lookin[0], "" ) );
            printf("was: %s\n", strstr( &lookin[0], "was" ) );
            printf("at: %s\n", strstr( &lookin[0], "at" ) );
            printf("the end: %s\n", strstr( &lookin[0], "the end") );
            putchar('\n');

            exit(0);
        }

    This example produces the following results:

    $ RUN STRSTR_EXAMPLE
    String: that this is a test was at the end
    Addr: that this is a test was at the end
    this: this is a test was at the end
    that: that this is a test was at the end
    NULL: that this is a test was at the end
    was: was at the end
    at: at this is a test was at the end
    the end: the end
    $

503  –  strtod

    Converts a given string to a double-precision number.

    Format

      #include  <stdlib.h>

      double strtod  (const char *nptr, char **endptr);

503.1  –  Function Variants

    The strtod function has variants named _strtod32 and _strtod64
    for use with 32-bit and 64-bit pointer sizes, respectively.

503.2  –  Arguments

 nptr

    A pointer to the character string to be converted to a double-
    precision number.

 endptr

    The address of an object where the function can store the address
    of the first unrecognized character that terminates the scan. If
    endptr is a NULL pointer, the address of the first unrecognized
    character is not retained.

503.3  –  Description

    The strtod function recognizes an optional sequence of white-
    space characters (as defined by isspace), then an optional plus
    or minus sign, then a sequence of digits optionally containing a
    radix character, then an optional letter (e or E) followed by an
    optionally signed integer. The first unrecognized character ends
    the conversion.

    The string is interpreted by the same rules used to interpret
    floating constants.

    The radix character is defined the program's current locale
    (category LC_NUMERIC).

    This function returns the converted value. For strtod, overflows
    are accounted for in the following manner:

    o  If the correct value causes an overflow, HUGE_VAL (with a plus
       or minus sign according to the sign of the value) is returned
       and errno is set to ERANGE.

    o  If the correct value causes an underflow, 0 is returned and
       errno is set to ERANGE.

    If the string starts with an unrecognized character, then the
    conversion is not performed, *endptr is set to nptr, a 0 value is
    returned, and errno is set to EINVAL.)

503.4  –  Return Values

    x                  The converted string.
    0                  Indicates the conversion could not be
                       performed. errno is set to one of the
                       following:

                       o  EINVAL - No conversion could be performed.

                       o  ERANGE - The value would cause an
                          underflow.

                       o  ENOMEM - Not enough memory available for
                          internal conversion buffer.

    HUGE_VAL           Overflow occurred; errno is set to ERANGE.

504  –  strtok

    Split strings into tokens.

    Format

      #include  <string.h>

      char *strtok  (char *s1, const char *s2);

      char *strtok_r  (char *s, const char *sep, char **lasts);

504.1  –  Function Variants

    The strtok function has variants named _strtok32 and _strtok64
    for use with 32-bit and 64-bit pointer sizes, respectively.
    Likewise, the strtok_r function has variants named _strtok_r32
    and _strtok_r64.

504.2  –  Arguments

 s1

    On the first call, a pointer to a string containing zero or more
    text tokens. On all subsequent calls for that string, a NULL
    pointer.

 s2

    A pointer to a separator string consisting of one or more
    characters. The separator string may differ from call to call.

 s

    A null-terminated string that is a sequence of zero or more text
    tokens separated by spans of one or more characters from the
    separator string sep.

 sep

    A null-terminated string of separator characters. This separator
    string can be different from call to call.

 lasts

    A pointer that points to a user-provided pointer to stored
    information needed for strtok_r to continue scanning the same
    string.

504.3  –  Description

    The strtok function locates text tokens in a given string. The
    text tokens are delimited by one or more characters from a
    separator string that you specify. The function keeps track of
    its position in the string between calls and, as successive calls
    are made, the function works through the string, identifying the
    text token following the one identified by the previous call.

    A token in s1 starts at the first character that is not a
    character in the separator string s2 and ends either at the end
    of the string or at (but not including) a separator character.

    The first call to the strtok function returns a pointer to the
    first character in the first token and writes a null character
    into s1 immediately following the returned token. Each subsequent
    call (with the value of the first argument remaining NULL)
    returns a pointer to a subsequent token in the string originally
    pointed to by s1. When no tokens remain in the string, the strtok
    function returns a NULL pointer. (This can occur on the first
    call to strtok if the string is empty or contains only separator
    characters.)

    Since strtok inserts null characters into s1 to delimit tokens,
    s1 cannot be a const object.

    The strtok_r function is the reentrant version of strtok. The
    function strtok_r considers the null-terminated string s as a
    sequence of zero or more text tokens separated by spans of one or
    more characters from the separator string sep. The lasts argument
    points to a user-provided pointer to stored information needed
    for strtok_r to continue scanning the same string.

    In the first call to strtok_r, s points to a null-terminated
    string, sep points to a null-terminated string of separator
    characters, and the value pointed to by lasts is ignored. The
    strtok_r function returns a pointer to the first character of
    the first token, writes a null character into s immediately
    following the returned token, and updates the pointer to which
    lasts points.

    In subsequent calls, s is a NULL pointer and lasts is unchanged
    from the previous call so that subsequent calls move through the
    string s, returning successive tokens until no tokens remain. The
    separator string sep can be different from call to call. When no
    token remains in s, a NULL pointer is returned.

504.4  –  Return Values

    x                  A pointer to the first character of the parsed
                       token in the string.
    NULL               Indicates that there are no tokens remaining
                       in the string.

504.5  –  Examples

    1.#include <stdio.h>

      #include <string.h>

      main()
      {
          static char str[] = "...ab..cd,,ef.hi";

          printf("|%s|\n", strtok(str, "."));
          printf("|%s|\n", strtok(NULL, ","));
          printf("|%s|\n", strtok(NULL, ",."));
          printf("|%s|\n", strtok(NULL, ",."));
      }

      Running this example program produces the following results:

        $ RUN STRTOK_EXAMPLE1
        |ab|
        |.cd|
        |ef|
        |hi|
        $

    2.#include <stdio.h>

      #include <string.h>

      main()
      {
         char *ptr,
              string[30];

         /* The first character not in the string "-" is "A".  The   */
         /* token ends at "C.                                        */

          strcpy(string, "ABC");
          ptr = strtok(string, "-");
          printf("|%s|\n", ptr);

          /* Returns NULL because no characters not in separator      */
          /* string "-" were found (i.e.  only separator characters   */
          /* were found)                                              */

          strcpy(string, "-");
          ptr = strtok(string, "-");
          if (ptr == NULL)
              printf("ptr is NULL\n");

      }

      Running this example program produces the following results:

        $ RUN STRTOK_EXAMPLE2
        |abc|
        ptr is NULL
        $

505  –  strtol

    Converts strings of ASCII characters to the appropriate numeric
    values.

    Format

      #include  <stdlib.h>

      long int strtol  (const char *nptr, char **endptr, int base);

505.1  –  Function Variants

    The strtol function has variants named _strtol32 and _strtol64
    for use with 32-bit and 64-bit pointer sizes, respectively.

505.2  –  Arguments

 nptr

    A pointer to the character string to be converted to a long.

 endptr

    The address of an object where the function can store 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.

505.3  –  Description

    The strtol function recognizes strings in various formats,
    depending on the value of the base. This function ignores
    any leading white-space characters (as defined by isspace in
    <ctype.h>) in the given string. It recognizes an optional plus
    or minus sign, then a sequence of digits or letters that may
    represent an integer constant according to the value of the base.
    The first unrecognized character ends the conversion.

    Leading zeros after the optional sign are ignored, and 0x or 0X
    is ignored if the base is 16.

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

    Truncation from long to int can take place after assignment or
    by an explicit cast (arithmetic exceptions not withstanding).
    The function call atol (str) is equivalent to strtol (str,
    (char**)NULL, 10).

505.4  –  Return Values

    x                  The converted value.
    LONG_MAX or LONG_  Indicates that the converted value would cause
    MIN                an overflow.
    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.

506  –  strtoq,strtoll

    Convert strings of ASCII characters to the appropriate numeric
    values. strtoll is a synonym for strtoq.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      __int64 strtoq  (const char *nptr, char **endptr, int base);

      __int64 strtoll  (const char *nptr, char **endptr, int base);

506.1  –  Function Variants

    These functions have variants named _strtoq32, _strtoll32 and
    _strtoq64, _strtoll64 for use with 32-bit and 64-bit pointer
    sizes, respectively.

506.2  –  Arguments

 nptr

    A pointer to the character string to be converted to an __int64.

 endptr

    The address of an object where the function can store 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.

506.3  –  Description

    The strtoq and strtoll functions recognize strings in various
    formats, depending on the value of the base. Any leading white-
    space characters (as defined by isspace in <ctype.h>) in the
    given string are ignored. The functions recognize an optional
    plus or minus sign, then a sequence of digits or letters that may
    represent an integer constant according to the value of the base.
    The first unrecognized character ends the conversion.

    Leading zeros after the optional sign are ignored, and 0x or 0X
    is ignored if the base is 16.

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

    The function call atoq (str) is equivalent to strtoq (str,
    (char**)NULL, 10).

506.4  –  Return Values

    x                  The converted value.
    __INT64_MAX or     Indicates that the converted value would cause
    __INT64_MIN        an overflow.
    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.

507  –  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);

507.1  –  Function Variants

    The strtoul function has variants named _strtoul32 and _strtoul64
    for use with 32-bit and 64-bit pointer sizes, respectively.

507.2  –  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.

507.3  –  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.

508  –  strtouq,strtoull

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

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdlib.h>

      unsigned __int64 strtouq  (const char *nptr, char **endptr, int base);

      unsigned __int64 strtoull  (const char *nptr, char **endptr, int base);

508.1  –  Function Variants

    These functions have variants named _strtouq32, _strtoull32 and
    _strtouq64, _strtoull64 for use with 32-bit and 64-bit pointer
    sizes, respectively.

508.2  –  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.

508.3  –  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.

509  –  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);

509.1  –  Arguments

 s1, s2

    Pointers to character strings.

 maxchar

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

509.2  –  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.

509.3  –  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.

509.4  –  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

510  –  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);

510.1  –  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.

510.2  –  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.

510.3  –  Return Values

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

511  –  swab

    Swaps bytes.

    Format

      #include  <unistd.h>

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

511.1  –  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.

511.2  –  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.

512  –  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, . . . );

512.1  –  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.

  . . .

    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.

512.2  –  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.

512.3  –  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.

513  –  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, . . . );

513.1  –  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.

  . . .

    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.

513.2  –  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.

513.3  –  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.

514  –  symlink

    Creates a symbolic link containing the specified contents.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int symlink  (const char *link_contents, const char *link_name);

514.1  –  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.

514.2  –  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.

514.3  –  Return Values

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

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

                       o  EEXIST - The link_name argument names an
                          existing file or symbolic link.

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

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

                       o  Any errno value from creat, fsync, lstat,
                          or write.

515  –  sysconf

    Gets configurable system variables.

    Format

      #include  <unistd.h>

      long int sysconf  (int name);

515.1  –  Argument

 name

    Specifies the system variable to be queried.

515.2  –  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:

    o  The symbolic constants defined in the <unistd.h> header file.

    o  The system variables are defined in the <limits.h> and
       <unistd.h> header files.

    sysconf Argument and Return Values 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

                      Symbolic
    System Variable   Constant for
    Returned          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_     The maximum number of
                      MAX            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_   The maximum number of
                      MAX            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_    The number of streams that one
                      MAX            process can have open at one
                                     time.
    TZNAME_MAX        _SC_TZNAME_    The maximum number of bytes
                      MAX            supported for the name of a time
                                     zone (not the length of the TZ
                                     environmental variable).
    _POSIX_JOB_       _SC_JOB_       This variable has a value of
    CONTROL           CONTROL        1 if the system supports job
                                     control; otherwise, -1 is
                                     returned.
    _POSIX_SAVED_IDS  _SC_SAVED_     This variable has a value of 1
                      IDS            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_   The maximum value allowed for
                      MAX            the obase variable with the bc
                                     command.
    BC_DIM_MAX        _SC_BC_DIM_    The maximum number of elements
                      MAX            permitted in an array by the bc
                                     command.
    BC_SCALE_MAX      _SC_BC_        The maximum value allowed for
                      SCALE_MAX      the scale variable with the bc
                                     command.
    BC_STRING_MAX     _SC_BC_        The maximum length of string
                      STRING_MAX     constants accepted by the bc
                                     command.
    COLL_WEIGHTS_MAX  _SC_COLL_      The maximum number of weights
                      WEIGHTS_MAX    that can be assigned to an
                                     entry in the LC_COLLATE locale-
                                     dependent information in a
                                     locale definition file.
    EXPR_NEST_MAX     _SC_EXPR_      The maximum number of
                      NEST_MAX       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_    The maximum number of repeated
                      MAX            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_     _SC_2_CHAR_    This variable has a value of 1
    TERM              TERM           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_        _SC_2_C_       Integer value indicating the
    VERSION           VERSION        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_         Integer value indicating the
                      VERSION        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_    The variable has a value of 1 if
                      DEV            the system supports the Fortran
                                     Development Utilities Option
                                     from the ISO POSIX-2 standard;
                                     otherwise, -1 is returned.
    _POSIX2_FORT_RUN  _SC_2_FORT_    The variable has a value of
                      RUN            1 if the system supports the
                                     Fortran Runtime Utilities Option
                                     from the ISO POSIX-2 standard;
                                     otherwise, -1 is returned.
    _POSIX2_          _SC_2_         The variable has a value of
    LOCALEDEF         LOCALEDEF      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_    _SC_THREAD_    This variable has a value of 1
    ATTR_STACKSIZE    ATTR_          if the system supports the POSIX
                      STACKSIZE      threads stack size attribute;
                                     otherwise, -1 is returned.
    _POSIX_THREAD_    _SC_THREAD_    The 1003.1c implementation
    PRIORITY_         PRIORITY_      supports the realtime scheduling
    SCHEDULING        SCHEDULING     functions.
    _POSIX_THREAD_    _SC_THREAD_    TRUE if the implementation
    SAFE_FUNCTIONS    SAFE_          supports the thread-safe ANSI
                      FUNCTIONS      C functions in POSIX 1003.1c.
    PTHREAD_          _SC_THREAD_    When a thread terminates,
    DESTRUCTOR_       DESTRUCTOR_    DECthreads iterates through
    ITERATIONS        ITERATIONS     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_    The maximum number of thread-
                      KEYS_MAX       specific data keys that an
                                     application can create.
    PTHREAD_STACK_    _SC_THREAD_    The minimum allowed size of a
    MIN               STACK_MIN      stack for a new thread. Any
                                     lower value specified for the
                                     "stacksize" thread attribute is
                                     rounded up.
    UINT_MAX          _SC_THREAD_    The maximum number of threads
                      THREADS_MAX    an application is allowed to
                                     create. Since DECthreads does
                                     not enforce any fixed limit,
                                     this value is -1.

    X/Open

    _XOPEN_VERSION    _SC_XOPEN_     An integer indicating the
                      VERSION        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_     This variable has a value of
                      CRYPT          1 if the system supports the
                                     X/Open Encryption Feature Group;
                                     otherwise, -1 is returned.
    XOPEN_ENH_I18N    _SC_XOPEN_     This variable has a value
                      ENH_I18N       of 1 if the system supports
                                     the X/Open enhanced
                                     Internationalization Feature
                                     Group; otherwise, -1 is
                                     returned.
    XOPEN_SHM         _SC_XOPEN_     This variable has a value
                      SHM            of 1 if the system supports
                                     the X/Open Shared Memory
                                     Feature Group; otherwise, -1
                                     is returned.

    X/Open Extended

    ATEXIT_MAX        _SC_ATEXIT_    The maximum number of functions
                      MAX            that you can register with
                                     atexit per process.
    PAGESIZE          _SC_PAGESIZE   Size, in bytes, of a page.
    PAGE_SIZE         _SC_PAGE_      Same as PAGESIZE. If either
                      SIZE           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_     This variable has a value of
                      UNIX           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_       Returns information for
                      CHIP_TYPE      the processor type. See the
                                     description after this table.

    For the _SC_CPU_CHIP_TYPE symbolic constant:

    o  On Alpha servers, sysconf returns the architecture type (2),
       as given by the $GETSYI system service.

    o  Integrity processor information is stored in CPUID register
       3. This register contains a 64-bit integer divided into 1-byte
       fields indicating version information related to the processor
       implementation. The sysconf function returns the low-order
       longword with the following information:

       31     24 23    16 15    8 7     0
       ----------------------------------
       | family | model  | rev   |number|
       ----------------------------------

    These fields are described in the following table:

    Field  Bits   Description

    number 7:0    Index of the largest implemented CPUID register
                  (one less than the number of implemented CPUID
                  registers). This value will be at least 4.
    rev    15:8   Processor revision number. An 8-bit value that
                  represents the revision or stepping of this
                  processor implementation within the processor
                  model.
    model  23:16  Processor model number. A unique 8-bit value
                  representing the processor model within the
                  processor family.
    family 31:24  Processor family number. A unique 8-bit value
                  representing the processor family.

515.3  –  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.

516  –  system

    Passes a given string to the host environment to be executed by a
    command processor. This function is nonreentrant.

    Format

      #include  <stdlib.h>

      int system  (const char *string);

516.1  –  Argument

 string

    A pointer to the string to be executed. If string is NULL, a
    nonzero value is returned. The string is a DCL command, not
    the name of an image. To execute an image, use one of the exec
    routines.

516.2  –  Description

    The system function spawns a subprocess and executes the command
    specified by string in that subprocess. The system function waits
    for the subprocess to complete before returning the subprocess
    status as the return value of the function.

    The subprocess is spawned within the system call by a call to
    vfork. Because of this, a call to system should not be made after
    a call to vfork and before the corresponding call to an exec
    function.

    For OpenVMS Version 7.0 and higher systems, if you include
    <stdlib.h> and compile with the _POSIX_EXIT feature-test macro
    set, then the system function returns the status as if it called
    waitpid to wait for the child. Therefore, use the WIFEXITED and
    WEXITSTATUS macros (described in the wait* routines) to retrieve
    the exit status in the range of 0 to 255.

    You set the _POSIX_EXIT feature-test macro by using /DEFINE=_
    POSIX_EXIT or #define _POSIX_EXIT at the top of your file, before
    any file inclusions.

516.3  –  Return Value

    nonzero value      If string is NULL, a value of 1 is returned,
                       indicating that the system function is
                       supported. If string is not NULL, the value
                       is the subprocess OpenVMS return status.

516.4  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <unistd.h>     /* write, close */
        #include <fcntl.h>      /* Creat */

        main()
        {
            int status,
                fd;

            /* Creat a file we are sure is there        */

            fd = creat("system.test", 0);
            write(fd, "this is an example of using system", 34);
            close(fd);

            if (system(NULL)) {
                status = system("DIR/NOHEAD/NOTRAIL/SIZE SYSTEM.TEST");
                printf("system status = %d\n", status);
            }
            else
                printf("system() not supported.\n");
        }

    Running this example program produces the following result:

    DISK3$:[JONES.CRTL.2059.SRC]SYSTEM.TEST;1
                               1
    system status = 1

517  –  tan

    Returns a double value that is the tangent of its radian
    argument.

    Format

      #include  <math.h>

      double tan  (double x);

      float tanf  (float x); (Integrity servers, Alpha)

      long double tanl  (long double x); (Integrity servers, Alpha)

      double tand  (double x); (Integrity servers, Alpha)

      float tandf  (float x); (Integrity servers, Alpha)

      long double tandl  (long double x); (Integrity servers, Alpha)

517.1  –  Argument

 x

    A radian expressed as a real number.

517.2  –  Description

    The tan functions compute the tangent of x, measured in radians.

    The tand functions compute the tangent of x, measured in degrees.

517.3  –  Return Values

    x                  The tangent of the argument.
    HUGE_VAL           x is a singular point ( . . . -3pi/2, -pi/2,
                       pi/2 . . . ).
    NaN                x is NaN; errno is set to EDOM.
    0                  x is Infinity; errno is set to EDOM.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.
    0                  Underflow occurred; errno is set to ERANGE.

518  –  tanh

    Returns the hyperbolic tangent of its argument.

    Format

      #include  <math.h>

      double tanh  (double x);

      float tanhf  (float x); (Integrity servers, Alpha)

      long double tanhl  (long double x); (Integrity servers, Alpha)

518.1  –  Argument

 x

    A real number.

518.2  –  Description

    The tanh functions return the hyperbolic tangent their argument,
    calculated as (e**x - e**(-x))/(e**x + e**(-x)).

518.3  –  Return Values

    n                  The hyperbolic tangent of the argument.
    HUGE_VAL           The argument is too large; errno is set to
                       ERANGE.
    NaN                x is NaN; errno is set to EDOM.
    0                  Underflow occurred; errno is set to ERANGE.

519  –  telldir

    Returns the current location associated with a specified
    directory stream. Performs operations on directories.

    Format

      #include  <dirent.h>

      long int telldir  (DIR *dir_pointer);

519.1  –  Argument

 dir_pointer

    A pointer to the DIR structure of an open directory.

519.2  –  Description

    The telldir function returns the current location associated with
    the specified directory stream.

519.3  –  Return Values

    x                  The current location.
    -1                 Indicates an error and is further specified in
                       the global errno.

520  –  tempnam

    Constructs the name for a temporary file.

    Format

      #include  <stdio.h>

      char *tempnam  (const char *directory, const char

                     *prefix, . . . ;)

520.1  –  Arguments

 directory

    A pointer to the pathname of the directory where you want to
    create a file.

 prefix

    A pointer to an initial character sequence of the filename. The
    prefix argument can be null, or it can point to a string of up
    to five characters used as the first characters of the temporary
    filename.

  . . .

    An optional argument that can be either 1 or 0. If you specify 1,
    tempnam returns the file specification in OpenVMS format. If you
    specify 0, tempnam returns the file specification in UNIX style
    format.

520.2  –  Description

    The tempnam function generates filenames for temporary files. It
    allows you to control the choice of a directory.

    If the directory argument is null or points to a string that is
    not a pathname for an appropriate directory, the pathname defined
    as P_tmpdir in the <stdio.h> header file is used. For programs
    running under a detached process, the directory argument cannot
    be null.

    You can bypass the selection of a pathname by providing the
    TMPDIR environment variable in the user environment. The value
    of the TMPDIR variable is a pathname for the desired temporary
    file directory.

    Use the prefix argument to specify a prefix of up to five
    characters for the temporary filename.

    The tempnam function returns a pointer to the generated pathname,
    suitable for use in a subsequent call to the free function.

    See also free.

                                   NOTE

       In contrast to tmpnam, tempnam does not have to generate
       a different filename on each call. tempnam generates a new
       filename only if the file with the specified name exists. If
       you need a unique filename on each call, use tmpnam instead
       of tempnam.

520.3  –  Return Values

    x                  A pointer to the generated pathname, suitable
                       for use in a subsequent call to the free
                       function.
    NULL               An error occurred; errno is set to indicate
                       the error.

521  –  tgamma

    Returns the gamma function of its argument.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double tgamma  (double x);

      float tgammaf  (float x);

      long double tgammal  (long double x);

521.1  –  Argument

 x

    A real value.

521.2  –  Description

    The tgamma functions compute the gamma function of x.

521.3  –  Return Values

    n                  Upon success, the gamma function of x.
    -1                 If x is negative. errno is set to EDOM.
    HUGE_VAL           Overflow occurred, or x is 0. errno is set to
                       ERANGE.
    NaN                If x is NaN or -Inf. errno is set to EDOM.
    x                  If x is +Inf.

522  –  time

    Returns the time (expressed as Universal Coordinated Time)
    elapsed since 00:00:00, January 1, 1970, in seconds.

    Format

      #include  <time.h>

      time_t time  (time_t *time_location);

522.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to the
    time function that is equivalent to the behavior before OpenVMS
    Version 7.0.

522.2  –  Argument

 time_location

    Either NULL or a pointer to the place where the returned time is
    also stored. The time_t type is defined in the <time.h> header
    file as follows:

    typedef unsigned long int time_t;

522.3  –  Return Values

    x                  The time elapsed past the Epoch.
    (time_t)(-1)       Indicates an error. If the value of
                       SYS$TIMEZONE_DIFFERENTIAL logical is wrong,
                       the function will fail with errno set to
                       EINVAL.

523  –  times

    Passes back the accumulated times of the current process and its
    terminated child processes.

    Format

      #include  <times.h>

      clock_t times  (struct tms *buffer); (OpenVMS V7.0 and higher)

      void times  (tbuffer_t *buffer); (pre OpenVMS V7.0)

523.1  –  Argument

 buffer

    A pointer to the terminal buffer.

523.2  –  Description

    For both process and children times, the structure breaks down
    the time by user and system time. Since the OpenVMS system does
    not differentiate between system and user time, all system times
    are returned as 0. Accumulated CPU times are returned in 10-
    millisecond units.

    Only the accumulated times for child processes running a C main
    program or a program that calls VAXC$CRTL_INIT or DECC$CRTL_INIT
    are included.

    On OpenVMS Version 7.0 and higher systems, the times function
    returns the elapsed real time in clock ticks since an arbitrary
    reference time in the past (for example, system startup time).
    This reference time does not change from one times function call
    to another. The return value can overflow the possible range of
    type clock_t values. When times fails, it returns a value of -1.
    The C RTL uses system-boot time as its reference time.

523.3  –  Return Values

    x                  The elapsed real time in clock ticks since
                       system-boot time.
    (clock_t)(-1)      Indicates an error.

524  –  tmpfile

    Creates a temporary file that is opened for update.

    Format

      #include  <stdio.h>

      FILE *tmpfile  (void);

524.1  –  Description

    The file exists only for the duration of the process, or until
    the file is closed and is preserved across calls to vfork.

524.2  –  Return Values

    x                  The address of a file pointer (defined in the
                       <stdio.h> header file).
    NULL               Indicates an error.

525  –  tmpnam

    Generates filenames that can be safely used for a temporary file.

    Format

      #include  <stdio.h>

      char *tmpnam  (char *name);

525.1  –  Function Variants

    The tmpnam function has variants named _tmpnam32 and _tmpnam64
    for use with 32-bit and 64-bit pointer sizes, respectively.

525.2  –  Argument

 name

    A character string containing a name to use in place of file-name
    arguments in functions or macros. Successive calls to tmpnam with
    a null argument cause the function to overwrite the current name.

525.3  –  Return Value

    x                  If the name argument is the NULL pointer
                       value NULL, tmpnam returns the address of
                       an internal storage area. If name is not NULL,
                       then it is considered the address of an area
                       of length L_tmpnam (defined in the <stdio.h>
                       header file). In this case, tmpnam returns the
                       name argument as the result.

526  –  toascii

    Converts its argument, an 8-bit ASCII character, to a 7-bit ASCII
    character.

    Format

      #include  <ctype.h>

      int toascii  (char character);

526.1  –  Argument

 character

    An object of type char.

526.2  –  Return Value

    x                  A 7-bit ASCII character.

527  –  tolower

    Converts a character to lowercase.

    Format

      #include  <ctype.h>

      int tolower  (int character);

527.1  –  Argument

 character

    An object of type int representable as an unsigned char or the
    value of EOF. For any other value, the behavior is undefined.

527.2  –  Description

    If the argument represents an uppercase letter, and there is
    a corresponding lowercase letter, as defined by character
    type information in the program locale category LC_CTYPE, the
    corresponding lowercase letter is returned.

    If the argument is not an uppercase character, it is returned
    unchanged.

527.3  –  Return Value

    x                  The lowercase letter corresponding to the
                       argument. Or, the unchanged argument, if it is
                       not an uppercase character.

528  –  _tolower

    Converts an uppercase character to lowercase.

    Format

      #include  <ctype.h>

      int _tolower  (int character);

528.1  –  Argument

 character

    This argument must be an uppercase letter.

528.2  –  Description

    The _tolower macro is equivalent to the tolower function except
    that its argument must be an uppercase letter (not lowercase, not
    EOF).

    As of OpenVMS Version 8.3 and to comply with the C99 ANSI
    standard and X/Open Specification, the _tolower macro by default
    does not evaluate its parameter more than once. It simply calls
    the tolower function. This avoids side effects (such as i++
    or function calls) where the user can tell how many times an
    expression is evaluated.

    To keep the older, optimized _tolower macro behavior, compile
    with /DEFINE=_FAST_TOUPPER. Then, as in previous releases, _
    tolower optimizes the call to avoid the overhead of a runtime
    call. The parameters are checked to determine how to calculate
    the result, thereby creating unwanted side effects. Therefore,
    when compiling with /DEFINE=_FAST_TOUPPER, do not use the _
    tolower macro with arguments that contain side-effect operations.
    For instance, the following example will not return the expected
    result:

    d = _tolower (C++);

528.3  –  Return Value

    x                  The lowercase letter corresponding to the
                       argument.

529  –  touchwin

    Places the most recently edited version of the specified window
    on the terminal screen.

    Format

      #include  <curses.h>

      int touchwin  (WINDOW *win);

529.1  –  Argument

 win

    A pointer to the window.

529.2  –  Description

    The touchwin function is normally used only to refresh
    overlapping windows.

529.3  –  Return Values

    OK                 Indicates success.
    ERR                Indicates an error.

530  –  toupper

    Converts a character to uppercase.

    Format

      #include  <ctype.h>

      int toupper  (int character);

530.1  –  Argument

 character

    An object of type int representable as an unsigned char or the
    value of EOF. For any other value, the behavior is undefined.

530.2  –  Description

    If the argument represents a lowercase letter, and there is
    a corresponding uppercase letter, as defined by character
    type information in the program locale category LC_CTYPE, the
    corresponding uppercase letter is returned.

    If the argument is not a lowercase character, it is returned
    unchanged.

530.3  –  Return Value

    x                  The uppercase letter corresponding to the
                       argument. Or, the unchanged argument, if the
                       argument is not a lowercase character.

531  –  _toupper

    Converts a lowercase character to uppercase.

    Format

      #include  <ctype.h>

      int _toupper  (int character);

531.1  –  Argument

 character

    This argument must be a lowercase letter.

531.2  –  Description

    The _toupper macro is equivalent to the toupper function except
    that its argument must be a lowercase letter (not uppercase, not
    EOF).

    As of OpenVMS Version 8.3 and to comply with the C99 ANSI
    standard and X/Open Specification, the _toupper macro by default
    does not evaluate parameters more than once. It simply calls
    the toupper function. This avoids side effects (such as i++
    or function calls) where the user can tell how many times an
    expression is evaluated.

    To keep the older, optimized _toupper macro behavior, compile
    with /DEFINE=_FAST_TOUPPER. Then, as in previous releases, _
    toupper optimizes the call to avoid the overhead of a runtime
    call. The parameters are checked to determine how to calculate
    the result, thereby creating unwanted side effects. So when
    compiling with /DEFINE=_FAST_TOUPPER, do not use the _toupper
    macro with arguments that contain side-effect operations. For
    instance, the following example will not return the expected
    result:

    d = _toupper (c++);

531.3  –  Return Value

    x                  The uppercase letter corresponding to the
                       argument.

532  –  towctrans

    Maps one wide character to another according to a specified
    mapping descriptor.

    Format

      #include  <wctype.h>

      wint_t towctrans  (wint_t wc, wctrans_t desc);

532.1  –  Arguments

 wc

    The wide character that you want to map.

 desc

    Description of the mapping obtained through a call to the wctrans
    function.

532.2  –  Description

    The towctrans function maps the wide character specified in wc,
    using the mapping described by desc.

    The current setting of the LC_CTYPE category must be the same as
    during the call to the wctrans function that returned the value
    of desc.

532.3  –  Return Value

    x                  The mapped value of the wc wide character,
                       if this character exists in the mapping
                       described by desc. Otherwise, the value of
                       wc is returned.

533  –  towlower

    Converts the argument, a wide-character code, to lowercase.
    If the argument is not an uppercase character, it is returned
    unchanged.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int towlower  (wint_t wc);

533.1  –  Argument

 wc

    An object of type wint_t representable as a valid wide character
    in the current locale, or the value of WEOF. For any other value,
    the behavior is undefined.

533.2  –  Description

    If the argument is an uppercase wide character, the corresponding
    lowercase wide character (as defined in the LC_CTYPE category of
    the locale) is returned, if it exists. If it does not exist, the
    function returns the input argument unchanged.

534  –  towupper

    Converts the argument, a wide character, to uppercase. If the
    argument is not a lowercase character, it is returned unchanged.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      int towupper  (wint_t wc);

534.1  –  Argument

 wc

    An object of type wint_t representable as a valid wide character
    in the current locale, or the value of WEOF. For any other value,
    the behavior is undefined.

534.2  –  Description

    If the argument is a lowercase wide character, the corresponding
    uppercase wide character (as defined in the LC_CTYPE category of
    the locale) is returned, if it exists. If it does not exist, the
    function returns the input argument unchanged.

535  –  trunc

    Truncates the argument to an integral value.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double trunc  (double x);

      float truncf  (float x,);

      long double truncl  (long double x);

535.1  –  Argument

 x

    A floating-point number.

535.2  –  Return Value

    n                  The truncated, integral value of the argument.

536  –  truncate

    Changes file length to a specified length, in bytes.

    Format

      #include  <unistd.h>

      int truncate  (const char *path, off_t length);

536.1  –  Arguments

 path

    The name of a file that is to be truncated. This argument must
    point to a pathname that names a regular file for which the
    calling process has write permission.

 length

    The new length of the file, in bytes. The off_t type of length
    is either a 64-bit or 32-bit integer. The 64-bit interface allows
    for file sizes greater than 2 GB, and can be selected at compile
    time by defining the _LARGEFILE feature-test macro as follows:

    CC/DEFINE=_LARGEFILE

536.2  –  Description

    The truncate function changes the length of a file to the size,
    in bytes, specified by the length argument.

    If the new length is less than the previous length, the function
    removes all data beyond length bytes from the specified file. All
    file data between the new End-of-File and the previous End-of-
    File is discarded.

    For stream files, if the new length is greater than the previous
    length, new file data between the previous End-of-File and the
    new End-of-File is added, consisting of all zeros. (For record
    files, it is not possible to extend the file in this manner.)

536.3  –  Return Values

    0                  Indicates success.
    -1                 An error occurred; errno is set to indicate
                       the error.

537  –  ttyname

    Find the pathname of a terminal.

    Format

      #include  <unixio.h> (Compatibility)

      char *ttyname  (void); (Compatibility)

      #include  <unistd.h> (OpenVMS V7.3-2 and higher)

      char *ttyname  (int filedes); (OpenVMS V7.3-2 and higher)

      int ttyname_r  (int filedes, char name, size_t

                     namesize); (OpenVMS V7.3-2 and higher),

                     (Integrity servers, Alpha)

537.1  –  Arguments

 filedes

    An open file descriptor.

 name

    Pointer to a buffer in which the terminal name is stored.

 namesize

    The length of the buffer pointed to by the name argument.

537.2  –  Description

    The implementation of the ttyname function that takes no
    argument is provided only for backward compatibility. This
    legacy implementation returns a pointer to the null-terminated
    name of the terminal device associated with file descriptor 0,
    the default input device (stdin). A value of 0 is returned if
    SYS$INPUT is not a TTY device.

    The ttyname_r function and the implementation of ttyname that
    takes a filedes argument are UNIX standard compliant and are
    available with only OpenVMS Version 7.3-2 and higher.

    The standard compliant ttyname function returns a pointer to a
    string containing a null-terminated pathname of the terminal
    associated with file descriptor filedes. The return value might
    point to static data whose content is overwritten by each call.
    The ttyname interface need not be reentrant.

    The ttyname_r function returns a pointer to store the null-
    terminated pathname of the terminal associated with the file
    descriptor filedes in the character array referenced by name. The
    array is namesize characters long and should have space for the
    name and the terminating null character. The maximum length of
    the terminal name is TTY_NAME_MAX.

    If successful, ttyname returns a pointer to a string. Otherwise,
    a NULL pointer is returned and errno is set to indicate the
    error.

    If successful, ttyname_r stores the terminal name as a null-
    terminated string in the buffer pointed to by name and returns 0.
    Otherwise, an error number is returned to indicate the error.

537.3  –  Return Values

    x                  Upon successful completion, ttyname returns a
                       pointer to a null-terminated string.
    NULL               Upon failure, ttyname returns a NULL pointer
                       and sets errno to indicate the failure:

                       o  EBADF - The fildes argument is not a valid
                          file descriptor.

                       o  ENOTTY - The fildes argument does not refer
                          to a terminal device.

    0                  Upon successful completion, ttyname_r returns
                       0.
    n                  Upon failure, ttyname_r sets errno to indicate
                       the failure, and returns the same errno code:

                       o  EBADF - The fildes argument is not a valid
                          file descriptor.

                       o  ENOTTY - The fildes argument does not refer
                          to a TTY device.

                       o  ERANGE - The value of namesize is smaller
                          than the length of the string to be
                          returned including the terminating null
                          character.

    0                  For the legacy ttyname, indicates that
                       SYS$INPUT is not a TTY device.

538  –  tzset

    Sets and accesses time-zone conversion.

    Format

      #include  <time.h>

      void tzset  (void);

      extern  char *tzname[];

      extern  long int timezone;

      extern  int daylight;

538.1  –  Description

    The tzset function initializes time-conversion information
    used by the ctime, localtime, mktime, strftime, and wcsftime
    functions.

    The tzset function sets the following external variables:

    o  tzname is set as follows, where "std" is a 3-byte name for
       the standard time zone, and "dst" is a 3-byte name for the
       Daylight Savings Time zone:

       tzname[0] = "std"
       tzname[1] = "dst"

    o  daylight is set to 0 if Daylight Savings Time should never be
       applied to the time zone. Otherwise, daylight is set to 1.

    o  timezone is set to the difference between UTC and local
       standard time.

    The environment variable TZ specifies how tzset initializes time
    conversion information:

    o  If TZ is absent from the environment, the implementation-
       dependent time-zone information is used, as follows:

          The best available approximation to local wall-clock time
          is used, as defined by the SYS$LOCALTIME system logical,
          which points to a tzfile format file that describes default
          time-zone rules.
          This system logical is set during the installation
          of OpenVMS Version 7.0 or higher to define a
          time-zone file based off the root directory
          SYS$COMMON:[SYS$ZONEINFO.SYSTEM].

    o  If TZ appears in the environment but its value is a null
       string, Coordinated Universal Time (UTC) is used (without
       leap-second correction).

    o  If TZ appears in the environment and its value is not a null
       string, the value has one of three formats, as described in
       Time-Zone Initialization Rules.

    Table REF-11 Time-Zone Initialization Rules

    TZ Format    Meaning

    :            UTC is used.
    :pathname    The characters following the colon specify the
                 pathname of a tzfile format file from which to
                 read the time-conversion information. A pathname
                 beginning with a slash (/)  represents an absolute
                 pathname; otherwise, the pathname is relative to
                 the system time-conversion information directory
                 specified by SYS$TZDIR, which by default is
                 SYS$COMMON:[SYS$ZONEINFO.SYSTEM].
    stdoffset[dstThefset]e is first used as the pathname of a file
                 (as described for the :pathname format) from which
    [,rule]]     to read the time-conversion information.

                 If that file cannot be read, the value is then
                 interpreted as a direct specification of the time-
                 conversion information, as follows:
                 std and dst-Three or more characters that are the
                 designation for the time zone:

                 o  std-Standard time zone. Required.

                 o  dst-Daylight Savings Time zone. Optional. If dst
                    is omitted, Daylight Savings Time does not apply.

                 Uppercase and lowercase letters are explicitly
                 allowed. Any characters are allowed, except the
                 following:

                 o  digits

                 o  leading colon (:)

                 o  comma (,)

                 o  minus (-)

                 o  plus (+)

                 o  ASCII null character

                 offset-The value added to the local time to arrive
                 at UTC. The offset has the following format:

                 hh[:mm[:ss]]

                 In this format:

                 o  hh (hours) is a one-or two-digit value of 0-24.

                 o  mm (minutes) is a value of 0-59. (optional)

                 o  ss (seconds) is a value of 0-59. (optional)

                 The offset following std is required. If no offset
                 follows dst, summer time is assumed, one hour ahead
                 of standard time. You can use one or more digits;
                 the value is always interpreted as a decimal number.

                 If the time zone is preceded by a minus sign (-),
                 the time zone is East of Greenwich; otherwise, it
                 is West, which can also be indicated by a preceding
                 plus sign (+).
                 rule-Indicates when to change to and return from
                 summer time. The rule has the form:

                 start[/time], end[/time]

                 where:

                 o  start is the date when the change from standard
                    time to summer time occurs.

                 o  end is the date for returning from summer time to
                    standard time.

                 If start and end are omitted, the default is the
                 US Daylight Savings Time start and end dates.
                 The format for start and end must be one of the
                 following:

                 o  Jn-The Julian day n (1 < n < 365). Leap days are
                    not counted. That is, in all years, including
                    leap years, February 28 is day 59 and March 1 is
                    day 60. You cannot explicitly refer to February
                    29.

                 o  n-The zero based Julian day (0 < n < 365). Leap
                    days are counted, making it possible to refer to
                    February 29.

                 o  Mm.n.d-The nth d day of month m, where:

                       0 < n < 5
                       0 < d < 6
                       1 < m < 12

                    When n is 5, it refers to the last d day of month
                    m. Sunday is day 0.

                 time-The time when, in current time, the change to
                 or return from summer time occurs. The time argument
                 has the same format as offset, except that you
                 cannot use a leading minus (-)  or plus (+) sign.
                 If time is not specified, the default is 02:00:00.

                 If no rule is present in the TZ specification, the
                 rules used are those specified by the tzfile format
                 file defined by the SYS$POSIXRULES system logical
                 in the system time-conversion information directory,
                 with the standard and summer time offsets from UTC
                 replaced by those specified by the offset values in
                 TZ.

                 If TZ does not specify a tzfile format file and
                 cannot be interpreted as a direct specification, UTC
                 is used.

                                   NOTE

       The UTC-based time functions, introduced in OpenVMS Version
       7.0, had degraded performance compared with the non-UTC-
       based time functions.

       OpenVMS Version 7.1 added a cache for time-zone files to
       improve performance. The size of the cache is determined
       by the logical name DECC$TZ_CACHE_SIZE. To accommodate most
       countries changing the time twice per year, the default
       cache size is large enough to hold two time-zone files.

    See also ctime, localtime, mktime, strftime, and wcsftime.

538.2  –  Sample TZ Specification

        EST5EDT4,M4.1.0,M10.5.0

      This sample TZ specification describes the rule defined in 1987
      for the Eastern time zone in the US:

      o  EST (Eastern Standard Time) is the designation for standard
         time, which is 5 hours behind UTC.

      o  EDT (Eastern Daylight Time) is the designation for summer
         time, which is 4 hours behind UTC. EDT starts on the first
         Sunday in April and ends on the last Sunday in October.

      Because time was not specified in either case, the changes
      occur at the default time, which is 2:00 A.M. The start and
      end dates did not need to be specified, because they are the
      defaults.

539  –  ualarm

    Sets or changes the timeout of interval timers.

    Format

      #include  <unistd.h>

      useconds_t ualarm  (useconds_t mseconds, useconds_t interval);

539.1  –  Arguments

 mseconds

    Specifies a number of real-time microseconds.

 interval

    Specifies the interval for repeating the timer.

539.2  –  Description

    The ualarm function causes the SIGALRM signal to be generated for
    the calling process after the number of real-time microseconds
    specified by useconds has elapsed. When the interval argument is
    nonzero, repeated timeout notification occurs with a period in
    microseconds specified by interval. If the notification signal
    SIGALRM is not intercepted or is ignored, the calling process is
    terminated.

    If you call a combination of ualarm and setitimer functions, and
    the AST status is disabled, the return value is invalid.

    If you call a combination of ualarm and setitimer functions, and
    the AST status is enabled, the return value is valid.

    This is because you cannot invoke an AST handler to clear the
    previous value of the timer when ASTs are disabled or invoked
    from a handler that was invoked at AST level.

                                   NOTE

       Interactions between ualarm and either alarm, or sleep are
       unspecified.

    See also setitimer.

539.3  –  Return Values

    n                  The number of microseconds remaining from the
                       previous ualarm or setitimer call.
    0                  No timeouts are pending or ualarm not
                       previously called.
    -1                 Indicates an error.

540  –  umask

    Creates a file protection mask that is used when a new file is
    created, and returns the previous mask value.

    Format

      #include  <stat.h>

      mode_t umask  (mode_t mode_complement);

540.1  –  Argument

 mode_complement

    Shows which bits to turn off when a new file is created. See the
    description of chmod to determine what the bits represent.

540.2  –  Description

    Initially, the file protection mask is set from the current
    process's default file protection. This is done when the C main
    program starts up or when DECC$CRTL_INIT (or VAXC$CRTL_INIT)
    is called. You can change this for all files created by your
    program by calling umask or you can use chmod to change the file
    protection on individual files. The file protection of a file
    created by open or creat is the bitwise AND of the open and creat
    mode argument with the complement of the value passed to umask on
    the previous call.

                                   NOTE

       The way to create files with OpenVMS RMS default protections
       using the UNIX system-call functions umask, mkdir, creat,
       and open is to call mkdir, creat, and open with a file-
       protection mode argument of 0777 in a program that never
       specifically calls umask. These default protections include
       correctly establishing protections based on ACLs, previous
       versions of files, and so on.

       In programs that do vfork/exec calls, the new process image
       inherits whether umask has ever been called or not from
       the calling process image. The umask setting and whether
       the umask function has ever been called are both inherited
       attributes.

540.3  –  Return Value

    x                  The old mask value.

541  –  uname

    Gets system identification information.

    Format

      #include  <utsname.h>

      int uname  (struct utsname *name);

541.1  –  Argument

 name

    The current system identifier.

541.2  –  Description

    The uname function stores null-terminated strings of information
    identifying the current system into the structure referenced by
    the name argument.

    The utsname structure is defined in the <utsname.h> header file
    and contains the following members:

    sysname        Name of the operating system implementation
    nodename       Network name of this machine
    release        Release level of the operating system
    version        Version level of the operating system
    machine        Machine hardware platform

541.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error; errno or vaxc$errno is set
                       as appropriate.

542  –  ungetc

    Pushes a character back into the input stream and leaves the
    stream positioned before the character.

    Format

      #include  <stdio.h>

      int ungetc  (int character, FILE *file_ptr);

542.1  –  Arguments

 character

    A value of type int.

 file_ptr

    A file pointer.

542.2  –  Description

    When using the ungetc function, the character is pushed back onto
    the file indicated by file_ptr.

    One push-back is guaranteed, even if there has been no previous
    activity on the file. The fseek function erases all memory of
    pushed-back characters. The pushed-back character is not written
    to the underlying file. If the character to be pushed back is
    EOF, the operation fails, the input stream is left unchanged, and
    EOF is returned.

    See also fseek and getc.

542.3  –  Return Values

    x                  The push-back character.
    EOF                Indicates it cannot push the character back.

543  –  ungetwc

    Pushes a wide character back into the input stream.

    Format

      #include  <wchar.h>

      wint_t ungetwc  (wint_t wc, FILE *file_ptr);

543.1  –  Arguments

 wc

    A value of type wint_t.

 file_ptr

    A file pointer.

543.2  –  Description

    When using the ungetwc function, the wide character is pushed
    back onto the file indicated by file_ptr.

    One push-back is guaranteed, even if there has been no previous
    activity on the file. If a file positioning function (such as
    fseek) is called before the pushed back character is read, the
    bytes representing the pushed back character are lost.

    If the character to be pushed back is WEOF, the operation fails,
    the input stream is left unchanged, and WEOF is returned.

    See also getwc.

543.3  –  Return Values

    x                  The push-back character.
    WEOF               Indicates that the function cannot push the
                       character back. errno is set to one of the
                       following:

                       o  EBADF - The file descriptor is not valid.

                       o  EALREADY - Operation is already in progress
                          on the same file.

                       o  EILSEQ - Invalid wide-character code
                          detected.

544  –  unlink

    Deletes the specified symbolic link from the system.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <unistd.h>

      int unlink  (const char *link_name);

544.1  –  Arguments

 link_name

    The name of the symbolic link to be deleted.

544.2  –  Description

    The unlink function deletes the specified symbolic link (link_
    name) from the system. The contents of the symbolic link are not
    examined, and no action is performed on the file specified in the
    contents. For other files, the unlink function behaves the same
    as the C RTL remove function.

    See also symlink, readlink, realpath, lchown, and lstat.

544.3  –  Return Values

    0                  Successful completion.
    -1                 Indicates an error. The named file (link_name)
                       is unchanged, and errno is set to any errno
                       value from remove.

545  –  unordered

    Returns the value 1 (TRUE) if either or both of the arguments is
    a NaN. Otherwise, it returns the value 0 (FALSE).

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double unordered  (double x, double y);

      float unorderedf  (float x, float y);

      long double unorderedl  (long double x, long double y);

545.1  –  Arguments

 x

    A real number.

 y

    A real number.

545.2  –  Return Values

    1                  Either or both of the arguments is a NaN.
    0                  Neither argument is a NaN.

546  –  unsetenv

    Deletes all instances of the environment variable name from the
    environment list.

    Format

      #include  <stdlib.h>

      void unsetenv  (const char *name);

546.1  –  Argument

 name

    The environment variable to delete from the environment list.

546.2  –  Description

    The unsetenv function deletes all instances of the variable name
    pointed to by the name argument from the environment list.

547  –  usleep

    Suspends execution for an interval.

    Format

      #include  <unistd.h>

      int usleep  (unsigned int mseconds);

547.1  –  Argument

 mseconds

    The number of microseconds to suspend execution for.

547.2  –  Description

    The usleep function suspends the current process from execution
    for the number of microseconds specified by the mseconds
    argument. This argument must be less than 1,000,000. However,
    if its value is 0, then the call has no effect.

    Be aware that usleep time specifications are rounded up
    approximately to the next millisecond because that is the finest
    time interval granularity possible on OpenVMS systems.

    There is one real-time interval timer for each process. The
    usleep function does not interfere with a previous setting of
    this timer. If the process set this timer before calling usleep
    and if the time specified by mseconds equals or exceeds the
    interval timer's prior setting, then the process is awakened
    shortly before the timer was set to expire.

547.3  –  Return Values

    0                  Indicates success.
    -1                 Indicates an error occurred; errno is set to
                       EINVAL.

548  –  utime

    Sets file access and modification times.

    Format

      #include  <utime.h>

      int utime  (const char *path, const struct utimbuf *times);

548.1  –  Arguments

 path

    A pointer to a file.

 times

    A NULL pointer or a pointer to a utimbuf structure.

548.2  –  Description

    The utime function sets the access and modification times of the
    filenamed by the path argument. The file must be openable for
    write-access to use this function.

    If times is a NULL pointer, the access and modification times of
    the file are set to the current time. To use utime in this way,
    the effective user ID of the process must match the owner of the
    file, or the process must have write permission to the file or
    have appropriate privileges.

    If times is not a NULL pointer, it is interpreted as a pointer
    to a utimbuf structure, and the access and modification times
    are set to the values in the specified structure. Only a process
    with an effective user ID equal to the user ID of the file or a
    process with appropriate privileges can use utime this way.

    The utimbuf structure is defined by the <utime.h> header. The
    times in the utimbuf structure are measured in seconds since the
    Epoch.

    Upon successful completion, utime marks the time of the last file
    status change, st_ctime, to be updated. See the <stat.h> header
    file.

                     NOTE (Integrity servers, Alpha)

       On OpenVMS Alpha and Integrity server systems, the stat,
       fstat, utime, and utimes functions have been enhanced to
       take advantage of the new file-system support for POSIX
       compliant file timestamps.

       This support is available only on ODS-5 devices on OpenVMS
       Alpha systems beginning with a version of OpenVMS Alpha
       after Version 7.3.

       Before this change, stat and fstat set the values of the st_
       ctime, st_mtime, and st_atime fields based on the following
       file attributes:

          st_ctime - ATR$C_CREDATE (file creation time)
          st_mtime - ATR$C_REVDATE (file revision time)
          st_atime - was always set to st_mtime because no support
          for file access time was available

       Also, for the file-modification time, utime and utimes were
       modifying the ATR$C_REVDATE file attribute, and ignoring the
       file-access-time argument.

       After the change, for a file on an ODS-5 device, the stat
       and fstat functions set the values of the st_ctime, st_
       mtime, and st_atime fields based on the following new file
       attributes:

          st_ctime - ATR$C_ATTDATE (last attribute modification
          time)
          st_mtime - ATR$C_MODDATE (last data modification time)
          st_atime - ATR$C_ACCDATE (last access time)

       If ATR$C_ACCDATE is 0, as on an ODS-2 device, the stat and
       fstat functions set st_atime to st_mtime.

       For the file-modification time, the utime and utimes
       functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
       file attributes. For the file-access time, these functions
       modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
       MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
       has no effect.

       For compatibility, the old behavior of stat, fstat, utime,
       and utimes remains the default, regardless of the kind of
       device.

       The new behavior must be explicitly enabled by defining the
       DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before
       invoking the application. Setting this logical does not
       affect the behavior of stat, fstat, utime, and utimes for
       files on an ODS-2 device.

548.3  –  Return Values

    0                  Successful execution.
    -1                 Indicates an error. The function sets errno to
                       one of the following values:

                       The utime function will fail if:

                       o  EACCES - Search permission is denied by
                          a component of the path prefix; or the
                          times argument is a NULL pointer and the
                          effective user ID of the process does
                          not match the owner of the file and write
                          access is denied.

                       o  ELOOP - Too many symbolic links were
                          encountered in resolving path.

                       o  ENAMETOOLONG - The length of the path
                          argument exceeds PATH_MAX, a pathname
                          component is longer than NAME_MAX, or a
                          pathname resolution of a symbolic link
                          produced an intermediate result whose
                          length exceeds PATH_MAX.

                       o  ENOENT - path does not name an existing
                          file, or path is an empty string.

                       o  ENOTDIR - A component of the path prefix is
                          not a directory.

                       o  EPERM - times is not a NULL pointer and
                          the calling process's effective user ID has
                          write-access to the file but does not match
                          the owner of the file, and the calling
                          process does not have the appropriate
                          privileges.

                       o  EROFS - The file system containing the file
                          is read-only.

549  –  utimes

    Sets file access and modification times.

    Format

      #include  <time.h>

      int utimes  (const char *path, const struct timeval times[2]);

549.1  –  Arguments

 path

    A pointer to a file.

 times

    an array of timeval structures. The first array member represents
    the date and time of last access, and the second member
    represents the date and time of last modification. The times
    in the timeval structure are measured in seconds and microseconds
    since the Epoch, although rounding toward the nearest second may
    occur.

549.2  –  Description

    The utimes function sets the access and modification times of the
    file pointed to by the path argument to the value of the times
    argument. The utimes function allows time specifications accurate
    to the microsecond.

    If the times argument is a NULL pointer, the access and
    modification times of the file are set to the current time. The
    effective user ID of the process must be the same as the owner
    of the file, or must have write access to the file or appropriate
    privileges to use this call in this manner.

    Upon completion, utimes marks the time of the last file status
    change, st_ctime, for update.

                     NOTE (Integrity servers, Alpha)

       On OpenVMS Alpha and Integrity server systems, the stat,
       fstat, utime, and utimes functions have been enhanced to
       take advantage of the new file-system support for POSIX
       compliant file timestamps.

       This support is available only on ODS-5 devices on OpenVMS
       Alpha systems beginning with a version of OpenVMS Alpha
       after Version 7.3.

       Before this change, the stat and fstat functions were
       setting the values of the st_ctime, st_mtime, and st_atime
       fields based on the following file attributes:

          st_ctime - ATR$C_CREDATE (file creation time)
          st_mtime - ATR$C_REVDATE (file revision time)
          st_atime - was always set to st_mtime because no support
          for file access time was available

       Also, for the file-modification time, utime and utimes were
       modifying the ATR$C_REVDATE file attribute, and ignoring the
       file-access-time argument.

       After the change, for a file on an ODS-5 device, the stat
       and fstat functions set the values of the st_ctime, st_
       mtime, and st_atime fields based on the following new file
       attributes:

          st_ctime - ATR$C_ATTDATE (last attribute modification
          time)
          st_mtime - ATR$C_MODDATE (last data modification time)
          st_atime - ATR$C_ACCDATE (last access time)

       If ATR$C_ACCDATE is 0, as on an ODS-2 device, the stat and
       fstat functions set st_atime to st_mtime.

       For the file-modification time, the utime and utimes
       functions modify both the ATR$C_REVDATE and ATR$C_MODDATE
       file attributes. For the file-access time, these functions
       modify the ATR$C_ACCDATE file attribute. Setting the ATR$C_
       MODDATE and ATR$C_ACCDATE file attributes on an ODS-2 device
       has no effect.

       For compatibility, the old behavior of stat, fstat, utime,
       and utimes remains the default, regardless of the kind of
       device.

       The new behavior must be explicitly enabled by defining the
       DECC$EFS_FILE_TIMESTAMPS logical name to "ENABLE" before
       invoking the application. Setting this logical does not
       affect the behavior of stat, fstat, utime, and utimes for
       files on an ODS-2 device.

549.3  –  Return Values

    0                  Successful execution.
    -1                 Indicates an error. The file times do not
                       change and the function sets errno to one of
                       the following values:

                       The utimes function will fail if:

                       o  EACCES - Search permission is denied by
                          a component of the path prefix; or the
                          times argument is a NULL pointer and the
                          effective user ID of the process does
                          not match the owner of the file and write
                          access is denied.

                       o  ELOOP - Too many symbolic links were
                          encountered in resolving path.

                       o  ENAMETOOLONG - The length of the path
                          argument exceeds PATH_MAX, a pathname
                          component is longer than NAME_MAX, or a
                          pathname resolution of a symbolic link
                          produced an intermediate result whose
                          length exceeds PATH_MAX.

                       o  ENOENT - A component of path does not
                          name an existing file, or path is an empty
                          string.

                       o  ENOTDIR - A component of the path prefix is
                          not a directory.

                       o  EPERM -The times argument is not a NULL
                          pointer and the calling process's effective
                          user ID has write-access to the file but
                          does not match the owner of the file and
                          the calling process does not have the
                          appropriate privileges.

                       o  EROFS - The file system containing the file
                          is read-only.

550  –  VAXC$CRTL_INIT

    Allows you to call the C RTL from other languages or to
    use the C RTL when your main function is not in C. It
    initializes the run-time environment and establishes both an exit
    and condition handler. VAXC$CRTL_INIT is a synonym for DECC$CRTL_
    INIT. Either name invokes the same routine.

    Format

      #include  <signal.h>

      void VAXC$CRTL_INIT();

550.1  –  Description

    The following example shows a Pascal program that calls the
    C RTL using the VAXC$CRTL_INIT function:

    On OpenVMS Alpha systems:

    $ PASCAL EXAMPLE
    $ LINK EXAMPLE,SYS$LIBRARY:VAXCRTL/LIB
    $ TY EXAMPLE.PAS
    PROGRAM TESTC(input, output);
    PROCEDURE VAXC$CRTL_INIT; extern;
    BEGIN
       VAXC$CRTL_INIT;
    END
    $

    A shareable image need only call this function if it contains
    an VSI C function for signal handling, environment variables,
    I/O, exit handling, a default file protection mask, or if it is a
    child process that should inherit context.

    Although many of the initialization activities are performed
    only once, DECC$CRTL_INIT can safely be called multiple times. On
    OpenVMS VAX systems, DECC$CRTL_INIT establishes the C RTL
    internal OpenVMS exception handler in the frame of the routine
    that calls DECC$CRTL_INIT each time DECC$CRTL_INIT is called.

    At least one frame in the current call stack must have that
    handler established for OpenVMS exceptions to get mapped to UNIX
    signals.

551  –  VAXC$ESTABLISH

    Used for establishing an OpenVMS exception handler for a
    particular routine. This function establishes a special C RTL
    exception handler in the routine that called it. This special
    handler catches all RTL-related exceptions that occur in later
    routines, and passes on all other exceptions to your handler.

    Format

      #include  <signal.h>

      void VAXC$ESTABLISH  (unsigned int (*exception_handler)(void
                           *sigarr, void *mecharr));

551.1  –  Arguments

 exception_handler

    The name of the function that you want to establish as an OpenVMS
    exception handler. You pass a pointer to this function as the
    parameter to VAXC$ESTABLISH.

 sigarr

    A pointer to the signal array.

 mecharr

    A pointer to the mechanism array.

551.2  –  Description

    VAXC$ESTABLISH must be used in place of LIB$ESTABLISH when
    programs use the C RTL routines setjmp or longjmp. See
    setjmp and longjmp, or sigsetjmp and siglongjmp.

    You can only invoke the VAXC$ESTABLISH function from an VSI C
    for OpenVMS function, because it relies on the allocation of data
    space on the run-time stack by the VSI C compiler. Calling
    the OpenVMS system library routine LIB$ESTABLISH directly from an
    VSI C function results in undefined behavior from the setjmp
    and longjmp functions.

    To cause an OpenVMS exception to generate a UNIX style signal,
    user exception handlers must return SS$_RESIGNAL upon receiving
    any exception that they do not want to handle. Returning SS$_
    NORMAL prevents the generation of a UNIX style signal. UNIX
    signals are generated as if by an exception handler in the
    stack frame of the main C program. Not all OpenVMS exceptions
    correspond to UNIX signals. See the "Error and Signal Handling"
    chapter of the VSI C RTL Reference Manual. for more information on
    the interaction of OpenVMS exceptions and UNIX style signals.

    Calling VAXC$ESTABLISH with an argument of NULL cancels an
    existing handler in that routine.

                                  NOTES

       On OpenVMS Alpha systems, VAXC$ESTABLISH is implemented as a
       compiler built-in function, not as an C RTL function.
       (Alpha only)

552  –  va_arg

    Returns the next item in the argument list.

    Format

      #include  <stdarg.h> (ANSI C)

      #include  <varargs.h> (DEC C Extension)

      type va_arg  (va_list ap, type);

552.1  –  Arguments

 ap

    A variable list containing the next argument to be obtained.

 type

    A data type that is used to determine the size of the next item
    in the list. An argument list can contain items of varying sizes,
    but the calling routine must determine what type of argument is
    expected since it cannot be determined at run time.

552.2  –  Description

    The va_arg function interprets the object at the address
    specified by the list incrementor according to type. If there
    is no corresponding argument, the behavior is undefined.

    When using va_arg to write portable applications, include the
    <stdarg.h> header file (defined by the ANSI C standard), not the
    <varargs.h> header file, and use va_arg only in conjunction with
    other functions and macros defined in <stdarg.h>.

    For an example of argument-list processing using the <stdarg.h>
    functions and definitions, see the "Character, String, and
    Argument-List Functions" chapter of the VSI C RTL Reference
    Manual.

553  –  va_count

    Returns the number of quadwords (Alpha only) in the argument
    list.

    Format

      #include  <stdarg.h> (ANSI C)

      #include  <varargs.h> (DEC C Extension)

      void va_count  (int count);

553.1  –  Argument

 count

    An integer variable name in which the number of quadwords
    (Alpha only) is returned.

553.2  –  Description

    The va_count macro places the number of quadwords (Alpha only) in
    the argument list into count. The value returned in count is the
    number of quadwords (Alpha only) in the function argument block
    not counting the count field itself.

    If the argument list contains items whose storage requirements
    are a quadword (Alpha only) of memory or less, the number in
    the count argument is also the number of arguments. However, if
    the argument list contains items that are longer than a quadword
    (Alpha only), count must be interpreted to obtain the number of
    arguments. Because a double is 8 bytes, it occupies one argument-
    list position on OpenVMS Alpha and Integrity server systems.

    The va_count macro is specific to VSI C for OpenVMS Systems
    and is not portable.

554  –  va_end

    Finishes the <varargs.h> or <stdarg.h> session.

    Format

      #include  <stdarg.h> (ANSI C)

      #include  <varargs.h> (DEC C Extension)

      void va_end  (va_list ap);

554.1  –  Argument

 ap

    The object used to traverse the argument list length. You must
    declare and use the argument ap as shown in this format section.

554.2  –  Description

    You can execute multiple traversals of the argument list, each
    delimited by va_start . . . va_end. The va_end function sets ap
    equal to NULL.

    When using this function to write portable applications, include
    the <stdarg.h> header file (defined by the ANSI C standard), not
    the <varargs.h> header file, and use va_end only in conjunction
    with other routines defined in <stdarg.h>.

    For an example of argument-list processing using the <stdarg.h>
    functions and definitions, see the "Character, String, and
    Argument-List Functions" chapter of the VSI C RTL Reference
    Manual.

555  –  va_start[_1]

    Used for initializing a variable to the beginning of the argument
    list.

    Format

      #include  <varargs.h> (DEC C Extension)

      void va_start  (va_list ap);

      void va_start_1  (va_list ap, int offset);

555.1  –  Arguments

 ap

    An object pointer. You must declare and use the argument ap as
    shown in the format section.

 offset

    The number of bytes by which ap is to be incremented so that
    it points to a subsequent argument within the list (that is,
    not to the start of the argument list). Using a nonzero offset
    can initialize ap to the address of the first of the optional
    arguments that follow a number of fixed arguments.

555.2  –  Description

    The va_start macro initializes the variable ap to the beginning
    of the argument list.

    The va_start_1 macro initializes ap to the address of an argument
    that is preceded by a known number of defined arguments. The
    printf function is an example of a C RTL function
    that contains a variable-length argument list offset from the
    beginning of the entire argument list. The variable-length
    argument list is offset by the address of the formatting string.

    When determining the value of the offset argument used in va_
    start_1, the implications of the OpenVMS calling standard must be
    considered.

    On OpenVMS Alpha and Integrity server systems, each argument item
    is a quadword.

                                   NOTE

       When accessing argument lists, especially those passed to a
       subroutine (written in C) by a program written in another
       programming language, consider the implications of the
       OpenVMS calling standard. For more information about the
       OpenVMS calling standard, see the VSI C User's Guide for
       OpenVMS Systems or the VSI OpenVMS Calling Standard.

    The preceding version of va_start and va_start_1 is specific to
    the C RTL, and is not portable.

    The following syntax describes the va_start macro in the
    <stdarg.h> header file, as defined in the ANSI C standard:

    Format

      #include  <stdarg.h> (ANSI C)

      void va_start  (va_list ap, parmN);

555.3  –  Arguments

 ap

    An object pointer. You must declare and use the argument ap as
    shown in the format section.

 parmN

    The name of the last of the known fixed arguments.

555.4  –  Description

    The pointer ap is initialized to point to the first of the
    optional arguments that follow parmN in the argument list.

    Always use this version of va_start in conjunction with functions
    that are declared and defined with function prototypes. Also use
    this version of va_start to write portable programs.

    For an example of argument-list processing using the <stdarg.h>
    functions and definitions, see the "Character, String, and
    Argument-List Functions" chapter of the VSI C RTL Reference
    Manual.

556  –  vfork

    Creates an independent child process. This function is
    nonreentrant.

    Format

      #include  <unistd.h>

      int vfork  (void); (_DECC_V4_SOURCE)

      pid_t vfork  (void); (not _DECC_V4_SOURCE)

556.1  –  Description

    The vfork function provided by VSI C for OpenVMS
    Systems differs from the fork function provided by other C
    implementations. The vfork and fork Functions shows the two major
    differences.

    Table REF-12 The vfork and fork Functions

    The vfork Function    The fork Function

    Used with the exec    Can be used without an exec function for
    functions.            asynchronous processing.
    Creates an            Creates an exact duplicate of the parent
    independent child     process that branches at the point where
    process that shares   vfork is called, as if the parent and the
    some of               child are the same process at different
    the parent's          stages of execution.
    characteristics.

    The vfork function provides the setup necessary for a subsequent
    call to an exec function. Although no process is created by
    vfork, it performs the following steps:

    o  It saves the return address (the address of the vfork call)
       to be used later as the return address for the call to an exec
       function.

    o  It saves the current context.

    o  It returns the integer 0 the first time it is called (before
       the call to an exec function is made). After the corresponding
       exec function call is made, the exec function returns control
       to the parent process, at the point of the vfork call, and
       it returns the process ID of the child as the return value.
       Unless the exec function fails, control appears to return
       twice from vfork even though one call was made to vfork and
       one call was made to the exec function.

    The behavior of the vfork function is similar to the behavior
    of the setjmp function. Both vfork and setjmp establish a return
    address for later use, both return the integer 0 when they are
    first called to set up this address, and both pass back the
    second return value as though it were returned by them rather
    than by their corresponding exec or longjmp function calls.

    However, unlike setjmp, with vfork, all local automatic
    variables, even those with volatile-qualified type, can have
    indeterminate values if they are modified between the call to
    vfork and the corresponding call to an exec routine.

556.2  –  Return Values

    0                  Indicates successful creation of the context.
    nonzero            Indicates the process ID (PID) of the child
                       process.
    -1                 Indicates an error - failure to create the
                       child process.

557  –  vfprintf

    Prints formatted output based on an argument list.

    Format

      #include  <stdio.h>

      int vfprintf  (FILE *file_ptr, const char *format, va_list ap);

557.1  –  Arguments

 file_ptr

    A pointer to the file to which the output is directed.

 format

    A pointer to a string containing the format specification. For
    more information about format and conversion specifications and
    their corresponding arguments, see the "Understanding Input and
    Output" chapter of the VSI C RTL Reference Manual.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

557.2  –  Description

    See also vprintf and vsprintf.

557.3  –  Return Values

    x                  The number of bytes written.
    Negative value     Indicates an output error. The function sets
                       errno. For a list of possible errno values
                       set, see fprintf.

558  –  vfscanf

    Reads formatted input based on an argument list.

    Format

      #include  <stdio.h>

      int vfscanf  (FILE *file_ptr, const char *format, va_list ap);

558.1  –  Arguments

 file_ptr

    A pointer to the file that provides input text.

 format

    A pointer to a string containing the format specification.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

558.2  –  Description

    The vfscanf function is the same as the fscanf function except
    that instead of being called with a variable number of arguments,
    it is called with an argument list that has been initialized by
    va_start (and possibly subsequent va_arg calls).

    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.

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

    This function returns the number of successfully matched and
    assigned input items.

    See also vscanf and vsscanf.

558.3  –  Return Values

    n                  The number of successfully matched and
                       assigned input items.
    EOF                Indicates that the end-of-file was encountered
                       or a read error occurred. If a read error
                       occurs, the function sets errno to one of the
                       following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This can indicate that conversion to a
                          numeric value failed due to overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

559  –  vfwprintf

    Writes output to the stream under control of the wide-character
    format string.

    Format

      #include  <wchar.h>

      int vfwprintf  (FILE *stream, const wchar_t *format, va_list

                     ap);

559.1  –  Arguments

 stream

    A file pointer.

 format

    A pointer to a wide-character string containing the format
    specifications.

 ap

    A variable list of the items needed for output.

559.2  –  Description

    The vfwprintf function is equivalent to the fwprintf function,
    with the variable argument list replaced by the ap argument.
    Initialize ap with the va_start macro (and possibly with
    subsequent va_arg calls) from <stdarg.h>.

    If the stream pointed to by stream has no orientation, vfwprintf
    makes the stream wide-oriented.

    See also fwprintf.

559.3  –  Return Values

    n                  The number of wide characters written.
    Negative value     Indicates an error. The function sets errno to
                       one of the following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This might indicate that conversion to a
                          numeric value failed because of overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

559.4  –  Examples

      The following example shows the use of the vfwprintf function
      in a general error reporting routine:

         #include <stdarg.h>
         #include <stdio.h>
         #include <wchar.h>

         void error(char *function_name, wchar_t *format,  . . . );
         {
            va_list args;

            va_start(args, format);
            /* print out name of function causing error */
            fwprintf(stderr, L"ERROR in %s: ", function_name);
            /* print out remainder of message */
            vfwprintf(stderr, format, args);
            va_end(args);
         }

560  –  vfwscanf

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

    Format

      #include  <wchar.h>

      int vfwscanf  (FILE *stream, const wchar_t *format, va_list

                    ap);

560.1  –  Arguments

 stream

    A file pointer.

 format

    A pointer to a wide-character string containing the format
    specifications.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

560.2  –  Description

    The vfwscanf function is equivalent to the fwscanf function,
    except that instead of being called with a variable number of
    arguments, it is called with an argument list (ap) that has been
    initialized by va_start (and possibly with subsequent va_arg
    calls).

    If the stream pointed to by stream has no orientation, vfwscanf
    makes the stream wide-oriented.

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

560.3  –  Return Values

    n                  The number of successfully matched and
                       assigned wide-character 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
                       vfscanf.

561  –  vprintf

    Prints formatted output based on an argument list.

    This function is the same as the printf function except that
    instead of being called with a variable number of arguments, it
    is called with an argument list that has been initialized by the
    va_start macro (and possibly with subsequent va_arg calls) from
    <stdarg.h>.

    Format

      #include  <stdio.h>

      int vprintf  (const char *format, va_list ap);

561.1  –  Arguments

 format

    A pointer to the string containing the format specification.

 ap

    A variable list of the items needed for output.

561.2  –  Description

    See the vfprintf and vsprintf functions.

561.3  –  Return Values

    x                  The number of bytes written.
    Negative value     Indicates an output error. The function sets
                       errno. For a list of possible errno values
                       set, see fprintf.

562  –  vscanf

    Reads formatted input based on an argument list.

    Format

      #include  <stdio.h>

      int vscanf  (const char *format, va_list ap);

562.1  –  Arguments

 format

    A pointer to the string containing the format specification.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

562.2  –  Description

    The vscanf function is the same as the scanf function except that
    instead of being called with a variable number of arguments, it
    is called with an argument list (ap) that has been initialized by
    the va_start macro (and possibly with subsequent va_arg calls).

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

    See also scanf, vfscanf, and vsscanf.

562.3  –  Return Values

    n                  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
                       vfscanf.

563  –  vsnprintf

    Prints formatted output based on an argument list.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <stdio.h>

      int vsnprintf  (char *str, size_t n, const char *format,
                     va_list ap);

563.1  –  Arguments

 str

    A pointer to a string that will receive the formatted output.

 format

    A pointer to a character string that contains the format
    specification.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

563.2  –  Description

    The vsnprintf function is the same as the snprintf function, but
    instead of being called with a variable number of arguments, it
    is called with an argument list that has been initialized by va_
    start (and possibly with subsequent va_arg calls).

    This function does not invoke the va_end macro. Because the
    function invokes the va_arg macro, the value of ap after the
    return is unspecified.

    Applications using vsnprintf should call va_end(ap) afterwards to
    clean up.

563.3  –  Return Values

    x                  The number of bytes (excluding the terminating
                       null byte) that would be written to str if n
                       is sufficiently large.
    Negative value     Indicates an output error occurred. The
                       function sets errno. For a list of possible
                       errno values set, see fprintf.

564  –  vsprintf

    Prints formatted output based on an argument list.

    This function is the same as the sprintf function except that
    instead of being called with a variable number of arguments, it
    is called with an argument list that has been initialized by va_
    start (and possibly with subsequent va_arg calls).

    Format

      #include  <stdio.h>

      int vsprintf  (char *str, const char *format, va_list ap);

564.1  –  Arguments

 str

    A pointer to a string that will receive the formatted output.
    This string is assumed to be large enough to hold the output.

 format

    A pointer to a character string that contains the format
    specification.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

564.2  –  Return Value

    x                  The number of bytes written.
    Negative value     Indicates an output error occurred. The
                       function sets errno. For a list of possible
                       errno values set, see fprintf.

565  –  vsscanf

    Reads formatted input based on an argument list.

    Format

      #include  <stdio.h>

      int vsscanf  (char *str, const char *format, va_list ap);

565.1  –  Arguments

 str

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

 format

    A pointer to a character string that contains the format
    specification.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

565.2  –  Description

    The vsscanf function is the same as the sscanf function except
    that instead of being called with a variable number of arguments,
    it is called with an argument list that has been initialized by
    va_start (and possibly with subsequent va_arg calls).

    The vsscanf function is also equivalent to the vfscanf 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 vfscanf function.

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

    See also vsscanf and sscanf.

565.3  –  Return Values

    n                  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
                       vfscanf.

566  –  vswprintf

    Writes output to the stream under control of the wide-character
    format string.

    Format

      #include  <wchar.h>

      int vswprintf  (wchar_t *s, size_t n, const wchar_t *format,
                     va_list ap);

566.1  –  Arguments

 s

    A pointer to a multibyte character sequence.

 n

    The maximum number of bytes that comprise the multibyte
    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 the
    "Understanding Input and Output" chapter of the VSI C RTL
    Reference Manual.

 ap

    A variable list of the items needed for output.

566.2  –  Description

    The vswprintf function is equivalent to the swprintf function,
    with the variable argument list replaced by the ap argument.
    Initialize ap with the va_start macro, and possibly with
    subsequent va_arg calls.

    See also swprintf.

566.3  –  Return Values

    n                  The number of wide characters written.
    Negative value     Indicates an error. The function sets errno to
                       one of the following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This might indicate that conversion to a
                          numeric value failed because of overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

567  –  vswscanf

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

    Format

      #include  <wchar.h>

      int vswscanf  (wchar_t *s, const wchar_t *format, va_list ap);

567.1  –  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.

 ap

    A list of expressions whose results correspond to conversion
    specifications given in the format specification.

567.2  –  Description

    The vswscanf function is equivalent to the swscanf function,
    except that instead of being called with a variable number of
    arguments, it is called with an argument list (ap) that has been
    initialized by va_start (and possibly with subsequent va_arg
    calls).

    The vswscanf function is also equivalent to the vfwscanf
    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
    vfwscanf function.

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

    See also vfwscanf and swscanf.

567.3  –  Return Values

    n                  The number of wide characters read.
    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
                       vfscanf.

568  –  vwprintf

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

    Format

      #include  <wchar.h>

      int vwprintf  (const wchar_t *format, va_list ap);

568.1  –  Arguments

 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 the
    "Understanding Input and Output" chapter of the VSI C RTL
    Reference Manual.

 ap

    The variable list of items needed for output.

568.2  –  Description

    The vwprintf function is equivalent to the wprintf function,
    with the variable argument list replaced by the ap argument.
    Initialize ap with the va_start macro, and possibly with
    subsequent va_arg calls. The vwprintf function does not invoke
    the va_end macro.

    See also wprintf.

568.3  –  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.

569  –  vwscanf

    Reads input from an array of wide characters under control of a
    wide-character format string.

    Format

      #include  <wchar.h>

      int vwscanf  (const wchar_t *format, va_list ap);

569.1  –  Arguments

 format

    A pointer to a wide-character string containing the format
    specifications.

 ap

    A list of expressions whose resultant types correspond to the
    conversion specifications given in the format specifications.

569.2  –  Description

    The vwscanf function is equivalent to the wscanf function, except
    that instead of being called with a variable number of arguments,
    it is called with an argument list (ap) that has been initialized
    by va_start (and possibly with subsequent va_arg calls).

    For more information about format and conversion specifications
    and their corresponding arguments, see the "Understanding Input
    and Output" chapter of the VSI C RTL Reference Manual.

    See also wscanf.

569.3  –  Return Values

    n                  The number of wide characters read.
    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
                       vfscanf.

570  –  wait

    Checks the status of the child process before exiting. A child
    process is terminated when the parent process terminates.

    Format

      #include  <wait.h>

      pid_t wait  (int *status);

570.1  –  Argument

 status

    The address of a location to receive the final status of the
    terminated child. The child can set the status with the exit
    function and the parent can retrieve this value by specifying
    status.

570.2  –  Description

    The wait function suspends the parent process until the final
    status of a terminated child is returned from the child.

    On OpenVMS Version 7.0 and higher systems, the wait function is
    equivalent to waitpid( 0, status, 0 ) if you include <wait.h> and
    compile with the _POSIX_EXIT feature-test macro set (either with
    /DEFINE=_POSIX_EXIT or with #define _POSIX_EXIT at the top of
    your file, before any file inclusions).

570.3  –  Return Values

    x                  The process ID (PID) of the terminated child.
                       If more than one child process was created,
                       wait will return the PID of the terminated
                       child that was most recently created.
                       Subsequent calls will return the PID of the
                       next most recently created, but terminated,
                       child.
    -1                 No child process was spawned.

571  –  wait3

    Waits for a child process to stop or terminate.

    Format

      #include  <wait.h>

      pid_t wait3  (int *status_location, int options, struct rusage
                   *resource_usage);

571.1  –  Arguments

 status_location

    A pointer to a location that contains the termination status of
    the child process as defined in the <wait.h> header file.

    Beginning with OpenVMS Version 7.2, when compiled with the _
    VMS_WAIT macro defined, the wait3 function puts the OpenVMS
    completion code of the child process at the address specified
    in the status_location argument.

 options

    Flags that modify the behavior of the function. These flags are
    defined in the Description section.

 resource_usage

    The location of a structure that contains the resource
    utilization information for terminated child processes.

571.2  –  Description

    The wait3 function suspends the calling process until the request
    is completed, and redefines it so that only the calling thread is
    suspended.

    The options argument modifies the behavior of the function. You
    can combine the flags for the options argument by specifying
    their bitwise inclusive OR. The flags are:

    WNOWAIT        Specifies that the process whose status is
                   returned in status_location is kept in a waitable
                   state. You can wait for the process again with the
                   same results.
    WNOHANG        Prevents the suspension of the calling process.
                   If there are child processes that stopped or
                   terminated, one is chosen and the waitpid function
                   returns its process ID, as when you do not specify
                   the WNOHANG flag. If there are no terminated
                   processes (that is, if waitpid suspends the
                   calling process without the WNOHANG flag), 0
                   (zero) is returned. Because you can never wait
                   for process 0, there is no confusion arising from
                   this return.
    WUNTRACED      Specifies that the call return additional
                   information when the child processes of the
                   current process stop because the child process
                   received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP
                   signal.

    If the wait3 function returns because the status of a child
    process is available, the process ID of the child process is
    returned. Information is stored in the location pointed to by
    status_location, if this pointer is not null.

    The value stored in the location pointed to by status_location is
    0 (zero) only if the status is returned from a terminated child
    process that did one of the following:

    o  Returned 0 from the main function.

    o  Passed 0 as the status argument to the _exit or exit function.

    Regardless of the status_location value, you can define this
    information using the macros defined in the <wait.h> header file,
    which evaluate to integral expressions. In the following macro
    descriptions, the status_value argument is equal to the integer
    value pointed to by the status_location argument:

    WIFEXITED(status_  Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       normally.
    WEXITSTATUS(status_If the value of WIFEXITED(status_value) is
    value)             nonzero, this macro evaluates to the low-order
                       8 bits of the status argument that the child
                       process passed to the _exit or exit function,
                       or to the value the child process returned
                       from the main function.
    WIFSIGNALED(status_Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       due to the receipt of a signal that was not
                       intercepted.
    WTERMSIG(status_   If the value of WIFSIGNALED(status_value) is
    value)             nonzero, this macro evaluates to the number of
                       the signal that caused the termination of the
                       child process.
    WIFSTOPPED(status_ Evaluates to a nonzero value if status was
    value)             returned for a child process that is currently
                       stopped.
    WSTOPSIG(status_   If the value of WIFSTOPPED(status_value) is
    value)             nonzero, this macro evaluates to the number
                       of the signal that caused the child process to
                       stop.
    WIFCONTINUED(status_valuates to a nonzero value if status
    value)             was returned for a child process that has
                       continued.

    If the information stored at the location pointed to by status_
    location was stored there by a call to wait3 that specified
    the WUNTRACED flag, one of the following macros evaluates to a
    nonzero value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    o  WIFSTOPPED(*status_value)

    o  WIFCONTINUED(*status_value)

    If the information stored in the location pointed to by status_
    location resulted from a call to wait3 without the WUNTRACED flag
    specified, one of the following macros evaluates to a nonzero
    value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    The wait3 function provides compatibility with BSD systems.
    The resource_usage argument points to a location that contains
    resource usage information for the child processes as defined in
    the <resource.h> header file.

    If a parent process terminates without waiting for all of its
    child processes to terminate, the remaining child processes is
    assigned a parent process ID equal to the process ID of the init
    process.

    See also exit, -exit, and init.

571.3  –  Return Values

    0                  Indicates success. There are no stopped or
                       exited child processes, the WNOHANG option is
                       specified.
    x                  The process_id of the child process. The
                       status of a child process is available.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  ECHILD - There are no child processes to
                          wait for.

                       o  EINTR - Terminated by receipt of a signal
                          intercepted by the calling process.

                       o  EFAULT - The status_location or resource_
                          usage argument points to a location outside
                          of the address space of the process.

                       o  EINVAL- The value of the options argument
                          is not valid.

572  –  wait4

    Waits for a child process to stop or terminate.

    Format

      #include  <wait.h>

      pid_t wait4   (pid_t process_id, union wait *status_location,
                    int options, struct rusage *resource_usage);

572.1  –  Arguments

 status_location

    A pointer to a location that contains the termination status of
    the child process as defined in the <wait.h> header file.

    Beginning with OpenVMS Version 7.2, when compiled with the _
    VMS_WAIT macro defined, the wait4 function puts the OpenVMS
    completion code of the child process at the address specified
    in the status_location argument.

 process_id

    The child process or set of child processes.

 options

    Flags that modify the behavior of the function. These flags are
    defined in the Description section.

 resource_usage

    The location of a structure that contains the resource
    utilization information for terminated child processes.

572.2  –  Description

    The wait4 function suspends the calling process until the request
    is completed.

    The process_id argument allows the calling process to gather
    status from a specific set of child processes, according to the
    following rules:

    If the
    process_
    id is          Then status is requested

    Equal to -1    For any child process. In this respect, the
                   waitpid function is equivalent to the wait
                   function.
    Greater than   For a single child process and specifies the
    0              process ID.

    The wait4 function only returns the status of a child process
    from this set.

    The options argument to the wait4 function modifies the behavior
    of the function. You can combine the flags for the options
    argument by specifying their bitwise-inclusive OR. The flags
    are:

    WNOWAIT        Specifies that the process whose status is
                   returned in status_location is kept in a waitable
                   state. You can wait for the process again with the
                   same results.
    WNOHANG        Prevents the suspension of the calling process.
                   If there are child processes that stopped or
                   terminated, one is chosen and the waitpid function
                   returns its process ID, as when you do not specify
                   the WNOHANG flag. If there are no terminated
                   processes (that is, if waitpid suspends the
                   calling process without the WNOHANG flag), 0 is
                   returned. Because you can never wait for process
                   0, there is no confusion arising from this return.
    WUNTRACED      Specifies that the call return additional
                   information when the child processes of the
                   current process stop because the child process
                   received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP
                   signal.

    If the wait4 function returns because the status of a child
    process is available, the process ID of the child process is
    returned. Information is stored in the location pointed to by
    status_location, if this pointer is not null.

    The value stored in the location pointed to by status_location is
    0 only if the status is returned from a terminated child process
    that did one of the following:

    o  Returned 0 from the main function.

    o  Passed 0 as the status argument to the _exit or exit function.

    Regardless of the status_location value, you can define this
    information using the macros defined in the <wait.h> header file,
    which evaluate to integral expressions. In the following macro
    descriptions, status_value is equal to the integer value pointed
    to by status_location:

    WIFEXITED(status_  Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       normally.
    WEXITSTATUS(status_If the value of WIFEXITED(status_value) is
    value)             nonzero, this macro evaluates to the low-order
                       8 bits of the status argument that the child
                       process passed to the _exit or exit function,
                       or to the value the child process returned
                       from the main function.
    WIFSIGNALED(status_Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       due to the receipt of a signal that was not
                       intercepted.
    WTERMSIG(status_   If the value of WIFSIGNALED(status_value) is
    value)             nonzero, this macro evaluates to the number of
                       the signal that caused the termination of the
                       child process.
    WIFSTOPPED(status_ Evaluates to a nonzero value if status was
    value)             returned for a child process that is currently
                       stopped.
    WSTOPSIG(status_   If the value of WIFSTOPPED(status_value) is
    value)             nonzero, this macro evaluates to the number
                       of the signal that caused the child process to
                       stop.
    WIFCONTINUED(status_valuates to a nonzero value if status
    value)             was returned for a child process that has
                       continued.

    If the information stored at the location pointed to by status_
    location was stored there by a call to wait4 that specified
    the WUNTRACED flag, one of the following macros evaluates to a
    nonzero value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    o  WIFSTOPPED(*status_value)

    o  WIFCONTINUED(*status_value)

    If the information stored in the location pointed to by status_
    location resulted from a call to wait4 without the WUNTRACED flag
    specified, one of the following macros evaluates to a nonzero
    value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    The wait4 function is similar to the wait3 function. However,
    the wait4 function waits for a specific child as indicated by
    the process_id argument. The resource_usage argument points to a
    location that contains resource usage information for the child
    processes as defined in the <resource.h> header file.

    See also exit and _exit.

572.3  –  Return Values

    0                  Indicates success. There are no stopped or
                       exited child processes, the WNOHANG option is
                       specified.
    x                  The process_id of the child process. The
                       status of a child process is available.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  ECHILD - There are no child processes to
                          wait for.

                       o  EINTR - Terminated by receipt of a signal
                          intercepted by the calling process.

                       o  EFAULT - The status_location or resource_
                          usage argument points to a location outside
                          of the address space of the process.

                       o  EINVAL- The value of the options argument
                          is not valid.

573  –  waitpid

    Waits for a child process to stop or terminate.

    Format

      #include  <wait.h>

      pid_t waitpid  (pid_t process_id, int *status_location, int options);

573.1  –  Arguments

 process_id

    The child process or set of child processes.

 status_location

    A pointer to a location that contains the termination status of
    the child process as defined in the <wait.h> header file.

    Beginning with OpenVMS Version 7.2, when compiled with the _
    VMS_WAIT macro defined, the waitpid function puts the OpenVMS
    completion code of the child process at the address specified in
    the status_location argument.

 options

    Flags that modify the behavior of the function. These flags are
    defined in the Description section.

573.2  –  Description

    The waitpid function suspends the calling process until the
    request is completed. It is redefined so that only the calling
    thread is suspended.

    If the process_id argument is -1 and the options argument is
    0, the waitpid function behaves the same as the wait function.
    If these arguments have other values, the waitpid function is
    changed as specified by those values.

    The process_id argument allows the calling process to gather
    status from a specific set of child processes, according to the
    following rules:

    If the
    process_
    id is          Then status is requested

    Equal to -1    For any child process. In this respect, the
                   waitpid function is equivalent to the wait
                   function.
    Greater than   For a single child process and specifies the
    0              process ID.

    The waitpid function only returns the status of a child process
    from this set.

    The options argument to the waitpid function modifies the
    behavior of the function. You can combine the flags for the
    options argument by specifying their bitwise-inclusive OR. The
    flags are:

    WCONTINUED     Specifies that the following is reported to the
                   calling process: the status of any continued child
                   process specified by the process_id argument whose
                   status is unreported since it continued.
    WNOWAIT        Specifies that the process whose status is
                   returned in status_location is kept in a waitable
                   state. You can wait for the process again with the
                   same results.
    WNOHANG        Prevents the calling process from being suspended.
                   If there are child processes that stopped or
                   terminated, one is chosen and waitpid returns its
                   PID, as when you do not specify the WNOHANG flag.
                   If there are no terminated processes (that is,
                   if waitpid suspends the calling process without
                   the WNOHANG flag), 0 (zero) is returned. Because
                   you can never wait for process 0, there is no
                   confusion arising from this return.
    WUNTRACED      Specifies that the call return additional
                   information when the child processes of the
                   current process stop because the child process
                   received a SIGTTIN, SIGTTOU, SIGSTOP, or SIGTSTOP
                   signal.

    If the waitpid function returns because the status of a child
    process is available, the process ID of the child process is
    returned. Information is stored in the location pointed to by
    status_location, if this pointer is not null. The value stored
    in the location pointed to by status_location is 0 only if the
    status is returned from a terminated child process that did one
    of the following:

    o  Returned 0 from the main function.

    o  Passed 0 as the status argument to the _exit or exit function.

    Regardless of the value of status_location, you can define this
    information using the macros defined in the <wait.h> header file,
    which evaluate to integral expressions. In the following function
    descriptions, status_value is equal to the integer value pointed
    to by status_location:

    WIFEXITED(status_  Evaluates to a nonzero value if status was
    value)             returned for a child process that terminated
                       normally.
    WEXITSTATUS(status_If the value of WIFEXITED(status_value) is
    value)             nonzero, this macro evaluates to the low-order
                       8 bits of the status argument that the child
                       process passed to the _exit or exit function,
                       or to the value the child process returned
                       from the main function.
    WIFSIGNALED(status_Evaluates to a nonzero value if status
    value)             returned for a child process that terminated
                       due to the receipt of a signal not
                       intercepted.
    WTERMSIG(status_   If the value of WIFSIGNALED(status_value) is
    value)             nonzero, this macro evaluates to the number of
                       the signal that caused the termination of the
                       child process.
    WIFSTOPPED(status_ Evaluates to a nonzero value if status was
    value)             returned for a child process that is currently
                       stopped.
    WSTOPSIG(status_   If the value of WIFSTOPPED(status_value) is
    value)             nonzero, this macro evaluates to the number
                       of the signal that caused the child process to
                       stop.
    WIFCONTINUED(status_valuates to a nonzero value if status
    value)             returned for a child process that continued.

    If the information stored at the location pointed to by status_
    location is stored there by a call to waitpid that specified
    the WUNTRACED flag, one of the following macros evaluates to a
    nonzero value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    o  WIFSTOPPED(*status_value)

    o  WIFCONTINUED(*status_value)

    If the information stored in the buffer pointed to by status_
    location resulted from a call to waitpid without the WUNTRACED
    flag specified, one of the following macros evaluates to a
    nonzero value:

    o  WIFEXITED(*status_value)

    o  WIFSIGNALED(*status_value)

    If a parent process terminates without waiting for all of its
    child processes to terminate, the remaining child processes is
    assigned a parent process ID equal to the process ID of the init
    process.

    See also exit, _exit, and wait.

573.3  –  Return Values

    0                  Indicates success. If the WNOHANG option was
                       specified, and there are no stopped or exited
                       child processes, the waitpid function also
                       returns a value of 0.
    -1                 Indicates an error; errno is set to one of the
                       following values:

                       o  ECHILD-The calling process has no existing
                          unwaited-for child processes. The process
                          or process group ID specified by the
                          process_id argument does not exist or is
                          not a child process of the calling process.

                       o  EINTR-The function was terminated by
                          receipt of a signal.

                          If the waitpid function returns because
                          the status of a child process is available,
                          the process ID of the child is returned to
                          the calling process. If they return because
                          a signal was intercepted by the calling
                          process, -1 is returned.

                       o  EFAULT- The status_location argument points
                          to a location outside of the address space
                          of the process.

                       o  EINVAL- The value of the options argument
                          is not valid.

574  –  wcrtomb

    Converts the wide character to its multibyte character
    representation.

    Format

      #include  <wchar.h>

      size_t wcrtomb  (char *s, wchar_t wc, mbstate_t *ps);

574.1  –  Arguments

 s

    A pointer to the resulting multibyte character.

 wc

    A wide character.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

574.2  –  Description

    If s is a NULL pointer, the wcrtomb function is equivalent to the
    call:

       wcrtomb (buf, L'\0', ps)

    where buf is an internal buffer.

    If s is not a NULL pointer, the wcrtomb function determines the
    number of bytes needed to represent the multibyte character that
    corresponds to the wide character specified by wc (including any
    shift sequences), and stores the resulting bytes in the array
    whose first element is pointed to by s. At most MB_CUR_MAX bytes
    are stored.

    If wc is a null wide character, a null byte is stored preceded by
    any shift sequence needed to restore the initial shift state. The
    resulting state described is the initial conversion state.

574.3  –  Return Values

    n                  The number of bytes stored in the resulting
                       array, including any shift sequences to
                       represent the multibyte character.
    -1                 Indicates an encoding error. The wc argument
                       is not a valid wide character. The global
                       errno is set to EILSEQ; the conversion state
                       is undefined.

575  –  wcscat

    Concatenates two wide-character strings.

    Format

      #include  <wchar.h>

      wchar_t *wcscat  (wchar_t *wstr_1, const wchar_t *wstr_2);

575.1  –  Function Variants

    The wcscat function has variants named _wcscat32 and _wcscat64
    for use with 32-bit and 64-bit pointer sizes, respectively.

575.2  –  Arguments

 wstr_1, wstr_2

    Pointers to null-terminated wide-character strings.

575.3  –  Description

    The wcscat function appends the wide-character string wstr_2,
    including the terminating null character, to the end of wstr_1.

    See also wcsncat.

575.4  –  Return Value

    x                  The first argument, wstr_1, which is assumed
                       to be large enough to hold the concatenated
                       result.

575.5  –  Example

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

        /* This program concatenates two wide-
 character strings using */
        /* the wcscat function, and then manually compares the result */
        /* to the expected result                                     */

        #define S1LENGTH 10
        #define S2LENGTH 8

        main()
        {
            int i;
            wchar_t s1buf[S1LENGTH + S2LENGTH];
            wchar_t s2buf[S2LENGTH];
            wchar_t test1[S1LENGTH + S2LENGTH];

            /* Initialize the three wide-character strings */

            if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH + S2LENGTH)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

        /* Concatenate s1buf with s2buf, placing the result    */
        /* into * s1buf.  Then compare s1buf with the expected */
        /* result in test1.                                    */

            wcscat(s1buf, s2buf);

            for (i = 0; i < S1LENGTH + S2LENGTH - 2; i++) {
                /* Check that each character is correct */
                if (test1[i] != s1buf[i]) {
                    printf("Error in wcscat\n");
                    exit(EXIT_FAILURE);
                }
            }

            printf("Concatenated string: <%S>\n", s1buf);
        }

      Running the example produces the following result:

        Concatenated string: <abcmnexyz orthis>

576  –  wcschr

    Scans for a wide character in a specified wide-character string.

    Format

      #include  <wchar.h>

      wchar_t *wcschr  (const wchar_t *wstr, wchar_t wc);

576.1  –  Function Variants

    The wcschr function has variants named _wcschr32 and _wcschr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

576.2  –  Arguments

 wstr

    A pointer to a null-terminated wide-character string.

 wc

    A character of type wchar_t.

576.3  –  Description

    The wcschr function returns the address of the first occurrence
    of a specified wide character in a null-terminated wide-character
    string. The terminating null character is considered to be part
    of the string.

    See also wcsrchr.

576.4  –  Return Values

    x                  The address of the first occurrence of the
                       specified wide character.
    NULL               Indicates that the wide character does not
                       occur in the string.

576.5  –  Example

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

        #define BUFF_SIZE 50

        main()
        {
            int i;
            wchar_t s1buf[BUFF_SIZE];
            wchar_t *status;

            /* Initialize the buffer */

            if (mbstowcs(s1buf, "abcdefghijkl lkjihgfedcba", BUFF_SIZE)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

         /* This program checks the wcschr function by incrementally */
         /* going through a string that ascends to the middle and    */
         /* then descends towards the end.                           */

            for (i = 0; (s1buf[i] != '\0') && (s1buf[i] != ' '); i++) {
                status = wcschr(s1buf, s1buf[i]);
                /* Check for pointer to leftmost character -test 1. */
                if (status != &s1buf[i]) {
                    printf("Error in wcschr\n");
                    exit(EXIT_FAILURE);
                }
            }

            printf("Program completed successfully\n");
        }

      When this example program is run, it produces the following
      result:

        Program completed successfully

577  –  wcscmp

    Compares two wide-character strings. It returns an integer that
    indicates if the strings are different, and how they differ.

    Format

      #include  <wchar.h>

      int wcscmp  (const wchar_t *wstr_1, const wchar_t *wstr_2);

577.1  –  Arguments

 wstr_1, wstr_2

    Pointers to null-terminated wide-character strings.

577.2  –  Description

    The wcscmp function compares the wide characters in wstr_1 with
    those in wstr_2. If the characters differ, the function returns:

    o  An integer less than 0, if the codepoint of the first
       differing character in wstr_1 is less than the codepoint of
       the corresponding character in wstr_2

    o  An integer greater than 0, if the codepoint of the first
       differing character in wstr_1 is greater than the codepoint
       of the corresponding character in wstr_2

    If the wide-characters strings are identical, the function
    returns 0.

    Unlike the wcscoll function, the wcscmp function compares the
    string based on the binary value of each wide character.

    See also wcsncmp.

577.3  –  Return Values

    < 0                Indicates that wstr_1 is less than wstr_2.
    > 0                Indicates that wstr_1 is greater than wstr_2.

578  –  wcscoll

    Compares two wide-character strings and returns an integer
    that indicates if the strings differ, and how they differ.
    The function uses the collating information in the LC_COLLATE
    category of the current locale to determine how the comparison is
    performed.

    Format

      #include  <wchar.h>

      int wcscoll  (const wchar_t *ws1, const wchar_t *ws2);

578.1  –  Arguments

 ws1, ws2

    Pointers to wide-character strings.

578.2  –  Description

    The wcscoll function, unlike wcscmp, compares two strings in a
    locale-dependent manner. Because no value is reserved for error
    indication, the application must check for one by setting errno
    to 0 before the function call and testing it after the call.

    See also wcsxfrm.

578.3  –  Return Values

    < 0                Indicates that ws1 is less than ws2.
    0                  Indicates that the strings are equal.
    > 0                Indicates that ws1 is greater than ws2.

579  –  wcscpy

    Copies the wide-character string source, including the
    terminating null character, into dest.

    Format

      #include  <wchar.h>

      wchar_t *wcscpy  (wchar_t *dest, const wchar_t *source);

579.1  –  Function Variants

    The wcscpy function has variants named _wcscpy32 and _wcscpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

579.2  –  Arguments

 dest

    Pointer to the null-terminated wide-character destination string.

 source

    Pointer to the null-terminated wide-character source string.

579.3  –  Description

    The wcscpy function copies source into dest, and stops after
    copying source's null character. If copying takes place between
    two overlapping strings, the behavior is undefined.

    See also wcsncpy.

579.4  –  Return Value

    x                  The address of source.

580  –  wcscspn

    Compares the characters in a wide-character string against a
    set of wide characters. The function returns the length of the
    initial substring that is comprised entirely of characters that
    are not in the set of wide characters.

    Format

      #include  <wchar.h>

      size_t wcscspn  (const wchar_t *wstr1, const wchar_t *wstr2);

580.1  –  Arguments

 wstr1

    A pointer to a null-terminated wide-character string. If this is
    a null string, 0 is returned.

 wstr2

    A pointer to a null-terminated wide-character string that
    contains the set of wide characters for which the function will
    search.

580.2  –  Description

    The wcscspn function scans the wide characters in the string
    pointed to by wstr1 until it encounters a character found in
    wstr2. The function returns the length of the initial segment of
    wstr1 that is formed by characters not found in wstr2.

580.3  –  Return Value

    x                  The length of the segment.

580.4  –  Example

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

        /* This test sets up 2 strings, buffer and w_string, and */
        /* then uses wcscspn() to calculate the maximum segment  */
        /* of w_string, which consists entirely of characters    */
        /* NOT from buffer.                                      */

        #define BUFF_SIZE 20
        #define STRING_SIZE 50

        main()
        {
            wchar_t buffer[BUFF_SIZE];
            wchar_t w_string[STRING_SIZE];
            size_t result;

            /* Initialize the buffer */

            if (mbstowcs(buffer, "abcdefg", BUFF_SIZE) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            /* Initialize the string */

            if (mbstowcs(w_string, "jklmabcjklabcdehjklmno", STRING_SIZE)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

        /* Using wcscspn - work out the largest string in w_string */
        /* which consists entirely of characters NOT from buffer   */

            result = wcscspn(w_string, buffer);
            printf("Longest segment NOT found in w_string is: %d", result);

        }

    Running the example program produces the following result:

    Longest segment NOT found in w_string is: 4

581  –  wcsftime

    Uses date and time information stored in a tm structure to create
    a wide-character output string. The format of the output string
    is controlled by a format string.

    Format

      #include  <wchar.h>

      size_t wcsftime  (wchar_t *wcs, size_t maxsize, const char
                       *format, const struct tm *timeptr); (XPG4)

      size_t wcsftime  (wchar_t *wcs, size_t maxsize, const wchar_t
                       *format, const struct tm *timeptr); (ISO C)

581.1  –  Function Variants

    Compiling with the _DECC_V4_SOURCE and _VMS_V6_SOURCE feature-
    test macros defined enables a local-time-based entry point to
    the wcsftime function that is equivalent to the behavior before
    OpenVMS Version 7.0.

581.2  –  Arguments

 wcs

    A pointer to the resultant wide-character string.

 maxsize

    The maximum number of wide characters to be stored in the
    resultant string.

 format

    A pointer to the string that controls the format of the output
    string. For the XPG4 interface, this argument is a pointer to
    a constant character string. For the ISO C interface, it is a
    pointer to a constant wide-character string.

 timeptr

    A pointer to the local time structure. The tm structure is
    defined in the <time.h> header file.

581.3  –  Description

    The wcsftime function uses data in the structure pointed to by
    timeptr to create the wide-character string pointed to by wcs. A
    maximum of maxsize wide characters is copied to wcs.

    The format string consists of zero or more conversion
    specifications and ordinary characters. All ordinary characters
    (including the terminating null character) are copied unchanged
    into the output string. A conversion specification defines how
    data in the tm structure is formatted in the output string.

    A conversion specification consists of a percent (%) character
    followed by one or more optional characters (see Optional
    Elements of wcsftime Conversion Specifications), and ending with
    a conversion specifier (see wcsftime Conversion Specifiers).
    If any of the optional characters listed in Optional Elements
    of wcsftime Conversion Specifications are specified, they must
    appear in the order shown in the table.

    Table REF-13 Optional Elements of wcsftime Conversion
                 Specifications

    Element    Meaning

    -          Optional with the field width to specify that the field
               is left-justified and padded with spaces. This cannot
               be used with the 0 element.
    0          Optional with the field width to specify that the field
               is right-justified and padded with zeros. This cannot
               be used with the - element.
    field      A decimal integer that specifies the maximum field
    width      width
    .precision A decimal integer that specifies the precision of data
               in a field.

               For the d, H, I, j, m, M, o, S, U, w, W, y, and Y
               conversion specifiers, the precision specifier is the
               minimum number of digits to appear in the field. If
               the conversion specification has fewer digits than that
               specified by the precision, leading zeros are added.

               For the a, A, b, B, c, D, E, h, n, N, p, r, t, T,
               x, X, Z, and % conversion specifiers, the precision
               specifier is the maximum number of wide characters to
               appear in the field. If the conversion specification
               has more characters than that specified by the
               precision, characters are truncated on the right.

               The default precision for the d, H, I, m, M, o, S,
               U, w, W, y, and Y conversion specifiers is 2, and the
               default precision for the j conversion specifier is 3.

    Note that the list of optional elements of conversion
    specifications from Optional Elements of wcsftime Conversion
    Specifications are VSI extensions to the XPG4 specification.

    wcsftime Conversion Specifiers lists the conversion specifiers.
    The wcsftime function uses fields in the LC_TIME category of
    the program's current locale to provide a value. For example, if
    %B is specified, the function accesses the mon field in LC_TIME
    to find the full month name for the month specified in the tm
    structure. The result of using invalid conversion specifiers is
    undefined.

    Table REF-14 wcsftime Conversion Specifiers

    SpecifierReplaced by

    a        The locale's abbreviated weekday name.
    A        The locale's full weekday name.
    b        The locale's abbreviated month name.
    B        The locale's full month name.
    c        The locale's appropriate date and time representation.
    C        The century number (the year divided by 100 and
             truncated to an integer) as a decimal number (00 - 99).
    d        The day of the month as a decimal number (01 - 31).
    D        Same as %m/%d/%y.
    e        The day of the month as a decimal number (1 - 31) in a
             2-digit field with the leading space character fill.
    Ec       The locale's alternative date and time representation.
    EC       The name of the base year (period) in the locale's
             alternative representation.
    Ex       The locale's alternative date representation.
    Ey       The offset from the base year (%EC) in the locale's
             alternative representation.
    EY       The locale's full alternative year representation.
    h        Same as %b.
    H        The hour (24-hour clock) as a decimal number (00 - 23).
    I        The hour (12-hour clock) as a decimal number (01 - 12).
    j        The day of the year as a decimal number (001 - 366).
    m        The month as a decimal number (01 - 12).
    M        The minute as a decimal number (00 - 59).
    n        The new-line character.
    Od       The day of the month using the locale's alternative
             numeric symbols.
    Oe       The date of the month using the locale's alternative
             numeric symbols.
    OH       The hour (24-hour clock) using the locale's alternative
             numeric symbols.
    OI       The hour (12-hour clock) using the locale's alternative
             numeric symbols.
    Om       The month using the locale's alternative numeric
             symbols.
    OM       The minutes using the locale's alternative numeric
             symbols.
    OS       The seconds using the locale's alternative numeric
             symbols.
    Ou       The weekday as a number in the locale's alternative
             representation (Monday=1).
    OU       The week number of the year (Sunday as the first day
             of the week) using the locale's alternative numeric
             symbols.
    OV       The week number of the year (Monday as the first day
             of the week) as a decimal number (01 -53) using the
             locale's alternative numeric symbols. If the week
             containing January 1 has four or more days in the new
             year, it is considered as week 1. Otherwise, it is
             considered as week 53 of the previous year, and the
             next week is week 1.
    Ow       The weekday as a number (Sunday=0) using the locale's
             alternative numeric symbols.
    OW       The week number of the year (Monday as the first day
             of the week) using the locale's alternative numeric
             symbols.
    Oy       The year without the century using the locale's
             alternative numeric symbols.
    p        The locale's equivalent of the AM/PM designations
             associated with a 12-hour clock.
    r        The time in AM/PM notation.
    R        The time in 24-hour notation (%H:%M).
    S        The second as a decimal number (00 - 61).
    t        The tab character.
    T        The time (%H:%M:%S).
    u        The weekday as a decimal number between 1 and 7
             (Monday=1).
    U        The week number of the year (the first Sunday as the
             first day of week 1) as a decimal number (00 - 53).
    V        The week number of the year (Monday as the first day
             of the week) as a decimal number (00 - 53). If the week
             containing January 1 has four or more days in the new
             year, it is considered as week 1. Otherwise, it is
             considered as week 53 of the previous year, and the
             next week is week 1.
    w        The weekday as a decimal number (0 [Sunday] - 6).
    W        The week number of the year (the first Monday as the
             first day of week 1) as a decimal number (00 - 53).
    x        The locale's appropriate date representation
    X        The locale's appropriate time representation
    y        The year without century as a decimal number (00 - 99).
    Y        The year with century as a decimal number.
    Z        Time-zone name or abbreviation. If time-zone information
             is not available, no character is output.
    %        Literal % character.

581.4  –  Return Values

    x                  The number of wide characters placed into the
                       array pointed to by wcs, not including the
                       terminating null character.
    0                  Indicates an error occurred. The contents of
                       the array are indeterminate.

581.5  –  Example

  /* Exercise the wcsftime formatting routine.             */
  /* NOTE: the format string is an "L" (or wide character) */
  /*       string indicating that this call is NOT in      */
  /*       the XPG4 format, but rather in ISO C format.    */

 #include <stdlib.h>
 #include <stdio.h>
 #include <time.h>
 #include <wchar.h>
 #include <locale.h>
 #include <errno.h>

 #define NUM_OF_DATES  7
 #define BUF_SIZE 256

  /* This program formats a number of different dates, once using the   */
  /* C locale and then using the fr_FR.ISO8859-1 locale.  Date and time */
  /* formatting is done using wcsftime().                               */

 main()

 {
   int count,
       i;
   wchar_t buffer[BUF_SIZE];
   struct tm *tm_ptr;
   time_t time_list[NUM_OF_DATES] =
   {500, 68200000, 694223999,
    694224000, 704900000, 705000000,
    705900000};

   /* Display dates using the C locale */
   printf("\nUsing the C locale:\n\n");

   setlocale(LC_ALL, "C");

   for (i = 0; i < NUM_OF_DATES; i++) {
       /* Convert to a tm structure */
       tm_ptr = localtime(&time_list[i]);

       /* Format the date and time */
       count = wcsftime(buffer, BUF_
 SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n",
                       tm_ptr);
       if (count == 0) {
           perror("wcsftime");
           exit(EXIT_FAILURE);
       }

       /* Print the result */
       printf("%S", buffer);
   }

   /* Display dates using the fr_FR.ISO8859-1 locale */
   printf("\nUsing the fr_FR.ISO8859-1 locale:\n\n");

   setlocale(LC_ALL, "fr_FR.ISO8859-1");

   for (i = 0; i < NUM_OF_DATES; i++) {
       /* Convert to a tm structure */
       tm_ptr = localtime(&time_list[i]);

       /* Format the date and time */
       count = wcsftime(buffer, BUF_
 SIZE, L"Date: %A %d %B %Y%nTime: %T%n%n",
                        tm_ptr);
       if (count == 0) {
           perror("wcsftime");
           exit(EXIT_FAILURE);
       }

       /* Print the result */
       printf("%S", buffer);
   }
 }

    Running the example program produces the following result:

    Using the C locale:

    Date: Thursday 01 January 1970
    Time: 00:08:20

    Date: Tuesday 29 February 1972
    Time: 08:26:40

    Date: Tuesday 31 December 1991
    Time: 23:59:59

    Date: Wednesday 01 January 1992
    Time: 00:00:00

    Date: Sunday 03 May 1992
    Time: 13:33:20

    Date: Monday 04 May 1992
    Time: 17:20:00

    Date: Friday 15 May 1992
    Time: 03:20:00

    Using the fr_FR.ISO8859-1 locale:

    Date: jeudi 01 janvier 1970
    Time: 00:08:20

    Date: mardi 29 février 1972
    Time: 08:26:40

    Date: mardi 31 décembre 1991
    Time: 23:59:59

    Date: mercredi 01 janvier 1992
    Time: 00:00:00

    Date: dimanche 03 mai 1992
    Time: 13:33:20

    Date: lundi 04 mai 1992
    Time: 17:20:00

    Date: vendredi 15 mai 1992
    Time: 03:20:00

582  –  wcslen

    Returns the number of wide characters in a wide-character
    string. The returned length does not include the terminating
    null character.

    Format

      #include  <wchar.h>

      size_t wcslen  (const wchar_t *wstr);

582.1  –  Argument

 wstr

    A pointer to a null-terminated wide-character string.

582.2  –  Return Value

    x                  The length of the wide-character string,
                       excluding the terminating null wide character.

583  –  wcsncat

    Concatenates a counted number of wide-characters from one string
    to another.

    Format

      #include  <wchar.h>

      wchar_t *wcsncat  (wchar_t *wstr_1, const wchar_t *wstr_2,
                        size_t maxchar);

583.1  –  Function Variants

    The wcsncat function has variants named _wcsncat32 and _wcsncat64
    for use with 32-bit and 64-bit pointer sizes, respectively.

583.2  –  Arguments

 wstr_1, wstr_2

    Pointers to null-terminated wide-character strings.

 maxchar

    The maximum number of wide characters from wstr_2 that are copied
    to wstr_1. If maxchar is 0, no characters are copied from wstr_2.

583.3  –  Description

    The wcsncat function appends wide characters from the wide-
    character string wstr_2 to the end of wstr_1, up to a maximum of
    maxchar characters. A terminating null wide character is always
    appended to the result of the wcsncat function. Therefore, the
    maximum number of wide characters that can end up in wstr_1 is
    wcslen(wstr_1) + maxchar + 1).

    See also wcscat.

583.4  –  Return Value

    x                  The first argument, wstr_1, which is assumed
                       to be large enough to hold the concatenated
                       result.

583.5  –  Example

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

        /* This program concatenates two wide-
 character strings using   */
        /* the wcsncat function, and then manually compares the result  */
        /* to the expected result                                       */

        #define S1LENGTH 10
        #define S2LENGTH 8
        #define SIZE     3

        main()
        {
            int i;
            wchar_t s1buf[S1LENGTH + S2LENGTH];
            wchar_t s2buf[S2LENGTH];
            wchar_t test1[S1LENGTH + S2LENGTH];

            /* Initialize the three wide-character strings */

            if (mbstowcs(s1buf, "abcmnexyz", S1LENGTH) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            if (mbstowcs(s2buf, " orthis", S2LENGTH) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            if (mbstowcs(test1, "abcmnexyz orthis", S1LENGTH + SIZE)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

        /* Concatenate s1buf with SIZE characters from s2buf, */
        /* placing the result into s1buf. Then compare s1buf  */
        /* with the expected result in test1.                 */

            wcsncat(s1buf, s2buf, SIZE);

            for (i = 0; i <= S1LENGTH + SIZE - 2; i++) {
                /* Check that each character is correct */
                if (test1[i] != s1buf[i]) {
                    printf("Error in wcsncat\n");
                    exit(EXIT_FAILURE);
                }

            }

            printf("Concatenated string: <%S>\n", s1buf);
        }

      Running the example produces the following result:

        Concatenated string: <abcmnexyz or>

584  –  wcsncmp

    Compares not more than maxchar characters of two wide-character
    strings. It returns an integer that indicates if the strings are
    different, and how they differ.

    Format

      #include  <wchar.h>

      int wcsncmp  (const wchar_t *wstr_1, const wchar_t *wstr_2,
                   size_t maxchar);

584.1  –  Arguments

 wstr_1, wstr_2

    Pointers to null-terminated wide-character strings.

 maxchar

    The maximum number of characters to search in both wstr_1 and
    wstr_2. If maxchar is 0, no comparison is performed and 0 is
    returned (the strings are considered equal).

584.2  –  Description

    The strings are compared until a null character is encountered,
    the strings differ, or maxchar is reached. If characters differ,
    wcsncmp returns:

    o  An integer less than 0 if the codepoint of the first differing
       character in wstr_1 is less than the codepoint of the
       corresponding character in wstr_2

    o  An integer greater than 0 if the codepoint of the first
       differing character in wstr_1 is greater than the codepoint
       of the corresponding character in wstr_2

    If no differences are found after comparing maxchar characters,
    the function returns 0.

    See also wcscmp.

584.3  –  Return Values

    < 0                Indicates that wstr_1 is less than wstr_2.
    0                  Indicates that wstr_1 equals wstr_2.
    > 0                Indicates that wstr_1 is greater than wstr_2.

585  –  wcsncpy

    Copies wide characters from source into dest. The function copies
    up to a maximum of maxchar characters.

    Format

      #include  <wchar.h>

      wchar_t *wcsncpy  (wchar_t *dest, const wchar_t *source, size_t
                        maxchar);

585.1  –  Function Variants

    The wcsncpy function has variants named _wcsncpy32 and _wcsncpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

585.2  –  Arguments

 dest

    Pointer to the null-terminated wide-character destination string.

 source

    Pointer to the null-terminated wide-character source string.

 maxchar

    The maximum number of wide characters to copy from source to
    dest.

585.3  –  Description

    The wcsncpy function copies no more than maxchar characters from
    source to dest. If source contains less than maxchar characters,
    null characters are added to dest until maxchar characters have
    been written to dest.

    If source contains maxchar or more characters, as many characters
    as possible are copied to dest. The null terminator of source is
    not copied to dest.

    See also wcscpy.

585.4  –  Return Value

    x                  The address of dest.

586  –  wcspbrk

    Searches a wide-character string for the first occurrence of one
    of a specified set of wide characters.

    Format

      #include  <wchar.h>

      wchar_t *wcspbrk  (const wchar_t *wstr, const wchar_t
                        *charset);

586.1  –  Function Variants

    The wcspbrk function has variants named _wcspbrk32 and _wcspbrk64
    for use with 32-bit and 64-bit pointer sizes, respectively.

586.2  –  Arguments

 wstr

    A pointer to a wide-character string. If this is a null string,
    NULL is returned.

 charset

    A pointer to a wide-character string containing the set of wide
    characters for which the function will search.

586.3  –  Description

    The wcspbrk function scans the wide characters in the string,
    stops when it encounters a wide character found in charset, and
    returns the address of the first character in the string that
    appears in the character set.

586.4  –  Return Values

    x                  The address of the first wide character in the
                       string that is in the set.
    NULL               Indicates that none of the characters are in
                       charset.

587  –  wcsrchr

    Scans for the last occurrence of a wide character in a given
    string.

    Format

      #include  <wchar.h>

      wchar_t *wcsrchr  (const wchar_t *wstr, wchar_t wc);

587.1  –  Function Variants

    The wcsrchr function has variants named _wcsrchr32 and _wcsrchr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

587.2  –  Arguments

 wstr

    A pointer to a null-terminated wide-character string.

 wc

    A character of type wchar_t.

587.3  –  Description

    The wcsrchr function returns the address of the last occurrence
    of a given wide character in a null-terminated wide-character
    string. The terminating null character is considered to be part
    of the string.

    See also wcschr.

587.4  –  Return Values

    x                  The address of the last occurrence of the
                       specified wide character.
    NULL               Indicates that the wide character does not
                       occur in the string.

587.5  –  Example

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

        #define BUFF_SIZE 50
        #define STRING_SIZE 6

        main()
        {
            int i;
            wchar_t s1buf[BUFF_SIZE],
                    w_string[STRING_SIZE];
            wchar_t *status;
            wchar_t *pbuf = s1buf;

            /* Initialize the buffer */

            if (mbstowcs(s1buf, "hijklabcdefg ytuhijklfedcba", BUFF_SIZE)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            /* Initialize the string to be searched for */

            if (mbstowcs(w_string, "hijkl", STRING_SIZE) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
           }

        /* This program checks the wcsrchr function by searching for */
        /* the last occurrence of a string in the buffer s1buf and   */
        /* prints out the contents of s1buff from the location of
        /* the string found.                                         */

            status = wcsrchr(s1buf, w_string[0]);
        /* Check for pointer to start of rightmost character string. */
            if (status == pbuf) {
                printf("Error in wcsrchr\n");
                exit(EXIT_FAILURE);
            }

            printf("Program completed successfully\n");
            printf("String found : [%S]\n", status);

        }

      Running the example produces the following result:

        Program completed successfully
        String found : [hijklfedcba]

588  –  wcsrtombs

    Converts a sequence of wide characters into a sequence of
    corresponding multibyte characters.

    Format

      #include  <wchar.h>

      size_t wcsrtombs  (char *dst, const wchar_t **src, size_t len,
                        mbstate_t *ps);

588.1  –  Function Variants

    The wcsrtombs function has variants named _wcsrtombs32 and
    _wcsrtombs64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

588.2  –  Arguments

 dst

    A pointer to the destination array for converted multibyte
    character sequence.

 src

    An address of the pointer to an array containing the sequence of
    wide characters to be converted.

 len

    The maximum number of bytes that can be stored in the array
    pointed to by dst.

 ps

    A pointer to the mbstate_t object. If a NULL pointer is
    specified, the function uses its internal mbstate_t object.
    mbstate_t is an opaque datatype intended to keep the conversion
    state for the state-dependent codesets.

588.3  –  Description

    The wcsrtombs function converts a sequence of wide characters
    from the array indirectly pointed to by src into a sequence of
    corresponding multibyte characters, beginning in the conversion
    state described by the object pointed to by ps.

    If dst is a not a NULL pointer, the converted characters are then
    stored into the array pointed to by dst. Conversion continues up
    to and including a terminating null wide character, which is also
    stored.

    Conversion stops earlier in two cases:

    o  When a code is reached that does not correspond to a valid
       multibyte character

    o  If dst is not a NULL pointer, when the next multibyte
       character would exceed the limit of len total bytes to be
       stored into the array pointed to by dst

    Each conversion takes place as if by a call to the wcrtomb
    function.

    If dst is not a NULL pointer, the pointer object pointed to by
    src is assigned either a NULL pointer (if the conversion stopped
    because it reached a terminating null wide character) or the
    address just beyond the last wide character converted (if any).
    If conversion stopped because it reached a terminating null
    wide character, the resulting state described is the initial
    conversion state.

    If the wcsrtombs function is called as a counting function,
    which means that dst is a NULL pointer, the value of the internal
    mbstate_t object will remain unchanged.

    See also wcrtomb.

588.4  –  Return Values

    x                  The number of bytes stored in the resulting
                       array, not including the terminating null (if
                       any).
    -1                 Indicates an encoding error-a character that
                       does not correspond to a valid multibyte
                       character was encountered; errno is set to
                       EILSEQ; the conversion state is undefined.

589  –  wcsspn

    Compares the characters in a wide-character string against a set
    of wide characters. The function returns the length of the first
    substring comprised entirely of characters in the set of wide
    characters.

    Format

      #include  <wchar.h>

      size_t wcsspn  (const wchar_t *wstr1, const wchar_t *wstr2);

589.1  –  Arguments

 wstr1

    A pointer to a null-terminated wide-character string. If this
    string is a null string, 0 is returned.

 wstr2

    A pointer to a null-terminated wide-character string that
    contains the set of wide characters for which the function will
    search.

589.2  –  Description

    The wcsspn function scans the wide characters in the wide-
    character string pointed to by wstr1 until it encounters a
    character not found in wstr2. The function returns the length of
    the first segment of wstr1 formed by characters found in wstr2.

589.3  –  Return Value

    x                  The length of the segment.

589.4  –  Example

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

        /* This test sets up 2 strings, buffer and w_string. It */
        /* then uses wcsspn() to calculate the maximum segment  */
        /* of w_string that consists entirely of characters     */
        /* from buffer.                                         */

        #define BUFF_SIZE 20
        #define STRING_SIZE 50

        main()
        {
            wchar_t buffer[BUFF_SIZE];
            wchar_t w_string[STRING_SIZE];
            size_t result;

            /* Initialize the buffer */

            if (mbstowcs(buffer, "abcdefg", BUFF_SIZE) == (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

            /* Initialize the string */

            if (mbstowcs(w_
 string, "abcedjklmabcjklabcdehjkl", STRING_SIZE)

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }

        /* Using wcsspn - work out the largest string in w_string */
        /* that consists entirely of characters from buffer       */

            result = wcsspn(w_string, buffer);
            printf("Longest segment found in w_
 string is: %d", result);

        }

    Running the example program produces the following result:

    Longest segment found in w_string is: 5

590  –  wcsstr

    Locates the first occurrence in the string pointed to by s1 of
    the sequence of wide characters in the string pointed to by s2.

    Format

      #include  <wchar.h>

      wchar_t *wcsstr  (const wchar_t *s1, const wchar_t *s2);

590.1  –  Function Variants

    The wcsstr function has variants named _wcsstr32 and _wcsstr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

590.2  –  Arguments

 s1, s2

    Pointers to null-terminated, wide-character strings.

590.3  –  Description

    If s2 points to a wide-character string of 0 length, the wcsstr
    function returns s1.

590.4  –  Return Values

    x                  A pointer to the located string.
    NULL               Indicates an error; the string was not found.

591  –  wcstod

    Converts a given wide-character string to a double-precision
    number.

    Format

      #include  <wchar.h>

      double wcstod  (const wchar_t *nptr, wchar_t **endptr);

591.1  –  Arguments

 nptr

    A pointer to the wide-character string to be converted to a
    double-precision number.

 endptr

    The address of an object where the function can store the address
    of the first unrecognized wide character that terminates the
    scan. If endptr is a NULL pointer, the address of the first
    unrecognized wide character is not retained.

591.2  –  Description

    The wcstod function recognizes an optional sequence of white-
    space characters (as defined by iswspace), then an optional plus
    or minus sign, then a sequence of digits optionally containing a
    radix character, then an optional letter (e or E) followed by an
    optionally signed integer. The first unrecognized character ends
    the conversion.

    The string is interpreted by the same rules used to interpret
    floating constants.

    The radix character is defined in the program's current locale
    (category LC_NUMERIC).

    This function returns the converted value. For wcstod, overflows
    are accounted for in the following manner:

    o  If the correct value causes an overflow, HUGE_VAL (with a plus
       or minus sign according to the sign of the value) is returned
       and errno is set to ERANGE.

    o  If the correct value causes an underflow, 0 is returned and
       errno is set to ERANGE.

    If the string starts with an unrecognized wide character, *endptr
    is set to nptr and a 0 value is returned.

591.3  –  Return Values

    x                  The converted string.
    0                  Indicates the conversion could not be
                       performed. The function sets errno to one
                       of:

                       o  EINVAL - No conversion could be performed.

                       o  ERANGE - The value would cause an
                          underflow.

                       o  ENOMEM - Not enough memory available for
                          internal conversion buffer.

    HUGE_VAL           Overflow occurred; errno is set to ERANGE.

592  –  wcstok

    Locates text tokens in a given wide-character string.

    Format

      #include  <wchar.h>

      wchar_t *wcstok  (wchar_t *ws1, const wchar_t *ws2); (XPG4)

      wchar_t *wcstok  (wchar_t *ws1, const wchar_t *ws2, wchar_t
                       **ptr); (ISO C)

592.1  –  Function Variants

    The wcstok function has variants named _wcstok32 and _wcstok64
    for use with 32-bit and 64-bit pointer sizes, respectively.

592.2  –  Arguments

 ws1

    A pointer to a wide-character string containing zero or more text
    tokens.

 ws2

    A pointer to a separator string consisting of one or more wide
    characters. The separator string can differ from call to call.

 ptr

    ISO C Standard only. Used only when ws1 is NULL, ptr is a caller-
    provided wchar_t pointer into which wcstok stores information
    necessary for it to continue scanning the same wide-character
    string.

592.3  –  Description

    A sequence of calls to wcstok breaks the wide-character string
    pointed to by ws1 into a sequence of tokens, each of which is
    delimited by a wide character from the wide-character string
    pointed to by ws2.

    The wcstok function keeps track of its position in the wide-
    character string between calls and, as successive calls are made,
    the function works through the wide-character string, identifying
    the text token following the one identified by the previous call.

    Tokens in ws1 are delimited by null characters that wcstok
    inserts into ws1. Therefore, ws1 cannot be a const object.

    The following sections describe differences between the XPG4
    Standard and ISO C Standard interface to wcstok.

    XPG4 Standard Behavior

    The first call to the wcstok function searches the wide-character
    string for the first character that is not found in the separator
    string pointed to by ws2. The first call returns a pointer to the
    first wide character in the first token and writes a null wide
    character into ws1 immediately following the returned token.

    Subsequent calls to wcstok search for a wide character that is
    in the separator string pointed to by ws2. Each subsequent call
    (with the value of the first argument remaining NULL) returns a
    pointer to the next token in the string originally pointed to by
    ws1. When no tokens remain in the string, wcstok returns a NULL
    pointer.

    ISO C Standard Behavior

    For the first call in the sequence, ws1 points to a wide-
    character string. In subsequent calls for the same string, ws1
    is NULL. When ws1 is NULL, the value pointed to by ptr matches
    that stored by the previous call for the same wide-character
    string. Otherwise, the value pointed to by ptr is ignored.

    The first call in the sequence searches the wide-character
    string pointed to by ws1 for the first wide character that is not
    contained in the current separator wide-character string pointed
    to by ws2. If no such wide character is found, then there are no
    tokens in the wide-character string pointed to by ws1, and wcstok
    returns a NULL pointer.

    The wcstok function then searches from there for a wide character
    that is contained in the current separator wide-character string.
    If no such wide character is found, the current token extends
    to the end of the wide-character string pointed to by ws1, and
    subsequent searches in the same wide-character string for a token
    return a NULL pointer. If such a wide character is found, it
    is overwritten by a null wide character, which terminates the
    current token.

    In all cases, wcstok stores sufficient information in the pointer
    pointed to by ptr so that subsequent calls with a NULL pointer
    for ws1 and the unmodified pointer value for ptr start searching
    just past the element overwritten by a null wide character (if
    any).

592.4  –  Return Values

    x                  A pointer to the first character of a token.
    NULL               Indicates that no token was found.

592.5  –  Examples

    1./* XPG4 version of wcstok call */

      #include <wchar.h>
      #include <string.h>
      #include <stdio.h>

      main()
      {
          wchar_t str[] = L"...ab..cd,,ef.hi";

          printf("|%S|\n", wcstok(str, L"."));
          printf("|%S|\n", wcstok(NULL, L","));
          printf("|%S|\n", wcstok(NULL, L",."));
          printf("|%S|\n", wcstok(NULL, L",."));
      }

    2./* ISO C version of wcstok call */

      #include <wchar.h>
      #include <string.h>
      #include <stdio.h>

      main()
      {
          wchar_t str[] = L"...ab..cd,,ef.hi";
          wchar_t *savptr = NULL;

          printf("|%S|\n", wcstok(str, L".", &savptr));
          printf("|%S|\n", wcstok(NULL, L",", &savptr));
          printf("|%S|\n", wcstok(NULL, L",.", &savptr));
          printf("|%S|\n", wcstok(NULL, L",.", &savptr));
      }

    Running this example produces the following results:

    $ $ RUN WCSTOK_EXAMPLE
    |ab|
    |.cd|
    |ef|
    |hi|
    $

593  –  wcstol

    Converts a wide-character string in a specified base to a long
    integer value.

    Format

      #include  <wchar.h>

      long int wcstol  (const wchar_t *nptr, wchar_t **endptr, int base);

593.1  –  Function Variants

    The wcstol function has variants named _wcstol32 and _wcstol64
    for use with 32-bit and 64-bit pointer sizes, respectively.

593.2  –  Arguments

 nptr

    A pointer to the wide-character string to be converted to a long
    integer.

 endptr

    The address of an object where the function can store a pointer
    to the first unrecognized character encountered in the conversion
    process (the character that follows the last character processed
    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.

    If base is 16, leading zeros after the optional sign are ignored,
    and 0x or 0X is ignored.

    If base is 0, the sequence of characters is interpreted by the
    same rules used to interpret an integer constant. After the
    optional sign:

    o  A leading 0 indicates octal conversion.

    o  A leading 0x or 0X indicates hexadecimal conversion.

    o  Any other combination of leading characters indicates decimal
       conversion.

593.3  –  Description

    The wcstol function recognizes strings in various formats,
    depending on the value of the base. This function ignores any
    leading white-space characters (as defined by the iswspace
    function) in the given string. It recognizes an optional plus
    or minus sign, then a sequence of digits or letters that can
    represent an integer constant according to the value of the base.
    The first unrecognized character ends the conversion.

593.4  –  Return Values

    x                  The converted value.
    0                  Indicates that the string starts with an
                       unrecognized wide character or that the value
                       for base is invalid. If the string starts with
                       an unrecognized wide character, *endptr is set
                       to nptr. The function sets errno to EINVAL.
    LONG_MAX or LONG_  Indicates that the converted value would cause
    MIN                a positive or negative overflow, respectively.
                       The function sets errno to ERANGE.

594  –  wcstombs

    Converts a sequence of wide-character codes to a sequence of
    multibyte characters.

    Format

      #include  <stdlib.h>

      size_t wcstombs  (char *s, const wchar_t *pwcs, size_t n);

594.1  –  Arguments

 s

    A pointer to the array containing the resulting multibyte
    characters.

 pwcs

    A pointer to the array containing the sequence of wide-character
    codes.

 n

    The maximum number of bytes to be stored in the array pointed to
    by s.

594.2  –  Description

    The wcstombs function converts a sequence of codes corresponding
    to multibyte characters from the array pointed to by pwcs to a
    sequence of multibyte characters that are stored into the array
    pointed to by s, up to a maximum of n bytes. The value returned
    is equal to the number of characters converted or a -1 if an
    error occurred.

    This function is affected by the LC_CTYPE category of the
    program's current locale.

    If s is NULL, this function call is a counting operation and n is
    ignored.

    See also wctomb.

594.3  –  Return Values

    x                  The number of bytes stored in s, not including
                       the null terminating byte. If s is NULL,
                       wcstombs returns the number of bytes required
                       for the multibyte character array.
    (size_t) -1        Indicates an error occurred. The function sets
                       errno to EILSEQ - invalid character sequence,
                       or a wide-character code does not correspond
                       to a valid character.

595  –  wcstoul

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

    Format

      #include  <wchar.h>

      unsigned long int wcstoul  (const wchar_t *nptr, wchar_t
                                 **endptr, int base);

595.1  –  Function Variants

    The wcstoul function has variants named _wcstoul32 and _wcstoul64
    for use with 32-bit and 64-bit pointer sizes, respectively.

595.2  –  Arguments

 nptr

    A pointer to the wide-character string to be converted to an
    unsigned long.

 endptr

    The address of an object where the function can store the address
    of the first unrecognized character encountered in the conversion
    process (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.

    If base is 16, leading zeros after the optional sign are ignored,
    and 0x or 0X is ignored.

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

595.3  –  Description

    The wcstoul function recognizes strings in various formats,
    depending on the value of the base. It ignores any leading
    white-space characters (as defined by the iswspace function)
    in the string. It recognizes an optional plus or minus sign,
    then a sequence of digits or letters that may represent an
    integer constant according to the value of the base. The first
    unrecognized wide character ends the conversion.

595.4  –  Return Values

    x                  The converted value.
    0                  Indicates that the string starts with an
                       unrecognized wide character or that the value
                       for base is invalid. If the string starts with
                       an unrecognized wide character, *endptr is set
                       to nptr. The function sets errno to EINVAL.
    ULONG_MAX          Indicates that the converted value would
                       cause an overflow. The function sets errno
                       to ERANGE.

595.5  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <wchar.h>
        #include <errno.h>
        #include <limits.h>

        /* This test calls wcstoul() to convert a string to an     */
        /* unsigned long integer. wcstoul outputs the resulting    */
        /* integer and any characters that could not be converted. */

        #define MAX_STRING 128

        main()
        {

            int base = 10,
                errno;
            char *input_string = "1234.56";
            wchar_t string_array[MAX_STRING],
                   *ptr;
            size_t size;
            unsigned long int val;
            printf("base = [%d]\n", base);
            printf("String to convert = %s\n", input_string);
          if ((size = mbstowcs(string_array, input_string, MAX_STRING)) ==

                (size_t)-1) {

                perror("mbstowcs");
                exit(EXIT_FAILURE);
            }
            printf("wchar_t string is = [%S]\n", string_array);

            errno = 0;
            val = wcstoul(string_array, &ptr, base);
            if (errno == 0) {
        printf("returned unsigned long int from wcstoul = [%u]\n", val);
              printf("wide char terminating scan(ptr) = [%S]\n\n", ptr);
            }
            if (errno == ERANGE) {
                perror("error value is :");
                printf("ULONG_MAX = [%u]\n", ULONG_MAX);
                printf("wcstoul failed, val = [%d]\n\n", val);
            }

        }

    Running the example program produces the following result:

    base = [10]
    String to convert = 1234.56
    wchar_t string is = [1234.56]
    returned unsigned long int from wcstoul = [1234]
    wide char terminating scan(ptr) = [.56]

596  –  wcswcs

    Locates the first occurrence in the string pointed to by wstr1
    of the sequence of wide characters in the string pointed to by
    wstr2.

    Format

      #include  <wchar.h>

      wchar_t *wcswcs  (const wchar_t *wstr1, const wchar_t *wstr2);

596.1  –  Function Variants

    The wcswcs function has variants named _wcswcs32 and _wcswcs64
    for use with 32-bit and 64-bit pointer sizes, respectively.

596.2  –  Arguments

 wstr1, wstr2

    Pointers to null-terminated wide-character strings.

596.3  –  Return Values

    Pointer            A pointer to the located wide-character
                       string.
    NULL               Indicates that the wide-character string was
                       not found.

596.4  –  Example

        #include <stdlib.h>
        #include <stdio.h>
        #include <wchar.h>

        /* This test uses wcswcs() to find the occurrence of each */
        /* subwide-character string, string1 and string2, within  */
        /* the main wide-character string, lookin.                */

        #define BUF_SIZE 50

        main()
        {
          static char lookin[] = "that this is a test was at the end";

          char string1[] = "this",
               string2[] = "the end";

          wchar_t buffer[BUF_SIZE],
                  input_buffer[BUF_SIZE];

          /* Convert lookin to wide-character format.         */
          /* Buffer and print it out.                         */

          if (mbstowcs(buffer, lookin, BUF_SIZE) == (size_t)-1) {

              perror("mbstowcs");
              exit(EXIT_FAILURE);
          }

          printf("Buffer to look in: %S\n", buffer);

          /* Convert string1 to wide-character format and use */
          /* wcswcs() to locate it within buffer              */

          if (mbstowcs(input_buffer, string1, BUF_SIZE) == (size_t)-1) {

              perror("mbstowcs");
              exit(EXIT_FAILURE);
          }

          printf("this: %S\n", wcswcs(buffer, input_buffer));

          /* Convert string2 to wide-character format and use */
          /* wcswcs() to locate it within buffer              */

          if (mbstowcs(input_buffer, string2, BUF_SIZE) == (size_t)-1) {

              perror("mbstowcs");
              exit(EXIT_FAILURE);
          }
          printf("the end: %S\n", wcswcs(buffer, input_buffer));

          exit(1);
        }

    Running this example produces the following results:

    Buffer to look in: that this is a test was at the end
    this: this is a test was at the end
    the end: the end

597  –  wcswidth

    Determines the number of printing positions on a display device
    that are required for a wide-character string.

    Format

      #include  <wchar.h>

      int wcswidth  (const wchar_t *pwcs, size_t n);

597.1  –  Arguments

 pwcs

    A pointer to a wide-character string.

 n

    The maximum number of characters in the string.

597.2  –  Description

    The wcswidth function returns the number of printing positions
    required to display the first n characters of the string pointed
    to by pwcs. If there are less than n wide characters in the
    string, the function returns the number of positions required
    for the whole string.

597.3  –  Return Values

    x                  The number of printing positions required.
    0                  If pwcs is a null character.
    -1                 Indicates that one (or more) of the wide
                       characters in the string pointed to by pwcs
                       is not a printable character.

598  –  wcsxfrm

    Changes a wide-character string such that the changed string can
    be passed to the wcscmp function and produce the same result as
    passing the unchanged string to the wcscoll function.

    Format

      #include  <wchar.h>

      size_t wcsxfrm  (wchar_t *ws1, const wchar_t *ws2, size_t
                      maxchar);

598.1  –  Arguments

 ws1, ws2

    Pointers to wide-character strings.

 maxchar

    The maximum number of wide characters, including the null wide-
    character terminator, allowed to be stored in s1.

598.2  –  Description

    The wcsxfrm function transforms the string pointed to by ws2
    and stores the resulting string in the array pointed to by ws1.
    No more than maxchar wide characters, including the null wide
    terminator, are placed into the array pointed to by ws1.

    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 ws1 is indeterminate. In such
    a case, the function returns the size of the transformed string.

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

    The wide-character string comparison functions, wcscoll and
    wcscmp, can produce different results given the same two wide-
    character strings to compare. This is because wcscmp does a
    straightforward comparison of the code point values of the
    characters in the strings, whereas wcscoll uses the locale
    information to do the comparison. Depending on the locale, the
    wcscoll comparison can be a multipass operation, which is slower
    than wcscmp.

    The wcsxfrm function transforms wide-character strings in such
    a way that if you pass two transformed strings to the wcscmp
    function, the result is the same as passing the two original
    strings to the wcscoll function. The wcsxfrm function is useful
    in applications that need to do a large number of comparisons on
    the same wide-character strings using wcscoll. In this case, it
    may be more efficient (depending on the locale) to transform the
    strings once using wcsxfrm and then use the wcscmp function to do
    comparisons.

598.3  –  Return Values

    x                  Length of the resulting string pointed to
                       by ws1, not including the terminating null
                       character.
    (size_t) -1        Indicates that an error occurred. The function
                       sets errno to EINVAL - The string pointed to
                       by ws2 contains characters outside the domain
                       of the collating sequence.

598.4  –  Example

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

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

 #define  BUFF_SIZE  20

 main()
 {
     wchar_t w_string1[BUFF_SIZE];
     wchar_t w_string2[BUFF_SIZE];
     wchar_t w_string3[BUFF_SIZE];
     wchar_t w_string4[BUFF_SIZE];
     int errno;
     int coll_result;
     int wcscmp_result;
     size_t wcsxfrm_result1;
     size_t wcsxfrm_result2;

     /* setlocale to French locale */

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

     /* Convert each of the strings into wide-character format. */

     if (mbstowcs(w_string1, "<a`>bcd", BUFF_SIZE) == (size_t)-1) {

         perror("mbstowcs");
         exit(EXIT_FAILURE);
     }

     if (mbstowcs(w_string2, "abcz", BUFF_SIZE) == (size_t)-1) {

         perror("mbstowcs");
         exit(EXIT_FAILURE);
     }

     /* Collate string 1 and string 2 and store the result. */

     errno = 0;
     coll_result = wcscoll(w_string1, w_string2);
     if (errno) {
         perror("wcscoll");
         exit(EXIT_FAILURE);
     }
     else {

        /*  Transform the strings (using wcsxfrm) into  */
        /*  w_string3 and w_string4.                    */

        wcsxfrm_result1 = wcsxfrm(w_string3, w_string1, BUFF_SIZE);

        if (wcsxfrm_result1 == ((size_t) - 1))
            perror("wcsxfrm");
        else if (wcsxfrm_result1 > BUFF_SIZE) {
            perror("\n** String is too long **\n");
            exit(EXIT_FAILURE);
        }
        else {
           wcsxfrm_result2 = wcsxfrm(w_string4, w_string2, BUFF_SIZE);
           if (wcsxfrm_result2 == ((size_t) - 1)) {
               perror("wcsxfrm");
               exit(EXIT_FAILURE);
            }
           else if (wcsxfrm_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 wcscoll on */
         /* the original strings.                                */

           else {
               wcscmp_result = wcscmp(w_string3, w_string4);
               if (wcscmp_result == 0 && (coll_result == 0)) {
                   printf("\nReturn value from wcscoll() and return value"
                                        " from wcscmp() are both zero.");
                   printf("\nThe program was successful\n\n");
               }
               else if ((wcscmp_result < 0) && (coll_result < 0)) {
                   printf("\nReturn value from wcscoll() and return value"
                                   " from wcscmp() are less than zero.");
                   printf("\nThe program was successful\n\n");
               }
               else if ((wcscmp_result > 0) && (coll_result > 0)) {
                   printf("\nReturn value from wcscoll() and return value"
                                 " from wcscmp() 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 wcscoll() and return value
           from wcscmp() are less than zero.
    The program was successful

599  –  wctob

    Determines if a wide character corresponds to a single-
    byte multibyte character and returns its multibyte character
    representation.

    Format

      #include  <stdio.h>

      #include  <wchar.h>

      int wctob  (wint_t c);

599.1  –  Argument

 c

    The wide character to be converted to a single-byte multibyte
    character.

599.2  –  Description

    The wctob function determines whether the specified wide
    character corresponds to a single-byte multibyte character when
    in the initial shift state and, if so, returns its multibyte
    character representation.

599.3  –  Return Values

    x                  The single-byte representation of the wide
                       character specified.
    EOF                Indicates an error. The wide character
                       specified does not correspond to a single-byte
                       multibyte character.

600  –  wctomb

    Converts a wide character to its multibyte character
    representation.

    Format

      #include  <stdlib.h>

      int wctomb  (char *s, wchar_t wchar);

600.1  –  Arguments

 s

    A pointer to the resulting multibyte character.

 wchar

    The code for the wide character.

600.2  –  Description

    The wctomb function converts the wide character specified by
    wchar to its multibyte character representation. If s is NULL,
    then 0 is returned. Otherwise, the number of bytes comprising the
    multibyte character is returned. At most, MB_CUR_MAX bytes are
    stored in the array object pointed to by s.

    This function is affected by the LC_CTYPE category of the
    program's current locale.

600.3  –  Return Values

    x                  The number of bytes comprising the multibyte
                       character corresponding to wchar.
    0                  If s is NULL.
    -1                 If wchar is not a valid character.

601  –  wctrans

    Returns the description of a mapping, corresponding to specified
    property, that can later be used in a call to towctrans.

    Format

      #include  <wctype.h>

      wctrans_t wctrans  (const char *property);

601.1  –  Argument

 property

    The name of the mapping. The following property names are defined
    for all locales:

    o  "toupper"

    o  "tolower"

    Additional property names may also be defined in the LC_CTYPE
    category of the current locale.

601.2  –  Description

    The wctrans function constructs a value with type wctrans_t that
    describes a mapping between wide characters identified by the
    property argument.

    See also towctrans.

601.3  –  Return Values

    nonzero            According to the LC_CTYPE category of the
                       current program locale, the string specified
                       as a property argument is the name of an
                       existing character mapping. The value returned
                       can be used in a call to the towctrans
                       function.
    0                  Indicates an error. The property argument
                       does not identify a character mapping in the
                       current program's locale.

602  –  wctype

    Used for defining a character class. The value returned by this
    function is used in calls to the iswctype function.

    Format

      #include  <wctype.h> (ISO C)

      #include  <wchar.h> (XPG4)

      wctype_t wctype  (const char *char_class);

602.1  –  Argument

 char_class

    A pointer to a valid character class name.

602.2  –  Description

    The wctype function converts a valid character class defined for
    the current locale to an object of type wctype_t. The following
    character class names are defined for all locales:

    alnum        cntrl        lower        space
    alpha        digit        print        upper
    blank        graph        punct        xdigit

    Additional character class names may also be defined in the LC_
    CTYPE category of the current locale.

    See also iswctype.

602.3  –  Return Values

    x                  An object of type wctype_t that can be used in
                       calls to the iswctype function.
    0                  If the character class name is not valid for
                       the current locale.

602.4  –  Example

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

  /* This test will set up a number of character class using wctype() */
  /* and then verify whether calls to iswctype() using these classes  */
  /* produce the same results as calls to the is**** routines.        */

 main()
 {

     wchar_t w_char;
     wctype_t ret_val;

     char *character = "A";

     /* Convert character to wide character format - w_char */

     if (mbtowc(&w_char, character, 1) == -1) {
         perror("mbtowc");
         exit(EXIT_FAILURE);
     }

     /* Check if results from iswalnum() matches check on */
     /* alnum character class                             */

     if ((iswalnum((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("alnum"))))
         printf("[%C] is a member of the character class alnum\n", w_char);
  else
     printf("[%C] is not a member of the character class alnum\n", w_char);

     /* Check if results from iswalpha() matches check on */
     /* alpha character class                             */

     if ((iswalpha((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("alpha"))))
    printf("[%C] is a member of the character class alpha\n", w_char);
     else
    printf("[%C] is not a member of the character class alpha\n", w_char);

     /* Check if results from iswcntrl() matches check on */
     /* cntrl character class                             */

     if ((iswcntrl((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("cntrl"))))
     printf("[%C] is a member of the character class cntrl\n", w_char);
     else
    printf("[%C] is not a member of the character class cntrl\n", w_char);

     /* Check if results from iswdigit() matches check on */
     /* digit character class                             */

     if ((iswdigit((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("digit"))))
     printf("[%C] is a member of the character class digit\n", w_char);
     else
    printf("[%C] is not a member of the character class digit\n", w_char);

     /* Check if results from iswgraph() matches check on */
     /* graph character class                             */

     if ((iswgraph((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("graph"))))
         printf("[%C] is a member of the character class graph\n", w_char);
     else
    printf("[%C] is not a member of the character class graph\n", w_char);

     /* Check if results from iswlower() matches check on */
     /* lower character class                             */

     if ((iswlower((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("lower"))))
         printf("[%C] is a member of the character class lower\n", w_char);
     else
    printf("[%C] is not a member of the character class lower\n", w_char);

     /* Check if results from iswprint() matches check on */
     /* print character class                             */

     if ((iswprint((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("print"))))
         printf("[%C] is a member of the character class print\n", w_char);
     else
    printf("[%C] is not a member of the character class print\n", w_char);

     /* Check if results from iswpunct() matches check on */
     /* punct character class                             */

     if ((iswpunct((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("punct"))))
         printf("[%C] is a member of the character class punct\n", w_char);
     else
    printf("[%C] is not a member of the character class punct\n", w_char);

     /* Check if results from iswspace() matches check on */
     /* space character class                             */

     if ((iswspace((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("space"))))
         printf("[%C] is a member of the character class space\n", w_char);
     else
     printf("[%C] is not a member of the character class space\n", w_char);

     /* Check if results from iswupper() matches check on */
     /* upper character class                             */

     if ((iswupper((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("upper"))))
         printf("[%C] is a member of the character class upper\n", w_char);
     else
     printf("[%C] is not a member of the character class upper\n", w_char);

     /* Check if results from iswxdigit() matches check on */
     /* xdigit character class                             */

     if ((iswxdigit((wint_t) w_char)) &&
         (iswctype((wint_t) w_char, wctype("xdigit"))))
         printf("[%C] is a member of the character class xdigit\n", w_char);
     else
    printf("[%C] is not a member of the character class xdigit\n", w_char);

 }

    Running this example produces the following result:

    [A] is a member of the character class alnum
    [A] is a member of the character class alpha
    [A] is not a member of the character class cntrl
    [A] is not a member of the character class digit
    [A] is a member of the character class graph
    [A] is not a member of the character class lower
    [A] is a member of the character class print
    [A] is not a member of the character class punct
    [A] is not a member of the character class space
    [A] is a member of the character class upper
    [A] is a member of the character class xdigit

603  –  wcwidth

    Determines the number of printing positions on a display device
    required for the specified wide character.

    Format

      #include  <wchar.h>

      int wcwidth  (wchar_t wc);

603.1  –  Argument

 wc

    A wide character.

603.2  –  Description

    The wcwidth function determines the number of column positions
    needed for the specified wide character wc. The value of wc must
    be a valid wide character in the current locale.

603.3  –  Return Values

    x                  The number of printing positions required for
                       wc.
    0                  If wc is a null character.
    -1                 Indicates that wc does not represent a valid
                       printing wide character.

604  –  wmemchr

    Locates the first occurrence of a specified wide character in an
    array of wide characters.

    Format

      #include  <wchar.h>

      wchar_t wmemchr  (const wchar_t *s, wchar_t c, size_t n);

604.1  –  Function Variants

    The wmemchr function has variants named _wmemchr32 and _wmemchr64
    for use with 32-bit and 64-bit pointer sizes, respectively.

604.2  –  Arguments

 s

    A pointer to an array of wide characters to be searched.

 c

    The wide character value to search for.

 n

    The maximum number of wide characters in the array to be
    searched.

604.3  –  Description

    The wmemchr function locates the first occurrence of the
    specified wide character in the initial n wide characters of
    the array pointed to by s.

604.4  –  Return Values

    x                  A pointer to the first occurrence of the wide
                       character in the array.
    NULL               The specified wide character does not occur in
                       the array.

605  –  wmemcmp

    Compares two arrays of wide characters.

    Format

      #include  <wchar.h>

      int wmemcmp  (const wchar_t *s1, const wchar_t *s2, size_t n);

605.1  –  Arguments

 s1, s2

    Pointers to wide-character arrays.

 n

    The maximum number of wide characters to be compared.

605.2  –  Description

    The wmemcmp function compares the first n wide characters of
    the array pointed to by s1 with the first n wide characters of
    the array pointed to by s2. The wide characters are compared not
    according to locale-dependent collation rules, but as integral
    objects of type wchar_t.

605.3  –  Return Values

    0                  Arrays are equal.
    Positive value     The first array is greater than the second.
    Negative value     The first array is less than the second.

606  –  wmemcpy

    Copies a specified number of wide characters from one wide-
    character array to another.

    Format

      #include  <wchar.h>

      wchar_t wmemcpy  (wchar_t *dest, const wchar_t *source, size_t n);

606.1  –  Function Variants

    The wmemcpy function has variants named _wmemcpy32 and _wmemcpy64
    for use with 32-bit and 64-bit pointer sizes, respectively.

606.2  –  Arguments

 dest

    A pointer to the destination array.

 source

    A pointer to the source array.

 n

    The number of wide characters to be copied.

606.3  –  Description

    The wmemcpy function copies n wide characters from the array
    pointed to by source to the array pointed to by dest.

606.4  –  Return Value

    x                  The value of dest.

607  –  wmemmove

    Copies a specified number of wide characters from one wide-
    character array to another.

    Format

      #include  <wchar.h>

      wchar_t wmemmove  (wchar_t *dest, const wchar_t *source, size_t n);

607.1  –  Function Variants

    The wmemmove function has variants named _wmemmove32 and
    _wmemmove64 for use with 32-bit and 64-bit pointer sizes,
    respectively.

607.2  –  Arguments

 dest

    A pointer to the destination array.

 source

    A pointer to the source array.

 n

    The number of wide characters to be moved.

607.3  –  Description

    The wmemmove function copies n wide characters from the location
    pointed to by source to the location pointed to by dest.

    The wmemmove and wmemcpy routines perform the same function,
    except that wmemmove ensures that the original contents of the
    source array are copied to the destination array even if the two
    arrays overlap. Where such overlap is possible, programs that
    require portability should use wmemmove, not wmemcopy.

607.4  –  Return Value

    x                  The value of dest.

608  –  wmemset

    Sets a specified value to a specified number of wide characters
    in an array of wide characters.

    Format

      #include  <wchar.h>

      wchar_t wmemset  (wchar_t *s, wchar_t c, size_t n);

608.1  –  Function Variants

    The wmemset function has variants named _wmemset32 and _wmemset64
    for use with 32-bit and 64-bit pointer sizes, respectively.

608.2  –  Arguments

 s

    A pointer to the array of wide characters.

 c

    The value to be placed in the first n wide characters of the
    array.

 n

    The number of wide characters to be set to the specified value c.

608.3  –  Description

    The wmemset function copies the value of c into each of the first
    n wide characters of the array pointed to by s.

608.4  –  Return Value

    x                  The value of s.

609  –  wprintf

    Performs formatted output from the standard output (stdout). See
    Chapter 2 for information on format specifiers.

    Format

      #include  <wchar.h>

      int wprintf  (const wchar_t *format, . . . );

609.1  –  Arguments

 format

    A pointer to a wide-character string containing the format
    specifications.

  . . .

    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.

609.2  –  Description

    The wprintf function is equivalent to the fwprintf function with
    the stdout argument interposed before the wprintf arguments.

609.3  –  Return Values

    n                  The number of wide characters written.
    Negative value     Indicates an error. The function sets errno to
                       one of the following:

                       o  EILSEQ - Invalid character detected.

                       o  EINVAL - Insufficient arguments.

                       o  ENOMEM - Not enough memory available for
                          conversion.

                       o  ERANGE - Floating-point calculations
                          overflow.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This might indicate that conversion to a
                          numeric value failed because of overflow.

                       The function can also set errno to the
                       following as a result of errors returned from
                       the I/O subsystem:

                       o  EBADF - The file descriptor is not valid.

                       o  EIO - I/O error.

                       o  ENOSPC - No free space on the device
                          containing the file.

                       o  ENXIO - Device does not exist.

                       o  EPIPE - Broken pipe.

                       o  ESPIPE - Illegal seek in a file opened for
                          append.

                       o  EVMSERR - Nontranslatable OpenVMS error.
                          vaxc$errno contains the OpenVMS error code.
                          This indicates that an I/O error occurred
                          for which there is no equivalent C error
                          code.

610  –  wrapok

    In the UNIX system environment, allows the wrapping of a word
    from the right border of the window to the beginning of the
    next line. This routine is provided only for UNIX software
    compatibility and serves no function in the OpenVMS environment.

    Format

      #include  <curses.h>

      wrapok  (WINDOW *win, bool boolf);

610.1  –  Arguments

 win

    A pointer to the window.

 boolf

    A Boolean TRUE or FALSE value. If boolf is FALSE, scrolling
    is not allowed. This is the default setting. The bool type is
    defined in the <curses.h> header file as follows:

    #define bool int

611  –  write

    Writes a specified number of bytes from a buffer to a file.

    Format

      #include  <unistd.h>

      ssize_t write  (int file_desc, void *buffer, size_t nbytes);

                     (ISO POSIX-1)

      int write  (int file_desc, void *buffer, int nbytes);

                 (Compatibility)

611.1  –  Arguments

 file_desc

    A file descriptor that refers to a file currently opened for
    writing or updating.

 buffer

    The address of contiguous storage from which the output data is
    taken.

 nbytes

    The maximum number of bytes involved in the write operation.

611.2  –  Description

    If the write is to an RMS record file and the buffer contains
    embedded new-line characters, more than one record may be written
    to the file. Even if there are no embedded new-line characters,
    if nbytes is greater than the maximum record size for the file,
    more than one record will be written to the file. The write
    function always generates at least one record.

    If the write is to a mailbox and the third argument, nbytes,
    specifies a length of 0, an end-of-file message is written to
    the mailbox. This occurs for mailboxes created by the application
    using SYS$CREMBX, but not for mailboxes created to implement
    POSIX pipes. For more information see the "Subprocess Functions"
    chapter of the VSI C RTL Reference Manual.

611.3  –  Return Values

    x                  The number of bytes written.
    -1                 Indicates errors, including undefined file
                       descriptors, illegal buffer addresses, and
                       physical I/O errors.

612  –  writev

    Writes to a file.

    Format

      #include  <uio.h>

      ssize_t writev  (int file_desc, const struct iovec *iov, int
                      iovcnt);

      ssize_t __writev64  (int file_desc, const struct
                          __iovec64  *iov, int iovcnt);
                          (Integrity servers, Alpha)

612.1  –  Function Variants

    The writev function has variants named _writev32 and __writev64
    for use with 32-bit and 64-bit pointer sizes, respectively.

612.2  –  Arguments

 file_desc

    A file descriptor that refers to a file currently opened for
    writing or updating.

 iov

    Array of iovec structures from which the output data is gathered.

 iovcnt

    The number of buffers specified by the members of the iov array.

612.3  –  Description

    The writev function is equivalent to write but gathers the output
    data from the iovcnt buffers specified by the members of the iov
    array: iov[0], iov[1], ..., iov[iovcnt-1]. The iovcnt argument
    is valid if greater than 0 and less than or equal to {IOV_MAX},
    defined in <limits.h>.

    Each iovec entry specifies the base address and length of an area
    in memory from which data should be written. The writev function
    writes a complete area before proceeding to the next.

    If filedes refers to a regular file and all of the iov_len
    members in the array pointed to by iov are 0, writev returns 0
    and has no other effect.

    For other file types, the behavior is unspecified.

    If the sum of the iov_len values is greater than SSIZE_MAX, the
    operation fails and no data is transferred.

    Upon successful completion, writev returns the number of bytes
    actually written. Otherwise, it returns a value of -1, the file
    pointer remains unchanged, and errno is set to indicate an error.

612.4  –  Return Values

    x                  The number of bytes written.
    -1                 Indicates an error. The file times do not
                       change, and the function sets errno to one of
                       the following values:

                       o  EBADF - The file_desc argument is not a
                          valid file descriptor open for writing.

                       o  EINTR - The write operation was terminated
                          due to the receipt of a signal, and no data
                          was transferred.

                       o  EINVAL - The sum of the iov_len values in
                          the iov array would overflow an ssize_t, or
                          the iovcnt argument was less than or equal
                          to 0, or greater than {IOV_MAX}.

                       o  EIO - A physical I/O error has occurred.

                       o  ENOSPC - There was no free space remaining
                          on the device containing the file.

                       o  EPIPE - An attempt is made to write to a
                          pipe or FIFO that is not open for reading
                          by any process, or that only has one end
                          open. A SIGPIPE signal will also be sent to
                          the thread.

613  –  wscanf

    Reads input from the standard input (stdin) under control of the
    wide-character format string.

    Format

      #include  <wchar.h>

      int wscanf  (const wchar_t *format, . . . );

613.1  –  Arguments

 format

    A pointer to a wide-character string containing the format
    specifications.

  . . .

    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.

613.2  –  Description

    The wscanf function is equivalent to the fwscanf function with
    the stdin arguments interposed before the wscanf arguments.

613.3  –  Return Values

    n                  The number of input items assigned. The number
                       can be less than provided for, even zero, in
                       the event of an early matching failure.
    EOF                Indicates an error. An input failure occurred
                       before any conversion.

614  –  y0,y1,yn

    Compute Bessel functions of the second kind.

    This function is supported on OpenVMS Integrity servers and
    Alpha only.

    Format

      #include  <math.h>

      double y0  (double x);

      float y0f  (float x);

      long double y0l  (long double x);

      double y1  (double x);

      float y1f  (float x);

      long double y1l  (long double x);

      double yn  (int n, double x);

      float ynf  (int n, float x);

      long double ynl  (int n, long double x);

614.1  –  Arguments

 x

    A positive, real value.

 n

    An integer.

614.2  –  Description

    The y0 functions return the value of the Bessel function of the
    second kind of order 0.

    The y1 functions return the value of the Bessel function of the
    second kind of order 1.

    The yn functions return the value of the Bessel function of the
    second kind of order n.

614.3  –  Return Values

    x                  The relevant Bessel value of x of the second
                       kind.
    -HUGE_VAL          The x argument is 0.0; errno is set to ERANGE.
    NaN                The x argument is negative or NaN; errno is
                       set to EDOM.
    0                  Underflow occurred; errno is set to ERANGE.
    HUGE_VAL           Overflow occurred; errno is set to ERANGE.

615  –  Version-Dependency Tables

    New functions are added to the VSI C Run-Time Library with each
    version of VSI C. These functions are implemented and shipped with
    the OpenVMS operating system, while the documentation and header
    files containing their prototypes are shipped with versions of
    the VSI C compiler.

    You might have a newer version of VSI C that has header files
    and documentation for C RTL functions that are not supported on
    your older OpenVMS system. For example, if your target operating
    system platform is OpenVMS Version 7.2, you cannot use C RTL
    functions introduced on OpenVMS Version 7.3, even though they are
    documented in this manual.

    The following tables list what C RTL functions are supported
    on recent OpenVMS versions. This is helpful for determining the
    functions to avoid using on your target OpenVMS platforms.

615.1  –  All OpenVMS Versions

    The following functions are available on all OpenVMS VAX, Alpha,
    and Integrity servers versions:

       abort         abs           access      acos
       alarm         asctime       asin        assert
       atan2         atan          atexit      atof
       atoi          atoll (Alpha) atol        atoq (Alpha)
       box           brk           bsearch     cabs
       calloc        ceil          cfree       chdir
       chmod         chown         clearerr    clock
       close         cosh          cos         creat
       ctermid       ctime         cuserid     decc$crtl_init
       decc$fix_time     decc$from_vms      decc$match_wild
       decc$record_read  decc$record_write  decc$set_reentrancy
       decc$to_vms       decc$translate_vms
       delete        delwin        difftime    div
       dup2          dup           ecvt        endwin
       execle        execlp        execl       execve
       execvp        execv         exit        _exit
       exp           fabs          fclose      fcvt
       fdopen        feof          ferror      fflush
       fgetc         fgetname      fgetpos     fgets
       fileno        floor         fmod        fopen
       fprintf       fputc         fputs       fread
       free          freopen       frexp       fscanf
       fseek         fsetpos       fstat       fsync
       ftell         ftime         fwait       fwrite
       gcvt          getchar       getcwd      getc
       getegid       getenv        geteuid     getgid
       getname       getpid        getppid     gets
       getuid        getw          gmtime      gsignal
       hypot         initscr       isalnum     isalpha
       isapipe       isascii       isatty      iscntrl
       isdigit       isgraph       islower     isprint
       ispunct       isspace       isupper     isxdigit
       kill          labs          ldexp       ldiv
       llabs (Alpha) lldiv(Alpha)  localeconv  localtime
       log10         log           longjmp     longname
       lseek         lwait         malloc      mblen
       mbstowcs      mbtowc        memchr      memcmp
       memcpy        memmove       memset      mkdir
       mktemp        mktime        modf        mvwin
       mv[w]addstr   newwin        nice        open
       overlay       overwrite     pause       perror
       pipe          pow           printf      putchar
       putc          puts          putw        qabs (Alpha)
       qdiv (Alpha)  qsort         raise       rand
       read          realloc       remove      rename
       rewind        sbrk          scanf       scroll
       setbuf        setgid        setjmp      setlocale
       setuid        setvbuf       sigblock    signal
       sigpause      sigstack(VAX) sigvec      sinh
       sin           sleep         sprintf     sqrt
       srand         sscanf        ssignal     stat
       strcat        strchr        strcmp      strcoll
       strcpy        strcspn       strerror    strftime
       strlen        strncat       strncmp     strncpy
       strpbrk       strrchr       strspn      strstr
       strtod        strtok        strtoll     strtol (Alpha)
       strtoq (Alpha) strtoull (Alpha)  strtoul  strtouq (Alpha)
       strxfrm       subwin        system      tanh
       tan           times         time        tmpfile
       tmpnam        toascii       tolower     _tolower
       touchwin      toupper       _toupper    ttyname
       umask         ungetc        vaxc$calloc_opt vaxc$cfree_opt
       vaxc$crtl_init    vaxc$establish vaxc$free_opt vaxc$malloc_opt
       vaxc$realloc_opt  va_arg    va_count    va_end
       va_start      va_start_1    vfork       vfprintf
       vprintf       vsprintf      wait        wcstombs
       wctomb        write         [w]addch    [w]addstr
       [w]clear      [w]clrattr    [w]clrtobot [w]clrtoeol
       [w]delch      [w]deleteln   [w]erase    [w]getch
       [w]getstr     [w]inch       [w]insch    [w]insertln
       [w]insstr     [w]move       [w]printw   [w]refresh
       [w]scanw      [w]setattr    [w]standend [w]standout

615.2  –  V6.2 and Higher

    The following additional functions are available on OpenVMS VAX
    and OpenVMS Alpha Version 6.2 and higher:

       catclose     catgets      catopen      fgetwc
       fgetws       fputwc       fputws       getopt
       getwc        getwchar     iconv        iconv_close
       iconv_open   iswalnum     iswalpha     iswcntrl
       iswctype     iswdigit     iswgraph     iswlower
       iswprint     iswpunct     iswspace     iswupper
       iswxdigit    nl_langinfo  putwc        putwchar
       strnlen      strptime     towlower     towupper
       ungetwc      wcscat       wcschr       wcscmp
       wcscoll      wcscpy       wcscspn      wcsftime
       wcslen       wcsncat      wcsncmp      wcsncpy
       wcspbrk      wcsrchr      wcsspn       wcstol
       wcstoul      wcswcs       wcswidth     wcsxfrm
       wcstod       wctype       wcwidth      wcstok

615.3  –  V7.0 and Higher

    The following additional functions are available on OpenVMS VAX
    and OpenVMS Alpha Version 7.0 and higher:

       basename     bcmp         bcopy        btowc
       bzero        closedir     confstr      dirname
       drand48      erand48      ffs          fpathconf
       ftruncate    ftw          fwide        fwprintf
       fwscanf      getclock     getdtablesizegetitimer
       getlogin     getpagesize  getpwnam     getpwuid
       gettimeofday index        initstate    jrand48
       lcong48      lrand48      mbrlen       mbrtowc
       mbsinit      mbsrtowcs    memccpy      mkstemp
       mmap         mprotect     mrand48      msync
       munmap       nrand48      opendir      pathconf
       pclose       popen        putenv       random
       readdir      rewinddir    rindex       rmdir
       seed48       seekdir      setenv       setitimer
       setstate     sigaction    sigaddset    sigdelset
       sigemptyset  sigfillset   sigismember  siglongjmp
       sigpending   sigprocmask  sigsetjmp    sigsuspend
       srand48      srandom      strcasecmp   strdup
       strfmon      strncasecmp  strsep       swab
       swprintf     swscanf      sysconf      telldir
       tempnam      towctrans    truncate     tzset
       ualarm       uname        unlink       unsetenv
       usleep       vfwprintf    vswprintf    vwprintf
       wait3        wait4        waitpid      wcrtomb
       wcsrtombs    wcsstr       wctob        wctrans
       wmemchr      wmemcmp      wmemcpy      wmemmove
       wmemset      wprintf      wscanf

615.4  –  V7.0 Alpha and Higher

    The following additional functions are available on OpenVMS Alpha
    Version 7.0 and higher:

       _basename32  _basename64  _bsearch32   _bsearch64
       _calloc32    _calloc64    _catgets32   _catgets64
       _ctermid32   _ctermid64   _cuserid32   _cuserid64
       _dirname32   _dirname64   _fgetname32  _fgetname64
       _fgets32     _fgets64     _fgetws32    _fgetws64
       _gcvt32      _gcvt64      _getcwd32    _getcwd64
       _getname32   _getname64   _gets32      _gets64
       _index32     _index64     _longname32  _longname64
       _malloc32    _malloc64    _mbsrtowcs32 _mbsrtowcs64

       _memccpy32   _memccpy64   _memchr32    _memchr64
       _memcpy32    _memcpy64    _memmove32   _memmove64
       _memset32    _memset64    _mktemp32    _mktemp64
       _mmap32      _mmap64      _qsort32     _qsort64
       _realloc32   _realloc64   _rindex32    _rindex64
       _strcat32    _strcat64    _strchr32    _strchr64
       _strcpy32    _strcpy64    _strdup32    _strdup64
       _strncat32   _strncat64   _strncpy32   _strncpy64
       _strpbrk32   _strpbrk64   _strptime32  _strptime64
       _strrchr32   _strrchr64   _strsep32    _strsep64
       _strstr32    _strstr64    _strtod32    _strtod64
       _strtok32    _strtok64    _strtol32    _strtol64
       _strtoll32   _strtoll64   _strtoq32    _strtoq64
       _strtoul32   _strtoul64   _strtoull32  _strtoull64
       _strtouq32   _strtouq64   _tmpnam32    _tmpnam64
       _wcscat32    _wcscat64    _wcschr32    _wcschr64
       _wcscpy32    _wcscpy64    _wcsncat32   _wcsncat64
       _wcsncpy32   _wcsncpy64   _wcspbrk32   _wcspbrk64
       _wcsrchr32   _wcsrchr64   _wcsrtombs32 _wcsrtombs64
       _wcsstr32    _wcsstr64    _wcstok32    _wcstok64
       _wcstol32    _wcstol64    _wcstoul32   _wcstoul64
       _wcswcs32    _wcswcs64    _wmemchr32   _wmemchr64
       _wmemcpy32   _wmemcpy64   _wmemmove32  _wmemmove64
       _wmemset32   _wmemset64

615.5  –  V7.2 and Higher

    The following additional functions are available on OpenVMS VAX
    and OpenVMS Alpha Version 7.2 and higher:

       asctime_r      ctime_r     decc$set_child_standard_streams
       decc$write_eof_to_mbx      decc$validated lclose
       dlerror        dlopen      dlsym
       fcntl          gmtime_r    localtime_r
       wchar

615.6  –  V7.3 and Higher

    The following additional functions are available on OpenVMS VAX
    and OpenVMS Alpha Version 7.3 and higher:

       fchown
       link
       utime
       utimes
       writev

615.7  –  V7.3-1 and Higher

    The following additional functions are available on OpenVMS Alpha
    Version 7.3-1 and higher:

       access     fseeko
       chmod      ftello
       chown      ftw
       fstat      readdir_r
                  stat

       vfscanf    vfwscanf
       vscanf     vwscanf
       vsscanf    vswscanf

       decc$feature_get_index
       decc$feature_get_name
       decc$feature_get_value
       decc$feature_set_value

615.8  –  V7.3-2 and Higher

    The following additional functions are available on OpenVMS Alpha
    Version 7.3-2 and higher:

    a64l           clock_getres   clock_gettime    clock_settime
    endgrent       getgrent       getgrgid         getgrgid_r
    getgrnam       getgrnam_r     getpgid          getpgrp
    _getpwnam64    getpwnam_r     _getpwnam_r64    _getpwent64
    getpwuid       _getpwuid64    getpwuid_r       _getpwuid_r64
    getsid         l64a           nanosleep        poll
    pread          pwrite         rand_r           readv
    _readv64       seteuid        setgrent         setpgid
    setpgrp        setregid       setreuid         setsid
    sighold        sigignore      sigrelse         sigtimedwait
    sigwait        sigwaitinfo    snprintf         ttyname_r
    vsnprintf      __writev64     decc$set_child_default_dir

615.9  –  V8.2 and Higher

    The following additional functions are available on OpenVMS Alpha
    and Integrity servers Version 8.2 and higher:

    clearerr_unlocked    feof_unlocked
    ferror_unlocked      fgetc_unlocked
    fputc_unlocked       flockfile
    ftrylockfile         funlockfile
    getc_unlocked        getchar_unlocked
    putc_unlocked        putchar_unlocked
    statvfs              fstatvfs
    _glob32              _glob64
    _globfree32          _globfree64
    socketpair

615.10  –  V8.3 and Higher

    The following additional functions are available on OpenVMS Alpha
    and Integrity servers Version 8.3 and higher:

    crypt       fchmod
    encrypt     lstat
    setkey      readlink
    lchown      symlink
    realpath    unlink

615.11  –  V8.4 and Higher

    The following additional functions are available on OpenVMS Alpha
    and Integrity servers Version 8.4 and higher:

    ftok              sem_init
    semctl            sem_open
    semget            sem_post
    semop             sem_timedwait
    sem_close         sem_trywait
    sem_destroy       sem_unlink
    sem_getvalue      sem_wait

616  –  Prototypes Duplicated to Nonstandard Headers

    The various standards dictate which header file must define
    each of the standard functions. This is the included header file
    documented with each function prototype in the Reference Section
    of this manual.

    However, many of the functions defined by the standards already
    existed on several operating systems and were defined in
    different header files. This is especially true on OpenVMS
    systems with the header files <processes.h>, <unixio.h>, and
    <unixlib.h>.

    So, to provide upward compatibility for these functions, their
    prototypes are duplicated in both the expected header file as
    well as the header file defined by the standards.

    Duplicated Prototypes lists these functions.

    Table B-1 Duplicated Prototypes

                 Duplicated
    Function     in            Standard says

    access       <unixio.h>    <unistd.h>
    alarm        <signal.h>    <unistd.h>
    bcmp         <string.h>    <strings.h>
    bcopy        <string.h>    <strings.h>
    bzero        <string.h>    <strings.h>
    chdir        <unixio.h>    <unistd.h>
    chmod        <unixio.h>    <stat.h>
    chown        <unixio.h>    <unistd.h>
    close        <unixio.h>    <unistd.h>
    creat        <unixio.h>    <fcntl.h>
    ctermid      <stdio.h>     <unistd.h>
    cuserid      <stdio.h>     <unistd.h>
    dirname      <string.h>    <libgen.h>
    dup          <unixio.h>    <unistd.h>
    dup2         <unixio.h>    <unistd.h>
    ecvt         <unixlib.h>   <stdlib.h>
    execl        <processes.h> <unistd.h>
    execle       <processes.h> <unistd.h>
    execlp       <processes.h> <unistd.h>
    execv        <processes.h> <unistd.h>
    execve       <processes.h> <unistd.h>
    execvp       <processes.h> <unistd.h>
    _exit        <stdlib.h>    <unistd.h>
    fcvt         <unixlib.h>   <stdlib.h>
    ffs          <string.h>    <strings.h>
    fsync        <stdio.h>     <unistd.h>
    ftime        <time.h>      <timeb.h>
    gcvt         <unixlib.h>   <stdlib.h>
    getcwd       <unixlib.h>   <unistd.h>
    getegid      <unixlib.h>   <unistd.h>
    getenv       <unixlib.h>   <stdlib.h>
    geteuid      <unixlib.h>   <unistd.h>
    getgid       <unixlib.h>   <unistd.h>
    getopt       <stdio.h>     <unistd.h>
    getpid       <unixlib.h>   <unistd.h>
    getppid      <unixlib.h>   <unistd.h>
    getuid       <unixlib.h>   <unistd.h>
    index        <string.h>    <strings.h>
    isatty       <unixio.h>    <unistd.h>
    lseek        <unixio.h>    <unistd.h>
    mkdir        <unixlib.h>   <stat.h>
    mktemp       <unixio.h>    <stdlib.h>
    nice         <stdlib.h>    <unistd.h>
    open         <unixio.h>    <fcntl.h>
    pause        <signal.h>    <unistd.h>
    pipe         <processes.h> <unistd.h>
    read         <unixio.h>    <unistd.h>
    rindex       <string.h>    <strings.h>
    sbrk         <stdlib.h>    <unistd.h>
    setgid       <unixlib.h>   <unistd.h>
    setuid       <unixlib.h>   <unistd.h>
    sleep        <signal.h>    <unistd.h>
    strcasecmp   <string.h>    <strings.h>
    strncasecmp  <string.h>    <strings.h>
    system       <processes.h> <stdlib.h>
    times        <time.h>      <times.h>
    umask        <stdlib.h>    <stat.h>
    vfork        <processes.h> <unistd.h>
    wait         <processes.h> <wait.h>
    write        <unixio.h>    <unistd.h>
Close Help