= kLIBC FAQ =

----
[[PageOutline(2-6,,inline)]]

----

== The linker ==


=== Do you know that ilink 5 screws up when there are many exports? === 


Yes, I do know. Possible workarounds are: 
  1. Use a different linker, for instance ilink from vac308 or the a.out linker.
  1. Reduce the number of exported symbols. For instance use {{{__declspec(dllexport)}}} or set up a generic export filter of some kind.
  1. Split up the .dll so the new dlls end up with an acceptable number of exports.
  1. Help me implement LX and OMF backends for binutils (and the gnu linker).


=== ILink : fatal error LNK1002: unrecognized option (ocache:0x02000000) ===

You're using the VAC308 ilink, but emxomfld thinks it's VAC365 or ilink 5 and feeds it the {{{/ocache}}} option. There are two soultions:
  1. Use ilink 5.
  2. {{{SET EMXOMFLD_TYPE=VAC308}}}


== Calling conventions ==

=== What's the story with the underscore? ===

The extra underscore can be said to be inherited from the microsoft compilers, which makes it go back to the early DOS days. [If somebody has a complete history, please update/let me know. bird]

The OS/2 (and Windows) C ABI (application binary interface) dicates that the {{{__cdecl}}} calling convention shall decorate functions with one leading underscore. To my knowledge most of the windows and OS/2 compilers with the exception of EMX does this. The OS/2 specific {{{_System}}} calling convention is basically the same as {{{__cdecl}}} except that there is no decoration of the function name (there is also the bit about AL containing the parameter count, but nobody really implements this). There are a number of other calling convetions on OS/2, {{{_Optlink}}} (the IBM compilers), watcom register call (todo: name), {{{__stdcall}}} (microsoft windows api), borland probably has one, etc...

The EMX ports of gcc didn't implement {{{__cdecl}}} according to the OS/2 ABI, they simply omitted the leading underscore. This made {{{_System}}} and {{{__cdecl}}} identical for all practical purposes. With gcc using {{{__cdecl}}} as default, this meant that {{{_System}}} could be completely ignored.

Now, starting with GCC 3.2.2 it became important that GCC could work together with other compilers (for building certain Odin32 dlls and other stuff). So, the OS/2 port was changed to decorate the all names according to the {{{__cdecl}}} ABI just like the microsoft compilers. Unfortunatly, breaks compatibility with EMX, but then GCC 3.2.2 comes with it's own, EMX derived, libc.


=== How to declare a function so it won't get an underscore? ===
{{{
void _System hello_world(void);
}}}

If you want to compile this with EMX, add {{{-D_System}}} to you compiler commandline or {{{#define _System}}} to some header.


=== How to declare a variable so it won't get an underscore? ===

Not really possible. You might use something like {{{int my_variable asm("my_variable");}}} but that's hardly generic or portable. (todo: check if it's really 'asm' and not some {{{__attribute__}}}.)



== End-Of-Line - O_BINARY / O_TEXT ==


=== What's the story with the different EOL markers? ===

See what wikipedia has to say on the subject of newline: http://en.wikipedia.org/wiki/Newline


=== Why doesn't read(fd, buf, size_of_file) return size_of_file? ===

Because you have opened the file in text mode and read will convert {{{\r\n}}} sequences to {{{\n}}}. An example (test this):
{{{
    FILE *pFile = fopen("myfile.txt", "w");
    fprintf(pFile, "hello\n");
    fclose(pFile);

    struct stat st;
    stat("myfile.txt", &st);
    printf("st_size is %d.\n", st.st_size);

    void *buf = alloca(st.st_size);
    int fd = open("myfile.txt", O_RDONLY);
    ssize_t rc = read(fd, buf, st.st_size);
    if (rc != st.st_size)
        printf("read returned %zd.\n", rc);
    close(fd);
}}}
This should produce the output
{{{
st_size is 7.
read returned 6.
}}}
You will get the same result if you use {{{fseek(SEEK_END); ftell();}}} or {{{lseek(SEEK_END); tell();}}} to find the file size.

There are two ways of fixing the problem. It depends on whether you wish to have the eol conversion or not. 
If this is really a binary file and you certainly don't want to have eol conversion, add O_BINARY to the flags open flags ("b" in the case of fopen). 
If this is a text file and you wish for eol conversion, you must alter the check for read success. TODO: suggest good ways of doing this.