1 CRTL The complete HP C Run-Time Library (C RTL) needed for use with the HP C compiler is distributed with the OpenVMS operating system, which runs on Alpha, and Intel[R] Itanium[R] processors. HP OpenVMS Industry Standard 64 for Integrity Servers is the full product name of the OpenVMS operating system on Intel Itanium 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 Alpha 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. 2 Feature-Test_Macros Feature-test macros provide a means for writing portable programs. They ensure that the Compaq C RTL symbolic names used by a program do not clash with the symbolic names supplied by the implementation. The Compaq 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 Compaq 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 Compaq C RTL header files define symbols without restriction. The feature-test macros supported by the Compaq 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 3 Standards_Macros The Compaq 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. 3 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 Compaq 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 Compaq C extensions. 4 _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 4 _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 4 _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 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 4 _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 4 _STDC_VERSION__==199409_ Makes ISO C Amendment 1 symbols visible. Standard Selected: ISO C Amendment 1 Other Standards Implied: ANSI C 4 _ANSI_C_SOURCE Makes ANSI C standard symbols visible. Standard Selected: ANSI C Other Standards Implied: None. 4 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 Compaq 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 . Therefore, 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 . Therefore, 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 . Therefore, 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 to support the sysconf function. However, these constants are not defined by _POSIX_C_SOURCE. The 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 . Note that _POSIX_C_SOURCE is defined only for programs compiled in strict ANSI C mode. o The fgetname function is a Compaq C RTL extension to . Therefore, 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 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 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 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 . 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. 3 Multiple-Version-Support_Macro By default, the header files enable APIs in the Compaq 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 Compaq C User's Guide for OpenVMS Systems. For example, compiling on OpenVMS Version 6.2 causes only Compaq 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 Compaq 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. 3 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 : 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 by adding them to another module. If this is the case on your system, then compiling with the provided with DEC C Version 5.2 might cause compilation errors. To maintain your current environment and include the DEC C Version 5.2 , compile with _DECC_V4_SOURCE defined. This will omit incompatible references from the DEC C Version 5.2 headers. In , for example, the previously listed typedefs will not be visible. o As of OpenVMS Version 7.0, the Compaq 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 (as required by the ISO POSIX-1 standard) and in (for Compaq 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 Compaq 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. 3 Curses_and_Socket_Compatibility_Macros The following feature-test macros are used to control the Curses and Socket subsets of the Compaq 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 if _BSD44_CURSES is defined. o The header file defines a 4.4BSD sockaddr structure only if _SOCKADDR_LEN or _XOPEN_SOURCE_EXTENDED is defined. Otherwise, defines a pre-4.4BSD sockaddr structure. If _SOCKADDR_LEN is defined and _XOPEN_SOURCE_EXTENDED is not defined, The 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. 3 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. 3 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 HP C Version 4 or _VMS_V6_SOURCE for OpenVMS Version 6), forces use of short (16-bit) UID/GID. 3 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. 3 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. 3 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 3 POSIX_Style_exit_(Integrity_servers,_Alpha)_ The HP 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 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 3 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. 3 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. 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. 3 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. 3 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 3 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. 3 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. 3 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. 3 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 (/). 3 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. 3 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. 3 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: / * " ? 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 #include #include #include 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); } 3 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. 3 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]. 3 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. 3 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. 3 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. 3 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. 3 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: : [ ^ 3 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 (.). 3 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. 3 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. 3 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. 3 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. 3 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. 3 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 3 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. 3 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. 3 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 3 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 3 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. 3 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 Compaq C Run-Time Library Reference Manual for OpenVMS Systems for more information on POSIX-compliant pathnames and symbolic links. 3 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. 3 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. 3 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. 3 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. 3 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". 3 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" 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 DECC$TZ_CACHE_SIZE DECC$TZ_CACHE_SIZE specifies the number of time zones that can be held in memory. Default: 2 Maximum: 2147483647 3 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 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 3 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. 2 a64l Converts a character string to a long integer. This function is OpenVMS Alpha and Integrity servers only. Format #include long a64l (const char *s); 3 Argument s Pointer to the character string that is to be converted to a long integer. 3 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 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. 2 abort Sends the signal SIGABRT that terminates execution of the program. Format #include void abort (void); 2 abs Returns the absolute value of an integer. Format #include int abs (int x); 3 Argument x An integer. 3 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. 2 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 int access (const char *file_spec, int mode); 3 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); 3 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. 3 Return_Values 0 Indicates that the access is allowed. -1 Indicates that the access is not allowed. 3 Example #include #include #include main() { if (access("sys$login:login.com", F_OK)) { perror("ACCESS - FAILED"); exit(2); } } 2 acos Returns the arc cosine of its argument. Format #include 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) 3 Argument x A radian expressed as a real value in the domain [-1,1]. 3 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. 2 acosh Returns the hyperbolic arc cosine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double acosh (double x); float acoshf (float x); long double acoshl (long double x); 3 Argument x A radian expressed as a real value in the domain [1, +Infinity]. 3 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. 2 [w]addch Add a character to the window at the current position of the cursor. Format #include int addch (char ch); int waddch (WINDOW *win, char ch); 3 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. 3 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. 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. 2 [w]addstr Add the string pointed to by str to the window at the current position of the cursor. Format #include int addstr (char *str); int waddstr (WINDOW *win, char *str); 3 Arguments win A pointer to the window. str A pointer to a character string. 3 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. 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. 2 alarm Sends the signal SIGALRM (defined in the header file) to the invoking process after the number of seconds indicated by its argument has elapsed. Format #include unsigned int alarm (unsigned int seconds); (ISO POSIX-1) int alarm (unsigned int seconds); (Compatibility) 3 Argument seconds Has a maximum limit of LONG_MAX seconds. 3 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). 3 Return_Value n The number of seconds remaining from a previous alarm request. 2 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 char *asctime (const struct tm *timeptr); char *asctime_r (const struct tm *timeptr, char *buffer); (ISO POSIX-1) 3 Arguments timeptr A pointer to a structure of type tm, which contains the broken- down time. The tm structure is defined in the 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. 3 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 Compaq 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. 3 Return_Values x A pointer to the string, if successful. NULL Indicates failure. 2 asin Returns the arc sine of its argument. Format #include 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) 3 Argument x A radian expressed as a real number in the domain [-1,1]. 3 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. 2 asinh Returns the hyperbolic arc sine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double asinh (double x); float asinhf (float x); long double asinhl (long double x); 3 Argument x A radian expressed as a real value in the domain [-Infinity, +Infinity]. 3 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. 2 assert Used for implementing run-time diagnostics in programs. Format #include void assert (int expression); 3 Argument expression An expression that has an int type. 3 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. 3 Example #include #include 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"); } 2 atan Format #include 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) 3 Argument x A radian expressed as a real number. 3 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. 2 atan2 Format #include 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) 3 Arguments y A radian expressed as a real number. x A radian expressed as a real number. 3 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 2 atanh Returns the hyperbolic arc tangent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double atanh (double x); float atanhf (float x); long double atanhl (long double x); 3 Argument x A radian expressed as a real value in the domain [-1,1]. 3 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. 2 atexit Registers a function that is called without arguments at program termination. Format #include int atexit (void (*func) (void)); 3 Argument func A pointer to the function to be registered. 3 Return_Values 0 Indicates that the registration has succeeded. nonzero Indicates failure. 3 Restriction The longjmp function cannot be executed from within the handler, because the destination address of the longjmp no longer exists. 3 Example #include #include static void hw(void); main() { atexit(hw); } static void hw() { puts("Hello, world\n"); } Running this example produces the following output: Hello, world 2 atof Converts an ASCII character string to a double-precision number. Format #include double atof (const char *nptr); 3 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. 3 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). 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. 2 atoi,atol Convert strings of ASCII characters to the appropriate numeric values. Format #include int atoi (const char *nptr); long int atol (const char *nptr); 3 Argument nptr A pointer to the character string to be converted to a numeric value. 3 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. 3 Return_Value n The converted value. 2 atoq,atoll Convert strings of ASCII characters to the appropriate numeric values. atoll is a synonym for atoq. This function is OpenVMS Alpha and Integrity servers only. atoq. Format #include __int64 atoq (const char *nptr); __int64 atoll (const char *nptr); 3 Argument nptr A pointer to the character string to be converted to a numeric value. 3 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. 3 Return_Value n The converted value. 2 basename Returns the last component of a pathname. Format #include char *basename (char *path); 3 Function_Variants The basename function has variants named _basename32 and _basename64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Argument path A UNIX style pathname from which the base pathname is extracted. 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. 3 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. 2 bcmp Compares byte strings. Format #include void bcmp (const void *string1, const void *string2, size_t length); 3 Arguments string1, string2 The byte strings to be compared. length The length (in bytes) of the strings. 3 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. 3 Return_Values 0 The strings are identical. Nonzero The strings are not identical. 2 bcopy Copies byte strings. Format #include void bcopy (const void *source, void *destination, size_t length); 3 Arguments source Pointer to the source string. destination Pointer to the destination string. length The length (in bytes) of the string. 3 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. 2 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 int box (WINDOW *win, char vert, char hor); 3 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. 3 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. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 brk Determines the lowest virtual address that is not used with the program. Format #include void *brk (unsigned long int addr); 3 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. 3 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. 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. 3 Restriction Unlike other C library implementations, the Compaq 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. 2 bsearch Performs a binary search. It searches an array of sorted objects for a specified object. Format #include void *bsearch (const void *key, const void *base, size_t nmemb, size_t size, int (*compar) (const void *, const void *)); 3 Function_Variants The bsearch function has variants named _bsearch32 and _bsearch64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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. 3 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. 3 Example #include #include #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! 2 btowc Converts a one-byte multibyte character to a wide character in the initial shift state. Format #include wint_t btowc (int c); 3 Argument c The character to be converted to a wide-character representation. 3 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. 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. 2 bzero Copies null characters into byte strings. Format #include void bzero (void *string, size_t length); 3 Arguments string Specifies the byte string into which you want to copy null characters. length Specifies the length (in bytes) of the string. 3 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. 2 cabs Returns the absolute value of a complex number. Format #include double cabs (cabs_t z); float cabsf (cabsf_t z); (Integrity servers, Alpha) long double cabsl (cabsl_t z); (Integrity servers, Alpha) 3 Argument z A structure of type cabs_t, cabsf_t, or cabsl_t. These types are defined in the 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) 3 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. 2 cacos Returns the complex arc cosine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex cacos (double complex z); float complex cacosf (float complex z); long double complex cacosl (long double complex z); 3 Argument z A complex value. 3 Description The cacos functions compute the complex arc cosine of z, with branch cuts outside the interval [-1, +1] along the real axis. 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, π] along the real axis. 2 cacosh Returns the complex arc hyperbolic cosine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex cacosh (double complex z); float complex cacoshf (float complex z); long double complex cacoshl (long double complex z); 3 Argument z A complex value. 3 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. 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π, +iπ] along the imaginary axis. 2 calloc Allocates an area of zeroed memory. This function is AST- reentrant. Format #include void *calloc (size_t number, size_t size); 3 Function_Variants The calloc function has variants named _calloc32 and _calloc64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Arguments number The number of items to be allocated. size The size of each item. 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. 3 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. 2 carg Returns the phase angle of its complex argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double carg (double complex z); float cargf (float complex z); long double cargl (long double complex z); 3 Argument z A complex value. 3 Description The carg functions compute the argument (also called phase angle) of z, with a branch cut along the negative real axis. 3 Return_Values n The value of the argument of z, in the interval [-π, +π]. 2 casin Returns the complex arc sine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex casin (double complex z); float complex casinf (float complex z); long double complex casinl (long double complex z); 3 Argument z A complex value. 3 Description The casin functions compute the complex arc sine of z, with branch cuts outside the interval [-1, +1] along the real axis. 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 [-π/2, +π/2] along the real axis. 2 casinh Returns the complex arc hyperbolic sine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex casinh (double complex z); float complex casinhf (float complex z); long double complex casinhl (long double complex z); 3 Argument z A complex value. 3 Description The casinh functions compute the complex arc hyperbolic sine of z, with branch cuts outside the interval [-i, +i] along the imaginary axis. 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π/2, +iπ/2] along the imaginary axis. 2 catan Returns the complex arc tangent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex catan (double complex z); float complex catanf (float complex z); long double complex catanl (long double complex z); 3 Argument z A complex value. 3 Description The catan functions compute the complex arc tangent of z, with branch cuts outside the interval [-i, +i] along the imaginary axis. 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 [-π/2, +π/2] along the real axis. 2 catanh Returns the complex arc hyperbolic tangent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex catanh (double complex z); float complex catanhf (float complex z); long double complex catanhl (long double complex z); 3 Argument z A complex value. 3 Description The catanh functions compute the complex arc hyperbolic tangent of z, with branch cuts outside the interval [-1, +1] along the imaginary axis. 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π/2, +iπ/2] along the imaginary axis. 2 catclose Closes a message catalog. Format #include int catclose (nl_catd catd); 3 Argument catd A message catalog descriptor. This is returned by a successful call to catopen. 3 Description The catclose function closes the message catalog referenced by catd and frees the catalog file descriptor. 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. 2 catgets Retrieves a message from a message catalog. Format #include char *catgets (nl_catd catd, int set_id, int msg_id, const char *s); 3 Function_Variants The catgets function has variants named _catgets32 and _catgets64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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. 3 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. 3 Example #include #include #include #include #include #include /* 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 2 catopen Opens a message catalog. Format #include nl_catd catopen (const char *name, int oflag); 3 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. 3 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 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. 2 cbrt Returns the rounded cube root of y. This function is OpenVMS Alpha and Integrity servers only. Format #include double cbrt (double y); float cbrtf (float y); long double cbrtl (long double y); 3 Argument y A real number. 2 ccos Returns the complex cosine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex ccos (double complex z); float complex ccosf (float complex z); long double complex ccosl (long double complex z); 3 Argument z A complex value. 3 Description The ccos functions return the complex cosine of z. 3 Return_Values x The complex cosine value. 2 ccosh Returns the complex hyperbolic cosine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex ccosh (double complex z); float complex ccoshf (float complex z); long double complex ccoshl (long double complex z); 3 Argument z A complex value. 3 Description The ccosh functions return the complex hyperbolic cosine of z. 3 Return_Values x The complex hyperbolic cosine value. 2 ceil Returns the smallest integer that is greater than or equal to its argument. Format #include double ceil (double x); float ceilf (float x); (Integrity servers, Alpha) long double ceill (long double x); (Integrity servers, Alpha) 3 Argument x A real value. 3 Return_Value n The smallest integer greater than or equal to the function argument. 2 cexp Returns the complex exponent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex cexp (double complex z); float complex cexpf (float complex z); long double complex cexpl (long double complex z); 3 Argument z A complex value. 3 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. 3 Return_Values x The complex exponential value of the argument. 2 cfree Makes available for reallocation the area allocated by a previous calloc, malloc, or realloc call. This function is AST-reentrant. Format #include void cfree (void *ptr); 3 Argument ptr The address returned by a previous call to malloc, calloc, or realloc. 3 Description The contents of the deallocated area are unchanged. In Compaq 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. 2 chdir Changes the default directory. Format #include int chdir (const char *dir_spec); (ISO POSIX-1) int chdir (const char *dir_spec, . . . ); (DEC C Extension) 3 Arguments dir_spec A null-terminated character string naming a directory in either an OpenVMS or UNIX style specification. . . . This argument is an Compaq 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. 3 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. 3 Return_Values 0 Indicates that the directory is successfully changed to the given name. -1 Indicates that the change attempt has failed. 2 chmod Changes the file protection of a file. Format #include int chmod (const char *file_spec, mode_t mode); 3 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. 3 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. 3 Return_Values 0 Indicates that the mode is successfully changed. -1 Indicates that the change attempt has failed. 2 chown Changes the user ID and group ID of the specified file. Format #include int chown (const char *file_spec, uid_t owner, gid_t group); 3 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. 3 Return_Values 0 Indicates success. -1 Indicates failure. 2 cimag Returns the imaginary part of its complex argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double cimag (double complex z); float cimagf (float complex z); long double cimagl (long double complex z); 3 Argument z A complex value. 3 Description The cimag functions return the imaginary part of z as a real number. 3 Return_Values x The imaginary part value. 2 [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 int clear(); int wclear (WINDOW *win); 3 Argument win A pointer to the window. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 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 void clearerr (FILE *file_ptr); 3 Argument file_ptr A file pointer. 2 clearerr_unlocked Same as the clearerr function, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include void clearerr_unlocked (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 2 clearok Sets the clear flag for the window. Format #include clearok (WINDOW *win, bool boolf); 3 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 header file as follows: #define bool int 3 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. 2 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 clock_t clock (void); 3 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 , to obtain the time in seconds. The type clock_t is defined in the 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. 3 Return_Values n The processor time used. -1 Indicates that the processor time used is not available. 2 clock_getres Gets the resolution for the specified clock. This function is OpenVMS Alpha and Integrity servers only. Format #include int clock_getres (clockid_t clock_id, struct timespec *res); 3 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. 3 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. 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. 2 clock_gettime Returns the current time (in seconds and nanoseconds) for the specified clock. This function is OpenVMS Alpha and Integrity servers only. Format #include int clock_gettime (clockid_t clock_id, struct timespec *tp); 3 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. 3 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. 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. 2 clock_settime Sets the specified clock. This function is OpenVMS Alpha and Integrity servers only. Format #include int clock_settime (clockid_t clock_id, const struct timespec *tp); 3 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. 3 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 , 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. 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. 2 clog Returns the complex natural (base e) logarithm of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex clog (double complex z); float complex clogf (float complex z); long double complex clogl (long double complex z); 3 Argument z A complex value. 3 Description The clog functions return the complex natural (base e) logarithm of z, with a branch cut along the negative real axis. 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π, +iπ] along the imaginary axis. 2 close Closes the file associated with a file descriptor. Format #include int close (int file_desc); 3 Argument file_desc A file descriptor. 3 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. 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). 3 Example #include int fd; . . . fd = open ("student.dat", 1); . . . close(fd); 2 closedir Closes directories. Format #include int closedir (DIR *dir_pointer); 3 Argument dir_pointer Pointer to the dir structure of an open directory. 3 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 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. 3 Example The following example shows how to search a directory for the entry name, using the opendir, readdir, and closedir functions: #include #include #include #include #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 ); } 3 Return_Values 0 Indicates success. -1 Indicates an error and is further specified in the global errno. 2 [w]clrattr Deactivate the video display attribute attr within the window. The clrattr function acts on the stdscr window. Format #include int clrattr (int attr); int wclrattr (WINDOW *win, int attr); 3 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); 3 Description These functions are specific to Compaq C for OpenVMS Systems and are not portable. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 [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 int clrtobot(); int wclrtobot (WINDOW *win); 3 Argument win A pointer to the window. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 [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 int clrtoeol(); int wclrtoeol (WINDOW *win); 3 Argument win A pointer to the window. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 confstr Determines the current value of a specified system variable defined by a string value. Format #include size_t confstr (int name, char *buf, size_t len); 3 Arguments name The system variable setting. Valid values for the name argument are the _CS_X names defined in the 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. 3 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 header file contains system-defined limits. The header file contains system-defined environmental variables. Also, confstr supports the following three HP-UX symbolic constants, which are added to header file : o _CS_MACHINE_IDENT o _CS_PARTITION_IDENT o _CS_MACHINE_SERIAL 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. 3 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. 2 conj Returns the complex conjugate of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex conj (double complex z); float complex conjf (float complex z); long double complex conjl (long double complex z); 3 Argument z A complex value. 3 Description The conj functions return the complex conjugate of z, by reversing the sign of its imaginary part. 3 Return_Values x The complex conjugate value. 2 copysign Returns x with the same sign as y. This function is OpenVMS Alpha and Integrity servers only. Format #include 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) 3 Arguments x A real value. y A real value. 3 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. 3 Return_Value x The value of x with the same sign as y. 2 cos Returns the cosine of its radian argument. Format #include 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) 3 Argument x A radian expressed as a real value. 3 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. 3 Return_Values x The cosine of the argument. HUGE_VAL Indicates that the argument is too large; errno is set to ERANGE. 2 cosh Returns the hyperbolic cosine of its radian argument. Format #include double cosh (double x); float coshf (float x); (Integrity servers, Alpha) long double coshl (long double x); (Integrity servers, Alpha) 3 Argument x A radian expressed as a real number. 3 Description The cosh functions return the hyperbolic cosine of x and are defined as (e**x + e**(-x))/2. 3 Return_Values x The hyperbolic cosine of the argument. HUGE_VAL Indicates that the argument is too large; errno is set to ERANGE. 2 cot Returns the cotangent of its radian argument. Format #include 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) 3 Argument x A radian expressed as a real number. 3 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. 3 Return_Values x The cotangent of the argument. HUGE_VAL Indicates that the argument is zero; errno is set to ERANGE. 2 cpow Returns the complex power function x**y. This function is OpenVMS Alpha and Integrity servers only. Format #include 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); 3 Argument x A complex value. y A complex value. 3 Description The cpow functions return the complex power function x**y, with a branch cut for the first parameter along the negative real axis. 3 Return_Values x The complex power function value. 2 cproj Returns a projection of its argument onto the Riemann sphere. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex cproj (double complex z); float complex cprojf (float complex z); long double complex cprojl (long double complex z); 3 Argument z A complex value. 3 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)) 3 Return_Values x The value of the projection onto the Riemann sphere. 2 creal Returns the real part of its complex argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double creal (double complex z); float crealf (float complex z); long double creall (long double complex z); 3 Argument z A complex value. 3 Description The creal functions return the real part of z. 3 Return_Values x The real part value. 2 creat Creates a new file. Format #include int creat (const char *file_spec, mode_t mode); (ISO POSIX-1) int creat (const char *file_spec, mode_t mode, . . . ); (DEC C Extension) 3 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 int acc_callback(int *first_arg, struct FAB *fab, struct RAB *rab); FAB and RAB are defined in the 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 Compaq 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 Compaq 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. 3 Description The Compaq 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. 3 Return_Values n A file descriptor. -1 Indicates errors, including protection violations, undefined directories, and conflicting file attributes. 2 [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 crmode() nocrmode() 3 Example /* Program to demonstrate the use of crmod() and curses */ #include 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. 2 crypt The password encryption function. Format #include #include char *crypt (const char *key, const char *salt;) 3 Function_Variants The crypt function has variants named _crypt32 and _crypt64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Argument key A user's typed password. salt A 2-character string. 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. 3 Return_Value pointer Pointer to the encrypted password. 2 csin Returns the complex sine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex csin (double complex z); float complex csinf (float complex z); long double complex csinl (long double complex z); 3 Argument z A complex value. 3 Description The csin functions compute the complex sine value of z. 3 Return_Values x The complex sine value. Returns the complex hyperbolic sine of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex csinh (double complex z); float complex csinhf (float complex z); long double complex csinhl (long double complex z); 3 Argument z A complex value. 3 Description The csinh functions compute the complex hyperbolic sine of z. 3 Return_Values x The complex hyperbolic sine value. 2 csqrt Returns the complex square root of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex csqrt (double complex z); float complex csqrtf (float complex z); long double complex csqrtl (long double complex z); 3 Argument z A complex value. 3 Description The csqrt functions compute the complex square root of z, with a branch cut along the negative real axis. 3 Return_Values x The complex square root value in the range of the right half-plane (including the imaginary axis). 2 ctan Returns the complex tangent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex ctan (double complex z); float complex ctanf (float complex z); long double complex ctanl (long double complex z); 3 Argument z A complex value. 3 Description The ctan functions compute the complex tangent value of z. 3 Return_Values x The complex tangent value. 2 ctanh Returns the complex hyperbolic tangent of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double complex ctanh (double complex z); float complex ctanhf (float complex z); long double complex ctanhl (long double complex z); 3 Argument z A complex value. 3 Description The ctanh functions compute the complex hyperbolic tangent value of z. 3 Return_Values x The complex hyperbolic tangent value. 2 ctermid Returns a character string giving the equivalence string of SYS$COMMAND. This is the name of the controlling terminal. Format #include char *ctermid (char *str); 3 Function_Variants The ctermid function has variants named _ctermid32 and _ctermid64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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 header file). 3 Return_Value pointer Points to a character string. 2 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 char *ctime (const time_t *bintim); char *ctime_r (const time_t *bintim, char *buffer); (ISO POSIX-1) 3 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. 3 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. 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 Compaq 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 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. 3 Return_Values x A pointer to the 26-character ASCII string, if successful. NULL Indicates failure. 2 cuserid Returns a pointer to a character string containing the name of the user initiating the current process. Format #include (X/Open, POSIX-1) #include (X/Open) char *cuserid (char *str); 3 Function_Variants The cuserid function has variants named _cuserid32 and _cuserid64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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 header file), and the name is written into that storage. If the user name is a null string, the function returns NULL. 3 Return_Values pointer Points to a string. NULL If the user name is a null string. 2 DECC$CRTL_INIT Allows you to call the Compaq C RTL from other languages or to use the Compaq 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 void DECC$CRTL_INIT(void); 3 Description The following example shows a Pascal program that calls the Compaq 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 Compaq 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. 2 decc$feature_get Calls decc$feature_get_value with a character-string feature name, rather than an index. Format #include int decc$feature_get (const char *name, int mode); 3 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 3 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. 3 Return_Values n An integer corresponding to the specified name and mode arguments. -1 Indicates an error; errno is set. 2 decc$feature_get_index Returns an index for accessing feature values. Format #include int decc$feature_get_index (char *name); 3 Argument name Pointer to a character string passed as a name in the list of supported features. 3 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. 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. 2 decc$feature_get_name Returns a feature name. Format #include char *decc$feature_get_name (int index); 3 Argument index An integer value from 0 to the highest allocated feature. 3 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. 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. 2 decc$feature_get_value Returns a feature value specified by the index and mode arguments. Format #include int decc$feature_get_value (int index, int mode); 3 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 3 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. 3 Return_Values n An integer corresponding to the specified index and mode arguments. -1 Indicates an error; errno is set. 2 decc$feature_set Calls decc$feature_set_value with a character-string feature name, rather than an index. Format #include int decc$feature_set (const char *name, int mode, int value); 3 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. 3 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. 3 Return_Values n The previous feature value. -1 Indicates an error; errno is set. 2 decc$feature_set_value Sets the default value or the current value for the feature specified by index. Format #include int decc$feature_set_value (int index, int mode, int value); 3 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. 3 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. 3 Return_Values n The previous feature value. -1 Indicates an error; errno is set. 2 decc$feature_show Displays all feature values for the specified feature name. Format #include int decc$feature_show (const char *name); 3 Argument name Pointer to a character string passed as a name in the list of supported features. 3 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. 3 Return_Values 0 Indicates success. -1 Indicates an error; errno is set. 2 decc$feature_show_all Displays all feature values for all feature names. Format #include int decc$feature_show_all (void); 3 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. 3 Return_Values 0 Indicates success. -1 Indicates an error; errno is set. 2 decc$fix_time Converts OpenVMS binary system times to UNIX binary times. Format #include unsigned int decc$fix_time (void *vms_time); 3 Argument vms_time The address of a quadword containing an OpenVMS binary time: unsigned int quadword[2]; unsigned int *vms_time = quadword; 3 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 Compaq C RTL routines, such as ctime and localtime. 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. 3 Example #include #include #include /* 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(¤t_vms_time[0]); /* fix the time */ number_of_seconds = decc$fix_time(¤t_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 Compaq C. It also shows the use of the SYS$GETTIM system service. 2 decc$from_vms Converts OpenVMS file specifications to UNIX style file specifications. Format #include int decc$from_vms (const char *vms_filespec, int action_routine, int wild_flag); 3 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. 3 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. 3 Return_Value x The number of filenames that result from the specified OpenVMS file specification. 3 Example /* This example must be run as a foreign command */ /* and be supplied with an OpenVMS file specification. */ #include #include 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 Compaq 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. 2 decc$match_wild Matches a string to a pattern. Format #include int decc$match_wild (char *test_string, char *string_pattern); 3 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]). 3 Description The decc$match_wild routine determines whether the specified test string is a member of the set of strings specified by the pattern. 3 Return_Values 1 (TRUE) The string matches the pattern. 0 (FALSE) The string does not match the pattern. 3 Example /* Define as a foreign command and then provide */ /* two arguments: test_string, string_pattern. */ #include #include 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]); } 2 decc$record_read Reads a record from a file. Format #include int decc$record_read (FILE *fp, void *buffer, int nbytes); 3 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. 3 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. 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. 2 decc$record_write Writes a record to a file. Format #include int decc$record_write (FILE *fp, void *buffer, int nbytes); 3 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. 3 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. 3 Return_Values x The number of bytes written. -1 Indicates errors, including undefined file descriptors, illegal buffer addresses, and physical I/O errors. 2 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 OpenVMS Alpha and Integrity servers only. Format #include int decc$set_child_default_dir (const char *default_dir); 3 Arguments default_dir The default directory specification for child processes, or NULL. 3 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. 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. 2 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 int decc$set_child_standard_streams (int fd1, int fd2, int fd3); 3 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). 3 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. 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. 3 Example parent.c ======== #include #include #include 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 #include 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. 2 decc$set_reentrancy Controls the type of reentrancy that reentrant Compaq C RTL routines will exhibit. Format #include int decc$set_reentrancy (int type); 3 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 Compaq 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 Compaq 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 Compaq 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. 3 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. 3 Return_Value type The type of reentrancy used before this call. -1 The reentrancy was set to a lower type. 2 decc$to_vms Converts UNIX style file specifications to OpenVMS file specifications. Format #include 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); 3 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. 3 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 3 Return_Value x The number of filenames that result from the specified UNIX style file specification. 3 Example /* Translate "UNIX" wildcard file names to OpenVMS names.*/ /* Define as a foreign command and provide the name as */ /* an argument. */ #include #include 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 Compaq 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. 2 decc$translate_vms Translates OpenVMS file specifications to UNIX style file specifications. Format #include char *decc$translate_vms (const char *vms_filespec); 3 Argument vms_filespec The address of a null-terminated string containing a name in OpenVMS file specification format. 3 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. 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. 3 Example /* Demonstrate translation of a "UNIX" name to OpenVMS */ /* form, define a foreign command, and pass the name as */ /* the argument. */ #include #include 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 ); } 2 decc$validate_wchar Confirms that its argument is a valid wide character in the current program's locale. Format #include int decc$validate_wchar (wchar_t wc); 3 Argument wc Wide character to be validated. 3 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. 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. 2 decc$write_eof_to_mbx Writes an end-of-file message to the mailbox. Format #include int decc$write_eof_to_mbx (int fd); 3 Argument fd File descriptor associated with the mailbox. 3 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. 3 Return_Values 0 Indicates success. -1 Indicates failure; errno and vaxc$errno are set according to the failure status returned by SYS$QIOW. 3 Example /* decc$write_eof_to_mbx_example.c */ #include #include #include #include #include #include #include #include #include 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 2 [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 int delch(); int wdelch (WINDOW *win); 3 Argument win A pointer to the window. 3 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. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 delete Deletes a file. Format #include int delete (const char *file_spec); 3 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. 3 Description If you specify a directory in the filename and it is a search list that contains an error, Compaq 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 Compaq 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. 3 Return_Values 0 Indicates success. nonzero value Indicates that the operation has failed. 2 [w]deleteln Delete the line at the current position of the cursor. The deleteln function acts on the stdscr window. Format #include int deleteln(); int wdeleteln (WINDOW *win); 3 Argument win A pointer to the window. 3 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. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 delwin Deletes the specified window from memory. Format #include int delwin (WINDOW *win); 3 Argument win A pointer to the window. 3 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. 3 Return_Values OK Indicates success. ERR Indicates an error. 2 difftime Computes the difference, in seconds, between the two times specified by the time1 and time2 arguments. Format #include double difftime (time_t time2, time_t time1); 3 Arguments time2 A time value of type time_t. time1 A time value of type time_t. 3 Description The type time_t is defined in the header file as follows: typedef unsigned long int time_t 3 Return_Value n time2 - time1 in seconds expressed as a double. 2 dirname Reports the parent directory name of a file pathname. Format #include char *dirname (char *path); 3 Function_Variants The dirname function has variants named _dirname32 and _dirname64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Argument path The file pathname. 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. 3 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. 3 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); 2 div Returns the quotient and the remainder after the division of its arguments. Format #include div_t div (int numer, int denom); 3 Arguments numer A numerator of type int. denom A denominator of type int. 3 Description The type div_t is defined in the standard header file as follows: typedef struct { int quot, rem; } div_t; 2 dlclose Deallocates the address space for a shared library. Format #include void dlclose (void *handle); 3 Argument handle Pointer to the shared library. 3 Description The dlclose function deallocates the address space allocated by the Compaq 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. 2 dlerror Returns a string describing the last error that occurred from a call to dlopen, dlclose, or dlsym. Format #include char *dlerror (void); 3 Return_Value x A string describing the last error that occurred from a call to dlopen, dlclose, or dlsym. 2 dlopen Provides an interface to the dynamic library loader to allow shareable images to be loaded and called at run time. Format #include void *dlopen (char *pathname, int mode); 3 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. 3 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. 3 Return_Values x A handle to be used by a dlsym or dlclose call. NULL Indicates an error. 2 dlsym Returns the address of the symbol name found in a shareable image. Format #include void *dlsym (void *handle, char *name); 3 Arguments handle Pointer to the shareable image. name Pointer to the symbol name. 3 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 3 Return_Values x Address of the symbol name found. NULL Indicates that the symbol was not found. 2 drand48 Generates uniformly distributed pseudorandom-number sequences. Returns 48-bit, nonnegative, double-precision floating-point values. Format #include double drand48 (void); 3 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. 3 Return_Value n A nonnegative, double-precision, floating- point value. 2 dup,dup2 Allocate a new descriptor that refers to a file specified by a file descriptor returned by open, creat, or pipe. Format #include int dup (int file_desc1); int dup2 (int file_desc1, int file_desc2); 3 Arguments file_desc1 The file descriptor being duplicated. file_desc2 The new file descriptor to be assigned to the file designated by file_desc1. 3 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. 3 Return_Values n The new file descriptor. -1 Indicates that an invalid argument was passed to the function. 2 [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 void echo (void); void noecho (void); 3 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. 2 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 Compaq C RTL. Format #include char *ecvt (double value, int ndigits, int *decpt, int *sign); 3 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. 3 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. 3 Return_Value x The value of the converted string. 2 encrypt Encrypts a string using the key generated by the setkey function. Format #include #include void encrypt (char *block[64], int edflag;) 3 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. 3 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. 3 Return_Value pointer Pointer to the encrypted password. 2 endgrent Closes the group database when processing is complete. Format #include void endgrent (void); 3 Description The endgrent function closes the group database. This function is always successful. No value is returned, and errno is not set. 2 endpwent Closes the user database and any private stream used by getpwent. Format #include void endpwent (void); 3 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. 2 endwin Clears the terminal screen and frees any virtual memory allocated to Curses data structures. Format #include void endwin (void); 3 Description A program that calls Curses functions must call the endwin function before exiting to restore the previous environment of the terminal screen. 2 erand48 Generates uniformly distributed pseudorandom-number sequences. Returns 48-bit nonnegative, double-precision, floating-point values. Format #include double erand48 (unsigned short int xsubi[3]); 3 Argument xsubi An array of three short ints, which form a 48-bit integer when concatenated together. 3 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. 3 Return_Value n A nonnegative, double-precision, floating- point value. 2 [w]erase Erases the window by painting it with blanks. The erase function acts on the stdscr window. Format #include int erase(); int werase (WINDOW *win); 3 Argument win A pointer to the window. 3 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). 3 Return_Values OK Indicates success. ERR Indicates an error. 2 erf Returns the error function of its argument. Format #include 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) 3 Argument x A radian expressed as a real number. 3 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. 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. 2 execl Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execl (const char *file_spec, const char *arg0, . . . , (char *)0); (ISO POSIX-1) int execl (char *file_spec, . . . ); (Compatibility) 3 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. 3 Description To understand how the exec functions operate, consider how the OpenVMS system calls any Compaq 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 Compaq 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. 3 Return_Value -1 Indicates failure. 2 execle Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execle (char *file_spec, char *arg0, . . . , (char *)0, char *envp[]); (ISO POSIX-1) int execle (char *file_spec, . . . ); (Compatibility) 3 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. 3 Description See execl for a description of how the exec functions operate. 3 Return_Value -1 Indicates failure. 2 execlp Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execlp (const char *file_name, const char *arg0, . . . , (char *)0); (ISO POSIX-1) int execlp (char *file_name, . . . ); (Compatibility) 3 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. 3 Description See execl for a description of how the exec functions operate. 3 Return_Value -1 Indicates failure. 2 execv Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execv (char *file_spec, char *argv[]); 3 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. 3 Description See execl for a description of how the exec functions operate. 3 Return_Value -1 Indicates failure. 2 execve Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execve (const char *file_spec, char *argv[], char *envp[]); 3 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. 3 Description See execl for a description of how the exec functions operate. 3 Return_Value -1 Indicates failure. 2 execvp Passes the name of an image to be activated in a child process. This function is nonreentrant. Format #include int execvp (const char *file_name, char *argv[]); 3 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. 3 Description See execl for a description of how the exec functions operate. 3 Return_Value -1 Indicates failure. 2 exit,_exit Terminate execution of the program from which they are called. These functions are nonreentrant. Format #include void exit (int status); #include void _exit (int status); 3 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 HP OpenVMS Command Definition, Librarian, and Message Utilities Manual. To get POSIX behavior, include 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. 3 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. 2 exp Returns the base e raised to the power of the argument. Format #include 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) 3 Argument x A real value. 3 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 header file to be the largest possible floating-point value. 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. 2 exp2 Returns the value of 2 raised to the power of the argument. This function is OpenVMS Alpha and Integrity servers only. Format #include double exp2 (double x); float exp2f (float x); long double exp2l (long double x); ) 3 Argument x A real value. 3 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 header file to be the largest possible floating-point value. 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. 2 fabs Returns the absolute value of its argument. Format #include double fabs (double x); float fabsf (float x); (Integrity servers, Alpha) long double fabsl (long double x); (Integrity servers, Alpha) 3 Argument x A real value. 3 Return_Value x The absolute value of the argument. 2 fchmod Changes file access permissions. Format #include int fchmod (int fildes, mode_t mode); 3 Arguments fildes An open file descriptor. mode The bit pattern that determines the access permissions. 3 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. 3 Return_Values 0 Indicates that the mode is successfully changed. -1 Indicates that the change attempt has failed. 2 fchown Changes the owner and group of a file. Format #include int fchown (int fildes, uid_t owner, gid_t group); 3 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. 3 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. 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. 2 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 int fclose (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be closed. 3 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. 3 Return_Values 0 Indicates success. EOF Indicates that the file control block is not associated with an open file. 2 fcntl Performs controlling operations on an open file. Format #include #include #include int fcntl (int file_desc, int request [, int arg]); int fcntl (int file_desc, int request [, struct flock *arg]); 3 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. 3 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 , 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 , 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 . 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 , 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 , 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. 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. 2 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 Compaq C RTL. Format #include char *fcvt (double value, int ndigits, int *decpt, int *sign); 3 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. 3 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. 3 Return_Value x A pointer to the converted string. 2 fdim Determines the positive difference between its arguments. This function is OpenVMS Alpha and Integrity servers only. Format #include double fdim (double x, double y); float fdimf (float x, float y); long double fdiml (long double x, long double y); 3 Argument x A real value. y A real value. 3 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. 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. 2 fdopen Associates a file pointer with a file descriptor returned by an open, creat, dup, dup2, or pipe function. Format #include FILE *fdopen (int file_desc, char *a_mode); 3 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). 3 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. 3 Return_Values pointer Indicates that the operation has succeeded. NULL Indicates that an error has occurred. 2 feof Tests a file to see if the end-of-file has been reached. Format #include int feof (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 Return_Values nonzero integer Indicates that the end-of-file has been reached. 0 Indicates that the end-of-file has not been reached. 2 feof_unlocked Same as feof, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int feof_unlocked (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values nonzero integer Indicates end-of-file has been reached. 0 Indicates end-of-file has not been reached. 2 ferror Returns a nonzero integer if an error occurred while reading or writing a file. Format #include int ferror (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 Description A call to ferror continues to return a nonzero integer until the file is closed or until clearerr is called. 3 Return_Values 0 Indicates success. nonzero integer Indicates that an error has occurred. 2 ferror_unlocked Same as ferror, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int ferror_unlocked (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values 0 Indicates success. nonzero integer Indicates that an error has occurred. 2 fflush Writes out any buffered information for the specified file. Format #include int fflush (FILE *file_ptr); 3 Argument file_ptr A file pointer. If this argument is a NULL pointer, all buffers associated with all currently open files are flushed. 3 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 Compaq 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. 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. 2 ffs Finds the index of the first bit set in a string. Format #include int ffs (int iteger); 3 Argument integer The integer to be examined for the first bit set. 3 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). 3 Return_Values x The index of the first bit set. 0 If index is 0. 2 fgetc Returns the next character from a specified file. Format #include int fgetc (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be accessed. 3 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. 3 Return_Values x The returned character. EOF Indicates the end-of-file or an error. 2 fgetc_unlocked Same as the fgetc function, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int fgetc_unlocked (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values n The returned character. EOF Indicates the end-of-file or an error. 2 fgetname Returns the file specification associated with a file pointer. Format #include char *fgetname (FILE *file_ptr, char *buffer, . . . ); 3 Function_Variants The fgetname function has variants named _fgetname32 and _ fgetname64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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). 3 Return_Values n The address of the buffer. 0 Indicates an error. 3 Restriction The fgetname function is specific to the Compaq C RTL and is not portable. 2 fgetpos Stores the current file position for a given file. Format #include int fgetpos (FILE *stream, fpos_t *pos); 3 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. 3 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. 3 Return_Values 0 Indicates successful completion. -1 Indicates that there are errors. 3 Example #include #include 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); } } 2 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 char *fgets (char *str, int maxchar, FILE *file_ptr); 3 Function_Variants The fgets function has variants named _fgets32 and _fgets64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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. 3 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. 3 Example #include #include #include 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") ; } 2 fgetwc Reads the next character from a specified file, and converts it to a wide-character code. Format #include wint_t fgetwc (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be accessed. 3 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. 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. 2 fgetws Reads a line of wide characters from a specified file. Format #include wchar_t *fgetws (wchar_t *wstr, int maxchar, FILE *file_ptr); 3 Function_Variants The fgetws function has variants named _fgetws32 and _fgetws64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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. 3 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. 3 Example #include #include #include #include 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"); } 2 fileno Returns the file descriptor associated with the specified file pointer. Format #include int fileno (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 Description If you are using version 5.2 or lower of the C compiler, undefine the fileno macro: #if defined(fileno) #undef fileno #endif 3 Return_Values x Integer file descriptor. -1 Indicates an error. 2 finite Returns the integer value 1 (True) when its argument is a finite number, or 0 (False) if not. This function is OpenVMS Alpha and Integrity servers only. Format #include int finite (double x); int finitef (float x); int double finitel (long double x); 3 Argument x A real value. 3 Description The finite functions return 1 when -Infinity < x < +Infinity. They return 0 when |x| = Infinity, or x is a NaN. 2 flockfile Locks a stdio stream. This function is OpenVMS Alpha and Integrity servers only. Format #include void flockfile (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 2 floor Returns the largest integer less than or equal to the argument. Format #include double floor (double x); float floorf (float x); (Integrity servers, Alpha) long double floorl (long double x); (Integrity servers, Alpha) 3 Argument x A real value. 3 Return_Value n The largest integer less than or equal to the argument. 2 fma Computes (x * y) + z, rounded as one ternary operation. This function is OpenVMS Alpha and Integrity servers only. Format #include 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); 3 Argument x,y,z Real values. 3 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. 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. 2 fmax Returns the maximum numeric value of its arguments. This function is OpenVMS Alpha and Integrity servers only. Format #include double fmax (double x, double y); float fmaxf (float x, float y); long double fmaxl (long double x, long double y); 3 Argument x A real value. y A real value. 3 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. 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. 2 fmin Returns the minimum numeric value of its arguments. This function is OpenVMS Alpha and Integrity servers only. Format #include double fmin (double x, double y); float fminf (float x, float y); long double fminl (long double x, long double y); 3 Argument x A real value. y A real value. 3 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. 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. 2 fmod Computes the floating-point remainder. Format #include 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) 3 Arguments x A real value. y A real value. 3 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. 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. 2 fopen Opens a file by returning the address of a FILE structure. Format #include 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) 3 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 Compaq 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 Compaq 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. 3 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, Compaq 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. 3 Return_Values x File pointer. NULL Indicates an error. The constant NULL is defined in the 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 2 fp_class Determines the class of IEEE floating-point values. This function is OpenVMS Alpha and Integrity servers only. Format #include int fp_class (double x); int fp_classf (float x); int fp_classl (long double x); 3 Argument x An IEEE floating-point number. 3 Description The fp_class functions determine the class of the specified IEEE floating-point number, returning a constant from the 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 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) 3 Return_Value x A constant from the header file. 2 fpathconf Retrieves file implementation characteristics. Format #include long int fpathconf (int filedes, int name); 3 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. 3 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 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. 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. 2 fprintf Performs formatted output to a specified file. Format #include int fprintf (FILE *file_ptr, const char *format_spec, . . . ); 3 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. 3 Example An example of a conversion specification follows: #include 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. 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. 2 fputc Writes a character to a specified file. Format #include int fputc (int character, FILE *file_ptr); 3 Arguments character An object of type int. file_ptr A file pointer. 3 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. 3 Return_Values x The character written to the file. Indicates success. EOF Indicates an output error. 2 fputc_unlocked Same as the fputc function, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int fputc_unlocked (int character, FILE *file_ptr); 3 Arguments character The character to be written. An object of type int. file_ptr A file pointer. 3 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. 3 Return_Values n The returned character. EOF Indicates the end-of-file or an error. 2 fputs Writes a character string to a file without copying the string's null terminator (\0). Format #include int fputs (const char *str, FILE *file_ptr); 3 Arguments str A pointer to a character string. file_ptr A file pointer. 3 Description Unlike puts, the fputs function does not append a new-line character to the output string. See also puts. 3 Return_Values Nonnegative value Indicates success. EOF Indicates an error. 2 fputwc Converts a wide character to its corresponding multibyte value, and writes the result to a specified file. Format #include wint_t fputwc (wint_t wc, FILE *file_ptr); 3 Arguments wc An object of type wint_t. file_ptr A file pointer. 3 Description The fputwc function writes a wide character to a file and returns the character. See also putwc. 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. 2 fputws Writes a wide-character string to a file without copying the null-terminating character. Format #include int fputws (const wchar_t *wstr, FILE *file_ptr); 3 Arguments wstr A pointer to a wide-character string. file_ptr A file pointer. 3 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. 3 Return_Values Nonnegative value Indicates success. -1 Indicates an error. The function sets errno. For a list of the values, see fputwc. 2 fread Reads a specified number of items from the file. Format #include size_t fread (void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr); 3 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. 3 Description The type size_t is defined in the header file 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. 3 Return_Values n The number of bytes read divided by size_of_ item. 0 Indicates the end-of-file or an error. 2 free Makes available for reallocation the area allocated by a previous calloc, malloc, or realloc call. Format #include void free (void *ptr); 3 Argument ptr The address returned by a previous call to malloc, calloc, or realloc. If ptr is a NULL pointer, no action occurs. 3 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 Compaq C RTL have declared free to return an int, the implementation of free does return 0 on success and -1 on failure. 2 freopen Substitutes the filenamed by a file specification for the open file addressed by a file pointer. The latter file is closed. Format #include FILE *freopen (const char *file_spec, const char *a_mode, FILE *file_ptr, . . . ); 3 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. 3 Description The freopen function is typically used to associate one of the predefined names stdin, stdout, or stderr with a file. 3 Return_Values file_ptr The file pointer, if freopen is successful. NULL Indicates an error. 2 frexp Calculates the fractional and exponent parts of a floating-point value. Format #include 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) 3 Arguments value A floating-point number of type double, float, or long double. eptr A pointer to an int where frexp places the exponent. 3 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. 3 Example #include 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. 3 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. 2 fscanf Performs formatted input from a specified file, interpreting it according to the format specification. Format #include int fscanf (FILE *file_ptr, const char *format_spec, . . . ); 3 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. 3 Description An example of a conversion specification follows: #include 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. 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. 2 fseek Positions the file to the specified byte offset in the file. Format #include int fseek (FILE *file_ptr, long int offset, int direction); 3 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. 3 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. 3 Return_Values 0 Indicates successful seeks. -1 Indicates improper seeks. 2 fseeko Positions the file to the specified byte offset in the file. Equivalent to fseek. Format #include int fseeko (FILE *file_ptr, off_t offset, int direction); 3 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. 3 Description The fseeko function is identical to the fseek function, except that the offset argument is of type off_t instead of long int. 2 fsetpos Sets the file position indicator for a given file. Format #include int fsetpos (FILE *stream, const fpos_t *pos); 3 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. 3 Description Call the fgetpos function before using the fsetpos function. 3 Return_Values 0 Indicates success. -1 Indicates an error. 2 fstat Accesses information about the file specified by the file descriptor. Format #include int fstat (int file_desc, struct stat *buffer); 3 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. 3 Arguments file_desc A file descriptor. buffer A pointer to a structure of type stat_t, which is defined in the 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 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 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 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. 3 Return_Values 0 Indicates successful completion. -1 Indicates an error other than a protection violation. -2 Indicates a protection violation. 2 fstatvfs Gets information about a device containing the specified file. This function is OpenVMS Alpha and Integrity servers only. Format #include int fstatvfs (int filedes, struct statvfs *buffer); 3 Arguments filedes File descriptor obtained from a successful open or fcntl function call. buffer Pointer to a statvfs structure to hold the returned information. 3 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 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. 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. 2 fsync Flushes data all the way to the disk. Format #include int fsync (int fd); 3 Argument fd A file descriptor corresponding to an open file. 3 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. 3 Return_Values 0 Indicates successful completion. -1 Indicates an error. 2 ftell Returns the current byte offset to the specified stream file. Format #include long int ftell (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values n The current offset. EOF Indicates an error. 2 ftello Returns the current byte offset to the specified stream file. This function is equivalent to ftell. Format #include off_t ftello (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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 2 ftime Returns the elapsed time since 00:00:00, January 1, 1970, in the structure pointed at by timeptr. Format #include int ftime (struct timeb *timeptr); 3 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. 3 Argument timeptr A pointer to the structure timeb_t. 3 Description The typedef timeb_t refers to the following structure defined in the 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. 3 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. 2 ftok Generates a standard interprocess communication key that is usable in subsequent calls to semget. This function is OpenVMS Alpha and Integrity servers only. Format #include key_t ftok (const char *path_name, int project_id); 3 Argument path_name the pathname of an existing file that is accessible to the process. project_id a value that uniquely identifies a project. 3 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. 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. 2 ftruncate Truncates a file to a specified length. Format #include int ftruncate (int filedes, off_t length); 3 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 3 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. 3 Return_Values 0 Indicates success. -1 An error occurred; errno is set to indicate the error. 2 ftrylockfile Acquires ownership of a stdio (FILE*) object. This function is OpenVMS Alpha and Integrity servers only. Format #include int ftrylockfile (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values 0 Indicates success. nonzero Indicates the lock cannot be acquired. 2 ftw Walks a file tree. Format #include int ftw (const char *path, int(*function)(const char *, const struct stat *, int), int depth); 3 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. 3 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 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 header file on your system for more information. o The ftw function supports UNIX style path name specifications. See also malloc, longjump, and stat. 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. 2 funlockfile Unlocks a stdio stream. This function is OpenVMS Alpha and Integrity servers only. Format #include void funlockfile (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 2 fwait Waits for I/O on a specific file to complete. Format #include int fwait (FILE *fp); 3 Argument fp A file pointer corresponding to an open file. 3 Description The fwait function is used primarily to wait for completion of pending asynchronous I/O. 3 Return_Values 0 Indicates successful completion. -1 Indicates an error. 2 fwide Determines and sets the orientation of a stream. Format #include int fwide (FILE *stream, int mode); 3 Arguments stream A file pointer. mode A value that specifies the desired orientation of the stream. 3 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. 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. 2 fwprintf Writes output to the stream under control of the wide-character format string. Format #include int fwprintf (FILE *stream, const wchar_t *format, . . . ); 3 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. 3 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 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. 3 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 #include #include /* . . . */ 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)); 2 fwrite Writes a specified number of items to the file. Format #include size_t fwrite (const void *ptr, size_t size_of_item, size_t number_items, FILE *file_ptr); 3 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. 3 Description The type size_t is defined in the header file 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. 3 Return_Value x The number of items written. The number of records written depends upon the maximum record size of the file. 2 fwscanf Reads input from the stream under control of the wide-character format string. Format #include int fwscanf (FILE *stream, const wchar_t *format, . . . ); 3 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. 3 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. 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. 2 gcvt Converts its argument to a null-terminated string of ASCII digits and returns the address of the string. Format #include char *gcvt (double value, int ndigit, char *buffer); 3 Function_Variants The gcvt function has variants named _gcvt32 and _gcvt64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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. 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. 3 Return_Value x The address of the buffer. 2 getc Returns the next character from a specified file. Format #include int getc (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be accessed. 3 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. 3 Return_Values n The returned character. EOF Indicates the end-of-file or an error. 2 getc_unlocked Same as getc, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int getc_unlocked (FILE *file_ptr); 3 Argument file_ptr A file pointer. 3 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. 3 Return_Values n The returned character. EOF Indicates the end-of-file or an error. 2 [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 char getch(); char wgetch (WINDOW *win); 3 Argument win A pointer to the window. 3 Description The getch and wgetch functions refresh the specified window before fetching a character. For more information, see the scrollok function. 3 Return_Values x The returned character. ERR Indicates that the function makes the screen scroll illegally. 2 getchar Reads a single character from the standard input (stdin). Format #include int getchar (void); 3 Description The getchar function is identical to fgetc(stdin). See also getchar_unlocked. 3 Return_Values x The next character from stdin, converted to int. EOF Indicates the end-of-file or an error. 2 getchar_unlocked Same as getchar, except used only within a scope protected by flockfile and funlockfile. This function is OpenVMS Alpha and Integrity servers only. Format #include int getchar_unlocked (void); 3 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. 3 Return_Values x The next character from stdin, converted to int. EOF Indicates the end-of-file or an error. 2 getclock Gets the current value of the systemwide clock. Format #include int getclock (int clktyp, struct timespec *tp); 3 Arguments clktyp The type of systemwide clock. tp Pointer to a timespec structure space where the current value of the systemwide clock is stored. 3 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 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 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) */ }; 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. 2 getcwd Returns a pointer to the file specification for the current working directory. Format #include char *getcwd (char *buffer, size_t size); (ISO POSIX-1) char *getcwd (char *buffer, unsigned int size, . . . ); (DEC C Extension) 3 Function_Variants The getcwd function has variants named _getcwd32 and _getcwd64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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). 3 Return_Values x A pointer to the file specification. NULL Indicates an error. 2 getdtablesize Gets the total number of file descriptors that a process can have open simultaneously. Format #include int getdtablesize (void); 3 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 Compaq 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. 3 Return_Values x The number of file descriptors that a process can have open simultaneously. -1 Indicates an error. 2 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 gid_t getegid (void); 3 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. 3 Return_Value x The effective group ID (POSIX IDs enabled), or the group number from the UIC (POSIX IDs disabled). 2 getenv Searches the environment array for the current process and returns the value associated with a specified environment name. Format #include char *getenv (const char *name); 3 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. 3 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. 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. 2 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 uid_t geteuid (void); 3 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 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 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. 3 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). 2 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 gid_t getgid (void); 3 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. 3 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. 2 getgrent Gets a group database entry. This function is OpenVMS Alpha and Integrity servers only. Format #include struct group *getgrent (void); 3 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. 3 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. 2 getgrgid Gets a group database entry for a group ID. This function is OpenVMS Alpha and Integrity servers only. Format #include #include struct group *getgrgid (gid_t gid); 3 Argument gid The group ID of the group for which the group database entry is to be retrieved. 3 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. 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. 2 getgrgid_r Gets a group database entry for a group ID. This function is OpenVMS Alpha and Integrity servers only. Format #include #include int getgrgid_r (gid_t gid, struct group *grp, char *buffer, size_t bufsize, struct group **result); 3 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. 3 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. 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. 2 getgrnam Gets a group database entry for a name. This function is OpenVMS Alpha and Integrity servers only. Format #include #include struct group *getgrnam (const char *name); 3 Argument name The group name of the group for which the group database entry is to be retrieved. 3 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. 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. 2 getgrnam_r Gets a group database entry for a name. This function is OpenVMS Alpha and Integrity servers only. Format #include #include int getgrnam_r (const char *name, struct group *grp, char *buffer, size_t bufsize, struct group **result); 3 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. 3 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. 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. 2 getgroups Gets the current supplementary group IDs of the calling process. Format #include int getgroups (int gidsetsize, gid_t grouplist[]); 3 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. 3 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. 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. 2 getitimer Returns the value of interval timers. Format #include int getitimer (int which, struct itimerval *value); 3 Arguments which The type of interval timer. The Compaq 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. 3 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 Compaq C RTL provides each process with one interval timer, defined in the header file as ITIMER_REAL. This timer decrements in real time and delivers a SIGALRM signal when the timer expires. 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.) 2 getlogin Gets the login name. Format #include char *getlogin (void); int *getlogin_r (char *name, size_t namesize); 3 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. 3 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. 2 getname Returns the file specification associated with a file descriptor. Format #include char *getname (int file_desc, char *buffer, . . . ); 3 Function_Variants The getname function has variants named _getname32 and _getname64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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). 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). 3 Return_Values x The address passed in the buffer argument. 0 Indicates an error. 2 getopt A command-line parser that can be used by applications that follow UNIX command-line conventions. Format #include (X/Open, POSIX-1) #include (X/Open, POSIX-2) int getopt (int argc, char * const argv[], const char *optstring); extern char *optarg; extern int optind, opterr, optopt; 3 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. 3 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. 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. 3 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 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 2 getpagesize Gets the system page size. Format #include int getpagesize (void); 3 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. 3 Return_Value x Always indicates success. Returns the number of bytes in a page. 2 getpgid Gets the process group ID for a process. This function is OpenVMS Alpha and Integrity servers only. Format #include pid_t getpgid (pid_t pid); 3 Argument pid The process ID for which the group ID is being requested. 3 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. 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. 2 getpgrp Gets the process group ID of the calling process. This function is OpenVMS Alpha and Integrity servers only. Format #include pid_t getpgrp (void); 3 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. 3 Return_Values x The process group ID of the calling process. 2 getpid Returns the process ID of the current process. Format #include pid_t getpid (void); 3 Return_Value x The process ID of the current process. 2 getppid Returns the parent process ID of the calling process. Format #include pid_t getppid (void); 3 Return_Values x The parent process ID. 0 Indicates that the calling process does not have a parent process. 2 getpwent Accesses user entry information in the user database, returning a pointer to a passwd structure. Format #include struct passwd *getpwent (void); 3 Function_Variants The getpwent function has variants named __32_getpwent and __64_getpwent for use with 32-bit and 64-bit pointer sizes, respectively. 3 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 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. 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. 2 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 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) 3 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. 3 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. 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 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. 3 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. 3 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 // getuid() #include // getpwuid_r() #include #include #include #include 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. 2 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 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) 3 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. 3 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. 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 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. 3 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. 2 gets Reads a line from the standard input (stdin). Format #include char *gets (char *str); 3 Function_Variants The gets function has variants named _gets32 and _gets64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Argument str A pointer to a character string that is large enough to hold the information fetched from stdin. 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. 3 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. 2 getsid Gets the process group ID of the session leader. This function is OpenVMS Alpha and Integrity servers only. Format #include pid_t getsid (pid_t pid); 3 Argument pid The process ID of the process whose session leader process group ID is being requested. 3 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. 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. 2 [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 int getstr (char *str); int wgetstr (WINDOW *win, char *str); 3 Arguments win A pointer to the window. str Must be large enough to hold the character string fetched from the window. 3 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. 3 Return_Values OK Indicates success. ERR Indicates that the function makes the screen scroll illegally. 2 gettimeofday Gets the date and time. Format #include int gettimeofday (struct timeval *tp, void *tzp); 3 Arguments tp Pointer to a timeval structure, defined in the header file. tzp A NULL pointer. If this argument is not a NULL pointer, it is ignored. 3 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. 3 Return_Values 0 Indicates success. -1 An error occurred. errno is set to indicate the error. 2 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 uid_t getuid (void); 3 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 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 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. 3 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). 2 getw Returns characters from a specified file. Format #include int getw (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be accessed. 3 Description The getw function returns the next four characters from the specified input file as an int. 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. 2 getwc Reads the next character from a specified file, and converts it to a wide-character code. Format #include wint_t getwc (FILE *file_ptr); 3 Argument file_ptr A pointer to the file to be accessed. 3 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. 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. 2 getwchar Reads a single wide character from the standard input (stdin). Format #include wint_t getwchar (void); 3 Description The getwchar function is identical to fgetwc(stdin). 3 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. 2 getyx Puts the (y,x) coordinates of the current cursor position on win in the variables y and x. Format #include getyx (WINDOW *win, int y, int x); 3 Arguments win Must be a pointer to the window. y Must be a valid lvalue. x Must be a valid lvalue. 2 glob Returns a list of existing files for a user supplied pathname (with optional wildcards). This function is OpenVMS Alpha and Integrity servers only. Format #include int glob (const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob); 3 Function_Variants The glob function has variants named _glob32 and _glob64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 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 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. 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 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 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. 3 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. 2 globfree Frees any space associated with the pglob argument resulting from a previous call to the glob function. Format #include void globfree (glob_t *pglob); 3 Function_Variants The globfree function has variants named _globfree32 and _ globfree64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Argument pglob Pointer to a previously allocated glob_t structure. 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. 2 gmtime Converts time units to the broken-down UTC time. Format #include struct tm *gmtime (const time_t *timer); struct tm *gmtime_r (const time_t *timer, struct tm *result); (ISO POSIX-1) 3 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. 3 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 header, and is also shown in tm Structure in the description of localtime. 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 Compaq 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. 3 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. 2 gsignal Generates a specified software signal, which invokes the action routine established by a signal, ssignal, or sigvec function. Format #include int gsignal (int sig [, int sigcode]); 3 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 header file. 3 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 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. 3 Return_Values 0 Indicates a sig argument that is outside the range defined in the 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. 2 hypot Returns the length of the hypotenuse of a right triangle. Format #include 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) 3 Arguments x A real value. y A real value. 3 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. 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. 2 iconv Converts characters coded in one codeset to characters coded in another codeset. Format #include size_t iconv (iconv_t cd, const char **inbuf, size_t *inbytesleft, char **outbuf, size_t *outbytesleft); 3 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. 3 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. 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. 2 iconv_close Deallocates a specified conversion descriptor and the resources allocated to the descriptor. Format #include int iconv_close (iconv_t cd); 3 Argument cd The conversion descriptor to be deallocated. A conversion descriptor is returned by a successful call to iconv_open. 3 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. 2 iconv_open Allocates a conversion descriptor for a specified codeset conversion. Format #include iconv_t iconv_open (const char *tocode, const char *fromcode); 3 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 HP C RTL Reference Manual for information on obtaining a list of currently available codesets or for details on adding new codesets. 3 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. 3 Example #include #include #include 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)) == (iconv_t) - 1) { /* 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); } 2 ilogb Returns the exponent part of its argument. This function is OpenVMS Alpha and Integrity servers only. Format #include int ilogb (double x); int ilogbf (float x); int ilogbl (long double x); 3 Argument x A real value. 3 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 . 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. 2 [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 char inch(); char winch (WINDOW *win); 3 Argument win A pointer to the window. 3 Return_Values x The returned character. ERR Indicates an input error. 2 index Searches for a character in a string. Format #include char *index (const char *s, int c); 3 Function_Variants The index function has variants named _index32 and _index64 for use with 32-bit and 64-bit pointer sizes, respectively. 3 Arguments s The string to search. c The character to search for. 3 Description The index function is identical to the strchr function, and is provided for compatibility with some UNIX implementations. 2 initscr Initializes the terminal-type data and all screen functions. You must call initscr before using any of the curses functions. Format #include void initscr (void); 3 Description The OpenVMS Curses version of the initscr function clears the screen before doing the initialization. The BSD-based Curses version does not. 2 initstate Initializes random-number generators. Format #include char *initstate (unsigned int seed, char *state, int size); 3 Arguments seed An initial seed value. state Pointer to an array of state information. size The size of the state information array. 3 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. 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. 2 [w]insch Insert a character at the current cursor position in the specified window. The insch function acts on the stdscr window. Format #include int insch (char ch); int winsch (WINDOW *win, char ch); 3 Arguments win A pointer to the window. ch The character to be inserted. 3 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. 3 Return_Values OK Indicates success. ERR Indicates that the function makes the screen scroll illegally. 2 [w]insertln Insert a line above the line containing the current cursor position. The insertln function acts on the stdscr window. Format #include int insertln(); int winsertln (WINDOW *win); 3 Argument win A pointer to the window. 3 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. 3 Return_Values OK Indicates success. ERR Indicates that the function makes the screen scroll illegally. 2 [w]insstr Insert a string at the current cursor position in the specified window. The insstr function acts on the stdscr window. Format #include int insstr (char *str); int winsstr (WINDOW *win, char *str); 3 Arguments win A pointer to the window. str A pointer to the string to be inserted. 3 Description Each character after the string shifts to the right, and the last character disappears. These functions are specific to Compaq C for OpenVMS Systems and are not portable. 3 Return_Values OK Indicates success. ERR Indicates that the function makes the screen scroll illegally. For more information, see the scrollok function. 2 isalnum Indicates if a character is classed either as alphabetic or as a digit in the program's current locale. Format #include int isalnum (int character); 3 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. 3 Return_Values nonzero If alphanumeric. 0 If not alphanumeric. 2 isalpha Indicates if a character is classed as an alphabetic character in the program's current locale. Format #include int isalpha (int character); 3 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. 3 Return_Values nonzero If alphabetic. 0 If not alphabetic. 2 isapipe Indicates if a specified file descriptor is associated with a pipe. Format #include int isapipe (int file_desc); 3 Argument file_desc A file descriptor. 3 Description For more information about pipes, see the "Subprocess Functions" chapter of the HP C RTL Reference Manual. 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). 2 isascii Indicates if a character is an ASCII character. Format #include int isascii (int character); 3 Argument character An object of type char. 3 Return_Values nonzero If ASCII. 0 If not ASCII. 2 isatty Indicates if a specified file descriptor is associated with a terminal. Format #include int isatty (int file_desc); 3 Argument file_desc A file descriptor. 3 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). 2 iscntrl Indicates if a character is classed as a control character in the program's current locale. Format #include int iscntrl (int character); 3 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. 3 Return_Values nonzero If a control character. 0 If not a control character. 2 isdigit Indicates if a character is classed as a digit in the program's current locale. Format #include int isdigit (int character); 3 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. 3 Return_Values nonzero If a decimal digit. 0 If not a decimal digit. 2 isgraph Indicates if a character is classed as a graphic character in the program's current locale. Format #include int isgraph (int character); 3 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. 3 Return_Values nonzero If a graphic character. 0 If not a graphic character. 2 islower Indicates if a character is classed as a lowercase character in the program's current locale. Format #include int islower (int character); 3 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. 3 Return_Values nonzero If a lowercase alphabetic character. 0 If not a lowercase alphabetic character. 2 isnan Test for a NaN. Returns 1 if the argument is NaN; 0 if not. This function is OpenVMS Alpha and Integrity servers only. Format #include int isnan (double x); int isnanf (float x); int isnanl (long double x); 3 Argument x A real value. 3 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). 2 isprint Indicates if a character is classed as a printing character in the program's current locale. Format #include int isprint (int character); 3 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. 3 Return_Values nonzero If a printing character. 0 If not a printing character. 2 ispunct Indicates if a character is classed as a punctuation character in the program's current locale. Format #include int ispunct (int character); 3 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. 3 Return_Values nonzero If a punctuation character. 0 If not a punctuation character. 2 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 int isspace (int character); 3 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. 3 Return_Values nonzero If a white-space character. 0 If not a white-space character. 2 isupper Indicates if a character is classed as an uppercase character in the program's current locale. Format #include int isupper (int character); 3 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. 3 Return_Values nonzero If an uppercase alphabetic character. 0 If not an uppercase alphabetic character. 2 iswalnum Indicates if a wide character is classed either as alphabetic or as a digit in the program's current locale. Format #include (ISO C) #include (XPG4) int iswalnum (wint_t wc); 3 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. 3 Return_Values nonzero If alphanumeric. 0 If not alphanumeric. 2 iswalpha Indicates if a wide character is classed as an alphabetic character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswalpha (wint_t wc); 3 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. 3 Return_Values nonzero If alphabetic. 0 If not alphabetic. 2 iswcntrl Indicates if a wide character is classed as a control character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswcntrl (wint_t wc); 3 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. 3 Return_Values nonzero If a control character. 0 If not a control character. 2 iswctype Indicates if a wide character has a specified property. Format #include (ISO C) #include (XPG4) int iswctype (wint_t wc, wctype_t wc_prop); 3 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. 3 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. 3 Return_Values nonzero If the character has the property wc_prop. 0 If the character does not have the property wc_prop. 3 Example #include #include #include #include #include #include /* 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 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 2 iswdigit Indicates if a wide character is classed as a digit in the program's current locale. Format #include (ISO C) #include (XPG4) int iswdigit (wint_t wc); 3 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. 3 Return_Values nonzero If a decimal digit. 0 If not a decimal digit. 2 iswgraph Indicates if a wide character is classed as a graphic character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswgraph (wint_t wc); 3 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. 3 Return_Values nonzero If a graphic character. 0 If not a graphic character. 2 iswlower Indicates if a wide character is classed as a lowercase character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswlower (wint_t wc); 3 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. 3 Return_Values nonzero If a lowercase character. 0 If not a lowercase character. 2 iswprint Indicates if a wide character is classed as a printing character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswprint (wint_t wc); 3 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. 3 Return_Values nonzero If a printing character. 0 If not a printing character. 2 iswpunct Indicates if a wide character is classed as a punctuation character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswpunct (wint_t wc); 3 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. 3 Return_Values nonzero If a punctuation character. 0 If not a punctuation character. 2 iswspace Indicates if a wide character is classed as a space character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswspace (wint_t wc); 3 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. 3 Return_Values nonzero If a white-space character. 0 If not a white-space character. 2 iswupper Indicates if a wide character is classed as an uppercase character in the program's current locale. Format #include (ISO C) #include (XPG4) int iswupper (wint_t wc); 3 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. 3 Return_Values nonzero If an uppercase character. 0 If not an uppercase character. 2 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 (ISO C) #include (XPG4) int iswxdigit (wint_t wc); 3 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. 3 Return_Values nonzero If a hexadecimal digit. 0 If not a hexadecimal digit. 2 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 int isxdigit (int character); 3 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. 3 Return_Values nonzero If a hexadecimal digit. 0 If not a hexadecimal digit. 2 j0,j1,jn Compute Bessel functions of the first kind. This function is OpenVMS Alpha and Integrity servers only. Format #include 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); 3 Arguments x A real value. n An integer. 3 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. 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. 2 jrand48 Generates uniformly distributed pseudorandom-number sequences. Returns 48-bit signed, long integers. Format #include long int jrand48 (unsigned short int xsubi[3]); 3 Argument xsubi An array of three short ints that form a 48-bit integer when concatenated together. 3 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. 3 Return_Value n Signed, long integers uniformly distributed over the range -231 2 kill Sends a signal to the process specified by a process ID. Format #include int kill (int pid, int sig); 3 Arguments pid The process ID. sig The signal code. 3 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 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. 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. 2 l64a Converts a long integer to a character string. This function is OpenVMS Alpha and Integrity servers only. Format #include char *l64a (long l); 3 Argument l A long integer that is to be converted to a character string. 3 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. 3 Return_Value x Upon successful completion