[$Header: /cvsroot/posix2/posix2/libext/FAQ,v 1.9 2000/05/31 09:12:05 veit Exp $]


	Frequently Asked Questions (FAQ) to the P/2 - libExt project



				"Steve Jobs said two years ago that X is 
				brain-damaged and it will be gone in
				two years.  He was half right."
							 (Dennis Ritchie)

More Info:

	http://posix2.sourceforge.net/


Q:
0.)
>I am keeping an eye on 2 libs and one app that I will surely port and that
>will surely use libEXt. 

A:
Great! Please link statically for now, until we finally announce the 'freeze'
of existing interfaces and entry points; later versions are likely not to be
binary compatible. Nevertheless, 'make dll' should produce a stripped dll. 
Feel free to use it for whatever *internal* tests you can imagine.

Q:
1.)
>I got libExt. Can I replace all EMX headers with libExt one? 

A:
Yes. They should be backwards compatible. Report any problems.
To put it more precisely: They should be backwards _source_ compatible. 

If you use our headers but _not_ use our library, well, you know, a lot of 
exciting side effects are to be expected...  ;-)

Q:
2.)
>If yes, are you sure all will work ok?

A:
I'm absolutely (100%) sure and I will fully guarantee this, provided
you have already paid the full price for the libExt
XXL-Super-Hyper-Software-Development-Kit. Price list on request.
(PS.: Will e-mail with a 10Mbyte price list bounce?)

3.)
>I successfully downloaded CVS of libExt and was surprised not to
> see EMX in it at all.

We cannot merge libext and emx on the long run because of different
licenses. We will use a BSD-style license. 
Because of this we must cleanly separate both libraries. 

	In general, our goal is full compatibility with 4.4 BSD, 
to reuse as much 4.4 BSD Net/2 Release code as possible and to write
our own kernel interfaces from scratch. So please consider remaining
similarities to emx in _our_ code as being "fast'n dirty hacks" for
testing purposes, only.

4.)
>But why can't we integrate libExt into EMX.

Because EMX is property of Eberhard Mattes and he has repeatedly
rejected - for several years now and not without good reasons - to
follow a route like our's. If he does not change his mind we will
respect his decision and must and _will_ leave emx untouched. This will
give you a choice: You can use the library interface _you_ need.

To make it absolutely clear: Our intention of seamless Un*x integration
on top of the OS/2 kernel is not any better or worse than emx's;
it's only different! And it is incompatible. This does _not_ mean that 
you cannot (and at this moment you even must do that) link against ANSI 
streams and other utility functions in the opaque emx dll's. It means: 

	We will not mix up the sources!

5.)
>I really do not want to mess with functions from different places and 
>want to keep them in 1 place ?

Yes, keep them in 1 place: libExt. Help us to write a complete
and BSD compatible implementation. If you then specify 'gcc -lext' (_our_
library before emx libs) on the linker command line, all stat references
will be seamlessly resolved by _our_ library. Application programmers
even won't notice what is actually happening; they will only notice
that their Linux/SunOS/BSD sources now compile and run correctly. The
relevant emx functions in the dll will not be linked in. Please
remember: First specify, first resolve. And what has already been
resolved cannot be re-resolved.

6.) Assembler generation questions:

6.a)
>I get this when trying to compile the i387math module...
>
>i387math.s: Assembler messages: [...]
          ^^ Should not happen, we use a large 'S' here. 
Cf.:

GCC(1)                      GNU Tools                      GCC(1)


       .s    Assembler source; assemble
       .S    Assembler source; preprocess, assemble
       .h    Preprocessor file; not usually named on command line


  file.s 
            Assembler code. 

  file.S 
            Assembler code which must be preprocessed. 

  other 
            An object file to be fed straight into linking. Any file
name with no recognized suffix is treated this way.   
  
  You can specify the input language explicitly with the '-x' option:  


  -x language 
            Specify explicitly the language for the following input
files (rather than letting the compiler choose a default based 
            on the file name suffix).  This option applies to all
following input files until the next '-x' option.  Possible values 
            for language are: 
            
            c  objective-c  c++
            c-header  cpp-output  c++-cpp-output
            assembler  assembler-with-cpp


The Makefile has this rule:

  .S.o:
	  $(CC) $(CFLAGS) -c $< -o $@

Probably your make is broken and does mess up the rules. Try instead:

  %.o:	%.S
	  $(CC) $(CFLAGS) -c $< -o $@

or use x11make.exe from XFree86/2.

6.b)
>I use 'as.exe' from bintools of pgcc to make it understand MMX commands, but
>it is not working well: see example
>
>  .global __imlib_get_cpuid
>     .type __imlib_get_cpuid,@function
>
>  __imlib_get_cpuid:
>     pushl %ebx
>     .......
>
>produces in .obj file _imlib_get_cpuid with one underscore! What to do?

Looks like you did not obey to the a.out symbol generation convention. On any box
you can find out how symbol names are generated for use by your linker, just compile
a sample: Look into the generated asm-output, search for underscores. Maybe you 
might want to write a wrapper in C and include inline assembler instructions only 
for those machine instructions that are unknown to pgcc/gcc. Examples in:

	'libm/mathx.c.' 

In this case you can employ typed variables and better ANSI type checking. 
Moreover, the compiler takes care for you of optimizing and instruction 
scheduling; do not forget to double-check the generated asm output, though. Or
you can alternatively fix the asm code and prepend an additional underscore.

7.) Timing questions:

> - What is HRTIMER.SYS? Part of Warp Server? Or is it available somewhere?

Search Hobbes for hrtimr11.zip. It is a  device driver implementing a high
resolution timer. The author granted us the right to use, copy and modify his 
sources for our project and asks for giving him due credits in the docs.
See libext/test/usleep.c for detailed explanations.

8.) Patches:
> I want to submit patches. How to proceed.

Read docs/CodeRules.txt first! Then, first fix defective ASCII with fixtxt. 

In toplevel (CVSROOT) directory:

1) Run make distclean! 

2) cvs -z4 update

3) cvs -z4 diff -udw >diff.out


9.) Docs:
> I don't have a written documentation of the XYZ standard?! Heeelp!

Well, unfortunately often standard documentations are sold - probably to 
prevent the community from using them ;-)
We collect a growing list of links to "free" (i.e. no cost, might require 
registration) programming&standard references:

  posix2/libext/Standards.html

A copy of this document should be on our website on SF.

10.) Additions of other libraries:
>Many libs use libJAIATIDNK wrapper for work - it can be easily added to 
>libEXT !?

Hmm, JAIATIDNK (Just Another Interesting Acronym That I Do Not Know ;-!> 
Forgive my unpordonable ingnorance about all those 'You cannot live without 
this latest and greatest library of the hour' acronyms. Can someone explain, 
please?

In general, we will integrate all libraries that are present as default libraries 
in recent *BSD systems, especially OpenBSD (US-based *BSD systems often lack many 
of them because of export restrictions). 
I (aka the current maintainer) am willing to provide anything as an option 
that people actually need (unsupported by me, of course) and are willing to 
support, if you send me a nice (aka human readable) module/header.
This is strictly for convenience and to have a central place to look for 
libraries, so that people do not need to hunt around the net for all 
(incompatible) versions of all (mutually incompatible) bits and peaces...

11.)
>Heeelp, BLURB.3bsd is unreadable. I want to learn about your fine system, but 
>while using Linux your manpage is unreadable.

Use a real operating system (*BSD) that does not imitate SYSV. The BSD authors
would put it this way:

  "The -man switch is stupid SYSV brain-damage, obsoleted since 4.0BSD! 
  In new code use only the superior Berkeley 'doc' macros. If you absolutely must 
  stay compatible with one-eyed fanatics of broken brain-damage, use the -mandoc 
  switch."


=========================================================



	FAQ's to libm
	-------------

>I just tried out to figure out what's going wrong with multi-standard
>support in libm and found the following:
>- dtestvec.exe apparently checks for correctness according to IEEE ??
>	At least test what I suppose due to the result with
>		-D_IEEE_LIBM.
>- libm itselft is (was?) compiled with -D_MULTI_LIBM -D_POSIX_MODE which
>	means that the code will go through some extra instructions to
>	produce a result and an exception value which is claimed to be
>	according to POSIX standard, but different from IEEE results.
>  (e.g. if nan is returned by "acos", it checks if the argument had
>	absolute value > 1 and if so, it sets the result to zero,
>	exception type to DOMAIN, exception name to "acos" and in the
>	POSIX case errno to EDOM; the result zero is obviously fully
>	intentional, so I assume, it's posixly correct.)

As it seems, Posix avoids NAN (for VAX compatibility??), returns zero
and sets errno. Let's try to discuss individual unexpected results:

1.)
	acos (2.0000000000000000e+00) = 0.0000000000000000e+00
	    should be nan
	acos (-2.0000000000000000e+00) = 0.0000000000000000e+00
	    should be nan
	asin (2.0000000000000000e+00) = 0.0000000000000000e+00
	    should be nan
	asin (-2.0000000000000000e+00) = 0.0000000000000000e+00
	    should be nan

This is intentional: Avoid NAN, return 0 and set errno.

2.) (both for IEEE and POSIX version)
	tanh (-0.0000000000000000e+00) = 0.0000000000000000e+00
	    should be -0.0000000000000000e+00

Conformance module k_standard.c does not contain a special case. I think this is a bug; as s_tanh.c uses GET_HIGH_WORD(jx,x) macro, the bug may be in the macro or in the C file: With a fast look at it I do not see how the sign of the argument is preserved. Is this intentional?


3.)
	log (-1.0000000000000000e+00) = -inf
	    should be nan
	log10 (-1.0000000000000000e+00) = -inf
	    should be nan
Like (1.).


4.) (both for IEEE and POSIX version)
	log1p (-0.0000000000000000e+00) = 0.0000000000000000e+00
	    should be -0.0000000000000000e+00

I think, a bug in the S file: Not sign-preserving, much like (2.).

5.)
	gamma (-1.0000000000000000e+00) = inf
	    should be nan
	gamma (0.0000000000000000e+00) = inf
	    should be nan
	gamma (-inf) = inf
	    should be nan

Test is wrong here, remove test; cf. my previous mail.


6.)
	atan2 (-0.0000000000000000e+00, 0.0000000000000000e+00) =
	0.0000000000000000e+00
	    should be -0.0000000000000000e+00

	atan2 (0.0000000000000000e+00, -0.0000000000000000e+00) =
	0.0000000000000000e+00
	    should be 3.1415926535897931e+00

	atan2 (-0.0000000000000000e+00, -0.0000000000000000e+00) =
	0.0000000000000000e+00
	    should be -3.1415926535897931e+00

Like (1.).


7.)
	pow (0.0000000000000000e+00, -3.0000000000000000e+00) = -inf
	    should be inf
	pow (0.0000000000000000e+00, -5.0000000000000000e-01) = -inf
	    should be inf
	pow (-0.0000000000000000e+00, -5.0000000000000000e-01) = -inf
	    should be inf

Intentional behaviour for standard conformance. Yet rather strange...


So in summary: Bugs are in (2.) and (4.). The rest is strange but conforming.

We should avoid 

tanh (-0.0000000000000000e+00) = 0.0000000000000000e+00
    should be -0.0000000000000000e+00
log1p (-0.0000000000000000e+00) = 0.0000000000000000e+00
    should be -0.0000000000000000e+00

