UnixWare/OpenServer Development Kit -- Release Notes

Note that the _stat and stat interfaces listed above are the versions of the stat system call that provide the older System V Release 3-style stat structure (before expanded fundamental types). Normally, the stat.h header file translates a call to stat(2) to xstat, which has always been in the shared part libc.

New applications compiled without -l cudk70 on Release 7.1.1 will no longer bind the symbols listed above into their own images and will, instead, expect to find them in the shared part of libc. Since the native versions of the shared part of libc on Release 7.0.1 do not contain the above symbols, such applications will not run on these systems. To permit Release 7.1.1 applications to run on UnixWare 7 Release 7.0.1, include the libcudk70.a library during the linking phase of compiling the application.

Here is an example:

   # start on a Release 7.1.1 system
   

   # a simple test program; realpath() is one of the APIs that moved
   #   from the static to the dynamic part of libc in Voyager
   UW701> cat rp.c
   

   #include <stdlib.h>
   #include <sys/param.h>
   #include <stdio.h>
   

   int main() {
           char p[MAXPATHLEN];
           realpath(".", p);
           printf("%s\n", p);
   }
   
   # build on Release 7.1.1 in the usual way
   UW711> /usr/ccs/bin/cc rp.c
   

   # run on Release 7.1.1 ... works great
   UW711> ./a.out
   /lfs/home1/jls/test
   

   # now move executable to a Release 7.0.1 system
   UW711> rcp a.out UW701:test
   

   # now we're on the Release 7.0.1 system
   

   # try to run it here ... test fails
   UW701> ./a.out
   dynamic linker: ./a.out: symbol not found: realpath
   Killed
   

   # get back to Release 7.1.1 system
   # and this time link program against special library
   UW711> cc rp.c -lcudk70
   

   # executable still works on Release 7.1.1
   UW711> ./a.out
   /lfs/home1/jls/test
   

   # now move it to the Release 7.0.1 system again
   UW711> rcp a.out UW701:test
   

   # and try it there ... this time it works
   UW701> ./a.out
   /home/jls/test

   UW701> nm a.out | grep realpath
   [46]    | 134513700|      52|FUNC |GLOB |0    |UNDEF  |realpath

In the second build, realpath has been statically linked in from the libcudk70 archive:

   UW701> nm a.out | grep realpath
   [31]    |         0|       0|FILE |LOCL |0    |ABS    |realpath.c
   [53]    | 134515216|      36|FUNC |GLOB |0    |8      |realpath
   [63]    | 134515216|      36|FUNC |GLOB |0    |8      |_realpath

In upcoming releases, more UnixWare system libraries and APIs will be made available through shared objects. Existing application binaries will continue to work as they do today, but when relinked on these newer releases, it is possible that the application binaries produced will not run on older releases.

Similarly, shared libraries currently using non-PIC objects will also continue to run as they do today, and when relinked on a newer release, it is again possible to create shared libraries that will not run on older releases.

Generally, SCO will provide updated UDKs so that older releases can run these newer binaries and shared libraries, but it is not required that all systems be upgraded. Thus updates of libcudk70.a to enable building binaries and shared libraries that can run on older releases will most likely be provided as these APIs and libraries are made available through shared objects.

C Compiler and Linker

To create an executable or shared object, use the CC or cc command. If any input object files contain C++ code, you must use the CC command.

Invoking the Linker directly

ld should be invoked directly only if the -r option is used to create a relocatable object to be used in a later link.

libthread and fork(2)

UnixWare 7 provides two versions of the traditional fork(2) system call: fork1 and forkall. In a process with only one light-weight process (LWP), there is no difference between the two routines. In a process with multiple LWPs, fork1 will create a child process with only a single LWP, the LWP that invoked fork1; forkall will create a child process that has copies of all LWPs from the parent process. Until UnixWare 7.0.1, fork was a synonym for forkall. In UnixWare 7.0.1, a change was introduced for processes that link with libthread: fork became a synonym for fork1 instead of forkall. This was done to conform to the POSIX and X/Open definitions of fork in multithreaded applications. However, certain applications had grown to depend on the behavior of fork and broke when the change was introduced. (There was no change in behavior for processes that do not link with libthread). In this release, the original behavior of fork has been restored; it is now once again synonymous with forkall. Applications that link with libthread and want the POSIX and X/Open behavior for fork can invoke fork1 directly or define the global variable _thread_sys_behavior and assign 1 as its value:

int _thread_sys_behavior = 1;

Process tracing (LD_TRACE)

Process tracing allows you to see what functions your process is calling, while it is executing. To trace an executable, you can set the following environment variables:

LD_TRACE=[sym,tim,hitim,lib,ret]
LD_TRACE_FILENO=fd
LD_TRACE_ARGNO=num
LD_TRACE_SCALE=num
LD_TRACE_STACK=funcname[,funcname...]
LD_TRACE_FRAMES=num

If LD_TRACE is set but doesn't contain any of the specified flags, you get a line for each function called:

sym(arg1, arg2, arg3) from hex_addr

You only see functions known to the dynamic linker; that is, no calls to static functions or functions defined in the same shared library as the caller and linked with the -Bsymbolic option to ld.

You can specify the number of arguments using LD_TRACE_ARGNO (default 3).

If a given library provides a table of functions and argument formats to the dynamic linker, then the dynamic linker will know the correct number of arguments and their formats (hex, decimal, unsigned, string, character, long long, float, double, long double). Varargs functions currently always print 3 hex args after the last fixed argument. Currently, only libc provides such a table.

If the sym flag is set, you get the symbol name instead of hex_addr. If the lib flag is set you get sym@lib and hex_addr@lib (or name@lib).

Symbolic names for the reference address can be wrong if the references come from symbols that have not been exported and so are not known to the dynamic linker. This is especially prevalent for references from a.outs. The dynamic linker picks the symbol from the same object that is closest to, but less than the reference address.

If tim is set you get:

	... at sec.usec

This uses gettimeofday; timing is not available until all shared library _init routines have been run.

If hitim is set, you get timing using the Pentium's high resolution rdtsc instruction. This will be either a raw value:

	... at ticks

or a scaled value, if you set LD_TRACE_SCALE. LD_TRACE_SCALE expects an integer representing the clock rate of your chip in mhz (e.g, 133 for a 133 mhz Pentium).

	... at sec.ticks

Caveats for the high resolution timer:

1. You must be on a Pentium (or later).
2. You must have set USER_RDTSC to non-zero using idtune and rebuilt/rebooted the kernel.
3. Timings can be inacurrate for a multi-processor box, since we do not synch the processor timers.

If ret is set, you get another line per call:

	=> sym[@lib] returned hex_val

The return value format is also specified by the function format table, if present. No format is printed for functions that return structs.

Output goes to file descriptor 2 unless you set LD_TRACE_FILENO, in which case it goes to fd.

Finally, instead of the regular 1 per call trace, you can get a stack trace for every instance of a given call. Say you want to see a stack trace for every call to malloc and printf. LD_TRACE_STACK=malloc,printf

You can control the output using:
LD_TRACE=[sym,lib,ret,tim,hitim]
LD_TRACE_ARGNO=num
LD_TRACE_FILENO=num
LD_TRACE_FRAMES=num

The timings and return values are printed only for the top function in each stack (the one you asked to trace). sym and lib control the format of the output for the rest of the frames as well. The depth of the stack can be limited using LD_TRACE_FRAMES. A value of 0 (the default) means print the entire stack.

A caveat about stack traces: the algorithm used by this feature works in most cases; one exception is for functions that return structs. Tracing through signal handlers is also likely to be problematic.

Limitations

• ``UDK binaries on SCO OpenServer''

• ``SCO OpenServer binaries and the OSRcompat package''

• ``Debugger''

• ``C++ Standard Library''

• ``libftp''

• ``link(2), rename(2), and symlink(2)''

• ``Sockets''

• ``Profiling and libthread''

• ``Java files and file(1)''

• ``SCOhelp on SCO UnixWare 2.1.3''

• ``PTFs on SCO UnixWare 2.1.3''

• ``Graphics on SCO UnixWare 2.1.3''

• ``svc_fdset warning''

UDK binaries on SCO OpenServer

UDK-built binaries using the following components will not work on SCO OpenServer:

• Remote Procedure Calls (RPC)

• Network Information Service (NIS)

• job control interfaces

• the getutent library call

• the threads library

SCO OpenServer binaries and the OSRcompat package

The dynamic linker provided with the UDK sometimes fails to identify the target operating system of a binary (e.g., with binaries that have been run through some versions of GNU strip). If SCO OpenServer binaries that executed successfully before you installed the UDK fail to execute, use the elfmark -t osr5 command to positively identify them as SCO OpenServer binaries.

Debugger

The graphical interface to debug will occasionally produce the following message: message pops up:

   Invalid operation on running object p??

The solution is to try again after a small pause.

In UnixWare 7 the online help for the graphical debugger is linked to the online documentation library for UnixWare 7. Therefore, the debugger online help does not work on SCO OpenServer systems.

C++ Standard Library

Most of the new C++ Standard Library is not in UnixWare 7. This includes:

• Standard Template Library. The C++ STL is not yet provided as part of the UDK. However, there is a freeware version available from Silicon Graphics. Skunkware contains a distribution of SGI STL release 3.11, with modifications for the SCO UDK C++ compiler. See the README.SCO within that distribution for further information. There is no official support from SCO for this distribution, although we are interested in hearing of any problems in using it.

• new iostreams

• string, bitset, auto_ptr; included as part of the SGI STL 3.11 (see above)

• locale

• new complex, valarray, numeric limits

libftp

Contrary to what is stated in the topic ``Porting, integration and compatibility'' in the UnixWare 7 documentation set, applications linked against the UnixWare 7 FTP library (libftp) may be run on both OpenServer 5 and UnixWare 2.1.X systems provided that the appropriate compatibility module has been installed.

link(2), rename(2), and symlink(2)

Some system administration scripts and other programs, which run with root privilege, create temporary files with potentially predictable names in public directories such as /tmp. In previous releases of UnixWare 7, it was possible for ordinary users to render a system unusable by linking protected files onto the names used by the programs. To guard against this type of attack, restrictions have been placed on the following system calls in Release 7.1.1:

System call	Restriction
link(2)	If the ``sticky bit'' (see chmod(2) is set on the directory in which the link is being created, either the directory or the object being linked from must be owned by the calling user ID.
rename(2)	If the sticky bit is set on the destination directory, the object being renamed cannot be a symbolic link, and either the directory or the object being renamed must be owned by the calling user ID. If the destination name refers to an exiting file, either this file or the destination directory must be owned by the calling user ID.
symlink(2)	If the sticky bit is set on the directory in which the link is being created, the directory must be owned by the calling user ID.

 -----------------------------------------------------------------------
| System call |  Restriction                                           |
|-------------|--------------------------------------------------------|
| link(2)     |  If the ``sticky bit'' (see chmod(2) is set on the     |
|             |  directory in which the link is being created, either  |
|             |  the directory or the object being linked from must be |
|             |  owned by the calling user ID.                         |
|-------------|--------------------------------------------------------|
| rename(2)   |  If the sticky bit is set on the destination directory,|
|             |  the object being renamed cannot be a symbolic link,   |
|             |  and either the directory or the object being renamed  |
|             |  must be owned by the calling user ID. If the          |
|             |  destination name refers to an exiting file, either    |
|             |  this file or the destination directory must be owned  |
|             |  by the calling user ID.                               |
|-------------|--------------------------------------------------------|
| symlink(2)  |  If the sticky bit is set on the directory in which the|
|             |  link is being created, the directory must be owned by |
|             |  the calling user ID.                                  |
|-------------|--------------------------------------------------------|

If the stated conditions are not met, the system call will fail with the error EPERM (Not privileged) set in errno. The P_OWNER privilege is required to override this restriction.

These restrictions are also apparent in the behavior of the ln(1) and mv(1) commands, which use these system calls, when used with the memfs, sfs, s5 and vxfs filesystem types on a Release 7.1.1 system.

Sockets

Release 7.1.1 of UnixWare 7 includes in-kernel sockets in which the socket routines used with the Internet (AF_INET and AF_INET6) and UNIX domain (AF_UNIX) families have been implemented as individual system calls. Previous releases of UnixWare implemented sockets as library calls, each of which might need to invoke many system calls to perform its function. The new in-kernel sockets implementation greatly enhances the performance of networking commands and services that use sockets by reducing the system overhead due to context switching. Other benefits include:

• in-kernel sockets are both multithread safe and MP safe

• increased server throughput is achieved by allowing multiple concurrent accept(3sock) calls on each socket

• listen(3sock) is no longer limited by the number of available semaphores

The define constant __OLD_SOCKET__ requests that the previous version of UnixWare 7 sockets be used, if available, instead of the in-kernel socket subsystem that is included in Release 7.1.1. Socket applications compiled on a Release 7.1.1 system will work on earlier releases of UnixWare 7 provided that PTF7401 has been installed on that system, or the application has been compiled with -D__OLD_SOCKET__ specified.

On a Release 7.1.1 system, the behavior of the sockets subsystem is controlled by the following parameters to inconfig(1Mtcp):

ss_connafunixndelay

Determines how a non-blocking connect(3sock) on a UNIX domain (AF_UNIX) socket will behave.

If set to 0 (default), connect returns -1 and sets EINPROGRESS in errno. However, the connection request is not aborted, and the connection is established asynchronously. Subsequent connect calls to the socket will fail if a connection has not yet been set up, and will return EALREADY in errno.

If set to 1, connect returns 0 and does not set a value in errno. The connection will complete synchronously and without appreciable delay. This ensures compatibility for applications which have been developed on operating systems where EINPROGRESS is not set. LI "ss_selectrdband" Determines how select(3C) will behave when a socket, for which an exception descriptor set has been defined, is shut down or closed for read operations. If set to 0 (default), exception bits are not set. If set to 1, exception bits are set.

ss_uw7_compat

The value of this parameter controls the system-wide default behavior of how newly created sockets handle asynchronous errors and events:

0

Sockets created by all binaries exhibit new behavior.

1 (default)

Sockets created by binaries that have been compiled on a Release 7.1.1 or later system exhibit new behavior. Sockets created by older binaries behave as in previous releases.

2

Sockets created by all binaries behave as in previous releases.

The SI_U7COMPAT ioctl command, described below, controls the behavior of individual sockets.

The behavior of sockets when handling asynchronous events and errors was changed in Release 7.1.1. Compatibility with behavior in earlier releases of UnixWare 7 may be obtained using the SI_U7COMPAT ioctl(2) command on an individual socket file descriptor:

   #include <sys/sockmod.h>
   ...
   int err, fd, x;
   ...
   /* Create a socket */
   fd = socket(domain, type, protocol);
   ...
   /* Select new behavior */
   x = 0;
   err = ioctl(fd, SI_UW7COMPAT, &x);
   ...
   /* Select old behavior */
   x = 1;
   err = ioctl(fd, SI_UW7COMPAT, &x);

0

Select new behavior:

• For read(2), recv(3sock), recvmsg(3sock), and recvfrom(3sock), an asynchronous error causes the function to return with an error without reading any data.

• For write(2), send(3sock), sendmsg(3sock), and sendto(3sock), an asynchronous error causes the function to return with an error without writing any data.

• For poll(2), an asynchronous error causes POLLERR to be set in the revent member of the file descriptor's pollfd structure.

• For select(3C), an asynchronous error causes an exception to be set in the exceptfds fd_set that corresponds to the file descriptor.

1

Select old behavior:

• connect(3sock) blocks all signals except SIGHUP, SIGINT, SIGQUIT, and SIGTERM.

• connect(3sock) always returns EINPROGRESS when first called to establish an asynchronous connection.

• If data received by a connectionless socket is not for the connected address, getsockopt(3sock) can retrieve EINVAL set for SO_ERROR. Other operations may set the asynchronous error returned by SO_ERROR.

Default socket behavior is controlled by the value of the inconfig(1Mtcp) ss_uw7_compat parameter.

The in-kernel sockets implementation in Release 7.1.1 is closer in behavior to BSD 4.3 sockets than was the sockets implementation in previous releases of UnixWare. The tables below update the tables given in ``Moving sockets applications to UnixWare 7'' in the online documentation.

Connection-mode primitives

BSD 4.3	UnixWare 7
If connect is called on an unbound socket, the protocol determines whether or not the endpoint will be bound before the connection takes place	When connect is called on an unbound socket, that socket is always bound to an address selected by the transport provider

 BSD 4.3                     UnixWare 7
 If connect is called on     When connect is called on
 an unbound socket, the      an unbound socket, that
 protocol determines         socket is always bound to
 whether or not the          an address selected by
 endpoint will be bound      the transport provider
 before the connection
 takes place

Data transfer primitives

BSD 4.3

UnixWare 7

If the MSG_PEEK flag has been set when sendmsg is called, and access rights are available, the access rights will be copied, leaving them available for reading by a subsequent call to recvmsg

If the MSG_PEEK flag is specified in a call to recvmsg, and access rights are available, the access rights will be transferred to the user buffer associated with the receiving socket. They are then destroyed, and the transferring socket has no further access to them. They are therefore unavailable to a subsequent call to recvmsg. Any data associated with the access rights will also be copied to the user buffer and will not be available to recvmsg

 BSD 4.3                     UnixWare 7
 If the MSG_PEEK flag has    If the MSG_PEEK flag is
 been set when sendmsg is    specified in a call to
 called, and access rights   recvmsg, and access
 are available, the access   rights are available, the
 rights will be copied,      access rights will be
 leaving them available      transferred to the user
 for reading by a            buffer associated with
 subsequent call to          the receiving socket.
 recvmsg                     They are then destroyed,
                             and the transferring
                             socket has no further
                             access to them.  They are
                             therefore unavailable to
                             a subsequent call to
                             recvmsg.  Any data
                             associated with the
                             access rights will also
                             be copied to the user
                             buffer and will not be
                             available to recvmsg

Information primitives

BSD 4.3	UnixWare 7
The SIOCSPGRP and FIOSETOWN commands for the ioctl(2) system call and the F_SETOWN command for the fcntl(2) system call take as arguments a positive process id or a negative process group id that identifies the intended recipient list of subsequent SIGURG and SIGIO signals	The only acceptable arguments to ioctl(2) and fcntl(2) are the caller's process id or a negative process group id which has the same absolute value as the caller's process id. In other words, the calling process is the only recipient of SIGURG and SIGIO signals

 BSD 4.3                     UnixWare 7
 The SIOCSPGRP and           The only acceptable
 FIOSETOWN commands for      arguments to ioctl(2) and
 the ioctl(2) system call    fcntl(2) are the caller's
 and the F_SETOWN command    process id or a negative
 for the fcntl(2) system     process group id which
 call take as arguments a    has the same absolute
 positive process id or a    value as the caller's
 negative process group id   process id.  In other
 that identifies the         words, the calling
 intended recipient list     process is the only
 of subsequent SIGURG and    recipient of SIGURG and
 SIGIO signals               SIGIO signals

Local management

BSD 4.3	UnixWare 7
setsockopt can be used at any time during the life of a socket.	Because of the state diagram specified by the Transport Provider Interface (TPI), a setsockopt operation on a transport provider conforming to this specification will fail if issued on a socket that is not bound to a local address. Specifically, if a socket is unbound and setsockopt is used, then the operation will succeed in the AF_INET domain, but will fail in the AF_UNIX domain

 BSD 4.3                     UnixWare 7
 setsockopt can be used at   Because of the state
 any time during the life    diagram specified by the
 of a socket.                Transport Provider
                             Interface (TPI), a
                             setsockopt operation on a
                             transport provider
                             conforming to this
                             specification will fail
                             if issued on a socket
                             that is not bound to a
                             local address.
                             Specifically, if a socket
                             is unbound and setsockopt
                             is used, then the
                             operation will succeed in
                             the AF_INET domain, but
                             will fail in the AF_UNIX
                             domain

Signals

BSD 4.3	UnixWare 7
SIGIO is delivered every time new data is appended to the socket input queue	SIGIO is delivered only when data is appended to a socket queue that was previously empty
A SIGURG is delivered every time new data is anticipated or actually arrives	A SUGURG is delivered only when there is no urgent data already pending

 BSD 4.3                     UnixWare 7
 SIGIO is delivered every    SIGIO is delivered only
 time new data is appended   when data is appended to
 to the socket input queue   a socket queue that was
                             previously empty
 A SIGURG is delivered       A SUGURG is delivered
 every time new data is      only when there is no
 anticipated or actually     urgent data already
 arrives                     pending

Miscellaneous

BSD 4.3	UnixWare 7
If ls -l is executed on a directory that contains a UNIX domain socket, an ``s'' will be printed on the left side of the mode field	If ls -l is executed on a directory that contains a UNIX domain socket, a ``p'' will be printed on the left side of the mode field
Executing ls -F will cause an equals sign (=) to be printed after any filename that represents a UNIX domain socket	Nothing will be printed after a filename that represents a UNIX domain socket

 BSD 4.3                     UnixWare 7
 If ls -l is executed on a   If ls -l is executed on a
 directory that contains a   directory that contains a
 UNIX domain socket, an      UNIX domain socket, a
 ``s'' will be printed on    ``p'' will be printed on
 the left side of the mode   the left side of the mode
 field                       field
 Executing ls -F will        Nothing will be printed
 cause an equals sign (=)    after a filename that
 to be printed after any     represents a UNIX domain
 filename that represents    socket
 a UNIX domain socket

Profiling and libthread

Programs built for profiling (with cc -p) that use libthread will not work correctly.

Java files and file(1)

file(1) does not correctly recognize Java .class files. If you want to have file(1) correctly identify these files, add the following line to /etc/magic:

   0       long    0xbebafeca      uxcore:999      Java Class File

SCOhelp on SCO UnixWare 2.1.3

The SCOhelp window appears slightly different on SCO UnixWare 2.1.3 than on UnixWare 7. Running /usr/X/bin/scohelp on UnixWare 2.1.3, the button bar is the standard Netscape button bar, not the SCO-specific button bar, and the icon at upper right is the Netscape icon, not the SCO icon. All other SCOhelp functionality remains the same on SCO UnixWare 2.1.3 as it is on UnixWare 7.

The SCOhelp server on UnixWare 2.1.3 may fail to start because of a permissions problem with the directory /usr/ns-home/httpd-scohelphttp/logs. The symptom of this failure is that /usr/X/bin/scohelp will start, but will fail to reach the SCOhelp server, returning an error. The workaround is to enter the following commands:

su root
chmod 777 /usr/ns-home/httpd-scohelphttp/logs
/usr/ns-home/httpd-scohelphttp/start

The last command starts the SCOhelp server.

PTFs on SCO UnixWare 2.1.3

When the UW2compat package is installed, it overwrites some of the native dynamic libraries (for example, /usr/lib/libsocket.so.1). If any of these libraries are later overwritten, for example by installing PTF3280, the new version of the library is not compatible with the UDK. This is not an issue on SCO OpenServer, as the OSRcompat package installs its libraries under /udk.

Graphics on SCO UnixWare 2.1.3

After installing the UW2compat package on SCO UnixWare 2.1.3, certain SCO UnixWare desktop administrative commands may fail when invoked by double clicking on their icons in the desktop. This problem can be resolved by restoring a filesystem symbolic link changed by the UW2compat package. Execute the following two commands as root:

rm /usr/lib/X11
ln -s /usr/X/lib /usr/lib/X11

svc_fdset warning

When installing the Release 7.1.1 UW2compat package on UnixWare 2.1.3, you may see several warning: copy relocation size mismatch for symbol svc_fdset messages on system startup. These messages can safely be ignored.