The XFree86/OS2 FAQ

• Some URLs: 
• http://www.x11.org/ (this has a rather large bibliography) 
• http://www.xfree86.org/ 
• http://set.gmd.de/~veit/os2/xf86os2.html (XFree86/OS2) 
• Newsgroups: 
• comp.windows.x.* (X11 specific things) 
• comp.os.os2.programmer.* (OS/2 specific things) 
• Mailing list (for XFree86/OS2): see Q 1.7 

• you have to pay for them 
• they are based on the PM desktop 

 Also some facilities might not be present, such as background images, PEX, XIE, DGA, or other X extensions. 

Please avoid cross-posting to other groups, this won't speed up answers, and usually annoys people who pay for their news and have broken software which does not recognize crossposts. 

Many people who have been using the last version(s) of XFree86/OS2 will also listen in the mentioned newsgroups, and will be helpful. 

Please choose a meaningful subject, preferably containing the word "XFree86" or "XFreeOS2" in the line. 

1. a valid email contact. In the past, some contact through the WWW pages failed because of wrong configured WWW readers. Some homebrew PPP link which is up approx 1 hour per week is likely not a valid email address. 
2. The relevant hardware configuration (CPU, RAM, video card, monitor, OS, fixpacks) 
3. The error.log file 
4. The xf86log.os2 file 
5. The popuplog.os2 file 
6. The XF86Config file 
7. If suspected, the CONFIG.SYS file 
8. A description of the effect and how it can be reproduced 
9. Information whether this also occurs on other systems with same or different hardware, or Linux, etc. 
10. 100000 US$ (...no, just kidding...) 

• To produce a error.log file, go to some directory and execute from a PM window (CMD.EXE) the following command:

startx 2>error.log
Type it exactly this way, don't add spaces or comments. 
• The xf86log.os2 file will be *sometimes* produced in the root directory of your boot partition. In many cases, it is not present or empty. 
• The popuplog.os2 file resides, if it exists, in the root directory of the boot partition. If you find one, delete it, and create the error.log file again (see above). If there is a new one then, it is from the current run. 
• The XF86Config file is the /XFree86/lib/X11/XF86Config file produced by the xf86config utility. 

• If there is a simple answer, including the well-known RTFM, I reply rather fast, during work hours in Germany (CET) maybe even within minutes. 
• You might very likely wait for very long for mails of the Q 1.8 style. 
• If the problem is complicated, I try to forward this problem to people, e.g. the XFree86 developers or even IBM (if this turns out to be some OS/2 bug), and you probably won't hear from me again for very long. 
• Occasionally, I am out of office, and won't read mail. 
• Probably you won't believe it, but there is REAL LIFE(tm), and I have recently found out about its existance. 
• Occasionally, I lose or forget some mail. This could be related to the fact/problem that I am human, not a mail robot. 

• Niall Mansfield, The X Window System - A User's Guide, Addison Wesley,

or 
• The Definite Guides to the X Windows System, Volume Three, X Window System User's Guide, O'Reilly&Associates 

Your mileage on book recommendations may vary, of course, and there is much more stuff in the shelves. 

• XF-version#-content.zip for distribution files 
• X-version#-content.zip if version# would make it longer than 8.3 chars 
• S-version#-content.zipfor "small X servers" which don't have the seldomly used extensions XIE and PEX in them. 

The /XFree86/lib/X11/doc/README file lists supported video hardware. 

                BUY HARDWARE AFTER CHECKING THAT IT WILL SUIT YOUR NEEDS!
                BOYCOTT MANUFACTURERS THAT WON'T GIVE YOU WHAT YOU WANT!

• test hardware is required 
• documentation is needed 
• a volunteer to do the job is needed 

If you want to work on support for a new server actively, please send a request to XFree86@XFree86.org. But be warned in advance: the emphasis is on active participation, and the core people there carefully check if this is really the case, and not one of the numerous requests to get access to the source code (which typically remain unanswered). 

 You have probably read my EDM/2 article "32 bit I/O at Warp Speed" and have installed the FASTIO.SYS driver. The XF86SUP.SYS driver is a superset of this. Remove FASTIO.SYS from your CONFIG.SYS; you won't need it anymore, XF86SUP.SYS will take over all the functions. 

For Warp 3, fixpack 5 contains some recommended fixes. You might consider to install at least this one. There are reports that FP22 is somehow broken, and that FP26 works well, and FP32 is regarded as great. Your mileage may vary. 

For Warp 4, I have tested no FP, FP1, and FP5, FP8, FP9 and FP11, with no visible difference on XFree86. Since these FPs actually change something (and be it just that they break IBM1S506.ADD or IBMIDECD.FLT usually), you might want or don't want to install one of these. 

And yes: fixpacks are cumulative, i.e. a FP with a higher number contains all fixes of the ones with a lower number. 

You can still use xmodmap as well. 

Part of the problem is that clients started in xinitrc.cmd remain under PM control (i.e. its parent is PM, not xinit, as intended), so when X goes down, it doesn't destroy these clients with it. 

Currently the following methods appear to work: pop up the window list (CTRL-ESC) and close the xinitrc.cmd process. If this does not help, close the other remaining X processes in the same way. Alternatively to the close function of the window list, a process kill program (killem, killit, pmkill, etc) or Watchcat should also work. 

1. Exclude the driver XF86SUP.SYS from CONFIG.SYS, and if you like, also the environment variables that were set during installation. Attention: some of them are necessary for proper TCP/IP networking. 
2. Remove the complete tree \XFree86. 

 The ugly thing with any dynamic IP address is obvious with any software which wants to connect *to* your host. Normally, it is *you* who initiates a connection, e.g. with your WWW browser, and this is no problem. The problem is that remote hosts must be able to find your host (resp. your X server). There is no solution, except to assign the DISPLAY variable as dynamic as the IP address. Needs some tweaking of the startxx.cmd script.

 Try to get a static IP address if possible (if necessary, by begging, bribing, or threatening :-)). 

You should run the PMX server on display :0 and the XFree86 one on display :1 (attention: the startx.cmd has this coded to :0 by default). 

Meanwhile, there are special ports of tcsh and ksh which work in an xterm. 

 You can use the EWS utility EXEMAP.EXE to check if these DLLs are linked in.

 Note: the existance of these DLLs does not mean that the program does not work at all, actually EMX.DLL could call KBD API functions but usually does not in the X11 environment. However, certain unexpected effects may occur in an xterm. I'll try to find a workaround for this in the future, but don't count on this. 

You may try out x3270, available from the ported software WWW page (Q 1.15). 

You might check DXPC from the ported software page, ported by Ron van Iwaarden. This is a public packet compression server/client which should give some relief. 

• CRSR<-, CTRL-B: back one char 
• CRSR->, CTRL-F: forward one char 
• CTRL-H, DEL<-: Delete char to the left 
• CTRL-U: clear entire line buffer 
• CTRL-A: cursor to beginning of line 
• CTRL-E: cursor to end of line 
• CTRL-K: kill to end of line 
• CTRL-V: Quote next char, i.e. next keystroke is added to the buffer without interpretation 
• DELETE (keypad): Delete char on cursor position 
• INSERT: Toggle insert mode 
• CRSR ^, CRSR v: retrieve last command (history feature) 

• It searches for man pages in the directories specified in the MANPATH environment variable. This is a semicolon (;) separated list of directories of the structure

drive:/dir/.../man1
/man2
/man3
...
What you have to specify actually is the directory path except the last level, such as in SET MANPATH=d:/XFree86/man;Q:/EMX/man;F:/other/mans/man
Not all chapters man1-mann need to be existent. If you have installed XF32man.zip, you can see the structure under \XFree86\man. 
• Preformatted pages are compressed with gzip (.gz extension). Such preformatted pages are produced from unformatted pages with

tbl file.man | eqn | groff -man | gzip >file.gz
• Unformatted pages are not compressed and have the extension corresponding to the chapter number of the man directory, e.g. in \XFree86\man\man1 this would be 1, like grep.1. 
• If you have unformatted man pages, you must have the groff utilities installed (groff, eqn, tbl). 
• If you use only preformatted manpages, you need cat and gzip. Both utilities are available from hobbes.nmsu.edu. 

1. Your application uses special OpenWindows fonts. OW can use Type3 fonts and special bitmap fonts, which are unsupported by XFree86 servers. The only workaround is to set up or have your Sun sysop set up a font server (xfs) and add it to the FontPath in your XF86Config file. 
2. The second reason is described in Q 3.39. 

 If you don't have any source code, it won't work. The application complains that the XFree86 server does not support the OpenGL 3D extension. 

 In practice, this support is broken since version 3.2, and never tested in XFree86/OS2. A future release will offer this and other combinations again. 

        #ifdef COLOR
        *customization: -color
        #endif

 Ask whether someone is already porting it, e.g. in the newsgroup comp.os.os2.programmer.porting; if not, then do it yourself. Applications don't appear magically, unless someone really ports them. So why not YOU? 

 The problem then is that I cannot give out the code or put it on an FTP server, not even diffs. I don't have the time nor resources to open a business that sells licenses of the libraries to anyone interested and collect the royalties to the Motif Open Software Consortium. Initially, I thought I would simply make binaries, encrypt them and put them on a FTP server. People or institutions that give me a proof of a valid Motif license would then get the decryption key. I was told, however, that this scheme would be juridically suspicious. 

So, this may be a point where companies, for instance, who are already involved in the Motif business could jump in, and offer the missing link. I have neither interest nor time to manage this. 

There is also the LessTif project to build a free Motif clone. Look at the ported software page (Q 1.15). 

If you aren't concerned either: Yes, commercial applications are allowed and welcome. THIS IS YOUR CHANCE! 

• Use the Imakefile and do not try to handcraft or patch a Makefile. Things will go wrong! 
• Read about the macros ProgramTargetName() and LibraryTargetName() and use them in the Imakefile, rather than hacking .exe and .lib names. The above will work, hacking won't. 
• Compile and link everything with the -Zmtd option, the libraries are multithreaded by intention. 
• Use #ifdef OS2Architecture in an Imakefile to specify an OS/2 dependent part. 
• In source or header files, exclusively use #ifdef __EMX__ for OS/2 EMX specific parts. Don't use other symbols, such as "OS2", "__OS2__", "i386", "__GNUC__", or "__32BIT__". Use only #ifdef, #else, #endif, not #elif, as some other compilers don't support this. 
• If you think there is a bug in the provided X11 include files, you are doing something wrong. 
• Many Imakefiles silently assume they are running under Unix, and therefore have program and library names hardcoded in. Use the LibraryTargetName and ProgramTargetName macros to wrap libs and programs, such as in

EXTRA_LIBRARIES = ../Xpmlib/LibraryTargetName(Xpm)
PROGRAMS = ProgramTargetName(xterm) ProgramTargetName(resize)

• Unix does not have drive letters, so a file (resources, fonts, config, etc.) path starts with '/' normally. XFree86 is located in a tree below %X11ROOT%\XFree86\... To prepend the X11ROOT part to a file path, a special function named __XOS2RedirRoot exists which you are supposed to use in these cases rather than an insane own solution. The prototype of this function is: const char* __XOS2RedirRoot(const char* pathname); 
• Don't reinvent the wheel concerning environment variables. Use the ones that are described in the installation file README.OS2, rather than invent yet another variable name for USERs, HOME directories, TMP directories, etc. 
• Although the rule was broken multiple times already in XFree86/OS2, try to make your filenames comply with the 8.3 file name convention, so that users may relocate them to elsewhere. 
• The libraries are multithreaded EMX libs for certain reasons. This causes a few side effects, particularly if fork() is involved. I got fork running in several situations, but it is no fun. Try to rewrite this code where possible (well-meant advice). 
• Many software from Unix assumes that lines have '\n' as a line delimiter. The X applications are linked with \emx\lib\binmode.o. Don't change this, some code relies on this. Rather rewrite the code to accept \r\n as a line delimiter. 
• You may use all Dos* API functions, as long as they don't conflict with EMX somehow (e.g. _beginthread vs. DosCreateThread). Stay away from Kbd*, Mou*, Vio* calls - none of those will do what you expect, but you can severely influence the operation of the X11 system. 
• If you must do port I/O, use the functions from xf86sup.sys for this; this driver is there anyway, so why not take advantage of it? Common precautions for directly accessing hardware apply. 
• Code that relies on Unix security, job control, tty/pty handling, needs major rewriting. In most cases, it is easier to make a separate file for OS/2 rather than clutter the original one with #ifdef clauses. 
• X11 executables must be linked as WINDOWCOMPAT and EXETYPE OS2 (the only exceptions are the X servers and xinit). 
• XFree86/OS2 by default does not have sh, so rewrite Unix shell scripts to REXX cmd files. Don't rely on others to install sh or other tools just for you. 
• If you want to contribute other software, please follow these guidelines for making your distribution zip file: 
• Use OS/2 zip for packing, even if some foobar packer gives you 1 % better compression. Don't use tar and gzip. 
• If you use an Imakefile (which is common practice with X apps), set the X11ROOT variable to another letter than the one where you have your X11 tree. This makes it easier for you to combine all necessary files into a distribution. 
• Use exactly the same tree structure as XFree86/OS2 is using Don't reinvent wheels and install to /usr/local/bin or similar, or rely on users to edit CONFIG.SYS to change the PATH or LIBPATH. 
• The last section means that the directories in your archive should be rooted to /XFree86. 
• Put sources in a separate archive, not in the binary release, and root this archive at /XFree86/src/PACKAGENAME, e.g. /XFree86/src/xfoo-0.42. 
• The reason for all that is that I want to engage Software Installer in the future to improve the installation procedure. This should integrate all contribution packages as well. I'll reject non-conforming contributions without warning. 

Note that you still need some secondary literature on special features of Imakefile rules. A recommended book on Imakefiles is available from O'Reilly&Assoc publ (Using imake). Ask in your bookstore. 

For own software to run under XFree86, this won't apply, of course. 

The MIT copyright under which XFree86 is distributed is less restrictive anyway. 

Another source of problems are files which contain CR-LF as a line delimiter. We have to fix this the hard way unfortunately; for well-defined reasons programs are linked with \emx\lib\binmode.o. You might try to convert offending files to the Unix convention with the program \XFree86\lib\X11\etc\fixcrlf.exe.
fixcrlf filename
This will convert the file in place. Never apply this program to executables, fontfiles or other binaries. We need a bug report for the program anyway.