Open System Services Programmer’s Guide Abstract The Open System Services Programmer’s Guide describes how to write software applications for the OSS environment. Emphasis is on the C and C++ programming languages.
© Copyright 1995, 2014 Hewlett-Packard Development Company, L.P. Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor’s standard commercial license. Warranty The information contained herein is subject to change without notice.
Contents About This Document...................................................................................15 About TNS, TNS/R Native, and TNS/E Native Processes............................................................15 About the Examples................................................................................................................15 About OSS Utilities.................................................................................................................
Physical and Logical Names................................................................................................53 Filename and Pathname Mappings......................................................................................54 Obtaining Corresponding Guardian and OSS Filenames........................................................56 Using Guardian Procedures................................................................................................57 OSS File-Access Permissions........
OSS Process Pairs.................................................................................................................158 OSS Process Pairs Overview..............................................................................................158 OSS Process Pair Considerations........................................................................................158 OSS Process Pair Creation................................................................................................
Accessing Terminals From the OSS Environment...................................................................210 Blocking and Nonblocking Opens.....................................................................................210 Blocking and Nonblocking Terminal I/O............................................................................211 Terminal Parameters.........................................................................................................211 Control Characters...............
Access Check Algorithm...................................................................................................266 ACL Operations Supported...............................................................................................266 ACL Interaction with stat()..................................................................................................266 ACL Interaction with chmod().............................................................................................
Converting 32-Bit Applications to 64-Bit Applications................................................................307 Step 1: Identify Programs that Need to be Compiled in the LP64 Data Model..........................307 Step 2: Identify Non-Portable Constructs..............................................................................307 Step 3: Using the C/C++ Compiler to Identify Needed Source Code Changes........................307 Step 4: Compile in the LP64 Data Model.............................
Using Thread-Aware $RECEIVE Functions............................................................................373 Caveats to Using Thread-Aware $RECEIVE..........................................................................376 Thread-Aware Enscribe Functions............................................................................................376 Using Thread-Aware Enscribe Functions..............................................................................
Build Scripts....................................................................................................................424 Header Files....................................................................................................................424 Standard and Nonstandard Pthread Types..........................................................................425 Global Variables.............................................................................................................
Figures 1 2 3 4 5 6 7 8 9 The Operating Environment for NonStop Systems.................................................................27 OSS Filenames and Disks..................................................................................................29 Components of Guardian File Names.................................................................................30 Guardian File Names and Disks........................................................................................
39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 Guardian Procedure Calls Audited When Used for Process Control .....................................255 Base ACL Entries............................................................................................................262 Actual (Nondefault) Optional ACL Entries..........................................................................262 Default ACL Entries...................
10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 Starting the Visual Inspect Debugger..................................................................................49 Convert Type 180 File to Type 101 File................................................................................50 Convert Type 101 File to Type 180 File.....................................................................
64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 Handling the Synchronous Signal SIGINT..........................................................................322 Handling the SIGCHLD Signal.........................................................................................324 Handling SIGALRM Signals.............................................................................................
About This Document The Open System Services Programmer’s Guide describes how to write software applications for the OSS environment. Emphasis is on the C and C++ programming languages.
About OSS Utilities Hewlett-Packard Company is not responsible for the proper functioning of unsupported utilities or facilities and will not respond to product reports about them. Such utilities and facilities include those in the OSS /bin/unsupported directory. Use these utilities and facilities at your own risk. Supported Release Version Updates (RVUs) This manual supports J06.03 and all subsequent J-series RVUs, H06.03 and all subsequent H-series RVUs, and G06.
Changes Made to the 520574-021 Edition (February 2014) The following information was added and changed for the J06.17 and H06.
• ◦ “Functions Available for Security Management” (page 250) ◦ “What Operations and Objects Are Audited” (page 253) ◦ “Considerations for File Auditing” (page 255) ◦ “Using OSS Access Control Lists (ACLs)” (page 259) ◦ New “OSS SEEP Programming” (page 274) section Added information about the new HP NonStop Storage Management Foundation (SMF) features: ◦ “Accessing Files From the OSS API” (page 65) ◦ New “Accessing Files on SMF Logical Disk Volumes” (page 68) subsection The following informat
• • Added 64-bit shared-memory information to: ◦ “Using Shared Memory” (page 189) ◦ “Features Unique to OSS Interprocess Communication” (page 176) Added interprocess-communication information to: ◦ “OSS Interprocess-Communication Functions” (page 196) ◦ “Guardian Interprocess-Communication Procedures” (page 203) • Added Guardian I/O information to “Guardian I/O Management Procedures” (page 234) • Added the new “64-Bit Support in OSS and Guardian” (page 285) chapter.
Document Organization This guide contains the following sections and appendixes: • Chapter 1: Overview of the OSS Programming Environment (page 26) introduces the OSS and Guardian file systems and process types, discusses how to select source and target environments, describes how to call OSS functions and Guardian procedures and functions in OSS programs, and indicates the programming tools available.
UPPERCASE LETTERS Uppercase letters indicate keywords and reserved words. Type these items exactly as shown. Items not enclosed in brackets are required. For example: MAXATTACH Italic Letters Italic letters, regardless of font, indicate variable items that you supply. Items not enclosed in brackets are required. For example: file-name Computer Type Computer type letters indicate: • C and Open System Services (OSS) keywords, commands, and reserved words. Type these items exactly as shown.
| Vertical Line A vertical line separates alternatives in a horizontal list that is enclosed in brackets or braces. For example: INSPECT { OFF | ON | SAVEABEND } … Ellipsis An ellipsis immediately following a pair of brackets or braces indicates that you can repeat the enclosed sequence of syntax items any number of times.
Table 1 Related Manuals The following are related programming guides: • Availability Guide for Application Design. This manual introduces the various products and concepts involved in designing and writing applications with increased availability. It describes alternative approaches to application design and the benefits and compromises of different approaches, and it includes check lists on how to go about developing more available applications. • C/C++ Programmer’s Guide.
• Guardian Programmer’s Guide. This guide describes how to access the Guardian API using Guardian procedure calls. It is written for application and system programmers. • Open System Services Porting Guide. This guide describes conversion techniques for moving existing C-language applications into the OSS environment. It discusses both C-language and operating system considerations. This guide is intended for application programmers, with some information for selected operating system users.
HP Encourages Your Comments HP encourages your comments concerning this document. We are committed to providing documentation that meets your needs. Send any errors found, suggestions for improvement, or compliments to docsfeedback@hp.com. Include the document title, part number, and any comment, error found, or suggestion for improvement you have concerning this document.
1 Overview of the OSS Programming Environment OSS is an alternative to the Guardian interface through which users and programs can interact with the HP NonStop operating system. OSS interfaces and functions greatly resemble those of UNIX systems in general, because of their common relationship to the POSIX standards.
The OSS API An application program interface (API) is a set of functions or procedure calls that permits user programs to communicate with the operating system. The OSS API coexists on NonStop systems with the traditional Guardian interfaces, as shown in Figure 1. Figure 1 The Operating Environment for NonStop Systems An application program can be compiled to run in either the OSS or Guardian environment and can use services from each environment, including the API, tools, and utilities.
• An XPG4 function, such as those provided in the fnmatch.h, nl_types.h, and wchar.h header files. • An XPG4 function that is an extension to standard header files, such as getw() in stdio.h. • Any function related to OSS access control lists (ACLs) • Any function designed to interact with OSS files that are larger than approximately 2 gigabytes. These functions, often called 64-bit APIs or 64-bit functions, typically have the number 64 in the name (for example the open64() function).
Figure 2 OSS Filenames and Disks Open System Services manages the directory tree using filesets. A fileset is a directory tree that can be mounted or unmounted. Most literature about UNIX refers to filesets as file systems. In the OSS and Guardian environments, the term file system also refers to the software that manages the file system. OSS files and directories are designated by pathnames. A pathname is the string of characters that uniquely identifies a file within its file system.
All OSS regular (data) files are odd-unstructured files. OSS regular files can be accessed using Guardian functions and procedures as well as OSS functions. File Access Access to an OSS file or directory is determined by a set of permission bits associated with it. The file owner, groups the owner belongs to, and others each have read, write, or execute permission for a file. For filesets that support OSS ACLs, access to an OSS file or directory is determined by the ACL.
Figure 4 Guardian File Names and Disks Guardian files on the local node appear as OSS files in the /G directory of the OSS file system. The local node name is omitted. Guardian files on remote NonStop nodes also appear as OSS files in the /E directory of the OSS file system. The pathnames for such files begin with /E/nodename and continue with the /G directory on the indicated node.
Figure 5 Guardian Files in the OSS File System File Types Using OSS functions, you can read and write only odd-unstructured Guardian files. EDIT files are unstructured files, and you can access them only for reading. OSS functions cannot access structured Guardian files (SQL, entry-sequenced, key-sequenced, and relative). You can access structured Guardian files using Guardian procedure calls in an OSS program. File Access Guardian file access is determined by the RWEP character string.
Creator processes and the process run-time environment are defined differently for the two types of processes. In the OSS environment, methods for creating a new process are: • fork() creates a new OSS process, running the same program image as the calling process, in the same CPU. tdm_fork() is a variant of fork() that permits access to additional process attributes. • exec...() associates a new program image with the current OSS process. Functions in the exec...
from the OSS shell to suspend a job, all processes in the group associated with that job can receive the signal to stop. (Signals can be sent to an individual process or to an entire process group.) A Guardian process cannot belong to a process group or session, which is a collection of one or more process groups. Example 1 provides code to demonstrate the use of some of the OSS group information functions including getgrent(), endgrent(), setgrent(), getgrgid(), and getgrnam().
Example 1 Using Some OSS Group Information Functions #include #include #include #include #include #include #include #include struct group *gnam = NULL; gid_t grouplist[NGROUPS_MAX]; int gcnt; char groupname[32]; int main(int argc, char *argv[]) { int i; char **ptr; /* Get the group number or name from the command line. If no argument is provided, use the group number for the user.
Process Ancestors The creator process of an OSS process is the “parent” process of the newly created “child” process. The child process inherits many OSS and Guardian attributes of the parent process. The creator process of a Guardian process is the “MOM” process of the newly created process if the new process is unnamed. If the new process is named, the creator process is its “ancestor.
Selecting Source and Target Execution Environments Application program development takes place in the source environment and includes writing, compiling, and debugging code. Once developed, the application program runs in the target execution environment. The source and target execution environments are usually the same (OSS or Guardian environment), but there are some special cases in which they are different.
Guardian Procedures You can (and in some cases must) use Guardian procedures when you cannot accomplish a task with OSS functions. For example, to get the file code of a Guardian file, you must use a Guardian file system procedure, such as FILE_GETINFO_ or FILE_GETINFOBYNAME_. You also might want to use Guardian procedures in cases where the Guardian procedure provides more information. For example, FILE_GETINFOLIST_ provides much more information than the stat() function about Guardian or OSS files.
Example 2 Calling a Guardian Procedure That Returns a Return Value #include #include #include #include /* Note 1 */ char *filename; short typeinfo[5]; int main(int argc, char *argv[]) { short retcode, physreclen; /* Note 2 */ /* Get Guardian filename and pass it to the Guardian procedure. */ if(argc > 1) filename = argv[1]; else filename = "$system.system.
Note 3 You must insert a placeholder comma (,) if you omit optional parameters, unless you omit them from the end of the list. Omitted optional parameters contain default values, if they are defined. Procedures That Return a Condition Code Example 3 (page 41) calls the Guardian procedures FILE_OPEN_ and READX to open and read data from a Guardian file, which is provided as an input parameter to the procedure. FILE_OPEN_ returns a return value in retcode, and READX returns a condition code in CC.
Example 3 Calling a Guardian Procedure That Returns a Condition Code #include #include #include #include #include /* Note 1 */ _cc_status CC; /* Note 2 */ short filenum, bytesread, retcode; char *filename; char buffer[1024]; int main(int argc, char *argv[]) { int i; /* Get Guardian filename and open the file. */ if (argc > 1) filename = argv[1]; else filename = "$system.system.
Procedures That Return Both a Return Value and a Condition Code Procedures that return both a return value and a condition code cannot be called directly from an OSS program, so you must write a “jacket” procedure in pTAL that can be called from a C program. This jacket procedure can contain only the code required to call the desired Guardian procedure, and the jacket procedure must be callable from an OSS program. Most Guardian procedures, but not all, can be called from an OSS program.
The c89 or c99 utility is used to compile and link OSS programs. Example 4 compiles but does not link the source file gprog.c with a SYSTYPE of GUARDIAN. Example 4 Specifying the systype Option to the c89 Utility $ c89 -c -Wsystype=guardian gprog.c The result of Example 4 is an object file named gprog.o. Example 5 compiles the main OSS program and links it with the Guardian C module object file into an executable program file named outfile.
gtacl Utility Using the gtacl utility is another way to mix development environments. gtacl runs a process in the Guardian environment from the OSS environment and lets you use Guardian tools from the OSS shell. You can use gtacl to start an interactive TACL process, execute a single Guardian environment command, or run a Guardian environment program. Example 6 uses gtacl to run the TACL STATUS command.
TIP: The OSS Core Utilities User Commands appendix in the Open System Services User's Guide provides details for viewing the vim(1) reference page. C Development Utilities Open System Services provides a variety of tools to assist you in developing C applications. The following are some of the more useful programming tools: • ar, which creates and maintains groups of one or more named files as a single library file written in an archive format.
TIP: The OSS Core Utilities User Commands appendix in the Open System Services User's Guide provides details for viewing the OSS Core Utilities reference pages. Compilation Tools The c89 and c99 utilities control the C compilation system in the OSS environment. There are native versions of c89 and c99 for TNS/E systems, a native version of c89 for TNS/R systems, and a TNS version of c89 for TNS/R systems. (A TNS version of c89 is not supported on TNS/E systems).
For more information, see: Topic Manual c89 The C/C++ Programmer’s Guide and the c89(1) utility reference page either online or in the Open System Services Shell and Utilities Reference Manual c99 The C/C++ Programmer’s Guide and the c99(1) utility reference page either online or in the Open System Services Shell and Utilities Reference Manual nld The nld Manual and the nld(1) reference page either online or in the Open System Services Shell and Utilities Reference Manual ld The ld Manual and the l
native processes. The Native Inspect debugger is supported only on TNS/E systems, and supports debugging of native processes in the OSS and Guardian environments. The Native Inspect debugger is conceptually similar to the Inspect debuggers and has similar functionality, but has different syntax and commands. The Native Inspect syntax is based on gdb, a debugger that is widely used throughout the industry and is familiar to many application developers.
menus and dialog boxes. Using Visual Inspect, you control the execution and debugging of your program from a PC while the program runs on a NonStop server. Visual Inspect supports high-level symbolic debugging of native and TNS processes (interpreted and accelerated) in the Guardian and OSS environments through a PC-based graphical user interface. Visual Inspect can also be used for debugging snapshot files. Visual Inspect is supported on both G-series and H-series systems.
Editor TEDIT is a full-screen text editor. For information about TEDIT features and commands, see the PS Text Edit and PS Text Format User’s Guide. File-Type Conversion Tools TEDIT creates type 101 files. Files in the /G directory created with an OSS editor such as vi have a type of 180. If you have a type 180 file you want to edit with TEDIT, use the conversion tool CTOEDIT to convert the type 180 file to a type 101 file, as shown in Example 11.
Debuggers See the discussion about the Inspect, Native Inspect, NonStop Development Environment for Eclipse (NSDEE), and Visual Inspect products in “OSS Tools” (page 44). Measure Performance Analyzer The Measure product is a data collection and measurement tool that provides a wide range of performance statistics on system resources; Measure interfaces can be used from the Guardian environment to gather information on OSS objects.
Using the NonStop Development Environment for Eclipse The HP NonStop Development Environment for Eclipse (NSDEE) is a Windows-hosted integrated development environment for NonStop applications. NSDEE supports building NonStop applications locally using Windows-hosted cross-compilers and tools, or remotely using compilers and tools on a NonStop server.
2 Managing Files You access OSS files in the OSS environment as you would access UNIX files. The OSS environment also enables you to access files in the Guardian environment, which means that you can create applications for NonStop systems that use data in Guardian files and that take advantage of OSS portability and other OSS features. In the OSS environment, sockets, pipes, FIFOs, and terminals are also files. These files are discussed elsewhere in this guide.
The OSS file system theoretically allows an unlimited degree of nesting of directories within a directory. You can have subdirectories in a directory, subsubdirectories in a subdirectory, and so on. The Guardian environment allows only three levels in a node: volume, subvolume, and file ID. You cannot have nesting; therefore, you cannot have a volume that is within another volume. Filename and Pathname Mappings The /G directory contains Guardian files, but they are referred to by OSS pathnames.
The pathname /G/volname/subvol/fileid of a permanent Guardian disk file is translated to the filename \NODE.$VOLNAME.SUBVOL.FILEID. The pathname /G/volname/#num of a temporary Guardian disk file is translated to \NODE.$VOLNAME.#num. With relative pathnames, the name component . (dot) is deleted. The pathname ./subvol/fileid is treated as /G/volname/subvol/fileid. If a relative pathname contains the name component .. (dot-dot), the preceding name component is deleted.
Table 5 Guardian Filename to OSS Pathname Translation Examples (continued) Guardian Filename OSS Pathname $p.#PTY12 /G/p/#pty12 $pubs.henry.panaceas /G/pubs/henry/panaceas Obtaining Corresponding Guardian and OSS Filenames You can obtain the Guardian filename that corresponds to an OSS pathname and vice-versa with OSS shell utilities, the Guardian File Utility Program (FUP), or through programmatic interfaces.
Example 14 Using pname to Obtain an OSS Pathname $ pname \$VOL.ZYQ00000.Z0000DV3 pname: $VOL.ZYQ00000.Z0000DV3 --> /home/henrysp/test $ pname \\node.\$VOL.ZYQ00000.Z0000DV3 pname: \node.$VOL.ZYQ00000.Z0000DV3 --> /home/henrysp/test $ pname -s \$VOL.ZYQ00000.Z0000DV3 /home/henrysp/test $ pname -s '$VOL.ZYQ00000.
Example 16 Using the Guardian PATHNAME_TO_FILENAME_ Procedure #include #include #include #include char filename[64]; short filelen; short status; int main(int argc, char *argv[]) { short ret; /* Make sure the correct number of arguments are entered. If not, print usage message and exit. */ if(argc < 2) { fprintf(stderr,"Usage: pthtofil pathname\n"); exit (1); } /* Invoke the Guardian procedure call. Note the special format for options.
Example 17 Using the Guardian FILENAME_TO_PATHNAME_ Procedure Guardian FILENAME_TO_PATHNAME procedure */ #include #include #include #include #include #include char pathname[PATH_MAX]; short pathlen; short index = 0; int main(int argc, char *argv[]) { short ret; /* Make sure the correct number of arguments are entered. If not, print a usage message and exit.
Example 18 Using FILE_COMPLETE_SET_, FILE_COMPLETE_, and FILE_COMPLETE_GETINFO_ /* Guardian FILE_COMPLETE_* procedures */ #include #include #include #include #include #include #include #include #include .h>
/* Set the completion elements for the OSS file and the Guardian file */ comp_elem[0].z_fnum_fd = fd; /* OSS file */ comp_elem[0].u_z_options.z_options.z_filetype = 1; comp_elem[0].u_z_options.z_options.z_read_ready = 1; comp_elem[0].u_z_options.z_options.z_exception = 1; comp_elem[1].z_fnum_fd = filenum; /* Guardian file */ comp_elem[1].u_z_options.z_options.
&bytesread, &request_tag ); /* number of bytes read */ /* request tag */ /* If the condition code returned is not the one for success, print a message and exit. */ if(_status_ne(CC)) { /* check the success condition code */ fprintf(stderr, "Awaitiox failed.\n"); exit(1); } printf("Bytes read = %d\n", bytesread); /* Print out the first ten bytes in octal plus "string".
Mappings of OSS file-access permissions to Guardian security are based on user information and are not predictable based only on file permission information. OSS file-access permissions do not reflect: • Safeguard access control lists (ACLs). To determine whether there is an Safeguard ACL on a Guardian file, use the Guardian FILE_GETINFOLISTBYNAME_ procedure. • OSS ACLs.
OSS ACLs and NFS Clients OSS ACLs are not supported by the OSS Network File System (NFS) for J06.08 and earlier J-series RVUs, H06.19 and earlier H-series RVUs, or G-series RVUs. Any attempt by NFS clients to access OSS objects protected by OSS ACLs that contain optional ACL entries is denied. OSS ACLs are supported by the OSS NFS for J06.09 and later J-series RVUs and H06.
Common and Unique Characteristics The OSS file system looks like a typical UNIX file system, but there are a few important differences. Features Common to the UNIX and OSS File Systems The OSS file system conforms to the POSIX.1 specification. There is no major difference between the OSS file system and most UNIX file systems. There are some differences in the particulars of some functions.
Odd-unstructured files and EDIT files are opened as OSS regular files. If you want your application to modify odd-unstructured Guardian files, or if your application uses data stored in odd-unstructured Guardian files or EDIT files, you can use the interoperability capabilities of the OSS environment and access these files with OSS functions. If you need to modify EDIT files or open structured files, you can use Guardian procedures as described in “Accessing Files From the Guardian API” (page 68).
Example 19 Reading a Guardian File With an OSS Function Call #include #include #include #include char buffer[1026]; char *filename; int fd; int nbytes; /* /* /* /* allow for NULL termination of string in buffer */ filename pointer */ file descriptor */ number of bytes read */ int main(int argc, char *argv[]) { /* Check for the proper number of arguments; if no filename is supplied, open the default file.
Example 20 Using fopen_guardian() in an OSS Module /* Verify current process is an OSS process */ #ifndef _OSS_TARGET #error “Wrong systype” #endif #include int main (int argc, char *argv[]) { FILE *G_File; FILE *P_File; int c; /* Open the Guardian file, note that since this is an OSS process, need to explicitly call a version of fopen()that opens a Guardian file. */ G_File = fopen_guardian ("$system.system.stdioh", "r"); /* Because this is an OSS process, we get the OSS fopen() by default.
OSS files can also be managed from the Guardian API. You would use Guardian procedures to access OSS files when you need to perform operations that use the nowait feature of the Guardian environment. Nowait I/O is the ability of an application process to continue executing in parallel with read and write operations; the application process runs concurrently with the I/O operation. The OSS environment uses waited I/O, where an application process is suspended during read and write operations.
Guardian Procedure Extensions for OSS HP provides extensions to Guardian procedures so that you can use them with OSS files. The extensions are summarized in Table 9 (page 100).
Example 21 Reading an OSS File in Nowait Mode With Guardian Procedures /* Reading an OSS file in Nowait Mode with Guardian Procedures */ #include #include #include #include #include #include
/* The program can execute code while the read operation is being completed by the system. */ for (i = 0; i < 100000; i++) ; printf("Now issuing AWAITIOX to wait for I/O completion.\n"); /* AWAITIOX completes the READX operation. */ CC = AWAITIOX(&filenum, /* file number */ , &bytesread, /* number of bytes read */ &request_tag, /* request tag */ ); /* If the condition code returned is not the one for success, print a message and exit.
Example 22 Reading an OSS File With Guardian Procedures #include #include #include #include #include _cc_status CC; short filenum, bytesread, retcode; char *pathname; char buffer[1025]; /* allow for NULL-terminated string */ int main(int argc, char *argv[]) { int i; /* If no pathname is supplied, use the default name. */ if (argc > 1) pathname = argv[1]; else pathname = "/usr/include/stdio.h"; /* Invoke the Guardian procedure.
Using Extended Guardian Procedures Example 23 shows the use of the extended Guardian procedure FILE_GETINFOBYNAME_ to get information about an OSS file whose pathname is provided as input to the program.
Example 23 Using a Guardian Procedure to Get OSS File Information by Name #include #include #include #include char *pathname; char filename[64]; short filelen; short status; short typeinfo[5]; short flags; int main(int argc, char *argv[]) { short retcode, physreclen; /* If no pathname is supplied, get information about the default file. */ if(argc > 1) pathname = argv[1]; else pathname = "/usr/include/stdio.
if(typeinfo[0] == 3) { printf("object type = %d\n", typeinfo[2]); printf("file type = %d\n", typeinfo[3]); printf("file code = %d\n", typeinfo[4]); } return(0); } Example 24 shows the use of the Guardian FILE_OPEN_ and FILE_GETINFO_ procedures to get information about an OSS file. The file is opened, and the file number is passed to the FILE_GETINFO_ procedure.
Example 24 Using a Guardian Procedure to Get OSS File Information by Number /* Using a Guardian Procedure to Get OSS File info by Number*/ #include #include #include #include short typeinfo[5]; char filename[64]; char *pathname; int main(int argc, char *argv[]) { short filenum, filelen, retcode, lasterror; /* If no pathname is supplied, open the default file. */ if(argc > 1) pathname = argv[1]; else pathname = "/usr/include/stdio.
if(typeinfo[0] == 3) { printf("object type = %d\n", typeinfo[2]); printf("file type = %d\n", typeinfo[3]); printf("file code = %d\n", typeinfo[4]); } return(0); } Accessing OSS Files Larger Than 2 GB Small Files and Large Files For RVUs earlier than H06.06 and G06.29, OSS files always had an underlying Guardian file format of Format 1 and were limited in size to approximately 2 GB (GB). This size limitation was a direct result of using 32-bit data types for file sizes and offsets. For J-series RVUs, H06.
execution when Guardian APIs are used. For more information, see “Compatibility Issue For Guardian Files Created by OSS APIs” (page 82) • Can be accessed using 64-bit APIs such as creat64() and open64() only: ◦ An application can explicitly call the 64-bit version of a function when you use the #define _LARGEFILE64_SOURCE 1 feature test macro or an equivalent compiler command option to compile the application.
The existing Native C run-time library APIs modified to be large file safe are: fclose() fflush() fgetc() fgetpos() fgets() fgetwc() fgetws() fopen_oss() fprintf() fputc() fputs() fputwc() fputws() fread() freopen_oss() fwrite() fscanf() fseek() fsetpos() ftell() getc() getchar() gets() getw() getwc() getws() getwchar() printf() putc() putchar() puts() putw() putws() putwchar() scanf() vfprintf() vprintf() In addition, HP supports two new 32-bit LFS APIs, fseeko() and ftello(), because fseek() and ftell() u
An application can explicitly call a 64-bit function when you use the #define _LARGEFILE64_SOURCE 1 feature test macro or an equivalent compiler command option to compile the application. An application call to interface() is automatically mapped to the interface64() function when you use the #define _FILE_OFFSET_BITS 64 feature test macro or an equivalent compiler command option to compile the application.
Interoperability Opening OSS Files Applications running on systems that do not include support for OSS large files can use either OSS or Enscribe APIs to open any OSS file smaller than approximately 2 GB, even if that file is on a system that includes support for OSS large files. HP does not support OSS opens of OSS files larger than approximately 2 GB on systems that do not include support for OSS large files.
Guardian applications that use file data and ignore file attributes are unaffected if all of these conditions are true: • The application is running on J-series RVUs, H06.06 or later H-series RVUs, or G06.29 or later G-series RVUs. • The Format 2 file is unstructured, code 180 with an EOF less than the Format 1 limit of approximately 4 GB. However, FILE_OPEN_ fails with error 580 if any of these conditions are true: • The RVU is earlier than G06.29 or H06.
• Directory-search authorization errors • Requestor's SOA privileges The OSS SEEP is not consulted for: • Search authorization on the directories in the path • /E and /G directories NFS operations are not supported on filesets that are OSS SEEP-protected: • An attempted NFS mount of a directory that belongs to an OSS SEEP-protected fileset is denied with an EPERM error. • An attempted NFS operation on an OSS SEEP-protected fileset is denied with an EPERM error.
#include #include #include char *fifo[3] = { "fifo-1", "fifo-2", "fifo-3" }; char *ofile[3] = { "ofile-1", "ofile-2", "ofile-3" }; fd_set m_rfds; fd_set s_rfds; int maxfdp1; int rd[3]; int fd[3]; int nrd[3]; int nread; int totread; int sumread; char buf[3][512]; /* up to 3 named pipes */ /* up to 3 output files */ /* /* /* /* /* /* /* /* /* /* master set of fd_set values */ fd_set values used by select */ Max.
nrd[i] = -1; /* set end-of-file marker */ } sumread += totread; } while(totread); printf("Total bytes read from files = %d\n", sumread); return(EXIT_SUCCESS); /* write of all fifos done */ } /* Execute parent program to read the named pipes using the select() function and non-blocking I/O */ printf("Parent process code started.
NOTE: Some of these actions affect the configuration of the fileset or of the disk volume and are not controlled by the application. • Minimize the number of open operations such as open() and opendir(). • Minimize the use of pipes and FIFOs between processors. • Minimize the use of AF_UNIX sockets between processes. • Minimize the use of shared opens (more than one process sharing an open file descriptor) between processors.
FTIOMODE, NORMALIOMODE, Performance, and Fault Tolerance The value used for the FTIOMODE and NORMALIOMODE options affect application performance and fault tolerance. Fault tolerance for files opened without using the O_SYNC bit is controlled by the NORMALIOMODE option setting; fault tolerance for files opened using the O_SYNC bit is controlled by the FTIOMODE option setting. NOTE: HP recommends that the S_NONSTOP extension not be used in new applications.
Performance and Reliability Tradeoffs As Table 7 shows, you must choose between performance and reliability in OSS file I/O. The higher the reliability, the slower the performance. For example, if you cannot afford to lose any file I/O operations, you should set the FTIOMODE and NORMALIOMODE attribute to UNBUFFEREDCP.
OSS File-System Functions Table 8 (page 91) displays information about each OSS function that you can use to manage files. The columns of the table contain the following: OSS Function The name of the function and a brief description. OSS Notes Notes about the OSS implementation of the function. The note “Can return extended errors” means that the function can return errors that are HP extensions to the XPG4 specification. Refer to the function’s reference page for further information.
Table 8 OSS File-System Functions OSS Function OSS Notes Guardian Notes access() Determines the accessibility of a file. Can return extended errors. FDM set. OSS SEEP consultation. Not all the Guardian information can be summarized here; for example, there are several security restrictions. For Guardian information, refer to the reference pages. chdir() Can return extended errors. Changes the current working directory. Can return Guardian file-system error numbers in errno. OSS SEEP consultation.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Guardian Notes user ID as the owner of the file or the super ID. For files in restricted-access filesets, see “Restricted-Access Filesets and File Privileges” (page 270). Can return extended errors. Can return Guardian file-system error numbers in errno. OSS SEEP consultation. chroot() Changes the effective root directory. Can return extended errors. FDM set. OSS SEEP consultation.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Closes a stream. Can return ENXIO, whose value is an optional extension defined in the XPG4 specification but is not defined in the POSIX standards. fcntl() Controls open file descriptors. Does not return EDEADLK. Guardian Notes Access to the file through a Guardian Advisory record locking is supported procedure call cannot be blocked by only for regular files; attempts on other an OSS lock.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Guardian Notes fstat64() can access both small files and large files. fstatvfs() fstatvfs64() Gets fileset information for an open file. Can return extended errors. fsync() Writes modified data and file attributes to permanent storage. Can return extended errors. ftruncate() ftruncate64() Changes file length. Can return extended errors. FDM set. Can return Guardian file-system error numbers in errno.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes lseek() lseek64() Sets the file offset for read or write operations. If called for nonseekable device, errno is set to EINVAL, except for pipes and FIFOs, in which case errno is set to EISPIPE. Guardian Notes Can return extended errors. Can return Guardian file-system error numbers in errno. lseek64() can access both small files and large files. lstat() lstat64() Provides information about a symbolic link or any file.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Guardian Notes nftw64() can access both small files do not affect the outcome of a call to nftw(). and large files. open() Many flags are implementation defined. open64() Opens a file for reading or writing or Can return extended errors. creates a file in the OSS environment. Can return Guardian file-system error numbers in errno. open64() can access both small files and large files. FDM set.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Guardian Notes The return of EOF from a device special file has no effect on subsequent read() calls. If nbytes > SSIZE_MAX, -1 is returned and errno is set to EINVAL. Can return extended errors. Can return Guardian file-system error numbers in errno. readdir() readdir64() Refer to opendir(). Can return extended errors.
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes Guardian Notes This call sets errno to EBUSY when the directory is a mount point. Can return extended errors. OSS SEEP consultation. scandir() scandir64() can access both small scandir64() files and large files. Scans a directory and builds an array of pointers to copies of selected directory entries. seekdir() Can return extended errors. Sets the position in a directory stream. If, after a call to fork() or Refer to opendir().
Table 8 OSS File-System Functions (continued) OSS Function OSS Notes telldir() Returns the current location of a directory stream. Can return extended errors. ulimit() Sets and gets file size limits. Can return extended errors. Guardian Notes The error EINVAL is returned when the second parameter is too large. umask() Sets and gets the value of the file mode creation mask. unlink() Removes a directory entry. The calling process requires both FDM set.
Guardian File-System Procedures Table 9 displays information about each Guardian procedure that you can use to manage files. Procedures that have been superseded by other procedures are not shown. The columns of the table contain the following: Guardian Procedure The name of the procedure and a brief description. OSS Notes Additional considerations or restrictions when the Guardian procedure is used on OSS files. For details about a procedure, refer to the Guardian Procedure Calls Reference Manual.
Table 9 Guardian File-System Procedures (continued) Guardian Procedure OSS Notes 32-bit addresses as well. Extends the capabilities of the CONTROLBUF procedure. FILE_CREATE_ Creates a Guardian disk file specifying commonly used disk file properties. Fails with file-system error 1163 when the file is an OSS file. FILE_CREATELIST_ Creates a Guardian disk file specifying properties in addition to commonly used disk file properties. Fails with file-system error 1163 when the file is an OSS file.
Table 9 Guardian File-System Procedures (continued) Guardian Procedure OSS Notes 64-bit extended addresses, but it can be used with 32-bit addresses as well. Extends the capabilities of the LOCKREC procedure. FILE_OPEN_ Opens a file. Set options. <10> to 1 to open an OSS file by its OSS pathname.OSS files can be opened only with shared exclusion mode. See also “Accessing OSS Files Larger Than 2 GB” (page 78). OSS SEEP consultation, beginning with the J06.15 and H06.26 RVUs.
Table 9 Guardian File-System Procedures (continued) Guardian Procedure OSS Notes for use with 64-bit extended addresses, but it can be used with 32-bit addresses as well. Extends the capabilities of the REPLYXL procedure. FILE_SETMODENOWAIIT64_ Beginning with the H06.24 and J06.13 RVUs, used to set device-dependent functions in a nowait manner on nowait files. The FILE_SETMODENOWAIT64_ procedure is intended for use with 64-bit extended addresses, but it can be used with 32-bit addresses as well.
Table 9 Guardian File-System Procedures (continued) Guardian Procedure OSS Notes FILENAME_FINDNEXT64_ Beginning with the H06.24 and J06.13 RVUs, returns the next name in a set of named entities that was defined by a call to the FILENAME_FINDSTART_ procedure. The FILENAME_FINDNEXT64_ procedure is intended for use with 64-bit extended addresses, but it can be used with 32-bit addresses as well. Extends the capabilities of the FILENAME_FINDNEXT_ procedure.
3 Managing Processes You can create, control, and terminate OSS processes as you would in a standard UNIX environment. In addition to the standard set of UNIX process-management functions, there are several HP extension functions that provide flexibility in propagating attributes during process creation. OSS processes have a full set of Guardian attributes as well as OSS-specific attributes.
Process Creation Functions You can create OSS processes with the fork() function. The attributes of the parent process are propagated to the child process, and the child process has an OSS process ID that uniquely identifies it. An OSS process can send signals to and receive signals from other OSS processes. You can query and modify the process environment using functions such as getpid() and putenv().
Example 26 Dynamic Launcher Program /* dlaunch1.c * * Simple OSS example using OSS socket APIs for communication * between requester and server. * * dlaunch1 (dynamic launcher 1) is an inetd-like program which * accepts socket connections and exec's a dserver process for * each connection. * * dserver reads stdin and echoes to stdout. dlaunch1 and dserver * write progress messages and error messages to stderr. * * dlaunch1 and the multiple dserver processes run on the same cpu.
if (bind(fd, (const struct sockaddr *)&addr, sizeof(addr)) < 0) { fprintf(stderr, "bind() call failed [errno %d]\n", errno); exit(1); } /* make the socket a listening socket */ if (listen(fd, 5) < 0) { fprintf(stderr, "listen() call failed [errno %d]\n", errno); exit(1); } /* fd usage * 0 stdin * 1 stdout * 2 stderr * 3 listenfd * */ - not used by dlaunch1, set up for dserver not used by dlaunch1, set up for dserver used by dlaunch1 for messages, inherited by dserver used by dlaunch1 for connections, not
/* we are grandchild ... exec server process with stdin * and stdout set to connection and stderr set to * launcher's stderr */ execv(".
Example 27 Dynamic Echo Server Program /* dserver.c * * Simple OSS server example using OSS APIs for communication * between requester and server. * * dserver is a dynamic echo server. A dserver process is launched * for each requester. dserver reads stdin and echoes on stdout. * dserver exits when idle for 60 seconds. */ #include #include #include #include #include #include #include #include
cpu, STDIN_FILENO, errno); exit(1); } else if (bytesread == 0) /* check for input closed */ { ffprintf(stderr, "dserver [cpu %d] - " "stopping [input closed]\n", cpu); exit(1); } else /* data received */ { /* give progress message */ msg_buff[bytesread] = '\0'; /* guarantee string NULL-terminated */ fprintf(stderr, "dserver [cpu %d] - " "message received on fd %d = %s", cpu, STDIN_FILENO, msg_buff); /* echo on stdout */ if (write(STDOUT_FILENO, msg_buff, bytesread) < 0) { fprintf(stderr, "dserver [cpu %d] -
Example 28 Determining and Changing Process Priority using getpriority() and nice() #include #include #include #include #include #include #include
printf("New nice value = %d\n", pval); pval = getpri(PRIO_PROCESS, 0); printf("Process priority set to %d\n", pval); return(0); } Features Unique to OSS Process Management • OSS processes have an OSS process ID and a process handle. An OSS process ID is a nonnegative integer that uniquely identifies a process within a node. A process handle is a data structure ten words long that uniquely identifies a process within a NonStop network. • There are HP extension functions.
for the fields in the input structure that contains Guardian attributes. Examples of these attribute fields are pe_cpu (processor), pe_debug_options (debug options), and pe_hometerm (home terminal). Some Guardian attributes are more important for you to manipulate than others. The following lists the attributes you might want to set when you create a process using the OSS HP extension functions.
Table 10 OSS and Guardian Process Attribute Comparison (continued) Process Attribute Guardian user ID OSS group ID OSS parent process ID OSS process ID OSS user ID Part of an OSS Process? Part of a Guardian Process? Always Always Always Always Always Always Always Never Never Always Never Always Always Never Sometimes Sometimes Sometimes Never Always Sometimes Program type Guardian OSS Terminals Guardian home terminal OSS controlling terminal nice scheduling priority Process-Management Interoper
Table 11 Guardian Process-Management Procedures That Can Access OSS Processes (continued) Guardian Procedure Description PROCESS_SPAWN_ Creates an OSS process PROCESS_STOP_ Terminates a process PROCESS_SUSPEND_ Places a process into a suspended state PROCESSHANDLE_COMPARE_ Compares two process handles and reports whether they are identical, represent different processes of the same process pair, or are different PROCESSHANDLE_DECOMPOSE_ Returns one or more parts of a process handle PROCESSHANDLE
Table 12 OSS Process-Management Functions That Can Access Guardian Processes (continued) OSS Function Description getegid() Gets the effective group ID of the calling process getenv() Returns the value of an environment variable geteuid() Gets the effective user ID of the calling process getgid() Gets the real group ID of the calling process getgroups() Gets the group list of the calling process getsid() Gets the group ID of the process that is the session leader of the specified process getui
Signals Interoperability Signals are software interrupts that provide a way of handling asynchronous events, such as a user at a terminal typing an interrupt key, timer expiration, detection of a hardware fault, or abnormal termination of a process. Using Standard Signals Functions Both OSS processes and Guardian native processes can send, receive, and handle signals using the functions in the OSS API, which conform to the POSIX.1 standard.
For information about how to use these functions, see the Guardian Programmer’s Guide. Examples in the following subsections show how to manage processes with both the OSS and Guardian APIs. For information about OSS functions, see the Open System Services System Calls Reference Manual and the Open System Services Library Calls Reference Manual. For information about Guardian procedures, see the Guardian Procedure Calls Reference Manual.
Example 29 Creating an OSS Process Using tdm_fork() and tdm_execvep() #include #include #include #include #include #include #include /* Note 1 */ /* Set defaults for input and output structures.
} else if (pid == 0) { /* child process executing */ printf("trying execute of %s\n", buf); printf("argv[0]=%s,argv[1]=%s,argv[2]=%s\n", argv[0],argv[1],argv[2]); /* Supply a name and processor number for the child process. */ procext.pe_name_options = _TPC_NAME_SUPPLIED; /* Note 3 */ procext.pe_process_name = "/G/HEINZ"; /* set process name */ procext.pe_cpu = 1; /* set processor number */ /* Pass parameter values to the child process.
Example 30 Creating an OSS Process Using tdm_spawnp() #include #include #include #include #include #include #include #include /* Note 1 */
procresults.pr_pid); fprintf(stderr, "procresults.pr_errno = %o\n", procresults.pr_errno); fprintf(stderr, "procresults.pr_TPCerror = %o\n", procresults.pr_TPCerror); fprintf(stderr, "procresults.pr_TPCdetail = %o\n", procresults.pr_TPCdetail); fprintf(stderr, "errno = %d\n", errno); fprintf(stderr, "couldn't spawn: %s\n", buf); } /* The parent process waits for the child process to terminate.
Example 31 Creating and Controlling a Guardian Process Using Guardian Procedures #include #include #include #include #include #include #include /* Initialize input parameter structure to default values. */ process_launch_parms_def proc_param = P_L_DEFAULT_PARMS_; /* Process results structure.
/* Reactivate the child process. */ retcode = PROCESS_ACTIVATE_ ((short *)&proc_results.z_phandle, ); if (retcode != 0) { fprintf(stderr, "Process activate failure, code = %d\n", retcode); exit(1); } printf("Process %s activated for 10 seconds\n", proc_name); sleep(10); /* wait ten seconds */ /* Terminate the child process. */ retcode = PROCESS_STOP_ ((short *)&proc_results.
Monitoring OSS Processes Reading Guardian System Messages A Guardian parent process must monitor an OSS child process by reading Guardian system messages from $RECEIVE. (An OSS parent process could monitor its child process by reading Guardian system messages, but it would be very unusual.
Example 32 Creating an OSS Process Using PROCESS_SPAWN_ /* Example 3-7 Creating an OSS Process using PROCESS_SPAWN_ */ #include #include #include #include #include #include #include #include #include #include #include
} return (err); } /* * This procedure returns nonzero if the specified OSS PID identifies * an existing process. Process handle is retrieved as a test.
fdentry[2].z_dupfd = -1; fdentry[2].z_name = errpath; fdentry[2].z_oflag = O_RDWR; fdentry[2].z_mode = 0755; /* Dummy inheritance structure */ inherit.
Using the OSS API OSS functions provide information about process times (times()), environment variables (getenv()), user IDs (getuid(), geteuid()), groups and group IDs (getgroups(), getgid(), getegid()), and system limits (sysconf()) for OSS and Guardian processes. Because Guardian processes do not have OSS process IDs and cannot belong to process groups, the getpid(), getppid(), and getpgrp() functions operate only on OSS processes.
Using the Guardian API The Guardian procedures that provide information about OSS processes as well as Guardian processes are PROCESS_GETINFO_ and PROCESS_GETINFOLIST_. Beginning with the H06.24 and J06.13 RVUs, additional 64-bit process attributes are available. For information about 64-bit process attributes, see “New PROCESS_GETINFOLIST_ Attributes” (page 287).
Example 34 Getting Information About a Process Using PROCESS_GETINFO_ #include #include #include #include #include
swapfile, 64, &swaplen, &errordetail, &proctype, &osspid ); /* /* /* /* /* /* swap filename */ maximum length */ length of swap filename */ details of any errors */ process type (1=OSS,0=Guardian) */ OSS process ID, if type=1 */ /* If unsuccessful, print error message and exit.
Example 35 Getting Information About a Process Using PROCESS_GETINFOLIST_ #include #include #include #include #include #include
srch_option, , , , , osspid ); /* /* /* /* /* /* search for OSS process */ attribute codes used in search */ number of attributes used */ match values found */ length of list returned */ OSS process ID */ /* If unsuccessful, print error message and exit.
processes do not have OSS process IDs and cannot belong to process groups or sessions, the setsid() and setpgid() functions operate only on OSS processes. Example 36 sets the user ID of the current process to the user ID of the user whose name is supplied at the command line. This program must be run using the super ID. Example 36 Setting the User ID of the Current Process Using setuid() #include #include #include #include #include
Example 37 Modifying Information About the Current Process Using PROCESS_SETINFO_ and PROCESS_SETSTRINGINFO_ /* Modifying info about the current process using PROCESS_SETINFO_ and */ /* PROCESS_SETSTRINGINFO_ (works on H-series RVUs only) */ #include #include #include #include
Note 1 You can get the name of a terminal using the ttyname() function or the tty command. OSS terminal names are in the format /G/ztnt/#pty00nn. The PROCESS_SETINFO_ procedure requires the Guardian form of a terminal name, which is in the format: • $ZTN0.#PTY00xx for systems running G-series RVUs. • $ZTNT.#PTY00xx for systems running H-series RVUs. To convert from an OSS pathname format to a Guardian filename format, use the PATHNAME_TO_FILENAME_ procedure.
dserver [cpu 1] - stopping [input closed] dlaunch2 stopping - timeout while the terminal running the copy of requester2 might show: /users/chris: ./requester2 Requester starting ?hello 1 Read 8 bytes back from server ?goodbye 1 Read 10 bytes back from server ?/users/chris: .
Example 38 Dynamic Launcher Program to Spawn Dynamic Server /* dlaunch2.c * * Simple OSS example using OSS socket APIs for communication * between requester and server. * * dlaunch2 (dynamic launcher 2) is an inetd-like program which * accepts socket connections and spawn's a dserver process for * each connection. * * dserver reads stdin and echoes to stdout. dlaunch2 and dserver * write progress messages and error messages to stderr. * * dlaunch2 starts the dserver processes run on different cpus.
fprintf(stderr, "socket() call failed [errno %d]\n", errno); exit(1); } /* Get server port from the command line or use default 12345 */ if (argc > 1) addr.sin_port = (short)atoi(argv[1]); /* use command line arg */ else addr.sin_port = 12345; /* use default */ addr.sin_family = AF_INET; /* internet address family */ addr.sin_addr.
/* flexible than exec */ /* find next available cpu */ do { cpuindex = (++cpuindex == cpucount) ? 0 : cpuindex; } while (((cpumask >> (15-cpuindex)) & 1) == 0); peparm.pe_cpu = cpuindex; inherit.flags = 0; if ((newpid = fork()) < 0) { fprintf(stderr, "fork() failed [errno %d]\n", errno); exit(1); } else if (newpid == 0) { /* we are child ...
Example 39 Launcher Program to Spawn Static Servers /*slaunch1.c * Simple OSS example using OSS sockets APIs for communication * between requester and server. * * slaunch1 (static launcher 1) is an inetd-like program which * starts an sserver (static server) process on each available cpu * and then passes each incoming socket connection to a sserver process. * * slaunch1 and sserver write progress messages and error messages * to stderr.
/* get process handle and cpu number */ PROCESSHANDLE_GETMINE_(phandle); PROCESSHANDLE_DECOMPOSE_(phandle, &cpu); /* print startup message */ fprintf(stderr, "slaunch1 starting in cpu %d\n", cpu); /* create AF_INET stream socket */ if ((fd = socket(AF_INET, SOCK_STREAM, 0)) < 0) { fprintf(stderr, "socket() call failed [errno %d]\n", errno); exit(1); } /* Get server port from the command line or use default 12345 */ if (argc > 1) addr.sin_port = (short)atoi(argv[1]); /* use command line arg */ else addr.
fprintf(stderr, "sserver spawn'ed in cpu %d\n", peparm.pe_cpu); if ((newpid = fork()) < 0) { fprintf(stderr, "fork() failed [errno %d]\n", errno); exit(1); } else if (newpid == 0) { /* we are child ...
/* find next available server */ do { cpuindex = (++cpuindex == cpucount) ? 0 : cpuindex; } while ((cpumask >> (15-cpuindex)) & 1 == 0); /* pass socket fd to next available server */ fdadata.fd = fd; if (sendmsg(serverfd[cpuindex], &fdmsghdr, 0) < 0) { fprintf(stderr, "sendmsg() call failed [errno %d]\n", errno); exit(1); } close(fd); } /* end while (1) */ } slaunch1 creates an AF_UNIX socket pair to use for interprocess communication with each of its servers.
Example 40 Static Echo Server /* sserver.c * * Simple OSS server example using OSS APIs for communication * between requester and server. * * sserver is a static echo server. A sserver process is launched * for each cpu with stdin being used for fd passing from slaunch * to sserver. When an fd is passed to sserver, it adds it to an * fdset and then echoes the input on that connection.
fdmsghdr.msg_iovlen iov[0].iov_base iov[0].iov_len = 1; = msg_buff; /* data ignored when passing fd */ = sizeof(msg_buff); fdmsghdr.msg_control fdmsghdr.msg_controllen fdadata.fdcmsghdr.cmsg_len fdadata.fdcmsghdr.cmsg_level fdadata.fdcmsghdr.cmsg_type fdadata.fd = = = = = = &fdadata; sizeof(fdadata); sizeof(fdadata); SOL_SOCKET; SCM_RIGHTS; -1; /* set by each recvmsg() call */ /* Find a ready socket ... */ while (1) { /* initialize timeout and bitmask for select() call */ timeval.
exit(1); } else if (bytesread == 0) /* peer closed connection */ { /* close socket and remove fd from active fd set */ fprintf(stderr, "sserver [cpu %d] - " "connection on fd %d closed\n", cpu, fd); close(fd); FD_CLR(fd,&fdset); fdcount--; } else /* data received */ { msg_buff[bytesread] = '\0'; /* make string NULL-terminated */ fprintf(stderr, "sserver [cpu %d] - " "message received on fd %d = %s", cpu, fd, msg_buff); /* echo back to sender */ if (send(fd, msg_buff, bytesread, 0) < 0) { fprintf(stderr, "ss
Table 13 OSS Process-Management Functions OSS Function OSS Notes Guardian Notes abort() Generates a software signal to terminate the calling process. Calls the Guardian ABEND procedure when called from a Guardian TNS process. alarm() Sets or changes a timer that expires at a specified time in the future. Results in undefined behavior when called from a Guardian TNS process.
Table 13 OSS Process-Management Functions (continued) OSS Function OSS Notes Guardian Notes execvp() Replaces the current process image with a new process image, using a filename, an argv array, and **environ. Can return extended errors. Sets errno to the ENOTOSS value when called from a Guardian process. Propagates open file descriptors except those opened using a Guardian function or procedure. For 64-bit OSS process-creation details, beginning with the H06.24 and J06.
Table 13 OSS Process-Management Functions (continued) OSS Function OSS Notes Guardian Notes getppid() If the parent process terminates or the Sets Guardian trap number 5 when Gets the OSS parent process ID of the calling process was created by a called from a Guardian process. Guardian process, it returns a parent calling process. process ID of 1. getsid() Gets the group ID of the process that is the session leader of the specified process Can return extended errors.
Table 13 OSS Process-Management Functions (continued) OSS Function OSS Notes Guardian Notes setpgrp() Can return extended errors. Creates a new session when the calling process is not a process group leader, and sets the process group ID of the calling process. Sets errno to the ENOTOSS value and sets Guardian trap number 5 when called from a Guardian process.
Table 13 OSS Process-Management Functions (continued) OSS Function OSS Notes Guardian Notes sigsuspend() Changes a process signal mask and suspends the calling process. Can return extended errors. Sets errno to the ENOTOSS value when called from a Guardian TNS process. sleep() Suspends the calling process for a specified interval of time. There are several implementation-defined features with respect to the SIGALRM signal. Results in undefined behavior when called from a Guardian TNS process.
Table 13 OSS Process-Management Functions (continued) OSS Function OSS Notes Guardian Notes uname() Can return extended errors. Gets information identifying the system on which the calling process runs. wait() If a parent process terminates without Sets errno to the ENOTOSS value waiting for all of its child processes to when called from a Guardian process. waitpid() Wait for a child process to terminate. terminate, the remaining child processes are assigned a parent process ID of 1.
Guardian Process-Management Procedures Table 14 displays information about each Guardian procedure that you can use to manage processes. Procedures that have been superseded by other procedures are not shown. The columns of the table contain the following: Guardian Procedure The name of the procedure and a brief description. OSS Notes Additional considerations or restrictions when the Guardian procedure is used on OSS processes.
Table 14 Guardian Process-Management Procedures (continued) Guardian Procedure OSS Notes For 64-bit OSS process creation details, beginning with the H06.24 and J06.13 RVUs, see “64-Bit OSS Processes” (page 286). OSS SEEP consultation, beginning with the J06.15 and H06.26 RVUs. For OSS SEEP details, see “Accessing OSS SEEP-Protected Files” (page 83). PROCESS_STOP_ Terminates a process. An OSS parent process receives a SIGCHLD signal and the OSS process termination status.
Table 14 Guardian Process-Management Procedures (continued) Guardian Procedure OSS Notes SETLOOPTIMER Sets the process loop-timer value of the calling process. When the process loop-timer expires for an OSS process, a SIGTIMEOUT signal is generated. SIGACTION_INIT_ Establishes the initial state of signal handling for the calling process. SIGACTION_RESTORE_ Restores the signal-handling state stored by a call to SIGACTION_SUPPLANT_.
facility; individual threads are not independently dispatched (that is, not “kernel” threads), so only one can be active on a processor at a time. There are no facilities to checkpoint a hidden pthread state. Designing, implementing, and testing a correct OSS process pair is not a simple task. Often it is preferable to use middleware subsystems that provide the necessary fault-tolerance features. However, sometimes a tailored process pair is the best or most efficient mechanism.
OSS process-creation functions invoked by a member of an OSS process pair have the following effects: • fork() creates a new process that inherits the usual attributes from its parent. The process name is not inherited; therefore, the new process is not relevant to the original process pair. • Functions in the exec...() family associate a new program image with the current PID. Operationally, a new process is created (with a different CPU, PIN identity), and the process performing the exec terminates.
File Number Conflicts A difficulty can occur in an OSS process pair, because an OSS process has two special “files” open—the root directory and the current working directory. Each of these objects consumes a file number in the process. Typically, when PROCESS_SPAWN_ creates a new OSS process, root and cwd are assigned file numbers 1 and 2, respectively. The standard in/out/error files get numbers 3, 4, and 5, respectively. Additional opens use additional numbers.
4 Managing Memory The term “memory management” has broad scope. The phrase applies to the actions of the operating system, which associates ranges of virtual addresses with physical addresses and with aggregations of data. Memory management applies somewhat differently to the actions in the user environment, including the run-time library.
Selectable Segments Selectable segments all share the same address range; all selectable segments have the same starting address (%2000000 or 0x80000). Thus, only one selectable segment is available to a process at any given time. You select a segment—make a segment current—with the SEGMENT_USE_ procedure. For information about using extended segments in application programs, see the Managing Memory chapter in the Guardian Programmer’s Guide.
Segment sharing is specified using an identifier called shmid, returned by shmget(), and passed to shmat(). Permission to share the segment is based on OSS protection mechanisms: the creator specifies whether the segment can be shared by the same user, the user group, or anyone. For information about the set of shm*() functions, see the Open System Services System Calls Reference Manual in the NTL.
In the OSS environment, communication between processes using shared memory, message queues, semaphores, and pipe functions is considered to be interprocess communication—rather than memory management. OSS interprocess-communication functions are discussed in “Interprocess Communication” (page 174). Pool Functions Frequently, portions of a memory segment are utilized for independent purposes.
5 Managing Time This section describes the time-management features that are common to both UNIX and the OSS API and those that are unique to the OSS API. You can use OSS functions and Guardian procedures to query the system clock, obtain process times, and set process timers. This section discusses the following topics: Topic Content “Common and Unique Characteristics” (page 166) Summary of the differences between OSS and UNIX time management.
Function Summary strptime() Converts a character string to a time value. tzset() Sets the time-zone conversion information. utime() Sets file access and modification times. wcsftime() Converts a date and time to a wide character string. Features Unique to OSS Time Management The OSS API does not provide functions that set or alter the system time or obtain information about processor times. It also does not provide an internal timer.
To obtain a timestamp time with an accuracy to the microsecond in an OSS program, you must use the Guardian JULIANTIMESTAMP procedure. Querying Process Times You can obtain the execution time of processes from the OSS API with the times() or clock() function. The times() function provides more information than the clock() function. An OSS process calls the times() or clock() function in the same way a UNIX process would.
OSS Time-Management Functions Table 16 (page 170) displays information about each OSS function that you can use to manage time. The columns of the table contain the following: OSS Function The name of the function and a brief description. OSS Notes Notes about the OSS implementation of the function. The note “Can return extended errors” means that the function can return errors that are HP extensions to the XPG4 specification. Refer to the function’s reference page for further information.
Example 42 Using gettimeofday() #include #include #include int main(int argc, char *argv[]) { struct timeval tv; struct timezone tz; /* Read the system values for the current time and time zone. The time is expressed in seconds and microseconds since midnight January 1, 1970. */ gettimeofday(&tv, &tz); printf("The current time is:\n%s", ctime(&tv.tv_sec)); printf("and %d microseconds after midnight January 1, 1970\n", tv.
Table 16 OSS Time-Management Functions (continued) OSS Function OSS Notes Guardian Notes Converts a broken-down time into time since the Epoch (00:00:00 UTC January 1, 1970 A.D.). Refer to ctime(). strftime() Converts a date and time to a string. strptime() Converts a character string to a time value. time() Obtains the time in seconds since the Epoch (00:00:00 UTC January 1, 1970 A.D.). times() Obtains process and child process elapsed times. Time values are approximate.
Table 17 Guardian Time-Management Procedures Guardian Procedure OSS Notes ADDDSTTRANSITION Allows the super ID to add an entry to the daylight-saving time (DST) transition table. CANCELPROCESSTIMEOUT Cancels a process-time timer previously initiated by a call to the SIGNALPROCESSTIMEOUT procedure. CANCELTIMEOUT Cancels a process-time timer previously initiated by a call to the SIGNALTIMEOUT procedure.
Table 17 Guardian Time-Management Procedures (continued) Guardian Procedure OSS Notes SETLOOPTIMER Enables you to limit the processor time a process is allowed. SETSYSTEMCLOCK Allows you to change the system clock. SIGNALPROCESSTIMEOUT Sets a timer based on process execution time. SIGNALTIMEOUT Sets a timer to a given number of units of elapsed time. TIME Provides the current date and time in integer form.
6 Interprocess Communication Interprocess-communication mechanisms allow processes to communicate within the same processor, between processors, and between nodes. This section discusses the following topics: Topic Content “Available Methods” (page 174) Summary of the mechanisms available to an OSS application. “Common and Unique Characteristics” (page 175) Summary of the differences between UNIX and OSS interprocess communication.
1 Applies to both AF_UNIX Release 2 sockets and earlier AF_UNIX sockets. However, AF_UNIX Release 2 sockets must be of the same mode to communicate with each other. See “Using AF_UNIX Sockets” (page 187). Table 19 lists the interprocess-communication methods available to an OSS process using mixed OSS and Guardian APIs, and the capabilities of each relevant to communication between processors and nodes. The methods are listed in an order consistent with Table 18.
Pipes and FIFOs are memory-resident interprocess channels through which OSS processes can communicate. OSS processes having a common ancestor can communicate through a pipe, but common ancestry is not required for OSS processes to communicate through a FIFO, which is a named pipe. OSS processes can share memory segments using shared-memory functions. OSS semaphores allow multiple processes to synchronize access to shared memory segments to avoid compromising the integrity of the data in those segments.
• “Using Shared Memory” (page 189) • “Using the $RECEIVE File” (page 191). Guardian processes can use OSS sockets APIs, with the restrictions described in Table 20 (page 197). The table includes a short description of the OSS sockets functions. OSS and Guardian processes cannot communicate using message queues, because only OSS processes can call the message queue functions.
After you start the server process, the requester process in Example 44 can be started in the foreground from the OSS shell using the command: ./requester2 Alternatively, both processes can be started in the foreground from separate terminal sessions. The following sample dialog illustrates the processes run from two terminal sessions. The server terminal session for the program in Example 43 appears as: /home/software/chrisbl/cabpubs: .
Example 43 Using AF_INET in an OSS Server Process /* server2.c * * Simple OSS server example using OSS socket APIs * for communication between requester and server. * * This server accepts AF_INET stream socket connections on * a listening port. Data requests are handled by printing * the data and then replying back to the requester with the * original data. The server exits when idle for 60 seconds.
fdcount = 1; highfd = fd; listenfd = fd; FD_ZERO(&fdset); FD_SET(listenfd, &fdset); /* Find a ready socket ... */ while (1) { /* initialize timeout and bitmask for select() call */ timeval.tv_sec = IDLE_PERIOD; timeval.
exit(1); } } } /* end else fd is an existing connection */ } /* end while (1) */ } Interprocess-Communication Interoperability 181
Example 44 Using AF_INET in an OSS Requester Process /* requester2.c * * Simple OSS requester example using OSS socket APIs * for communication between requester and server. * * This requester accepts terminal input and sends it to a * server using a send() call and then waits for a response using * a recv() call. When the server echoes the data back to the * requester, the recv() call completes and the requester prompts * for more terminal input.
printf("?"); fgets(msg_buff, BUFF_LEN, stdin); if (feof(stdin)) exit(0); bytesread = (int)strlen(msg_buff); /* send prompt */ /* read user input */ /* if EOF then exit(0) */ /* includes newline */ /* send line to server... if error then exit(1) */ if (send(fd, msg_buff, bytesread, 0) < 0) { printf("send() call failed [errno %d]\n", errno); exit(1); } /* expect echo from server...
/home/software/chrisbl/cabpubs: .
Example 45 Using AF_INET in a Guardian Server Process /* server2g.c * * Simple OSS server example using Guardian socket APIs * for communication between requester and server. * * This server accepts AF_INET stream socket connections on * a listening port. Data requests are handled by printing * the data and then replying back to the requester with the * original data. The server exits when idle for 60 seconds. * * Note - Guardian sockets do not have Posix semantics.
addr.sin_family = AF_INET; addr.sin_addr.s_addr = gethostid(); /* internet address family */ /* assume server on our host */ /* bind socket to address ... if error then exit(1) */ if (bind_nw(fd, (struct sockaddr *)&addr, sizeof(addr), bind_tag) < 0) { printf("bind_nw() call failed [errno %d]\n", errno); exit(1); } AWAITIOX(&fd, , , , FOREVER); /* start a nowait accept ...
/* need to post an accept for the next connection */ addrlen = sizeof(addr); if (accept_nw(fd, (struct sockaddr *)&addr, &addrlen, accept_tag) < 0) { printf("accept_nw() call failed [errno %d]\n", errno); exit(1); } } else /* else data or error on an existing connection */ { if (bytesread == 0) /* no data - error or close */ { /* close our end */ FILE_CLOSE_(fd); /* not close(fd) but FILE_CLOSE_(fd) */ free(msg_buff_ptr[fd]); msg_buff_ptr[fd] = NULL; } else /* data was received */ { /* so print data and ech
◦ Sockets are created in compatibility mode by default. The mode of the socket is determined by the name of the transport provider process when the socket is created. After a socket is created, the mode of the socket cannot be changed. ◦ Sockets created in compatibility mode can communicate with other sockets created in compatibility mode but cannot communicate with sockets created in portability mode.
getpeername() has the /E/local_system/ prefix (if present) stripped, all symbolic links resolved, all /./ strings suppressed, and all /../ strings resolved. • If the file to which a socket is bound is removed or renamed, calls to getsockname() continue to return the original absolute path name.
On servers running J06.12 or later J-series RVUs or H06.23 or later H-series RVUs: • Both Guardian processes and OSS processes can call the OSS shared memory functions, which are shmat(), shmctl(), shmdt(), and shmget(). They can share segments as described for shmget(). • There is no configured limit to the number of shared memory segments or their size created by shmget(). The size of the shared memory segment and number of shared memory segments are limited by system resources only.
Using the $RECEIVE File OSS and Guardian processes can use Guardian procedures to communicate between nodes, between processors, and within the same processor through $RECEIVE. $RECEIVE is a special file in the Guardian filesystem through which a process can receive system messages or messages from other processes.
Example 46 Using $RECEIVE in an OSS Server Process /* server1.c * * Simple OSS server example using Guardian file input/output * APIs for communication between requester(s) and server. * * This server accepts requests on $RECEIVE. Data requests are * handled by printing the data and then replying back to the * requester with the original data. Open and close requests * are handled by updating an opener count. The server exits * when idle for 60 seconds.
fprintf(stderr, "READUPDATEX() to %s failed\n", filename); exit(1); } /* Wait for I/O completion on $RECEIVE. */ CC = AWAITIOX(&fnum, , &bytesread, , IDLE_PERIOD); /* /* /* /* /* file number */ buffer address */ count transferred */ tag */ time limit (60 sec) */ /* get last file error ...
Example 47 Using $RECEIVE in an OSS Requester Process /* requester1.c * * Simple OSS requester example using Guardian file input/output * APIs for communication between requester and server. * * This requester accepts terminal input and sends it to a * server using a waited WRITEREADX() call. When the server * echoes the data back to the requester, the WRITEREADX() call * completes and the requester prompts for more terminal input.
FILE_CLOSE_(fnum); exit(0); } /* /* close server */ and exit(0) */ } bytesread = (short)strlen(msg_buff);/* includes newline */ CC = WRITEREADX(fnum, /* file number */ msg_buff, /* msg buffer */ bytesread, /* size of string to server */ BUFF_LEN, /* length of buffer */ &bytesread); /* number read back */ if (_status_ne(CC)) /* if error, exit(1) */ { fprintf(stderr, "WRITEREADX() to %s failed\n", procname); retcode = FILE_GETINFO_(fnum, &error); if (retcode == 0) fprintf(stderr, "File error = %d\n", erro
delivery of each message. The following list shows the order of increasing overhead (decreasing performance) for AF_UNIX Release 2 processes and sockets: 1. Both processes are in the same processor and their sockets were created in that processor. 2. The processes are in different processors and each process is using a socket created in its processor. 3. One of the processes resides in a processor other than where its socket was created. 4.
• The use of static memory by the process increases slightly.
Table 20 OSS Interprocess-Communication Functions (continued) OSS Function OSS Notes Guardian Notes directory; otherwise, the group ID is set to the effective group ID of the calling process. G file system. OSS SEEP consultation. msgctl() Performs message queue control operations. Can return extended errors. Sets errno to the ENOTOSS value when called from a Guardian process. msgget() Creates or returns the identifier for a message queue. Can return extended errors.
Table 20 OSS Interprocess-Communication Functions (continued) OSS Function OSS Notes Guardian Notes semop() Performs semaphore operations. Can return extended errors. Sets errno to the ENOTOSS value when called from a Guardian process. send() Sends a message to a connected socket. Can return extended errors. send64() Sends a message to a connected socket. Can return extended errors. sendmsg() Sends a message to a socket using a message structure. Can return extended errors.
Table 20 OSS Interprocess-Communication Functions (continued) OSS Function OSS Notes Creates a new shared memory A shared memory segment is shared segment or returns the identifier of an through the Kernel-Managed existing shared memory segment. Swap-space Facility. If a processor fails, all shared memory segments in that processor are lost. Guardian Notes on servers running J06.11 or earlier J-series RVUs, H06.22 or earlier H-series RVUs, or G-series RVUs.
Table 21 OSS Interprocess-Communication-Related Functions (continued) OSS Function OSS Notes Guardian Notes freeaddrinfo() Frees a specified address information structure previously allocated by getaddrinfo(). freehostent() Frees hostent structure previously allocated by getipnodebyaddr or getipnodebyname. gai_sterr() Aids applications in printing error messages returned by getaddrinfo(). getaddrinfo() Converts hostnames and service names into socket address structures.
Table 21 OSS Interprocess-Communication-Related Functions (continued) OSS Function OSS Notes getprotoent() Gets the next protocol entry. Availability of database might require system manager action. getservbyname() Gets a network services entry by name. Availability of database might require system manager action. getservbyport() Availability of database might require Gets a network services entry by port system manager action. number. getservent() Gets the next entry in the network services database.
Table 21 OSS Interprocess-Communication-Related Functions (continued) OSS Function OSS Notes Guardian Notes inet_ntoa() Translates an integer Internet address into a character string in Internet dot notation. inet_ntop() Converts a binary internet address to a character value. inet_pton() Converts a character string to an IPv4 or IPv6 binary address. ntohl() Converts a 32-bit integer from Internet network byte order to host byte order.
OSS Notes Additional considerations or restrictions when the Guardian procedure is called from an OSS process. Table 23 (page 206) displays information about Guardian procedures useful when performing interprocess communication. The columns of the table contain the same kind of information as in Table 22. For details about a procedure, refer to the Guardian Procedure Calls Reference Manual and the Guardian Programmer’s Guide.
Table 22 Guardian Interprocess-Communication Procedures (continued) Guardian Procedure OSS Notes Establishes a Guardian file open with a file number. Can be used by: • A requester process to open a server process file • A server process to open its $RECEIVE file FILE_READUPDATE64_ Beginning with the H06.24 and J06.13 RVUs. Reads data from a disk or process file in anticipation of a subsequent write to the file and extends the capabilities of READUPDATE(XL). FILE_REPLY64_ Beginning with the H06.24 and J06.
Table 23 Guardian Interprocess-Communication-Related Procedures Guardian Procedure OSS Notes CONTROL Issues CONTROL operations to a process that simulates an input/output device. CONTROLBUF Issues CONTROLBUF operations to a process that simulates an input/output device. FILE_CONTROL64_ Performs device-dependent I/O operations. Beginning with the H06.24 and J06.13 RVUs. FILE_CONTROLBUF64_ Performs device-dependent I/O operations requiring a data buffer. Beginning with the H06.24 and J06.13 RVUs.
7 Managing I/O This section describes how to manage OSS tape, terminal, and printer I/O. It discusses the following topics: Topic Content “Common and Unique Characteristics” (page 207) Summary of the differences between OSS and UNIX I/O. “I/O Interoperability” (page 207) The objects on which you can use OSS I/O functions and Guardian procedures. “Tape I/O” (page 208) Tape I/O using pax and the Guardian API. “Terminal I/O” (page 210) Terminal I/O using the OSS API.
Tape I/O The OSS environment has no programmatic access to tapes. To access tapes in the OSS environment you must use the pax utility. You can, however, use Guardian procedures to write OSS files and output directly to tape and read them directly from tape. Tape I/O With pax The pax utility reads, writes, and lists files and directories to and from archive files. An archive file can be a disk or tape file. You can use the pax utility from a C program by invoking it with the popen() function.
Example 48 Using the pax Utility From a Program #include #include #include FILE *fpout; #define MAXLINE 132 char paxbuf[MAXLINE]; char line[MAXLINE]; int main (int argc, char *argv[]) { /* The program is called with name of a backup (archive) file. Make sure the correct number of arguments are entered. If not, print a usage message and exit.
• Many systems and vendors use only labeled tapes. • You can access labeled tapes on different systems than the one your file is on. To perform read or write operations on an OSS file on a labeled tape, follow these steps: 1. Open the desired OSS file. 2. Open the proper tape file by passing the name of a DEFINE that has the appropriate attributes as the filename parameter to the FILE_OPEN_ procedure. 3. Position the tape to available space on the tape. 4.
Blocking and Nonblocking Terminal I/O For J-series RVUs, H06.06 and later H-series RVUs, and G06.27 and later G-series RVUs, nonblocking behavior is supported for Telserv and OSSTTY terminal objects for these functions: • select() • FILE_COMPLETE_() • FILE_COMPLETE_SET_() • FILE_COMPLETE_GETINFO_() If you attempt to use these funcions on a terminal process running on a system that is running RVUs earlier than G06.27 or H06.06: • select() returns the error ENOTSUP.
Table 24 Canonical Mode Control Characters and Associated Flags in termios.h (continued) Control Character Default Value Associated Flag Index in c_cc QUIT %X1C ^\ ISIG, NOFLSH VQUIT START %X11 ^Q IXON/IXOFF VSTART STOP %X13 ^S IXON/IXOFF VSTOP SUSP %X1A ^Z ISIG, NOFLSH VSUSP Noncanonical mode control characters, their default values, associated flags, and indexes into the array specified by the c_cc field of the termios structure are shown in Table 25.
Example 49 Accessing an OSS Terminal With Guardian Procedures in the OSS API #include #include #include #include #include
/* Read input from the terminal using READX. */ CC = READX(filenum, /* terminal file number */ buffer, /* input buffer */ sizeof(buffer), /* size of buffer */ &bytesread, /* bytes read */ ); /* Check for successful terminal read operation. */ if (_status_ne(CC)) { fprintf(stderr, "READX from terminal failed: %s\n", terminal); exit(1); } /* Write and read from the terminal in one operation.
Figure 6 OSSTTY Interaction With OSS and Guardian Environments OSSTTY supports three standard qualifiers: #stdin, #stdout, and #stderr. OSS applications can redirect their standard input, standard output, and standard error to OSSTTY by using these qualifiers: Qualifier Description /G/name/#stdin Redirects standard input data to the OSSTTY process identified by name. /G/name/#stdout Redirects standard output data to the OSSTTY process identified by name.
The value specified for input can be either of the following: • A Guardian process; for example, $vhs (Guardian virtual hometerm subsystem) or $zhome (Guardian reliable home terminal). • Any Telserv terminal. The OSSTTY process will redirect all data received from the specified input to any process that uses $process-name.#stdin (Guardian process) or /G/process-name/#stdin (OSS process) as its standard input.
Examples of OSSTTY Usage Following are some typical examples of OSSTTY usage. Redirecting Input From a Guardian Process to an OSS Process In this example, OSSTTY is used to direct input from $vhs (Guardian virtual hometerm subsystem) to an ftp client running in OSS. TACL> run osstty /name $tty, in $vhs, nowait/ TACL> osh $/usr/ucb/ftp
The logger process receives input through $RECEIVE and sends the data to the log file logfile. Example 50 shows the source code for the logger program.
Example 50 Example Logger Program Used With OSSTTY /* Logger Program used with OSSTTY */ #pragma runnable, symbol, nolist, inspect /* This is a simple logger program. It does the following: - Opens its $RECEIVE for interprocess communication. - Creates an EDIT file that is provided as run-time argument during instantiation. It is used as a log file. - Accepts an OPEN from an application and logs the data that is being written to it.
short ret_fd; _cc_status read_status ; short error = 0; /* Create the EDIT file */ file_create(argv[1]); /* Open $RECEIVE for interprocess communication */ dol_RECEIVE_opener(); /* Exit only when close received from OSSTTY */ for (;;) { /* Read from $RECEIVE in waited manner */ read_status = READUPDATEX(rcv_fd, (char *)U_data, MAX_USRMSG, &rcv_cnt); /* A CCG on $RECEIVE means that a system message has been received */ if( _status_gt(read_status)) { error = tty_info_fnum (rcv_fd); if(error == 6) system_messa
FILE_PURGE_((char *)file_name, (short)strlen(file_name)); error = OPENEDIT_((char *)file_name, (short)strlen(file_name), &edit_fd, 2/*Write Only*/, 0/* shared*/, 0,/*nowait depth*/ 15); if (error) { printf("Unable to Created EDIT File\n"); exit(0); } } short tty_info_fnum(short fd) { short error; (void) FILE_GETINFO_(fd, &error ); return error; } /* Open $RECEIVE in waited manner for interprocess communication */ void dol_RECEIVE_opener(void) { short error = 0; if (( rcv_fd = tty_open_file ("$RECEIVE", 8, 0
Note the following about using this program: • If you give the program a process name qualified with the system name, such as \mysys.$sh, the program fails with a TACL error. • If #INFORMAT is set to TACL, you must escape TACL special characters like the vertical bar with a tilde: ~| • If you run a utility, such as cat, SCF, or VPROC, the "be" and "print" routines will hang. The TACL program consists of the following procedures.
Example 51 Running an Interactive OSS Session From the Guardian Environment == TACL macro for an interactive OSS session from the Guardian environment == file: sh == Start an OSSTTY process and OSS shell ?section sh routine #push pname [#case [#argument /value pname/ processname /syntax/ otherwise] |1| #set pname [#shiftstring /up/ [pname]] [#case [#argument end otherwise] |1| [#if [#processexists [pname]] |then| #output Process [pname] already exists -- terminating.
#output Extraneous input -- terminating. #output #unframe #return ] == end case |2| #output Expecting a process name -- terminating. #output #unframe #return ] == end case #set name [pname] #chardel name 1 for 1 [#if not [#variableinfo /existence/ [name]^in^buf] |then| #output Nothing to get rid of.
#unframe == Display output from previously defined OSSTTY/OSS shell environment ?section print routine #frame #push pname out^line #if [#argument /value pname/ processname] #if [#argument end] #chardel pname 1 for 1 [#if not [#variableinfo /existence/ [pname]^in^buf] |then| #output Process not known.
print $[pname] [#if not [#variableinfo /existence/ [pname]^status] |then| == print complained that the process died.
Example 52 Printing an OSS File With the lp Utility #include #include #include FILE *fpin, *fpout; #define MAXLINE 132 char lpbuf[MAXLINE]; char line[MAXLINE]; int main (int argc, char *argv[]) { if(argc < 2) { fprintf(stderr, "Usage: lpopen \n"); exit(1); } /* Open the input file. */ if((fpin = fopen(argv[1], "r")) == NULL) { fprintf(stderr, "Can't open %s\n", argv[1]); exit(1); } /* Create a string for popen() with the name of the file to be printed in the title.
Example 53 (page 229) shows how to send an OSS file to the spooler and how to control the spooler from an OSS program using Guardian spooler procedures. The printer is opened using FILE_OPEN_, then SPOOLSTART is called to establish a level-3 spooling session using a level-3 buffer to compress and block data. The SPOOLCONTROL procedure is used to send control codes to the level-3 buffer, and the SPOOLWRITE procedure is used to compress and block data in the level-3 buffer.
Example 53 Sending an OSS File to the Guardian Spooler /* Example: Sending an OSS file to the Guardian Spooler */ #include #include #include #include
, /* , /* , /* , /* , /* 047, stick with default location */ form name for the job */ report name for the job */ number of copies */ page size (in lines) */ /* flag - attributes of job */ /* 040 - hold after bit on */ /* 007 - job priority = 7 */ , /* owner of job */ , /* maximum number of lines allowed for job */ , /* maximum number of pages allowed for job */ , /* filename of spooler collector */ , /* alternative parameter to collector filenum */ l3buffer /* 32 bit pointer to l3 buffer */ ); if (retcode
fprintf(stderr, "SPOOLCONTROL failed: %s\n", printer); fprintf(stderr, "retcode = %d\n", retcode); exit(1); } retcode = SPOOLEND( /* complete the spool job */ , /* 16-bit level-3 buffer */ 0104, /* flag - attributes of job */ /* 0100 - hold bit on */ /* 0004 - job priority = 4 */ l3buffer ); if (retcode != 0) { fprintf(stderr, "SPOOLEND error %d\n", retcode); exit(1); } fclose(infile); /* close input file */ FILE_CLOSE_(filenum); /* close printer file */ printf("File %s spooled to %s printer\n", pathname,pr
Example 54 Sending an OSS File Directly to a Printer Using the Guardian API #include #include #include #include #include
} /* Position the paper to top of form again. */ CC = CONTROL(filenum, /* send control code to printer */ 1, /* forms control mode */ 0 /* top of form control code */ ); if (_status_ne(CC)) { fprintf(stderr, "Illegal control code to printer: %s\n",\ printer); exit(1); } fclose(infile); /* close input file */ FILE_CLOSE_(filenum); /* close printer file */ exit(0); } OSS I/O Management Functions Table 26 (page 233) displays information about each OSS function that you can use to manage I/O.
Table 26 OSS I/O Functions (continued) OSS Function OSS Notes Guardian Notes Retrieves file implementation characteristics. isatty() Tests for a terminal. Can return extended errors. pathconf() Retrieves file implementation characteristics. Can return extended errors. tcdrain() Waits for output to complete. Can return extended errors. tcflow() Performs flow control functions. Can return extended errors. tcflush() Can return extended errors.
Table 27 Guardian I/O Procedures (continued) Guardian Procedure OSS Notes CONTROLBUF Performs device-dependent I/O operations that require a data buffer. DEVICE_GETINFOBYLDEV_ Obtains the logical and physical attributes of a device. FILE_CONTROL64_ Performs device-dependent I/O operations. Beginning with the H06.24 and J06.13 RVUs. FILE_CONTROLBUF64_ Performs device-dependent I/O operations requiring a data buffer. Beginning with the H06.24 and J06.13 RVUs.
8 Using Logging Mechanisms This section describes how to log information in the OSS environment. You can log information in two ways in the OSS environment: • With the OSS logging functions • With Event Management Service (EMS) procedures Use the OSS logging functions in portable applications. These functions enable you to use the function calls of the Berkeley Software Distribution (BSD) UNIX logging mechanism to send log messages.
Table 28 OSS Logging Functions (continued) Function Description setlogmask() Sets the EMS event log mask syslog() Logs messages These functions are described in closelog(3), openlog(3), setlogmask(3), and syslog(3) reference pages, which are available either online or in the Open System Services Library Calls Reference Manual.
Table 29 OSS Logging Function Parameters and Default Values Parameter of Function Default Value Description of Default Value facility openlog() LOG_USER Logs messages generated by user processes and displays the facility string USER. ident openlog() “syslog” Causes the identity string “syslog” to appear in messages. level syslog() LOG_INFO Assigns the level LOG_INFO to the event and displays the level string INFO.
Table 30 Logging Level Event Numbers and Strings Level EMS Event Number Message String LOG_EMERG 5 EMERGENCY (most severe) LOG_ALERT 6 ALERT LOG_CRIT 7 CRITICAL LOG_ERR 8 ERROR LOG_WARNING 9 WARNING LOG_NOTICE 10 NOTICE LOG_INFO 11 INFO LOG_DEBUG 12 DEBUG (least severe) Initializing Logging Parameters The openlog() function initializes the Event Management Service (EMS) event log parameters that are used by the OSS logging mechanism.
Table 32 OSS Logging Facilities (continued) Facility Message String Description LOG_LPR LPR Messages generated by a line printer subsystem. LOG_MAIL MAIL Messages generated by a mail subsystem. LOG_NEWS NEWS Messages generated by a network news subsystem. LOG_SYSLOG SYSLOG Messages generated by a syslogd demon. LOG_USER USER Messages generated by user processes. This is the default value. LOG_UUCP UUCP Messages generated by a UNIX-to-UNIX copy program (UUCP) subsystem.
Example 55 Calling syslog() With Formatting Codes fahr = 50; syslog( LOG_DEBUG , "%4d Fahrenheit -- %6.1f Centigrade " , fahr , (5.0/9.0)*(fahr - 32 ) ); This call produces the following message: USER DEBUG : 50 Fahrenheit -- 10.0 Centigrade You can use the %m formatting code to include the current error number. Example 56 shows a code fragment with a call to syslog() using %m.
Example 57 Use of System Logging Functions /* Using System logging functions */ #include #include #include
Logging Parameters and EMS Tokens OSS logging function parameters correspond to the EMS tokens listed on the syslog(3) reference page, which is available either online or in the Open System Services Library Calls Reference Manual. The values of the tokens can be changed by the functions described in this section, but the tokens themselves cannot be changed with the OSS API. Table 34 lists logging function parameters with their corresponding EMS tokens.
Table 35 OSS Logging-Mechanism Functions (continued) OSS Function OSS Notes strerror() Accesses a message explaining the function error. Upon successful completion, this function returns a pointer to the generated message string. If the error number is not valid, errno is set to the EINVAL value. syslog() Logs messages. 244 Using Logging Mechanisms Guardian Notes If you specify the LOG_PID option with the openlog() function on a Guardian process, the syslog() function fails with Guardian trap 5.
9 Using Subsystems From OSS There are HP subsystems that you can access from OSS programs. This section summarizes considerations or limitations in using HP subsystems from your OSS application programs. The section also provides references to manuals that discuss these subsystems in detail.
appropriate to your programming language; you can even partially automate that action by including an entry for the action in a make file. For example, the following make file entry: zspi.h: /G/system/zspidef/zspic cp /G/system/zspidef/zspic ./zspi.h creates a dependency on the presence of the necessary file in the user’s local directory and makes sure that any updates made to the Guardian copy of the file also appear in the copy used to compile the application.
HP NonStop TS/MP HP NonStop Transaction Services/MP (TS/MP) provides online transaction processing. TS/MP can create and monitor OSS servers, but it does not support OSS requesters. An OSS server process must read its $RECEIVE file to get messages from requester processes. To read the $RECEIVE file, you must use Guardian procedures. OSS and Guardian server classes can be managed by the same PATHMON process.
HP NonStop Distributed Computing Environment (DCE) HP NonStop Distributed Computing Environment (DCE) is an integrated set of services that supports the development and execution of distributed applications between heterogeneous networked computers.
10 Managing OSS Security This section provides a brief overview of the features available for program control of OSS process and file security.
• OSS file auditing mechanisms and policies are implemented through the Guardian environment Safeguard product instead of such UNIX commands or utilities as: /etc/reboot /etc/shutdown /etc/syslog passwd Prior to the J06.15 and H06.26 RVUs, OSS file auditing features are not available through third-party Security Event-Exit Process (SEEP) programs. • Access to OSS auditing logs occurs through the Safeguard audit reduction tool (SAFEART) program.
Figure 7 Major Components and Interfaces for OSS Security Management Table 36 OSS Security-Related Functions OSS Function Security-Related Behavior acl() Changes file access permissions for a list of users and groups. OSS SEEP consultation.1 chmod() fchmod() lchmod() Changes file access permissions. chown() fchown() lchown() Changes file ownership. crypt() Encrypts a password or other character data. cuserid() Gets the user name associated with the real user ID of the current process.
Table 36 OSS Security-Related Functions (continued) OSS Function Security-Related Behavior getsid() Gets the group ID of the process that is the session leader of the specified process. getgrent() Gets group information from the group database. getgroups() Gets the list of groups to which the current process belongs. getlogin() Gets the login name (user name) for the current terminal session.
Security Auditing of OSS files Your application program does not need to provide its own file auditing mechanism. Your system manager can enable file auditing on a specific fileset. When auditing is enabled, certain application program activities for any file in that fileset can automatically generate entries in the audit file for the system where the file is located.
Table 37 OSS Function Calls Audited When Used With Audited Filesets (continued) OSS Function Attributes or Actions Audited chown() fchown() lchown() The values of the OSS user ID, group ID, and file mode before and after the call. connect() For AF_UNIX sockets, the values of the OSS user ID and group ID. Only audited beginning with the J06.15 and H06.26 RVUs. creat() creat64() For all files, the value of the file mode, the OSS user ID, the group ID, and rdev.
Table 37 OSS Function Calls Audited When Used With Audited Filesets (continued) OSS Function Attributes or Actions Audited tdm_execve() tdm_execvpe() The process name and the value of the OSS user ID and group ID. tdm_fork() The process name and the value of the OSS user ID and group ID. tdm_spawn() tdm_spawnp() The process name and the value of the OSS user ID and group ID.
renaming operation; propagation occurs after completion of the rename() function call. If both of the following are true: • An affected fileset and its mount point are managed by different OSS name server processes • The renaming is followed immediately by an audited operation on a file in that fileset Then the audit record produced by the latter operation might include a pathname that does not reflect the renaming because the renaming propagation has not completed.
Example 58 Using OSS Security Functions /* Using OSS Security functions (without ACLs) */ #include #include #include #include #include #include #include #include #include
printf("The following supplementary groups are available:\n"); for(i = 0; i < ngroups; i++) { gid = grouplist[i]; printf("\t"); printgroup(gid); printf("\n"); } return; } struct stat statbuf; int main(int argc, char **argv) { uid_t uid; gid_t gid, egid; char *login; char termid[L_ctermid]; int fd; /* Get new effective group ID from command line. Default value set to real group ID value.
statbuf.st_uid, statbuf.st_gid); if(setregid( ((gid_t)-1), egid) < 0) { fprintf(stderr, "Can't change effective group ID of process.\n"); exit(1); } if(chown("junkfile", (uid_t)-1, egid) < 0) { fprintf(stderr, "Can't change group ID of file.\n"); exit(1); } if(stat("junkfile", &statbuf) < 0) { fprintf(stderr, "Can't get status of file 'junkfile'\n"); exit(1); } printf("junkfile chown'ed with uid = %d, gid = %d\n", statbuf.st_uid, statbuf.
OSS ACLs: • Are supported in Version 3 and later catalog versions of OSS filesets. • Are supported for directories, regular files, first-in, first-out (FIFO) files, and bound AF_UNIX sockets. • Support up to 150 ACL entries. • Support separate permissions for up to 146 additional users and groups. • Support default ACL inheritance (see “ACL Inheritance” (page 263)). • Are based on the POSIX 1003.1e draft standard and the HP-UX implementation of ACLs.
privilege The ability to ignore access restrictions and change restrictions imposed by security policy and implemented in an access control mechanism. In OSS, the super ID is the only user ID that can ignore access restrictions. However, the super ID and any member of the Safeguard SECURITY-OSS-ADMINISTRATOR security group can change the ownership and access permissions (standard UNIX permissions or ACL entries) of a file.
Base ACL Entries The base ACL entries grant permissions equivalent to standard UNIX permissions. When an ACL consists of the four base ACL entries only, it is called a minimal ACL, and the permissions for the class and other ACL entries are equal. The chmod() and acl() functions can change base ACL entries.
g:writers:rwGrant read and write access to all members of the group writers. Actual ACL Entries The base ACL entries, optional user ACL entries, and optional group ACL entries are considered actual ACL entries because they actually control access to the associated file or directory. These ACL entries are also called nondefault ACL entries. Default ACL Entries Default ACL entries are allowed for directories only. Default ACL entries do not determine who can access the directory.
• The file-creation mode (mode) • The process umask (umask) If the fileset does not support OSS ACLs, the permissions of the created file are the mode bitwise-ANDed with the complement of the umask. If the fileset supports OSS ACLs, but the system on which the process is running does not support OSS ACLs, and the parent directory for the created file does not have default ACL entries, the permissions of the created file are the mode bitwise-ANDed with the complement of the umask.
For security reasons, if an ACL contains default ACL entries, all of the default base ACL entries should be provided.
default:group:dos:--default:group:tres:--- Access Check Algorithm To determine the permissions granted to an accessing process, the operating system checks for matching IDs in the following order: 1. If the EUID of the process is the same as the owner of the file, grant the permissions specified in the user:: entry of the ACL. Otherwise, continue to the next check. 2.
) or chmod( ) functions and are ignorant of ACLs are more likely to produce expected results. The st_acl field indicates the presence of optional ACL entries in the ACL for the file. The st_basemode field provides the owning user permissions, owning group permissions, and other permissions for the file.
For more information about OSS NFS file system security, see the Overview of NFS for Open System Services and the Open System Services NFS Management and Operations Guide. Header file The sys/acl.h header file defines the following constants to govern the number of entries per ACL: NACLENTRIES The maximum number of entries per ACL, including base entries NACLBASE The number of base entries For compatibility with HP-UX, the variable name NACLVENTRIES is provided as an alias for NACLENTRIES.
Example 59 Using acl() and aclsort() /* This program provides simple examples of acl(2) and aclsort(3) usage. * It adds a GROUP ACL entry (with read permissions) to the ACL of the * file. The file pathname and group ID number are passed as command * arguments. * To run: * addACLgroup * This program performs the following steps: * 1. Acquires the count of ACL entries in the ACL on the file * using acl(ACL_CNT). * 2. Allocates memory for the ACL buffer using malloc(). * 3.
printf("Number of ACL entries = %d\n", prevCount); /* Allocate space, reserving 1 extra ACL entry for the new GROUP entry */ newCount = prevCount + 1; if (( aclEnt = (acl_t *) malloc( newCount * sizeof(acl_t))) == 0 ) { printf("malloc error= %d, text = %s\n", errno, strerror(errno)); return 1; } /* Acquire the existing ACL on the object */ if ((prevCount = acl(pathname, ACL_GET, prevCount, aclEnt)) == -1 ) { printf("acl(ACL_GET) error= %d, text = %s\n", errno, strerror(errno)); free(aclEnt); return 1; } pri
Restricted-Access Filesets Applications that depend on the super ID for file access are subject to additional restrictions for files that are in restricted-access filesets. When accessing a file in a restricted-access fileset, the super ID is restricted by the same file permissions and owner privileges as any other user ID: It has no special privileges unless the executable file started by the super ID has the PRIVSETID file privilege (see “File Privilege File Attribute” (page 272)).
File Privilege File Attribute On systems running J06.11 or later J-series RVUs or H06.22 or later H-series RVUs, files have an additional file privilege attribute that specifies which special privileges, if any, a file has when accessing files in a restricted-access fileset.
PRIVSOARFOPEN File Privilege The PRIVSOARFOPEN file privilege allows a process to directly access any file in a restricted-access fileset on the local system, but only if that executable file has been started by a locally-authenticated member of the Safeguard SECURITY-OSS-ADMINISTRATOR (SOA) group.
OSS SEEP Programming This section provides the following OSS Security Event-Exit Process (SEEP) information: • “OSS SEEP Management” (page 274) • “OSS SEEP Consultation” (page 275) • “OSS SEEP System and Library Calls” (page 276) • “Final Result of the Operation” (page 277) • “OSS SEEP Interprocess-Communication Messages” (page 279) • “OSS SEEP Design” (page 283) • “OSS SEEP-Related EMS Events” (page 283) An OSS SEEP is a user-written process that participates in additional file-access authori
3. 4. Open the OSS SEEP for access-authorization requests Send the handshake message, and after an OSS SEEP reply, change the OSS SEEP's state to RUNNING The OSS SEEP runs with a userid of SUPER.SUPER. The backup OSS name server does a backup open of the OSS SEEP when the primary OSS name server completes the OSS SEEP start. Each time the OSS name server starts the OSS SEEP, it first attempts to kill any process with the same process name. An EMS message notes this action.
Figure 8 OSS SEEP Consultation Flow Depending on the OSS SEEP’s response, the OSS name server either immediately responds to the request with a security error or continues with the standard security evaluation. For examples of final results for security evaluations, see “Final Result of the Operation” (page 277). Considerations for OSS SEEP consultation are: • The OSS name server does not consult the OSS SEEP for access to /E and /G filesets.
access(2) – ee-oss-op-access* acl(2) – ee-oss-op-acl** bind(2) – ee-oss-op-bind chdir(2) – ee-oss-op-chdir chmod(2) – ee-oss-op-chmod chown(2) – ee-oss-op-chown chroot(2) – ee-oss-op-chroot connect(2) – ee-oss-op-connect creat(2) – ee-oss-op-open or ee-oss-op-open64 creat64(2) – ee-oss-op-open64 execl(2) – ee-oss-op-exec execle(2) – ee-oss-op-exec execlp(2) – ee-oss-op-exec execv(2) – ee-oss-op-exec execve(2) – ee-oss-op-exec execvp(2) – ee-oss-op-exec FILE_OPEN_ – ee-oss-op-fileopen fchmod(2) – ee-oss-op-c
1 OSS SEEP Result POSIX ACL Result Standard OSS Permissions Result Directory Search Denial1 SOA Member Final Result NO N/A N/A N/A YES Success (because SOA member overrules OSS SEEP result of NO) NORECORD N/A N/A YES N/A Failure (because directory search denial) NORECORD YES N/A NO N/A Success NORECORD NO N/A NO NO Failure (because ACL result of NO) NORECORD NO N/A NO YES Success (because SOA member overrules ACL result of NO) NORECORD None YES NO N/A Success NOREC
1 OSS SEEP Result POSIX ACL Result Standard OSS Permissions Result Directory Search Denial1 Final Result NORECORD None YES NO Success NORECORD None NO NO Failure (because standard permissions result of NO) Directory-search authorization error due to Standard OSS Permissions The OSS name server performs its normal standard OSS permissions or POSIX ACLs evaluation upon a NORECORD ruling from the OSS SEEP. NOTE: An OSS SEEP response timeout is treated as NORECORD for all users.
Header_Data Table 43 shows the structure of the header data sent from the OSS name server to the OSS SEEP. The header is always present. When the OSS SEEP responds to an event request, it is expected to alter these fields in the header data: • Error • Status • SubjectData • MessageData NOTE: The field names in the following table are pseudonyms and do not exactly match the names as specified in the DDL. For variable names, see the DDL output. The DDL is located in the ZOSS.SEEPDDL file.
Table 43 Header_Data (continued) Field Type Description 3501 = Message size exceeded maximum expected message size 3503 = OSS SEEP does not support this message data type 3505 = OSS SEEP’s supported message version is lower than MinMsgVersion of this message Status short (2 bytes) Status of the reply message. This field is valid only for the OSS_ACCESS_CONTROL message type and if the Error field contains the value 0.
Table 44 Subject_Data (continued) Field Type Description SavedGroupID int (4 bytes) The subject's saved group ID. AuthNode Int (4 bytes) Last authenticated node number for a remote subject, zero otherwise. Valid only if associated AuthNodeValid is set (True). GroupList VAR-STRING The subject’s supplementary group list. AuthNodeValid BOOLEAN True indicates the AuthNode field contains a valid remote node value. IsSOA Boolean Indicates if the user is an SOA member.
Table 45 Message_Data (Access Control) (continued) Field Type Description NewGroup int (4 bytes) The OSS object's new group. Valid only for the chgrp() function. Mode int (4 bytes) The file mode. NewMode int (4 bytes) The new file mode for the chmod() function. Also the open or access type for the open(), open64(), FILE_OPEN_ and access() APIs. IsRestrictedFileset Boolean TRUE indicates the file belongs to a restricted-access fileset.
• While attempting to start the OSS SEEP with the configured process name, if there is already a process running with the same name, the OSS name server stops the process and starts the OSS SEEP with that name. • There is an error sending an authorization request to the OSS SEEP. The EMS event reports a communication error with the OSS SEEP. After the EMS event is generated for an OSS SEEP's failure to start, the same EMS event is not generated for a predefined hold-off period of 2 minutes.
11 64-Bit Support in OSS and Guardian The HP NonStop H06.24 RVU (and later H-series RVUs) and the J06.13 RVU (and later J-series RVUs) offer several features to enable the full power of 64-bit computing. These RVUs include tools to help you transition from 32-bit applications to 64-bit OSS applications. NonStop TNS/E systems running H06.24 and later H-series RVUs or J06.
• 64-bit threaded applications must use the Posix User Threads library. • 32-bit and 64-bit processes can communicate through inter-process communication (IPC) messages and shared memory. 64-Bit OSS Processes A 32-bit OSS process is created when running an OSS program that was compiled under the ILP32 data model, which is the default data model. (See “ILP32 and LP64 Data Models” (page 289) for details of the OSS data models.
Process Type Attribute The type of process—32-bit or 64-bit—is recorded in the process control block (PCB) during process creation and is provided by the PROCESS_GETINFOLIST_ Guardian procedure. The attribute code for determining if a process is 64-bit is 155 (ZSYS_VAL_PINF_IS_64BIT). New PROCESS_GETINFOLIST_ Attributes New PROCESS_GETINFOLIST_ 64-Bit-Wide Attributes PROCESS_GETINFOLIST_ has new 64-bit attributes that provide information about the 64-bit addresses and values used by a process.
Table 47 PROCESS_GETINFOLIST_ Superseded 32-Bit-Only Attributes (continued) Code Attribute Data Type Description 107 ZSYS_VAL_PINF_PRIVSTACK_MAX INT(32) Maximum privileged stack size 108 ZSYS_VAL_PINF_GLOBALS_ORG INT(32) 32-bit address start of global data 109 ZSYS_VAL_PINF_GLOBALS_SIZE INT(32) Size of global data 113 ZSYS_VAL_PINF_SPACE_GUARANTEE INT(32) Guaranteed swap/memory space The above PROCESS_GETINFOLIST_ equivalent 32-bit-only attributes: • Are superseded and HP recommends using
64-Bit Heap and 32-Bit Heap for 64-Bit OSS Processes 64-Bit Heap for 64-Bit Processes The default Heap Manager for 64-bit OSS processes manages space in the 64-bit addressable part of process-private virtual memory.
Beginning with the H06.24 and J06.13 RVUs, C/C++ also supports a 64-bit data model, called LP64. This name indicates that long and pointer data types are 64 bits wide. In this model, int remains 32 bits wide. The following table shows the size (in bits) for the various C/C++ data types in the ILP32 and LP64 data models.
NOTE: 32-bit processes—whether OSS or Guardian—can only access 64-bit memory through flat segments that are allocated using the SEGMENT_ALLOCATE64_ Guardian procedure. You can use SEGMENT_ALLOCATE64_ to share 64-bit memory segments between 32-bit and 64-bit processes. SEGMENT_ALLOCATE64_ is similar to SEGMENT_ALLOCATE_ and it allocates a flat segment in the 64-bit space. For information about SEGMENT_ALLOCATE64_, see the Guardian Procedure Calls Reference Manual in the NTL.
C/C++ Language Features Supporting 64-Bit Addressing Beginning with the H06.24 and J06.13 RVUs, the C/C++ compilers hosted on Guardian, OSS, and Windows support a command-line directive to specify the data model in the resulting compilation. The syntax is slightly different between the Guardian compilers and the other compilers. For detailed information about the NonStop C/C++ compilers in the OSS, Windows, and Guardian environments, see the latest C/C++ Programmer's Guide for NonStop Systems in the NTL.
The large file model is assumed in 64-bit OSS programs. File offsets are always 64 bits. For information about large file aware APIs, see “Large File Aware APIs” (page 80). 32-Bit and 64-Bit Public DLLs The following public DLLs have both 32-bit and 64-bit versions that are used by 32-bit and 64-bit processes, respectively. 32-bit public DLLs begin with the letter “Z” and 64-bit public DLLs begin with the letter “Y”.
SQL/MP is not supported for 64-bit OSS processes. New OSS Function in YPUTDLL A new PUT_FILE_WRITEREAD_() function is added to the YPUTDLL 64-bit PUT Library. This new function is used as a wrapper routine for the FILE_WRITEREAD_ and FILE_WRITEREAD64_ Guardian procedures. For information about PUT_FILE_WRITEREAD_(), see the Open System Services Library Calls Reference Manual in the NTL. For information about thread-aware Enscribe functions, see “Thread-Aware Enscribe Functions ” (page 420).
recv64_() recvfrom64_() strstr64() write64() Guardian Procedures Callable from 64-Bit OSS Processes A large number of Guardian procedures can be called from 64-bit OSS processes.
ERRNO_GET_ FILE_AWAITIO64_ FILE_CONTROL64_ FILE_CONTROLBUF64_ FILE_COMPLETE_GETINFO_ FILE_COMPLETE_SET_ FILE_COMPLETEL_ FILE_LOCKFILE64_ FILE_LOCKREC64_ FILE_CLOSE_ FILE_CREATE_ FILE_CREATELIST_ FILE_GETINFO_ FILE_GETINFOBYNAME_ FILE_GETINFOLIST_ FILE_GETINFOLISTBYNAME_ FILE_GETLOCKINFO_ FILE_GETRECEIVEINFO_ FILE_GETRECEIVEINFOL_ FILE_OPEN_ FILE_READ64_ FILE_READLOCK64_ FILE_READUPDATE64_ FILE_READUPDATELOCK64_ FILE_RENAME_ FILE_REPLY64_ FILE_SETKEY_ FILE_SETLASTERROR_ FILE_SETMODENOWAIT64_ FILE_SETPOSITION
FP_IEEE_EXCEPTIONS_SET_ FP_IEEE_ROUND_GET_ FP_IEEE_ROUND_SET_ GETCPCBINFO GETSYSTEMSERIALNUMBER GETTMPNAME GETTRANSID GETTRANSINFO HALTPOLL HEADROOM_ENSURE_ HIST_FORMAT_ HIST_GETPRIOR_ HIST_INIT_ JULIANTIMESTAMP TMF_GET_EXTTRANSID_() TMF_GETTXHANDLE_() TMF_SETTXHANDLE_() TMF_SUSPEND_() TMF_SUSPEND_EXT_() TMF_TXBEGIN_() TMF_TXHANDLE_FROM_BEGINTAG_() TMF_VERSION_() TRANSIDTOTEXT TS_NANOSECS_ TS_UNIQUE_COMPARE_ TS_UNIQUE_CONVERT_TO_JULIAN_ TS_UNIQUE_CREATE_ VRO_SET_ NOTE: Not all of the NonStop Kernel (NSK)
with 64-bit public DLLs and neutral DLLs. 32-bit applications can link with 32-bit public DLLs and neutral DLLs. ENOFT has been enhanced to display the data model. enoft> filehdr ******** ELF File Header Ident: Type: Target Machine: ... Flags: ELF64-bit Big_Endian NSK Linkfile IA64 (0x830000) NO_SHARED_GLOBALIZED Neutral DATA MODEL Data Models for Object Files Beginning with the H06.24 and J06.13 RVUs, the -set option for the eld linker has a new attribute named data_model.
A DLL type mismatch occurs when the linker searches for a 32-bit or 64-bit DLL, and the linker encounters a DLL of the opposite model. In this case: 1. The linker will: a. Issue a warning that a DLL of the incorrect model was found b. Remember the location of the incorrect DLL c. Continue searching 2. 3. If a DLL of the correct model (or a neutral DLL) is subsequently found, that DLL is used.
New pragma Directives There is limited support for the combining of modules compiled with different data models into a single loadfile. This feature is specifically limited to code that is intended for a data-model-neutral DLL. This feature is not allowed for user-level applications. It is the programmer's responsibility to insure that declarations and definitions are consistent between separately compiled modules that are to be combined. Two new pragmas are provided to aid in this.
Example 61 Mixed Data-Model Programming Example #pragma section definesave #if (_TANDEM_ARCH_ > 1) _tal _extensible short DEFINESAVE ( const char _ptr32 *, /* IN */ short _ptr32 *, /* OUT */ short , /* IN */ short _ptr32 *, /* OUT */ short /* IN */ ); #else _tal _extensible short DEFINESAVE ( const char _far *, /* IN */ short _far *, /* OUT */ short , /* IN */ short _far *, /* OUT */ short /* IN */ ); #endif /* This is where the program text starts */ #include ...
_ptr64_to_ptr32 This new builtin makes sure a program can safely truncate a 64-bit pointer to a 32-bit pointer. void _ptr32 * _ptr64_to_ptr32(void _ptr64 *); If the passed pointer is a sign-extended 32-bit pointer, its low-order 32 bits are returned. Otherwise, a run-time trap occurs. New OSS String Manipulation Functions The string.h file contains prototypes for new string manipulation functions that accept 64-bit pointers and data lengths. These functions return pointers that are also 64-bits wide.
Guardian Socket Interfaces • recv64 • recvfrom64_ • recvmsg64_ • recv_nw64_ • recvfrom_nw64_ • t_recvfrom_nw64_ • send64_ • sendmsg64_ • sendto64_ • send_nw64_ • sendmsg_nw64_ • sendto_nw64_ • t_sendto_nw64_ NOTE: Both 32-bit and 64-bit callers can pass 32-bit pointers and 64-bit pointers to these interfaces. The passed 32-bit pointers are automatically sign-extended to 64 bits wide. The passed 64-bit pointers are used as is.
• uid_t – For LP64, the uid_t type in /usr/include/sys/types.h, is changed from long to int. #ifdef __LP64 typedef int uid_t; #else typedef long uid_t; #endif • size_t – For LP64, the size_t type in /usr/include/sys/types.h, is changed from unsigned int to unsigned long. #ifdef __LP64 typedef unsigned long size_t; #else typedef unsigned int size_t; #endif • ssize_t – For LP64, the ssize_t type in /usr/include/sys/types.h, is changed from int to long.
Example 62 getsockname() Data Type Change for LP64 In this example, the current ILP32 code is: size_t length; struct sockaddr addr; getsockname( fd, &addr, &length ); For LP64, the ILP32 code would be changed as follows: socklen_t length; struct sockaddr addr; getsockname( fd, &addr, &length ); Note that the LP64 code would compile and work correctly with the ILP32 data model. For information about these socket functions, see the Open System Services System Calls Reference Manual in the NTL.
• stat structure – This new stat structure has the same fields as the stat64 structure, with the exception of 8-byte time fields. This structure is in /usr/include/sys/stat.h. • statvfs structure – This new statvfs structure has the same fields as the statvfs64 structure, with the exception of unsigned long fields. This structure is in /usr/include/ sys/statvfs.h.
Converting 32-Bit Applications to 64-Bit Applications The advantages of 64-bit applications are: • The string-manipulation and file and socket I/O APIs available for 32-bit applications that access 64-bit data segments are very limited. There are many more string-manipulation and file and socket I/O APIs available for 64-bit applications, which access 64-bit data segments.
HP recommends that code be compiled with the migration check warnings enabled, and each warning examined, before compiling with -Wlp64. 64-Bit Programming Guidelines When transitioning to 64-bit mode, strive to maintain a single set of source files and header files for both data models. Consider the following guidelines before porting to 64-bit mode: • Data Truncation – Truncation problems can happen when assignments are made between 64-bit and 32-bit data items.
• ◦ Casting an int to a pointer can cause errors when the pointer is de-referenced. ◦ Casts between long* to int* are problematic because the object of a long pointer is 64 bits in size, but the object of an int pointer is only 32 bits in size. ◦ Functions that return pointers, when declared implicitly, can return truncated values. ◦ Comparing an int to a pointer can cause unexpected results. ◦ Avoid pointer arithmetic between long and int.
• ◦ Avoid hardcoding bit shift values ◦ Avoid hardcoding constants with malloc()and malloc32() Bit Shifts and Bit Masks – Bit shifts and bit masks are sometimes coded with the assumption that the operations are performed in variables that have the same data type as the result. In cases such as: a = b operation c The data type used for the intermediate result of the operation depends on the types of b and c. The intermediate result is then promoted to the type of a.
Both Native Inspect and Eclipse-based debugging have been enhanced to support debugging of 64-bit processes.
There are significant time and space trade-offs with compression: • The none option is the fastest, but (the compressed dump) takes the most space. • The gzip option is the next fastest, but takes up less space than none. • The bzip2 option is the slowest, but takes up the least space. In the absence of a save option, and in the saveabend case, compression is selectively applied based on the uncompressed file size.
12 Using the Standard POSIX Threads Library Standard POSIX Threads is a user-space implementation of IEEE POSIX Standard 1003.1c pthreads for use by native C and C++ applications in the OSS environment on NonStop servers. The POSIX threads standard is officially described in International Standard ISO/IEC 9945-1; 1996 (E) IEEE Std 1003.1,1996 (Incorporating ANSI/IEEE Stds 1003.1-1990, 1003.1b-1993, 1003.1c-1995, and 1003.1i-1995). For simplicity, this chapter refers to the “Standard document.
Table 54 Process Resources (continued) Resource Type Description Thread context Private The data maintained by the threads library on behalf of a thread; contains the per-thread signal mask, which is used by the pthread_kill() function All external data Global Includes process and module global resources All static internal variables Global Heap Global File descriptors and file state Global SQL cursors Global Environment variables Global Signal mask Global Includes file and record locks
Attributes Defined by Threads Macros The attributes of Standard POSIX Threads are determined by macros in unistd.h. Table 55 lists the principal macros that influence the HP implementation for NonStop servers. Table 55 Attributes of Standard POSIX Threads Defined by Macros Macro or Attribute Description in Standard POSIX Threads Mutex and condition variable initialization attributes: _POSIX_THREAD_PROCESS_SHARED Not defined.
default signal action is taken. For a terminating signal, the default behavior is to terminate the process. For J-series RVUs, H06.06 and later H-series RVUs, and G06.29 and later G-series RVUs, you can define signal-catching functions for asynchronous signals. See “Thread-Aware Signal Handling” (page 317). The supported signal numbers are listed in Table 56. For more information about the Standard POSIX Threads implementation of signals, see “Using Signals” (page 330).
Table 56 Signals Processed by Threads (continued) Name Number Type 2 Default Action Description SIGURG 5 Asynchronous Discard signal Urgent condition on I/O channel SIGUSR1 16 Asynchronous Terminate process User-defined signal 1 SIGUSR2 17 Asynchronous Terminate process User-defined signal 2 SIGWINCH 12 Synchronous Discard signal Terminal device window size changed 1 Signal cannot be caught or ignored. 2 For H06.20 and earlier H-series RVUs and J06.
Types of Signals Signals are categorized as synchronous, asynchronous, or process level: • Synchronous signals result from an event that occurs inside a process and are delivered synchronously with that event. These signals are delivered to current active thread. If current active thread has not installed the signal handler, then default actions are performed.
Thread-Aware Signal Handling APIs These APIs are supported for J-series RVUs, H06.06 and later H-series RVUs, and G06.29 and later G-series RVUs: API Description spt_signal() Allows the calling thread to change the action to be taken when a specific signal is delivered to the thread issuing this function call. To enable thread-aware signal handling, export the SPT_THREAD_AWARE_SIGNAL environmental variable from within the shell to the value 1.
Example 63 Handling the Synchronous Signal SIGFPE /* This test program demonstrates handling the */ /* SIGFPE synchronous signal. */ /* You must also export the environment variable **/ /* SPT_THREAD_AWARE_SIGNAL to 1 to **/ /** enable thread-aware signal handling **/ #define SPT_THREAD_AWARE /** enables thread aware behavior **/ #define SPT_THREAD_SIGNAL /** maps signal() to spt_signal()**/ #include
Example 64 (page 322) creates a thread that waits for asynchronous signal SIGINT. Sample input: > kill -2 process-name or Both of these inputs generate a SIGINT signal. The output of Example 64 (page 322) depends on whether thread-aware signal handling is enabled: • If thread-aware signal handling is not enabled, the program terminates, which is the default behavior when signal 2 (SIGINT) is received. Sample output: Enter Testcase - .
Example 64 Handling the Synchronous Signal SIGINT /* Program which demonstrates behavior of Asynchronous */ /* signal SIGINT */ /** You must also export the environment variable **/ /** SPT_THREAD_AWARE_SIGNAL to 1 to **/ /** enable thread-aware signal handling **/ #define SPT_THREAD_AWARE /** enables thread aware behavior **/ /** and maps functions to spt_ versions **/ #include
Example 65 (page 324) demonstrates handling the SIGCHLD signal. This example creates two threads, each of which call fork(). When the child process executes, the process raises the SIGCHLD signal. The output of Example 65 (page 324) depends on whether thread-aware signal handling is enabled: • If thread-aware signal handling is not enabled, the SIGCHLD signal results in the default action described in Table 56 (page 316) (discard the signal).
Example 65 Handling the SIGCHLD Signal /* This program demonstrates the handling of the */ /* SIGCHLD signal */ /** You must also export the environment variable **/ /** SPT_THREAD_AWARE_SIGNAL to 1 to **/ /** enable thread-aware signal handling **/ #define SPT_THREAD_AWARE /** enables thread aware behavior **/ /** and maps functions to spt_ versions **/ #include
} void sig_cld1(int signo) { printf("\nSignal received for Thread1 is %d\n",signo); } void sig_cld2(int signo) { printf("\nSignal received for Thread2 is %d\n",signo); } Example 66 (page 326) provides an example of SIGALRM handling. It creates two threads that wait for a SIGALRM signal. The output of Example 66 (page 326) depends on whether thread-aware signal handling is enabled: • If thread-aware signal handling not enabled, the entire process terminates when the SIGALRM signal is received.
Example 66 Handling SIGALRM Signals /*Program demonstrating handling the SIGALRM signal */ /** You must also export the environment variable **/ /** SPT_THREAD_AWARE_SIGNAL **/ /** to 1 to enable thread-aware signal handling **/ #define SPT_THREAD_AWARE /** enables thread aware behavior and maps **/ /** functions other than alarm() and signal() to their spt_ versions**/ #define SPT_THREAD_SIGNAL /** maps alarm() to spt_alarm()**/ #include
Threads Portability Standard POSIX Threads follow the POSIX threads Standard document. Using thread functions whose names end with _np (non-portable) decreases the portability of a program, because these functions are extensions to the standard. Using the jacket routines provided by HP also reduces portability of a threaded application; see “Jacket Routines” (page 333) for more information about the jacket routines.
Keeping Application Design Simple Because of the inherent complexity of multithreaded programming, application designers should follow these recommendations: • Write programs with a single application thread when possible. • Keep multiple application threads independent of each other when possible. If this is not possible, keep the interdependencies to a minimum.
When using functions that return pointers to static library data, immediately copy the data to thread-private memory. Beware of Libraries That Maintain Context Across Calls Some libraries maintain context across calls. For example, the getpwent() function returns information about the next user in the user database, with the current position kept implicitly in the library. The setpwent() function ensures that the next call to getpwent() returns the first user entry.
Yielding Control Because Standard POSIX Threads are never preempted, a call to the sched_yield() function might be needed to allow time-critical run-time threads to execute. This function releases the processor to another thread of the same or higher priority. The calling thread may get control immediately if no threads of the same or higher priority are ready to run. Be careful using the sched_yield() function.
The sigsetjmp() and siglongjmp() functions have an option to save and restore the signal mask. This option can cause signals that were enabled by another thread to be inadvertently masked. When handling signals: • Do not use the raise() function for an exception, and do not use the longjmp() function to exit a synchronous signal handler. Simply returning from a signal handler is safe and is the recommended practice.
In single-threaded applications: • Process resources can be used freely. No synchronization is needed. The application can freely use process resources such as process and module globals, the heap, file descriptors, SQL cursors, and the signal mask. Mutexes and condition variables are not needed. • Standard libraries can be used freely. The application can share access to library data, including implicit context maintained across multiple library calls.
This type of application includes OSS servers that maintain application state in the server to improve performance or that share resources, such as file opens, to reduce resource consumption. This type of application also includes client programs that use parallelism. Programs with multiple interdependent application threads can be synchronized by using mutexes to reserve access to a shared resource and by using condition variables to wait for a shared resource to be in a certain state.
SERVERCLASS_DIALOG Jacket Routines The Pathsend SERVERCLASS_DIALOG jacket routines are used to: • Establish a dialog with a server instance in a Pathway server class • Send and receive messages within the dialog • Abort or end the dialog The Context-Sensitive Pathway requester can be written using the thread-aware SERVERCLASS_DIALOG jacket routines to communicate with a server instance in the Pathway server class.
• If a thread is created, it does not inherit its parent's transaction; the created thread's transaction context is nil. • If a thread terminates or is destroyed while it has an active transaction, that transaction is then inaccessible from the process. If cancellation is a possibility, use exception handlers for pthread_cancel_e. Alternatively, use the pthread_cleanup_push() and pthread_cleanup_pop() functions to ensure that the transaction is terminated if the thread exits or is cancelled.
Example 67 Threaded Time-of-Day Server Socket /* Threaded time-of day server socket. */ /* If compiled for TNS/R, specify the ZSPTSRL compilation option. */ /* If compiled for TNS/E, specify the ZSPTDLL, the standard POSIX threads */ /* shared run-time library. */ #include #include #include #include #include #include /* Defines thread-aware functions calls to the threads package: */ #define SPT_THREAD_AWARE #include
if(pthread_setconcurrency(1)) { perror("pthread_setconcurrency"); exit(-1); } /* Initializes attribute: */ if(pthread_attr_init(&my_attr)) { perror("pthread_attr_init"); exit(-1); } /* Sets detach Attribute: */ if(pthread_attr_setdetachstate(&my_attr,PTHREAD_CREATE_DETACHED)) { perror("pthread_attr_setdetachstate"); exit(-1); } /* Creates socket: */ if ((sock = socket(AF_INET, SOCK_STREAM, 0)) < 0) { perror("Socket Error"); exit(-1); } /* Sets up Bind: */ bzero(&servaddr, sizeof(servaddr)); servaddr.
accept_fd = accept(sock, NULL, NULL); if (accept_fd < 0) { perror("Accept Error"); exit(-1); } /* Dispatches a thread to handle service request: */ if(pthread_create(&my_thread,&my_attr,&worker_thread,&accept_fd) { perror("pthread_create"); exit(-1); } } /* while */ }/* main */ Example 68 (page 339) also creates a threaded time-of-day server socket, but using $RECEIVE.
Example 68 Threaded Time-of-Day Server Socket Using $RECEIVE #include #include #include #include #include #include #define SPT_THREAD_AWARE /* Must come after cextdecs.h: */ #include
{ perror("pthread_attr_init"); exit(-1); } /* Sets detach state for thread attribute: */ if(pthread_attr_setdetachstate(&my_attr,PTHREAD_CREATE_DETACHED)!=0) { perror("pthread_attr_setdetachstate"); exit(-1); } error = FILE_OPEN_(filename, (short)strlen(filename), &filenum, 0, , 1, 10, 1); fprintf(stderr,"main: FILE_OPEN_: error: %d\n",error); assert(error == 0); error = spt_INITRECEIVE(filenum, 10); fprintf(stderr,"main: spt_initReceive: error: %d\n",error); fflush(stderr); assert(error == 0); while (1) {
other threads in the process are nonblocking functions. Nonblocking I/O functions are sometimes called asynchronous I/O functions. The behavior of an OSS I/O library function can vary according to these factors: • Whether the file descriptor is for a regular file or a non-regular file. • Whether the function was designed to be process-blocking, thread-aware (thread-blocking), or nonblocking for that type of file. • Whether the file descriptor passed to the function is nonblocking.
Non-Regular Files For non-regular files, there are functions that can provide thread-aware behavior or both nonblocking and thread-aware behavior: • The spt_*() set of functions are thread aware only if the file descriptor is nonblocking. The behavior of these functions depend on how the file descriptor O_NONBLOCK flag is set: ◦ If O_NONBLOCK (fd flag) is set, then the call will not block the other calling threads. It might block the calling thread depending on the function call.
Table 58 Comparison of spt_*, spt_*x, and spt_*z Functions Function Set Behavior for Non-Regular Files Behavior for Regular Files spt_*() File descriptor is nonblocking: Always process-blocking (all threads in the process must wait for I/O to complete). ◦ Function is thread-aware (other threads can continue to run) ◦ Function blocks the calling thread. File descriptor is not nonblocking: this function is process-blocking (all threads in the process must wait for I/O to complete).
EAGAIN, EINPROGRESS, or EWOULDBLOCK. Otherwise, this function blocks the calling thread but allows other threads to run. ◦ • For regular files, this function blocks the entire process. spt_readz() is a thread-aware function with this behavior: ◦ For non-regular files, this function does not require the file descriptor to be nonblocking for this function to be thread-aware.
Table 59 System and Equivalent Thread-Aware Functions (continued) Standard (Process-Blocking) Thread-Aware Functions OSS Functions (Non-Regular Files Only) Nonblocking Thread-Aware Thread-Aware (Regular Files) Functions (Non-Regular Files and Nonblocking Only) Thread-Aware (Non-Regular Files) Functions gets() spt_gets() spt_getsx() getw() spt_getw() spt_getwx() getwc() spt_getwc() spt_getwcx() getwchar() spt_getwchar() spt_getwcharx() printf() spt_printf() spt_printfx() putc() spt_putc()
Preprocessor Directives Automatically Map Standard System Calls to Thread-Aware or Nonblocking Thread-Aware System Calls When you use preprocessor directives when compiling the application, standard system calls are automatically mapped to the appropriate Standard POSIX Thread system call, eliminating the need to explicitly call spt_*(), spt_*x(), or spt_*z() functions. Using preprocessor directives is preferred to using explicit calls to thread-aware or nonblocking thread-aware functions.
Defining Nonblocking Thread-Aware Functions for Non-Regular Files The spt_*x() set of nonblocking thread-aware functions for non-regular files are available on systems running J-series RVUs, H06.05 and later H-series RVUs, and G06.28 and later G-series RVUs. For C applications, a macro to map interface() to spt_interfacex() is available when you use the #define SPT_THREAD_AWARE_NONBLOCK preprocessor directive before including spthread.
NOTE: When you use the #define SPT_THREAD_AWARE_XNONBLOCK or #define SPT_THREAD_AWARE_PRAGMA_XNONBLOCK, if a function has a corresponding spt_*x() function but not a corresponding spt_*z() function, the function is mapped to the corresponding spt_*x() function. The following example illustrates using the SPT_THREAD_AWARE_XNONBLOCK define: #define SPT_THREAD_AWARE_XNONBLOCK #include main() ...
Example 69 File Stream Thread-Aware Function Usage ... fs = fopen(path, mode); fd = fileno(fs); fcntl(fd, F_SETFL, fcntl(fd, F_GETFL) | O_NONBLOCK); ... // Call thread-aware functions. ... fclose(fs); ... Example 70 (page 349) shows opening a file descriptor for use with a thread-aware function. If the file descriptor is to be used with a nonblocking thread-aware function, it is not necessary to set the O_NONBLOCK flag. Example 70 File Descriptor Thread-Aware Function Usage ...
Example 72 Pthreads Nonblocking Disk File I/O (SPT_THREAD_AWARE_NONBLOCK version) /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ sptdio.c - SPThreads Diskfile IO Example Program This Pthreads program demonstrates a multithreaded program that can perform I/O on multiple OSS regular files (diskfiles) using non-blocking OSS I/O and Guardian nowaited I/O.
/********************/ /* LITERALS/DEFINES */ /********************/ /* the maximum number of I/O threads created by this program */ #define MAX_THREADS 4 /* concurreny level value passed to pthread_setconcurrency() */ /* the value of 100000 sets the minimum scheduled quantum to */ /* 0.000001 seconds.
/**********************************************/ /* read the OSS file in a thread aware manner */ /**********************************************/ while (1) { nbytes = read(fd, iobuf, IOSIZE); if (nbytes < 0) { if ((errno == EWOULDBLOCK) || (errno == EAGAIN)) { /**************************************************************************/ /* NOTE that this code does not execute for regular (disk) files, because */ /* read() on a regular file never returns EWOULDBLOCK or EAGAIN */ /***************************
/* *----------------------------------------------------------------------* * OSS_write_thread -* * Description: * * This thread writes an OSS file using OSS I/O. * Note that OSS I/O on regular files is serialized and only one OSS I/O * per open can occur at a given time. Even though we use the thread * aware library,the entire program blocks while the OSS write() * function performs the I/O. * * Results: * none.
/*******************************************************************/ /* NOTE that this code does not execute for regular (disk) files, */ /* because write() on a regular file never returns EWOULDBLOCK or */ /* EAGAIN */ /*******************************************************************/ ret = spt_fd_write_ready(fd, NULL); if (ret != 0) { printf("*** ERROR in OSS_write_thread: spt_fd_write_ready()failed w/error %d ***\n", ret); exit(0); } } else { printf("*** ERROR in OSS_write_thread: write() failed w/er
char *iobuf; short err; spt_error_t spte; long error; _cc_status cc; long tag; long long filesize = 0; if ((iobuf = malloc(IOSIZE)) == NULL) { printf("*** ERROR in Grd_READ_thread: I/O buffer ***\n"); exit(0); } memset(iobuf, 0, IOSIZE); unable to allocate /**********************************************************/ /* open the OSS file using FILE_OPEN_() so we can do */ /* Guardian nowait I/O */ /**********************************************************/ err = FILE_OPEN_(Grd_READ_file, (short) sizeof(G
spte = spt_awaitio(fnum, tag, -1, &count_read, &error, NULL); if (spte != SPT_SUCCESS) { (void) CANCELREQ(fnum, tag); printf("*** ERROR in Grd_READ_thread: spt_awaitio() failed w/error %d ***\n", (int) error); exit(0); } else if (error == 1) /* EOF */ break; filesize += count_read; } } /* while */ spt_unregFile(fnum); FILE_CLOSE_(fnum); printf("==> Grd_READ_thread() read %ld bytes from file %s\n", filesize, Grd_READ_file); return(NULL); } /* *---------------------------------------------------------------*
/* create the OSS file before opening it with Guardian FILE_OPEN_() */ if ((fd = open(Grd_WRITE_file, O_WRONLY | O_NONBLOCK | O_CREAT | O_TRUNC, S_IRWXU)) < 0) { printf("*** ERROR in Grd_WRITE_thread: open() of %s failed w/error %d ***\n", Grd_WRITE_file, errno); exit(0); } close(fd); /******************************************************************/ /* now open the OSS file using FILE_OPEN_() so we can do */ /* Guardian nowait I/O */ /************************************************************ *****/
spt_unregFile(fnum); FILE_CLOSE_(fnum); printf("==> Grd_WRITE_thread() wrote %d bytes to file %s\n", WRITE_FILESIZE, Grd_WRITE_file); return(NULL); } int main(int argc, char *argv[]) { /* the following variables correspond to the OSS filenames specified /* as command line parameters to the program char OSS_read_filename[PATH_MAX]; char OSS_write_filename[PATH_MAX]; char Grd_READ_filename[PATH_MAX]; char Grd_WRITE_filename[PATH_MAX]; /* total number of threads that have been created */ int nmbr_created_threa
/********************************************************/ /* Set the concurrency level for the thread scheduler */ /********************************************************/ pthread_setconcurrency(CONCURRENCY_LEVEL); /**********************************/ /* Create all of the I/O threads */ /**********************************/ for (i = 1; i < argc; i = i + 2) { if (strcmp(argv[i], "-r") == 0) { pthread_create(&thread_handle[nmbr_created_threads++], NULL, &OSS_read_thread, OSS_read_filename); } else if (st
Example 73 Pthreads Thread-Aware Disk File I/O Using SPT_THREAD_AWARE_XNONBLOCK /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ sptdio.c - SPThreads Diskfile IO Example Program This Pthreads program demonstrates a multithreaded program that can perform I/O on multiple OSS regular files (diskfiles) using thread-aware OSS I/O functions available on systems running J06.04 and later J-series RVUs or H06.15 and later H-series RVUs.
/* *----------------------------------------------------------------* OSS_read_thread -* * Description: * * This thread reads an OSS file using OSS I/O. Because this program * uses the define SPT_THREAD_AWARE_XNONBLOCK, the read() function is * mapped to the spt_readz() function, which is thread-aware and blocks * the thread instead of the entire process. Other threads are free to * do work while this thread is blocked waiting for an I/O completion. * * * Results: * none.
/*******************************************************************/ /* NOTE that this code does not execute for regular (disk) files, */ /* because read() on a regular file never returns EWOULDBLOCK or */ /* EAGAIN */ /*******************************************************************/ ret = spt_fd_read_ready(fd, NULL); if (ret != 0) { printf("*** ERROR in OSS_read_thread: spt_fd_read_ready() failed w/err %d\n",ret); exit(0); } } else { printf("*** ERROR in OSS_read_thread: %d ***\n",errno); exit(0); }
/*****************************************************************/ /* prepare I/O buffer (page aligned, paged into physical memory) */ /*****************************************************************/ if ((iobuf = malloc(IOSIZE)) == NULL) { printf("*** ERROR in OSS_write_thread: ***\n"); exit(0); } memset(iobuf, 0, IOSIZE); unable to allocate I/O buffer /*********************/ /* open the OSS file */ /*********************/ if ((fd = open(OSS_write_file, O_WRONLY | O_NONBLOCK | O_CREAT | O_TRUNC, S_I
printf("==> OSS_write_thread() wrote %d bytes to file %s\n", WRITE_FILESIZE, OSS_write_file); return(NULL); } int main(int argc, char *argv[]) { /* the following variables correspond to the OSS filenames specified /* as command line parameters to the program char OSS_read_filename[PATH_MAX]; char OSS_write_filename[PATH_MAX]; /* total number of threads that have been created */ int nmbr_created_threads = 0; /* array of handles for each thread created */ pthread_t thread_handle[MAX_THREADS]; int i; */ */ /
else if (strcmp(argv[i], "-w") == 0) { pthread_create(&thread_handle[nmbr_created_threads++], NULL, &OSS_write_thread, OSS_write_filename); } } printf("\n==> All threads created...
Table 60 System and Equivalent Reentrant Functions System Function Reentrant Function asctime() asctime_r() ctermid() ctermid_r() ctime() ctime_r() gamma() gamma_r() getgrent() getgrent_r() getgrgid() getgrgid_r() getgrnam() getgrnam_r() gethostbyaddr() gethostbyaddr_r() gethostbyname() gethostbyname_r() gethostent() gethostent_r() getlogin() getlogin_r() getnetbyaddr() getnetbyaddr_r() getnetbyname() getnetbyname_r() getnetent() getnetent_r() getprotobyname() getprotobyname_r
Example Program Using Reentrant Functions Example 74 (page 368) provides an example program that uses the strtok_r() reentrant fuction.
Example 74 Using the Reentrant Function strtok_r /* reent.c - Using the reentrant function strtok_r * * Compilation steps: * * /usr/bin/c89 -Wextensions -Wsystype=oss -c reent.c -o reent.o * /usr/bin/nld /usr/lib/crtlmain.o reent.o ./libspt.a -obey \ * /usr/lib/libc.obey -lzcplsrl -o reent */ #include #include
For details on each function, see the appropriate reference page in the Open System Services System Calls Reference Manual. Table 61 Thread-Aware Toolkit Functions and Types Function Description spt_unregFile() Unregister the file number as one you will manage. Any threads waiting on file number I/O will awaken with SPT_ERROR and system error 16. spt_FileIOHandler_p() Callback type required by spt_regFileIOHandler().
Example 75 Thread-Aware Toolkit Program Flow ... FILE_OPEN(…, &filenum, …); spt_regFile(filenum); ... // Do work on filenum. ... spt_unregFile(filenum); FILE_CLOSE(filenum); ... Example 76 Simplified Program Flow For a Thread-Aware Function ... READX(filenum, ...); spte = spt_awaitio(filenum, tag, -1, count_read, &error, NULL); if (spte != SPT_SUCCESS) (void) CANCELREQ(filenum, tag); return error; ... Example 77 illustrates using a thread-aware read() function.
thread-aware library (spt_*x() functions) or the thread-aware library for regular files (spt_*z() functions). If you were to use this code with the thread-aware library instead of the nonblocking thread aware library, you risk blocking the whole process if the file descriptor does not have the O_NONBLOCK flag set. Example 78 Nonblocking Thread-Aware read() Function /* /* /* /* /* This program fragment assumes you are using the nonblocking thread- */ aware library.
Example 79 Example READX() Function Used In Thread-Aware Manner { spt_error_t spte; long error; _cc_status cc; long tag; tag = spt_generateTag(); cc = READX(filenum, buffer, read_count, , tag); /* If READX() failed. */ if (_status_lt(cc)) { short short_error; (void) FILE_GETINFO_(filenum, &short_error); return short_error; } /* Loop forever. */ while (1) { spte = spt_awaitio(filenum, tag, timelimit, count_read, &error, NULL); /* If spte is SPT_INTERRUPTED then try again.
For details on each function, see the appropriate reference page in the Open System Services System Calls Reference Manual. The functions listed above provide only basic $RECEIVE handling support, not higher-level capabilities associated with a $RECEIVE package. You can build such higher-level functions using the primitives present in the thread-aware $RECEIVE functions, but must tailor them for whatever domain-specific application they occur in.
Example 81 Function with spt_RECEIVEREAD() and spt_REPLYX() ... while (1) { if (spt_RECEIVEREAD(…) != 0) break; ... // Do work. ... if (spt_REPLYX(…) != 0) break; } ... Example 82 shows a single thread calling the thread-aware spt_RECEIVEREAD() function. Using thread-aware $RECEIVE functions allows one or more threads to perform work on $RECEIVE, without a thread unnecessarily blocking another thread.
Example 82 $RECEIVE Server #include #include short filenum; void * thread_start(void *parms) { long bytesread, error; char buffer[2]; short receive_info[17]; while (1) { error = spt_RECEIVEREAD(filenum, buffer, (short)sizeof(buffer), &bytesread, -1, receive_info, NULL); if (error != 0) break; // Do real work here! error = spt_REPLYX("server's reply.
if (pthread_join(thread2, NULL) != 0) { perror("main: pthread_join"); exit(1); } } Caveats to Using Thread-Aware $RECEIVE Proper operation of thread-aware $RECEIVE depends on the following conditions: • No calls to AWAITIO[X] () with a file number of -1 are made. • No calls to AWAITIO[X] () with a file number for $RECEIVE are made. • No calls to FILE_COMPLETE_SET_ () are made. • No calls to FILE_COMPLETE_ () are made using the permanent set.
Table 63 Thread-Aware Enscribe Functions (continued) Function Description SPT_SETMODE Sets device-dependent functions SPT_WRITEREADX Writes data to a file from an array in the application, then waits for data to be transferred back from the file SPT_WRITEX Writes data from an array in the application to an open file SPT_WRITEUPDATEX Transfers data from an array in the application to a file SPT_WRITEUPDATEUNLOCKX Performs random processing of records in a disk file SPT_LOCKFILE Excludes other us
Example 83 Using the Thread-Aware SPT_FILE_OPEN Function /* Using the thread-aware SPT_FILE_OPEN function #include #include #include #include #include */ short filenum; void *Thread2(void *args) { printf("Hello, I am Thread2\n"); } void *Thread1(void *args) { short error; char *name = "$SYSTEM.TEST.
OSS File Descriptor and Timer Callbacks Thread-aware functions listed in Table 64 allow registration and use of callbacks for OSS file descriptors and timer callbacks. For details on each function, see the appropriate reference page in the Open System Services System Calls Reference Manual. Table 64 Thread-Aware Callback Functions and Types Function Description spt_OSSFileIOHandler_p Callback type required by spt_regOSSFileIOHandler().
13 Using the POSIX User Thread (PUT) Model Library The POSIX User Model Thread library is a user-space implementation of IEEE Std 1003.1, 2004, POSIX System Application Program Interface for use by native C and C++ TNS/E-targeted applications in the OSS environment on NonStop servers. This library is supported on systems running H06.21 and later H-series RVUs and J06.10 and later J-series RVUs.
_PUT_SELECT_SINGLE_ This define maps select() to a variant of select() that checks the status of a single file descriptor using a faster algorithm. (This is equivalent to SPT_SELECT_SINGLE in the SPT library.) Environment Variables PUT_THREAD_AWARE_REGULAR_IO_DISABLE Allows you to disable the thread aware regular file I/O behavior. For more information about thread-aware regular file I/O behavior, see “Thread-Aware and Nonblocking OSS Functions” (page 396).
sigaction() sigsuspend() sleep() wait() waitpid() Attributes Defined by Threads Macros The attributes of the PUT Model library are determined by macros in unistd.h. Table 65 lists the principal macros that influence the HP implementation for NonStop servers. Table 65 Attributes of the POSIX User Thread Model Library Defined by Macros Macro or Attribute Description in the POSIX User Thread Model Library _POSIX_THREADS Implementation supports threads options.
Process Resources All resources of a process—for example, open files or memory—are either global or private, as shown in Table 66. Private resources can be accessed only by a specific thread. Global resources can be accessed by all threads. Access to global resources by threads should be synchronized using mutex or condition variables.
Table 67 Numerical Limits in the POSIX User Thread Model Library Symbolic Constant Description _POSIX_ARG_MAX Maximum length of the arguments for one of the 4096 exec functions, in bytes, including environment data _POSIX_CHILD_MAX Maximum number of simultaneous processes for 6 one real user ID _POSIX_DESTRUCTOR_ITERATIONS Maximum number of attempts to destroy the thread-specific data of a thread on termination 4 _POSIX_FD_SETSIZE Maximum number of descriptors that a process can examine _POSIX_OP
Table 67 Numerical Limits in the POSIX User Thread Model Library (continued) Symbolic Constant Description Value PTHREAD_STACK_MIN Minimum number of bytes available for the thread 4096 stack. PTHREAD_THREADS_MAX Maximum number of threads supported per process 2048 Signals and Signal Handling Types of Signals There are two basic types of signals: • Synchronous signals represent events that occur inside a process.
Table 68 Signals Processed by Threads (continued) Name Number Type Default Action Description SIGNOMEM 23 Synchronous Terminate with saveabend No memory available SIGPIPE 13 Asynchronus Terminate process Write on a pipe, no one to read it SIGQUIT 3 Asynchronous Terminate with saveabend Quit SIGRECV 19 Synchronous Discard signal Message queued on $RECEIVE (currently not used) SIGSEGV 11 Synchronous Terminate with saveabend Invalid address reference SIGSTK 25 Synchronous Termi
usleep() wait() waitpid() • The pthread_kill() function provides a mechanism for synchronously directing a signal to a thread in the calling process. Signals sent with the pthread_kill() function are queued in FIFO order for the target thread. More than one instance of the same signal might be pending for a thread. However, applications should not rely on this ordering. • A signal is handled in the context of the given thread.
Using Signals With the setjmp() and longjmp() Functions Using the setjmp() and longjmp() functions can interfere with signal handling. The longjmp() function causes a thread to jump to the execution context saved by a previous call to the setjmp() function, but it does not restore the signal mask of the process. If the longjmp() function is called within a signal handler, the signal mask used in the signal handler is retained when execution resumes at the setjmp() location.
Types of Signals Signals are categorized as synchronous, asynchronous, or process level: • Synchronous signals result from an event that occurs inside a process and are delivered synchronously with that event. These signals are delivered to current active thread. If current active thread has not installed the signal handler, then default actions are performed.
executed, and signal 8 (SIGFPE) is received by the thread. On successful return from a signal-catching function for a SIGFPE, SIGILL, SIGLIMIT,SIGMEMERR, SIGMEMMGR, SIGNOMEM, SIGSEGV, SIGABRT, or SIGSTK signal that was not generated by a kill() or raise() function call, a process receives a SIGABEND signal and terminates. Example 86 Handling the Synchronous Signal SIGFPE /* This test program demonstrates handling the */ /* SIGFPE synchronous signal.
In Example 87 (page 391), the signal handler of thread1 is executed and thread1 no longer waits for a signal. Sample output: Enter Testcase - ./Test2 sigaction returned 0 Wait for threads to complete Signal received is 2 sigsuspend returned -1 Main completed. Example 87 Handling the Synchronous Signal SIGINT /* Program that demonstrates behavior of Asynchronous */ /* signal SIGINT */ #define _PUT_MODEL_ /** enables thread aware behavior **/ #include #include #include
Example 88 (page 393) demonstrates handling the SIGCHLD signal. This example creates two threads, each of which call fork(). When the child process executes, the process raises the SIGCHLD signal. The SIGCHLD signal is delivered to the correct thread, and sigaction() function in the example defines the action to be taken.
Example 88 Handling the SIGCHLD Signal /* This program demonstrates the handling of the */ /* SIGCHLD signal */ #define _PUT_MODEL_ /** enables thread aware behavior **/ #include #include #include #include #include #include “myio.h” /** contains my_printf which is process-blocking**/ struct sigaction sigset_t waitset; int rc; sigact_t,osigact_t; void sig_cld1(int); void sig_cld2(int); void *do_work1(void *arg) { pid_t pid; sigact_t.
pthread_join(tid1,NULL); pthread_join(tid2,NULL); my_printf ("\nMain Completed\n"); } void sig_cld1(int signo) { my_printf("\nSignal received for Thread1 is %d\n",signo); } void sig_cld2(int signo) { my_printf("\nSignal received for Thread2 is %d\n",signo); } Example 89 (page 395) provides an example of SIGALRM handling. It creates two threads that wait for a SIGALRM signal. The SIGALRM signal is delivered to the correct thread, and the sighand1() and sighand2() functions define the actions to be taken.
Example 89 Handling SIGALRM Signals /*Program demonstrating handling the SIGALRM signal */ #define _PUT_MODEL_ /** enables thread aware behavior **/ #include #include #include #include “myio.h” /** contains my_printf which is process-blocking**/ void sighand1(int); void sighand2(int); struct sigaction sigact_t; int rc; void *do_work(void *arg) { sigset_t set; sigfillset(&set); sigdelset(&set,SIGALRM); sigact_t.
my_printf("Signal received is %d\n",signo); } Thread-Aware and Nonblocking OSS Functions If a function must wait for an I/O operation to complete, the function blocks its caller (either a thread or a process) from continuing until the I/O operation completes. A function that blocks all threads while it waits for I/O to complete is a process-blocking function. Process-blocking functions are not thread aware.
Serialization of File Operations On an Open File The PUT Model library supports a thread-aware set of functions that serialize file operations on an open regular file. If a thread calls one of the thread-aware functions to access a file that already has a file operation in progress by a different thread, the calling thread is blocked until the prior file operation is complete. For example: 1. Thread A calls the thread-aware version of the read() function to read the open file MyDataFile.
Table 69 System and Equivalent Thread-Aware Functions Standard (Process-Blocking) OSS Functions Nonblocking and thread aware in PUT Model library for regular files Nonblocking and thread aware Thread aware in PUT Model in PUT Model library for library (functions not related to non-regular files file I/O) accept() — yes — alarm() — — yes close() yes yes — connect() — yes — dup2() — yes — fcntl() yes yes — fork() — — yes fstat() yes — — fstat64() yes — — fsync() yes —
Table 69 System and Equivalent Thread-Aware Functions (continued) Standard (Process-Blocking) OSS Functions Nonblocking and thread aware in PUT Model library for regular files Nonblocking and thread aware Thread aware in PUT Model in PUT Model library for library (functions not related to non-regular files file I/O) write() yes yes — writev() — — yes The Set of Thread-Aware I/O Functions Must Be Used Together The PUT Model library serializes I/O functions on open files only for the thread-aware r
Example 91 File Descriptor Thread-Aware Function Usage ... filedes = open(path, oflag, mode | O_NONBLOCK); ... // Call thread-aware functions. ... close(filedes); ... Example 92 (page 400) shows preparing an open file descriptor for use with a thread-aware function. It is not necessary to set the O_NONBLOCK flag. Example 92 Open File Descriptor Thread-Aware Function Usage ... fcntl(filedes, F_SETFL, fcntl(fd, F_GETFL) | O_NONBLOCK); ... // Call thread-aware functions. ...
Example 93 Pthreads Thread-Aware Disk File I/O Using PUT Model Library /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ sptdio.c - Pthreads thread-aware Diskfile IO Example Program This Pthreads program demonstrates a multithreaded program that can perform I/O on multiple OSS regular files (diskfiles) using thread-aware OSS I/O functions Note that OSS I/O on regular files is serialized.
/* size of files that are written - 1Mb */ #define WRITE_FILESIZE 1048576 /* ----------------------------------------------------------------* OSS_read_thread -* * Description: * * This thread reads an OSS file using OSS I/O. Because this program * uses the define _PUT_MODEL>, the read() function is * mapped to the thread—aware read() function, which blocks * the thread instead of the entire process. * Other threads are free to do * work while this thread is blocked waiting for an I/O completion.
/************************************************************************/ /* NOTE that this code does not execute for regular (disk) files, */ /* because read() on a regular file never returns EWOULDBLOCK or EAGAIN */ /************************************************************************/ ret = put_fd_read_ready(fd, NULL); if (ret != 0) { my_printf("*** ERROR in OSS_read_thread: put_fd_read_ready() \ failed w/err %d\n",ret); exit(0); } } else { my_printf("*** ERROR in OSS_read_thread: \ %d ***\n",errno)
my_printf("*** ERROR in OSS_write_thread: allocate I/O buffer \ ***\n"); exit(0); unable to } memset(iobuf, 0, IOSIZE); /*********************/ /* open the OSS file */ /*********************/ if ((fd = open(OSS_write_file, O_WRONLY | O_NONBLOCK | O_CREAT | O_TRUNC, S_IRWXU)) < 0) { my_printf("*** ERROR in OSS_write_thread: open() of %s failed w/error \ %d ***\n", OSS_write_file, errno); exit(0); } /***********************************************/ /* write the OSS file in a thread-aware manner */ /********
int main(int argc, char *argv[]) { /* the following variables correspond to the OSS filenames /* specified as command line parameters to the program char OSS_read_filename[PATH_MAX]; char OSS_write_filename[PATH_MAX]; /* total number of threads that have been created */ int nmbr_created_threads = 0; /* array of handles for each thread created */ pthread_t thread_handle[MAX_THREADS]; int i; */ */ /*************************************/ /* Process command line arguments */ /*********************************
/***************************************************/ /* wait for the threads to complete */ /* this is where control is passed to the threads */ /* to the threads */ /***************************************************/ for (i = 0; i < nmbr_created_threads; ++i) { pthread_join(thread_handle[i], NULL); } } /* main() */ Threads Portability The PUT Model library follows the POSIX Threads Standard document.
fopen64_guardian() fopen64_std_file() freopen_guardian() freopen64_guardian() lgamma() localeconv() localtime() lrand48() wcstombs() wctomb() Cancellation Points These functions contain a cancellation point: accept() close() connect() creat() creat64() fcntl() (with F_SETLK as cmd) fsync() msgrcv() msgsnd() open() open64() pause() read() readv() recv() recvfrom() recvmsg() select() send() sendmsg() sendto() sigsuspend() sigwait() sleep() system() usleep() wait() waitpid() write() writev() Potential Canc
dlopen() endhostent() endnetent() endprotoent() endservent() fclose() fcntl() fflush() fgetc() fgetpos() fgetpos64() fgets() fgetwc() fgetws() fopen() fopen_oss() fopen64() fopen64_oss() fmtmsg() fprintf() fputc() fputs() fputwc() fputws() fread() freehostent() freopen() freopen_oss() freopen64() freopen64_oss() fscanf() fseek() fseeko() fseeko64() fsetpos() fsetpos64() ftell() ftello() ftello64() ftw() ftw64() fwprintf() fwrite() gethostent() putchar() gethostent_r() putchar_unlocked() getipnodebyaddr() p
Reentrant functions include the _r suffix in their names. To determine if a function is reentrant, see the reference page for that function either online or in the Open System Services System Calls Reference Manual. Many functions are unsafe in multithreaded applications, often because these functions return a pointer to a string or structure that is in static storage. A second call to the function overwrites the static storage (the results from the first call).
Example 94 Using the Reentrant Function strtok_r /* reent.c - Using the reentrant function strtok_r * * Compilation steps: * * /usr/bin/c89 -Wextensions -Wsystype=oss -c reent.c -o reent.o * /usr/bin/nld /usr/lib/crtlmain.o reent.o ./libspt.a -obey \ * /usr/lib/libc.obey -lzcredll -o reent */ #define _PUT_MODEL_ #include #include #include #include #include #include “myio.
Thread-Aware Toolkit Functions and Types Functions written using the thread-aware toolkit (Table 70) allow one or more threads to perform work on one or more files without any one thread unnecessarily blocking another thread. To enable these functions, you must include the pthread.h header file. You can use these functions with the thread-aware functions in the PUT Model library. For details on each function, see the appropriate reference page in the Open System Services System Calls Reference Manual.
Example 95 (page 412) uses the default callback mechanism by registering the file number via put_regFile(2). In some cases, you may wish to provide your own callback using put_regFileIOHandler(2), which registers the file number as one you will manage through the callback you define. Example 95 Thread-Aware Toolkit Program Flow ... FILE_OPEN(…, &filenum, …); put_regFile(filenum); ... // Do work on filenum. ... put_unregFile(filenum); FILE_CLOSE(filenum); ...
Example 97 Nonblocking Thread-Aware read() Function /* /* /* /* /* /* /* /* /* This program fragment assumes that you are using the PUT Model library. For regular files, the read() function is thread-aware unless you have set the PUT_THREAD_AWARE_REGULAR_IO_DISABLE environment variable. For non-regular files, the read() function can be thread aware or thread aware nonblocking.
Example 98 Example READX() Function Used In Thread-Aware Manner { put_error_t spte; long error; _cc_status cc; long tag; tag = put_generateTag(); cc = READX(filenum, buffer, read_count, , tag); /* If READX() failed. */ if (_status_lt(cc)) { short short_error; (void) FILE_GETINFO_(filenum, &short_error); return short_error; } /* Loop forever. */ while (1) { spte = put_awaitio(filenum, tag, timelimit, count_read, &error, NULL); /* If spte is put_INTERRUPTED then try again.
The functions listed above provide only basic $RECEIVE handling support, not higher-level capabilities associated with a $RECEIVE package. You can build such higher-level functions using the primitives present in the thread-aware $RECEIVE functions, but must tailor them for whatever domain-specific application they occur in.
Example 100 Function with put_RECEIVEREAD() and put_REPLYX() ... while (1) { if (put_RECEIVEREAD(…) != 0) break; ... // Do work. ... if (put_REPLYX(…) != 0) break; } ... Example 101 shows a single thread calling the thread-aware put_RECEIVEREAD() function. Using thread-aware $RECEIVE functions allows one or more threads to perform work on $RECEIVE, without a thread unnecessarily blocking another thread.
Example 101 $RECEIVE Server #define _PUT_MODEL_ #include #include #include #include #include #include #include “myio.
if (pthread_join(thread1, NULL) != 0) { perror("main: pthread_join"); exit(1); } if (pthread_join(thread2, NULL) != 0) { perror("main: pthread_join"); exit(1); } } Caveats to Using Thread-Aware $RECEIVE Proper operation of thread-aware $RECEIVE depends on the following conditions: • No calls to AWAITIO[X] () with a file number of -1 are made. • No calls to AWAITIO[X] () with a file number for $RECEIVE are made. • No calls to FILE_COMPLETE_SET_ () are made.
SERVERCLASS_DIALOG Jacket Routines The Pathsend SERVERCLASS_DIALOG jacket routines are used to: • Establish a dialog with a server instance in a Pathway server class • Send and receive messages within the dialog • Abort or end the dialog The Context-Sensitive Pathway requester can be written using the thread-aware SERVERCLASS_DIALOG jacket routines to communicate with a server instance in the Pathway server class.
• If a thread terminates or is destroyed while it has an active transaction, that transaction is then inaccessible from the process. If cancellation is a possibility, use exception handlers for pthread_cancel_e. Alternatively, use the pthread_cleanup_push() and pthread_cleanup_pop() functions to ensure that the transaction is terminated if the thread exits or is cancelled.
Table 72 Thread-Aware Enscribe Functions (continued) Function PUT_FILE_WRITEREAD_ Description 1 Writes data to a process previously opened from an array and waits for data to be transferred back from the process PUT_READX Returns data from an open file to the application process data area PUT_READUPDATEX Reads data from a disk or process file in anticipation of a subsequent write to the file PUT_READLOCKX Sequentially locks and reads records in a disk file PUT_READUPDATELOCKX Locks, then reads the
Example 102 Using the Thread-Aware PUT_FILE_OPEN Function /* Using the thread-aware PUT_FILE_OPEN function */ #define _PUT_MODEL_ #include #include #include #include #include #include #include “myio.h” /* contains my_printf which is process blocking */ short filenum; void *Thread2(void *args) { my_printf("Hello, I am Thread2\n"); } void *Thread1(void *args) { short error; char *name = "$SYSTEM.TEST.
Table 73 Thread-Aware Callback Functions and Types Function Description put_OSSFileIOHandler_p Callback type required by put_regOSSFileIOHandler(). put_regOSSFileIOHandler Register the file descriptor as one that the user will manage through a user supplied callback. put_unregOSSFileIOHandler Unregister file descriptor as one that the user will manage. put_setOSSFileIOHandler Set interest in file descriptor. put_regTimerHandler Register a user supplied timer callback.
Build Scripts Build scripts used to compile application modules must define macro _PUT_MODEL_. This macro determines which definitions are obtained from various header files such as sys/types.h and stdio.h. The build scripts must not define macro _SPT_MODEL_. The build scripts must also specify linking the PUT Model library (for example, the c89 –lput option) and must not specify linking the SPT library (for example, dot use the –lspt option).
The put/put_types.h header file includes PUT Model library versions of the nonstandard definitions that applications that use the SPT library obtained from spt_types.h, with this difference: • The spt_types.h header file defines type timespec_t that refers to a nonstandard struct timespec data item whose first field has type unsigned long. The put/put_types.h header file does not define this type. Instead, the standard header file time.
function name, such as read() and you must include the appropriate standard header file. For more information about these functions, see “Thread-Aware and Nonblocking OSS Functions” (page 396). Nonstandard spt_* Functions Have put_* Equivalents The SPT library provides some non-standard spt_*() and SPT_functions, such as spt_select_single_np() and SPT_INITRECEIVE(). The PUT Model library provide analogs to these functions that you can call directly.
Different Behavior for C Language I/O Functions The SPT library intercepts calls to C language I/O functions (such as fgetc(), fprintf(), and so forth) made by SPT application modules and, because it processes certain outcomes internally, never reports that an operation failed because of a situation in which errno would be set to EWOULDBLOCK (or to values describing a few other similar situations).
to handle signals, converting it to an application that uses the PUT Model library might require additional logic to handle thread-specific signals. Use of Process Resources There are many differences in the internal logic of the public libraries that provide run-time services. The resultant different (potentially dramatically different) patterns of usage of process resources can have an impact ranging from minor to severe.
Jacket Routines for Functions Related to Pathway or TMF The PUT Model library does provide jacket routines for calls to Pathway servers (SERVERCLASS_SEND and SERVERCLASS_SEND_INFO) and for TMF transactions, as described in “Jacket Routines (Nonblocking Versions of SERVERCLASS_ and TMF System Calls)” (page 418).
Making Process-Blocking Calls When a thread calls a Guardian procedure that blocks the process, all other threads in the process are also prevented from executing. If a thread is blocked for a significant period of time, it can delay or even prevent the execution of time-critical run-time functions.
Single Versus Multiple Application Threads OSS threaded applications can be classified as follows, in order of increasing complexity: • “Programs With a Single Application Thread” (page 431) • “Programs With Multiple Independent Application Threads” (page 432) • “Programs With Multiple Interdependent Application Threads” (page 432) Programs With a Single Application Thread Externally, programs with a single application thread behave like standard, sequential (nonthreaded) programs.
Programs With Multiple Independent Application Threads Programs containing multiple threads can improve performance by providing concurrent execution. An application thread is independent if it does not explicitly share application resources that exist in the process environment, such as application file opens, SQL cursors, or modifiable application data structures. This type of application includes simple OSS servers that maintain the application state in a database.
Example 105 Threaded Time-of-Day Server Socket /* Threaded time-of day server socket. */ /* If compiled for TNS/E, specify the ZPUTDLL, */ /* the standard POSIX threads shared run-time library. */ #define _PUT_MODEL_ #define _XOPEN_SOURCE_EXTENDED 1 #include #include #include #include #include #include #include #include #include
/* Defines one pthread_t per request we intend to handle: */ pthread_t my_thread; pthread_attr_t my_attr; /* Turns on concurrency: */ if(pthread_setconcurrency(1)) { perror("pthread_setconcurrency"); exit(-1); } /* Initializes attribute: */ if(pthread_attr_init(&my_attr)) { perror("pthread_attr_init"); exit(-1); } /* Sets detach Attribute: */ if(pthread_attr_setdetachstate(&my_attr,PTHREAD_CREATE_DETACHED)) { perror("pthread_attr_setdetachstate"); exit(-1); } /* Creates socket: */ if ((sock = socket(AF_INET
/* Sets socket to listen: */ if (listen(sock, 1) < 0) { perror("Listen Error"); exit(-1); } /* Starts server: */ while(1) { bzero(&accept_addr, sizeof(accept_addr)); accept_fd = accept(sock, NULL, NULL); if (accept_fd < 0) { perror("Accept Error"); exit(-1); } /* Dispatches a thread to handle service request: */ if(pthread_create(&my_thread,&my_attr,&worker_thread,&accept_fd)) { perror("pthread_create"); exit(-1); } } /* while */ }/* main */ Example 106 (page 436) also creates a threaded time-of-day server
Example 106 Threaded Time-of-Day Server Socket Using $RECEIVE #define _PUT_MODEL_ #include #include #include #include #include #include #include #include “myio.h” /** contains my_printf which is process-blocking**/ /* Must come after cextdecs.h: */ #include
/* Sets detach state for thread attribute: */ if(pthread_attr_setdetachstate(&my_attr,PTHREAD_CREATE_DETACHED)!=0) { perror("pthread_attr_setdetachstate"); exit(-1); } error = FILE_OPEN_(filename, (short)strlen(filename), &filenum, 0, , 1, 10, 1); my_fprintf(stderr,"main: FILE_OPEN_: error: %d\n",error); assert(error == 0); error = put_INITRECEIVE(filenum, 10); my_fprintf(stderr,"main: put_INITRECEIVE: error: %d\n",error); fflush(stderr); assert(error == 0); while (1) { error = put_RECEIVEREAD(filenum, buff
A Documented OSS Functions This appendix lists the following information for each OSS function. Function The name of the OSS function. Reference Where the function is documented: HP Native Only RVU Notes Library The hard-copy reference page for the function is in the Open System Services Library Calls Reference Manual. System The hard-copy reference page for the function is in the Open System Services System Calls Reference Manual.
Function Reference HP Native Only acosh() Library Yes TNS/R, TNS/E acoshf() Library TNS/E H06.21, J06.10 acoshl() Library TNS/E H06.21, J06.10 acosl() Library TNS/E H06.21, J06.10 advance() Library TNS/R, TNS/E alarm() Library Yes _alloca() Library Yes TNS/E H06.22, J06.11 asctime() Library asctime_r() Library Yes TNS/R, TNS/E G06.28, H06.05, J06.03 asin() Library asinf() Library TNS/E H06.21, J06.10 asinh() Library asinhf() Library TNS/E H06.21, J06.
Function Reference bzero() Library TNS/R, TNS/E cabs() Library TNS/E H06.21, J06.10 cabsf() Library TNS/E H06.21, J06.10 cabsl() Library TNS/E H06.21, J06.10 cacos() Library TNS/E H06.21, J06.10 cacosf() Library TNS/E H06.21, J06.10 cacosh() Library TNS/E H06.21, J06.10 cacoshf() Library TNS/E H06.21, J06.10 cacoshl() Library TNS/E H06.21, J06.10 cacosl() Library TNS/E H06.21, J06.10 ca11oc() Library Yes ca11oc32() Library Yes TNS/E H06.24, J06.
Function Reference ccoshl() HP Native Only RVU Notes Library TNS/E H06.21, J06.10 ccosl() Library TNS/E H06.21, J06.10 ceil() Library ceilf() Library TNS/E H06.21, J06.10 ceill() Library TNS/E H06.21, J06.10 cexp() Library TNS/E H06.21, J06.10 cexpf() Library TNS/E H06.21, J06.10 cexpl() Library TNS/E H06.21, J06.
Function Reference cos() Library cosf() Library cosh() Library coshf() Native Only RVU Notes TNS/E H06.21, J06.10 Library TNS/E H06.21, J06.10 coshl() Library TNS/E H06.21, J06.10 cosl() Library TNS/E H06.21, J06.10 cpow() Library TNS/E H06.21, J06.10 cpowf() Library TNS/E H06.21, J06.10 cpowl() Library TNS/E H06.21, J06.10 cproj() Library TNS/E H06.21, J06.10 cprojf() Library TNS/E H06.21, J06.10 cprojl() Library TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes ctime_r() Library Yes TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference erfcf() Native Only RVU Notes Library TNS/E H06.21, J06.10 erfcl() Library TNS/E H06.21, J06.10 erff() Library TNS/E H06.21, J06.10 erfl() Library TNS/E H06.21, J06.10 exec() System execl() System Extended execle() System Extended execlp() System Extended execv() System Extended execve() System Extended execvp() System Extended _exit() System Yes _Exit() Library TNS/E H06.08, J06.
Function Reference fegetenv() HP Native Only RVU Notes Library TNS/E H06.21, J06.10 fegetexceptflag() Library TNS/E H06.21, J06.10 fegetround() Library TNS/E H06.21, J06.10 feholdexcept() Library TNS/E H06.21, J06.10 feof() Library feraiseexcept() Library TNS/E H06.21, J06.10 ferror() Library fesetenv() Library TNS/E H06.21, J06.10 fesetexceptflag() Library TNS/E H06.21, J06.10 fesetround() Library TNS/E H06.21, J06.10 fetestexcept() Library TNS/E H06.21, J06.
Function Reference fmodf() Native Only RVU Notes Library TNS/E H06.21, J06.10 fmodl() Library TNS/E H06.21, J06.10 fmtmsg() Library TNS/R, TNS/E fnmatch() Library fopen() Library fopen_guardian() Library Yes fopen_oss() Library Yes fopen_std_file() Library Yes fopen64() Library Yes G06.29, H06.06, J06.03 fopen64_guardian() Library Yes G06.29, H06.06, J06.03 fopen64_oss() Library Yes G06.29, H06.06, J06.03 fopen64_std_file() Library Yes G06.29, H06.06, J06.
Function Reference frexpf() HP Native Only RVU Notes Library TNS/E H06.21, J06.10 frexpl() Library TNS/E H06.21, J06.10 fscanf() Library Yes fseek() Library Yes fseeko() Library Yes G06.29, H06.06, J06.03 fseeko64() Library Yes G06.29, H06.06, J06.03 fsetpos() Library fsetpos64() Library Yes G06.29, H06.06, J06.
Function Reference HP get_assign_msg_by_name() Library Yes get_max_assign_msg_ordinal() Library Yes get_param_by_name() Library Yes get_param_msg() Library Yes get_startup_msg() Library Yes getaddrinfo() Library Yes getc() Library Extended getc_unlocked() Library Extended getchar() Library Extended getchar_unlocked() Library Extended getcwd() Library Extended getdate() Library TNS/R, TNS/E getdtablesize() Library TNS/R, TNS/E getegid() System getenv() Library Ye
Function Reference HP Native Only RVU Notes gethostname() System getipnodebyaddr() Library Yes getipnodebyname() Library Yes getlogin() Library Extended getlogin_r() Library getnameinfo() Library Yes getnetbyaddr() Library Yes TNS/R, TNS/E getnetbyaddr_r() Library Yes TNS/R, TNS/E getnetbyname() Library Yes TNS/R, TNS/E getnetbyname_r() Library Yes TNS/R, TNS/E getnetent() Library Yes TNS/R, TNS/E getnetent_r() Library Yes TNS/R, TNS/E getopt() Library getpages
Function Reference HP Native Only RVU Notes getpwuid_r() Library Extended TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference HP Native Only HBA_GetVersion() Library TNS/E HBA_LoadLibrary() Library TNS/E HBA_OpenAdapter() Library TNS/E HBA_RefreshInformation() Library TNS/E hcreate() Library hdestroy() Library heap_check() Library Yes heap_check32() Library Yes heap_check_always() Library Yes heap_check_always32() Library Yes heap_min_block_size() Library Yes hsearch() Library htonl() Library htons() Library hypot() Library hypotf() RVU Notes TNS/E H06.24, J06.
Function Reference HP Native Only RVU Notes inet_pton() Library Yes initgroups() Library Yes TNS/R, TNS/E H06.18, J06.07 initstate() Library TNS/R, TNS/E insque() Library TNS/R, TNS/E ioctl() System isalnum() Library isalpha() Library isascii() Library isatty() Library isblank() Library iscntrl() Library isdigit() Library isfinite() Library isgraph() Library isgreater() Extended Extended TNS/E H06.08 TNS/E H06.21, J06.10 Library TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes iswprint() Library iswpunct() Library iswspace() Library iswupper() Library iswxdigit() Library isxdigit() Library j0() Library j1() Library jn() Library jrand48() Library kill() System l64a() Library labs() Library lchmod() System Yes G06.28, H06.05, J06.03 lchown() System Extended G06.28, H06.05, J06.03 lcong48() Library ldexp() Library ldexpf() Library TNS/E H06.21, J06.10 ldexpl() Library TNS/E H06.21, J06.
Function Reference localeconv() Library localtime() Library localtime_r() Library log() Library logb() Library Extended TNS/R, TNS/E logbf() Library Extended TNS/E H06.21, J06.10 logbl() Library Extended TNS/E H06.21, J06.10 logf() Library TNS/E H06.21, J06.10 logl() Library TNS/E H06.21, J06.10 log1p() Library log1pf() Library TNS/E H06.21, J06.10 log1pl() Library TNS/E H06.21, J06.10 log2() Library TNS/E H06.21, J06.10 log2f() Library TNS/E H06.21, J06.
Function Reference lwres_gai_strerror() HP Native Only RVU Notes Library TNS/R, TNS/E H06.05, G06.27 lwres_getaddrinfo() Library TNS/R, TNS/E H06.05, G06.27 lwres_gethostbyaddr() Library TNS/R, TNS/E H06.05, G06.27 lwres_gethostbyname() Library TNS/R, TNS/E H06.05, G06.27 lwres_gethostbyname2() Library TNS/R, TNS/E H06.05, G06.27 lwres_getipnodebyaddr() Library TNS/R, TNS/E H06.05, G06.27 lwres_getipnodebyname() Library TNS/R, TNS/E H06.05, G06.
Function Reference HP mkdir() System Extended mkfifo() Library Extended mknod() System Extended mkstemp() Library TNS/R, TNS/E mktemp() Library TNS/R, TNS/E mktime() Library modf() Library modff() Library TNS/E H06.21, J06.10 modfl() Library TNS/E H06.21, J06.10 mrand48() Library msgctl() System Extended msgget() System Extended msgrcv() System Extended msgsnd() System Extended Function Reference HP Native Only RVU Notes nan() Library TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes open() System Extended open64() System Yes opendir() Library Extended openlog() Library Extended pathconf() Library Extended pause() Library Extended pclose() Library Extended perror() Library pipe() System Extended popen() Library Extended pow() Library powf() Library TNS/E H06.21, J06.10 powl() Library TNS/E H06.21, J06.
Function Reference HP Native Only pthread_cleanup_push() System Yes TNS/R, TNS/E pthread_cond_broadcast() System Yes TNS/R, TNS/E pthread_cond_destroy() System Yes TNS/R, TNS/E pthread_cond_init() System Yes TNS/R, TNS/E pthread_cond_signal() System Yes TNS/R, TNS/E pthread_cond_signal_int_np() System Yes TNS/R, TNS/E pthread_cond_timedwait() System Yes TNS/R, TNS/E pthread_cond_wait() System Yes TNS/R, TNS/E pthread_condattr_destroy() System Yes TNS/R, TNS/E pthread_
Function Reference HP Native Only RVU Notes pthread_mutexattr_settype() System TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes put_RECEIVEREADL() System Yes TNS/E H06.21, J06.10 put_regFile() System Yes TNS/E H06.21, J06.10 put_regFileIOHandler() System Yes TNS/E H06.21, J06.10 put_regOSSFileIOHandler() System Yes TNS/E H06.21, J06.10 put_regPathsendFile() System Yes TNS/E H06.21, J06.10 put_regPathsendTagHandler() System Yes TNS/E H06.21, J06.10 put_regTimerHandler() System Yes TNS/E H06.21, J06.10 put_REPLYX() System Yes TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes PUT_WRITEUPDATEX() System Yes TNS/E H06.21, J06.10 PUT_WRITEX() System Yes TNS/E H06.21, J06.10 putc() Library Extended putc_unlocked() Library Extended TNS/E H06.21, J06.10 putchar() Library Extended putchar_unlocked() Library Extended TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes recvmsg64_() System Yes TNS/E H06.24, J06.13 regcmp() Library regcomp() Library regerror() Library regex() Library regexec() Library regfree() Library remainder() Library Extended TNS/R, TNS/E remainderf() Library TNS/E H06.21, J06.10 remainderl() Library TNS/E H06.21, J06.10 remove() Library remove_guardian() Library Yes remove_oss() Library Yes remque() Library TNS/R, TNS/E remquo() Library TNS/E H06.21, J06.
Function Reference HP Native Only RVU Notes scandir() Library Yes G06.29, H06.06, J06.03 scandir64() Library Yes G06.29, H06.06, J06.
Function Reference HP Native Only RVU Notes setpwent() Library Extended setregid() System Yes G06.27, H06.05, J06.03 setreuid() System Yes G06.27, H06.05, J06.
Function Reference HP Native Only RVU Notes sockatmark() System Yes socket() System Extended socket_transport_name_get() System Yes socket_transport_name_set() System Yes socketpair() System Extended snprintf() Library Yes sprintf() Library Yes SPT_ABORTTRANSACTION() Library Yes TNS/R, TNS/E spt_accept() System Yes TNS/R, TNS/E spt_acceptx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_alarm() System Yes TNS/R, TNS/E G06.29, H06.06, J06.
Function Reference HP Native Only RVU Notes spt_fgetcx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_fgets() System Yes TNS/R, TNS/E spt_fgetsx() System Yes TNS/R, TNS/E spt_fgetwc() System Yes TNS/R, TNS/E spt_fgetwcx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 SPT_FILE_CLOSE_() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 SPT_FILE_OPEN_() System Yes TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference HP Native Only RVU Notes spt_gets() System Yes TNS/R, TNS/E spt_getsx() System Yes TNS/R, TNS/E spt_getTMFConcurrentTransactions() System Yes TNS/R, TNS/E spt_getw() System Yes TNS/R, TNS/E spt_getwc() System Yes TNS/R, TNS/E spt_getwchar() System Yes TNS/R, TNS/E spt_getwcharx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_getwcx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_getwx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference HP Native Only RVU Notes spt_putwcharx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_putwcx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_putwx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_read() System Yes TNS/R, TNS/E SPT_READLOCKX() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 SPT_READUPDATELOCKX() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 SPT_READUPDATEX() System Yes TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference HP Native Only RVU Notes spt_select() System Yes TNS/R, TNS/E spt_select_single_np() System Yes TNS/R, TNS/E spt_send() System Yes TNS/R, TNS/E spt_sendmsg() System Yes TNS/R, TNS/E spt_sendmsgx() System Yes TNS/R, TNS/E spt_sendto() System Yes TNS/R, TNS/E spt_sendtox() System Yes TNS/R, TNS/E G06.28, H06.05, J06.03 spt_sendx() System Yes TNS/R, TNS/E G06.28, H06.05, J06.
Function Reference HP Native Only SPT_TMF_SetTxHandle() System Yes TNS/R, TNS/E SPT_TMF_SUSPEND() System Yes TNS/R, TNS/E SPT_UNLOCKFILE() System Yes TNS/R, TNS/E G06.28, H06.04, J06.03 SPT_UNLOCKREC() System Yes TNS/R, TNS/E G06.28, H06.04, J06.
Function Reference HP Native Only stat() System Yes stat64() System Yes statvfs() System Yes statvfs64() System Yes step() Library TNS/R, TNS/E strcasecmp() Library TNS/R, TNS/E strcat() Library strcat64() Library strchr() Library strchr64() Library strcmp() Library strcmp64() Library strcoll() Library strcpy() Library strcpy64() Library strcspn() Library strdup() Library strerror() Library strerror_r() Library strfmon() Library strftime() Library strlen()
Function Reference HP Native Only RVU Notes strstr64() Library Yes TNS/E H06.24, J06.13 strtod() Library strtof() Library TNS/E H06.08, J06.03 strtoimax() Library TNS/E H06.08, J06.03 strtok() Library strtok_r() Library TNS/R, TNS/E G06.28, H06.05, J06.03 strtol() Library strtoll() Library strtoul() Library strtoull() Library strtoumax() Library TNS/E H06.08, J06.03 strxfrm() Library swab() Library swprintf() Library TNS/E H06.08, J06.
Function Reference HP Native Only RVU Notes tdm_fork() System Yes tdm_spawn() System Extended tdm_spawnp() System Extended telldir() Library tempnam() Library terminate_program() Library tfind() Library tgamma() Library TNS/E H06.21, J06.10 tgammaf() Library TNS/E H06.21, J06.10 tgammal() Library TNS/E H06.21, J06.10 time() Library times() Library tmpfile() Library tmpfile_guardian() Library Yes tmpfile_oss() Library Yes tmpfile64() Library Yes G06.29, H06.
Function Reference HP Native Only RVU Notes ttyname_r() Library Extended TNS/R, TNS/E G06.28, H06.05, J06.03 twalk() Library tzset() Library ulimit() System umask() System uname() System ungetc() Library ungetwc() Library unlink() System Extended unordered() Library Yes usleep() Library utime() System va_arg() Library va_end() Library va_start() Library valloc() Library vfprintf() Library vfscanf() Library vfwprintf() Library TNS/E H06.08, J06.
Function Reference wcscoll() Library wcscpy() Library wcscspn() Library wcsftime() Library wcslen() Library wcsncat() Library wcsncmp() Library wcsncpy() Library wcspbrk() Library wcsrchr() Library wcsrtombs() Library wcsspn() Library wcstod() Library wcstof() HP Native Only RVU Notes TNS/E H06.08, J06.03 Library TNS/E H06.08, J06.03 wcstoimax() Library TNS/E H06.08, J06.
Function Reference wprintf() Library write() System Extended write64_() Library Yes writev() System Extended wscanf() Library y0() Library y1() Library yn() Library Documented OSS Functions HP Native Only RVU Notes TNS/E H06.08, J06.03 TNS/E H06.24, J06.13 TNS/E H06.08, J06.
B API Interoperability in TNS Processes This appendix contains Table 77 (page 482), which describes the interoperability between the Guardian API and the Open System Services (OSS) API in TNS processes. This appendix applies only to G-series systems: the J-series and H-series OSS environments do not support TNS processes. Table 77 lists the functions and macros in the Guardian C Run-Time Library and the OSS API. Functions in the Guardian sockets library and Guardian system procedures are not included.
Function and Macro Behavior A function or macro that can be called in both the Guardian and OSS environments might or might not behave in the same way in each environment. Behavior can be classified into three categories: • Identical behavior Many of the functions and macros behave the same way in each environment because they take environment-independent parameters. For example, string functions such as strcat() are identical in the Guardian and OSS environments.
• Types of parameters (OSS or Guardian) the function or macro requires. • Types of objects (OSS or Guardian) the function or macro operates on. G and O Notation In the columns headed “Module Compiled As,” and “Process Called From,” the letter “G” indicates “Guardian” and “O” indicates “OSS.” Specified By The “Specified By” column indicates where a function or macro is defined: ISO The function or macro is specified in the ISO/ANSI C standard. POSIX The function or macro is specified in the POSIX.
The following table describes the “Usage Notes” values that appear frequently. Usage Note Meaning Checking variants If the CHECK pragma is specified, functions and macros in both Guardian and OSS modules perform identical parameter validation. If the NOCHECK pragma is specified, functions and macros in both Guardian and OSS modules do not perform extra parameter validation. The Guardian environment compiler defaults to CHECK. The OSS environment compiler defaults to NOCHECK.
1. The following information can be derived about the acos() function: • Specified in the ISO/ANSI C standard. • Can be called from Guardian and OSS modules. • Can be called from Guardian and OSS processes. • 2. 3. 4. When called from a Guardian module, it causes an exception on arithmetic overflow; when called from an OSS module, it does not. The following information can be derived about the edlseek() function: • Is an extension specified by HP. • Can be called only from Guardian modules.
Table 77 API Interoperability in TNS Processes Function or Macro Specified By Module Process Compiled Called As From __ns_backup_fopen() HP G G __ns_fget_file_open_state() HP G G __ns_fget_file_state() HP G G __ns_fopen_special() HP G G __ns_fset_file_state() HP G G __ns_start_backup() HP G G _abs() HP G, O G, O _exit() X/OPEN G, O G, O _is_system_trap() HP G G _max() HP G, O G, O _min() HP G, O G, O _tolower() XPG4 G, O G, O _toupper() XPG4 G, O G, O ab
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes cfgetispeed() POSIX O O cfgetospeed() POSIX O O cfsetispeed() POSIX O O cfsetospeed() POSIX O O chdir() POSIX G, O G, O OSS parameters only OSS objects and limited Guardian objects chmod() POSIX G, O G, O OSS objects only chown() POSIX G, O G, O OSS objects and limited Guardian objects chroot() XPG4 G, O G, O chvol() HP G G cl
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes dup() POSIX O G, O OSS parameters only OSS objects and limited Guardian objects dup2() POSIX O G, O OSS parameters only OSS objects and limited Guardian objects ecvt() HP G, O G, O edfseek() HP G G, O Guardian parameters only Guardian objects only edftell() HP G G, O Guardian parameters only Guardian objects only edlseek() HP G G, O Guar
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes OSS function operates on OSS objects and limited Guardian objects fdtogfn() HP G G, O Guardian parameters only Guardian objects only feof() ISO G, O G, O Parameters must match module Guardian function operates only on Guardian objects OSS function operates on OSS objects and limited Guardian objects ferror() ISO G, O G, O Parameters must match module
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes OSS function operates on OSS objects and limited Guardian objects fopen_guardian() HP G, O G, O Guardian parameters only Guardian objects only fopen_oss() HP G, O G, O OSS parameters only OSS objects and limited Guardian objects fopen_std_file() HP G G fork() POSIX O O OSS objects only fpathconf() POSIX G, O G, O OSS parameters only fprintf(
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes Guardian function operates only on Guardian objects OSS function operates on OSS objects and limited Guardian objects fseek() ISO G, O G, O Parameters must match module Guardian function operates only on Guardian objects OSS function operates on OSS objects and limited Guardian objects fsetpos() ISO G, O G, O Parameters must match module Guardian function
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes OSS function operates on OSS objects and limited Guardian objects getchar() ISO G, O G, O getcwd() POSIX G, O G, O getegid() POSIX G, O G, O getenv() ISO G, O G, O geteuid() POSIX G, O G, O getgid() POSIX G, O G, O getgrgid() POSIX O O Data can be overwritten by subsequent call or call to getgrnam() getgrnam() POSIX O O Data can be
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From globfree() POSIX G, O G, O gmtime() ISO G, O G, O hcreate() XPG4 G, O G, O hdestroy() XPG4 G, O G, O heap_check() HP G, O G, O heap_check_always() HP G, O G, O heap_min_block_size() HP G, O G, O hsearch() XPG4 G, O G, O hypot() XPG4 G, O G, O iconv() XPG4 O O iconv_close() XPG4 O O iconv_open() XPG4 O O ioctl() X/OPEN G, O G, O
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From iswprint() XPG4 G, O G, O iswpunct() XPG4 G, O G, O iswspace() XPG4 G, O G, O iswupper() XPG4 G, O G, O iswxdigit() XPG4 G, O G, O isxdigit() XPG4 G, O G, O j0() XPG4 G, O G, O j1() XPG4 G, O G, O jn() XPG4 G, O G, O jrand48() XPG4 G, O G, O kill() POSIX O O labs() ISO G, O G, O lcong48() XPG4 G, O G, O ldexp() ISO G, O G,
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes mbtowc() ISO G, O G, O memccpy() ISO O G, O memchr() ISO G, O G, O Checking variants memcmp() ISO G, O G, O Checking variants memcpy() ISO G, O G, O Checking variants memmove() ISO G, O G, O Checking variants memset() ISO G, O G, O Checking variants memswap() HP G, O G, O Checking variants mkdir() POSIX G, O G, O OSS parame
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From perror() ISO G, O G, O pipe() POSIX O G, O OSS parameters only popen() POSIX G, O G, O OSS parameters only pow() ISO G, O G, O Exception variants printf() ISO G, O G, O Only Guardian modules or only OSS modules putc() ISO G, O G, O Parameters must match module putchar() ISO G, O G, O Only Guardian modules or only OSS modules Guardian function op
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes regexec() XPG4 O O regfree() XPG4 O O remove() ISO G, O G, O Parameters must match module remove_guardian() HP G, O G, O Guardian parameters only remove_oss() HP G, O G, O OSS parameters only rename() ISO G, O G, O Parameters must match module Guardian function operates only on Guardian objects OSS function operates on OSS objects and lim
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes setnbuf() HP G, O G, O Parameters must match module setpgid() POSIX G, O O OSS objects only setpgrp() POSIX O O OSS objects only setpwent() X/OPEN O O _XOPEN_SOURCE_EXTENDED or _TANDEM_SOURCE setregid() XPG4 O O OSS objects only setreuid() XPG4 O O OSS objects only setsid() POSIX O O OSS objects only setuid() POSIX G, O G, O s
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes srand48() XPG4 G, O G, O sscanf() ISO G, O G, O stat() POSIX O G, O OSS parameters only OSS objects and limited Guardian objects stcarg() HP G, O G, O Checking variants stccpy() HP G, O G, O Checking variants stcd_i() HP G, O G, O Checking variants stcd_l() HP G, O G, O Checking variants stch_i() HP G, O G, O Checking variants
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes strpbrk() ISO G, O G, O Checking variants strptime() XPG4 G, O G, O strrchr() ISO G, O G, O Checking variants strspn() ISO G, O G, O Checking variants strstr() ISO G, O G, O Checking variants strtod() ISO G, O G, O Checking variants strtok() ISO G, O G, O Checking variants strtol() ISO G, O G, O Checking variants strtoll() IS
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes telldir() XPG4 G, O G, O OSS parameters only OSS objects and limited Guardian objects tempnam() XPG4 G, O O terminate_program() HP G, O G, O tfind() XPG4 G, O G, O time() ISO G, O G, O times() POSIX G, O G, O tmpfile() ISO G, O G, O Parameters must match module tmpfile_guardian() HP G, O G, O Guardian parameters only tmpfile_oss()
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From va_end() ISO G, O G, O va_start() ISO G, O G, O vfprintf() ISO G, O G, O vfscanf() ISO G, O G, O vprintf() ISO G, O G, O vscanf() ISO G, O G, O vsnprintf() ISO G,O G,O vsprintf() ISO G, O G, O vsscanf() ISO G, O G, O wait() POSIX O O OSS objects only waitpid() POSIX O O OSS objects only wcscat() XPG4 G, O G, O wcschr() XPG4 G,
Table 77 API Interoperability in TNS Processes (continued) Function or Macro Specified By Module Process Compiled Called As From Usage Notes wcsxfrm() XPG4 G, O G, O wctomb() XPG4 G, O G, O wctype() XPG4 G, O G, O wcwidth() XPG4 G, O G, O wmemchr() ISO G, O G, O Checking variants wmemcmp() ISO G, O G, O Checking variants wmemcpy() ISO G, O G, O Checking variants wmemmove() ISO G, O G, O Checking variants wmemset() ISO G, O G, O Checking variants wordexp() POSIX
C API Interoperability in Native Processes This appendix contains the API Interoperability tables, which describe the interoperability between the Guardian API and the OSS API in TNS/R and TNS/E native processes. These tables list the functions and macros in the native C Run-Time Library and the OSS API. Functions in the Guardian sockets library and Guardian system procedures are not included.
modules. See Chapter 1: Overview of the OSS Programming Environment (page 26) for a discussion of when to write mixed-module applications. Environment of the Module The environment of a module is determined by the value of the SYSTYPE compiler pragma, which directs the compiler to generate code appropriate for the specified target execution environment. Environment of the Process The environment of a process is determined by the environment of the module defining the main() function.
OSS objects. Some functions and macros are more limited in their interoperability between environments. For each function or macro listed in the API Interoperability tables, the level of interoperability it provides is indicated by the following information: • Specification or standard where the function or macro is defined. • Whether the function or macro can be called from a Guardian module, an OSS module, a Guardian process, or an OSS process.
By default, functions and macros specified by HP are declared only for Guardian modules. To use such a function or macro in an OSS module (if that is allowed), specify the _TANDEM_SOURCE feature test macro when you compile the module.
Usage Note Meaning be the same. Behavior might be different in each environment. OSS function operates on OSS objects and limited Guardian objects The OSS function or macro operates on OSS objects and some types of Guardian objects. The extent of support for Guardian objects differs for each function or macro. OSS objects and limited Guardian objects The function or macro operates on OSS objects and some types of Guardian objects.
Usage Note Meaning SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK An application call to interface() is automatically mapped to this spt_interfacez() function when you use the #define SPT_THREAD_AWARE_XNONBLOCK feature test macro (for C applications) or the #define SPT_THREAD_AWARE_PRAGMA_XNONBLOCK (for C++ applications) or an equivalent compiler command option to compile the application.
3. The following information can be derived about the rename() function: • Specified in the ISO/ANSI C standard. • Can be called from Guardian and OSS modules. • Can be called from Guardian and OSS processes. • 4. Guardian function operates only on Guardian objects; OSS function operates on OSS objects and limited Guardian objects. The following information can be derived about the rename_oss() function: • Is an extension specified by HP. • Can be called from Guardian or OSS modules.
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes asctime() ISO G, O G, O asctime_r() Threads G, O G, O asin() ISO G, O G, O asinf() ISO G, O G, O asinh() ISO G, O G, O asinhf() ISO G, O G, O asinhl() ISO G, O G, O asinl() ISO G, O G, O assert() ISO G, O G, O atan() ISO G, O G, O atanf() ISO G, O G, O atanh() ISO G, O G, O atanhf() ISO G,
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes cacosh() ISO G, O G, O IEEE_float only cacoshf() ISO G, O G, O IEEE_float only cacoshl() ISO G, O G, O IEEE_float only cacosl() ISO G, O G, O IEEE_float only calloc() ISO G, O G, O calloc32() HP G, O G, O Support for 64-bit OSS callers carg() ISO G, O G, O IEEE_float only cargf() ISO G, O G, O IEEE_fl
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes ceill() ISO G, O G, O cexp() ISO G, O G, O IEEE_float only cexpf() ISO G, O G, O IEEE_float only cexpl() ISO G, O G, O IEEE_float only cfgetispeed() POSIX G, O G, O cfgetospeed() POSIX G, O G, O cfsetispeed() POSIX G, O G, O cfsetospeed() POSIX G, O G, O chdir() POSIX G, O G, O OSS parameters only OS
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) 510 Function or Macro Specified Module By Compiled As Process Called From Usage Notes conjf() ISO G, O G, O IEEE_float only conjl() ISO G, O G, O IEEE_float only connect() XPG4 O O _PUT_MODEL_ _XOPEN_SOURCE_EXTENDED copysign() ISO G, O G, O copysignf() ISO G, O G, O copysignl() ISO G, O G, O cos() ISO G, O G, O cosf() ISO G, O G, O cosh() ISO G, O G, O coshf() ISO G, O G, O
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes csqrt() ISO G, O G, O csqrtf() ISO G, O G, O csqrtl() ISO G, O G, O ctan() ISO G, O G, O IEEE_float only ctanf() ISO G, O G, O IEEE_float only ctanh() ISO G, O G, O IEEE_float only ctanhf() ISO G, O G, O IEEE_float only ctanhl() ISO G, O G, O IEEE_float only ctanl() ISO G, O G, O IEEE_float only c
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes OSS objects and limited Guardian objects 512 dup2() POSIX O O OSS parameters only OSS objects and limited Guardian objects _PUT_MODEL_ ecvt() HP G, O G, O Data can be overwritten by a subsequent call edfseek() HP G G, O Guardian parameters only Guardian objects only edftell() HP G G, O Guardian parameters only Guardia
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes exp() ISO G, O G, O expf() ISO G, O G, O expl() ISO G, O G, O expml() XPG4 G, O G, O expmlf() ISO G, O G, O expmll() ISO G, O G, O exp2() ISO G, O G, O IEEE_float only exp2f() ISO G, O G, O IEEE_float only exp2l() ISO G, O G, O IEEE_float only fabs() ISO G, O G, O fabsf() ISO G, O G, O fabsl(
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) 514 Function or Macro Specified Module By Compiled As Process Called From Usage Notes fetestexcept() ISO G, O G, O IEEE_float only feupdateenv() ISO G, O G, O IEEE_float only fflush() ISO G, O G, O ffs() XPG4 G, O G, O fgetc() ISO G, O G, O fgetpos() ISO G, O G, O fgetpos64() XLFS G, O G, O fgets() ISO G, O G, O fgetwc() XPG4 G, O G, O fgetws() XPG4 G, O G, O fileno() XPG4
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes OSS function operates on OSS objects and limited Guardian objects fopen_guardian() HP G, O G, O Guardian parameters only Guardian objects only fopen_oss() HP G, O G, O OSS parameters only OSS objects and limited Guardian objects fopen_std_file() HP G G fopen64() XLFS G, O G, O Parameters must match process Guardian funct
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) 516 Function or Macro Specified Module By Compiled As Process Called From Usage Notes freopen() ISO G, O G, O Parameters must match process Guardian function operates only on Guardian objects OSS function operates on OSS objects and limited Guardian objects freopen_guardian() HP G, O G, O Guardian parameters only Guardian objects only freopen_oss() HP G, O G, O OSS parameters only OSS objects and limite
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes objects_LARGEFILE64_SOURCE or _FILE_OFFSET_BITS _PUT_MODEL_ fstatvfs() XPG4 O O This function provides compatibility with the System V Interface Definition, Revision 3 fstatvfs64() XLFS O O This function provides compatibility with the System V Interface Definition, Revision 3 _LARGEFILE64_SOURCE or _FILE_OFFSET_BITS fsync() XP
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) 518 Function or Macro Specified Module By Compiled As Process Called From Usage Notes gamma_r() Threads G, O G, O _SPT_MODEL_ gcvt() XPG4 G, O G, O get_assign_msg() HP G G get_assign_msg_by_name() HP G G get_max_assign_msg _ordinal() HP G G get_param_by_name() HP G G get_param_msg() HP G G get_startup_msg() HP G G getaddrinfo() XPG4 O O getc() ISO G, O G, O getc_unlocked() Th
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes getgrnam() POSIX G, O G, O Data is overwritten by subsequent call or call to getgrgid() getgrnam_r() Threads G, O G, O _SPT_MODEL_ getgroups() POSIX O O gethostbyaddr() XPG4 O O gethostbyaddr_r() Threads O O gethostbyname() XPG4 O O gethostbyname_r() Threads O O gethostbyname2() HP O O gethostent() XPG4
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From getprotobynumber() XPG4 O O getprotobynumber_r() HP O O getprotoent() XPG4 O O getprotoent_r() HP O O _SPT_MODEL_ getpwent() X/OPEN G, O G, O _TANDEM_SOURCE _XOPEN_SOURCE_EXTENDED or getpwent_r() HP G, O G, O _SPT_MODEL_ getpwnam() POSIX G, O G, O getpwnam_r() Threads G, O G, O getpwuid() POSIX G, O G, O getpwuid_
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From globfree() POSIX G, O G, O gmtime() ISO G, O G, O gmtime_r() Threads G, O G, O HBA_CloseAdapter() FC-MI O O HBA_FreeLibrary() FC-MI O O HBA_GetAdapterAttributes() FC-MI O O HBA_GetAdapterName() FC-MI O O HBA_GetAdapterPortAttributes() FC-MI O O HBA_GetDiscoveredPortAttributes() FC-MI O O HBA_GetFcpTargetMapping() F
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From if_nameindex() XPG4 O O if_nametoindex() XPG4 O O ilogb() XPG4 G, O G, O ilogbf() ISO G, O G, O ilogbl() ISO G, O G, O imaxabs() ISO G, O G, O imaxdiv() ISO G, O G, O index() XPG4 G, O G, O inet_addr() XPG4 O O inet_lnaof() XPG4 O O inet_makeaddr() XPG4 O O inet_netof() XPG4 O O inet_network() XPG4 O
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes islower() ISO G, O G, O isnan() function ISO G, O G, O Returns a value of 0 (zero) for Tandem floating-point data.
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From ldexpf() ISO G, O G, O ldexpl() ISO G, O G, O ldiv() ISO G, O G, O lfind() XPG4 G, O G, O lgamma() XPG4 G, O G, O lgammaf() ISO G, O G, O lgammal() ISO G, O G, O lgamma_r() Threads G, O G, O _SPT_MODEL_ link() POSIX O G, O OSS parameters only OSS objects only listen() XPG4 O O _XOPEN_SOURCE_EXTENDED llabs()
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes log10f() ISO G, O G, O log10l() ISO G, O G, O longjmp() ISO G, O G, O longlong_to_dec() HP G, O G, O lrand48() XPG4 G, O G, O lrint() ISO G, O G, O IEEE_float only lrintf() ISO G, O G, O IEEE_float only lrintl() ISO G, O G, O IEEE_float only lround() ISO G, O G, O IEEE_float only lroundf() ISO G,
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes malloc32() HP G, O G, O Support for TNS/E 64-bit OSS callers malloc_pages() HP G, O G, O This function can be called by TNS/E native processes only _max() HP G, O G, O mblen() ISO G, O G, O mbrlen() ISO G, O G, O mbrtowc() ISO G, O G, O mbsinit() ISO G, O G, O mbsrtowcs() ISO G, O G, O mbstowcs() ISO G,
Table 78 API Interoperability in Native Processes (Functions a through m) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes mktime() ISO G, O G, O modf() ISO G, O G, O modff() ISO G, O G, O modfl() ISO G, O G, O mrand48() XPG4 G, O G, O msgctl() XPG4 O O OSS objects only msgget() XPG4 O O OSS objects only msgrcv() XPG4 O O OSS objects only msgsnd() XPG4 O O OSS objects only Using the API Interoperability Tables 527
Table 79 API Interoperability in Native Processes (Functions n through z) Function or Macro Specified Module By Compiled As Process Called From Usage Notes nan() ISO G, O G, O IEEE_float only nanf() ISO G, O G, O IEEE_float only nanl() ISO G, O G, O IEEE_float only nearbyint() ISO G, O G, O IEEE_float only nearbyintf() ISO G, O G, O IEEE_float only nearbyintl() ISO G, O G, O IEEE_float only nextafter() XPG4 G, O G, O nextafterf() ISO G, O G, O nextafterl() ISO G,
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes pause() POSIX G, O G, O _PUT_MODEL_ pclose() POSIX O O OSS parameters only perror() ISO G, O G, O pipe() POSIX O G, O OSS parameters only popen() POSIX O O OSS parameters only pow() ISO G, O G, O powf() ISO G, O G, O powl() ISO G, O G, O printf() ISO G, O G, O pthread_atfork() Threads O O OSS ob
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _PUT_MODEL_ or _SPT_MODEL_ pthread_attr_setguardsize() Threads O O OSS objects only _PUT_MODEL_ pthread_attr_setguardsize_ np() Threads O O OSS objects only pthread_attr_setinheritsched() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_attr_setschedparam() Threads O O OSS objects only _PUT_MODEL_ or _SPT
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _SPT_MODEL_ pthread_cond_wait() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_condattr_destroy() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_condattr_init() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_create() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODE
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _SPT_MODEL_ pthread_key_create() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_key_delete() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_kill() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_kill_np() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_l
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _PUT_MODEL_ or _SPT_MODEL_ pthread_self() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_setcancelstate() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_setcanceltype() Threads O O OSS objects only _PUT_MODEL_ or _SPT_MODEL_ pthread_setconcurrency() Threads O O OSS objects only _PUT_MOD
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes PUT_ENDTRANSACTION() HP O O Guardian objects only _PUT_MODEL_ put_fd_read_ready() Threads O O OSS objects only _PUT_MODEL_ put_fd_write_ready() Threads O O OSS objects only _PUT_MODEL_ PUT_FILE_CLOSE_() HP O O Guardian objects only _PUT_MODEL_ PUT_FILE_OPEN_() HP O O Guardian objects only _PUT_MODEL_ PUT_FILE_WRIT
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes put_RECEIVEREADL() HP O O Guardian objects only _PUT_MODEL_ put_regFile() Threads O O OSS objects only _PUT_MODEL_ put_regFileIOHandler() Threads O O OSS objects only _PUT_MODEL_ put_regOSSFileIOHandler() Threads O O OSS objects only _PUT_MODEL_ put_regPathsendFile() Threads O O OSS objects only _PUT_MODEL_ put_re
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _PUT_MODEL_ Support for TNS/E native Guardian and 32-bit OSS callers PUT_SERVERCLASS_SEND_() HP O O Guardian objects only _PUT_MODEL_ PUT_SERVERCLASS_SEND_INFO_() HP O O Guardian objects only _PUT_MODEL_ PUT_SERVERCLASS_SENDL_() HP O O Guardian objects only _PUT_MODEL_ PUT_SETMODE() HP O O Guardian objects only _PUT_MOD
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _PUT_MODEL_ PUT_WRITEUPDATEUNLOCKX() HP O O Guardian objects only _PUT_MODEL_ PUT_WRITEUPDATEX() HP O O Guardian objects only _PUT_MODEL_ PUT_WRITEX() HP O O Guardian objects only _PUT_MODEL_ putc() ISO G, O G, O putc_unlocked() Threads G, O G, O putchar() ISO G, O G, O putchar_unlocked() Threads G, O G, O p
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes _SPT_MODEL_ readdir64() XLFS G, O G, O OSS parameters only OSS objects and limited Guardian objects _LARGEFILE64_SOURCE or _FILE_OFFSET_BITS readdir64_r() Threads G, O G, O OSS parameters only OSS objects and limited Guardian objects _LARGEFILE64_SOURCE or _FILE_OFFSET_BITS _SPT_MODEL_ readlink() X/OPEN G, O G, O OSS objects
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes regexec() XPG4 G, O G, O regfree() XPG4 G, O G, O remainder() XPG4 G, O G, O remainderf() ISO G, O G, O remainderl() ISO G, O G, O remove() ISO G, O G, O Parameters must match process remove_guardian() HP G, O G, O Guardian parameters only remove_oss() HP G, O G, O OSS parameters only remque() XPG4 G,
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes scalblnl() ISO G, O G, O IEEE_float only scalbn() ISO G, O G, O IEEE_float only scalbnf() ISO G, O G, O IEEE_float only scalbnl() ISO G, O G, O IEEE_float only scandir() HP O O HP extension to XPG4 specification scandir64() XLFS O O _LARGEFILE64_SOURCE or _FILE_OFFSET_BITS scanf() ISO G, O G, O sched_get_
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes sendto64_() HP O O Support for TNS/E native Guardian and 32-bit OSS callers setbuf() ISO G, O G, O setegid() XPG4 O O seteuid() XPG4 O O setfilepriv() HP G, O G, O setgid() POSIX O O setgrent() POSIX G, O G, O setgroups() HP O O sethostent() XPG4 O O setjmp() ISO G, O G, O setkey() XPG4 G, O G,
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes shmctl() XPG4 G*, O G*, O * Guardian support for this function is for J06.12 and later J-series RVUs and H06.23 and later H-series RVUs only. shmdt() XPG4 G*, O G*, O * Guardian support for this function is for J06.12 and later J-series RVUs and H06.23 and later H-series RVUs only.
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes socketpair() XPG4 O O _XOPEN_SOURCE_EXTENDED snprintf() ISO G, O G, O sprintf() ISO G, O G, O SPT_ ABORTTRANSACTION() HP O O Guardian objects only spt_accept() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA _XOPEN_SOURCE_EXTENDED spt_acceptx() Threads O O OSS objects only _SPT_MODEL_ S
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA _XOPEN_SOURCE_EXTENDED spt_connectx() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK _XOPEN_SOURCE_EXTENDED SPT_CONTROL() HP O O Guardian objects only spt_du
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_fd_write_ready() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_fflush() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_fflushx() Threads O O OSS objects only SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_N
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK SPT_FILE_CLOSE_() HP O O Guardian objects only SPT_FILE_OPEN_() HP O O Guardian objects only spt_fork() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_fputwc() Threads O O OSS objects only spt_fputwcx() Threads O O OSS objects only SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_fread() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_fwrite() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_fwritex() Threads O O OSS objects only SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes spt_getsx() Threads O O OSS objects only SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_getTMFConcurrentTransactions() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_getw() Threads O O OSS objects only SP
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes spt_INITRECEIVE() HP O O Guardian objects only spt_INITRECEIVEL() HP O O Guardian objects only spt_interrupt() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_interruptTag() Threads O O OSS objects only SPT_LOCKFILE() HP O O Guardian objects only SPT_LOCKREC() HP O O Guardian obje
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_putcx() Threads O O OSS objects only SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_puts() Threads O O OSS objects only spt_putsx() Threads O O OSS objects only SPT_
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK spt_read() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA SPT_READLOCKX() HP O O Guardian objects only SPT_READUPDATELOCKX() HP O O Guardian objects only SPT_READUPDATEX() HP O O Guardian objects only spt_readv() Threads O O
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ PRAGMA _XOPEN_SOURCE_EXTENDED spt_recvfromx() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK _XOPEN_SOURCE_EXTENDED spt_recvmsg() Threads O O OSS objects only _XOPEN_SOURCE_EXTENDED sp
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE_ PRAGMA spt_regPathsendTagHandler() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_regTimerHandler() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_REPLYX() HP O O Guardian objects only spt_REPLYXL() HP O O Guardian objects only SPT_RESUMETR
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes spt_sendtox() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; or SPT_THREAD_AWARE_ XNONBLOCK or SPT_THREAD_AWARE_ PRAGMA_XNONBLOCK _XOPEN_SOURCE_EXTENDED spt_sendx() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK; o
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_SIGNAL_ PRAGMA spt_sigpending() Threads O O OSS objects only _SPT_MODEL_ SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_sigsuspend() Threads O O OSS objects only _SPT_MODEL_ Set SPT_THREAD_AWARE_ SIGNAL to catch externally generated signals at the thread level spt_sigwait() Threads O O OSS objects only Set SPT_T
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA SPT_UNLOCKFILE() HP O O Guardian objects only SPT_UNLOCKREC() HP O O Guardian objects only spt_unregFile() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_unregOSSFileIOHandler() HP O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGM
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes To use nonblocking feature set SPT_THREAD_AWARE_ NONBLOCK or SPT_THREAD_AWARE_ PRAGMA_NONBLOCK spt_wakeup() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA spt_write() Threads O O OSS objects only SPT_THREAD_AWARE or SPT_THREAD_AWARE_ PRAGMA SPT_WRITEREADX() HP O O Guardian objects only SPT_WRITEUP
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes srand48() XPG4 G, O G, O srandom() XPG4 G, O G, O sscanf() ISO G, O G, O stat() POSIX G, O G, O OSS parameters only OSS objects and limited Guardian objects stat64() XLFS G, O G, O OSS parameters only OSS objects and limited Guardian objects _LARGEFILE64_SOURCE or _FILE_OFFSET_BITS statvfs() XPG4 O G, O OSS param
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From strftime() ISO G, O G, O strlen() ISO G, O G, O strlen64() HP G, O G, O strncasecmp() XPG4 G, O G, O strncat() ISO G, O G, O strncat64() HP G, O G, O strncmp() ISO G, O G, O strncmp64() HP G, O G, O strncpy() ISO G, O G, O strncpy64() HP G, O G, O strpbrk() ISO G, O G, O strptime() XPG4 G, O G, O strrchr
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes swab() XPG4 G, O G, O swprintf() ISO G, O G, O swscanf() ISO G, O G, O symlink() X/OPEN G, O G, O sysconf() POSIX G, O G, O syslog() X/OPEN G, O G, O system() ISO G, O G, O tan() ISO G, O G, O tanf() ISO G, O G, O tanh() ISO G, O G, O tanhf() ISO G, O G, O tanhl() ISO G, O G, O tanl() ISO G,
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes tgammaf() ISO G, O G, O IEEE_float only tgammal() ISO G, O G, O IEEE_float only time() ISO G, O G, O times() POSIX G, O G, O tmpfile() ISO G, O G, O Result matches process temp file created in tmpfile_guardian() HP G, O G, O Guardian parameters only tmpfile_oss() HP G, O G, O OSS parameters only tmpfile64(
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes umask() POSIX O O uname() POSIX O O ungetc() ISO G, O G, O ungetwc() XPG4 G, O G, O unlink() ISO O G, O unordered() XPG4 G, O G, O usleep() POSIX O O _PUT_MODEL_ utime() POSIX O G, O OSS parameters only OSS objects and limited Guardian objects va_arg() ISO G, O G, O va_end() ISO G, O G, O va_start
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From wcscpy() XPG4 G, O G, O wcscspn() XPG4 G, O G, O wcsftime() XPG4 G, O G, O wcslen() XPG4 G, O G, O wcsncat() XPG4 G, O G, O wcsncmp() XPG4 G, O G, O wcsncpy() XPG4 G, O G, O wcspbrk() XPG4 G, O G, O wcsrchr() XPG4 G, O G, O wcsrtombs() ISO G, O G, O wcsspn() XPG4 G, O G, O wcstod() XPG4 G, O G, O wcstof(
Table 79 API Interoperability in Native Processes (Functions n through z) (continued) Function or Macro Specified Module By Compiled As Process Called From Usage Notes wordfree() POSIX O O wprintf() ISO G, O G, O write() XPG4 O O OSS parameters only OSS objects and limited Guardian objects _PUT_MODEL_ write64_() HP O O Support for TNS/E native Guardian and 32-bit OSS callers writev() XPG4 O O OSS parameters only OSS objects only _PUT_MODEL_ wscanf() ISO G, O G, O y0() XPG4 G
Glossary $RECEIVE A special Guardian file through which a process receives and optionally replies to messages from other processes. 32-bit address space The portion of the address space available to users of 32-bit addresses. On TNS/E systems, 32-bit addresses become 64-bit addresses by sign extension. Addresses 0 through 0x7FFFFFFF designate the first 2 gigabytes (GB) of per-process address space, starting at address 0.
appropriate privileges An implementation-defined means of associating privileges with a process for function calls or function call options that need special privileges. authorization attributes Security attributes of a process that can change through use of functions such as setuid() (or of Guardian procedures such as PROCESS_CREATE_) without reauthentication. The authorization attributes include the effective user ID, saved-set user ID, saved-set group ID, user audit flags, and the effective user name.
conforming POSIX.1 application An application that is either an ISO/IEC-conforming POSIX.1 application or a national-standards-body conforming POSIX.1 application. constraint An object that helps protect the integrity of data in a table by specifying a condition or conditions that all the values in a particular column of the table must satisfy. Unlike other SQL objects, a constraint has only an SQL name, not an operating system name, and a constraint does not have a file label.
event A significant change in some condition in the system or network. An event can be an operational error, notification of limits exceeded, request for action, notification of lines and other objects becoming available, and so on. Note that an event is not always an error. Event Management Service (EMS) A part of the Distributed Systems Management (DSM) product used to provide event collection, event logging, and event distribution facilities.
file transfer protocol (FTP) 1. 2. The Internet-standard, high-level protocol for transferring files from one machine to another. The application used to send complete files over Transmission Control Protocol/Internet Protocol (TCP/IP) services filename In the OSS environment, a component of a pathnamecontaining any valid characters other than slash (/) or null. See also file name. fileset In the OSS environment, a set of files with a common mount point within the file hierarchy.
Guardian services An application program interface (API) to the HP NonStop™ operating system, plus the tools and utilities associated with that API. This term is synonymous with Guardian environment. See also Guardian. hard link The relationship between two directory entries for the same file. A hard link acts as an additional pointer to a file. A hard link cannot be used to point to a file in another fileset. Contrast with symbolic link. header 1. 2.
large file aware An application or function that can process large OSS files in addition to small OSS files. For example, it must be able to access large files as input and generate large files as output. Contrast with large file safe. large file safe An application or function that causes no loss of data or corruption of data when it encounters a large OSS file.
noft utility A utility that reads and displays information from TNS/R native object files. non-regular file An OSS file that is not a regular (disk) file. noncanonical input mode A terminal input mode in which data is made available to a process when a timer expires or when a certain number of characters have been entered. Noncanonical data is not grouped into logical lines of input. This mode is sometimes called block mode or transparent mode. Contrast with canonical input mode.
OSS SEEP-protected Additional file-access authorization provided by an OSS Security Event-Exit Process (SEEP). For details of OSS SEEP, see “Accessing OSS SEEP-Protected Files” (page 83). OSS signal See Open System Services (OSS) signal. parent process The process that created a given process, or (if that process has stopped) a process that has inherited a given process. See also child process.
process group A set of OSS processes that can signal associated processes. Each OSS process in an Expand node is a member of a process group; the process group has a process group ID. A new process becomes a member of the process group of its creator. process group ID The unique identifier representing a process group during its lifetime. process group leader The process that has the process group ID of its process group as its OSS process ID.
root fileset The fileset with the device number of 0, normally containing the root directory for the OSS file system in an HP NonStop system. HP recommends that this fileset be named “root”. save file A file created by the Inspect subsystem in response to a command from a debugger. A save file contains enough information about a running process at a given time to restart the process at the same point in its execution.
other processes. A process can block some deferrable signals but not others. A signal is nondeferrable by the nature of its generation, not its identity; thus kill(pid, SIGSEGV) sends a deferrable signal to the target pid. Signals are used in all native and all OSS processes, but not in Guardian TNS processes (which use traps instead). signal delivery The action taken in or upon the target process because of the signal.
system process A process running as part of or on behalf of the HP NonStop operating system. A system process does not have an OSS process ID. System V A version of UNIX developed and marketed originally by AT&T. terminal A type of character special file that conforms to the interface description in Clause 7 of ISO/IEC IS 9945-1: 1990.
RISC instruction set and can run TNS object files by interpretation or after acceleration. TNS/R systems include all HP systems that use NSR-x processors. Contrast with TNS and TNS/E. TNS/R C compiler The C compiler that generates TNS/R object files. Compare with TNS C compiler and TNS/E C compiler.
drives, or to a virtual volume managed by the Storage Management Foundation (SMF). The volume name is also the name of the process that manages the volume. waited I/O I/O operations for which the initiating process does not resume execution until the I/O operations are completed. Contrast with nowait I/O. working directory In the Open System Services (OSS) environment, a directory, associated with a process, that is used in pathname resolution for relative pathnames.
Index Symbols #define _FILE_OFFSET_BITS 64, 503 #define _LARGEFILE64_SOURCE, 503 #define _PUT_MODEL_, 504 #define _SPT_MODEL_, 504 #define _TANDEM_SOURCE, 505 #define _XOPEN_SOURCE_EXTENDED, 505 #define SPT_THREAD_AWARE, 346, 504 #define SPT_THREAD_AWARE_NONBLOCK, 346, 347, 504 #define SPT_THREAD_AWARE_PRAGMA, 346, 504 #define SPT_THREAD_AWARE_PRAGMA_NONBLOCK, 346, 347, 504 #define SPT_THREAD_AWARE_PRAGMA_XNONBLOC, 346 #define SPT_THREAD_AWARE_PRAGMA_XNONBLOCK, 505 #define SPT_THREAD_AWARE_SIGNAL, 505 #defi
setacl command, 266 supported RVUs, 63 types of files supported, 260 types of objects supported, 63 access control lists (ACLs) and NFS, 64, 260 access() function, 91, 92, 253 Accessing OSS SEEP-protected files, 83 acl() function, 251, 253, 266 ACL-PRESENT flag, 63 ACLs see Access control lists (ACLs) aclsort() function, 268 add_define utility, 114 ADDDSTTRANSITION procedure, 172 Address space shared memory, 190 AF_INET sockets, 174, 175, 177 AF_INET6 sockets, 175 AF_UNIX sockets AF_UNIX Release 1, 187 AF_U
Guardian processes example using Guardian procedures, 123 using Guardian procedures, 123, 126 OSS processes, using Guardian procedures, 123, 126 using OSS functions, 119 Controlling terminal, 114 Converting 32-bit applications to 64-bit, 307 CONVERTPROCESSTIME procedure, 172 CONVERTTIMESTAMP procedure, 172 CPUTIMES procedure, 172 creat() function, 92, 254 creat64() function, 254 Creating processes example using the PROCESS_SPAWN_ procedure, 126 Guardian processes example using Guardian procedures, 123 using
Fault isolation, 331, 430 fchmod() function, 251, 253 fchown() function, 251, 254 fclose() function, 93 fcntl() function, 93 fd_count parameter, child process, 123 fd_map parameter, child process, 123 FE_ENOENT error, 188 Feature test macro, 502, 503 FIFO, 174, 175, 176 File caching, 87 File descriptor inherited from parent process , 123 nonblocking, 341, 396 File privilege attribute, 63 File system, 29 Guardian, 30, 32 OSS, 28, 30 File types Guardian, OSS access, 32 OSS, 30 File-type conversion tools, 50 F
getaddrinfo() function, 201 getcwd() function, 94 getdate() function, 170 getegid() function, 151, 251 getenv() function, 151 geteuid() function, 151, 251 getfilepriv command, 272 getgid() function, 151, 252 getgrent() function, 252 getgroups() function, 151, 252 gethostbyaddr() function, 201 gethostbyname() function, 201 gethostent() function, 201 gethostid() function, 201 getipnodebyaddr function, 201 getipnodebyname() function, 201 getlogin() function, 252 getnameinfo() function, 201 getnetbyaddr() funct
HP NonStop TS/MP, accessing from OSS programs, 247 HP NonStop Tuxedo system, accessing from OSS programs, 247 HP Tandem Development Suite (TDS), 52 HP Tandem LAN Access Method (TLAM), accessing from OSS programs, 245 htonl() function, 202 htons() function, 202 I I/O balancing read and write operations, and performance improvement, 195 printing, 226, 227, 233 example, lp utility with popen() function, 226 redirecting to Guardian objects, 214 tape, 208 example, pax utility with popen() function, 209 terminal
parameters, initializing , 239 Logon, authenticated, 273 longjmp() function, 152, 330, 388 lp utility, example with popen() function, 226 LP64 data model, 289 lseek() and lseek64() functions, 95 lstat() and lstat64() functions, 95 lstat() function, 252 lstat64() function, 252 M make utility, 45 Managing memory, 162 Measure product , 51, 167 Memory segments, 164, 189 sharing, 176 synchronize access, 164, 189 Memory management, 162 Memory segments extended, 162 flat, 162 Guardian, 164 native processes, 163 O
64-bit support, 285 Guardian command, piping output, 44 TACL process, starting from, 44 text-editing tools, 44 OSS file system, 28 directories, 54 nesting, 54 UNIX differences, 65 OSS files FUP INFO command display, 57 information with Guardian procedure by name, 74, 76 information with Guardian procedure by number, 76 labeled-tape operations, 210 large files, 78 printing from program, 226 reading with Guardian procedure, nowait mode, 72 reading with Guardian procedure, wait mode, 73 sending directly to pri
pax utility, example with popen() function, 209 PC cross compiler, 52 pclose() function, 198 Performance analyzer, 51 Performance considerations file system functions, 86 fork() function , 138 interprocess communication , 195 process creation, 119, 138 process management , 138 tdm_fork() function , 138 tdm_spawn() function , 138 tdm_spawnp() function , 138 workload distribution, 138 Permissions, OSS corresponding Guardian security, 63 FUP INFO display, 57 permission bits, 30 perror() function, 243 Persisten
environment, 129 example with PROCESS_GETINFO_ procedure, 131 OSS See OSS processes, 113 persistent, 125 pipes and FIFOs on same processor, and performance improvements , 195 Processes, Guardian shared memory, 164, 189 Processes, OSS shared memory, 164, 189 PROCESSHANDLE_COMPARE_ procedure, 157 PROCESSHANDLE_DECOMPOSE_ procedure, 157 PROCESSHANDLE_GETMINE_ procedure, 157 PROCESSHANDLE_NULLIT_ procedure, 157 PROCESSHANDLE_TO_CRTPID_ procedure, 157 PROCESSHANDLE_TO_FILENAME_ procedure , 157 PROCESSHANDLE_TO_S
Guardian translation, 55 remove() function, 97 rename() function, 97, 254 rename_oss() function, 97 REPLYX procedure, 205 Resource types, 313, 383 Restricted-access filesets see Filesets, restricted-access retcode, 39 Return value changes for thread functions, 314, 381 Guardian procedure, OSS example, 38 rewinddir() function, 97 rmdir() function, 97, 252, 254 Root directory, 28 S S_NONSTOP attribute performance and reliability considerations, 88 S_NONSTOP file open flag, 87, 88 Safeguard access control lis
handler, default, 118 threads with, 331, 388 Signal mask, 330, 388 signal() function, 153 SIGNALPROCESSTIMEOUT procedure, 173 SIGNALTIMEOUT procedure, 173 sigpending() function, 153 sigprocmask() function, 153 sigsetjmp() function, 153 sigsuspend() function, 154 sigwait() function, 385 Single-threading versus multithreading, 332, 431 sleep() function, 118, 154 Small files see OSS files, small files and 64-bit APIs, 78 size limit, 78 underlying Guardian file format, 78 SMF, 65, 68 SNAX Extended Facility (SNA
used with threads, 331, 430 tdm_spawn() function, 113, 154 performance considerations, 119, 138 used with audited file, 255 tdm_spawnp() function, 113 example, 121, 123 performance considerations, 119, 138 used with audited file, 255 tdm_spawnp(2) function, 154 tdmext.
X X.
