The un*x to OS/2-EMX Porting FAQ

by Alexander Mai

Preface
First I'm going to answer some questions that nobody ever asked...

What Is It?
This is a collection of tips & tricks for porting software from un*x (here the term "un*x" means UNIX and UNIX-like systems) to IBM's OS/2. If you need a more thorough introduction into the business of porting, you should read the draft for the UNIX/POSIX to emx-OS/2 Porting Guide written by Arnd Hanses: it's also available in PDF version.

In general porting requires a broad range of knowledge, so this document also includes general information about coding techniques, un*x & X11 programming, and much more. I assume that the reader is already familiar with OS/2 and has some experience with un*x (usage at least, perhaps even system programming), C programming and EMX/gcc. Otherwise you can't do anything worthwhile here... Sorry!

How To Use This FAQ?
There is a PDF version of this document available. This is the only "official" version since it features a Table of Contents and is complete within a single file. You can even create printouts and extract a plain text version. (try pdftops and pdftotext, which are part of the xpdf distribution.) Remember that the FIND function of your browser/viewer is your friend! Some parts have been put in external documents with "local linkage", i.e. "compiled" ("official") versions already include those. Due to the substantial amount of external links within this FAQ access to the Internet is nearly mandatory.

How To Report Bugs?
In case you are going to correct an error, contribute another entry or fix spelling or grammar, you are welcome to edit this wiki pages.

Copyright, License, Legal Stuff
Contributions to this document came from various people and resources on the net. However to avoid that a single one is neglected in a reference or credits list, all are omitted! Two exceptions are being made for two individuals without their efforts I would not use OS/2 any more and therefore not work on this FAQ: Eberhard Mattes (author of the EMX package including the docs which I frequently cite) and Holger Veit (who ported XFree86 to OS/2). Many hints given in this document came from these two people and the numerous members of their projects' mailing lists.

Alexander Mai give permission to republish this articles under the Creative Commons Attribution-Share Alike 3.0 license to be included on this wiki.

Usage of the tips & procedures described here is totally on your own risk, there is no warranty that they do what you might expect without any unwanted side effects!

General News
Since I do not get much feedback concerning this document it is growing slowly, and also still contains lot of typos and errors. Currently (Q4/2003) the document is quite "stable", I'm busy fixing errors and broken links.

Work is/was ongoing to get many of the hints and workarounds mentioned here into a powerful extension library for EMX (aka "libext"). Take a look and see what's already done! Especially try to look up whether symbols missing in this FAQ are already included there.

Latest Changes
Last Update (I may list some of the previous changes as well):
 * Caught some grammar/spelling errors
 * Updates to the standards document
 * Update many external links
 * Update some of my links and my email address (For checking links I'm using ALC Alexander's Link Checker)

The Golden Rules
There are some famous Golden Rules out there. The first one is quite simple:
 * Check out what's already available!

This is also known as:
 * Do not re-invent the wheel!

Many programmers waste time doing things over and over again, and especially programmers for OS/2 to enjoy this (just look at all those coding the very same kind of utilities over and over again, like file managers, thousands of wget clones, etc). Before you start coding search on [OS/2 software sites] google (or similar search engines) and asked on the EMX, XFree86 OS/2 and related mailing lists.
 * Enhance portability when porting!

Do not produce code which in turn does no longer build on the platform where it comes from. Minimum requirement is to use the ... clause (I'm talking about C/C++ only here). You should however even try to go a step further and use generic catches like: ...
 * 1) ifdef __EMX__
 * 1) endif
 * 1) ifndef HAVE_NON_STANDARD_FEATURE_FOO
 * 1) endif

Tools
To actually port something you need to have EMX and all important related development packages installed properly (in their latest version). To deal with X11 applications you need the XFree86OS/2 package including the development stuff (all older commercial alternatives like IBM's PMX or Hummingbird's Exceed are abandoned/outdated and therefore neglected here. Project Everblue, an X11 to PM mapper for local apps, is still in very early stage of development and of no use so far). At least for the X server itself you have more choices in addition to XFree86OS/2: Also check out libext. In addition to providing libc enhancements it also ships with a set of utilities.
 * Hob X11
 * WeirdX (Java X Server)

gcc 2.8.1, the default C compiler from the current EMX 0.9d distribution, is quite old. However meanwhile there are alternatives. I suggest to install pgcc which you may download from OS/2 software sites or it's homesite. The Pentium optimized GCC offers OS/2 users access to a gcc of the 2.9x series, as opposed to EMX which is at gcc level 2.8.1. PGCC/2 also offers new features: improved code generation for recent processors, a new version of GAS (=GNU assembler) with MMX support, less C++-related bugs, enhanced C++ features/language set and a new, but broken g77 (=GNU Fortran 77 compiler).

Recently there also came up a port (beta status) of gcc 3.x (a more recent version is available from Innotek. Probably won't bring much for plain C programming, but certainly has enhanced support for C++.

There are various tutorials on getting EMX and XFree86 OS/2 to work, please refer to the according link section.

Standard Tools
Except the basic requirements as outlined above you will need additional tools if you want to build packages bigger than the famous "Hello_World.c" example. The following list is probably too long, but except a waste of disk space I see no reason not to install some utilities in advance ;-)

Those tools have to be first in %PATH% before any other [[#nameclash|incompatible versions]! All should be available from OS/2 software sites. Don't forget to put sh.exe into the /bin subdirectory on your working drive to keep many scripts/Makefiles running without changes (this holds for other standard tools as well, like rm, cp, ...).
 * GNU file utils (cp, install, [#ln ln], ls, mkdir, mv, rm)
 * GNU shell utils (expr, pwd, sleep, tee, [#test_exe test])
 * GNU text utils (cat, head, join, sort, tail, uniq)
 * find
 * bash, ash (or other standard-like shell)
 * GNU bison (yacc</tt> replacement)
 * flex (lex</tt> replacement)
 * grep (egrep, fgrep, etc.)
 * [#gzip gzip ("GNU zip")]
 * (GNU) Make
 * patch
 * sed
 * tar
 * uname (unfortunately many versions exist; get one that is compatible with your [#autoconf autoconf] version)
 * uudecode/uuencode

Other useful tools include:
 * diff (to create patches, so called "diffs", for text files only)
 * groff, man (to read un*x man pages)
 * indent (to format source code)

Scripting Languages
un*x offers a variety of script languages like Perl and Tcl/Tk. Some are used for rather simple tasks if the more basic tools (like sed</tt>, awk</tt>, etc.) are no longer sufficient or the suitable command lines become too awful. The OS/2 command shell cmd.exe</tt> can not execute such things directly, so you either have to explicitly call the interpreter (like foo bar.foo</tt>) or rename it to foo.cmd</tt> and add a suitable first line containing extproc foo</tt> like e.g. for Perl scripts: extproc perl -S Perl scripts of this kind have to be in your %PATH%</tt>!

The following table contains several language interpreters which have already been ported to OS/2. The offered links may not necessarily point to the latest version, but you will find out yourself.

Archiver Formats
Here is a list of some common archiver formats and the according tools to extract them (see [OS/2 software sites]).

On un*x it's common to use cumulative suffixes, so hello.tar.gz</tt> refers to a file hello.tar</tt> which is an archive file produced by tar</tt> which has finally been packed by [#gzip gzip</tt>].

Helpful Stuff
Here I present some tools which you don't really need, but which are nice to have around!
 * There are numerous utilities available which translate files from un*x to DOS [#text_formats text format] (and Macintosh if required) and vice versa: dos2unix/unix2dos</tt>, recode</tt>, tr</tt>, <tt>trans</tt>, ...
 * TVFS: Toronto Virtual File System Available from OS/2 software sites. It installs a virtual drive and allows to create links on it. So you can access all your partitions on that single virtual drive and don't need to use drive letters!
 * OS2TRACE (OS/2 API tracer) A tool which can trace down most OS/2 API calls. Not very helpful when starting work on a port ...
 * Get <tt>chk4dlls</tt> somewhere. It lists all DLLs required by an executable/DLL and is an equivalent to the <tt>ldd</tt> utility available on many un*x systems. Note that it doesn't list libraries which are explicitly dynamically loaded during runtime using <tt>DosLoadModule</tt>, <tt>dlopen</tt>, etc.
 * Get some tools to process the various documentation formats. Converters are available for
 * HTML to IPF
 * man to HTML
 * Texinfo to html (new makeinfo)
 * Texinfo to IPF
 * Those converters may be combined in a tool chain, so that a conversion of some lengthy man page to a simple-structured INF document is actually possible.


 * Get CVS (Concurrent Versions System): A tool used for many open source projects on the net. You do not need to actively participate in the development to benefit from CVS: You can then easily get upgrades without downloading the whole package. The given link may carry outdated executables; check out OS/2 software sites.
 * Get <tt>ctags</tt>. It scans the sources and produces a reference list of all symbols together with their precise location. Together with a suitable editor (like NEdit, Emacs, XEmacs, vi and it's clones, ...) this makes a powerful combination: e.g. you select a function's name and a single keystroke will bring you to its definition! The probably best, because most powerful implementation is Exuberant ctags.

Common APIs
Beyond the problems of getting configuration and Makefiles to run properly on OS/2 the most striking problem is obviously to get the missing un*x API calls done on OS/2. In general there are two solutions: The first one sounds like the preferable approach, but on a single-user, non-un*x system it doesn't make much sense to deal in detail with concepts which don't exist on the target platform!
 * map them to native interfaces
 * forget about them

Useful & Dirty Workarounds
These are not necessarily "canonical" and clean approaches, but often they fulfil their purpose very well. This section includes functions, macros and constants. The functions/macro replacements might be "enhanced" by adding the correct number of arguments. Obviously defining a macro/function to either <tt>0</tt> or the appropriate return code upon error relies on the concept that the source was written properly and to some extent handles failures of these APIs properly.

Attention: using these redefinitions will make debugging more complicated since you have to remember all of them! At least I don't have a source code debugger which offers additional support here.
 * 1) define chdir             _chdir2           /* see [#_chdir2 below] */
 * 2) define chown(x,y,z)      (0)
 * 3) define endgrent                          /* is type void */
 * 4) define FNDELAY           O_NONBLOCK
 * 5) define getcwd            _getcwd2          /* see [#_getcwd2 below] */
 * 6) define getdtablesize   (1024)
 * 7) define getgrent        ((group*)NULL)
 * 8) define link(x, y)        (-1)              /* no hard links, [#links below] */
 * 9) define lstat(n, b)       stat(n, b)        /* see [#stat stat], [#links links] */
 * 10) define major(dev)        (0)               /* see [#devicedriverinterfaces below] */
 * 11) define makedev(dev,minr) (0)               /* see [#devicedriverinterfaces below] */
 * 12) define minor(dev)        (0)               /* see [#devicedriverinterfaces below] */
 * 13) define mkfifo(p,m)       (0)               /* see below for [#mkfifo mkfifo] */
 * 14) define mknod(p,m,d)      (0)               /* see [#devicedriverinterfaces below] */
 * 15) define mlock             (-1)              /* see [#mlock below] */
 * 16) define munlock           (-1)              /* see [#mlock below] */
 * 17) define munlockall        (-1)              /* see [#mlock below] */
 * 18) define readlink(x,y,z)   (0)               /* or (-1) and use [#errno errno]? */
 * 19) define setgrent                          /* is of type void */
 * 20) define setpgrp         (0)               /* ? */
 * 21) define sigset(x,y)       signal(x,y)       /* well, almost ... */
 * 22) define strcasecmp        stricmp           /* see [#libext libExt] */
 * 23) define strncasecmp       strnicmp          /* see [#libext libExt] */
 * 24) define symlink(x,y)      (-1)              /* see [#links below] */
 * 25) define sync                              /* check out fsync, etc. */
 * 26) define S_ISLNK(x)        (0)               /* see [#stat below] */
 * 27) define S_IFLNK           (0)               /* see [#stat below] */
 * 28) define S_ISBLK(x)        (0)               /* see [#stat below] */
 * 29) define S_IFBLK           (0)               /* see [#stat below] */
 * 30) define S_ISVTX           (0)               /* see [#stat below] */
 * 31) define usleep(t)  _sleep2(((t)+500)/1000)  /* see [#usleep below] */

APIs that need Special Care
This section features some comments on available APIs which have to be handled with special care and some thoughts on not yet implemented ones.
 * <tt>ecvt</tt>, <tt>fcvt</tt>, <tt>gcvt</tt>:Convert a floating-point number into a string. Not available as far as I know. Try replacing it by <tt>*printf</tt> or even attempt to write your own version. Shouldn't be too hard...
 * <tt>errno</tt>:<tt>errno</tt> is nothing un*x-specific, but an integral part of ANSI/ISO C's error handling. The catch here is that some programmers erroneously <tt>#define errno</tt> to something like <tt>int</tt> or even abuse it as a name for an identifier.
 * Related to <tt>errno</tt> is an important thumb-rule: always compile and link your EMX apps as multi-threaded applications (gcc flag <tt>-Zmt</tt>). This will avoid much trouble.

Replace <tt>exec*</tt> with <tt>spawn*</tt> and <tt>exit</tt> if the parent process waits for the termination of the new process (by calling <tt>wait</tt> or by waiting for <tt>SIGCHLD</tt>). This is required to keep the process ID of the child process. In a forked process, however, you don't have to do this because emx.dll does it for you. Write your own <tt>fcntl</tt> or add code which makes use of an existing <tt>flock*</tt> implementation. Or watch libext. Replace <tt>fork</tt> and <tt>exec*</tt> with <tt>spawn*</tt>. Under OS/2, <tt>fork</tt> is inefficient. You may not care if it's rarely being called, but read the docs for any specific information about the <tt>fork</tt> implementation. Don't forget that <tt>fork</tt> doesn't work in <tt>link386</tt> (<tt>-Zomf</tt>) created executables! Read the section about <tt>XTHREADS</tt> if you are going to use <tt>fork</tt> or threads within an X11 application. Also see <tt>ulimit(3)</tt>, <tt>sysconf(3)</tt>, emxdev: chapter "7 Customizing". Also see <tt>system</tt>. It also fails on open files. Also see <tt>remove</tt>. On un*x you can (re)move open files. On OS/2 you can not and therefore this call might fail (this is a simplified picture; it can also fail on un*x - but won't do that often). A major component here is the file system, and since modern operating systems can deal with many of them, it is not precise to make statements based only on the OS being used. The EMX docs describe what happens if <tt>sigaction</tt> and [#signal <tt>signal</tt>] are used together. Comment out or replace code which is based on non-implemented signals. The EMX (IBM toolkit) docs list all available signals and give further information. But, of course, you need to know what you're going to miss then... By collecting signal types from various operating systems I got a rather long list - see below. The references {OS/2- I BM, E MX, B oth, none} may be incomplete or even wrong. Please check the according docs, or even the headers! <tt>lstat</tt> may be mapped to <tt>stat</tt>, but for compatibility with future enhancements it should have its own wrapper (see libext).
 * <tt>exec*</tt>:See <tt>fork</tt> and the section about <tt>process</tt> handling.
 * <tt>fchmod</tt>:Part of libext.
 * <tt>fcntl</tt>:<tt>F_SETLK</tt> is not supported.
 * <tt>flock</tt>:Check out the native API <tt>DosSetFileLocks</tt>. Also see libext.
 * <tt>fork</tt>:See <tt>exec*</tt> and the section about process handling.
 * <tt>getenv</tt>: See section about environment variables.
 * <tt>getrlimit</tt>:This is not a POSIX.1 function, but should be part of libExt
 * <tt>mlock</tt>, <tt>munlock</tt>, <tt>munlockall</tt>:The <tt>DevHlp*</tt> interfaces (API for device drivers) provide such calls, to mark memory pages as non-swappable. However this is no trivial replacement which could be implemented by inserting a few lines of code.
 * <tt>poll</tt>:A call similar to [#select <tt>select</tt>]. Check out libExt for an emulation using this relationship.
 * <tt>popen</tt>:Ensure to use the "b" in the mode flag when necessary!
 * <tt>random</tt>:The EMX docs claim that <tt>random</tt> is superior to <tt>rand</tt>, so try to use this instead. It's hidden in <tt>libbsd</tt>.
 * <tt>realpath</tt>:libext has an implementation which can be used as a stand-alone version after editing a few lines.
 * <tt>rename</tt>:EMX' <tt>rename</tt> doesn't replace existing targets.
 * <tt>remove</tt>:<tt>remove</tt> fails on open files.
 * <tt>select</tt>: <tt>select</tt> is a common source of portability problems. These may involve: the necessary header files, argument types or some "EMXisms", like the following: <tt>select</tt> will report that <tt>stdin</tt> is "ready", i.e. will return immediately. If you want to trigger on any new input, i.e. keystrokes, you have to change the terminal settings (see <tt>tcsetattr</tt>). A small code snippet should give you the idea:
 * <tt>sigaction</tt>:Check the code which signal model is used and choose the appropriate linker flags (see [#signal <tt>signal</tt>]). Especially check if you need to link with <tt>-Zbsd-signals</tt> while [#x2 XFree86OS/2] (imake; perhaps the docs mention it as well) still tends to use <tt>-Zsysv-signals</tt>.
 * <tt>signal</tt>:By default EMX' signal processing is different from any existing standard (as of SVID or BSD): <tt>SIG_ACK</tt> should be used instead of the signal handler address to re-enable a signal by calling <tt>signal</tt> when the signal handler has been called. This behavior can be changed with the <tt>-Zbsd-signals</tt> and <tt>-Zsysv-signals</tt> linker options of EMX gcc. If you use POSIX.1 functions for signal handling, <tt>SIG_ACK</tt> is not required.
 * <tt>stat</tt>, <tt>fstat</tt>, <tt>lstat</tt>
 * A call to query about an entry in your filesytem. This may be non-portable when it checks for non-existing properties on the new platform, like special file types or even low-level entries within the file system internals (inodes, etc.).

<tt>system</tt> and <tt>popen</tt> do not expand wildcards unless <tt>COMSPEC</tt>/<tt>EMXSHELL</tt> points to a shell which expands wildcards (of course on un*x those calls wouldn't do either - but the shell being called). Read the EMX docs to learn which shell is called by these routines! One may run across code like <tt>system("foo&");</tt> which would try to launch a job in the background with an un*x shell but this won't work with <tt>cmd.exe</tt>. See [#shvscmd "sh vs. cmd.exe"]! Another quite portable approach uses [#select <tt>select</tt>] as shown in the example code below. You must not specify descriptors to monitor, but only a timeout. Check out the docs which resolution actually is provided here and about properties of this call in general (e.g. the effect of signals being raised).
 * <tt>system</tt>:If you are lazy and keep the un*x-like forward slashes in paths arguments for <tt>system</tt> calls may be passed to <tt>cmd.exe</tt> which might not be able to handle them!
 * <tt>tcsetattr</tt>: Any kind of subtle problems with VIO programs may stem from the fact the EMX by default uses a non-standard mode for terminal IO. The first call to <tt>tcsetattr</tt> switches to Posix mode.
 * <tt>unlink</tt>:An obsolete call. Use <tt>remove</tt> instead.
 * <tt>usleep</tt>:The workaround given above (using <tt>_sleep2</tt>) doesn't feature a microsecond resolution; but contrary to its name many implementations on un*x won't do either. More info on timers on OS/2 is available on EDM/2. Also see info about [#itimer g/setitimer].

Ported APIs
This is a collection of known ports of APIs which are more complex than a simple wrapper like: I try to list only "general purpose" stuff that can used in any kind of application. Interfaces for rather special purposes may be collected elsewhere. Some of those and many others are meanwhile part of [#libext libExt]. A work in progress implementation is part of [#libext libExt] and a closed-source one on [OS/2 software sites]. There's an article explaining how to write your own implementation. An implementation comes with the math package <tt>Octave</tt> (on [OS/2 software sites]). Implementations are on [OS/2 software sites], but are not usable in xterms. A Regular Expression is a text string that describes some set of strings. You can use it to search (and afterwards edit/process) for certain patterns. See [regex] for a small summary. Be aware that beyond some common features there are portability problems waiting if you use it heavily. H. Veit has done a port for EMX. Part of [#libext libExt]. A simple mapping to OS/2 calls should be nearly straightforward, as this [priority.zip sample] shows. Also available within [#libext libext]. Implementations come with [#x2 XFree86 OS/2] and [#libext libext] as well. Various ports are available on [OS/2 software sites].
 * 1) define foo bar
 * <tt>dlopen</tt>/<tt>dlfcn</tt> (access to dynamic link libraries) Part of [#libext libExt].
 * <tt>drand48</tt>, <tt>srand48</tt> (random numbers) Part of [#libext libExt]. You can try to write a simple wrapper around <tt>rand</tt> or even better [#random <tt>random</tt>]. Just be aware of the slightly different interface.
 * <tt>gettext</tt> ( N ational L anguage S upport library from GNU) (on [OS/2 software sites] and from H.C. Chu)
 * <tt>mmap</tt>, <tt>munmap</tt>, etc. (mapping files into memory)
 * <tt>mkfifo(3)</tt> (a named-pipe mechanism using the file system)
 * <tt>pthreads</tt> (POSIX threads) (on [OS/2 software sites] and on ftp.everblue.org)
 * (GNU) <tt>readline</tt> (provides simple editing features in an input line on terminals)
 * <tt>regex</tt> ([regular expressions]) (on [OS/2 software sites]; also part of [#libext libext])
 * <tt>rpc</tt> ( R emote P rocedure C all) interfaces are supplied with [#libext libExt].
 * <tt>scandir</tt> (read directory entries)
 * <tt>setitimer</tt>/<tt>getitimer</tt> (timer functions)
 * H. Veit posted some comments and an example how to implement it using a secondary thread.
 * An (incomplete) implementation is part of [#libext libExt].
 * hrtimer.sys (version >= 1.1) with new simple <tt>open</tt>/<tt>read</tt> interface should make timing easy and enable writing an itimer compatible interface. Also you may read this EDM/2 article.
 * <tt>setpriority</tt>, <tt>getpriority</tt> (set/get process priority)
 * <tt>shm</tt> (shared memory between different processes): <tt>shmat</tt>, <tt>shmctl</tt>,<tt>shmdt</tt>, <tt>shmget</tt>
 * <tt>syslog</tt> (send messages to system logger)

un*x Process Stuff
Process handling is a bit different on un*x. However often you won't notice that, since the most frequently used APIs are dealing with starting a process via [#system <tt>system</tt>], [#exec <tt>exec*</tt>], etc. which are available on OS/2 EMX (also see [#fork <tt>fork</tt>]).

The term thread has no unique meaning in the un*x world as opposed to OS/2. Those un*x systems which had already offered something similar to the OS/2 threads concept often developed their own standard for this (see threads-FAQ for more details). Finally pthreads (POSIX threads) settled down as a standard. A wrapper library from this API set to native OS/2 threads exists (see [OS/2 software sites]), but may still be work in progress.

Starting Processes
For purposes similar to those of multi-threading often child processes started via <tt>[#fork|fork]</tt> are being used.

When <tt>fork/exec*</tt> is used to start a subprocess often communication between the parent and child process is done. The most simple way is to redirect <tt>std*</tt> (=<tt>stdin</tt>/<tt>stdout</tt>/<tt>stderr</tt>) using pipes (created by <tt>pipe</tt>). If you migrate the code from <tt>fork/exec* to <tt>spawn*</tt> you have to change this code slightly as well: in the former case pipes are created, then the child process switches it's <tt>std*</tt> to the according ends of the previously created pipes before calling <tt>exec*</tt>. The parent just closes the unused ends of the pipes and keeps those required to communicate with the child. When using <tt>spawn*</tt> you don't have explicit access to the child, but it inherits the pipes/handles given from it's parent. So you have to redirect <tt>std*</tt> of the whole process to the pipes, start the child and fixup <tt>std*</tt> again: An example (no warranty, but it seems to work) with those two alternatives is now given: it will execute the command given as the first argument. First the version using <tt>fork/exec*</tt>: or with [#spawn <tt>spawn*</tt>]: Watch out for open files (socket, ...), better: file handles, being passed to subprocesses: e.g. handles to an open file which are being passed to a spawned child process may prevent the parent from removing that file later on. See <tt>fcloseall</tt> and <tt>fcntl</tt> (-> <tt>FD_CLOEXEC</tt> flag).
 * 1) create backups of the std* handles (-> <tt>dup</tt>)
 * 2) redirect the std* handles (-> <tt>dup2</tt>)
 * 3) start the child (-> <tt>spawn*</tt>)
 * 4) restore std* (-> <tt>dup2</tt>) and <tt>close</tt> unused file handles

Process Properties
Nothing sophisticated from the un*x point of view is taught here, just briefly mention some interesting features from an OS/2 users point of view...
 * Information about the processes on the system may be retrieved using the non-portable [#slash_proc /proc] interface.
 * You may halt a process by sending [#sigstop <tt>SIGSTOP</tt>] and make it continue by sending [#sigcont <tt>SIGCONT</tt>].

un*x Filesystem Stuff
Common "native" un*x filesystems are quite different from those usually found on OS/2 (FAT, HPFS, HPFS386, JFS). Be aware that some really surprising things may show up: interfaces to memory, processes and hardware devices for example!

Let's have a look at some interesting properties: Working on [#libext libExt] showed me that one has to do some search on native OS/2 APIs which can be used for case-sensitive file system stuff. <tt>DosQuery*Info</tt> will succeed on calls for files in a case-insensitive matching! More useful is <tt>DosFindFirst</tt> and it's friends (see Toolkit docs for sample code). Using a replacement for symbolic links which does actually copy and also echoes a warning might be a good, but "dangerous" idea. This approach will not only miss updates on that file but might also cause a program to produce unwanted files: applications sometimes create links for temporary file access. Performing a file duplication will create trash on your harddisk which is not being cleaned up. Often code checks whether a given path is an absolute one by comparing the beginning with "/". So grep for this string! (see <tt>_fullpath</tt> and <tt>_abspath</tt>) may help to support drive letters.
 * File names are case-sensitive!
 * No drive letters are being used!
 * There are standard paths which always exist! Try out <tt>man hier</tt> on your favourite un*x system to get a description of the file system hierarchy being used. In the following overview I may also mention some which are not mandatory, while trying to have all the canonical ones included.
 * root directory. That one is unique due the absence of drive letters.
 * /bin
 * contains system executables
 * /dev
 * virtual interface to devices of all kinds (hardware, logical, ...)
 * /etc
 * configuration data
 * /home
 * directories of each user
 * /opt
 * optional installed stuff
 * /proc
 * Interface to processes on the system. By read and even write access to this virtual file system you have control over all processes. However there's no unique standard for this.
 * /sbin
 * system executables (administration stuff, ...)
 * /tmp
 * a place for temporary data
 * /usr
 * binaries, data for the users
 * /var
 * partition which contains stuff of varying size during run time (logs, mails, data caches, ...)
 * Distributed over a few places on the system you will find the man pages, the standard un*x online help format (a few GNU projects have chosen Texinfo instead nowadays: you shouldn't support this). Several subdirectories contain manuals which usually carry the section number as a suffix (like <tt>foo.2</tt>)
 * Section 1
 * user commands
 * Section 2
 * system calls
 * Section 3
 * libc calls
 * Section 4
 * devices (e.g. hd, sd)
 * Section 5
 * file formats and protocols (e.g. wtmp, /etc/passwd, nfs)
 * Section 6
 * games
 * Section 7
 * conventions, macro packages, etc.
 * Section 8
 * system administration
 * Section n
 * Tcl/Tk, Perl, etc.
 * un*x file systems support links, e.g. you can have multiple references to a single file or directory (see [#tvfs TVFS]). They can be created by the un*x tool <tt>ln</tt>, which is therefore sometimes required by scripts. Symbolic link (also called soft link) are created by <tt>ln -s foo bar</tt>. Hard links are fortunately rarely used in applications and are very hard to fake.
 * un*x file systems support links, e.g. you can have multiple references to a single file or directory (see [#tvfs TVFS]). They can be created by the un*x tool <tt>ln</tt>, which is therefore sometimes required by scripts. Symbolic link (also called soft link) are created by <tt>ln -s foo bar</tt>. Hard links are fortunately rarely used in applications and are very hard to fake.
 * The separator of path components is a slash '/' as opposed to OS/2's backslash '\'. Many OS/2 APIs understand the '/', but <tt>cmd.exe</tt> and most apps do not.
 * Multiple paths (e.g. in environment variables like [#path_env <tt>PATH</tt>]) are separated by a colon ':'.
 * The root dir on an un*x system is "/".
 * Using
 * 1) define getcwd _getcwd2
 * 2) define chdir _chdir2
 * Note that "///abc" is a valid un*x filename. It's equivalent to "/abc". In general multiple '/' characters won't hurt, unlike the situation on OS/2.
 * <tt>chdir ("..")</tt> is a no-op under un*x if the current working directory is the root directory. Under EMX it fails in the root directory.

Miscellaneous Issues
This is a collection of various helpful suggestions which don't fit yet in the other sections.

Various Hints
BTW, in case you got trapped inside vi [a famous un*x editor], feel uncomfortable, but don't know how to get out, here's the magic code: <tt>:q!</tt> Nowadays often a different system called "terminfo" is being used for the very same purpose. You may use the existence of this variable to distinguish between an xterm and an OS/2 textmode session (OS/2 window or fullscreen). <tt>test</tt> is a standard program on un*x, which does apparently nothing - at least if you don't have a closer look at it ... (yes, if you want to know more about the ellipses you should ask "man test" :-) Below's an incomplete(!) list. The "external" and "internal" is meant with respect to <tt>cmd.exe</tt>. <tt> ld -X -r -o darin.o foo1.o foo2.o ... </tt> However you will rarely need to do so. Better create static libraries/archives which collect object code in a much more convenient way. Among the most important formats are archiver types, which are covered elsewhere in this FAQ. unsigned All_Exceptions = EM_INVALID|EM_DENORMAL|EM_ZERODIVIDE|EM_OVERFLOW|EM_UNDERFLOW|EM_INEXACT; _control87(PC_53, MCW_PC);           /* IEEE compatible precision */ _control87(All_Exceptions, MCW_EM);  /* don't mask, i.e. hide exceptions */
 * Static libraries on un*x follow the unique naming convention to carry a leading <tt>lib</tt> prefix, like <tt>libfoo.a</tt>. If you want to link against it however, the right command is <tt>-lfoo</tt>. On EMX unfortunately this prefix has been dropped, i.e. <tt>-lfoo</tt> links against <tt>foo.a</tt> (or <tt>foo.lib</tt>) instead.
 * Shared and dynamic link libraries use the suffix <tt>.so</tt> on most un*x systems (alternatives include <tt>.sl</tt>). There's no need for an import library usually. On un*x/ELF systems shared/dynamic libraries may contain unresolved references, on OS/2 they at least carry a 'link' to the DLL which contains those. This has both advantages and disadvantages, e.g. if you want to access symbols from a dynamically opened library (using [#dlopen <tt>dlopen</tt>]): on OS/2 you will be able to call such a routine in any case, on un*x/ELF you might end up with unresolved symbols!
 * On un*x you can start executables having any name - given the executable file bit is set properly. On OS/2 things are a bit more complicated. You're on the safe side if you adopt the convention used by <tt>cmd.exe</tt>, i.e. you can only execute files with the endings <tt>.com</tt>, <tt>.exe</tt>, <tt>.cmd</tt>, <tt>.bat</tt> (this is the exact search order, BTW!). Most of this trouble is bound to <tt>cmd.exe</tt> and all APIs which may (or may not, see docs) interface with it (including [#popen popen] and [#system system]).
 * For "fast" moving targets like libpng (image format library) or nameclash examples like Xaw, Xaw3d and Xpm don't be shy to link statically ...
 * Check for those "un*xisms" (listed in this FAQ) by using grep or an equivalent command to do a recursive search. Look for all standard paths (see above), and all commands which are mentioned in this introduction.
 * Famous problems are related to the binary/text mode mess on OS/2, especially when using <tt>stdin</tt>/<tt>stdout</tt>. See <tt>_fsetmode</tt>, <tt>fopen</tt>, ... in the EMX docs.
 * Note that on un*x plain text files have a different format than on DOS, OS/2. There are many tools available to convert between them (see [#tools tools section]). This also requires much care on the [#open_calls <tt>*open</tt>] calls.
 * There are some environment variables which are frequently used on un*x, and often also on OS/2. Some un*x apps erroneously assume some of them to always exist, i.e. <tt>getenv</tt> calls to return a non-<tt>NULL</tt> result. Changing this is a valuable bugfix, not a porting related change!
 * EDITOR: Your favorite editor.
 * HOME: Directory which contains data specific for the current user
 * HOSTTYPE: Name of platform
 * LD_LIBRARY_PATH: On a couple of systems used to tell the loader where to look for shared libraries. Equivalent on OS/2 would be <tt>BEGINLIBPATH</tt>
 * LOGNAME: Same as USER (??)
 * MACHTYPE: Description of architecture/OS
 * MAIL: Location of your incoming mailbox
 * OSTYPE: Type of operating system
 * PAGER: Standard tool to page output. Something like "more" or "less"
 * PATH: Same as on OS/2. Except the [#pathsep delimiter character]
 * PRINTER: Default printer. Might be used in conjunction with printing tools like "lp", "lpr"
 * PWD: Current directory
 * SHELL: Standard shell to be used. Often used by Makefiles.
 * TERM: Name of the terminal type currently used (see [#termcap termcap, terminfo]). Make sure that your software runs in an OS/2 window as well as in an xterm!
 * TERMCAP: Used by termcap to find termcap.dat which describes the capabilities of the used terminal device.
 * TMP: Usually not necessary, since all systems have a directory for temporary stuff in <tt>/tmp</tt>. On OS/2 unfortunately one sometimes runs across <tt>TEMP</tt>, <tt>TEMPDIR</tt> and other garbage.
 * TMPDIR: The environment variable which [POSIX] apps should use to determine the temporary directory.
 * USER: Name of user
 * WINDOWID: Id of current X11 window
 * Usually <tt>argv[0]</tt> within <tt>main(int argc, char *argv[])</tt> contains the name of the current executable. This is sometimes checked and used to determine the runtime behavior (e.g. egrep and grep may be the very same binary or xfoo may be the X11 GUI version of some program foo). This check will always be against <tt>"foo"</tt>, so you have to add a check for <tt>foo.exe</tt> as well.
 * A famous FAQ of un*x programming is how to determine the name and absolute path of the current executable. While there is no simple approach, most methods include the usage of [#argv0 <tt>argv[0]</tt>] (e.g. <tt>basename(argv[0])</tt>). On OS/2 the answer is simple: EMX provides the interface <tt>_execname</tt> which is more or less just:
 * Never ever name an executable <tt>test</tt> {<tt>.com, .exe, .cmd, .bat</tt>}!
 * Unfortunately some OS/2 tools (including built-in cmd.exe commands) have their counterparts on un*x with exactly the same name but different semantics/syntax.
 * External commands
 * <tt>find, install, join</tt> (DOS), <tt>more, patch, sort, time, unpack</tt>
 * Internal commands
 * <tt>cd, date, dir, echo, exit, mkdir, rmdir, set</tt>
 * To merge a.out objects you may try something like
 * You will run across many new file formats. Get the file utility for OS/2 which can identify file types using a database of file signatures (mostly some unique header which is a few bytes long). This is a standard utility on un*x.
 * For better conformance to the <tt>IEEE 754</tt> standard you may use:
 * 1) include <float.h>
 * <tt>/dev/random</tt>, a device which should deliver (pseudo) random numbers has no equivalent in the poor random number generators which are distributed with the various libc's on OS/2. For more info on random numbers visit the /dev/random Support Page and The pLab Project Home Page. And the local information about the [#random <tt>random</tt>] and [#rand48 <tt>*rand48</tt>] interfaces.

sh vs. cmd.exe
While many want to abandon the "good old", but brain-dead <tt>cmd.exe</tt> there are many reasons to keep it, mainly for compatibility to existing solutions. So one may have to migrate a couple of shell commands and even complete simple scripts. To get this done on OS/2 you have to do it "manually" in your code since <tt>cmd.exe</tt> won't do it for you. However be aware that even people on OS/2 may use shells which already expand (4os2? or an un*xish shell). This shouldn't hurt at first glance, but may end up with a substantial number of command line arguments passed to your application!
 * Remember the <tt>cmd.exe</tt>/<tt>sh</tt> operators (which are surprisingly often identical ...):
 * All standard un*x shells expand wildcard characters:
 * <tt>*</tt>
 * match every set of characters
 * <tt>?</tt>
 * match a single character.

EMX (and even IBM's toolsets) has it's own routine to help you getting that job done: int main (int argc, char *argv[]) { _wildcard (&argc, &argv); /* ... the program ... */ } foo "file name with blanks.txt" set EQUATION=E=mc2 does not work. A work-around is to use a REXX wrapper: /* Ok, use REXX */ call Value "EQUATION", "E=MC2", "OS2ENVIRONMENT" <tt> gzip -d foo.tar.gz | tar xf - | sort | bzip2 -dc >bar.bz2 </tt> may produce an error message like <tt> SYS0008: There is not enough memory available to process this command. </tt> Then try grouping commands together as [#group_cmds shown above].
 * 1) include <stdlib.h>
 * To avoid expansion of wildcard characters one may quote command line arguments within a "" pair. <tt>cmd.exe</tt> has a slightly different concept here. Anyway for both trivial examples include specifying file names with embedded blanks, e.g.
 * <tt>cmd.exe</tt> is unable to accept environment variables with include some special characters like '='. So trying to specify
 * Sometimes long command pipes or those which have to transfer large amounts of data fail on <tt>cmd.exe</tt>, e.g.

In & Out
This is a section about general Input/Output related topics. Since that issues are rather complex I can't even nearly fill/discuss all subsections...

Device Driver Interfaces
Under un*x device drivers frequently feature interfaces which show up in the file system. This is at first glance something new to OS/2 users, but actually they already know similar interfaces (<tt>\PIPE\</tt>). Since this mechanism to access arbitrary devices has no trivial mapping to OS/2 capabilities, not all [#workarounds related interfaces] can be ported: the code needs a major rewrite.

Printing
Printing on un*x is quite different from OS/2: no sophisticated system interfaces exist (read: may exist but are rarely used and not necessarily portable) so all applications have to do this on their own. Existing no-cost solutions (since only those are - if at all - of interest to OS/2 users in this context) include: As a common denominator usually PostScript-capable printer is supposed to be available to the system. Also a set of standard utilities to submit/manipulate jobs for this device is required. If you're lucky enough to have a PostScript printer on your OS/2 system you may use the <tt>lpr</tt> and <tt>lpd</tt> tools (shipped with Warp 4) to access the PostScript printer queues from the command line. More on this topic can be found in the separate document which however covers "only" printing from non-PM applications.
 * the "new" X11 printing interface (-> <tt>libXp</tt>, which in turn may be used by libs such as [#motif M*tif]). This is not supported by [#x2 XFree86OS/2] 3.x, though.
 * clever tools which trigger a conversion of "arbitrary" input data to Postscript, like a2ps.

Sound
Portable audio doesn't seem to be available across operating system borders. For many un*x flavours there's the Open Sound System (OSS), which brings digital audio (also MIDI) with an "open" interface.

There's a <tt>/dev/audio</tt> emulation available from OS/2 software sites (devaudio*.zip). Given this version one might imagine to have the current implementation enhanced by additional features.

Miscellaneous I/O
With respect to general hardware access it's hard to find a portable standard at all here. Here's a short list of docs/projects which deal with portable I/O:
 * serial IO

EMX & OS/2 Specifics
Here I address peculiarities and problems that the EMX runtime and OS/2 system present to the programmer. Most are taken from "emxlib.doc: 5.1 Porting Unix applications" and from emxdev.doc: 5 Hints for porting Unix programs to emx", but I'm also adding entries here myself.

From EMX docs
Though the following entries are more or less excerpts from the EMX docs I've started to modify them and therefore do no longer claim that it's actually the same what you can read in the EMX distributions! Usage of the <tt>-Zbin-files</tt> (gcc) linker flag is in general a bad idea since it too often breaks handling of text files. <tt>system ("whatever >/dev/null");</tt> won't work as the standard OS/2 interpreter (<tt>cmd.exe</tt>g</tt>) doesn't recognize "<tt>/dev/null</tt>" (see <tt>system</tt>). <tt>setvbuf (stdout, NULL, _IOLBF, BUFSIZ);</tt> and to use <tt>fflush(stdout);</tt> if you need the output immediately (flushing is required only after displaying prompting texts before reading input or displaying progress reports that don't end with a newline character). <tt>GDB</tt> output has been made much faster by using line buffering. Always use the standard interface, i.e. POSIX.1 <tt>termios</tt> in new code!
 * Socket handles are not inherited across <tt>exec*</tt> and <tt>spawn*</tt>. A process created by <tt>fork</tt> inherits the socket handles of its parent process, though.
 * The size of messages is restricted to 32767 bytes (this is a limitation of IBM TCP/IP for OS/2).
 * By default sockets are in binary mode. Use <tt>setmode</tt> to switch to text mode. Text mode applies to <tt>read</tt> and <tt>write</tt>, only. <tt>recv</tt> and <tt>send</tt> always use binary mode.
 * The functions <tt>recvmsg</tt>, <tt>sendmsg</tt>, and <tt>socketpair</tt> are not implemented.
 * Change all <tt>open</tt>, <tt>fopen</tt>, <tt>fdopen</tt> and <tt>freopen</tt> calls to use <tt>O_BINARY</tt> or <tt>"b"</tt>, respectively, for binary files (see "text formats"). If a file contains both binary and textual data, read the file in binary mode and do the conversion yourself.
 * Though <tt>fseek</tt> and <tt>ftell</tt> now work on text files, the offsets are different from what Unix programs expect. You may have to open the files in binary mode and ignore carriage returns (this has been done in <tt>GDB</tt>).
 * Programs reading a.out files should be changed to call <tt>_seek_hdr</tt> or <tt>_fseek_hdr</tt> before reading the header to support .exe files. More changes are usually required.
 * The null device is called <tt>/dev/null</tt> under Unix. The <tt>__open</tt> system call translates the filenames <tt>/dev/null</tt> and <tt>/dev/tty</tt> (lower case, with slashes) to <tt>nul</tt> and <tt>con</tt>, respectively. However,
 * Do not use the <tt>PTRACE_TRACEME</tt> request of <tt>ptrace</tt>: use <tt>P_DEBUG</tt> instead when starting the process with <tt>spawn*</tt>.
 * The shell isn't called <tt>/bin/sh</tt>. Use <tt>system</tt>.
 * Printing single characters is inefficient. A solution is to use
 * Note that <tt>VEOF</tt> != <tt>VMIN</tt> and <tt>VEOL</tt> != <tt>VTIME</tt>. Programs which use <tt>VEOF</tt> and <tt>VEOL</tt> to access <tt>VMIN</tt> and <tt>VTIME</tt>, respectively, should be changed to use <tt>VMIN</tt> and <tt>VTIME</tt>. emx uses separate fields for <tt>VEOF</tt>, <tt>VEOL</tt>, <tt>VMIN</tt> and <tt>VTIME</tt>.
 * To use termio, you have to reset the <tt>IDEFAULT</tt>g</tt> bit of <tt>c_lflag</tt>. This does not apply to termios.

From other sources
Do not use <tt>_read_kbd</tt>! This breaks your code in [#keyinxterm xterms] and in addition it is non-portable! touch __shd.c gcc -dM -E %1 %2 %3 %4 %5 %6 %7 %8 %9 __shd.c rm __shd.c
 * When using <tt>spawn*</tt>g</tt> take care of unwanted effects when [#filehandles file handles] are inherited. Also check out the related problem of [#spawnsocket socket] handles!
 * Use termio or termios or read the keyboard with <tt>_read_kbd</tt> if you don't want to get input line by line.
 * To figure out which preprocessor <tt>#define</tt>s are in effect you can use the example batch script (for cmd.exe) below. Two un*x utils (<tt>touch</tt>, <tt>rm</tt>) are required, but you may easily replace them by native OS/2 calls. Advantage of the given version is obviously that you can use it almost literally on many un*x system and it can handle a big number of additional commandline arguments like compiler flags: "-ansi" is a candidate here.
 * Sometimes projects link explicitly against <tt>libc</tt> (<tt>-lc</tt>). This in 95% useless and sometimes will trigger problems even on un*x. On EMX the situation is even worse, the required C runtime is distributed in more than a single library, consult the EMX docs on that issue.
 * The un*x math library (<tt>libm</tt>) is often specified in Makefiles among the linker flags. Using EMX you don't need this (the functions are already among the standard C libs). But to keep the linker happy with those Makefiles a dummy math library exists, which is linked if <tt>-lm</tt> is used. The enhanced math library from [#libext libext] is available in a stand-alone library.
 * <tt>ranlib</tt> (a tool to prepare static libraries for usage by linker) is not available and not necessary with EMX anyway. You may use the <tt>s</tt> command of ar instead, like <tt>ar s foo.a</tt> (or just forget about it completely ...).
 * A famous issue on OS/2 programming is the task to allocate more than 32MB of memory for a single object. Yes, of course this is possible, but when using EMX it may not be straight-forward. Check out the <tt>_uflags</tt> call. Note that it interferes with [#fork <tt>fork</tt>].

Configuration Stuff
Various build mechanisms are used in the un*x world: simple/complex/nested Makefiles, crazy batch files, autoconf, Imakefiles, ... Anyway you should get all available un*x tools which are already ported, many of them being from GNU. More details can be found at the description of [#autotools autoconf] and in the [#tools tools section].

Makefiles
In my opinion Makefiles are the best build mechanism. Up to obscure internal rules of the Make utils it is a clean and obvious approach and also it's very easy to learn. for i in $(subdirs); do (cd $i; $(MAKE) bar); done to for %i in ($(subdirs)) do (cd %i && $(MAKE) -f Makefile.os2 & cd ..) If the Makfile contains sh commands, you may have to add a missing <tt>SHELL=/bin/sh</tt> on your own. Below is an example of some sophisticated feature of GNUMake that <tt>x11make</tt> does not properly handle while some GNU make 3.76 from OS/2 software sites does: VERSION := $(shell grep -e "^VERSION=" $(VFILE) | sed -e "s/VERSION=//")
 * Get a version of GNU make from [Ported Software Sites|OS/2 software sites]. Watch out for embedded shell commands!
 * If you use XFree86-OS/2 there's a <tt>make.cmd</tt> in your <tt>%PATH%</tt> which is helpful to some extent and presents a problem in some other cases. You may call the underlying binary executable by <tt>x11make.exe</tt>. This batch file defines <tt>SHELL=""</tt> and may do other things (just currently it doesn't ...).
 * GNU make offers many useful features which are beyond the common standard (as defined by POSIX.1, ... ?) for <tt>make</tt> on un*x. However since GNU make is very portable and widely available you may try to use them anyway.
 * To learn about converting sh-syntax to cmd.exe-syntax refer to the section which discusses sh vs. cmd.exe issues. Here's just another example, you may convert
 * Figure out which shell is used, especially if the <tt>SHELL</tt> variable is set explicitly!
 * Have a couple of different make versions around!

Batch Files
The term "batch file" here refers to scripts written for an un*x-like shell (see below). Those shells scan the first line of an executable batch file for the interpreter being required (similar to <tt>EXTPROC</tt> which cmd.exe recognizes) while you can also write some commands for the current shell without that header: Some comments on shell scripts: <tt>set -x</tt>
 * 1) ! /bin/sh
 * Try to run them in an un*x-like shell like <tt>ash</tt>, <tt>bash</tt>, <tt>csh</tt>, <tt>ksh</tt>, <tt>tcsh</tt>, <tt>zsh</tt>, ...
 * To debug shell scripts add this line near the beginning (or the interesting section)
 * Other script language interpreters may be found in [#scriptlangs according section] of this FAQ.

auto* tools
GNU autoconf is a tool (set) which produces configuration and Makefiles to build software in different environments. Given the software is properly adapted and autoconf has support for that platform it will then automatically detect the available tools and programming environment (libraries, headers, etc.).

autoconf
Source distributions of packages usually include a created "config.h" header which specifies the locally available features via preprocessor clauses like For more details on this read the short introduction into the auto* business written by Ian Lance Taylor. Some OS/2-specific comments are helpful. An important requirement is probably experience with that stuff on a real un*x-platform, otherwise you'll struggle way too often.

<tt>autoconf && configure && make</tt> The default autoconf port lacks a "-Zexe" for plain EMX and such things, but that shouldn't be real problems. Of course you can also run the "configure" script unmodified, which will at least run through if it's old and simple enough. You may have to fix the resulting files (e.g. config.h and Makefile manually). If configure just stops at some questionable code fragment you might also just drop that stuff. Often even a run with lots of wrong results produces a better set of output files than a non-expert might create...
 * In case there's a <tt>configure.in</tt> file available you should try one of the existing autoconf ports:
 * Version 2.13 (1.4)
 * Version 2.5x (1.5) from OS/2 software sites
 * Often it's used in packages which also make use of automake and libtool.
 * Check out the [list of standard tools].
 * Ensure that the supplied <tt>configure.in</tt> is compatible to the current autoconf port (e.g. look for <tt>AC_PREREQ</tt> and no fancy libtool stuff (especially dynamic or shared libraries) is being done. Then things should be as trivial as
 * If you don't have the <tt>configure.in</tt> source try out the "convert_configure" or "configure-fixer" scripts from Ilya Zakharevich.

automake
automake is a companion to [#autoconf autoconf] and OS/2 ports are available at the same places usually. A project might start from an even simpler set of input files which will then be processed by automake and autoconf to end up with a configure script which will finally create all Makefiles and configuration files. automake itself creates a Makefile.in out of a Makefile.am. In general all files <tt>configure</tt> should process have to carry the .in postfix.

libtool
GNU libtool is being used to build libraries. Usually only for shared libs, since producing static ones should be quite simple (and standard).
 * There's an OS/2 port of version 1.2d (see [#hcchu below]).
 * Doesn't work for DLLs on OS/2, or at least not in a real useful way.
 * Maintaining DLLs which entry points are explicitly using ordinals is a pain. There's a tool (currently part of the LessTif for OS/2 distribution) which does the job for you: mkdef.cmd, a powerful REXX program, reads in an old .def file, remembers all entries and their corresponding ordinals and while keeping them it assigns unique new ones. The list of the currently available symbols may be automatically created by <tt>emxexp</tt>.
 * <tt>link386</tt> has a (documented) commandline flag <tt>/OLD</tt> which should somehow correspond to a feature of automatic matching ordinals with an older existing DLL, but I never got it to work.
 * There are other tools which do help the user to create a DLL without having to write a linker definition file manually.
 * <tt>dllar.cmd</tt> from [#pgcc <tt>pgcc</tt>]
 * "dynamic" script packages from I. Zakharevich (look for "dynamic*.zip" archives)

Imakefile
imake and related tools like xmkmf ship with X11 distributions. It is used for X11 software only. Run <tt>xmkmf</tt> (<tt>mxmkmf</tt> exists for LessTif systems; the OS/2 port lacks this so far) to create a Makefile from an input <tt>Imakefile</tt>. <tt>xmkmf make Makefiles make</tt> is required for larger projects.
 * Often a sequence like
 * Unfortunately an Imakefile may also contain non-portable shell commands.
 * To address configuration issues that can't be resolved by using the "knowledge base" of the X11 installation the user sometimes has to adjust configuration files which are then included by the Imakefile.
 * Watch out for explicit settings of system-dependent variables like <tt>CFLAGS</tt>, <tt>CXXFLAGS</tt>, a common mistake by software authors!

X11 Specifics
In general you don't need to make changes specific related to the [#x2 XFree86OS/2] implementation of the X11 standard. It is very close to the level which is supplied for un*x platforms. In turn XFree86 is based on the official releases from the OpenGroup and therefore conforming to the standards. Similar to the [#motif M*tif] case, here the official implementation is the standard ...

In fact most problems arising are already covered in the XFree86OS/2 FAQ and on the related [#mailinglists mailinglist].
 * How to get a single key pressed in an xterm?: This is a real FAQ for [#un*x un*x programming].
 * By default many terminals are in a mode which blocks until RETURN is pressed. The major task to be done is therefore setting the terminal in the correct mode. Fortunately there is a standard interface for this defined within [Standards.html#posix POSIX.1].
 * You should read about [#tcsetattr <tt>tcsetattr</tt>] and check out the sample code which I provide for the [#select <tt>select</tt>] call or have a look at some other sample code.


 * How to work around the non-working <tt>SIGWINCH</tt>?: Have a look at this [termsize library]
 * Is X11 multi-threaded?:[XFree86OS/2] does not support the X11 threading concept called <tt>XTHREADS</tt>. This is not a critical limitation since any valid software has to check (and can easily do) whether this feature is enabled or not. Here's a suitable autoconf macro:
 * It is important to perform all X11 calls from a single thread. Otherwise you may get errors like:

<tt> Xlib: unexpected async reply </tt>.
 * This may require quite some efforts if you have an application which uses multiple threads to emulate some missing timer APIs like [#itimer <tt>g/setitimer</tt>].


 * How to debug an X11 application?:See debugging.html for some general comments. Remember that an X11 application isn't running straight through some <tt>main</tt> routine (except for the beginning or end perhaps), but most of the time it stays in a loop which waits for events like keyboard or mouse actions. Then it calls the appropriate routines ("callbacks") which have been installed to react upon them.


 * How to resolve X errors?:If the app <tt>foo</tt> uses the XIntrinsics (usually linked against [#libxt Xt.dll]) run <tt>foo -sync</tt> inside a debugger and [debugging_os2.html#breakonexit set a breakpoint on <tt>exit</tt>]. Also check out the [debugging.html#xerrors according section] in debugging.html.


 * What if an (X11) app fails to link due to unresolved symbols?:If the linking process fails, this probably means you didn't specify some library, or the required libraries aren't available on your system (this is nothing X11 specific). Also you could have missed to specify an object file. Error messages indicating this problem contain long lists of undefined symbols, most of which have a name with an identical prefix, such as <tt>Xm</tt>. The leading underscore which gets added to all symbols (at least using EMX/gcc) is omitted here for brevity. In the following I list some prefixes and the related linker command to select the required library. A concise description is given as well as an entry which tells you from where to get the library. The entries are sorted by the name of the library, not by the exported symbols.

You may locate symbols which aren't listed here by running <tt>emxexp</tt> on the libraries in %X11ROOT%/XFree86/lib. Obviously the library name tends to be the same cryptic letter combination as the prefix you are looking for. Libraries marked as C++ -bindings have mangled names, i.e. a complex mixture between the plain name of the function/variable/method and its signature (if it's a routine). Use <tt>nm -C foo.o</tt> to see the demangled names.The order in which you have to link these libs is partially fixed: -lUil -lMrm -lXm -lXt -lXmu -lXp -lXext -lXpm -lSM -lICE -lX11 Requirement is that a library which depends on another one is specified before that other one. Of course not all of these libraries are always necessary, but in some cases even more libraries may be required. The socket library (<tt>-lsocket</tt>) is another candidate here. It provides e.g. <tt>gethostname</tt> or <tt>connect</tt>.


 * How to link an X11 application statically?
 * If you want to debug an X11 application and need to deal with X Errors (see debugging.html and debugging_os2.html) you may consider to link the X11 libraries statically as well (though you don't gain much here).

To do so you have to get the static libraries package from the [#x2 official distribution]. Then replace all link requests -lfoo by -lfoo_s. Switching one library from dynamic to static linkage might force you to do the same with others as well! However you may try to link only those statically which are required to satisfy the linker (see example below). In addition new libraries might now be required, e.g. <tt>-lsocket</tt> (see [#xapplink "What if an (X11) app fails to link due to unresolved symbols?"]). A sample commandline would be: gcc -Zmtd -Zbsd-signals -o bar.exe bar.o -lXt_s -lX11_s -lsocket

Be warned though: statically linked X11 apps might cause problems once you update your X/2 system. My instructions here could also be incomplete: I got some strange errors which I could not explain so far ... And don't forget that applications for [#x2 XFree86OS/2] demand to be linked via <tt>-Zmtd</tt>.

Actually I should better say "stand-alone, dualmode" application, therefore see also [#xappstatic "How to link an X11 application statically?"] Many X11 apps feature a commandline interface as well, e.g. to issue a help message upon <tt>-help</tt>. This is (almost) never found within OS/2 PM applications since this didn't fit into IBM's shortminded concept of separating PM and VIO apps unfortunately. This can be done by "morphing" the application. You may try out the sample code provided by Darren Abbott.
 * How to create a "dualmode" application?
 * When building a dualmode application (command line and X11 app in a single executable) you may wish to link to the X11 libraries statically. This way you can distribute a binary to people which don't have [#x2 XFree86OS/2] installed.


 * How to distinguish between VIO, PM, X11 session?!
 * Sometimes one need to check programmatically whether a process is running in a VIO, PM or X11 session. The latter is not recognized by native OS/2 or EMX APIs, so we need to look for some hacks... If some parent process was started from within the X11 session the environment variable [#windowid WINDOWID] is set to some integer value. A more thorough check seems to be difficult; even if one would climb up the process hierarchy it's not obvious what to check for: e.g. a search for "xterm" wouldn't catch alternatives like "rxvt". One would have to check whether the current process (or one of its parents) belongs to a window on the current display?!The even more fundamental check whether X11 itself is available (and running) can be based on that code snippet:

Display *disp=XOpenDisplay(NULL); which should assign a non-NULL value to <tt>disp</tt>. If you want to make that binary running without X11 to be installed add those two steps before: dlopen( %X11ROOT%/XFree86/lib/X11.dll ) /* pseudeo code only! */ and perform that check. However in general it's better to link the whole application [#xappstatic statically against the X11 libs] then.
 * 1) include <X11/Xlib.h>
 * check for %X11ROOT%
 * try to dynamically load libX11:


 * Which GUI toolkits/widget sets are available?
 * Dozens of them exist in the un*x world and many of them have been ported already (check out sites.html). However there are none of the commercial ones available, i.e. those which don't offer sources for free. Mostly used in the X11 world is the industry standard Motif (developed & owned by the OpenGroup; core part of it is [#libxm libXm]). Meanwhile you may use the OpenMotif release on a few platforms, but not on OS/2 (you may however obtain a source license for big money and try to compile for XFree86 OS/2). Instead you may download LessTif from www.lesstif.org: it is a free (LGPL'ed) available clone of Motif. It is source compatible, so you can just rebuild sources written for Motif.

External Resources
This is mainly a link section. Except references to documents which I've written I refer to OS/2-related information sources.

Related Documents
Some related documents which I have written and still work on. Most of them were initially just excerpts from this porting FAQ. Then I got the idea that they might be useful for other purposes as well ...
 * There is an extraneous tutorial from me about basic debugging issues available, which is not operating system specific.
 * Some system-specific issues might be worthwhile to mention for OS/2-EMX however. See Debugging on OS/2.
 * Information about printing from non-PM applications is collected within Printing.
 * A short summary about Regular Expressions.
 * Sites carrying ported and native OS/2 software are listed in Ported Software Sites.

Online Resources
There are many big, useless link lists out there. I try to collect real helpful ones, i.e. canonical resources as well as sites which have real unique offers. libext or p*six/2 project offers a libc which makes porting very simple! The IBM DeveloperToolbox (former "Developers Connection"=DevCon) offers among other valuable stuff the toolkit docs including xpg4ref.inf, the reference for the portable C API. Electronic developer magazine for OS/2 Timur Tabi's site offers many useful links and information those famous guys with a kinky definition of "free software". Home of the virulent license types GPL (AKA "General Public Virus") and LGPL Better avoid it if you can!
 * General Info, Standards
 * Check out Standards.html for lots of valuable references!
 * OS/2 Software, Ports
 * libext project
 * XFree86 OS/2: Free X11 Server and libraries
 * Many site carrying ports are listed on sites.html
 * OS/2-specific Informations
 * Installing XFree86OS/2 and an "UNIXish environment" from C. Hennecke
 * "Getting Started with EMX/GCC" (an EDM/2 article)
 * DevCon
 * EDM/2
 * TT's OS/2 Programming Page
 * The OS/2 API Project (discontinued and incomplete, but free!)
 * IBM Redbooks online
 * IBM pubs online
 * Misc
 * GNU project
 * Info about the "OpenSource" term.
 * Introduction to various license types
 * Mailing lists
 * emx (emx@xfreeos2.dyndns.org)
 * XFree86 OS/2 (xfreeos2@xfreeos2.dyndns.org)
 * POSIX/2, libExt project (posix2@xfreeos2.dyndns.org)