The World of Computer Software

home *** CD-ROM | disk | FTP | other *** search

/ The World of Computer Software / World_Of_Computer_Software-02-387-Vol-3of3.iso / e / emxdev8f.zip / EMXDEV.DOC < prev next >

Wrap

Text File | 1993-01-03 | 397KB | 9,622 lines

=============================================================================== emxdev.doc emx 0.8f APPLICATION DEVELOPER'S GUIDE 03-Jan-1993 =============================================================================== Copyright (c) 1990-1993 by Eberhard Mattes Table of Contents ================= 1 Introduction 2 Managing bound .exe files with emxbind 2.1 Creating an .exe file 2.2 Changing the type of an .exe file 2.3 Extracting the a.out file from a bound .exe file 2.4 Displaying and changing the emx options of a bound .exe file 2.5 Updating emx.exe in a bound .exe file 2.6 Stripping the symbol table from a bound .exe file 2.7 Module definition files 3 Using emx options 4 More emx utilities 4.1 updt 4.2 emximp 4.3 emxomf 4.4 emxomfld 4.5 emxomfar 4.6 emxcat 4.7 emxrev 5 Library functions and system calls 5.1 Preliminary notes 5.2 Overview 5.3 Library reference: functions 5.4 Library reference: variables 5.5 termio 5.6 System calls 6 Hints for porting Unix programs to emx 7 Creating OS/2 programs 7.1 Calling OS/2 API functions 7.2 Importing from OS/2 DLLs 7.3 Creating Presentation Manager applications using ld and emxbind 7.4 Creating Presentation Manager applications using emxomf and LINK386 7.5 Creating dynamic link libraries 7.5.1 Creating dynamic link libraries that use emxlibc.dll 7.5.2 Creating dynamic link libraries that don't use emxlibc.dll 7.6 Using the DLL version of the C library 7.7 Creating multi-threaded programs 7.8 Calling 16-bit functions 8 Customizing 8.1 Increasing the heap size 8.2 Increasing the stack size 8.3 Increasing the number of files 9 Debugger (DOS) 10 Executable file format 11 Known problems 1 Introduction ============== This document describes how to use emx utilities to create programs running under emx and how to create OS/2 programs with the emx utilities. The GNU utilities are described in gnudev.doc. There are three methods for creating executable files: (E1) using ld and emxbind (E2) using emxomf, emxomfld and LINK386, the program will use the emx.dll dynamic link library for performing system calls (E3) using emxomf, emxomfld and LINK386, the program will be linked with a system call library The assembler creates a Unix-style a.out object file (.o file). When using method (E1), .o files created by the assembler are linked by a Unix-style linker with Unix-style libraries (.a files) to create a Unix-style a.out file. Then, emxbind is used to turn this file into an .exe file that can be executed under both OS/2 2.0 and DOS. Using method (E1) enables core dumps and fork(). Moreover, programs created with method (E1) can be debugged using GDB, the GNU debugger. Programs created using method (E1) use emx (emx.dll under OS/2, emx.exe under DOS) for system calls. When using method (E2), the .o files created by the assembler are converted to Object Module Formats files (.obj files). These files are linked with the OS/2 linker LINK386. The libraries are .LIB files. emxomfld is a front end to LINK386 which converts the ld command line to a LINK386 command line. Programs created with method (E2) cannot create core dumps, cannot call fork() and cannot be debugged with GDB. Method (E2) works only under OS/2 2.0 and creates programs that work only under OS/2 2.0. Files created with method (E2) are usually smaller. The emx.dll dynamic link library is used for system calls. The -Zomf option of GCC selects method (E2). When using method (E3), the program won't call the emx.dll dynamic link library. A system call library (emx emulator) is linked to the program. The system call library maps system calls to OS/2 API calls. Only a subset of the emx system calls is available with method (E3). For instance, termio is not available. Functions which are not available or are limited with method (E3) are marked [*] in the library reference. Use a module definition file and the STACKSIZE statement to set the stack size. The default stack size is 8192 bytes, which is too small. Note that the command line arguments and the complete environment are copied to the stack on startup. Method | (E1) | (E2) | (E3) -------------------------------+--------------+-------------+------------- GCC options | | -Zomf | -Zomf -Zsys Object file format | a.out | OMF | OMF Object file name extension | .o | .obj | .obj Library file name extension | .a | .lib | .lib Executable file format | LX & a.out | LX | LX Object files converted by | N/A | emxomf | emxomf Executable files converted by | emxbind | N/A | N/A Linker | ld | LINK386 | LINK386 Librarian | ar | LIB | LIB Minimal set of libraries | libc libgcc | libc libgcc | libc libgcc | | libemx1 | libsys libos2 | | libemx2 | Methods for importing | (I1) (I2) | (I3) | (I3) Can link with OMF libraries | NO (note 1) | NO (note 1) | YES Debugger | GDB | N/A | N/A emx.dll required at run time | YES | YES | NO Library support | +++ | ++ | + `collect' required for C++ | NO | NO | NO Core dumps | YES | NO | NO Size overhead | big | none | (note 2) Programs run under DOS | YES | NO | NO Can create DLLs | YES (note 3) | YES | YES EMXOPT environment variable | YES | YES | NO -Zmt supported | YES | YES | NO Use -lemxio for port I/O | NO (note 4) | YES | YES Note 1: import libraries can be used after conversion with emximp Note 2: depends on the set of syscalls used by the program Note 3: not recommended Note 4: -lemxio is required when using -Zmt. Without -Zmt, libemxio should not be used Programs created with method (E1) or (E2) can use emxlibc.dll, a dynamic link library containing the C library. Use the -Zmt option to make a program that uses emxlibc.dll. Programs which use emxlibc.dll don't run under DOS. Both emxlibc.dll and emx.dll are required. There are two advantages of using emxlibc.dll: - thread-safe C library functions (well, ...) - _beginthread() and _endthread() are available - reduced executable size - programs don't have to be re-linked when the C library is changed. Use -Zomf -Zmt to minimize the size of the executable file. Please note that you should change the name of emxlibc.dll if you want to distribute your program with a modified version of that dynamic link library. For using floating point arithmetic, a coprocessor is required (80387 or i486). All exceptions are masked, that is, computation continues with +#INF, -#INF, +#NAN or -#NAN after an error. A 387 coprocessor is not required for doing floating point arithmetic under OS/2 2.0. Under DOS, a 387 coprocessor (or i486) is required for doing floating point arithmetic. Under OS/2, a core dump file will be written if a protection violation (exception 0xc0000005) occurs. You can later debug the program using the .exe file and the core dump file. The name of the core dump file is `core', and it is put into the current working directory. Use the -c emx option to suppress writing a core dump file. When linking a program using method (E2) or (E3), core dump files are not written by that program. OS/2 and DOS support both the forward slash and the backslash for separating directories. Unix utilities usually treat backslash specially, therefore you should use forward slash. This document uses forward slash unless an OS/2 or DOS command is shown (cmd.exe and command.com use backslashes). File name extensions (the list is incomplete): a Unix-style library (archive) bat DOS batch file c C source file cc C++ source file cmd OS/2 batch file def Module definition file doc Documentation file dll Dynamic link library dvi Device independent file, created by TeX exe Executable file h C include file (header file) i<digits> Split GNU info file imp emx import list file inf GNU info file (use `info' for reading) lib OMF library m Objective C source file map Map file, created by LINK386 o Object file (Unix style, a.out) obj Object file (OMF) rc Resource script file res Binary resource file s Assembler source file tex TeX (or texinfo) source file Directories: /emx Main directory, contains no files /emx/bin Executable files and batch files /emx/dll OS/2 DLL files /emx/doc Documentation /emx/include C header files /emx/lib Libraries /emx/new New .exe files created by the makebin batch file /emx/test Test programs /emx/tmp Temporary directory for building OMF libraries 2 Managing bound .exe files with emxbind ======================================== 2.1 Creating an .exe file ------------------------- emxbind binds emx.exe and an emx executable file into one executable file which runs both under OS/2 2.0 (6.167 or later) and DOS. Usage: emxbind [-b] [<emxbind_options>] [-c[<core_file>]] [-d<def_file>] [-r<res_file>] [-h<heap_size>] [-k<stack_size> <emx>[.exe] <input_file> [<output_file>[.exe]] [<emx_options>] emxbind [-b] [<emxbind_options>] [-c[<core_file>]] [-d<def_file>] [-r<res_file>] [-h<heap_size>] <-k<stack_size> <input_file> [<emx_options>] -b (optional): this emxbind command means `bind' and is the default. If you want to use the -s option (strip symbol table), -b cannot be omitted, that is, you should type -bs (otherwise, emxbind would perform the -s command described below) -c[<core_file>] combine an a.out file and a core dump file created for that a.out file into one program. This can be used to create a a program with preloaded data. Note that the .exe file will waste lots of disk space. If you don't enter <core_file>, core is used -d[<def_file>] read the module definition file <def_file>. The default extension is `def'. If <def_file> is omitted, <input_file> with `def' extension is used instead. See below for details on module definition files -k<stack_size> set the size of the stack object of the executable file. The stack size set by this option is used under OS/2. The stack size is given in KB, the default is 8192 (8 MB). The stack size must be between 20 and 524288 (512 MB). The stack size should not be less than 32 KB. To let emx.dll allocate and manage a stack object, use -k0 (this is not recommended; stack probes are required). You should not use -k without -b, as a -k command is planned for a future version of emxbind -r<res_file> put resources from binary resource file <res_file> (no default extension) into the .exe file. Use `rc -r' to create the binary resource file. Do not use rc to put the resources into the .exe file -h<heap_size> set heap size. This is the space available for allocation by malloc(). The heap size is specified in megabytes (1 to 512). The default value is 32 <emxbind_options>: -q don't display title -v display more information: list resources, display path name of emxl.exe unless given on command line, display the statements in the module definition file that are ignored -f set application type to `full screen'. See also -e command -p set application type to `Presentation Manager'. See also -e command -s strip symbols (requires -b). You can also strip the symbol table before creating the .exe file by calling strip.exe or after creating the .exe file by using the -s emxbind command -w set application type to `windowed' (default). See also -e command Only one of the options -f, -p and -w can be used. If none of these options is used, the application type is taken from the NAME statement of the module definition file (-d option). If no module definition file is used, -w is the default. <emx> (optional if no output file is given): path name of emx (default extension: `exe'), that is emx.exe, emxd.exe or emxl.exe. Using emxl is recommended. If this argument is omitted (in this case the <output_file> argument must be omitted as well), the file name from the STUB statement of the module definition file is used. The file is sought in the directories listed in the EMXPATH and PATH environment variables. If no module definition file is used or if the STUB statement isn't used, the file /emx/bin/emxl.exe will be used. If that file doesn't exist, emxl.exe will be sought in the directories listed in the EMXPATH and PATH environment variables. If that fails, emxl.exe is sought in the current working directory. If the -v option is given, the path name of emxl.exe will be displayed unless a STUB statement is present <input_file>: path name of the a.out file to be read. This name sans directory part and extension is also used as module name for the .exe file <output_file> (optional): path name of the bound executable file. The default extension is `exe' unless the LIBRARY statement is used in the module definition file. If LIBRARY is used in the module definition file (that is, when you're creating a dynamic link library), the default extension is `dll'. If the <output_file> parameter is omitted, the <input_file> parameter will be used instead (do not specify an extension for the input file to avoid overwriting the input file!) <emx_options> (optional): emx options to be used when running the bound program. These options will be examined before those given in EMXOPT. emxbind does not completely check the validity of the options. See `Using emx options' for details. emx options for OS/2 and DOS: -c Disable core dumps caused by signals -h# Set file handle limit emx options for DOS: -a* Enables dangerous features. -p Don't use low memory (lower Megabyte) -s# Set stack size (KB) -C# Commit memory -L Disable preloading of pages from the executable file. emx options for OS/2: -f# Set maximum stack frame size (KB) Example: emxbind \emx\emxl myprog -s16384 -p This example will bind myprog and emxl.exe into myprog.exe. The stack size will be set to 16384 KB (under DOS) if this value is not overridden by EMXOPT when myprog.exe is run. The program will be able to run DOS programs. This example can be abbreviated to emxbind myprog -s16384 -p The bound program does not run under DOS versions prior to 3.0. emx options cannot be put onto the command line; use EMXOPT instead. Do not compress the bound executable with a program like TINYPROG, PKLITE, or LZEXE, which makes the program uncompresses itself when started. emx can be used for running bound .exe files created using the same version of emx. spawn() and exec() also work on bound .exe files. The GNU programs GDB, nm, objdump and size (but not strip) have been modified to work with bound .exe files. You can use the emx loader emxl.exe to save disk space. When the bound executable is run, emxl.exe will load emx.exe to run the program. There is a small speed penalty due to locating and loading emx.exe. As the program name is passed on the command line to emx.exe, the available length of the command line is reduced if emxl.exe is used. The maximum command line length can be used if emx.exe is bound to the executable. If the EMX environment variable is set, emxl.exe first tries to load the file specified by that variable. Use SET EMX=c:\emx\bin\emx.exe to speed up locating emx.exe. You can also use emxd.exe this way. If the EMX environment variable is not set or the emx.exe file specified by EMX could not be loaded, emxl.exe will try emx.exe in the current working directory, then emx.exe in all directories listed in the PATH environment variable. 2.2 Changing the type of an .exe file ------------------------------------- You can change the application type after creating an .exe file with emxbind. For instance, this can be used after creating an .exe file with GCC. Exactly one of the options -f, -p and -w must be given. Note that you can set the application type while creating an .exe file with the -b command. Usage: emxbind -e <emxbind_options> <program_file>[.exe] <emxbind_options>: -q don't display title -f set application type to `full screen' -p set application type to `Presentation Manager' -w set application type to `windowed' Exactly one of the options -f, -p and -w must be given. <program_file>: path name of the bound .exe file to be changed. The default extension is `exe' Example: gcc -o myprog.exe myprog.c emxbind -ep myprog Alternatively, you can create a file named myprog.def containing NAME WINDOWAPI and invoke gcc with the following command line: gcc -o myprog.exe myprog.def 2.3 Extracting the a.out file from a bound .exe file ---------------------------------------------------- Usage: emxbind -x [<emxbind_options>] <input_file>[.exe] <output_file> <emxbind_options>: -q don't display title <input_file>: path name of a bound .exe file to be read. The default extension is `exe' <output_file>: path name of the a.out file to be created After extracting the a.out file from an .exe file which was created using a core dump file, you should not use that file for creating an .exe file. Use the -u command if you want to replace emx.exe, emxl.exe or emxd.exe contained in a bound .exe file. The relocation information is removed by emxbind while binding an .exe file. Therefore, the a.out file extracted from a bound .exe file does not include relocation information. This applies to dynamic link libraries and a.out files linked with the -R option of ld. 2.4 Displaying and changing the emx options of a bound .exe file ---------------------------------------------------------------- emxbind also can display or change the emx options of a bound .exe file. Note that the -i option was called -s in previous versions of emxbind. Usage (showing options): emxbind -i [<emxbind_options>] <program_file>[.exe] Usage (altering options): emxbind -a [<emxbind_options>] <program_file>[.exe] [<emx_options>] <emxbind_options>: -q don't display title <program_file>: path name of a bound .exe file to be read or changed, respectively. The default extension is `exe' <emx_options>: remove the options if empty, otherwise put these options into the .exe file (see also -b command) 2.5 Updating emx.exe in a bound .exe file ----------------------------------------- emxbind also can replace the DOS loader in an existing bound .exe file. You should use this only if you can't rebuild the .exe file because you don't have the a.out file. Note that you usually have to re-link your program when using a new release of emx due to differences in the system interface. Usage: emxbind -u [<emxbind_options>] <emx>[.exe] <program_file>[.exe] <emxbind_options>: -q don't display title <emx>: path name of emxd.exe, emx.exe or emxl.exe. This DOS loader is copied to the <program_file>. The default extension is `exe'. <program_file>: path name of the bound .exe file to be changed. The default extension is `exe'. Better make a backup copy of the file before using emxbind -u. 2.6 Stripping the symbol table from a bound .exe file ----------------------------------------------------- emxbind can also be used to remove the symbol table from a bound .exe file (strip.exe cannot be used on .exe files). You can also strip the symbol table while creating the .exe file by using the -s option with the -b command. Usage: emxbind -s [<emxbind_options>] <program_file>[.exe] <emxbind_options>: -q don't display title <program_file>: path name of the bound .exe file to be changed. The default extension is `exe'. Better make a backup copy of the file before using emxbind -s. 2.7 Module definition files --------------------------- emxbind reads LINK386 compatible module definition files. In the following list of available statements, optional parts are enclosed in brackets. Case is ignored for keywords (though IBM says you should use upper case for keywords). See below a list of keywords. You cannot use keywords for function names, module names etc. In case of a conflict, enclose the offending name in single or double quotes. Quotes are also required if a name contains a special character such as blank, tab, `@', `=', `.' or `;'. Lines starting with a semicolon are treated as comment lines and are completely ignored. Numbers can be given in decimal, octal or hexadecimal, using C syntax. CODE ... Ignored. DATA ... Ignored. DESCRIPTION 'text' Put a text into the .EXE or .DLL file. The text must be enclosed in single or double quotes. To include a single quote in single quotes or a double quote in double quotes, simply enter the quote twice. The text will be put at the start of the nonresident name table, which is put at the end of the .EXE or .DLL file. Typically, DESCRIPTION is used to insert a copyright message. Example: DESCRIPTION 'HAL9000 -- Copyright (c) 2001 by Space Odyssey Inc.' EXETYPE ... Ignored. EXPORTS entryname [=internalname] [@ordinal [RESIDENTNAME]] Make a function visible outside the .EXE or .DLL file. All entry points of a dynamic link library must be exported using EXPORTS. Exporting entry points of .EXE files is less common. Following the EXPORTS keyword, you can enter any number of entryname [=internalname] [@ordinal [RESIDENTNAME]] lines, one for each entrypoint. entryname is the name of the function as made visible outside of the .EXE or .DLL file. entryname is always converted to upper case. internalname is the name of the function as defined in your program. If =internalname is omitted, it is assumed to be identical to entryname. internalname is case sensitive. Exported functions not only have a name (entryname), they also have an ordinal number, the position within the name table. Using ordinal numbers when importing saves space and is supposed to be faster. You can assign a specific ordinal number to an exported function by entering @ordinal. ordinal is the ordinal number to be used (1 to 65535). If @ordinal is not given, emxbind chooses an unused ordinal number, but you won't know the ordinal number and therefore cannot use it for importing. If @ordinal is specified, entryname is by default put into the nonresident name table, which is not kept in memory while the .EXE or .DLL file is running or loaded, respectively. This saves space. To put entryname into the resident name table, enter RESIDENTNAME. Then, OS/2 will keep entryname in memory while the .EXE or .DLL file is running or loaded, respectively. This saves time. Example: EXPORTS my_qsort=qsort1 @1 RESIDENTNAME my_hsort HEAPSIZE number Ignored. number can be MAXVAL as well. IMPORTS [internalname=]modulename.entry Ignored. Use emximp instead. LIBRARY [libraryname] [initialization] [termination] Create dynamic link library (.DLL file). If LIBRARY is used, it must be the first statement of the module definition file. libraryname is the name of the module. The name is the first entry of the resident name table and must match the base name of the DLL file. If libraryname is not specified, the name of the a.out file sans directory and extension is used. initialization can be either INITGLOBAL or INITINSTANCE. INITGLOBAL causes the library initialization function to be called when the DLL is initially loaded into memory. INITINSTANCE causes the library initialization function to be called each time a process loads the DLL and each time a process referencing the DLL is started. termination can be either TERMGLOBAL or TERMINSTANCE. TERMGLOBAL causes the library termination function to be called when the DLL is no longer used by any process. TERMINSTANCE causes the library termination function to be called each time a process frees the DLL and each time a process referencing the DLL terminates. Currently, TERMGLOBAL seems to cause the termination function to be called not at all. See _DLL_InitTerm() for details about the library initialization function and the library termination function. If initialization and termination are omitted, INITGLOBAL and TERMGLOBAL are used. If one of initialization and termination is specified, the other one defaults to an appropriate value, as shown by the following table: | (no termination) | TERMGLOBAL | TERMINSTANCE ----------------------+------------------+--------------+------------- (no initialization) | INITGLOBAL | INITGLOBAL | INITINSTANCE | TERMGLOBAL | TERMGLOBAL | TERMINSTANCE ----------------------+------------------+--------------+------------- INITGLOBAL | INITGLOBAL | INITGLOBAL | INITGLOBAL | TERMGLOBAL | TERMGLOBAL | TERMINSTANCE ----------------------+------------------+--------------+------------- INITINSTANCE | INITINSTANCE | INITINSTANCE | INITINSTANCE | TERMINSTANCE | TERMGLOBAL | TERMINSTANCE Examples: LIBRARY LIBRARY INITINSTANCE LIBRARY mylib LIBRARY mylib INITINSTANCE TERMGLOBAL NAME [appname] [apptype] [NEWFILES] Create a .EXE file. If NAME is used, it must be the first statement. appname is the name of the module. The name is the first entry of the resident name table. If appname is not specified, the name of the a.out file sans directory and extension is used. apptype can be one of the following keywords: NOTWINDOWCOMPAT the program will run full-screen WINDOWAPI the program is a Presentation Manager application WINDOWCOMPAT the program will run in a text window The default is WINDOWCOMPAT. apptype can be overridden on the emxbind command line with the -f, -p and -w options. The NEWFILES keyword (LONGNAMES is an alias) is ignored, emx applications always use long file names. Examples: NAME WINDOWAPI NAME myprog NAME myprog NOTWINDOWCOMPAT OLD 'library' Ignored. PROTMODE Ignored. SEGMENTS ... Ignored. STACKSIZE number Set the stack size for OS/2 programs. Always use this statement as the default is too small. The stack size should be 32768 or more. The stack size for DOS programs is controlled by the -s emx option. STUB 'program' Use program as DOS executable file. This program is run if the .EXE or .DLL file is started under DOS. program is sought in the directories listed in the EMXPATH and PATH environment variables unless the file name includes a directory. If the <emx> argument is given on the emxbind command line, the STUB statement is ignored. If <emx> is not given and the STUB statement is not present, \emx\bin\emxl.exe is used. If that file does not exist, emxl.exe is sought in the directories listed in the EMXPATH and PATH environment variables and in the current working directory. Example: STUB 'emx.exe' Reserved words -------------- The following words are reserved. You cannot use them as function names, module names, etc. unless enclosed in quotes. ALIAS INVALID PHYSICAL BASE IOPL PRELOAD CLASS LIBRARY PRIVATE CODE LOADONCALL PRIVATELIB CONFORMING LONGNAMES PROTECT CONTIGUOUS MAXVAL PROTMODE DATA MIXED1632 PURE DESCRIPTION MOVABLE READONLY DEV386 MOVEABLE READWRITE DEVICE MULTIPLE REALMODE DISCARDABLE NAME RESIDENT DOS4 NEWFILES RESIDENTNAME DYNAMIC NODATA SEGMENTS EXECUTEONLY NOEXPANDDOWN SHARED EXECUTE-ONLY NOIOPL SINGLE EXECUTEREAD NONAME STACKSIZE EXETYPE NONCONFORMING STUB EXPANDDOWN NONDISCARDABLE SWAPPABLE EXPORTS NONE TERMGLOBAL FIXED NONPERMANENT TERMINSTANCE HEAPSIZE NONSHARED UNKNOWN HUGE NOTWINDOWCOMPAT VIRTUAL IMPORTS OBJECTS WINDOWAPI IMPURE OLD WINDOWCOMPAT INCLUDE ORDER WINDOWS INITGLOBAL OS2 INITINSTANCE PERMANENT 3 Using emx options =================== Under DOS, emx options can be given on the emx command line. Under OS/2 and DOS, emx options can also be given in the EMXOPT environment variable. Moreover, you can use emxbind to put emx options into the executable file. Options given on the emx command line override options given in EMXOPT. Options given in EMXOPT override options stored in the executable file. The following options are available: -a* [DOS] Enable dangerous features: -ac makes data and the stack executable, -am enables _memaccess(), -aw enables write access to all memory areas, -ai enables _portaccess(). By default, only the .text section is executable, _memaccess() and _portaccess() are disabled. You can combine letters: for instance, -aim enables both _memaccess() and _portaccess(), -aciw enables all dangerous features. Note: -ac is automatically set in programs run with P_DEBUG mode of spawn(). -c Disable core dumps caused by signals. Core dumps created by _core() are not disabled. -d [DOS] Don't use extended memory. Only low memory (below 1 MB) will be used. -e [DOS] Don't check for 387 coprocessor. Assume no coprocessor is present. -f# [OS/2] Set maximum stack frame size (KB), minimum: -f4, maximum: -f32768, default: -f512. -h# Set file handle limit. Under DOS, the DOS file handle limit for the emx process is set to #. The number # must be between 10 and 255. This option is ignored for DOS versions earlier than 3.30. This option does not change the emx limit for the number of files per process -- that limit is always 40. Under OS/2, the file handle limit for the current process is set to #. The number # must be between 10 and 255. -m# [DOS] Select machine. -m1 selects Fujitsu FMR70 (not implemented yet), -m2 selects NEC PC-98 (not implemented yet), -m3 selects Inboard 386/PC. -o [DOS] Send the register dump of an exception to stdout. Without -o, the register dump is sent to the CON device. You need -o for redirecting the register dump to a file. -p [DOS] Don't use low memory (lower Megabyte); use this if the program runs a DOS program; not required for emx programs (either a.out and bound .exe). If -p is not given, low memory will be used and there won't be enough low memory for running other programs. -r* Prepend drive letter * to absolute path names. If a path name starts with / but does not start with //, /dev/ or /pipe/, * followed by a colon will be prepended. If -rd has been given, the file name \mydir\abc will be translated to d:\mydir\abc. Note: this option can cause unexpected effects. -s# [DOS] Set stack size (KB), minimum: -s8, maximum: -s524288, default: -s8192. Note that under DOS, the heap and the stack share the same memory area. The pages not used by the stack are available for the heap. Therefore, you should use -s# if you need more than 8 MB of heap and stack. -t Truncate file names to 8.3 format. -C# [DOS] Commit memory. By default, memory is allocated as soon as a page is accessed. If there isn't enough memory (and swap space), the process is terminated. With -C#, memory is allocated when creating the process and when enlarging the data segment with brk() and sbrk(). If there isn't enough memory (and swap space), the process brk(), sbrk(), malloc() etc. return an error. The number # specifies how many KB should be allocated for the stack. If # is omitted, 0 is used. The -C# option is not yet completely implemented -- if an allocation request succeeds partly, the allocated pages are not freed. -E [OS/2] Run debuggee in same session. -F [DOS] Use fast A20 switching. -L [DOS] Disable preloading of pages from the executable file. By default, the complete code and data areas are read into memory before a program is started. If there is not enough memory, no pages are preloaded. With -L (or if not enough memory is available), pages are loaded as soon as they are accessed. -O [DOS] Override XMS version check. -P [DOS] Use patched code for A20 switching. -S# [DOS] Enable the emx kernel debugger. Use the -S option to operate the debugger through the keyboard and display. If you want to debug using a terminal, enter -S1 to use COM1, -S2 to use COM2. -V Display emx version. -Z [DOS] Don't zero-fill pages. This option is used for testing. 4 emx utilities =============== 4.1 updt -------- - Copy file if contents have changed: updt [-v] <source_file> <target_file> updt copies the source file to the target file if the target file does not exist or if the source and target files differ in contents. This is used by the makefile for GCC. - Copy file if source file is newer: updt [-v] -t <source_file> <target_file> updt copies the source file to the target file if the target file does not exist or if the source file is newer than the target file. This is used for configuring GCC. The -v option turns on information messages. 4.2 emximp ---------- emximp manages files required for importing functions from dynamic link libraries. Three different methods for importing are used for the two methods of creating executable files. When using ld and emxbind, there are two methods for importing: (I1) The import library contains a small piece of code for each function which loads the AL register with the number of argument words and jumps to the imported function. Information on imported functions is stored in tables in the text segment of the program. emxbind reads these tables to creates appropriate fixups in the .EXE file. When an imported function is called while running the resulting program under DOS, an error message will be displayed and the program will be terminated. Data cannot be imported with method (I1). You have to use the -R option of ld. (I2) The import library does not contain code. Instead, it contains special symbol table entries, which are copied to the a.out file. One of these entries makes ld create a relocatable output file. emxbind reads the symbol table and creates appropriate fixups in the .EXE file. The AL register isn't loaded with the number of argument words. The program will be aborted (protection violation) when an imported function is called under DOS. Importing by name is not supported, the ordinal number will always be used. The -R option of ld is automatically turned on when referencing an import definition of type (I2). When using emxomf and LINK386, the standard OS/2 method is used: (I3) LINK386 reads a .LIB import library or a module definition file to create appropriate fixups. The AL register isn't loaded with the number of argument words. The program won't run under DOS. Methods (I2) and (I3) are recommended unless the dynamic link library requires the AL register to be loaded with the number of argument words. libos2.a uses method (I2). emximp is used to create appropriate files for all these methods. Information on functions exported by dynamic link libraries is provided in emx import list files. The following table summarizes the features of the three methods: Method | (I1) | (I2) | (I3) ---------------------+--------+---------+---------- Linker | ld | ld | LINK386 Import by name | YES | NO | YES Load AL register | YES | NO | NO Code overhead | YES | NO | NO Catch call under DOS | YES | NO | NO Import library type | .o .a | .a | .lib .def Can import functions | YES | YES | YES Can import data | NO | YES | YES Additive fixups | NO | YES | YES Linker options | -R | | What is an emx import list file? -------------------------------- An emx import list file defines how functions can be imported from dynamic link libraries. For each function, the import list file defines the name of the function, the module name (that's the name of the dynamic link library exporting the function), either the ordinal number or the name of the function as exported by the dynamic link library, and the number of argument 32-bit words expected by the function (this is the number of arguments unless structures are passed by value). For method (I1), emximp is used to turn an import list file into an `.a' import library which can be linked to a program using the ld linker. emximp either creates assembler source files (.s) or automatically calls the assembler to create object files (.o). The object files can be packed into a library with the ar program. For method (I2), emximp is used to turn an import list file or an OMF import library (.lib file) directly into an `.a' import library which can be linked to a program using the ld linker. For method (I3), emximp can convert an import list file into a module definition file or an OMF import library. Comments in an import list file are started with a semicolon. Empty lines are ignored. For each function you have to put one line into the import list file. Here's an example of an import list file: ; myimport.imp DosStartTimer doscalls 351 3 DosStopTimer doscalls 290 1 Such a line consists of four components which are separated by one or more blanks. The first word is the name of the function, as used in C programs. The second word is the name of the DLL. The third word is either the ordinal number of the DLL entry or the name of the DLL entry. You have to use ordinal numbers for OS/2 API functions. The fourth word is the number of 32-bit words of arguments expected by the function. This is the number of arguments unless structures are passed by value. A question mark used as forth word is equivalent to using the number 0. A question mark should be used if the number of arguments is unknown or if the entry point is not a function (data can also be exported). Using a question mark causes a warning when creating files for method (I1). An `R' used as forth word causes the AL register not to be loaded with method (I1) -- this is used for functions which expect an argument in the EAX register. An `F' used as forth word specifies a 16-bit function. emximp appends `_16_' in front of the function name to notify emxbind and emxomf of the 16-bitness of the function. References to symbols starting with _16_ are fixed up by 16:16 far pointers. Creating an emx import list file from an OMF import library (.lib file) ----------------------------------------------------------------------- emximp -o <output_file>.imp <input_file>.lib ... <output_file> is the name of the emx import list file to be created. The name must end with `.imp'. <input_file> is the name of an existing import library file. The name must end with `.lib'. You can give one or more input file names on the command line. As the number of argument words of the functions cannot be derived from the import library, a question mark instead of a number for the number of argument words is written to the import list file. Creating an emx import list file from a module definition file (.def file) -------------------------------------------------------------------------- emximp -o <output_file>.imp <input_file>.def <output_file> is the name of the emx import list file to be created. The name must end with `.imp'. <input_file> is the name of an existing module definition file. The name must end with `.def'. You can give only one input file name. As the number of argument words of the functions cannot be derived from the module definition file, a question mark instead of a number for the number of argument words is written to the import list file. Creating an emx import library for method (I1) ---------------------------------------------- emximp [-a<assembler>] [-b<base_name>|<prefix_length>] [-p<module>]... [-s] <input_file>.imp ... <input_file> is the name of the import list file. The name must end with `.imp'. You can give one or more input file names on the command line. The names of the output files are either taken from the import list file or automatically generated by emximp. A line in starting with `+' starts a new assembly language file or object file (module). The name of the output file is given after the `+': +os2mem1.s ; start a new output file This feature is used only for method (I1). All the functions defined in one module are linked if at least one of the functions is referenced. It's possible to let emximp automatically write one file per function. The output file names are constructed by appending the ordinal number or a sequential number to a fixed prefix or to a prefix of the DLL name. To let emximp automatically choose output file names, use the -b command line option. If -b is given, the import list file must not contain lines starting with `+'. The argument of the -b option is either a number or a string. If the argument is a string, that string is used as base name of the output files If the argument is a number, that many characters are taken from the start of each DLL name to create the base name of the output file. A number is appended to the base name. If -s is given, a sequential number is appended, starting with the number 1. The number is incremented for each output file. If -s is not given, the ordinal number of the function is appended; giving entry names instead of ordinal numbers in the import list file is not allowed for that reason. Note that appending ordinal numbers to the names may cause problems (output for different functions written to the same file) if multiple DLLs are used in the import list file and the argument of the -b option is a string (or too small a number to make the prefixes unique). These problems also occur if the import list file defines multiple functions to refer to the same entry point. The extension of the output files is `.o' if the -a option is used, `.s' otherwise. By default, emximp creates assembler source files. emximp can automatically call an assembler to assemble the output files. This feature is turned on by the -a command line option. The argument of the -a option is the name of the assembler (there must be no blanks between -a and the argument). If the argument is omitted, `as' is used. The default extension is .exe, the program will be sought in the directories listed in the PATH environment variable. The object files will have the same name as the assembler source files, with the `.s' extension replaced by `.o'. Under OS/2, the assembly language files are not actually written, a pipe is used instead. Under DOS, the assembly language files created by emximp will be deleted automatically after running the assembler. To save space in the executable file, DLL names which are often used should be put into separate files, see above for an example. Use the -p option of emximp to use separate files for the DLL names. The argument of the -p option is the name of the DLL. emximp prepends `__os2_' to the DLL name for making the label used for referencing the DLL name. You can use multiple -p option. Here's how to write a separate file which defines a DLL name: .globl __os2_pmgpi .text __os2_pmgpi: .asciz "PMGPI" This file declares the DLL name `PMGPI'. Use the `-p pmgpi' option of emximp to tell emximp to create code that references this file. Technical details: Let's examine the .s file created by emximp.exe for the DosSelectSession function. 1) .globl _DosSelectSession 2) .align 2, 144 3) _DosSelectSession: 4) movb $1, %al 5) 1: jmp __os2_bad 6) 2: .long 1, 1b+1, L1, 38 7) L1: .asciz "sesmgr" 8) .stabs "__os2dll", 23, 0, 0, 2b Line 1 is obvious: it exports _DosSelectSession from libos2.a so that ld will link this module when _DosSelectSession is referenced. Line 2 is a speed hack: the 386 performs much better when jumping to an address which is an integral multiple of 4. Line 3 declares _DosSelectSession. Your program calls this code when calling DosSelectSession. Line 4 stores the number of arguments in the AL register (or rather, the number of argument 32-bit words). Line 5 jumps to __os2_bad which displays an error message and stops execution. This is what happens if you run the program on DOS. Line 6 creates a small table which is read by emxbind: It consists of four words: - a word of flag bits. Currently, only bit 0 is defined: it's 0 for import by name, 1 for import by ordinal. - the address of the word to be fixed up for referencing the DLL. `1b+1' means `local label 1, looking backwards, add one to address'. Therefore, the address used by the JMP instruction is used. - a pointer to the name of the module (null-terminated ASCII string). For often used names the pointer should point to a string in a separate, common module to save space, see the -p option. - the ordinal number or a pointer to the name of the entry point (null-terminated ASCII string), respectively, depending on bit 0 of the flags word. Line 7 defines the module name pointed to by the table. Line 8 is the tricky part: it contains a special symbol table entry to make ld build a table named __os2dll which contains pointers to all the small tables (2b is the address of the small table). See also crt0.s, where the table is initialized. crt0 contains a pointer to the table in a fixed location so that emxbind can find the table of pointers, read all the small tables (as described above) and create the necessary OS/2 fixups. Creating an a.out import library for method (I2) ------------------------------------------------ emximp -o <output_file>.a <input_file>.imp ... emximp -o <output_file>.a <input_file>.lib ... <output_file>.a is the name of the archive file to be created. The name must end with `.a'. <input_file>.imp is the name of an emx import list file. The name must end with `.imp'. <input_file>.lib is the name of an import library (OMF). The name must end with `.lib'. Modules in the input files which are not import definitions are ignored. You can give one or more input file names on the command line; all input file must be of the same type, either `.imp' or `.lib'. All import records of the input files are converted to import modules for method (I2). After creating the output file, you should run `ar s' on the output file to increase linking efficiency. Technical details: A member named `__.IMPORT' is added to the archive. GNU ld (the one ported to emx) has been patched to turn on relocatable output if it finds a member named `__.IMPORT' in a library. As only the __.SYMDEF member is scanned if present, `__.IMPORT' defines the special symbol `__IMPORT!'. When patched GNU ld finds the definition of a symbol named `__IMPORT!' in the __.SYMDEF member, relocatable output is turned on. (Relocatable output can also be turned on by using the -R option of ld.) For each function in the input files, emximp adds an a.out-type module to the output file. Such a module defines two symbols. One symbol defines the entry point, the other symbol gives information on the DLL name and the ordinal number. For instance, for LIBRARY doscalls EXPORTS DosBeep @286 the two symbols `_DosBeep' and `_DosBeep=doscalls.286' are defined. The symbol types 0x69 and 0x6b are used, respectively. GNU ld has been patched to keep references to symbols of type 0x69 in the relocation table. emxbind scans the relocation table for references to symbols of type 0x69 and scans the symbol table for a matching symbol of type 0x6b which defines the entry point. Creating an OMF import library for method (I3) ---------------------------------------------- emximp -o <output_file>.lib <input_file>.imp ... <output_file>.a is the name of the import library file to be created. The name must end with `.lib'. <input_file>.imp is the name of a module definition file. You can give one or more input file names on the command line. All the import list files must define functions that are in the same dynamic link library. Lines start with `+' are ignored. The number of argument words is lost after that conversion, that is, you cannot recreated the import list file using emximp. Creating a module definition file for method (I3) ------------------------------------------------- emximp -o <output_file>.def <input_file>.imp ... <output_file> is the name of the module definition file to be created. The name must end with `.def'. <input_file> is the name of an emx import list file. The name must end with `.imp'. You can give one or more input file names on the command line. All the import list files must define functions that are in the same dynamic link library. Lines start with `+' are ignored. The number of argument words is lost after that conversion, that is, you cannot recreated the import list file using emximp. 4.3 emxomf ---------- The emxomf tool converts a.out object files (.o files) to Object Module Formats (.obj files). The converted files can be used with the OS/2 linker link386.exe. emxomf [-d] [-l] [-s] [-m<symbol>] -o <output_file> <input_file> Convert a single .o or .a file (INPUT_FILE) to an .obj or .lib file (OUTPUT_FILE). There are no default extensions. If -l is given, the module (all the modules of the archive when converting an archive) is supposed to be a library module. A library module doesn't define a stack segment, doesn't have an entry point and doesn't request libraries. If -m is given, the module is supposed to be the main module of a program. A main module defines a default stack segment (0x2000 bytes) and has an entry point. SYMBOL is the name of the entry point, that is, the function that should be called when the program is started. -m is used for the startup code module crt0 and should not be used for user modules. If -l and -m are missing, the module is supposed to be part of a program but not the main module. Such a module doesn't define a stack segment, doesn't have an entry point. If the -d option is given, the input file is deleted after successful conversion. If the input file is an archive, it is not deleted. If the -s option is given, debugging information is omitted. emxomf [-d] [-l] [-s] [-x] [-m<symbol>] [-O <directory>] [-r|R<response_file>] <input_file>... Convert multiple .o and .a files to .obj and .lib files (more than one INPUT_FILE can be given on the command line). The names of the output files are constructed by replacing the extension of the INPUT_FILES with `.obj' or `.lib', respectively. If the -x option is given, all members (which must be a.out modules) of archives (.a files) are converted to .obj files. The names of the output files are constructed by replacing the extension of the member names with `.obj'. If the -x option is not given, archives (.a files) are converted to libraries (.lib files). If the -O option is given, the output files are written to the directory DIRECTORY. A LIB response file RESPONSE_FILE is created if you use the -r or -R option. When using -r, the response file will contain commands to add the modules to a library file, when using -R, it will contain commands to replace the modules in a library file. See above for a discussion of the -l and -m options. If the -d option is given, all the input files except for archives are deleted after successful conversion. If the -s option is given, debugging information is omitted. 4.4 emxomfld ------------ emxomfld is a front end to LINK386, providing an ld-like command line syntax for LINK386. After parsing the command line, LINK386 is called with equivalent command line arguments. emxomfld -o file [-sS] [-l lib] [-L libdir] [-T base] file... The name of the output file is specified by the argument of the -o option. The default extension (.EXE or .DLL) is provided by LINK386. If -o is omitted, `$$$' will be used. Libraries are specified by -l options. The argument of an -l option is prepended by `lib'. For instance, -lc causes libc.lib to be used. Libraries are sought in the directories given by -L options. emxomfld appends the directories to the LIB environment variable. The -T option is translated to the /base option of LINK386. Use -T 0x10000 to create non-relocatable .EXE files, which are slightly smaller and load slightly faster. The -s and -S options cause debugging information to be discarded. If -s and -S are not used, emxomfld passes the /debug option to link386. The files given on the emxomfld command line are assumed to be OBJ files to be linked unless the extension is .def, .lib, .map or .res. A file having a .def extension is used as module definition file. There may be at most one module definition file. A file having a .lib extension is used as library file. A file having .map extension is used as map file to be written by LINK386. A file having a .res extension is used as binary resource file; RC is called to attach the resources to the output file. Example: emxomfld -o test -lc -Lc:/mylibs test1 test2 test.def test.map test.res Create file test.exe (or test.dll, depending on the contents of test.def), by linking test1.obj and obj2.obj with libc.lib. libc.lib is sought in c:/mylibs. Use the module definition file test.def, create the map file test.map. Call RC to copy the resources from test.res to test.exe (or test.dll). The following debugging option is available: -i pass the /information option to LINK386, causing file names to be displayed while linking The following options are ignored: -x discard all local symbols -X discard local symbols starting with L 4.5 emxomfar ------------ emxomfar is a librarian for OMF LIB files with a command line interface similar to `ar' to simplify makefiles. emxomfar [-p#] <command> <library_file> [<module>]... The default extension for <library_file> is .lib. When modifying a library file, a backup file with .bak extension is created. The following commands are available: d Delete modules from library. The module name __.SYMDEF is ignored. q Quick append. This command is equivalent to the r command. r Replace modules in library. Modules which are not in the library are added to the library. The default extension for modules is .obj. s This command is ignored -- will do nothing. t List table of contents. Use the v option to also list public symbols. x Extract modules from library. The default extension for modules is .obj. You can additionally use the following modifiers in the <command> argument: c Don't display warning when creating new library. v Verbose output. The following option must precede <command> if used: -p# Set page size to # bytes (16, 32, 64, ..., 32768). If -p is not given, a page size of 16 bytes will be used. Increase the page size if emxomfar complains about too big a library. If emxomfar doesn't complain, you shouldn't increase the page size to save disk space. The following `ar' commands are not implemented: m Move members to the end of the archive. p Copy members to standard output. The following `ar' modifiers in the <command> argument are ignored: l Create temporary file in current directory. o Preserve dates. u Update. Don't replace members with older files. The following `ar' modifiers in the <command> argument are not implemented: a Position after specified member. b Position before specified member. i Position before specified member. Example: emxomfar -p32 rc newlib *.obj 4.6 emxcat ---------- The emxcat tool concatenates assembler or C source files. This is used for building emxlibc.dll. emxcat -o <output_file> <input_file>... All the <input_file>s are concatenated and written to <output_file>. If the output file is included in the input files, it is not copied; emxcat simply compares the file names, therefore it's possible to fool emxcat and make it copying until the disk is full. An #include statement is omitted if it has already been copied to the output file. When the order of the include files is essential, the first input file should contain #include statements in the correct order. (By using two passes, emxcat could be enhanced to put the #include statements into the correct order.) When concatenating .s files, lines starting with CONST_ are also omitted if already copied. All macros #defined by an input file are #undefined after copying the input file. 4.7 emxrev ---------- emxrev displays the revision number of emx DLLs (emx.dll, emxio.dll and emxlibc.dll). The revision number is incremented every time a changed version of a DLL is released. By looking at the revision numbers of the DLLs, you can tell which one is the newest one. To display the revision number of the default emx DLLs, type emxrev The default DLLs are those used by the operating system when starting a program. To display the revision number of a specific file, type emxrev -f file If a directory is included in FILE, append .dll to the name. If no directory is included in FILE, don't append .dll to the name. To display the revision numbers of the emx DLLs in directory DIR, type emxrev -d dir To display the revision numbers of the emx DLLs in all directories of drive D:, type emxrev -c d: To display the revision numbers of the emx DLLs in all directories of all hard disks, type emxrev -a To display the revision numbers of the emx DLLs in the directories listed in the LIBPATH statement of a config.sys file, type emxrev -p file where FILE is the name of the config.sys file. 5 Library functions and system calls ==================================== 5.1 Overview ------------ The following emx libraries are provided: libc The C library. This library includes the standard C library functions, Unix extensions and emx extensions. This library is also provided as dynamic link library (emxlibc.dll) libemx1 System call interface for emx. For instance, this library translates the __open() system call to system call 0x2b of emx. When using this library, emx.dll is required under OS/2. This library is always required for DOS programs libemx2 Import library for emx.dll. This library is used by libemx1 and libos2 (unless libsys is used) libemxio Import library for emxio.dll. When using hardware port I/O functions such as _outp8(), you may have to use this library. libemxio must be used when linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt). libemxio must not be used if the program should also run under DOS libg Dummy debugging library. GCC uses -lg if -g is given on the command line libgcc Compiler helper functions for GCC. The functions of libgcc are duplicated in emxlibc.dll. As libgcc requires functions from libc and libc requires functions from libgcc, libgcc must be given twice on the command line of the Unix-style linker: -lgcc -lc -lgcc libgraph Graphics library. For certain functions, this library requires access to hardware ports. When using these functions, you have to use libemxio after libgraph unless the program should also run under DOS libm Dummy math library. This library is provided for makefile compatibility; it isn't required as the math functions are contained in libc libmt Import library for emxlibc.dll. This library is used instead of libc and libgcc when using the -Zmt option libos2 Import library for OS/2 API. This library is not a pure import library, it also contains static code for DosGetMessage and DosQueryMessageCP and for the 16-bit wrappers. libemx2 or libsys is required by the 16-bit wrappers libsys System call emulation library. This library is used instead of libemx1 when creating stand-alone OS/2 applications (-Zsys). libsys is provided in OMF style only (libsys.lib) libvideo Video library. This library contains the functions declared in sys/video.h and sys/winmgr.h. The following dynamic link libraries are provided: emx.dll This is the emx run-time support. The import library for emx.dll is libemx2 emxio.dll Access to hardware ports. The import library for emxio.dll is libemxio emxlibc.dll emx C library. Contains all functions of libc and libgcc, except for port I/O functions. For compatibility with existing programs, emxlibc.dll contains dummy functions for port I/O, though these didn't work in emxlibc.dll of emx 0.8e. The import library for emxlibc.dll is libmt 5.2 Preliminary notes --------------------- - Day-light-saving time (summer time) is not implemented. This affects only computation of GMT. If there are problems with the interpretation of the TZ environment variable, use EMXTZ for emx programs. See tzset() for details. - Not all functions declared in the header files are implemented. - Does anyone have a surplus copy of the ANSI C specs? A donation of the ANSI C standard paper would be appreciated. - By default, text mode is used for files. See fread() and fwrite() for details. The default can be globally changed to binary mode by linking with binmode.o or binmode.obj. - See the description of g_mode() for general information about the graphics library. - See the description of v_init() for general information about the video library. - See the description of wm_init() for general information about the window manager functions. 5.3 Library reference: functions -------------------------------- The functions are listed almost alphabetically. The origin of most of the functions is shown in [brackets] at the end of the first line. Functions which are not available or are limited with the system call library (-Zsys, libsys.lib) are marked [*]. ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void volatile abort (void); abort() does some cleaning up and aborts program by raising SIGABRT. The default action for SIGABRT is to display the message `Abnormal program termination' and exit with return code 3. See also: exit(), _exit(), raise(), signal() ------------------------------------------------------------------------------ #include <stdlib.h> /* use this */ [ANSI] #include <math.h> /* or this */ int abs (int n); Return the absolute value of N: If N is negative, -N is returned. Otherwise, N is returned. In-line code is generated for this function. See also: fabs(), labs() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _abspath (char *dst, const char *src, int size); Construct an absolute path name for the file name or directory name SRC. The absolute path name is put to DST. It is assumed that there are SIZE bytes available at DST, this includes the terminating 0 byte. If there is an error, -1 is returned. If _abspath() succeeds, 0 is returned. If SIZE is too small, errno is set to ERANGE and -1 is returned. DST can be identical to SRC. Backslashes are translated into forward slashes. The absolute path name is not translated to lower case. If SRC ends with a slash or backslash, DST will end with a slash. _abspath() works with non-existing paths, it accesses the appropriate drive only for finding out the current working directory, if necessary. See also: _fnisabs(), _fullpath() ------------------------------------------------------------------------------ #include <io.h> [UNIX] int access (const char *name, int mode); Returns 0 if the file or directory NAME is accessible in mode MODE. Otherwise returns -1 and sets errno to ENOENT or EACCES. If MODE is 0, access() checks only for existence of the file or directory. If MODE is 2, access() checks for write permission. If MODE is 4, access() checks for read permission (always granted under DOS and OS/2 if the file exists). If MODE is 6, access() checks for read and write permission. Restrictions: access() does not work with devices (ENOENT). See also: open(), stat() ------------------------------------------------------------------------------ #include <stdlib.h> [*] [UNIX] unsigned alarm (unsigned SEC); Raises SIGALRM after SEC seconds have expired. There is only one alarm clock, calling alarm() while the alarm clock is running, the time will be reset to the new value. If SEC is zero, the alarm clock will be stopped. alarm() returns the number of seconds remaining on the alarm clock before setting the new value. Under DOS, SIGALRM is not raised until return from DOS if the timer expired during a DOS call. Restriction: When using the system call library libsys.lib (-Zsys), alarm() is not available. See also: raise(), signal(), sleep(), _sleep2() ------------------------------------------------------------------------------ #include <alloca.h> void *alloca (size_t n); Allocate N bytes from the current stack frame. The memory space allocated by alloca() will be freed on exit from the current function. Do not pass the pointer returned by alloca() to free(). This note applies only if you need stack probes: If alloca() with constant argument occurs in the first statement of a function with less than 4096 bytes of local data or if two calls to alloca() with constant arguments occur twice in a row without accessing the memory pointed to by the return value of the first call, you have to change your code to make GCC generate correct stack probes. This can be done by storing a dummy value to the return value of alloca(). Example: p = alloca (0xf00); {char *fix=alloca (0); *fix = 0;} q = alloca (0xf00); Example: void test (void) { char local[0xf00], *p; {char *fix=alloca (0); *fix = 0;} p = alloca (0xf00); /*...*/ } See also: GCC, malloc() ------------------------------------------------------------------------------ #include <time.h> [ANSI] char *asctime (const struct tm *t); Convert the time and date given by the structure pointed to by T to a string. A pointer to the string is returned. There is only one memory location for the ctime() and asctime() results, a call to ctime() or asctime() overwrites the result of a previous calls to ctime() or asctime(). As localtime() is called by ctime(), the memory location shared by localtime(), gmtime(), and mktime() is overwritten. The string looks like "Sun Mar 22 22:59:18 1992\n" with a terminating 0. All fields have fixed width. See also: ctime() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double acos (double x); double asin (double x); double atan (double x); double atan2 (double y, double x); Compute the arc sine, arc cosine and arc tangent of X, respectively. atan2() computes the arctangent of Y/X, using the signs of Y and X to determine the quadrant. If X is outside [-1,1], asin() and acos() return #NAN and set errno to EDOM. See also: cos(), sin(), tan() ------------------------------------------------------------------------------ #include <assert.h> [ANSI] void assert (int exp); If the preprocessor macro NDEBUG is defined, assert() does nothing. Otherwise, if EXP is zero, the message Assertion failed: EXP, file FILE, line LINE is displayed and the program is aborted. EXP, FILE and LINE are replaced with EXP (as text), the source file name and the source line number, respectively. If EXP is non-zero, nothing is done. See also: abort() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] int atexit (void (*func)(void)); The function FUNC will be called when the process is terminated. The last function installed by calling atexit() will be called first. Up to 32 functions can be installed. 0 is returned if successful, -1 otherwise. See also: abort(), exit(), _exit() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] #include <math.h> /* alternate include file for atof() */ double atof (const char *string); int atoi (const char *string); long atol (const char *string); Convert the textual representation of a number in STRING to a number. Leading whitespace is ignored. If the string cannot be converted, 0 is returned. See also: _atoll(), _itoa(), _ltoa(), scanf() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] long long _atoll (const char *string); Convert the textual representation of a number in STRING to a number. Leading whitespace is ignored. If the string cannot be converted, 0 is returned. See also: atol() ------------------------------------------------------------------------------ #include <strings.h> [BSD] int bcmp (const void *buffer1, const void *buffer2, size_t n); Compare the first N bytes at BUFFER1 to the first N bytes at BUFFER2. If the two buffers are identical (or if N is zero), 0 is returned. Otherwise, a non-zero value is returned. See also: memcmp() ------------------------------------------------------------------------------ #include <strings.h> [BSD] void bcopy (const void *src, void *dst, size_t n); Copy memory. Copy N bytes from SRC to DST. The two regions may overlap. See also: memmove() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] int _beginthread (void (*start)(void *arg), void *stack, unsigned stack_size, void *arg_list); Start a thread. START is the start address (a function). ARG_LIST will be passed in the ARG parameter of the START function. STACK is ignored, using NULL is recommended. STACK_SIZE is the size of the stack for the new thread. When the START function returns, the thread is terminated. A thread can also terminate itself by calling _endthread(). If successful, _beginthread() returns the thread ID. On error, _beginthread() sets errno and returns -1. The stack allocated for the new thread is completely committed, that is, stack probes are not required. Do not start a thread with DosCreateThread unless it doesn't call C library functions. _beginthread() is available only when using emxlibc.dll (-Zmt). See also: _endthread() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] void *brk (void *addr); Change end address of data segment to ADDR. On success, brk() returns 0, cast as pointer. Otherwise, -1 cast as pointer is returned and errno set to ENOMEM. Please don't use brk() -- use malloc() instead for memory allocation. See also: malloc(), sbrk() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void *bsearch (const void *key, const void *base, size_t num, size_t width, int (*compare)(const void *key, const void *element)); Perform a binary search on the sorted array BASE to find KEY. The array has NUM elements of size WIDTH bytes each. bsearch() calls COMPARE to compare an array element pointed to by ELEMENT with KEY. COMPARE should return 0 if KEY and ELEMENT are equal; a negative value, if KEY is smaller than ELEMENT; a positive value if KEY is greater than ELEMENT with respect to the sorting order of ARRAY. bsearch() returns a pointer to an occurrence of KEY in the array. If KEY is not found, NULL is returned. If there are multiple occurrences of KEY in ARRAY, bsearch() returns a pointer to any one of the entries. If ARRAY is not sorted, bsearch() does not work. See also: qsort() ------------------------------------------------------------------------------ #include <strings.h> [BSD] void bzero (void *buffer, size_t n); Set N bytes at BUFFER to 0. See also: memset() ------------------------------------------------------------------------------ #include <math.h> double cbrt (double x); Compute and return the cube root of X. This is done by calling pow() and adjusting the sign. See also: pow(), sqrt() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double ceil (double x); Return as floating-point number the smallest integer that is greater than or equal to X (round up). See also: floor(), rint(), trunc() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] int chdir (const char *name); Change to directory NAME. If NAME contains a drive letter, the working directory on that drive is changed, but the selected drive does not change. If successful, 0 is returned. Otherwise, -1 is returned. Restriction: Under DOS, the current working directory is not a property of a process, it's a system-wide property. That may change in a future release of emx. See also: _chdir2(), getcwd() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _chdir2 (const char *name); Change to drive and directory NAME. If NAME contains a drive letter, that drive is selected. If successful, 0 is returned. Otherwise, -1 is returned. Restriction: Under DOS, the current working directory and the default drive is not a property of a process, it's a system-wide property. That may change in a future release of emx. See also: chdir(), getcwd() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] int _chdrive (char drive); Make the disk drive DRIVE the default drive. DRIVE must be in 'A' through 'Z'. _chdrive() always returns 0, even if the drive does not exist. See also: _chdir2(), _getdrive() ------------------------------------------------------------------------------ #include <io.h> [UNIX] #include <sys/stat.h> int chmod (const char *name, int pmode); Change permission settings of the file named NAME to PMODE. There's only one permission bit under OS/2 and DOS, the read-only attribute. Return value: 0 success -1 failure Restriction: Only the S_IWRITE bit of PMODE is used. See also: creat(), open(), stat(), umask() ------------------------------------------------------------------------------ #include <io.h> [PC] int chsize (int handle, long size); Change the length of the file associated with HANDLE to LENGTH bytes. The position of the file pointer is undefined after calling this function. If LENGTH is greater than the current length of the file, bytes of zeros are appended. HANDLE must be open for writing. If successful, 0 is returned. Otherwise, -1 is returned. See also: ftruncate() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] void clearerr (FILE *stream); Clear the error and end-of-file indicators of STREAM. See also: ferror(), feof() ------------------------------------------------------------------------------ #include <time.h> [ANSI] clock_t clock (void); clock() returns the amount of processor time (timer ticks) used by the calling process since the process has been started. There are CLOCKS_PER_SEC timer ticks per second. Restriction: clock() returns the time elapsed, not the CPU time. See also: time() ------------------------------------------------------------------------------ #include <io.h> [UNIX] int close (int handle); Close the file associated with the handle HANDLE. If successful, 0 is returned, -1 if not. See also: dup(), open() ------------------------------------------------------------------------------ #include <stdlib.h> [*] [emx] int _core (int handle); Write a core dump to the file HANDLE. HANDLE must be open for writing. The core dump file can be used later for debugging or for creating another .exe file which includes the data as saved when _core() was called. Restriction: _core() works only in programs linked with ld. It does not work in programs linked with LINK386. When using the system call library libsys.lib (-Zsys), _core() is not available. See also: raise() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double cos (double x); double sin (double x); double tan (double x); Compute the sine, cosine and tangent of X, respectively. If the absolute value of x is greater than or equal to 2^63, #NAN is returned and errno set to EDOM. See also: acos(), asin(), atan() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double cosh (double x); double sinh (double x); double tanh (double x); Compute the hyperbolic sine, hyperbolic cosine and hyperbolic tangent of X, respectively. On overflow, #INF is returned and errno set to ERANGE. See also: exp() ------------------------------------------------------------------------------ #include <io.h> [UNIX] #include <sys/stat.h> int creat (const char *name, int pmode); Create a file named NAME with permission settings PMODE. This is equivalent to open (name, O_WRONLY|O_TRUNC|O_CREAT, pmode) See also: open() ------------------------------------------------------------------------------ #include <io.h> [emx] int _crlf (char *buf, size_t size, size_t *new_size); Translate CR/LF pairs to LF characters. The conversion is done in-place in the buffer BUF of size SIZE. The new size is stored to *NEW_SIZE. If the buffer ends with a CR, 1 is returned. Otherwise, 0 is returned. See also: fread(), _fsetmode(), read(), setmode() ------------------------------------------------------------------------------ [OS/2] int _CRT_init (void); void _CRT_term (void); These two functions are provided for being called from _DLL_InitTerm(), the DLL initialization and termination function. _CRT_init() initializes the C run-time library. On success, 0 is returned. On failure, -1 is returned. _CRT_term() terminates the C run-time library. Example: /emx/test/testdll1.c See also: _DLL_InitTerm() ------------------------------------------------------------------------------ #include <time.h> [ANSI] char *ctime (const time_t *t); Convert the number of seconds elapsed since 00:00 GMT 1-Jan-1970 given by the variable pointed to by T to a string representing that moment for the local timezone. A pointer to the string is returned. There is only one memory location for the ctime() and asctime() results, a call to ctime() or asctime() overwrites the result of a previous calls to ctime() or asctime(). As localtime() is called by ctime(), the memory location shared by localtime(), gmtime(), and mktime() is overwritten. The string looks like "Sun Mar 22 22:59:18 1992\n" with a terminating 0. All fields have fixed width. See also: asctime() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] void _defext (char *dst, const char *ext); Add the default extension EXT to the file name DST. If the file name part of DST contains an extension (including the empty extension), nothing will be done. Otherwise, a dot and EXT will be appended. See also: _getext(), _remext(), _splitpath() ------------------------------------------------------------------------------ #include <time.h> [ANSI] double difftime (time_t t1, time_t t0); Return the difference (in seconds) T1-T0 between T0 and T1. ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] div_t div (int num, int den); ldiv_t ldiv (long num, long den); Perform an integer division, dividing NUM by DEN. The quotient and the remainder are returned in the quot and rem fields, respectively. The following table shows the signs of quot and rem depending on the signs of NUM and DEN: NUM DEN | quot rem --------+--------- + + | + + + - | - + - + | - - - - | + - See also: _lldiv(), _uldiv(), _ulldiv() ------------------------------------------------------------------------------ [OS/2] unsigned long _DLL_InitTerm (unsigned long mod_handle, unsigned long flag); _DLL_InitTerm is the library initialization and termination function for dynamic link libraries. It is called by the operating system to initialize the library (if FLAG is zero) or to terminate the library (if FLAG is one). MOD_HANDLE is the module handle of the dynamic link library. _DLL_InitTerm() should return 1 to indicate success. On failure, 0 should be returned. The default _DLL_InitTerm() function does nothing but returning 1. To initialize the C library, you have to write an _DLL_InitTerm() function which calls _CRT_init(). Example: /emx/test/testdll1.c See also: _CRT_init(), _CRT_term() ------------------------------------------------------------------------------ #include <sys/dirtree.h> [emx] void _dt_free (struct _dt_tree *dt); Deallocate the memory allocated by _dt_read() for the directory tree DT. See also: _dt_read() ------------------------------------------------------------------------------ #include <sys/dirtree.h> [emx] struct _dt_tree *_dt_read (const char *dir, const char *mask, unsigned flags); Create a directory tree in memory. The tree consists of a linked list of _dt_node structures. Subtrees are attached to the SUB field of _dt_node structures for directories. Files matching MASK in the directory DIR are put into the tree. If FLAGS includes _DT_TREE, all subdirectories of DIR are also scanned for files and directories matching MASK. If _DT_TREE is not included, the subdirectories of DIR are not scanned. If FLAGS includes _DT_NOCPDIR, the `.' and `..' entries are omitted. If successful, _dt_read() returns a pointer to a _dt_tree structure. The TREE field of that structure is the root of the tree. On error, the errno variable is set and NULL is returned. _fnlwr() is used to convert file names to lower case on upper-case-only file systems. Example: /emx/test/dttest.c See also: _dt_free(), _dt_sort(), _dt_split(), _fnlwr(), _fnexplode() ------------------------------------------------------------------------------ #include <sys/dirtree.h> [emx] void _dt_sort (struct _dt_tree *dt, const char *spec); Sort the directory tree DT according to SPEC. DT is a directory tree created by _dt_read(). SPEC is a string of characters which is read from left to right. Each character tells _dt_sort() how to compare two tree nodes. If the nodes compare equal, the next character is examined. This is repeated until the two nodes are different according to the sorting criterion indicated by a character of SPEC or the end of the SPEC string is reached. If the end of the SPEC string is reached, the two nodes are considered equal and the two nodes are put in an arbitrary order. The following characters of SPEC are defined: e File name extensions are compared, ascending ASCII order E File name extensions are compared, descending ASCII order f Directories are placed before files F Files are placed before directories n File names are compared, ascending ASCII order N File names are compared, descending ASCII order s File size is compared, ascending S File size is compared, descending t Time stamps (last modification) are compared, ascending T Time stamps (last modification) are compared, descending All other characters are ignored. _fncmp() is used for comparing file names. If _fncmp() returns 0, strcmp() is used in addition. strcmp() can return a non-zero value only if the current code page doesn't match the code page used when creating the directory entries. See also: _dt_read(), _fncmp() ------------------------------------------------------------------------------ #include <sys/dirtree.h> [emx] int _dt_split (const char *src, char *dir, char *mask); Split the path name SRC into a directory part and a name part for _dt_read(). The directory part is stored to DIR, the name part is stored to MASK. If SRC is a directory, MASK is set to "*". See also: _dt_read() ------------------------------------------------------------------------------ #include <io.h> [UNIX] int dup (int handle); int dup2 (int handle1, int handle2); Create a duplicate of the file handle HANDLE or HANDLE1, respectively, that is, another handle that refers to the same file or device or pipe as the handle given. Both handles share the same file pointer. dup() chooses the lowest numbered available handle. dup2() uses HANDLE2 for the new file handle. If HANDLE2 is open when dup2() is called, it is closed by dup2(). If there is an error, -1 is returned. Otherwise, the new file handle is returned. Restriction: dup2() currently doesn't work correctly under DOS. See also: close(), fcntl(), open() ------------------------------------------------------------------------------ #include <sys/ea.h> [emx] void _ea_free (struct _ea *ptr); Free the memory allocated for the value of an extended attribute stored in the structure pointed to by PTR. If the VALUE field of the structure is non-NULL, free() is called for that pointer. Then, the VALUE field is set to NULL. See also: _ea_get() ------------------------------------------------------------------------------ #include <sys/ea.h> [emx] int _ea_get (struct _ea *dst, const char *path, int handle, const char *name); Retrieve the extended attribute NAME of a file or directory. If PATH is non-NULL, an extended attribute of the file or directory named by PATH is retrieved. Otherwise, an extended attribute of the file referred to by HANDLE is retrieved. The letter case of NAME is ignored. The flags, the value and the size of the value of the extended attribute is copied to DST. If there is an error, errno is set and -1 is returned. Otherwise, 0 is returned. If the extended attribute NAME does not exist, 0 is returned, the SIZE field of DST is set to 0 and the VALUE field of DST is set to NULL. _ea_get() allocates memory for the value of the extended attribute by calling malloc(). The structure declaration is: struct _ea { int flags; int size; void *value; }; The FLAGS field contains the flags byte of the extended attribute (only bits 0 through 7 of FLAGS are used). Currently, OS/2 defines only bit 7: it's set for critical EAs. SIZE is the length of the value in bytes. The VALUE field points to the (binary) value of the extended attribute. Use _ead_read() to retrieve all the extended attributes of a file or directory. See also: _ea_free(), _ea_put(), _ead_read() ------------------------------------------------------------------------------ #include <sys/ea.h> [emx] int _ea_put (struct _ea *src, const char *path, int handle, const char *name); Add an extended attribute to a file or directory. If PATH is non-NULL, the extended attribute is added to the file or directory named by PATH. Otherwise, the extended attribute is added to the file referred to by HANDLE which must be open for writing. NAME is the name of the extended attribute. The letter case of NAME is ignored. SRC points to an _ea structure which holds the flags, size and value of the extended attribute to be added. If the SIZE field is 0, the extended attribute is removed. Bits 0 though 7 of FLAGS contain the flags byte for the extended attribute. Currently, OS/2 defines only bit: it's the critical EA bit. The FLAGS field should be zero unless you exactly know what you're doing. If there is an error, errno is set and -1 is returned. Otherwise, 0 is returned. Use _ead_write() to replace or update multiple extended attributes at once. See also: _ea_get(), _ea_remove(), _ead_write() ------------------------------------------------------------------------------ #include <sys/ea.h> [emx] int _ea_remove (const char *path, int handle, const char *name); Remove the extended attribute named NAME from a file or directory. If PATH is non-NULL, the extended attribute is removed from the file or directory named by PATH. Otherwise, the extended attribute is removed from the file referred to by HANDLE. The letter case of NAME is ignored. If there is an error, errno is set and -1 is returned. Otherwise, 0 is returned. Removing a non-existing extended attribute of an existing file or directory is not an error. See also: _ea_put(), _ead_write() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_add (_ead ead, const char *name, int flags, const void *value, int size); Add the extended attribute NAME to the extended attributes descriptor EAD. NAME should be a null-terminated string. The value of the extended attribute is set to SIZE bytes of VALUE. The flags byte of the extended attribute is set to FLAGS. Only bits 0 through 7 of FLAGS are used. Currently, OS/2 defines only bit 7 of the flags byte: it's the critical EA bit. FLAGS should be zero unless you exactly know what you're doing. If an extended attribute named NAME already exists in EAD, it is updated with FLAGS, SIZE and VALUE. If there is an error, errno is set and a negative value is returned. On success, the index of the new (or updated) extended attribute is returned. The extended attributes on disk are not affected. After calling _ead_add(), the pointers returned by previous invocations of _ead_get_fea2list(), _ead_get_name() and _ead_get_value() will be invalid. As _ead_add() does a case-sensitive search, you should pass an upper-case names in NAME. If there are two extended attributes in an extended attributes descriptor whose names differ only in letter case, only one of both will be written to the disk by _ead_write(). See also: _ead_delete(), _ead_replace(), _ead_write(), _nls_strupr() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] _ead _ead_clear (_ead ead); Discard the extended attributes of the extended attributes descriptor EAD. After calling _ead_clear(), _ead_count() will return 0 for EAD. The extended attributes on disk are not modified. After calling _ead_clear(), do not use pointers returned by _ead_get_name(), _ead_get_value() and _ead_get_fea2list() for that descriptor. See also: _ead_create(), _ead_destroy(), _ead_read() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_copy (_ead dst_ead, _ead src_ead, int src_index); Copy the extended attribute SRC_INDEX from the extended attributes descriptor SRC_EAD to the extended attributes descriptor DST_EAD. If SRC_INDEX is 0, all extended attributes of SRC_EAD are copied to DST_EAD. Otherwise, SRC_INDEX must be a number between 1 and the number of extended attributes of SRC_EAD. _ead_copy() uses _ead_add() to copy the extended attributes. The extended attributes on disk are not affected. See also: _ead_add() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_count (_ead ead); Return the number of extended attributes available from the extended attributes descriptor EAD. See also: _ead_create(), _ead_get_name(), _ead_get_value() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] _ead _ead_create (void) Create an extended attributes descriptor. Such a descriptor is used for handling the extended attributes of files and directories. If successful, _ead_create() returns a descriptor which can be used by the other functions for handling extended attributes. Otherwise, errno is set and NULL is returned. Use _ead_destroy() if you no longer need the descriptor. To copy all the extended attributes of a file or a directory to an extended attributes descriptor, use _ead_read(). Initially, no extended attributes are held by an extended attributes descriptor. Example: /emx/test/eatool.c See also: _ead_destroy(), _ead_get_name(), _ead_get_value(), _ead_read() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_delete (_ead ead, int index); Delete the extended attribute INDEX from the extended attributes descriptor EAD. INDEX must be a number between 1 and the number of extended attributes of EAD. If successful, this function returns 0. Otherwise, errno is set and a negative number is returned. After calling _ead_delete(), the pointers returned by previous invocations of _ead_get_fea2list(), _ead_get_name() and _ead_get_value() will be invalid. Moreover, _ead_delete() invalidates index numbers. See also: _ead_add(), _ead_find() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] void _ead_destroy (_ead ead); Invalidate the extended attributes descriptor EAD which has been created by _ead_create(). All memory associated with EAD is released. EAD must not be NULL. After calling _ead_destroy(), EAD is invalid and can no longer be used. After calling _ead_destroy(), do not use pointers returned by _ead_get_name(), _ead_get_value() and _ead_get_fea2list() for that descriptor. See also: _ead_clear(), _ead_create() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_fea2list_size (_ead ead); Return the size of the FEA2LIST of the extended attributes descriptor EAD. If EAD doesn't hold any extended attributes, 0 is returned. See also: _ead_get_fea2list() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] void *_ead_fea2list_to_fealist (const void *src); Convert the FEA2LIST SRC (OS/2 2.0 format) to a FEALIST (OS/2 1.2 format). SRC must not be NULL. This function allocates memory with malloc() to hold the converted list. A pointer to the converted list is returned. If you no longer need the buffer allocated by this function, you should deallocate it with free(). If there is an error, errno is set and NULL is returned. SRC is of type PFEA2LIST, the return value is of type PFEALIST. To avoid having to include os2.h when including ead.h, void pointers are used instead. See also: _ead_fealist_to_fea2list(), _ead_get_fea2list() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] void *_ead_fealist_to_fea2list (const void *src); Convert the FEALIST SRC (OS/2 1.2 format) to a FEA2LIST (OS/2 2.0 format). SRC must not be NULL. This function allocates memory with malloc() to hold the converted list. A pointer to the converted list is returned. If you no longer need the buffer allocated by this function, you should deallocate it with free(). If there is an error, errno is set and NULL is returned. SRC is of type PFEALIST, the return value is of type PFEA2LIST. To avoid having to include os2.h when including ead.h, void pointers are used instead. See also: _ead_fea2list_to_fea2list() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_find (_ead ead, const char *name); Return the index of the extended attribute named NAME of the extended attributes descriptor EAD. NAME should be a null-terminated string. If there is no such extended attribute, errno is set to ENOENT and -1 is returned. Otherwise, a number between 1 and the number of extended attributes of EAD is returned. Note that OS/2 converts names of extended attributes to upper case when writing them to the disk. As _ead_find() does a case-sensitive compare, lower-case names are not found. See also: _ead_count(), _ead_get_name(), _ead_get_value(), _nls_strupr() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] const void *_ead_get_fea2list (_ead ead); Return a pointer to the FEA2LIST of the extended attributes descriptor EAD. You should cast the return value to PFEA2LIST. The return type of _ead_get_fea2list() is not PFEA2LIST to be able to include ead.h without having to include os2.h. The pointer points to memory allocated by the extended attributes functions -- do not use the pointer after calling _ead_add(), _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or _ead_replace() and do not write to the buffer. See also: _ead_fea2list_size(), _ead_fea2list_to_fealist() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_get_flags (_ead ead, int index); Return the flags byte of the extended attribute INDEX of the extended attributes descriptor EAD. INDEX must be a number between 1 and the number of extended attributes of EAD. On error, errno is set and -1 is returned. See also: _ead_count(), _ead_get_value() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] const char *_ead_get_name (_ead ead, int index); Return a pointer to the name of the extended attribute INDEX of the extended attributes descriptor EAD. INDEX must be a number between 1 and the number of extended attributes of EAD. The pointer points to memory allocated by the extended attributes functions -- do not use the pointer after calling _ead_add(), _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or _ead_replace() and do not write to the buffer. On error, errno is set and NULL is returned. See also: _ead_count(), _ead_name_len() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] const void *_ead_get_value (_ead ead, int index); Return a pointer to the value of the extended attribute INDEX of the extended attributes descriptor EAD. INDEX must be a number between 1 and the number of extended attributes of EAD. The pointer points to memory allocated by the extended attributes functions -- do not use the pointer after calling _ead_add(), _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or _ead_replace() and do not write to the buffer. On error, errno is set and NULL is returned. See also: _ead_count(), _ead_find(), _ead_get_flags(), _ead_value_size() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_name_len (_ead ead, int index); Return the length of the name of the extended attribute INDEX of the extended attributes descriptor EAD. If INDEX is 0, the total length of all the names is returned, not including the terminating null characters. Otherwise, INDEX must be a number between 1 and the number of extended attributes of EAD; the length of the name of the INDEXth extended attribute is returned. The terminating null character is not included in the length. On error, errno is set and -1 is returned. See also: _ead_count(), _ead_get_name() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] _ead _ead_read (_ead ead, const char *path, int handle, int flags); Copy the extended attributes of a file or directory to the extended attributes descriptor EAD. The extended attributes held previously by EAD are discarded. If PATH is not NULL, the extended attributes of that path name (file or directory) are copied to EAD. If PATH is NULL, the extended attributes of the file referred to by the file handle HANDLE are copied to EAD. FLAGS is not yet used and must be 0. If successful, _ead_read() returns zero. Otherwise, errno is set and a negative number is returned. _ead_read() calls _ead_clear(), reads all the extended attributes and stores them in memory. Use _ead_destroy() to deallocate that memory and invalidate EAD. When using a non-NULL PATH, _ead_read() does not lock the file while while reading the extended attributes. You might want to open a handle in deny-write mode and pass it in HANDLE to avoid problems due to other threads or processes modifying the extended attributes while _ead_read() is reading. This doesn't work with and isn't required for directories. _ead_read() can also be used under DOS though no extended attributes will be copied. Therefore, your program doesn't have to decide whether to use these functions or not. Use _ea_get() to retrieve extended attributes one by one. See also: _ea_get(), _ead_create(), _ead_destroy(), _ead_get_name(), _ead_get_value() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_replace (_ead ead, int index, int flags, const void *value, int size); Update the extended attribute INDEX of the extended attributes descriptor EAD with FLAGS and SIZE bytes of VALUE. INDEX must be a number between 1 and the number of extended attributes of EAD. On success, _ead_replace() returns 0. On error, errno is set and a negative value is returned. The extended attributes on disk are not affected. After calling _ead_replace(), the pointers returned by previous invocations of _ead_get_fea2list(), _ead_get_name() and _ead_get_value() will be invalid. See also: _ead_add(), _ead_write() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] void _ead_sort (_ead ead); Sort by name the extended attributes of the extended attributes descriptor EAD. Sorting is done in memory -- the extended attributes on disk are not affected. After calling _ead_sort(), index 1 refers to the extended attribute with the lexically smallest name. strcmp() is used for comparing names. _ead_sort() sorts the index, not the extended attributes proper. Therefore, all functions that modify the extended attributes of EAD undo the effect of _ead_sort(). See also: _ead_create(), _ead_get_name(), _ead_read() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_use_fea2list (_ead ead, const void *src); Copy all the extended attributes from the FEA2LIST SRC (OS/2 2.0 format) to the extended attributes descriptor EAD. All extended attributes previously held by EAD are discarded. The extended attributes on the disk are not affected. If successful, _ead_use_fea2list() returns 0. Otherwise, errno is set and a negative value is returned. See also: _ead_write() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_value_size (_ead ead, int index); Return the size of the extended attribute INDEX of the extended attributes descriptor EAD. If INDEX is 0, the total size of all the values of EAD is returned. Otherwise, INDEX must be a number between 1 and the number of extended attributes of EAD; the size of the INDEXth extended attribute is returned. On error, errno is set and -1 is returned. See also: _ead_count(), _ead_get_value() ------------------------------------------------------------------------------ #include <sys/ead.h> [emx] int _ead_write (_ead ead, const char *path, int handle, int flags); Write all the extended attributes of the extended attributes descriptor EAD to the file or directory PATH or HANDLE. The extended attributes previously attached to that file or directory are discarded and replaced by the extended attributes of EAD if FLAGS is 0. This is done by deleting the extended attributes of the file or directory which are not in EAD. If FLAGS is _EAD_MERGE, the extended attributes of the file or directory which are also present in EAD are replaced by those of EAD. Extended attributes of EAD which are not attached to the file or directory are added to the extended attributes of the file or directory. If PATH is non-NULL, the extended attributes are written to the file or directory specified by the path name PATH. If PATH is NULL, the extended attributes are written to the file referred to by the file handle HANDLE. The extended attributes of EAD are not modified. If _ead_write() is successful, 0 is returned. Otherwise, errno is set and a negative value is returned. Under DOS, _ead_write() does nothing and always returns 0. Use _ea_put() to add or update extended attributes one by one. See also: _ea_put(), _ead_clear(), _ead_read(), _ead_use_fea2list() ------------------------------------------------------------------------------ #include <os2.h> [emx] void *_emx_16to32 (_far16ptr ptr); _far16ptr _emx_32to16 (void *ptr); _emx_16to32 converts a 16-bit far pointer (16:16 format) to a 32-bit flat pointer. _emx_32to16 converts a 32-bit flat pointer to a 16-bit far pointer (16:16 format). The type _far16ptr is used for 16-bit far pointers. ------------------------------------------------------------------------------ #include <stdlib.h> [PC] void _endthread (void); A thread that has been created by _beginthread() can call _endthread() to end its execution. A thread also ends when the function started with _beginthread() returns. Terminating the main thread (thread 1) of a process terminates the process (return value will be 0). Do not use DosExit to end a thread started by _beginthread(). _endthread() is available only when using emxlibc.dll (-Zmt). See also: _beginthread () ------------------------------------------------------------------------------ #include <io.h> [PC] int eof (int handle); Return 1 if the current position of HANDLE is at the end of the file, return 0 otherwise. On failure, -1 is returned. ------------------------------------------------------------------------------ #include <process.h> [UNIX] /* exec () */ int execl (const char *name, const char *arg0, ...); int execle (const char *name, const char *arg0, ...); int execlp (const char *name, const char *arg0, ...); int execlpe (const char *name, const char *arg0, ...); int execv (const char *name, const char * const *argv); int execve (const char *name, const char * const *argv, const char * const *envp); int execvp (const char *name, const char * const *argv); int execvpe(const char *name, const char * const *argv, const char * const *envp); Replace calling process with a new process. The calling process terminates after starting the new process. NAME is the name of the executable file to run. Use execl(), execle(), execlp() or execlpe() for passing a fixed number of arguments. ARG0 is the 0th argument which is the program name, by convention. Following ARG0, the arguments are given. After the last argument, a NULL pointer must be following. At least ARG0 must be specified. Use execv(), execve(), execvp() or execvpe() for passing a variable number of arguments. ARGV points to an array of strings. The first entry is the program name, by convention. The last argument must be followed by a NULL pointer. execl(), execlp(), execv() and execvp() pass the environment of the current process to the child process. To pass a different environment to the child process pass a pointer to an array of strings after the NULL argument pointer of execle() and execlpe() or pass the pointer in the ENVP argument of execve() and execvpe(). The last environment string in the array must be followed by a NULL pointer. When the new process ends, the parent process is notified by SIGCLD and wait() will return the original process ID. Return value: the return value is -1 if an error occurs. On success, these functions do not return. Restrictions: Native DOS programs cannot be run. The new process gets a new process ID. All signals are reset to SIG_DFL in the new process. See also: spawn() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void volatile exit (int ret); Flush streams, remove temporary files, call functions set by atexit() and terminate the current process. The return code RET is passed to the parent process. If RET is negative or greater than 255, 255 will be used instead to avoid returning 0 (success) for non-zero RET due to truncation to 8 bits. See also: abort(), atexit(), _exit() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] void volatile _exit (int ret); Exit without flushing streams, removing temporary files or calling functions set by atexit(). The return code RET is passed to the parent process. If RET is negative or greater than 255, 255 will be used instead to avoid returning 0 (success) for non-zero RET due to truncation to 8 bits. See also: abort(), atexit(), exit() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double exp (double x); exp() computes the exponential function of X, e^X is returned. On overflow, +#INF is returned and errno set to ERANGE. See also: log(), pow() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] void *_expand (void *mem, size_t new_size); Try to expand the memory block pointed to by MEM to the new size NEW_SIZE. If the block cannot be expanded, NULL is returned. Otherwise, MEM is returned. Please do not use this function -- use realloc() instead. See also: realloc() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double fabs (double x); Return the absolute value of X: If X is negative, -X is returned. Otherwise, X is returned. See also: abs(), labs() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fclose (FILE *stream); Close the open stream STREAM. Return 0 if successful, EOF otherwise. See also: fcloseall(), fflush(), fopen() ------------------------------------------------------------------------------ #include <stdio.h> [PC] int fcloseall (void); Close all open streams. Return the number streams closed or EOF if an error occurs. See also: fclose(), flushall(), fopen() ------------------------------------------------------------------------------ #include <fcntl.h> [*] [BSD] int fcntl (int handle, int request, int arg); File control. The following two REQUEST codes are implemented (partially): F_GETFL Return the file flags of the file specified by HANDLE. Currently, only two file flags are supported by fcntl: O_APPEND and O_NDELAY. F_SETFL Set the file flags of the file specified by HANDLE. Currently, only two file flags are supported by fcntl: O_APPEND and O_NDELAY. O_NDELAY has an effect only if HANDLE is 0 and HANDLE refers to the keyboard and the IDEFAULT and ICANON bits are not set. O_NDELAY also works for pipes created by emx programs and for named pipes. See `termio' and read(). F_GETFD Return close-on-exec flag in bit 0 of return value. If the bit is set, HANDLE will not be inherited by child processes. F_SETFD Set close-on-exec flag from bit 0 of ARG. If the bit is set, HANDLE will not be inherited by child processes. Restrictions: F_GETFD and F_SETFD are not implemented under DOS. When using the system call library libsys.lib (-Zsys), O_NDELAY is not supported. See also: dup(), ioctl(), open() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] FILE *fdopen (int handle, const char *mode); Create a stream for the low-level file handle HANDLE. The MODE flags should match the mode used for opening the file handle HANDLE. If `b' or `t' is used in MODE, the handle will be changed using setmode() to O_BINARY or O_TEXT mode, respectively. If neither `b' nor `t' is used, the translation mode is not changed. You should not rely on this behaviour: always specify the desired translation mode. A future release of the C library will have independent modes for low-level files and streams. If fdopen() fails, NULL is returned. See also: fopen(), open() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int ferror (FILE *stream); int feof (FILE *stream); ferror() returns a non-zero value if the error indicator of STREAM is set. feof() returns a non-zero value if the end-of-file indicator of STREAM is set. See also: clearerr() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fflush (FILE *stream); Write the buffer of STREAM to its file if STREAM is open for writing. Clear the buffer of STREAM if STREAM is open for reading. The effect of ungetc() is undone. Return value: 0 success EOF failure See also: fclose() ------------------------------------------------------------------------------ #include <strings.h> [BSD] int ffs (int i); Find the first bit set in I and return the index of that bit. The least significant bit is numbered 1, the most significant bit is numbered 32. The smallest number n is returned for which bit n is set in I. If there are no bits set in I (that is, I is zero), zero is returned. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fgetc (FILE *stream); Read a character from STREAM. The character is returned. If an error occurs or if the end of the file is reached, EOF is returned. fgetc() is a function. See also: fgetchar(), getc(), getchar() ------------------------------------------------------------------------------ #include <stdio.h> [PC] int fgetchar (void); Read a character from stdin, respectively. The character is returned. If an error occurs or if the end of the file is reached, EOF is returned. fgetchar () is equivalent to fgetc (stdin). fgetchar() is a function. See also: fgetc(), getchar() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fgetpos (FILE *stream, fpos_t *pos); Store the current position of the file pointer of the file STREAM in the variable pointed to by POS. fgetpos() currently does not work with text-mode files. See also: fsetpos(), ftell() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] char *fgets (char *buffer, int n, FILE *stream); Read a string from STREAM to BUFFER. Stop after reading N-1 characters or after a newline (LF) character has been read. A null character is appended. fgets() returns BUFFER. If an error occurs or the end of the file is reached, fgets() returns NULL. See also: gets(), scanf() ------------------------------------------------------------------------------ #include <io.h> [PC] long filelength (int handle); Return the length in bytes of the file HANDLE. If there is an error, -1 is returned. See also: chsize(), ftruncate(), lseek() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int fileno (FILE *stream); fileno() returns the file handle associated with STREAM. See also: fdopen() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _filesys (const char *drive, char *name, size_t size); Copy the file system type of DRIVE to the buffer NAME. The size of the buffer is SIZE bytes. DRIVE must point to a drive letter followed by a colon. Examples for file system types are: FAT, LAN, HPFS, CDFS, NFS. Return value: 0 success. The file system type has been copied to NAME. -1 failure. errno contains the error number. Example: char drive[3] = "C:"; char fsys[16]; if (_filesys (drive, fsys, sizeof (fsys)) != 0) perror ("_filesys"); else printf ("File system: %s\n", fsys); Typical output of the example: File system: FAT See also: _fnlwr() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double floor (double x); Return as floating-point number the largest integer that is less than or equal to X (round down). See also: ceil(), rint(), trunc() ------------------------------------------------------------------------------ #include <stdio.h> [PC] int flushall (void); Flush the buffers of all open streams. Write the buffers of streams open for writing to their files, clear the buffers of streams open for reading. The number of open streams is returned. See also: fflush() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double fmod (double x, double y); Compute remainder of X/Y. The return value z is calculated such that X = i * Y + z, where i is an integer, z has the same sign as X and |z| < |Y|. fmod (x, 0.0) returns 0.0. ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _fncmp (const unsigned char *string1, const unsigned char *string2); _fncmp() compares the two file name strings STRING1 and STRING2 and returns zero if the two strings are identical after conversion to upper case. Otherwise, a non-zero value is returned which is negative if STRING1 is less than STRING2 and positive if STRING1 is greater than STRING2 after conversion to upper case. Conversion to upper case includes accented characters etc., depending on the current country code and code page. If _nls_init() has not yet been called, it is called by _fncmp(). See also: _nls_init(), _nls_strupr(), strcmp() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char **_fnexplode (const char *mask); void _fnexplodefree (char **list); Wildcard expansion of MASK. _fnexplode() returns a vector containing pointers to the file names. The list includes directories. Hidden and system files are omitted. The end of the list is marked by a NULL pointer. On error, NULL is returned. Memory is allocated with malloc(). _fnlwr() is used to convert file names to lower case on upper-case-only file systems. Use _fnexplodefree() to free the memory allocated for a file name list. Example: /emx/test/eatool.c See also: _dt_read(), _fnlwr(), opendir(), _wildcard() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char _fngetdrive (const char *src); Return as upper-case letter the drive name given in the path name SRC. If SRC does not contain a drive name, _fngetdrive() returns 0. Example: char *fname, drive; drive = _fngetdrive (fname); if (drive == 0) drive = _getdrive (); ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _fnisabs (const char *name); Return a non-zero value if NAME is an absolute file name. Otherwise, return 0. Absolute file names start with \ or /, optionally preceded by a drive name. See also: _abspath() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] void _fnlwr (char *name); void _rfnlwr (void); void _sfnlwr (const char *name); _fnlwr() converts the file name NAME to lower case unless the file system is case preserving. Accented characters etc. are converted as well. If NAME does not contain a drive letter, it is assumed to refer to the drive set by _sfnlwr(). To save time, _fnlwr() caches information about file systems. If the file system of a drive changes or if the current drive changes, you should call _rfnlwr() to reset the cache. _sfnlwr() takes the drive name from NAME for future _fnlwr() calls. If _sfnlwr() hasn't been called since the last call to _rfnlwr() or if NAME does not contain a drive letter, _fnlwr() uses the current drive. If _nls_init() has not yet been called, it is called by _fnlwr(). See also: _filesys(), _nls_init(), _nls_strlwr() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] FILE *fopen (const char *fname, const char *mode); Open a stream. FNAME is the name of the file, MODE is a string which specifies the file mode. The first character of MODE is `r' for reading, `w' for writing or `a' for appending. If a `+' character follows `a' or `w', the file will be also opened for reading. There are two additional MODE flags: `t' for text mode, `b' for binary mode. Text mode, which is the default, skips CR characters on input and converts LF characters to CR/LF pairs on output. Ctrl-Z on input indicates EOF. Binary mode disables these transformations. The file is opened in the sharing mode SH_DENYNO, see sopen(). If you want to use a different sharing mode, use _fsopen(). See also: fclose(), fdopen(), freopen(), _fsopen(), sopen() ------------------------------------------------------------------------------ #include <process.h> [*] [UNIX] int fork (void); Duplicate current process. A child process is created which is a copy of the calling process. Both the parent process and the child process resume at the point where fork() was called. The child process inherits the following attributes of the parent process: - environment - memory - signal settings (function address or SIG_DFL or SIG_IGN) - file handles (unless private, see fcntl()) - current working directories - umask - break points. This is an OS/2 bug. When debugging a program containing fork(), set a breakpoint in the branch of execution that's executed only in the parent process The new process differs from the parent process in the following ways: - the child process has a unique process ID - the child process has a different parent process ID (the process ID of the parent process) - the child process has copies of the file descriptors of the parent process. The file pointers are shared - termio is turned off in child process - all resources allocated using OS/2 calls are not inherited by the child process: semaphores, queues, threads, memory, file handles, etc. - the alarm clock is turned off - the CPU time (returned by clock()) is set to 0 When the new process terminates, SIGCLD is raised in the process which forked that process. On error, -1 is returned. On success, the process ID of the new process is returned to the calling process, 0 to the new process. Restrictions: fork() is not implemented for DOS. fork() works only in programs linked by ld. It does not work in programs linked by LINK386. When using the system call library libsys.lib (-Zsys), fork() is not available. fork() is very inefficient for OS/2. To start a child process, use spawn() instead of fork() and exec(). Private file handles (see fcntl()) are not inherited by the child process. If the parent process uses termio for the keyboard, the child process cannot read from the keyboard using _read_kbd(), termio or the Kbd OS/2 API functions. See also: alarm(), fcntl(), spawn() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fprintf (FILE *stream, const char *format, ...); Formatted output to the stream STREAM. On success, the number of characters written to STREAM is returned. Otherwise, EOF is returned. See also: fscanf(), printf() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fputc (int c, FILE *stream); Write the character C to STREAM. The character written is returned. On failure, EOF is returned. fputc() is a functions. See also: fprintf(), fputchar(), fputs(), putc(), putchar() ------------------------------------------------------------------------------ #include <stdio.h> [PC] int fputchar (int c); Write the character C to stdout. fputchar (c) is equivalent to fputc (c, stdout). The character written is returned. On failure, EOF is returned. fputchar() is a function. See also: fputc(), putchar() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fputs (const char *string, FILE *stream); Write the string STRING to STREAM. On failure, EOF is returned. Otherwise, a non-negative value is returned. In contrast to puts(), a LF character is not appended automatically. See also: fgets(), fputc(), printf(), puts() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] size_t fread (void *buffer, size_t size, size_t count, FILE *stream); Read COUNT objects of SIZE bytes each from STREAM to BUFFER. The file pointer is incremented by the number of bytes read. The number of complete objects read is returned which may be less than COUNT, for instance 0, if an error occurs or if the end of the file is reached. Use ferror() and feof() to distinguish between these two conditions. On failure, the position of the file pointer is undefined. If STREAM has been opened in text mode, CR/LF pairs are translated to LF characters. This translation does not affect the return value -- SIZE and COUNT are applied after translation. See also: fgetc(), fgets(), fwrite() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void free (void *mem); Deallocate a block of memory allocated by malloc(), calloc() or realloc(). MEM points to the block of memory. MEM must have been returned by malloc(), calloc() or realloc(). Do not use MEM after calling free(). See also: calloc(), malloc(), realloc() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] FILE *freopen (const char *fname, const char *mode, FILE *stream); Close and reopen STREAM. The file FNAME will be opened in mode MODE. See fopen() for details. If successful, a pointer to the new stream is returned. Otherwise, NULL is returned. See also: fclose(), fopen() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double frexp (double x, int *exp_ptr); Extract mantissa and exponent of X. The mantissa is returned, the exponent, an integer, is stored to *EXP_PTR. The following holds for the mantissa m: 0.5 <= |m| < 1.0. If X is zero, both the mantissa and the exponent are 0. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fscanf (FILE *stream, const char *format, ...); The stream STREAM is read and input is parsed according to the format string FORMAT. For each field in FORMAT there must be a pointer to the location receiving the value. The pointers are passed after the FORMAT argument. On success, the number of fields converted is returned. Otherwise, EOF is returned. See also: fprintf(), scanf() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fseek (FILE *stream, long offset, int origin); fseek() moves the file pointer of STREAM. The new position OFFSET is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is relative to the current position, if ORIGIN is SEEK_END, OFFSET is relative to the end of the file. The file pointer cannot be moved before the beginning of the file. fseek() does not work with text-mode files. On success, 0 is returned. On error, a non-zero value is returned. See also: fgetpos(), fsetpos(), ftell(), rewind() ------------------------------------------------------------------------------ #include <stdio.h> [emx] int _fseek_hdr (FILE *stream); Move the file pointer of STREAM to the a.out header of an executable file (a.out or bound .exe). _fseek_hdr() assumes that the file pointer points to the beginning of the header (ie, the beginning of the file). If there is an error, _fseek_hdr() sets errno and returns -1. If no header is found, the file pointer will be repositioned to the original position. See also: _seek_hdr() ------------------------------------------------------------------------------ #include <stdio.h> [emx] int _fsetmode (FILE *stream, const char *mode); Change the text/binary mode of a stream. MODE must be either "b" or "t". _fsetmode() returns 0 if successful. Otherwise, -1 is returned. _fsetmode() is usually used to put stdin or stdout to binary mode. See also: fopen() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int fsetpos (FILE *stream, const fpos_t *pos); Restore the position of the file pointer of the file STREAM to the position saved by fgetpos() in the variable pointed to by POS. fsetpos() currently does not work with text-mode files. See also: fgetpos(), fseek() ------------------------------------------------------------------------------ #include <stdio.h> [PC] #include <share.h> FILE *_fsopen (const char *fname, const char *mode, int shflag); Open a stream. FNAME is the name of the file, MODE is a string which specifies the file mode. The first character of MODE is `r' for reading, `w' for writing or `a' for appending. If a `+' character follows `a' or `w', the file will be also opened for reading. There are two additional MODE flags: `t' for text mode, `b' for binary mode. Text mode, which is the default, skips CR characters on input and converts LF characters to CR/LF pairs on output. Ctrl-Z on input indicates EOF. Binary mode disables these transformations. The sharing mode of the file is given by SHFLAG. The following sharing modes are available: SH_DENYRW Deny read and write access SH_DENYRD Deny read access (permit write access) SH_DENYWR Deny write access (permit read access) SH_DENYNO Deny nothing (permit read and write access) See also: fopen(), sopen() ------------------------------------------------------------------------------ #include <io.h> [UNIX] #include <sys/types.h> #include <sys/stat.h> int fstat (int handle, struct stat *buffer); Retrieve information about the open file HANDLE. fstat() will put the data into the structure pointed to by BUFFER. Restrictions: st_dev and st_rdev are set to zero. Each call to fstat() returns a different value for st_ino. See also: ioctl(), stat() ------------------------------------------------------------------------------ #include <io.h> [BSD] int fsync (int handle); Flush the buffers associated with HANDLE and update the directory. fsync() returns 0 if successful, -1 otherwise. Restriction: fsync() is currently not implemented for DOS: errno is set to EMSDOS. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] long ftell (FILE *stream); ftell() returns the current position of the file pointer of STREAM. If there is an error, ftell() returns -1. ftell() currently does not work with text-mode files. See also: fgetpos(), fseek() ------------------------------------------------------------------------------ #include <sys/timeb.h> [SysV] void ftime (struct timeb *ptr); Get current time and store it to the structure pointed to by PTR. That structure has the following fields: dstflag Non-zero if daylight saving time is active for the local timezone. Currently, this field is always 0. millitm Milliseconds of current time. time Current time in seconds since 00:00 GMT 1-Jan-1970. timezone Difference between GMT and local time in minutes. Positive values are to the west of GMT. See also: gettimeofday(), time() ------------------------------------------------------------------------------ #include <io.h> [BSD] int ftruncate (int handle, long length); Truncate the file associated with HANDLE to at most LENGTH bytes. The position of the file pointer is undefined after calling this function. If LENGTH is greater than the current length of the file, the length is not changed. HANDLE must be open for writing. If successful, 0 is returned. Otherwise, -1 is returned. See also: chsize(), truncate() ------------------------------------------------------------------------------ #include <sys/types.h> #include <sys/stat.h> #include <ftw.h> int ftw (const char *path, int (*fn)(const char *name, const struct stat *stat_ptr, int flag), int depth); Call FN for all entries of the directory tree whose root is PATH. Directories are visited before the entries they contain. FN is not called for the directories `.' and `..'. The name of the entry is passed in NAME. Forward slashes are used to separate directories (backslashes in PATH are not converted to forward slashes). _fnlwr() is called to convert the file names to lower case on upper-case-only file systems. A structure filled in by stat() is pointed to by STAT_PTR. FLAG is one of the following: FTW_D NAME is a directory FTW_F NAME is a file FTW_NS stat() failed, the contents of structure pointed to by STAT_PTR are undefined FTW_DNR NAME is an unreadable directory (does not happen under DOS and OS/2) If FN returns 0, ftw() continues. Otherwise, ftw() terminates and returns the value returned by FN. On error, ftw() returns -1. The DEPTH argument is ignored by this implementation of ftw(). In other implementations, DEPTH is used to restrict the number of file handles used by ftw(): one file handle is required for each level. If DEPTH is less than the number of levels, ftw() will be slow. Example: /emx/test/ftwtest.c See also: _fnlwr(), opendir() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] int _fullpath (char *dst, const char *src, int size); Construct an absolute path name for the file name or directory name SRC. The absolute path name is put to DST. It is assumed that there are SIZE bytes available at DST, this includes the terminating 0 byte. If there is an error, -1 is returned. If _fullpath() succeeds, 0 is returned. If SIZE is too small, errno is set to ERANGE and -1 is returned. DST can be identical to SRC. Backslashes are translated into forward slashes. The absolute path name is not translated to lower case. _fullpath() accesses the appropriate drive. It fails if a directory does not exist unless the non-existing directory is the last member of the resulting path name. See also: _abspath() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] size_t fwrite (const void *buffer, size_t size, size_t count, FILE *stream); Write COUNT objects of SIZE bytes each from BUFFER to STREAM. The file pointer is incremented by the number of bytes written. The number of complete objects written is returned which may be less than COUNT, for instance 0, if an error occurs. On failure, the value of the file pointer is undefined. If STREAM has been opened in text mode, LF characters are translated to CR/LF pairs. This translation does not affect the return value -- SIZE and COUNT are applied before the translation. See also: fputc(), fputs(), fread(), printf() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_box (int x0, int y0, int x1, int y1, int color, int fill_flag); Draw a box which has the four vertices (X0,Y0), (X0,Y1), (X1, Y0) AND (X1, Y1). If FILL_FLAG is G_OUTLINE, the outline is drawn, that is, four lines between the vertices. If FILL_FLAG is G_FILL, the interior of the box is filled. The color COLOR is used for drawing. See also: g_clip() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_clear (int color); Clear the screen (graphics mode, only). All pixels are set to the color COLOR. The clipping rectangle is ignored. ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_clip (int x0, int y0, int x1, int y1); Define the clipping rectangle. Only pixels with X coordinate between X0 and X1 (inclusive) and Y0 and with Y coordinate between X1 and Y1 (inclusive) are drawn. No drawing is performed outside that clipping rectangle. After switching to graphics mode with g_mode(), the clipping rectangle is set to the entire screen. This is equivalent to calling g_clip (0, 0, g_xsize-1, g_ysize-1) See also: g_mode(), g_xsize, g_ysize ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_ellipse (int cx, int cy, int rx, int ry, int color, int fill_flag); Draw an ellipse or a circle. One axis is horizontal, the other one vertical. The center of the ellipse is at (CX,CY). The horizontal radius is RX, the vertical radius is RY. It's impossible to draw an ellipse with even length of an axis. If FILL_FLAG is G_OUTLINE, the outline of the ellipse is drawn. If FILL_FLAG is G_FILL, the interior of the ellipse is filled. The color COLOR is used for drawing. See also: g_clip() ------------------------------------------------------------------------------ #include <graph.h> [emx] int g_get (int x, int y); Return the color of the pixel at (X,Y). If (X,Y) is outside the clipping rectangle, -1 is returned. See also: g_clip(), g_set() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_hline (int y, int x0, int x1, int color); Draw a horizontal line between (X0,Y) and (X1,Y). The color COLOR is used for drawing. See also: g_box(), g_clip(), g_line(), g_vline() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_line (int x0, int y0, int x1,int y1, int color); Draw a line of arbitrary slope between (X0,Y0) and (X1,Y1). The color COLOR is used for drawing. To draw horizontal or vertical lines, you should use g_hline() and g_vline(), respectively, which are specialized functions optimized for speed. See also: g_clip(), g_hline(), g_polygon(), g_triangle(), g_vline() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_lock (void); Lock the screen. Under OS/2, the screen must be locked while access graphics memory. All the graphics drawing functions lock the screen, draw, and unlock the screen unless it's already locked. To avoid the overhead of locking and unlocking for each function call, you can lock and unlock the screen yourself when performing many successive drawing operations. Note that you should not lock the screen for more than a few seconds. g_lock() increments a counter, which is initialized to zero by g_mode(). The screen is locked while the counter is non-zero. g_unlock() decrements the counter and unlocks the screen if the counter reaches zero. See also: g_unlock() ------------------------------------------------------------------------------ #include <graph.h> [emx] int g_mode (int mode); Select graphics mode. If MODE is G_MODE_OFF, graphics mode is turned off and 0 is returned. If MODE is G_MODE_VGA_L, the 320x200 VGA mode with 256 colors is chosen. If switching to graphics mode succeeds, 1 is returned. Otherwise, 0 is returned. The global variables g_xsize, g_ysize and g_colors are set. The clipping rectangle is set to the entire screen. General information about the graphics library: Programs using the graphics library work both under DOS and in OS/2 full-screen sessions. The coordinates of the screen are (0,0) (upper left) through (g_xsize-1,g_ysize-1) (lower right). You have to link with libgraph (use the -lgraph option). Under DOS, emx option -acm is required, see `Using emx options'. Restriction: Only G_MODE_VGA_L mode is currently implemented. Example: /emx/test/graph.c See also: g_clip(), g_modeset(), g_colors, g_xsize, g_ysize ------------------------------------------------------------------------------ #include <graph.h> [emx] int g_modeset (int mode, int flag); Modify a graphics mode number. The mode number to be modified is passed in MODE, the value passed in FLAG specifies how to modify the mode number: G_SET_KEEP causes the mode number to be not modified. The new mode number is returned. On failure, G_MODE_OFF is returned. The global variables g_xsize, g_ysize and g_colors are set. Restriction: As only G_SET_KEEP is implemented, g_modeset() is useless. It's included for compatibility with existing programs. See also: g_mode(), g_colors, g_xsize, g_ysize ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_polygon (const int *x, const int *y, int n, int color, int fill_flag); Draw a polygon. The N vertices are stored in the X and Y arrays: (X[i],Y[i]) for i = 0, ..., n-1. If FILL_FLAG is G_OUTLINE, the outline of the polygon is drawn, that is, a line from vertex 0 to vertex 1, from vertex 1 to vertex 2, ..., vertex n-2 to vertex n-1, vertex n-1 to vertex 0. If FILL_FLAG is G_FILL, the interior of the polygon is filled. A point is defined to be in the interior of the polygon, if an infinite line to any side of that pixel intersects the polygon an odd number of times. The color COLOR is used for drawing. See also: g_clip(), g_line(), g_triangle() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_set (int x, int y, int color); Set the pixel (X,Y) to the color COLOR. See also: g_clip(), g_get() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_triangle (int x0, int y0, int x1, int y1, int x2, int y2, int color, int fill_flag); Draw a triangle. The vertices are (X0,Y0), (X1,Y1) and (X2,Y2). If FILL_FLAG is G_OUTLINE, the outline of the triangle is drawn, that is, a line from (X0,Y0) to (X1,Y1), a line from (X1,Y1) to (X2,Y2) and a line from (X2,Y2) to (X0,Y0). If FILL_FLAG is G_FILL, the interior of the triangle is filled. The color COLOR is used for drawing. See also: g_clip(), g_line(), g_polygon() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_unlock (void); void g_unlockall (void); Unlock the screen. g_unlock() undoes one invocation of g_lock() by decrementing the counter incremented by g_lock(). If the counter reaches zero, the screen is unlocked. If the counter already was zero, the counter is not changed. g_unlockall() undoes all invocations of g_lock() by resetting the counter to zero and unlocking the screen if the counter was non-zero. See also: g_lock() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_vgapal (const char *pal, int first, int n, int wait_flag); Set the VGA palette. This function sets N (1 through 256) DAC registers starting with register FIRST (0 through 255). For each register, 3 bytes are taken from PAL: red, green, blue. Each byte should have a value between 0 and 63, inclusive. If WAIT_FLAG is non-zero, g_vgapal() waits for the vertical retrace to avoid snow on the screen, see g_waitv(). Under DOS, emx option -ai is required, see `Using emx options'. Under OS/2, emxio.dll is required. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio) after libgraph (-lgraph). libemxio must not be used if the program should run under DOS. See also: g_waitv() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_vline (int x, int y0, int y1, int color); Draw a vertical line between (X,Y0) and (X,Y1). The color COLOR is used for drawing. See also: g_box(), g_clip(), g_hline(), g_line() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_waitv (void); Wait for vertical retrace. Under DOS, emx option -ai is required, see `Using emx options'. Under OS/2, emxio.dll is required. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio) after libgraph (-lgraph). libemxio must not be used if the program should run under DOS. Note that this function eats lots of CPU time. See also: g_vgapal(), _wait01() ------------------------------------------------------------------------------ #include <graph.h> [emx] void g_wmode (int wmode); Select a `writing mode'. This is not yet implemented. ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] char *getcwd (char *buffer, int size); getcwd() retrieves the name of the current working directory (excluding the drive name) and stores it to BUFFER. It is assumed that there are SIZE bytes available at BUFFER. This includes the terminating 0. If SIZE is too small, getcwd() returns NULL and sets errno to ERANGE. If BUFFER is NULL, a buffer of suitable size, but at least SIZE bytes, is allocated with malloc(). If getcwd() succeeds, BUFFER is returned. getcwd() translates backslashes into forward slashes. It does not translate upper-case directory names to lower case. See also: chdir(), _getcwd1(), _getcwd2(), getwd() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _getcwd1 (char *buffer, char drive); _getcwd1() retrieves the name of the current working directory (starting with a slash, excluding the drive name) of drive DRIVE and stores it to BUFFER. If DRIVE is 0, the currently selected drive is used. Otherwise, DRIVE must be in 'A' through 'Z'. It is assumed that there are enough bytes available at BUFFER. If _getcwd1() succeeds, 0 is returned. _getcwd1() translates backslashes into forward slashes. It does not translate upper-case directory names to lower case. See also: chdir(), getcwd(), _getcwd2() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char *_getcwd2 (char *buffer, int size); _getcwd2() works like getcwd() but in addition it includes the drive name in BUFFER. See also: chdir(), getcwd(), _getcwd1() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] char _getdrive (void); Return as upper-case letter the currently selected drive. See also: _chdir2(), _chdrive(), _getcwd2() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] char *getenv (const char *name); Find NAME in the environment. If the variable is found, a pointer to the value is returned. Otherwise, NULL is returned. See also: environ, putenv() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char *_getext (const char *path); Return a pointer to the extension of the file name PATH. The pointer points to the dot character that starts the extension. If there is no extension, NULL is returned. If the last member of PATH starts with a dot ("/usr/mattes/.profile", for instance), NULL is returned. See also: _defext(), _getname(), _remext(), _splitpath() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char *_getname (const char *path); Return a pointer to the name part (last component, including the extension) of the file name PATH. The pointer points to the character after the last path separator (slash, backslash and colon). If there is no path separator, PATH is returned. See also: _getext(), _splitpath() ------------------------------------------------------------------------------ #include <stdlib.h> [BSD] int getpagesize (void); Return the page size, which is 4096 for the 386. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int getc (FILE *stream); int getchar (void); Read a character from STREAM or stdin, respectively. The character is returned. If an error occurs or if the end of the file is reached, EOF is returned. getchar () is equivalent to getc (stdin). getc() and getchar() are in-line functions or macros. See also: fgetc() ------------------------------------------------------------------------------ #include <getopt.h> [UNIX] int getopt (int argc, char **argv, const char *opt_str); Parse command line options. ARGC is the number of argument strings, ARGV is an array of argument strings, OPT_STR is a string describing the available options. Typically, the ARGC and ARGV arguments of main() are passed to getopt(). Each option is of one of the following types: - option without argument: the option letter is listed in OPT_STR; - option with mandatory argument: the option letter in OPT_STR is followed by a colon - option with optional argument: the option letter in OPT_STR is followed by two colons. For instance, c = getopt (argc, argv, "abc:d::v") defines five options: -a, -b, -c and -v don't take arguments, -c takes a mandatory argument, -d takes an optional argument. Before the first call to getopt(), the global variable optind must be set to 0 (that's the initial value, see also bugs below). Calling getopt() parses the next command line option. If there are no more command line options, getopt() returns EOF. After calling getopt(), optind is the index of the next command line argument. After calling getopt(), the global variable optarg points to the argument of the option. If there is no argument, optarg is NULL. There are three modes of operation, which are controlled by the global variable optmode: GETOPT_UNIX Options are at the start of the command line. When the first non-option is reached, parsing options stops and getopt() returns EOF. GETOPT_UNIX is the default. GETOPT_ANY Options may appear anywhere on the command line. ARGV is reordered to move the non-options to the end. When there are no more options, getopt() returns EOF. The remaining arguments are all the arguments of the command line which are not options. GETOPT_KEEP Options may appear anywhere on the command line. If the current argument is not an option, getopt() returns 0. optarg will point to the argument. The next call to getopt() examines the next command line argument. If the global variable opterr is non-zero (this is the default), getopt() writes an appropriate error message to stderr on failure and returns '?'. If opterr is zero, getopt() does not display an error message on failure and returns '?'. The global variable optswchar is a string of characters which start options. The default value is "-", that is, options are started by hyphens. You might want to assign "-/" or "/" to optswchar. If a command line argument consists of two equal switch characters (see optswchar), the remaining command line arguments are not treated as options. Options may be clustered, that is, if an option does not take an argument, getopt() treats the following character of the same command line argument as option. If an option takes a mandatory argument, the argument either follows immediately the option or is taken from the next command line argument. If an option takes an optional argument, the argument must immediately follow the option. getopt() returns the next option character. If there are no more command line options, EOF is returned. On failure, '?' is returned. If optmode is GETOPT_KEEP and the current command line argument is not an option, 0 is returned. When writing portable programs, you should not use optmode, optswchar and options taking optional arguments. Only letters should be used as options. optmode must not be changed after the first call to getopt(). optswchar, however, may be changed at any time. Bugs: optind should be set to 1 (instead of 0) for parsing the first command line argument. As it is initialized to 0 by this implementation of getopt() and seems to be initialized to 1 by the BSD implementation, just do not initialize optind and everything will be OK. See also: main(), _swchar() ------------------------------------------------------------------------------ #include <process.h> [UNIX] int getpid (void); Return the process identification number of the calling process. ------------------------------------------------------------------------------ #include <process.h> [UNIX] int getppid (void); Return the process identification number of the parent process of the calling process. ------------------------------------------------------------------------------ #include <pwd.h> [UNIX] struct passwd *getpwent (void); struct passwd *getpwuid (int uid); struct passwd *getpwnam (char *name); void setpwent (void); void endpwent (void); Dummy functions. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] char *gets (char *buffer); Read a string from stdin to BUFFER. Stop after a newline (LF) character has been read. The newline character is replaced with a null character. gets() returns BUFFER. If an error occurs or the end of the file is reached, gets() returns NULL. Use fgets() instead as gets() doesn't know how big BUFFER is. See also: fgets(), scanf() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int getw (FILE *stream); Read a word (int) from STREAM and return it. On failure, -1 is returned. As -1 is also a possible word value, you have to use ferror() to recognize an error condition. Avoid using this function. See also: putw(), fwrite() ------------------------------------------------------------------------------ #include <stdlib.h> char *getwd (char *buffer); getwd() retrieves the name of the current working directory (excluding the drive name) and stores it to BUFFER. It is assumed that there are MAXPATHLEN bytes available at BUFFER. This includes the terminating 0. MAXPATHLEN is defined in sys/param.h. If getwd() succeeds, BUFFER is returned. If getwd() fails, an error message is copied to BUFFER and NULL is returned. getwd() translates backslashes into forward slashes. It does not translate upper-case directory names to lower case. See also: getcwd() ------------------------------------------------------------------------------ #include <sys/time.h> [BSD] int gettimeofday (struct timeval *tp, struct timezone *tzp); Obtain the current time and timezone. If TP is not NULL, the current Greenwich Mean Time, expressed in seconds and microseconds since 00:00 1-Jan-1970, is stored to *TP. If TZP is not NULL, information about the timezone is stored to *TZP. See also: ftime(), time() ------------------------------------------------------------------------------ #include <time.h> [ANSI] struct tm *gmtime (const time_t *t); Convert the number of seconds elapsed since 00:00 1-Jan-1970 (GMT) given by the variable pointed to by T to a time and date structure (GMT) and return a pointer to the structure. gmtime(), mktime() and localtime() use the same memory location, therefore the values are overwritten if one of these functions is called. See also: localtime() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] int _heapchk (void); int _heapset (unsigned fill); _heapchk() checks the heap and returns _HEAPBADBEGIN (if the pointers to the heap are corrupt), _HEAPBADNODE (if there is a corrupt entry in the heap), _HEAPEMPTY (if the heap is empty) or _HEAPOK (if the heap is ok). _heapset() fills unused areas of the heap with FILL. See _heapchk() for the return values. In fact, _heapchk() is a special variant of _heapset() which doesn't fill unused areas of the heap. ------------------------------------------------------------------------------ #include <math.h> [UNIX] double hypot (double x, double y); Compute and return sqrt (x*x + y*y). On overflow, #INF is returned and errno is set to ERANGE. See also: sqrt() ------------------------------------------------------------------------------ #include <strings.h> [BSD] char *index (const char *string, int c); Return a pointer to the first occurrence of the character C in the null-terminated string STRING. If there is no character C in STRING, NULL is returned. If C is 0, a pointer to the terminating zero of STRING is returned. See also: rindex(), strchr() ------------------------------------------------------------------------------ #include <sys/hw.h> [*] [emx] unsigned _inp8 (unsigned port); unsigned _inp16 (unsigned port); unsigned _inp32 (unsigned port); These functions read a single byte or word from a hardware port. _inp8() reads a byte from PORT, _inp16() reads a 16-bit word from PORT, _inp32() reads a 32-bit word from PORT. You have to call _portaccess() first to enable access to a range of ports. To make your program work under DOS, you have to use emx option -ai, see `Using emx options'. Under OS/2, your program requires emxio.dll in a directory listed in LIBPATH. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio). libemxio must not be used if the program should run under DOS. See also: _portaccess(), _inps8(), _outp8(), _wait0() ------------------------------------------------------------------------------ #include <sys/hw.h> [*] [emx] void _inps8 (unsigned port, unsigned char *dst, unsigned count); void _inps16 (unsigned port, unsigned short *dst, unsigned count); void _inps32 (unsigned port, unsigned long *dst, unsigned count); These functions read multiple bytes or words from a hardware port. _inps8() reads COUNT bytes from PORT to the buffer DST. _inps16() reads COUNT 16-bit words from PORT to the buffer DST. The COUNT argument of _inps8() must not exceed 65535. The DST pointer of _inps16() must be aligned on a 16-bit boundary, that is, the address must be even. COUNT must not exceed 32768. The DST pointer of _inps32() must be aligned on a 32-bit boundary, that is, the address must be a multiple of four. COUNT must not exceed 65536. You have to call _portaccess() first to enable access to a range of ports. To make your program work under DOS, you have to use emx option -ai, see `Using emx options'. Under OS/2, your program requires emxio.dll in a directory listed in LIBPATH. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio). libemxio must not be used if the program should run under DOS. See also: _portaccess(), _inp8(), _outps8() ------------------------------------------------------------------------------ #include <dos.h> [PC] int _int86 (int int_num, union REGS *inp_regs, union REGS *out_regs); Issue software interrupt under DOS. This function loads the processor registers EAX, EBX, ECX, EDX, ESI and EDI from INP_REGS, calls software interrupt INT_NUM and stores the processor registers EAX, EBX, ECX, EDX, ESI, EDI and the flags register to OUT_REGS. The value of EAX is returned. emx option -ac must be used to enable _int86(). If -ac is not used, a protection violation exception occurs when _int86() is called. See `Using emx options'. Restrictions: _int86() is not supported under OS/2 (there are no software interrupts under OS/2). The emx DOS extender currently supports only interrupts 0x10, 0x11, 0x14, 0x16, 0x17 and 0x21. Note that pointer conversion is done only for the subset of interrupt 0x21 services known by DOS 3.3. Pointer conversion is currently done for interrupt 0x21 only. Please note the following difference to DOS C compilers: the REGS union does not contain an X.CFLAG field. The complete flags register is stored to the E.EFLAGS field instead. The carry flag is available in bit 0 of the E.EFLAGS and X.FLAGS fields. Example: /emx/test/vmode.c ------------------------------------------------------------------------------ #include <sys/ioctl.h> [*] [SysV] int ioctl (int handle, int request, int int_arg); int ioctl (int handle, int request, void *ptr_arg); Device control for HANDLE. REQUEST codes are: TCGETA see `termio' TCSETA see `termio' TCGETAF see `termio' TCGETAW see `termio' TCFLSH flush the buffers. If INT_ARG is 0, the input buffer is flushed; if INT_ARG is 1, the output buffer is flushed; if INT_ARG is 2, both the input and output buffers are flushed. Works only if HANDLE is 0 and HANDLE refers to the keyboard. Only flushing the keyboard buffer is implemented FIONREAD get number of available characters. The number of available characters is stored to the int pointed to by PTR_ARG. FIONREAD is implemented for the following types of handles: - stdin handles (keyboard) with IDEFAULT not set (DOS: handle 0 only). Note that if ICANON is set, the number of characters in the keyboard buffer is returned which is not the number of characters available for read(), as at least one of the buffered characters (carriage return) is used for command line editing - named pipes - pipes created with pipe() by programs using emx.dll - all file handles under DOS (0 or 1 character available) FGETHTYPE get the handle type and store it to the int pointed to by PTR_ARG. See /emx/include/sys/ioctl.h for handle types (HT_FILE, for instance). If an error occurs, errno is set and -1 is returned. Restriction: When using the system call library libsys.lib (-Zsys), only the FGETHTYPE request is available. See also: fcntl(), open(), read() ------------------------------------------------------------------------------ #include <ctype.h> [UNIX] int isascii (int c); Return a non-zero value iff C is a valid ASCII character which can be used with isalnum() etc. isascii() can be applied to all integer values. isascii() is implemented both as macro and as function. See also: isalnum() ------------------------------------------------------------------------------ #include <ctype.h> [ANSI] int isalnum (int c); /* alphanumeric character */ int isalpha (int c); /* alphabetic character */ int iscntrl (int c); /* control character */ int isdigit (int c); /* decimal digit */ int isgraph (int c); /* printable character but not space */ int islower (int c); /* lower-case letter */ int isprint (int c); /* printable character */ int ispunct (int c); /* punctuation character */ int isspace (int c); /* white-space character */ int isupper (int c); /* upper-case letter */ int isxdigit (int c); /* hexadecimal digit */ These functions (or macros) return a non-zero value if the condition is true, or 0 if it is not true. C must be an ASCII character or EOF. Otherwise the result is unpredictable. Use isascii() to check for valid ASCII characters. These routines are implemented both as macros and as functions. See also: isascii(), tolower(), toupper(), _tolower(), _toupper() ------------------------------------------------------------------------------ #include <io.h> [UNIX] int isatty (int handle); Returns a non-zero value if HANDLE refers to a character device. Returns 0 if HANDLE does not refer to a character file (file or pipe). If there is an error, errno is set and -1 is returned. See also: _isterm(), ioctl() ------------------------------------------------------------------------------ #include <io.h> [emx] int _isterm (int handle); Returns a non-zero value if HANDLE refers to the stdin (keyboard) or stdout (screen) device. Otherwise, returns 0. If there is an error, errno is set and 0 is returned. Consider using ioctl (FGETHTYPE) instead. See also: _isterm(), ioctl() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] char *_itoa (long value, char *string, int radix); char *_ltoa (int value, char *string, int radix); char *_ultoa (unsigned long value, char *string, int radix); Convert the number VALUE to a string using the number base RADIX (between 2 and 36). The string is stored to STRING. STRING is returned. See also: atoi(), _lltoa(), strtol() ------------------------------------------------------------------------------ #include <signal.h> [*] [UNIX] int kill (int pid, int sig); Send the signal SIG to process PID. Only SIGINT and SIGBREAK can be sent to arbitrary child processes. A process can send the other signals only to itself, see raise(), or to other emx programs. If SIG is 0, kill() checks only if PID is valid or not. If PID is smaller than -1, the signal is sent to process -PID and its children. Some special cases are not implemented: pid=0, pid=1. If successful, kill() returns 0. Otherwise -1 is returned and errno set to one of the following values: EINVAL SIG is not a valid signal number ESRCH PID is not the process ID of a process or process PID is not a child process Restrictions: Special treatment of PID=0, PID=1 and PID=-1 is not implemented. Negative values of PID are implemented for OS/2 only and work only for direct children of the caller. When using the system call library libsys.lib (-Zsys), a process can send arbitrary signals to itself, only SIGINT and SIGBREAK can be sent to only child processes, negative values of PID are not allowed. See also: raise(), signal() ------------------------------------------------------------------------------ #include <stdlib.h> /* use this */ [ANSI] #include <math.h> /* or this */ long labs (long n); Return the absolute value of N: If N is negative, -N is returned. Otherwise, N is returned. In-line code is generated for this function. See also: abs(), fabs() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double ldexp (double x, int exp); Compute and return X * 2 ^ EXP. On overflow, #NAN is returned and errno is set to ERANGE. ------------------------------------------------------------------------------ #include <stdlib.h> [emx] _lldiv_t _lldiv (long long num, long long den); _uldiv_t _uldiv (unsigned long num, unsigned long den); _ulldiv_t _ulldiv (unsigned long long num, unsigned long long den); Perform an integer division, dividing NUM by DEN. The quotient and the remainder are returned in the quot and rem fields, respectively. The following table shows the signs of quot and rem depending on the signs of NUM and DEN for _lldiv(): NUM DEN | quot rem --------+--------- + + | + + + - | - + - + | - - - - | + - Note: Do not use the -fpcc-struct-return GCC option. See also: div(), ldiv() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char *_lltoa (long long value, char *string, int radix); char *_ulltoa (unsigned long long value, char *string, int radix); Convert the number VALUE to a string using the number base RADIX (between 2 and 36). The string is stored to STRING. STRING is returned. See also: atoi(), _itoa(), strtol() ------------------------------------------------------------------------------ #include <locale.h> [ANSI] struct lconv *localeconv (void); Not implemented. ------------------------------------------------------------------------------ #include <time.h> [ANSI] struct tm *localtime (const time_t *t); Convert the number of seconds elapsed since 00:00 GMT 1-Jan-1970 given by the variable pointed to by T to a time and date structure for the local timezone and return a pointer to the structure. gmtime(), mktime() and localtime() use the same memory location, therefore the values are overwritten if one of these functions is called. See also: gmtime() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double log (double x); double log10 (double x); log() returns the natural logarithm of X. log10() returns the base-10 logarithm of X. If X is zero, -#INF is returned and errno set to EDOM. If X is negative, +#NAN is returned and errno set to EDOM. See also: exp(), pow() ------------------------------------------------------------------------------ #include <setjmp.h> [ANSI] void volatile longjmp (jmp_buf there, int n); Restore the context saved in THERE by setjmp(). longjmp() does a non-local `goto'. When calling longjmp() in a signal handler or in a function called by a signal handler (that is, while a signal handler is active), the signal handler will be unwound, that is, it is assumed that the signal handler doesn't return. See also: setjmp() ------------------------------------------------------------------------------ #include <io.h> [UNIX] long lseek (int handle, long offset, int origin); lseek() moves the file pointer of HANDLE. The new position OFFSET is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is relative to the current position, if ORIGIN is SEEK_END, OFFSET is relative to the end of the file. The file pointer cannot be moved before the beginning of the file. lseek() returns the new position relative to the beginning of the file. If there is an error, -1 is returned. See also: tell() ------------------------------------------------------------------------------ [ANSI] int main (void); int main (int argc, char *argv[]); int main (int argc, char *argv[], char *envp[]); This is the function called by the startup code to run your program. It is not a library function. ARGC is the number of command line arguments, including the program name. ARGV is an array of pointers to the command line arguments. ENVP is an array of pointers to the environment strings. The last entry of ARGV and ENVP is a NULL pointer. main() should always return a value. If main() returns, exit() is called using the return value of main() as argument. If main() ends without return() or calling exit(), the return code of the program is undefined. This should be avoided. After changing the environment with putenv(), you should use the environ global variable instead of the ENVP argument of main(). See also: environ, exit(), _response(), _wildcard() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void *malloc (size_t size); Allocate a block of memory big enough for holding SIZE bytes. If there is an error, malloc() returns NULL. If SIZE is 0, zero bytes of memory are allocated, the return value will be unequal NULL. Restriction: The current malloc() implementation is not really suitable for virtual memory because the complete heap (including allocated blocks) is traversed for a free block. It's possible to use GNU malloc instead. Do not replace malloc() etc. when using emxlibc.dll as the functions in emxlibc.dll won't call your replacements. See also: calloc(), free(), realloc() ------------------------------------------------------------------------------ #include <math.h> [PC] int matherr (struct exception *x); Exception handler for floating point math. Restriction: matherr() is not implemented. ------------------------------------------------------------------------------ #include <sys/hw.h> [emx] void *_memaccess (unsigned first, unsigned last, int flag); Gain access to physical memory under DOS. To access memory which is outside the memory space of the current process, you have to call _memaccess(). emx option -am must be used to enable _memaccess(), see `Using emx options'. FIRST is the address of the first byte of the physical memory area, LAST is the address of the last byte of the physical memory area to be accessed. Both addresses are physical addresses. FIRST and LAST+1 must be page aligned: FIRST and LAST+1 must be integral multiples of 4096. That is, with using hexadecimal notation, FIRST must end with 000, LAST must end with fff. A pointer to virtual memory mapped to the physical memory area is returned. If FLAG is 0, read access is granted. If FLAG is 1, read and write access is granted. Write access can be granted if the address range of the physical memory area is entirely in the range 0xa0000 to 0xbffff. If bytes outside this range are included in FIRST to LAST, emx option -aw must be used to enable write access, see `Using emx options'. If _memaccess() fails, NULL is returned and errno set to one of the following values: EACCES FIRST not page aligned; LAST+1 not page aligned; LAST not greater than FIRST; write access not allowed EINVAL FLAG is not 0 or 1 ENOMEM not enough virtual memory for storing the paging tables; linear address space of process not big enough for the request Restriction: _memaccess() is not available under OS/2. Example: /emx/test/hw_mem.c See also: _portaccess() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [emx] #include <memory.h> /* or this */ size_t _memcount (void *mem, int c, size_t n); Return the number of bytes equal to C of the N bytes at address MEM. ------------------------------------------------------------------------------ #include <string.h> /* use this */ [PC] #include <memory.h> /* or this */ void *memccpy (void *s1, const void *s2, int c, size_t n); Copy at most the first N bytes from S2 to S1, stopping after copying a byte equal to the lower 8 bits C. If memccpy() stops because a byte equal to C has been found, a pointer to the byte after the last destination byte (which is equal to C) is returned. If N bytes have been copied without finding a byte equal to C, NULL is returned. See also: memchr(), memcpy(), memmove(), strcpy(), strncpy() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [ANSI] #include <memory.h> /* or this */ void *memchr (const void *s, int c, size_t n); Search the first N bytes at S for a byte equal to the lower 8 bits of C. If a byte equal to C is found, a pointer to the first occurrence of C is returned. If there is no such byte, NULL is returned. ------------------------------------------------------------------------------ #include <string.h> /* use this */ [ANSI] #include <memory.h> /* or this */ int memcmp (const void *s1, const void *s2, size_t n); Compare the first N bytes at S1 to the first N bytes at S2. If the two buffers are identical (or if N is zero), 0 is returned. Otherwise, a value is returned which indicates the relationship of the first differing byte: a negative value means buffer S1 is lexically less than buffer S2, a positive value means buffer S1 is lexically greater than buffer S2. See also: bcmp(), _memdif(), memicmp() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [emx] #include <memory.h> /* or this */ size_t _memcount (const void *mem, int c, size_t n); Count and return the number of occurrences of character C in the memory area of size N bytes at MEM. ------------------------------------------------------------------------------ #include <string.h> /* use this */ [ANSI] #include <memory.h> /* or this */ void *memcpy (void *s1, const void *s2, size_t n); Copy memory. Copy N bytes from S2 to S1. The two regions must not overlap. memcpy() returns S1. GCC generates in-line code for special applications of memcpy(). Use memmove() instead of memcpy() to copy overlapping regions of memory. See also: bcopy(), memmove() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [emx] #include <memory.h> /* or this */ size_t _memdif (const void *mem1, const void *mem2, size_t n); Compare the first N bytes at MEM1 to the first N bytes at MEM2. If the two buffers are identical (or if N is zero), _MEMDIF_EQ is returned. Otherwise, the byte offset of the first difference is returned. See also: memcmp() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [PC] #include <memory.h> /* or this */ int memicmp (const void *s1, const void *s2, size_t n); Compare the first N bytes at S1 to the first N bytes at S2, ignoring letter case. If the two buffers are identical (or if N is zero), 0 is returned. Otherwise, a value is returned which indicates the relationship of the first differing byte: a negative value means buffer S1 is lexically less than buffer S2 (after conversion to lower case), a positive value means buffer S1 is lexically greater than buffer S2 (after conversion to lower case). See also: memcmp(), tolower() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [ANSI] #include <memory.h> /* or this */ void *memmove (void *s1, const void *s2, size_t n); Copy memory. Copy N bytes from S2 to S1. The two regions may overlap. memmove() returns S1. See also: bcopy(), memcpy() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [ANSI] #include <memory.h> /* or this */ void *memset (void *s, int c, size_t n); Fill memory. Set N bytes at S to C. memset() returns S. See also: bzero() ------------------------------------------------------------------------------ #include <string.h> /* use this */ [emx] #include <memory.h> /* or this */ void _memswap (void *s1, void *s2, size_t n); Swap two areas of memory of N bytes each, pointed to by S1 and S2. The two areas must not overlap. ------------------------------------------------------------------------------ #include <stdlib.h> [BSD] int mkdir (const char *name, long mode); Create a directory named NAME. Only one directory can be created in one step, therefore all but the last component of NAME must exist. MODE (containing the permission bits) is ignored. See also: chdir(), rmdir() ------------------------------------------------------------------------------ #include <io.h> [UNIX] char *mktemp (char *template); Create a unique file name by modifying TEMPLATE. Trailing X characters of TEMPLATE are replaced by a letter followed by digits (the process ID). There should be 6 trailing X characters. Only 26 different file names per process can be created. On success, TEMPLATE is returned. On failure, NULL is returned. Note that the TEMPLATE string is modified, do not use a string constant! Example: char tmp[20]; strcpy (tmp, "exXXXXXX"); if (mktemp (tmp) != NULL) { /* ... */ } See also: tempnam(), tmpfile(), tmpnam() ------------------------------------------------------------------------------ #include <time.h> [ANSI] time_t mktime (struct tm *t); Return the number of seconds elapsed between 00:00 GMT 1-Jan-1970 and the moment defined by the structure pointed to by T. T is interpreted as local time. On error, -1 cast as time_t is returned. See also: gmtime(), localtime() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double modf (double x, double *int_ptr); Split X into fractional part (which is returned) and integer part (which is stored to *INT_PTR). Both the fractional and the integer part have the same sign as X. See also: ceil(), floor(), frexp(), rint(), trunc() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] size_t _msize (const void *mem); Return the size of the memory block MEM which has been allocated by malloc(), realloc() or calloc(). MEM must be the pointer obtained by calling malloc(), realloc() or calloc(). See also: _expand() ------------------------------------------------------------------------------ #include <sys/nls.h> [emx] void _nls_init (void); Initialize the global variables _nls_tolower_tab and _nls_toupper_tab which are used by _nls_tolower(), _nls_toupper(), _nls_strlwr() and _nls_strupr(). Before calling one of these functions, _nls_init() must be called. Moreover, _nls_init() should be called after changing the country or code page. The tables are initialized appropriately for the current country code and code page. See also: _fncmp(), _nls_tolower(), _nls_strlwr() ------------------------------------------------------------------------------ #include <sys/nls.h> [emx] unsigned char *_nls_strlwr (unsigned char *string); unsigned char *_nls_strupr (unsigned char *string); These functions convert all the characters of the string STRING to lower case or upper case, respectively. Accented characters etc. are converted as well. STRING is returned. Before using one of these functions, _nls_init() must be called. See also: _nls_init(), _nls_tolower(), _nls_toupper() ------------------------------------------------------------------------------ #include <sys/nls.h> [emx] unsigned char _nls_tolower (unsigned char c); unsigned char _nls_toupper (unsigned char c); These routines convert the character C to lower case or upper case, respectively. Accented characters etc. are converted as well. Before using one of these routines, _nls_init() must be called. These routines are implemented as macros. See also: _nls_init(), _nls_strlwr(), _nls_strupr() ------------------------------------------------------------------------------ #include <io.h> [UNIX] #include <fcntl.h> #include <sys/types.h> #include <sys/stat.h> int open (const char *name, int oflag); int open (const char *name, int oflag, int pmode); Open a file or device. NAME is the name of the file or device. OFLAG contains one or more of the following values, combined by the | operator: O_RDONLY Open for reading. Writing is not allowed O_WRONLY Open for writing. Reading is not allowed O_RDWR Open for reading and writing O_APPEND Move the file pointer to the end of file before any write operation takes place. This is used for appending to a file O_CREAT Create the file if it does not exist O_TRUNC Truncate the size of the file to 0 O_EXCL Fail if the O_CREAT is used and the file already exists O_NDELAY Currently ignored. O_BINARY Binary mode, no translation. See below O_TEXT Text mode, translate CR/LF to LF. See below If a new file is created, PMODE (modified by the umask value), is used to set the file permissions. S_IREAD grants read access, S_IWRITE grants write access. S_IREAD is ignored (DOS and OS/2 limitation). To grant both read and write access, use S_IREAD|S_IWRITE. There are two additional OFLAG flags: O_TEXT for text mode, O_BINARY for binary mode. Text mode, which is the default, translates each CR/LF pair to a LF character on input and translates LF characters to CR/LF pairs on output. If the last character of a file is Ctrl-Z, it is discarded on input. Binary mode disables these transformations. If the file or device cannot be opened, open() sets errno and returns -1. If open() succeeds, the file handle is returned. The file handle is always greater than -1. The mode O_TRUNC|O_RDONLY is not implemented. The mode O_TEXT|O_WRONLY does not overwrite a Ctrl-Z at the end of the file -- this causes problems when appending. Ctrl-Z at the end of the file is obsolete, anyway. The file is opened in the sharing mode SH_DENYNO, see sopen(). See also: close(), fdopen(), sopen() ------------------------------------------------------------------------------ #include <sys/types.h> [BSD] #include <dirent.h> /* this is recommended */ #include <sys/dir.h> /* this also works (for now) */ DIR *opendir (char *name); int closedir (DIR *dirp); struct dirent *readdir (DIR *dirp); void seekdir (DIR *dirp, long off); long telldir (DIR *dirp); void rewinddir (DIR *dirp); Scan directories. opendir() opens the directory NAME for scanning. If there is an error, NULL is returned. Otherwise a value is returned which is used with the other functions to continue the scanning. closedir() ends the directory scan of DIRP. After closing DIRP, you must not use DIRP. You should close all handles created by opendir(). readdir() retrieves the next directory entry for DIRP. If there are no more directory entries, NULL is returned. seekdir() moves to the specified directory entry of DIRP. If OFF is 0, the first directory entry will be read next. If OFF is 1, the second directory entry will be read next. And so on. telldir() returns the current position in DIRP. 0 is returned for the first directory entry. rewinddir() is equivalent to seekdir (0). These functions use _fnlwr() to convert the file names to lower case on upper-case-only file systems. See also: _fnlwr(), _wildcard() ------------------------------------------------------------------------------ #include <sys/hw.h> [*] [emx] void _outp8 (unsigned port, unsigned value); void _outp16 (unsigned port, unsigned value); void _outp32 (unsigned port, unsigned value); These functions write a single byte or word to a hardware port. _outp8() writes the byte VALUE to PORT, _outp16() writes the 16-bit word VALUE to PORT, _outp32() writes the 32-bit word VALUE to PORT. You have to call _portaccess() first to enable access to a range of ports. To make your program work under DOS, you have to use emx option -ai, see `Using emx options'. Under OS/2, your program requires emxio.dll in a directory listed in LIBPATH. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio). libemxio must not be used if the program should run under DOS. See also: _portaccess(), _inp8(), _outps8() ------------------------------------------------------------------------------ #include <sys/hw.h> [*] [emx] void _outps8 (unsigned port, const unsigned char *src, unsigned count); void _outps16 (unsigned port, const unsigned short *src, unsigned count); void _outps32 (unsigned port, const unsigned short *src, unsigned count); void _outps8dac (unsigned port, const unsigned char *src, unsigned count); These functions write multiple bytes or words to a hardware port. _outps8() writes COUNT bytes from SRC to PORT. _outps16() writes COUNT 16-bit words from SRC to PORT. _outps32() writes COUNT 32-bit words from SRC to PORT. The COUNT argument of _outps8() must not exceed 65535. The SRC pointer of _outps16() must be aligned on a 16-bit boundary, that is, the address must be even. COUNT must not exceed 32768. The SRC pointer of _outps32() must be aligned on a 32-bit boundary, that is, the address must be a multiple of four. COUNT must not exceed 65536. _outps8dac() is a slowed-down version of _outps8() suitable for writing to the VGA palette registers. You have to call _portaccess() first to enable access to a range of ports. To make your program work under DOS, you have to use emx option -ai, see `Using emx options'. Under OS/2, your program requires emxio.dll in a directory listed in LIBPATH. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio). libemxio must not be used if the program should run under DOS. See also: _portaccess(), _inps8(), _outp8() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] int _path (char *dst, const char *name); Find an executable file. If NAME contains a colon, a slash or a backslash, only that name will be tried. If NAME does not contain colons, slashes or backslashes, the file will be sought in the directories listed in the EMXPATH and PATH environment variables. If the file is not found, DST will be an empty string, errno will be ENOENT and -1 will be returned. If the file is found, the path name will be copied to DST and 0 will be returned. No default extension is used. See also: getenv(), _searchenv() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int pclose (FILE *stream); Close a pipe created by popen(). pclose() waits until the child process started by popen() ends and closes STREAM. The termination status of the child process is returned. See wait() for details about the return value. If there is an error, pclose() returns -1. Restriction: pclose() is not implemented under DOS. See also: popen() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] void perror (const char *string); Print an appropriate error message for the current errno value to stderr. If STRING is NULL or is the empty string "", just the error message is printed. Otherwise, STRING and a colon precede the error message. See also: errno, strerror(), sys_errlist, sys_nerr ------------------------------------------------------------------------------ #include <io.h> [UNIX] int pipe (int *two_handles); Create an unnamed pipe. The handle used for reading from the pipe is stored to TWO_HANDLES[0], the handle used for writing to the pipe is stored to TWO_HANDLES[1]. Both handles are in text mode; use setmode() if you want to switch to binary mode. pipe() returns 0 if successful, -1 otherwise. Restrictions: pipe() is implemented for OS/2 only. See also: close(), dup(), popen(), setmode() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] FILE *popen (const char *command, const char *mode); Start a child process and connect one end of a pipe to it. popen() runs the command COMMAND by starting a command processor. MODE must start with `r' or `w'. If it starts with `r', stdout of COMMAND will be redirected, you can get the output by reading from the stream returned by popen(). If MODE starts with `w', stdin of COMMAND will be redirected, you can send data to COMMAND by writing to the stream returned by popen(). Append `b' for binary mode or `t' for text mode to the MODE string. The default is text mode, see also fopen(). If an error occurs, popen() returns NULL. Otherwise, popen() returns a stream which is connected to the local end of the pipe. Use pclose() to close the stream. Restriction: popen() is not implemented under DOS. See also: pclose(), pipe(), _splitargs(), system() ------------------------------------------------------------------------------ #include <sys/hw.h> [emx] int _portaccess (unsigned first, unsigned last); Gain access to hardware ports. To access hardware ports, you have to call _portaccess(). FIRST is the address of the first port, LAST is the address of the last port. emx option -ai must be used to enable _portaccess() under DOS, see `Using emx options'. On success, 0 is returned. On failure, -1 is returned. _portaccess() always succeeds under OS/2. Example: /emx/test/hw_io.c See also: _memaccess(), _inp8(), _outp8(), _wait0() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double pow (double x, double y); Raise X to the power of Y and return the result. If pow() is undefined for a given pair of X and Y, #NAN is returned and errno is set to EDOM. On overflow, #INF is returned and errno is set to ERANGE. See also: cbrt(), exp(), log(), sqrt() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int printf (const char *format, ...); Formatted output to the stdout stream. On success, the number of characters written to stdout is returned. Otherwise, EOF is returned. Characters in FORMAT are copied unmodified to the destination unless a format specification is hit. A format specification has the following format: %[flags][width][.precision][size]type where items in brackets are optional. For each format specification an argument of the specified type is taken from the argument list, is formatted according to the format specification and written to the destination. To include one percent sign in the output, put two percent signs (%%) into the FORMAT string. The following FLAGS characters are available: - left-justify the converted value. Without this flag, the value is right-justified + always insert sign (+ or -) for a signed number (blank) insert a blank space if the conversion of a signed number doesn't start with a sign (+ or -). If both + and (blank) are given, (blank) is ignored. 0 pad with '0' characters instead of blanks. This flag is ignored for non-numeric conversions # use alternate conversion. See below If the length of the converted value is less than WIDTH, it is padded with blanks or '0' characters, depending on the 0 flag and the conversion type. Unless the - flag is used, the field is padded on the left. If the length of the converted value is greater than WIDTH, the field is not truncated. WIDTH is either a decimal number or a '*' character. In the latter case, the width is taken from the argument list. PRECISION specifies the number of decimal digits after the decimal point of a floating point number. For the s conversion, PRECISION specifies the maximum string length. PRECISION is either a decimal number or a '*' character. In the latter case, the precision is taken from the argument list. SIZE is either h for a `short' type or l for a `long' type. If SIZE is not specified, the default size is used. Use L or ll for a `long long' type. TYPE is one of the following characters: c character (char) d signed decimal number (int) e floating-point number (double), using e as exponent sign: -#.###e+##. There's exactly one digit before the decimal point. The number of digits after the decimal point is specified by PRECISION. If PRECISION is missing, 6 digits are printed E floating-point number (double), using E as exponent sign. See e f floating-point number (double) printed in fixed-point format. The number of digits after the decimal point is specified by PRECISION. If PRECISION is missing, 6 digits are printed. If PRECISION is specified as 0, no decimal point is printed g floating-point number (double). The number is printed using type d, e or f, depending on the number. If the number is an integer, type d is used. If the exponent (of f format output) is less than -4 or greater than PRECISION (default: 6), type e is used. Otherwise, type f is used G floating-point number (double), using E as exponent sign instead of e. See g i signed decimal number (int). Same as d n store the number of characters formatted up to this point in the FORMAT string (int *). No output o octal number (unsigned). The # flag prepends 0. p pointer (void *). The output format of a pointer is implementation-dependent. In this implementation, p is equivalent to x s string (char *). Print characters of the string until a null character is reached or PRECISION (if specified and non-zero) is exhausted u unsigned decimal number (unsigned) x hexadecimal number (unsigned), using lower-case letters. The # flag prepends 0x. X hexadecimal number (unsigned), using upper-case letters. The # flag prepends 0x Restriction: The output could be more accurate for floating point values. Some rather special cases are not implemented. See also: fopen(), fwrite(), scanf() ------------------------------------------------------------------------------ #include <sys/ptrace.h> [*] [SysV] int ptrace (int request, int pid, int addr, int data); Debug child process. The child process is identified by PID. The following REQUEST codes are defined: PTRACE_TRACEME Not implemented -- use spawn (P_DEBUG) instead PTRACE_PEEKTEXT Read a 32-bit word from the text space of the child process. ADDR is the address of the word. The word at ADDR is returned. PTRACE_PEEKDATA See PTRACE_PEEKTEXT. On machines with separate data and text space, this request will read from the data space. PTRACE_PEEKUSER Read a 32-bit word from the process table of the child process. This can be used to read the registers of the child process. See sys/user.h for details. PTRACE_POKETEXT Write the 32-bit word DATA to address ADDR of the text space of the child process. PTRACE_POKEDATA See PTRACE_POKETEXT. On machines with separate data and text space, this request will write to the data space. PTRACE_POKEUSER Write a 32-bit word to the process table of the child process. This can be used to alter the registers of the child process. See sys/user.h for details. Not all registers can be modified. PTRACE_RESUME Resume the child process. The child process will run until a signal occurs. PTRACE_EXIT Kill the child process. PTRACE_STEP Execute the next instruction of the child process. PTRACE_SESSION If DATA is 0, select the session of the calling process. If DATA is 1, select the child session. If DATA is 2, the child session is automatically selected by the next PTRACE_STEP (on CALL instructions only) or PTRACE_RESUME command. This request is emx specific and is ignored under DOS. As -1 is a legal return value for the PTRACE_PEEK requests, you should set errno to 0 before calling ptrace() and check errno after the call. Restrictions: Currently, a process can debug only one child process. While debugging a child process, wait() cannot be used for waiting for another child. When using the system call library libsys.lib (-Zsys), ptrace() is not available. See also: spawn(), wait() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int putc (int c, FILE *stream); int putchar (int c); Write the character C to STREAM or stdout, respectively. putchar (c) is equivalent to putc (c, stdout). The character written is returned. On failure, EOF is returned. putc() and putchar() are in-line functions or macros. See also: fprintf(), fputs(), fputc() ------------------------------------------------------------------------------ #include <stdlib.h> [BSD] int putenv (const char *string); Put STRING into the environment of the calling process. STRING is a pointer to a string of the form name=value where NAME is the name of the environment variable and VALUE is the value of the environment variable. If the environment variable NAME already exists, the current value is replaced by the new value, VALUE. If NAME is not already in the environment, STRING is put into the environment. Do not free or reuse STRING after calling putenv(). Using an auto variable is also a bad idea. After calling putenv(), do not use the ENVP argument of main(). Use environ instead. On success, 0 is returned. On failure, -1 is returned. See also: getenv() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int puts (const char *string); Write the string STRING followed by a newline (LF) character (which is translated to CR/LF if stdout is in text mode) to the stdout stream. On failure, EOF is returned. Otherwise, a non-negative value is returned. See also: fputs(), fgets() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int putw (int x, FILE *stream); Write the word (int) X to STREAM and return it. On failure, -1 is returned. As -1 is also a possible int value, you have to use ferror() to recognize an error condition. Avoid using this function. See also: getw(), fwrite() ------------------------------------------------------------------------------ #include <stdlib.h> /* use this */ [ANSI] #include <search.h> /* or this */ void qsort (void *base, size_t num, size_t width, int (*compare)(const void *x1, const void *x2)); Sort an array. BASE is a pointer to the beginning of the array. The array contains NUM elements of WIDTH bytes each. COMPARE is called to compare the two elements pointed to by X1 and X2. COMPARE should return a negative value, if element X1 is less than element X2, zero, if element X1 equals element X2, and a positive value if element X1 is greater than element X2. qsort() is not stable: the order of equal elements is undefined. ------------------------------------------------------------------------------ #include <signal.h> [ANSI] int raise (int sig); Raise the signal SIG. This causes the program to end, if SIG_DFL is installed for that signal. If SIG_IGN is installed for that signal, the request is ignored. If a signal handler has been installed and the signal is not waiting for acknowledgement, the signal handler will be called. If SIGQUIT, SIGILL, SIGTRAP, SIGEMT, SIGFPE, SIGBUS, SIGSEGV or SIGSYS is raised and SIG_DFL is installed for that signal, a core dump file will be created unless the -c emx option is used (see `Using emx options'). If successful, raise() returns 0. Otherwise -1 is returned and errno set to the following value: EINVAL SIG is not a valid signal number Restriction: Core dump files are not written if LINK386 was used for linking. See also: abort(), kill(), signal() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] int rand (void); void srand (unsigned int seed); rand() returns a pseudo-random number in the range 0 through RAND_MAX (32767). RAND_MAX is defined in stdlib.h. srand() initializes the sequence of random numbers. The initial SEED value (without calling srand()) is 1. See also: libbsd (bsddev.doc) ------------------------------------------------------------------------------ #include <io.h> [UNIX] int read (int handle, void *buf, size_t nbyte); Read up to NBYTE characters from file HANDLE to the buffer BUF. The number of characters read is returned. If there is an error, -1 is returned. The return value may be less than NBYTE. For instance, this happens if the end of the file is reached. See also `termio' below. If HANDLE is 0 and HANDLE refers to the keyboard and O_NDELAY has been set with fcntl() for HANDLE and the IDEFAULT and ICANON bits have been reset with ioctl() for HANDLE, -1 is returned and errno is set to EAGAIN if the call to read() would block. Even if there is some data available, but not enough with respect to VMIN, -1 is returned. See also: open(), setmode(), write() ------------------------------------------------------------------------------ #include <stdlib.h> [*] [emx] #include <sys/kbdscan.h> /* optional, for extended scan codes */ int _read_kbd (int echo, int wait, int sig); Get a character from the keyboard. Extended codes are preceded by a null character (call _read_kbd() again!), the scan codes are defined in /emx/include/sys/kbdscan.h. If ECHO is non-zero, input will be echoed, if WAIT is non-zero, _read_kbd() will wait until a character is available, if WAIT is zero and no character is available, _read_kbd() will return -1, if SIG is zero, Ctrl-C will be ignored. Examples: #define getch() _read_kbd (0, 1, 0) #define getche() _read_kbd (1, 1, 0) Please use `termio' instead, see below. See also the termio.c test program. It's important to call _read_kbd() again if _read_kbd() returns 0. To see what happens if you don't, type Ctrl-S F10 under DOS. See also: ioctl(), read(), conio.h ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] void *realloc (void *mem, size_t size); Reallocate the block of memory pointed to by MEM, making it big enough to hold SIZE bytes. If MEM is NULL, a new block of memory is allocated. Otherwise, MEM must be a pointer returned by calloc(), malloc() or realloc(); the size of MEM is adjusted. If MEM cannot be expanded in-place, it is moved. A pointer to the new, resized block of memory is returned. If there is not enough memory available, NULL is returned. MEM can also be a pointer to a block of memory freed by free() as long as calloc(), malloc() and realloc() have not been called since freeing the block. Using this feature is not recommended, it may be removed in future implementations of realloc(). See also: malloc() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] void _remext (char *path); Remove the extension from the file name PATH. If the last member of PATH starts with a dot ("/usr/mattes/.profile", for instance) PATH isn't modified. See also: _defext(), _getext(), _splitpath() ------------------------------------------------------------------------------ #include <stdio.h> /* use this */ [ANSI] #include <io.h> /* or this */ int remove (const char *name); Delete the file NAME. 0 is returned if successful, -1 if not. Under OS/2 and DOS, unlink() and remove() are equivalent. See also: unlink(). ------------------------------------------------------------------------------ #include <stdio.h> /* use this */ [ANSI] #include <io.h> /* or this */ int rename (const char *old_name, const char *new_name); Rename the file or directory OLD_NAME to NEW_NAME. Moving a file to a different directory on the same drive is possible. 0 is returned if successful, -1 if not. ------------------------------------------------------------------------------ #include <stdlib.h> [emx] void _response (int *argcp, char ***argvp); Expand response files. If you want response files (@filename, filename contains a list of arguments one per line) to be expanded, call _response (&argc, &argv); at the beginning of main(). Response file arguments enclosed in double quotes won't be expanded. If a response file cannot be opened, the argument is kept unchanged. See also: main(), _wildcard() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] void rewind (FILE *stream); Move the file pointer of STREAM to the beginning of the file and clear the error and end-of-file indicators. See also: fseek() ------------------------------------------------------------------------------ #include <strings.h> [BSD] char *rindex (const char *string, int c); Return a pointer to the last occurrence of the character C in the null-terminated string STRING. If there is no character C in STRING, NULL is returned. If C is 0, a pointer to the terminating null character of STRING is returned. See also: index(), strrchr() ------------------------------------------------------------------------------ #include <math.h> double rint (double x); Return as floating-point number the integer that is nearest to X. If there's a tie, that is, fabs(rint(x)-x) == 0.5, rint(x) is even. See also: ceil(), floor(), trunc() ------------------------------------------------------------------------------ #include <stdlib.h> [BSD] int rmdir (const char *name); Remove the directory NAME. Only one directory is removed in one step. If NAME (or a subdirectory of NAME) is the current working directory of a process, it cannot be removed. On success, 0 is returned. On failure, -1 is returned. See also: mkdir() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int _rmtmp (void); Close and delete the files created by tmpfile() in the current working directory. It must be used only in the directory in which tmpfile() created the temporary files. The number of closed (and deleted) files is returned. See also: tmpfile() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] void *sbrk (int incr); Change memory allocation by INCR bytes. If INCR is positive, the memory limit is increased. If INCR is negative, the memory limit is decreased (not yet completely implemented). On success, sbrk() returns the previous memory limit. Otherwise, -1 cast as pointer is returned and errno set to ENOMEM. Please don't use sbrk() -- use malloc() instead for memory allocation. See also: brk(), malloc() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int scanf (const char *format, ...); The stream STREAM is read and input is parsed according to the format string FORMAT. For each field in FORMAT there must be a pointer to the location receiving the value. The pointers are passed after the FORMAT argument. Whitespace in FORMAT matches whitespace in the input. All other characters except for % are compared to the input. Parsing ends if a mismatch is encountered. %% in FORMAT matches % in the input. A % which is not followed by another % or the end of the string starts a field specification. The field in the input is interpreted according to the field specification. For most field types, whitespace is ignored at the start of a field. Field specifications have the format %[*][width][size]type where items in brackets are optional. If the * is present, the value is not assigned. No pointer will be fetched from the argument list. WIDTH is a positive integral decimal number specifying the maximum field width. At most this many characters are read for this field. SIZE is either h for a `short' type or l for a `long' type. If SIZE is omitted, the default size is used. TYPE is one of the following characters: c character. Whitespace is not skipped (char) d decimal integer (int) e f g floating-point value (float) E F G floating-point value (float) i decimal, octal or hexadecimal integer (int) n number of characters read so far (int). Doesn't take input o octal integer (int) s string (char *) x hexadecimal integer (int) [ string (char *) [...] Note: Use %lf for variables of type `double'. On success, the number of fields converted is returned. Otherwise, EOF is returned. See also: fgets(), fread(), fscanf(), printf(), sscanf(), vscanf() ------------------------------------------------------------------------------ #include <stdlib.h> [*] [emx] void _scrsize (int *dst); Retrieve the screen (window) size. The number of text columns (width) is stored to DST[0], the number of text rows (height) is stored to DST[1]. Restriction: When using the system call library libsys.lib (-Zsys), this function always sets DST[0] to 80 and DST[1] to 25. See also: v_dimen() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] void _searchenv (const char *name, const char *var, char *path); Search a file in the directories listed in an environment variable. First, the file name NAME is tried as is. If that file does not exist, the directories listed in the environment variable VAR are searched. If the file is found, the constructed path name (either NAME or a directory plus NAME) will be copied to PATH. If the file is not found, PATH will be the empty string. See also: getenv(), _path() ------------------------------------------------------------------------------ #include <io.h> [emx] int _seek_hdr (int handle); Move the file pointer of HANDLE to the a.out header of an executable file (a.out or bound .exe). _seek_hdr() assumes that the file pointer points to the beginning of the header (ie, the beginning of the file). If there is an error, _seek_hdr() sets errno and returns -1. If no header is found, the file pointer will be repositioned to the original position. See also: _fseek_hdr() ------------------------------------------------------------------------------ #include <sys/types.h> [*] [BSD] #include <sys/time.h> #include <io.h> int select (int nfds, struct _fd_set *readfds, struct _fd_set *writefds, struct _fd_set *exceptfds, struct timeval *timeout); Wait for a file handle to become ready. select() returns as soon as there's data ready to be read from a handle in READFDS. If TIMEOUT is NULL, select() waits indefinitely. Otherwise, waiting terminates after the time-out value given by TIMEOUT. NFDS is the number of handles to be checked. select() returns the number of ready handles and updates READFDS to include only the ready handles. On time out, 0 is returned. On failure, -1 is returned. The following macros are available for handling the bitstrings used by select(): FD_ZERO(s) clear all bits of S FD_SET(n,s) set bit N in S FD_CLR(n,s) clear bit N in S FD_ISSET(n,s) Return a non-zero value iff bit N is set in S select() is implemented for the following types of handles: - stdin handles (keyboard) with IDEFAULT not set (DOS: handle 0 only). Note that if ICANON is set, read() has to wait until the line is completed - named pipes - pipes created with pipe() by programs using emx.dll - all file handles under DOS Restrictions: WRITEFDS and EXCEPTFDS are ignored. When using the system call library libsys.lib (-Zsys), select() is not available. See also: ioctl(), pipe() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int setbuf (FILE *stream, char *buffer); Associate the buffer BUFFER (of size BUFSIZ) with STREAM. This must be done before the file has been read or written. If BUFFER is NULL, the file is unbuffered. You should use setvbuf() instead. BSD setbuf() seems to have an `int' return value, therefore emx setbuf() has an `int' return value. This should not break programs which expect `void setbuf()'. See also: setbuffer(), setvbuf() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] int setbuffer (FILE *stream, char *buffer, size_t size); Associate the buffer BUFFER (of size SIZE) with STREAM. This must be done before the file has been read or written. If BUFFER is NULL, the file is unbuffered. You should use setvbuf() instead. BSD setbuffer() seems to have an `int' return value, therefore emx setbuffer() has an `int' return value. This should not break programs which expect `void setbuffer()'. See also: setvbuf() ------------------------------------------------------------------------------ #include <setjmp.h> [ANSI] int setjmp (jmp_buf here); Save the current stack context in HERE and return 0. Later, you can continue at this point by calling longjmp(). When execution continues at setjmp() after calling longjmp(), the second argument of longjmp() is returned, which is always non-zero. See also: longjmp() ------------------------------------------------------------------------------ #include <locale.h> [ANSI] char *setlocale (int category, const char *locale); Not implemented. ------------------------------------------------------------------------------ #include <io.h> [PC] #include <fcntl.h> int setmode (int handle, int mode); Change the text/binary mode of a file handle. MODE must be either O_BINARY or O_TEXT. If there's an error, setmode() returns -1 and sets errno to EBADF or EINVAL otherwise setmode() returns the previous mode, that is, O_BINARY or O_TEXT. Note: Use _fsetmode() to change the mode of a stream. See also: _fsetmode(), open() ------------------------------------------------------------------------------ #include <sys/time.h> [BSD] int settimeofday (const struct timeval *tp, const struct timezone *tzp); Not implemented. ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int setvbuf (FILE *stream, char *buffer, int mode, size_t size); Set the buffering mode of STREAM to MODE, using the buffer BUFFER of size SIZE bytes. Available modes are: _IONBF the file is unbuffered, BUFFER and SIZE are ignored _IOFBF the file is full buffered _IOLBF the file is line buffered The file must not have been read or written since it was opened. If BUFFER is NULL, a buffer of SIZE bytes is allocated by setvbuf() using malloc() unless MODE is _IONBF. When reading a file, _IOFBF and _IOLBF are equivalent. Each time a newline character is written to a line-buffered file, the buffer is flushed. The buffer is also flushed if it becomes full while writing. The buffer is filled by reading from the disk file (or device) if the buffer becomes empty while reading. On success, 0 is returned. On failure, a non-zero value is returned. See also: fflush() ------------------------------------------------------------------------------ #include <signal.h> [ANSI] void (*signal (int sig, void (*handler)()))(int sig); Install the signal handler HANDLER for signal SIG. You can install the default signal handler by using SIG_DFL for HANDLER. You can cause the signal to be ignored by using SIG_IGN for HANDLER. SIG must not be SIGKILL. Some systems reset a signal to SIG_DFL before calling the signal handler. emx doesn't. SIG_ACK is used instead: Once a signal handler for a specific signal has been called, that signal is disabled until acknowledged. You can acknowledge a signal by calling signal (signal_number, SIG_ACK). Only one signal of any type may be pending. (May change in the future.) The default processing for all signals except for SIGCLD is to terminate the process. If a signal which isn't ignored (that is, SIG_DFL or handler installed) occurs while calling read() with `termio' enabled (see below), -1 will be returned by read() and errno will be set to EINTR. The buffer will flushed. Do not use floating point math in a signal handler if the signal handler will return to the interrupted code. File i/o in the signal handler is also dangerous because a file i/o function could have been interrupted by the signal. If successful, signal() returns the previous signal handler (includes SIG_IGN and SIG_DFL) defined for signal SIG. On failure, SIG_ERR is returned. Restrictions: SIGPIPE is not yet implemented. When using the system call library libsys.lib (-Zsys), SIGALRM and SIGCLD don't occur. See also: abort(), kill(), raise() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] unsigned sleep (unsigned sec); Suspend the calling process for SEC seconds. Currently, sleep() doesn't get interrupted by SIGALRM and always returns 0. SEC should not exceed 4294967. See also: alarm(), _sleep2() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] unsigned _sleep2 (unsigned millisec); Suspend the calling process for MILLISEC milliseconds. Currently, _sleep2() doesn't get interrupted by SIGALRM and always returns 0. As the system clock is used for timing, the actual duration of the time interval depends on the granularity of the system clock. The time interval is rounded up to the next clock tick. Also note that calling _sleep2() involves an overhead. See also: alarm(), sleep() ------------------------------------------------------------------------------ #include <io.h> [PC] #include <share.h> int sopen (const char *name, int oflag, int shflag, ...); Open a file or device with an explicit sharing mode. NAME is the name of the file or device. OFLAG contains one or more of the following values, combined by the | operator: O_RDONLY Open for reading. Writing is not allowed O_WRONLY Open for writing. Reading is not allowed O_RDWR Open for reading and writing O_APPEND Move the file pointer to the end of file before any write operation takes place. This is used for appending to a file O_CREAT Create the file if it does not exist O_TRUNC Truncate the size of the file to 0 O_EXCL Fail if the O_CREAT is used and the file already exists O_NDELAY Currently ignored. O_BINARY Binary mode, no translation. See below O_TEXT Text mode, translate CR/LF to LF. See below If a new file is created, PMODE (modified by the umask value), is used to set the file permissions. S_IREAD grants read access, S_IWRITE grants write access. S_IREAD is ignored (DOS and OS/2 limitation). There are two additional OFLAG flags: O_TEXT for text mode, O_BINARY for binary mode. Text mode, which is the default, translates each CR/LF pair to a LF character on input and translates LF characters to CR/LF pairs on output. If the last character of a file is Ctrl-Z, it is discarded on input. Binary mode disables these transformations. If the file or device cannot be opened, open() sets errno and returns -1. If open() succeeds, the file handle is returned. The file handle is always greater than -1. The mode O_TRUNC|O_RDONLY is not implemented. The mode O_TEXT|O_WRONLY does not overwrite a Ctrl-Z at the end of the file -- this causes problems when appending. Ctrl-Z at the end of the file is obsolete, anyway. The sharing mode of the file is given by SHFLAG. The following sharing modes are available: SH_DENYRW Deny read and write access SH_DENYRD Deny read access (permit write access) SH_DENYWR Deny write access (permit read access) SH_DENYNO Deny nothing (permit read and write access) See also: close(), fdopen(), open() ------------------------------------------------------------------------------ #include <process.h> [*] [PC] /* spawn() */ int spawnl (int mode, const char *name, const char *arg0, ...); int spawnle (int mode, const char *name, const char *arg0, ...); int spawnlp (int mode, const char *name, const char *arg0, ...); int spawnlpe (int mode, const char *name, const char *arg0, ...); int spawnv (int mode, const char *name, const char * const *argv); int spawnve (int mode, const char *name, const char * const *argv, const char * const *envp); int spawnvp (int mode, const char *name, const char * const *argv); int spawnvpe (int mode, const char *name, const char * const *argv, const char * const *envp); Run a process. NAME is the name of the executable file to run. Use spawnl(), spawnle(), spawnlp() or spawnlpe() for passing a fixed number of arguments. ARG0 is the 0th argument which is the program name, by convention. Following ARG0, the arguments are given. After the last argument, a NULL pointer must be following. At least ARG0 must be specified. Use spawnv(), spawnve(), spawnvp() or spawnvpe() for passing a variable number of arguments. ARGV points to an array of strings. The first entry is the program name, by convention. The last argument must be followed by a NULL pointer. spawnl(), spawnlp(), spawnv() and spawnvp() pass the environment of the current process to the child process. To pass a different environment to the child process pass a pointer to an array of strings after the NULL argument pointer of spawnle() and spawnlpe() or pass the pointer in the ENVP argument of spawnve() and spawnvpe(). The last environment string in the array must be followed by a NULL pointer. The MODE argument specifies how to run the child process. The following values are available: P_WAIT run the process synchronously, that is, control returns to the parent process after the child process finishes P_NOWAIT run the process asynchronously, that is in parallel with the parent process. P_NOWAIT is not implemented for DOS P_OVERLAY replace the parent process, that is, run the child process and terminate the parent process P_DEBUG run the process in debugging mode, that is, under control of the parent process. Use ptrace() to control the child process P_DETACH run the process detached, that is, without input and output. P_DETACH is not available under DOS P_SESSION run the process in a separate session. P_SESSION is not available under DOS. Additional flags are available for P_SESSION, which can be added by using the | operator. Use one of the following for selecting the session type: P_DEFAULT let the operating system choose the session type P_FULLSCREEN start a full-screen session P_WINDOWED start a windowed session These flags control the initial appearance of the window: P_MINIMIZE minimize the window P_MAXIMIZE maximize the window Additionally, you can use the following flags: P_BACKGROUND start the session in the background P_FOREGROUND start the session in the foreground. This works only if the calling session is in the foreground. P_FOREGROUND is the default P_NOCLOSE don't close the window automatically when the process ends When the new process terminates, SIGCLD is raised in the process which started that process. This does not apply to P_WAIT, P_OVERLAY and P_DETACH. Return value: the return value of the child process (P_WAIT) or the process ID of the child process (P_NOWAIT and P_DEBUG) if successful. Otherwise -1. Restrictions: When running a (native) DOS program, the environment of emx, not that of the process calling spawn() will be inherited. The command line length is restricted to 126 characters when running DOS programs. DOS programs can only be run in P_WAIT mode. P_NOWAIT is not implemented under DOS. The default extension is .exe; if you want to run a .com file, explicitly add .com. Currently, DOS seems to crash if you try to spawn a .COM file without using emx option -p, see `Using emx options'. (The machine crashes on the second attempt.) When using the system call library libsys.lib (-Zsys), only modes P_WAIT, P_NOWAIT and P_OVERLAY are currently available. SIGCLD is not implemented under DOS. See also: exit(), ptrace(), system(), wait() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char **_splitargs (char *string, int *count); Parse STRING like a command line and build a vector of pointers to the arguments. The vector is terminated by a NULL pointer. The number of arguments is stored to the variable pointed to by COUNT unless COUNT is NULL. STRING is modified by _splitargs(), the pointers in the resulting vector point into STRING. _splitargs() allocates the vector using malloc(). If you no longer need the vector, use free() to deallocate it. On error, _splitargs() sets errno and returns NULL. Arguments in STRING are separated by whitespace (one or more blanks, tabs and linefeeds). Whitespace at the start of STRING is skipped. To include blanks, tabs or linefeeds in an argument, the argument must be quoted using double quotation marks. To remove the special meaning of a double quote, precede it with a backslash. To remove the special meaning of a backslash in front of a double quote, precede the backslash with a backslash. The backslash character doesn't have a special meaning unless it precedes a double quote or any number of backslashes followed by a double quote. In other words: If there are n backslashes (\) immediately preceding a double quote character ("), floor(n/2) backslashes are put into the argument. If n is odd, the double quote character is put into the argument. If n is even (including zero), the double quote character is used for quoting, that is, spaces are not treated as argument delimiters until the next `quoting' double quote character (ie, a double quote character immediately preceded by an even number (including zero) of backslashes) is found. Backslashes not preceding a quote character are always read as backslashes. See also: popen(), system() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] void _splitpath (const char *src, char *drive, char *dir, char *fname, char *ext); Split the path name SRC into its components. The drive name (including the colon) is stored to DRIVE. The directory (including the final slash or backslash) is copied to DIR, the file name without extension is copied to FNAME, the extension (including the dot) is copied to EXT. The buffers should be of size _MAX_DRIVE, _MAX_DIR, _MAX_FNAME and _MAX_EXT, respectively. These constants include the terminating null characters. If one of the pointers (except for SRC) is NULL, that component is not stored. Example: char drive[_MAX_DRIVE], dir[_MAX_DIR]; char fname[_MAX_FNAME], ext[_MAX_EXT]; char *path = "c:/files/more/test.file.c"; _splitpath (path, drive, dir, fname, ext); Results of the example: drive = "c:" dir = "/files/more/" fname = "test.file" ext = ".c" See also: _fngetdrive(), _getext(), _getname() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int sprintf (char *buffer, const char *format, ...); Formatted output to the string BUFFER. The string must be big enough to hold the output. On success, the number of characters copied to BUFFER (excluding the terminating null character) is returned. Otherwise, EOF is returned. See also: printf(), sscanf() ------------------------------------------------------------------------------ #include <math.h> [ANSI] double sqrt (double x); Compute and return the square root of X. If X is negative, +#NAN is returned and errno set to EDOM. See also: cbrt(), pow() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int sscanf (const char *buffer, const char *format, ...); Parse BUFFER according to the format string FORMAT. For each field in FORMAT there must be a pointer to the location receiving the value. The pointers are passed after the FORMAT argument. On success, the number of fields converted is returned. Otherwise, EOF is returned. See also: scanf(), sprintf() ------------------------------------------------------------------------------ #include <io.h> [UNIX] #include <sys/types.h> #include <sys/stat.h> int stat (const char *name, struct stat *buffer); Retrieve information about the file or directory NAME. stat() will put the data into the structure pointed to by BUFFER. Restrictions: st_dev and st_rdev are set to zero. Each call to stat() returns a different value for st_ino. See also: fstat() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strcat (char *string1, const char *string2); Append the null-terminated string STRING2 to the null-terminated string STRING1 and return STRING1. The strings must not overlap. See also: strcpy() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strchr (const char *string, int c); Return a pointer to the first occurrence of the character C in the null-terminated string STRING. If there is no character C in STRING, NULL is returned. If C is 0, a pointer to the terminating zero of STRING is returned. See also: index(), memchr(), strrchr(), strstr() ------------------------------------------------------------------------------ #include <string.h> [ANSI] int strcmp (const char *string1, const char *string2); Compare the null-terminated strings STRING1 and STRING2. If STRING1 is less than STRING2, a negative value is returned. If STRING1 is equal to STRING2, zero is returned. If STRING1 is greater than STRING2, a positive value is returned. See also: memcmp(), stricmp(), strncmp() ------------------------------------------------------------------------------ #include <string.h> [ANSI] int strcoll (const char *string1, const char *string2); Not implemented. See also: strcmp() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strcpy (char *string1, const char *string2); Copy the null-terminated string STRING2 to STRING1 and return STRING1. The strings must not overlap. See also: memccpy(), memcpy(), strcat(), strncpy() ------------------------------------------------------------------------------ #include <string.h> [ANSI] size_t strcspn (const char *string1, const char *string2); Return the length of the initial substring of STRING1 which consists of characters not in STRING2. That is, the index of the first character in STRING1 which also occurs in STRING2 is returned. If all characters of STRING1 are not in STRING2, the length of STRING1 is returned. See also: strpbrk(), strspn() ------------------------------------------------------------------------------ #include <string.h> [UNIX] char *strdup (const char *string); Creates a duplicate of STRING by using malloc() to allocate storage and copying STRING. A pointer to the new string is returned. If there is not enough memory, NULL is returned. See also: malloc(), strcpy() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strerror (int errnum); Return a pointer to a an error message according to the error number ERRNO. You must not write to the string returned by strerror(). The string may get changed by the next call to strerror(). See also: errno, perror(), sys_errlist ------------------------------------------------------------------------------ #include <time.h> [ANSI] size_t strftime (char *string, size_t size, const char *format, const struct tm *t); Format time. The output string is written to the buffer STRING of SIZE characters, including the terminating null character. Like sprintf(), strftime() copies FORMAT to STRING, replacing format specifications with formatted data from T. Ordinary characters are copied unmodified. The following format specifications are available: %% percent sign %a locale's abbreviated weekday name %A locale's full weekday name %b locale's abbreviated month name %B locale's full month name %c locale's date and time (this is currently equivalent to %a %b %d %H:%M:%S %Y) %d day of month (01-31) %D date, this is equivalent to %m/%d/%y %e day of month ( 1-31), blank padded %h locale's abbreviated month name %H hour (00-23) %I hour (01-12) %j day of year (001-366) %m month (01-12) %M minute (00-59) %n newline character %p locale's equivalent to AM or PM, as appropriate %r time in AM/PM notation, this is equivalent to %I:%M:%S %p %S second (00-59) %t TAB character %T time, this is equivalent to %H:%M:%S %U week number of the year, the first day of the week is Sunday (00-53) %w weekday, the first day of the week is Sunday (0-6) %W week number of the year, the first day of the week is Monday (00-53) %x locale's date representation (this is currently equivalent to %m/%d/%y) %X locale's time representation (this is currently equivalent to %H:%M:%S) %y year without century (00-99) %Y year with century (1970-2038) %Z timezone name (taken from the timezone variable, as the timezone isn't provided by T) If % is followed by a character not listed above, the results are undefined. On success, the number of characters copied to STRING, excluding the terminating null character, is returned. On failure (SIZE exceeded), 0 is returned. Restrictions: locales are not yet implemented. See also: asctime(), sprintf() ------------------------------------------------------------------------------ #include <string.h> [PC] int stricmp (const char *string1, const char *string2); Compare STRING1 and STRING2, ignoring letter case. If the strings are equal, 0 is returned. Otherwise, a positive value is returned if STRING1 is greater than STRING2 (after conversion to lower case). A negative value is returned if STRING1 is less than STRING2 (after conversion to lower case). See also: strcmp(), tolower() ------------------------------------------------------------------------------ #include <string.h> [ANSI] size_t strlen (const char *string); Returns the length (number of characters) of the string STRING. The length does not include the terminating null character. See also: strchr() ------------------------------------------------------------------------------ #include <string.h> [PC] char *strlwr (char *string); Converts the string STRING to lower case. The characters 'A' through 'Z' are mapped to the characters 'a' through 'z'. All other characters are not changed. The STRING argument is returned. See also: _fnlwr(), strupr() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strncat (char *string1, const char *string2, size_t count); Append the null-terminated string STRING2 to the null-terminated string STRING1. At most COUNT characters of STRING2 are appended to STRING1. strncat() terminates the new value of STRING1 with a null character. STRING1 is returned. See also: strcat(), strncpy() ------------------------------------------------------------------------------ #include <string.h> [ANSI] int strncmp (const char *string1, const char *string2, size_t count); Compare the null-terminated strings STRING1 and STRING2. At most the first COUNT characters are compared. If STRING1 is less than STRING2, a negative value is returned. If STRING1 is equal to STRING2, zero is returned. If STRING1 is greater than STRING2, a positive value is returned. See also: memcmp(), strcmp(), strnicmp() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strncpy (char *string1, const char *string2, size_t count); Copy the null-terminated string STRING2 to STRING1 and return STRING1. The strings must not overlap. At most the first COUNT characters of STRING2 are copied. If STRING2 is shorter than COUNT characters, STRING1 is padded with null characters to COUNT characters. A terminating null character is always appended. See also: strcpy(), strncat() ------------------------------------------------------------------------------ #include <string.h> [emx] char *_strncpy (char *string1, const char *string2, size_t size); Copy the null-terminated string STRING2 to STRING1 and return STRING1. The strings must not overlap. At most SIZE characters, including the terminating null character, are copied to STRING1. A terminating null character is always appended, even if STRING2 is too long. See also: strcpy(), strncpy() ------------------------------------------------------------------------------ #include <string.h> [PC] int strnicmp (const char *string1, const char *string2, size_t count); Compare the null-terminated strings STRING1 and STRING2 ignoring letter case. At most the first COUNT characters are compared. If STRING1 is equal to STRING2, zero is returned. If STRING1 is less than STRING2 (after conversion to lower case), a negative value is returned. If STRING1 is greater than STRING2 (after conversion to lower case), a positive value is returned. See also: memicmp(), strcmp(), strncmp(), tolower() ------------------------------------------------------------------------------ #include <string.h> [PC] char *strnset (char *string, int c, size_t count); Set, at most, the first COUNT characters of STRING to the character C and return STRING. If the length of STRING is less than COUNT, strnset() stops at the terminating null character. See also: memset(), strset() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strpbrk (const char *string1, const char *string2); Return a pointer to the first occurrence in STRING1 of a character of STRING2. The terminating null character is not included in the search. If no character of STRING2 can be found in STRING1, NULL is returned. See also: strchr(), strcspn() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strrchr (const char *string, int c); Return a pointer to the last occurrence of the character C in the null-terminated string STRING. If there is no character C in STRING, NULL is returned. If C is 0, a pointer to the terminating null character of STRING is returned. See also: rindex(), strchr() ------------------------------------------------------------------------------ #include <string.h> [PC] char *strrev (char *string); Reverse the order of the characters in STRING return STRING. The terminating null character remains in place. ------------------------------------------------------------------------------ #include <string.h> [PC] char *strset (char *string, int c); Replace all the characters of STRING with the character C. The terminating null character is not changed. See also: memset(), strnset() ------------------------------------------------------------------------------ #include <string.h> [ANSI] size_t strspn (const char *string1, const char *string2); Return the length of the initial substring of STRING1 which consists entirely of characters in STRING2. That is, the index of the first character in STRING1 which does not occur in STRING2 is returned. If all characters in STRING1 also occur in STRING2, the length of STRING1 is returned. See also: strcspn(), strpbrk() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strstr (const char *string1, const char *string2); Return a pointer to the first occurrence of STRING2 in STRING1. If the length of STRING2 is zero, STRING1 is returned. If STRING2 is not a substring of STRING1, NULL is returned. See also: strchr() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] double strtod (const char *string, char **end_ptr); Convert ASCII representation of a number to a double. Leading white space is skipped. strtod() stops at the first character that cannot be converted. If END_PTR is not NULL, a pointer to that character is stored to *END_PTR. strtod() sets errno and returns 0.0 on failure, sets errno and returns +#NAN or -#NAN on overflow. The string pointed to by STRING is expected to have the following form: [whitespace] [+|-] [digits] [.digits] [[d|D|e|E] [+|-] digits] See also: sscanf() ------------------------------------------------------------------------------ #include <string.h> [ANSI] char *strtok (char *string1, const char *string2); Return a pointer to the next token in STRING1. The characters of STRING2 are the set of delimiting characters. Tokens in STRING1 are separated by one or more characters from STRING2. The first call to strtok() for STRING1 skips leading delimiters and returns a pointer to the first token. To get the next token of STRING1, call strtok() with a NULL argument for STRING1. STRING2, the set of delimiters, may be different on subsequent calls. strtok() modifies the string STRING1 by inserting null characters for terminating tokens. Thus, the pointer returned by strtok() points to a null-terminated token. If there are no more tokens, NULL is returned. ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] long strtol (const char *string, char **end_ptr, int radix); Convert ASCII representation of a number to a signed long integer. Leading white space is skipped. RADIX is the number base used for conversion. It must either be between 2 and 36 or be zero. If RADIX is 0, the number base is derived from the format of the number. If the number starts with `0x', base 16 is used. If the number starts with `0' (not followed by `x'), base 8 used. If the number does not start with `0', base 10 is used. strtol() stops at the first character that cannot be converted. If END_PTR is not NULL, a pointer to that character is stored to *END_PTR. strtol() sets errno and returns 0 on failure, sets errno and returns LONG_MIN or LONG_MAX on overflow. See also: _ltoa(), strtoul(), sscanf() ------------------------------------------------------------------------------ #include <stdlib.h> [ANSI] unsigned long strtoul (const char *string, char **end_ptr, int radix); Convert ASCII representation of a number to an unsigned long integer. Leading white space is skipped, a sign character is not allowed. RADIX is the number base used for conversion. It must either be between 2 and 36 or be zero. If RADIX is 0, the number base is derived from the format of the number. If the number starts with `0x', base 16 is used. If the number starts with `0' (not followed by `x'), base 8 used. If the number does not start with `0', base 10 is used. strtoul() stops at the first character that cannot be converted. If END_PTR is not NULL, a pointer to that character is stored to *END_PTR. strtoul() sets errno and returns 0 on failure, sets errno and returns ULONG_MAX on overflow. See also: _ultoa(), strtol(), sscanf() ------------------------------------------------------------------------------ #include <string.h> [PC] char *strupr (char *string); Converts the string STRING to upper case. The characters 'a' through 'z' are mapped to the characters 'A' through 'Z'. All other characters are not changed. The STRING argument is returned. See also: strlwr() ------------------------------------------------------------------------------ #include <stdlib.h> [UNIX] void swab (const void *src, void *dst, size_t n); Copy N bytes from SRC to DST, swapping each pair of adjacent bytes. N must be even. ------------------------------------------------------------------------------ #include <stdlib.h> [emx] char _swchar (void); Retrieve the current switch character. If the switch character has been changed to '-', _swchar() returns '-'. Otherwise, _swchar() returns 0. In this case, you should use the standard switch character '/'. See also: getopt() ------------------------------------------------------------------------------ #include <stdlib.h> [*] [emx] int _syserrno (void); Return the OS/2 or DOS error code for the last system call of the current thread. If there was no error, 0 is returned. If the last system call hasn't called an OS/2 or DOS function, 0 is returned. Restrictions: Not implemented under DOS. When using the system call library libsys.lib (-Zsys), this function is not supported. ------------------------------------------------------------------------------ #include <process.h> [ANSI] int system (const char *name); Execute the command NAME by passing it to the command interpreter. system() uses the COMSPEC environment variable for locating cmd.exe or command.com, respectively. The PATH environment variable is not used for locating cmd.exe. If the argument is "", an interactive shell will be started. If the argument is NULL, system() only checks whether cmd.exe or command.com, respectively, can be found. When running a (native) DOS program, the environment of emx, not that of the process calling spawn() will be inherited. Because command.com is used under DOS, the command line is restricted to about 123 characters. If you don't need a command shell, use spawn() instead of system(). It's a bad idea to run emx programs using system() -- not tested. You must use the -p emx option when using system() under DOS, see `Using emx options'. If system() failed, errno is set and -1 is returned. If the argument is NULL and the command processor can be found, 0 is returned. In all other cases, the return code of the command processor is returned. The return code of the program run by the command processor is returned by cmd.exe but not by command.com. command.com always returns 0. See also: popen(), spawn(), _splitargs() ------------------------------------------------------------------------------ #include <io.h> [PC] long tell (int handle); tell() returns the current position of the file pointer of HANDLE. If there is an error, tell() returns -1. See also: lseek() ------------------------------------------------------------------------------ #include <stdio.h> [UNIX] char *tempnam (const char *dir, const char *prefix); Generate the name suitable for a temporary file without overwriting an existing file. tempnam() returns a pointer to a string allocated by malloc(). If the TMP environment variable is set and the directory specified by TMP exists, that directory is used. Otherwise, the DIR argument is used. If DIR is NULL or the directory specified by DIR does not exist, P_tmpdir as defined in stdio.h is used. If even this fails, NULL is returned. The name of the file will start with PREFIX. PREFIX must not be longer than 5 characters. See also: tmpnam() ------------------------------------------------------------------------------ #include <time.h> [ANSI] time_t time (time_t *ptr); Return the number of seconds elapsed since 00:00 GMT 1-Jan-1970. The system time is converted according to the local timezone. If PTR is not NULL, the result is also stored to the variable pointed to by PTR. See also: ftime(), gettimeofday() ------------------------------------------------------------------------------ #include <time.h> [UNIX] #include <sys/times.h> long times (struct tms *buffer); Return the current time in CLK_TCK fractions of a second since 00:00 GMT 1-Jan-1970. Also sets the tms_utime field of BUFFER to the number of seconds the process has been running. The other fields are set to 0. Restriction: The return value is unusable due to overflow. See also: clock(), time() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] FILE *tmpfile (void); Create and open a temporary file. The name of the file is created with tmpnam(). The file is opened in "w+b" mode. On success, a stream pointer is returned. On failure, NULL is returned. See also: _rmtmp(), tmpnam() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] char *tmpnam (char *string); Create a unique file name and store it to STRING. There must be L_tmpnam bytes at STRING. If STRING is NULL, a static buffer is used which will be overwritten by subsequent calls. The file name is a concatenation of P_tmpdir and a sequence of digits. On success, a pointer to the new name is returned. On failure, NULL is returned. See also: tempnam(), tmpfile(), mktemp() ------------------------------------------------------------------------------ #include <ctype.h> [ANSI] int tolower (int c); int toupper (int c); tolower() converts the character C to lower case, if it is in the range 'A' ... 'Z'. toupper() converts the character C to upper case, if it is in the range 'a' ... 'z'. See also: stricmp(), strlwr(), strupr(), _tolower(), _toupper() ------------------------------------------------------------------------------ #include <ctype.h> [UNIX] int _tolower (int c); int _toupper (int c); _tolower() converts the upper-case character C to lower case; C must be in the range 'A' through 'Z'. _toupper() converts the lower-case character C to upper case; C must be in the range 'a' through 'z'. See also: tolower(), toupper() ------------------------------------------------------------------------------ #include <math.h> double trunc (double x); Return as floating-point number X chopped to an integer by truncating the fractional digits (rounding toward 0). See also: ceil(), floor(), modf(), rint() ------------------------------------------------------------------------------ #include <io.h> [BSD] int truncate (char *name, long length); Truncate the file NAME to at most LENGTH bytes. If LENGTH is greater than the current length of the file, the length is not changed. If successful, 0 is returned. Otherwise, -1 is returned. See also: chsize(), ftruncate() ------------------------------------------------------------------------------ #include <time.h> [UNIX] void tzset (void); Set timezone according to the TZ environment variable. If you have a problem with a program interpreting TZ differently (for instance a program which supports day-light-saving time), set EMXTZ for emx programs. If EMXTZ is set, emx will use the value of EMXTZ instead of the value of TZ. The following global variables are set by tzset(): daylight, timezone, tzname. TZ has the following format: TZ1[offset][TZ2] Where TZ1 is the three-letter name of the local timezone, offset is the optional offset to GMT (hours; positive values are to the west of Greenwich) and TZ2 is the optional name of the day-light-saving timezone, which is currently ignored. Example: PST8PDT. If TZ is not set, GMT is used. ------------------------------------------------------------------------------ #include <stdlib.h> [SysV] long ulimit (int request, long newlimit); Set or get process limits. The following REQUEST codes are implemented: 1 Return the maximum file size. Always returns 1 << 21. 2 Set the maximum file size to NEWLIMIT. Ignored. Returns NEWLIMIT. 3 Return the greatest possible break value 4 Return the number of files that can be open simultaneously per process. Always returns 40. ------------------------------------------------------------------------------ #include <io.h> [UNIX] int umask (int pmode); Set the file-permission mask of the current process to PMODE. The previous file-permission mask is returned. Only the S_IWRITE bit is used. Restrictions: The current file-permission mask is inherited by emx programs spawned under DOS. Under OS/2, the file-permission mask is not yet inherited. When spawning a non-emx program (such as command.com, see system()) which spawns an emx program, that program won't inherit the file-permission mask. See also: fopen(), open() ------------------------------------------------------------------------------ #include <sys/utsname.h> [UNIX] int uname (struct utsname *name); Store information identifying the current system to the structure pointed to by NAME. This function returns 0 (always successful). ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int ungetc (int c, FILE *stream); Push back the character C onto STREAM and clear the end-of-file indicator. STREAM must be open for reading. The next read operation on STREAM starts with C. If C is EOF, nothing is done. Only one character can be pushed onto a stream. fflush(), fseek(), fsetpos() and rewind() undo ungetc(). After a successful ungetc(), the value of the file pointer is undefined until the character has been read. On success, the character C is returned. On failure, EOF is returned. See also: fgetc(), fflush() ------------------------------------------------------------------------------ #include <stdio.h> /* use this */ [UNIX] #include <io.h> /* or this */ int unlink (const char *name); Delete the file NAME. 0 is returned if successful, -1 if not. Under OS/2 and DOS, unlink() and remove() are equivalent. See also: remove(). ------------------------------------------------------------------------------ #include <sys/utime.h> [SysV] int utime (const char *name, const struct utimbuf *times); Set time stamp of file NAME to the access time and modification time given in TIMES. If TIMES is NULL, both the access time and the modification time are set to the current time. See also: stat(), utimes() ------------------------------------------------------------------------------ #include <sys/time.h> [BSD] int utimes (const char *name, const struct timeval *tvp); Set time stamp of file NAME to the access time given in TVP[0] and the modification time given in TVP[1]. If TVP is NULL, both the access time and the modification time are set to the current time. See also: stat(), utime() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_attrib (int a); Set the attributes (colors etc.) used by video library functions to A. You can make A by using the binary OR operator and the F_whatever, B_whatever, INTENSITY and BLINK constants. See also: v_init(), v_putc() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_backsp (int count); Backspace the cursor. The cursor is moved left by COUNT characters. If the cursor leaves the screen at the left edge, it is moved to the end of the previous line. The cursor cannot leave the screen at the top edge. See also: v_putc() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_clear (void); Clear the screen using the current attributes. See also: v_attrib(), v_clreol() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_clreol (void); Clear the line from the current cursor position to the end of the current line using the current attributes. See also: v_attrib(), v_clear() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_ctype (int start, int end); Set the cursor type. START is the first row of the cursor, END is the last row of the cursor. Both values are zero-based. Use v_hardware() to determine the size of the character box. See also: v_getctype(), v_hardware(), v_hidecursor() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_delline (int count); Delete COUNT lines at the current cursor position by moving up the lines below the current line. The current attributes are used for filling lines becoming empty at the bottom of the screen. See also: v_attrib(), v_insline(), v_scroll() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_dimen (int *width, int *height); Store the screen width (columns) to WIDTH, the screen height (lines) to HEIGHT. See also: _scrsize() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] int v_getattr (void); Return the current attributes. See also: v_attrib() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_getctype (int *start, int *end); Store the current cursor start and end rows to START and END. See also: v_ctype() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_getline (char *dst, int x, int y, int count); Copy COUNT character/attributes pairs from the screen at position (X,Y) to DST. 2*COUNT bytes are copied. The cursor is not moved. See also: v_putline() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_getxy (int *x, int *y); Store the current cursor position to X (column) and Y (line). See also: v_gotoxy() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_gotoxy (int x, int y); Move the cursor to line Y, column X. Both values are zero-based. Line 0 is the top line, column 0 is the left-most column. See also: v_getxy() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] int v_hardware (void); Return a value indicating the display adapter type. The following values are defined: V_MONOCHROME Monochrome display adapter V_COLOR_8 Color display adapter, the character box height is 8 scan lines V_COLOR_12 Color display adapter, the character box height is 12 scan lines See also: v_ctype() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_hidecursor (void); Turn off the cursor. Use v_ctype() to turn the cursor on. See also: v_ctype() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] int v_init (void); Initialize video library. You must call this function before calling any other video library function. The attributes are set to F_WHITE|B_BLACK. General information about the video library: The video library implements text-mode output to the screen. You have to link with libvideo (use the -lvideo option). Under DOS, emx option -acm is required, see `Using emx options'. See wm_init() for a higher-level interface. Example: /emx/test/video.c See also: v_attrib() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_insline (int count); Insert COUNT empty lines at the current cursor position by moving down the line at the current cursor position and all lines below that line. The current attributes are used for filling the empty lines. See also: v_attrib(), v_delline(), v_scroll() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] int v_printf (const char *fmt, ...); Formatted output to the screen at the current cursor position. The cursor is moved. See printf() for details on FMT. The number of output characters is returned. See also: v_attrib(), v_putc(), v_puts() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_putc (char c); Display character C on the screen at the current cursor position, using the current attributes. The cursor is moved. If the cursor leaves the screen at the right edge, it will be moved to the start of the next line. If C is '\n', the cursor is moved to the start of the next line. If the cursor leaves the screen at the bottom edge, the screen is scrolled up. See also: v_attrib(), v_puts(), v_scrollup() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_putline (const char *src, int x, int y, int count); Copy COUNT character/attributes pairs from SRC to the screen at position (X,Y). 2*COUNT bytes are copied. The cursor is not moved. See also: v_getline(), v_putmask(), v_putn() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_putm (const char *str, int len); Display LEN characters of STR at the current cursor position using the current attributes. The cursor is not moved. See also: v_putline(), v_putn(), v_puts() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_putmask (const char *src, const char *mask, int x, int y, int count); Copy COUNT character/attributes pairs from SRC to the screen. A character/attributes pair at SRC[2*i] and SRC[2*i+1], is copied only if MASK[i] is non-zero. The cursor is not moved. See also: v_putline() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_putn (char c, int count); Display character C at the current cursor position. COUNT is the number of times to display the character. The cursor is not moved. See also: v_attrib(), v_putc() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_puts (const char *str); Display string STR at the current cursor position using the current attributes. The '\n' character moves the cursor to the start of the next line. Scrolling is performed when the cursor leaves the screen at the bottom edge. See also: v_attrib(), v_putc(), v_putm() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_scroll (int tl_x, int tl_y, int br_x, int br_y, int count, int flag); Scroll a rectangle of the screen by COUNT lines. The top left character cell is at (TL_X,TL_Y), the bottom right character cell is at (BR_X,BR_Y). If FLAG is V_SCROLL_UP, the rectangle is scrolled up, if FLAG is V_SCROLL_DOWN, the rectangle is scrolled down. If FLAG is V_SCROLL_CLEAR, the rectangle is filled with blanks. Lines becoming empty are filled with blanks using the current attributes. See also: v_attrib(), v_scrollup() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] void v_scrollup (void); Scroll screen up by one line. The bottom line is filled with blanks, using the current attributes. See also: v_attrib(), v_putc() ------------------------------------------------------------------------------ #include <sys/video.h> [emx] int v_vprintf (const char *fmt, va_list arg_ptr); Formatted output to the screen. Instead of a list of arguments, this function takes a pointer to the list of arguments. See v_printf() for details. See also: v_printf(), va_arg() ------------------------------------------------------------------------------ #include <stdarg.h> [ANSI] type va_arg (va_list arg_ptr, type); void va_end (va_list arg_ptr); void va_start (va_list arg_ptr, type prev_arg); Access arguments of a function with variable number of arguments. You have to declare a variable of type va_list, for instance ARG_PTR. Use va_start (arg_ptr, prev_arg), where PREV_ARG is the argument preceding the variable arguments, to initialize ARG_PTR. Use va_arg (arg_ptr, type) to get the next argument, which is of type TYPE. Use va_end (arg_ptr) if you no longer need ARG_PTR. Restriction: PREV_ARG should not be of type `float' unless there's a prototype for the function, TYPE should not be `float'. Both problems are due to the fact that float is promoted to double. See also: vprintf() ------------------------------------------------------------------------------ #include <stdio.h> [ANSI] int vprintf (const char *format, va_list arg_ptr); int vfprintf (FILE *stream, const char *format, va_list arg_ptr); int vsprintf (char *buffer, const char *format, va_list arg_ptr); Formatted output to stdout, to the stream STREAM or to the string BUFFER, respectively. Instead of a list of arguments, these functions take a pointer to the list of arguments. See printf() for details. See also: printf(), va_arg() ------------------------------------------------------------------------------ #include <stdio.h> [emx] int vscanf (const char *format, va_list arg_ptr); int vfscanf (FILE *stream, const char *format, va_list arg_ptr); int vsscanf (const char *buffer, const char *format, va_list arg_ptr); Parse input from stdin, STREAM or BUFFER, respectively. Instead of a list of arguments, these functions take a pointer to the list of arguments. See scanf() for details. See also: scanf(), va_arg() ------------------------------------------------------------------------------ #include <process.h> /* use this */ [UNIX] #include <sys/wait.h> /* or this */ int wait (int *status); Wait until a child process terminates or if a child process which is being debugged gets a signal, for instance, SIGTRAP after a single step has been performed. If there are no child processes, wait() returns immediately, setting errno to ECHILD and returning -1. If STATUS is not NULL, the return code and the termination status are stored to the location pointed to by STATUS. The termination status is stored in the low-order byte, the return code is stored in the high-order byte. If the child process terminates normally, the low-order byte contains 0, the high-order byte contains the return code. If the child process has been stopped, the low-order byte contains 127, the high-order byte contains the signal number. This occurs only if the child process is being debugged. If the child process terminated due to a signal, the low-order byte contains the signal number, the high-order byte contains 0. See also the macros defined in sys/wait.h. [...] wait() returns the process ID of the child process. If an error occurs, wait() sets errno and returns -1. Example: int tc, pid; pid = wait (&tc); if (pid >= 0) { if ((tc & 0xff) == 0) printf ("Normal process termination, rc=%d\n", tc >> 8); else if ((tc & 0xff) == 127) printf ("Process stopped by signal %d\n", tc >> 8); else printf ("Process terminated by signal %d\n", tc & 0xff); } Restrictions: Under DOS wait() is currently implemented only for processes being debugged; see ptrace() and spawn(). Under OS/2, wait() works only for processes started with spawn() or exec(). It does not work for processes started with DosExecPgm or DosStartSession. If the processes found by wait() has been started as a session, only the return code is available, not the signal number. wait() is not interrupted by signals. See also: ptrace(), signal(), spawn(), waitpid() ------------------------------------------------------------------------------ #include <sys/hw.h> [*] [emx] void _wait0 (unsigned port, unsigned mask); void _wait1 (unsigned port, unsigned mask); void _wait01 (unsigned port, unsigned mask); void _wait10 (unsigned port, unsigned mask); The _wait0() and _wait1() functions wait for the bit indicated by MASK of the 8-bit hardware port PORT being 0 or 1, respectively. The _wait01() and _wait10() functions wait for a 0->1 or 1->0 transition, respectively, of the bit indicated by MASK of the 8-bit hardware port PORT. If there are multiple bits set in MASK, `0' means all bits cleared, `1' means at least one bit set. You have to call _portaccess() first to enable access to a range of ports. To make your program work under DOS, you have to use emx option -ai, see `Using emx options'. Under OS/2, your program requires emxio.dll in a directory listed in LIBPATH. When linking with LINK386 (-Zomf) or when using emxlibc.dll (-Zmt), you have to use libemxio (-lemxio). libemxio must not be used if the program should run under DOS. Note that these functions eat lots of CPU time. See also: _portaccess(), _inp8() ------------------------------------------------------------------------------ #include <sys/wait.h> [UNIX] int waitpid (int pid, int *status, int options); Wait until the child process PID terminates. If PID is -1, waitpid() waits for any child process, as does wait(). If there is no child process with process ID PID (or if PID is -1 and there is no child process), errno is set to ESRCH and -1 is returned. If STATUS is not NULL, the return code and the termination status are stored to the location pointed to by STATUS, see wait() for details. OPTIONS is currently ignored. Restrictions: waitpid() is not implemented for negative values of PID. OPTIONS is ignored. waitpid() is not implemented under DOS. waitpid() cannot be used with ptrace() -- wait() must be used instead. See also: wait() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] void _wildcard (int *argcp, char ***argvp); Expand wildcards. If you want wildcards on the command line to be expanded, call _wildcard (&argc, &argv); at the beginning of main(). Wildcard arguments enclosed in double quotes won't be expanded. If the expansion of a wildcard argument is empty, the wildcard argument is kept unchanged. Directories are included in the expansion. Hidden and system files are omitted. _fnlwr() is used to convert file names to lower case on upper-case-only file systems. See also: _fnexplode(), main(), _response() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_attrib (wm_handle wh, int a); Set the default attributes of window WH to A. See also: wm_create(), wm_get_attrib(), wm_putc() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_attrib_all (wm_handle wh, int a); Change the attributes of all characters of window WH (except of the border) to A. The character codes are not changed. See also: wm_attrib(), wm_clear(), wm_create() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_backsp (wm_handle wh, int count); Backspace the cursor of window WH. The cursor is moved left by COUNT characters. If the cursor leaves the window at the left edge, it is moved to the end of the previous line. The cursor cannot leave the window at the top edge. See also: wm_putc() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_border (wm_handle wh, int bflag, int battr, const char *title, int tflag, int tattr); Change the border of window WH. The border type is set to BFLAG: 0 turns the border off, 1 uses a single line, 2 uses a double line, 3 and 4 use both single and double lines -- which is not recommended as most code pages do not contain the necessary symbols. All other values are used as characters for drawing the border. The attributes BATTR are used for drawing the border. TITLE is displayed centered in the top line of the border. If TFLAG is non-zero, vertical bars are used to separate the title text from the border. The attributes TATTR are used for displaying the title text. See also: wm_create() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_bottom (wm_handle wh); Move window WH to the bottom of the window stack, that is, it will be moved below all other windows. See also: wm_top(), wm_up() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_chide (int flag); Set the cursor hide mode. If FLAG is non-zero, the cursor is hidden if the current cursor position is hidden by another window. If FLAG is zero, the cursor is visible even if the cursor position is hidden by another window. The initial value is non-zero. See also: wm_ctype(), wm_cursor() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_clear (wm_handle wh); Clear window WH by filling WH with blanks using the current attributes. See also: wm_attrib(), wm_attrib_all() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_close (wm_handle wh); Close the window WH. After closing the window, it still exists but is not visible. See also: wm_open() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_close_all (void); Close all the windows. wm_close_all() restores the original screen contents. See also: wm_close(), wm_open() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_clr_eol (wm_handle wh, int x, int y); Clear from position (X,Y) of window WH to the end of that line of that window by displaying blanks. The current attributes are used. See also: wm_clear() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] wm_handle wm_create (int x0, int y0, int x1, int y1, int border, int battr, int wattr); Create a window. The upper left character of the window interior is at (X0,Y0), the bottom right character of the window interior is at (X1,Y1). A window may be larger than the screen or partially or completely outside the screen. BORDER specifies the border type: 0 doesn't draw a border, 1 uses a single line, 2 uses a double line, 3 and 4 use both single and double lines -- which is not recommended as most code pages do not contain the necessary symbols. All other values are used as characters for drawing the border. The attributes BATTR are used for drawing the border. The attributes for displaying text in the window are set to WATTR. After creating a window, it is invisible. Use wm_open() to show the window. wm_create() returns the handle of the window if successful. Otherwise, NULL is returned. See also: wm_attrib(), wm_border(), wm_delete(), wm_open() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_ctype (wm_handle wh, int start, int end); Set the cursor type of window WH. START is the first row of the cursor, END is the last row of the cursor. Both values are zero-based. The cursor type set by wm_ctype() is used for displaying the cursor if it is connected to window WH. Use v_hardware() to determine the size of the character box. See also: v_hardware(), wm_chide(), wm_cursor() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_cursor (wm_handle wh); Connect the screen cursor with the cursor of window WH. The cursor is displayed at the cursor position of window WH, using the cursor type of window WH. If WH is NULL, the screen cursor is not connected to any window and is invisible. Initially, the screen cursor is not connected to any window. See also: wm_chide(), wm_ctype(), wm_cvis() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_cvis (wm_handle wh, int flag); Set the cursor status of window WH. If FLAG is non-zero, the cursor is enabled, if FLAG is zero, the cursor is disabled. See also: wm_chide(), wm_cursor() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_del_char (wm_handle wh, int x, int y, int count); Delete COUNT characters at position (X,Y) of window WH. Characters to the right of that position are moved left, the positions becoming vacant at the right edge of the window are filled with blanks using the current attributes. See also: wm_attrib(), wm_del_line(), wm_ins_char() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_del_line (wm_handle wh, int y, int count); Delete COUNT lines at line Y of window WH by moving up the lines below that line. The current attributes are used for filling lines becoming empty at the bottom of the window. See also: wm_attrib(), wm_del_char(), wm_ins_line(), wm_scroll() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_delete (wm_handle wh); Destroy the window WH. After calling wm_delete(), the window handle WH must no longer be used. The window is not closed. See also: wm_close(), wm_create() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_dimen (wm_handle wh, int *width, int *height); Store the width of the window WH (columns) to WIDTH, the height (lines) to HEIGHT. See also: wm_create() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_down (wm_handle wh); Move window WH down the window stack, that is, it will be covered by an additional window unless WH is already the bottom window. See also: wm_bottom(), wm_top(), wm_up() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_exit (void); Quit the window manager and release all memory allocated by the window manager. All window handles become invalid. The windows are not closed. See also: wm_close(), wm_delete() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] wm_handle wm_find (int x, int y); Find the window which is visible at position (X,Y) of the screen. The window handle is returned if such a window exists. Otherwise, NULL is returned. ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] int wm_get_attrib (wm_handle wh); Return the current attributes of window WH. See also: wm_attrib() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] wm_handle wm_get_cursor (void); Get the window to which the screen cursor is connected. The window handle is returned. If the cursor is not connected to any window, NULL is returned. See also: wm_cursor() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_get_pos (wm_handle wh, int *x, int *y); Store the screen coordinates of the upper left character of the interior of window WH to X and Y. See also: wm_create(), wm_move() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_getxy (wm_handle wh, int *x, int *y); int wm_getx (wm_handle wh); int wm_gety (wm_handle wh); wm_getxy() stores the cursor coordinates of window WH to X and Y. wm_getx() returns the horizontal position (column) of the cursor of window WH. wm_gety() returns the vertical position (line) of the cursor of window WH. The coordinates are zero-based and are relative to the upper left character of the interior of window WH. See also: wm_gotoxy() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_gotoxy (wm_handle wh, int x, int y); Move the cursor of window WH to (X,Y). The coordinates are zero-based and are relative to the upper left character of the interior of window WH. If the screen cursor is connected to the cursor of window WH, the screen cursor is moved. See also: wm_cursor(), wm_getxy() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_ins_char (wm_handle wh, int x, int y, int count); Insert COUNT blank characters at position (X,Y) of window WH. Characters to the right of that position are moved right. The current attributes are used for displaying the blank characters. See also: wm_attrib(), wm_del_char(), wm_ins_line() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_ins_line (wm_handle wh, int y, int count); Insert COUNT empty lines at line Y of window WH by moving down that line and all lines below that line. The current attributes are used for filling the empty lines. See also: wm_attrib(), wm_del_line(), wm_scroll() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] int wm_init (int n); Initialize the window manager and allocate memory for N windows. You must call this function before calling any other window manager function. General information about window manager functions: The window manager functions implement text-mode output to windows on the screen. You have to link with libvideo (use the -lvideo option). Under DOS, emx option -acm is required, see `Using emx options'. Example: /emx/test/wm_demo.c, /emx/test/wm_hello.c See also: wm_exit() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_move (wm_handle wh, int x, int y); Move the window WH. The upper left character of the interior of the window will be at screen coordinates (X,Y). See also: wm_get_pos() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_open (wm_handle wh); Open the window WH. The window will be showed on the screen unless it is covered by other windows or outside the screen. See also: wm_close() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] int wm_printf (wm_handle wh, const char *fmt, ...); Formatted output to window WH at the current cursor position of that window. The cursor is moved. See printf() for details on FMT. The number of output characters is returned. See also: wm_attrib(), wm_putc(), wm_puts() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_puta_at (wm_handle wh, int x, int y, int a, int count); Change to A the attributes of COUNT characters at position (X,Y) of window WH. All COUNT characters must be in one line of the window. See also: wm_attrib(), wm_putsa_at() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putc (wm_handle wh, char c); Display character C in window WH at the current cursor position of that window, using the current attributes of that window. The cursor of that window is moved. If the cursor leaves the window at the right edge, it will be moved to the start of the next line. If C is '\n', the cursor is moved to the start of the next line. If the cursor leaves the window at the bottom edge, the window is scrolled up. See also: wm_attrib(), wm_putc_at(), wm_putca(), wm_scroll(), wm_wrap() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putc_at (wm_handle wh, int x, int y, char c); Display character C at position (X,Y) of window WH using the current attributes of that window. The cursor is not moved. See also: wm_attrib(), wm_gotoxy() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putca (wm_handle wh, char c, int a); Display character C in window WH at the current cursor position of that window, using the attributes A. The cursor of that window is moved. If the cursor leaves the window at the right edge, it will be moved to the start of the next line. If C is '\n', the cursor is moved to the start of the next line. If the cursor leaves the window at the bottom edge, the window is scrolled up. See also: wm_putc(), wm_putca_at(), wm_scroll(), wm_wrap() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putca_at (wm_handle wh, int x, int y, char c, int a); Display character C at position (X,Y) of window WH using the attributes A. The cursor is not moved. ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_puts (wm_handle wh, const char *str); Display string STR in window WH at the current cursor position of that window using the current attributes of that window. The '\n' character moves the cursor to the start of the next line. Scrolling is performed when the cursor leaves the window at the bottom edge. See also: wm_attrib(), wm_putc(), wm_putsa(), wm_scroll(), wm_wrap() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_puts_at (wm_handle wh, int x, int y, const char *str); Display string STR in window WH at position (X,Y) using the current attributes of that window. The '\n' character is not interpreted, the cursor is not moved. See also: wm_attrib(), wm_puts() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putsa (wm_handle wh, const char *str, int a); Display string STR in window WH at the current cursor position of that window using the attributes A. The '\n' character moves the cursor to the start of the next line. Scrolling is performed when the cursor leaves the window at the bottom edge. See also: wm_putca(), wm_puts(), wm_scroll(), wm_wrap() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_putsa_at (wm_handle wh, int x, int y, const char *str, int a); Display string STR in window WH at position (X,Y) using the attributes A. The '\n' character is not interpreted, the cursor is not moved. See also: wm_putsa() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_scroll (wm_handle wh, int count); Scroll the interior of window WH up by one line. The bottom line is filled with blanks, using the current attributes. See also: wm_attrib(), wm_del_line(), wm_ins_line(), wm_putc() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_top (wm_handle wh); Move window WH to the top of the window stack, that is, it will cover all other windows. See also: wm_bottom(), wm_down() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_up (wm_handle wh); Move window WH up the window stack, that is, it will cover an additional window unless WH is already the top window. See also: wm_bottom(), wm_down(), wm_top() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_update (wm_handle wh, int flag); Set the update mode of window WH. If FLAG is non-zero (which is the default), the screen is updated immediately if window WH is changed. If FLAG is zero, changes to window WH are done in memory only. This can be done to improve speed. Each call to update() copies the window to the screen, regardless of the FLAG argument. ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] int wm_vprintf (wm_handle wh, const char *fmt, va_list arg_ptr); Formatted output to window WH. Instead of a list of arguments, this function takes a pointer to the list of arguments. See wm_printf() for details. See also: wm_printf(), va_arg() ------------------------------------------------------------------------------ #include <sys/winmgr.h> [emx] void wm_wrap (wm_handle wh, int wrap_flag); Set the end-of-line wrap mode of window WH. If FLAG is non-zero (which is the default), the cursor is moved to the next line if it reaches the end of a line. If FLAG is zero, the cursor stays at the end of the line. wm_wrap() applies to wm_putc(), wm_puts(), wm_printf(), etc. See also: wm_putc() ------------------------------------------------------------------------------ #include <io.h> [UNIX] int write (int handle, const void *buf, size_t nbyte); Write NBYTE characters from the buffer BUF to the file HANDLE. The number of characters written is returned. If there is an error, -1 is returned. Writing 0 characters is allowed -- the request will be ignored. In text mode, LF characters are translated to CR/LF pairs. This translation does not affect the return value. See also: open(), setmode(), read() ------------------------------------------------------------------------------ 5.4 Library reference: variables -------------------------------- The variables are listed almost alphabetically. ------------------------------------------------------------------------------ #include <time.h> int daylight; Not implemented, always zero. See also: timezone, tzname, tzset() ------------------------------------------------------------------------------ #include <stdlib.h> [emx] const unsigned int _emx_env; This variable contains bits describing the environment your program is running in: 0x0001 Running under VCPI 0x0002 Running under XMS 0x0004 VDISK 3.3 detected 0x0008 Running under DESQview 0x0010 287 coprocessor present 0x0020 387 coprocessor present 0x0200 Running under OS/2 2.0 0x0400 File names are truncated (-t option) 0x0800 Data and stack executable (-ac option under DOS) You should check the 0x0200 bit before calling an OS/2 API function. You should check the 0x0400 bit when comparing file names. See also: _osmode ------------------------------------------------------------------------------ #include <stdlib.h> [emx] const unsigned int _emx_vcmp; This variable contains the emx version number, suitable for comparing. Example: if (_emx_vcmp > 0x302e3861) /* > 0.8a */ See also: _emx_vprt ------------------------------------------------------------------------------ #include <stdlib.h> [emx] const char _emx_vprt[5]; This variable contains the emx version number, suitable for printing. Example: printf ("emx version: %s\n", _emx_vprt); See also: _emx_vcmp ------------------------------------------------------------------------------ #include <stdlib.h> char **environ; A pointer to the current environment of the process. After changing the environment with putenv(), you should use this variable instead of the ENVP parameter of main(). See also: main(), putenv() ------------------------------------------------------------------------------ #include <stdlib.h> /* use this */ [ANSI] #include <errno.h> /* or this */ int errno; When a library function call fails, errno is usually set to a value indicating the type of error. On success, errno is not changed. The following errno values are supported: EPERM 1 Operation not permitted ENOENT 2 No such file or directory ESRCH 3 No such process EINTR 4 Interrupted system call EIO 5 I/O error E2BIG 7 Arguments or environment too big ENOEXEC 8 Invalid executable file format EBADF 9 Bad file number ECHILD 10 No child processes EAGAIN 11 No more processes ENOMEM 12 Not enough memory EACCES 13 Permission denied EEXIST 17 File exists EXDEV 18 Cross-device link ENOTDIR 20 Not a directory EISDIR 21 Is a directory EINVAL 22 Invalid argument EMFILE 24 Too many open files ENOSPC 28 Disk full ESPIPE 29 Illegal seek EROFS 30 Read-only file system EPIPE 32 Broken pipe EDOM 33 Domain error ERANGE 34 Result too large EMSDOS 37 Not supported under MS-DOS ENAMETOOLONG 38 File name too long When creating a multi-threaded program (-Zmt), errno is not a global variable; it's an lvalue that depends on the thread number. Threads started with _beginthread() have independent errno values. Threads started with DosCreateThread must not use errno or library functions which use errno. See also: _beginthread(), perror(), strerror(), sys_errlist ------------------------------------------------------------------------------ #include <graph.h> [emx] int g_xsize; int g_ysize; int g_colors; These variables describe the graphics mode selected by g_mode() or g_modeset(). g_xsize is the horizontal resolution (width), g_ysize is the vertical resolution (height), g_colors is the number of distinct colors that can be displayed at a time. See also: g_mode(), g_modeset() ------------------------------------------------------------------------------ #include <stdlib.h> [PC] const unsigned char _osminor; const unsigned char _osmajor; These variables contain the minor and major version numbers of the operating system. For DOS 3.30, _osmajor is 3 and _osminor is 30. For OS/2 2.0, _osmajor is 20, _osminor is 0. Example: printf ("OS version: %d.%d\n", _osmajor, _osminor); See also: _emx_env, _osmode ------------------------------------------------------------------------------ #include <stdlib.h> [PC] const unsigned char _osmode; This variable contains DOS_MODE if your program is running under DOS or OS2_MODE if your program is running under OS/2. See also: _emx_env ------------------------------------------------------------------------------ #include <stdlib.h> const char * const sys_errlist[]; const int sys_nerr; sys_errlist is an array of error messages indexed by errno values. sys_nerr is the number of elements in the sys_errlist array. See also: errno, perror(), strerror() ------------------------------------------------------------------------------ #include <time.h> long timezone; Seconds west of Greenwich. This variable is set by tzset(). See also: daylight, tzname, tzset() ------------------------------------------------------------------------------ #include <time.h> char *tzname[2]; The first pointer points to the name of the current timezone. The second pointer points to the day-light-saving timezone name (not implemented). This variable is set by tzset(). See also: daylight, timezone, tzset() ------------------------------------------------------------------------------ 5.5 termio ---------- #include <io.h> #include <sys/termio.h> #include <sys/kbdscan.h> /* optional, for extended scan codes */ int ioctl (int handle, int request, struct termio *buffer); Get or set parameters for the keyboard. The parameters are used only for read() and functions which call read(). HANDLE must be the stdin handle (0) and must be connected to the keyboard. REQUEST is TCGETA to get the parameters, TCSETA to set the parameters. TCSETAW waits for the output buffer to be empty, then sets the parameters (emx treats TCSETAW exactly like TCSETA). TCSETAF waits for the output buffer to be empty, then flushes the input buffer, then sets the parameters. BUFFER points to the following structure: struct termio { unsigned int c_iflag; /* input modes */ unsigned int c_oflag; /* output modes */ unsigned int c_cflag; /* control modes */ unsigned int c_lflag; /* local modes */ unsigned int c_line; /* unused */ unsigned char c_cc[NCC]; /* control characters etc. */ }; If c_lflag includes IDEFAULT, the default operating system input method is used (including command line editing). Input is always done line by line. All other fields of the termio structure are ignored. If c_lflag does not include IDEFAULT, UNIX-like input processing is performed; the following bits of c_iflag are used by emx in the following sequence: IDELETE Backspace key generates DEL character (emx extension) ISTRIP Clear bit 7 of all input characters INLCR Translate linefeed into carriage return IGNCR Ignore carriage return ICRNL Translate carriage return into linefeed IUCLC Convert upper case letters (A-Z) into lower case (a-z) If IDELETE is set, the two meanings of the backspace key (the one above the Return key) are swapped: Backspace generates DEL and Ctrl-Backspace generates Ctrl-H. If IDELETE is not set, Backspace generates Ctrl-H and Ctrl-Backspace generates DEL. The IDELETE bit applies only to the backspace key and does not affect other methods of entering Ctrl-H or DEL. All bits of c_oflag and c_cflag are ignored. The following bits of c_lflag are used by emx: IDEFAULT Enable termio (emx extension) ISIG Enable signal processing (see VINTR and VQUIT) ICANON Read input line by line, enable line editing ECHO Echo input ECHOK Echo CR/LF after VKILL The c_cc array contains control characters. If an element of c_cc is set to zero, no character will trigger the action associated with that element. VINTR Raise SIGINT if ISIG is set in c_iflag VQUIT Raise SIGQUIT if ISIG is set in c_iflag The following characters are used if ICANON is set: VERASE Delete one character to the left (default: Ctrl-H) VKILL Deletes the entire input line (default: Ctrl-U) VEOF Indicates EOF (default: Ctrl-D) VEOL Indicates end of line (default: none) The VERASE, VKILL and VEOF characters can be escaped by preceding them with a backslash. EOF at the beginning of a line is usually interpreted as end of input. The following elements are used if ICANON is not set: VMIN Minimum number of characters to be read (default: 6) VTIME Time-Out in 0.1 seconds (default: 1) Note that VMIN and VTIME are not equal to VEOF and VEOL, respectively. Unix uses the VEOF field for both VEOF and VMIN, the VEOL field for both VEOL and VTIME. emx uses separate fields for the four values. There are four cases for VMIN and VTIME (that is, BUFFER->c_cc[VMIN] and BUFFER->c_cc[VTIME]): VMIN = 0, VTIME = 0 Return all the characters stored in the input buffer. If there are no characters in the buffer, read() returns immediately. read() doesn't wait for input. VMIN = 0, VTIME > 0 Return after at least one character has been received or after waiting for VTIME * 0.1 seconds, whichever happens first. In the latter case, read() will return 0. VMIN > 0, VTIME = 0 Return after at least VMIN characters have been received. VMIN > 0, VTIME > 0 Return after at least VMIN characters have been received or if no characters have been received for VMIN * 0.1 seconds after receipt of a character (the time-out applies after at least one character has been received and is reset after each character). In all cases, read() will return as many characters as are available in the input buffer, up to the number of characters requested in the read() call. If O_NDELAY has been set for HANDLE with fcntl(), read() will always immediately return. If there is not enough data available with respect to VMIN, read() will immediately return -1 and set errno to EAGAIN. If IDEFAULT is not set, the text/binary mode of the handle is ignored: the conversions are set by ioctl() including CR-to-LF conversion and EOF character. If ICANON is not set, function keys are returned as two characters. The first one is a null ('\0') character, the second one is the scan code. See /emx/include/sys/kbdscan.h for scan codes. When using the system call library libsys.lib (-Zsys), termio is not supported. 5.6 System calls ---------------- [To be written.] All system calls are declared in sys/emx.h. Interface routines are in the libemx1.a and libemx1.lib libraries. System call emulation routines are in the libsys.lib library. Please do not use system calls from application programs -- always use C library functions. If you need a system call, put a function into the library which issues the system call. Do not use INT 21H: the function numbers and the parameter passing conventions are subject to change. Similarities to DOS function numbers are just coincidence and will probably disappear. Moreover, INT 21H cannot be used under OS/2. The goal is to have Unix-like system calls. 6 Hints for porting Unix programs to emx ======================================== - If you want Unix-like wildcard expansion built into the program, use int main (int argc, char *argv[]) { _wildcard (&argc, &argv); /* ... the program ... */ } This should be done at the very beginning of main(), before argc and argv are used. - Change all open(), fopen(), fdopen() and freopen() calls to use O_BINARY or "b", respectively, for binary files. If a file contains both binary and textual data, read the file in binary mode and do the conversion yourself. This is also required if fseek() is used on the file (see GDB), due to library restrictions. - Replace fork() and exec() with spawn(). - Replace exec() with spawn() and exit() if the parent process waits for the termination of the new process (wait(), SIGCLD). - Programs reading a.out files should be changed to call _seek_hdr() or _fseek_hdr() before reading the header to support .exe files. More changes are usually required. - Watch out for Unix file system hacks: Unix allows deleting and renaming an open file (the file will be deleted after being closed). - Watch out for Unix file names (Unix is case sensitive, long file names and multiple dots are allowed). - The null device is called /dev/null under Unix. Use nul, /dev/nul or \dev\nul instead. - Programs using stdin, stdout or stderr for binary data should call _fsetmode(). - If you want to use \ for separating directories, changes may be necessary. These changes are optional because / also works. - Implement support for drive names. This can be done by using #define getcwd _getcwd2 #define chdir _chdir2 In addition, some changes will be necessary. For instance, you have to change code which checks whether a file name is an absolute path name. _fullpath() and _abspath() can also be useful. - Note that ///abc is a valid Unix file name. It's equivalent to /abc. - Use `termio' or read the keyboard with _read_kbd() if you don't want to get input line by line. - Under Unix, directories in environment variables (PATH, for instance) are separated by colons; use semicolons instead. - Do not use ptrace(PTRACE_TRACEME): use P_DEBUG instead when starting the process with spawn(). - Signal handling is different: SIG_ACK should be used instead of the signal handler address to re-enable a signal when the signal handler has been called. - The shell isn't called /bin/sh. Use system(). system() doesn't expand wildcards. - Outputting single characters is inefficient. A solution is to use setvbuf (stdout, NULL, _IOLBF, BUFSIZ) and to use fflush (stdout) 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). GDB output has been made much faster by using line buffering. - Note that VEOF != VMIN and VEOL != VTIME. Programs which use VEOF and VEOL to access VMIN and VTIME, respectively, should be changed to use VMIN and VTIME. emx uses separate fields for VEOF, VEOL, VMIN and VTIME. - To use `termio', you have to reset the IDEFAULT bit of c_lflag. 7 Creating OS/2 programs ======================== 7.1 Calling OS/2 API functions ------------------------------ Use #include <os2.h> in your C files to call OS/2 API functions. GCC automatically links your program with libos2.a (or libos2.lib) by passing the -los2 option to the linker. If you call the linker manually, you have to tell the linker to link with libos2. Note that your program will crash if it calls an OS/2 API function when run under DOS. You can use either the header file that comes with emx (os2emx.h) or the header files that come with the Developer's Toolkit for OS/2 2.0 (an IBM product). By default, os2emx.h is used when #including os2.h. To use the header files of the Developer's Toolkit for OS/2 2.0, edit /emx/include/os2.h to #include os2tk.h instead of os2emx.h, and add the toolkit include file directory to the C_INCLUDE_PATH, CPLUS_INCLUDE_PATH and OBJC_INCLUDE_PATH environment variables. Note that you should define INCL_WHATEVER constants when using os2emx.h as you would with the IBM Developer's Toolkit for OS/2 2.0 -- though not all constants are tested by the current version of os2emx.h. os2emx.h contains definitions of the following OS/2 API functions: Device I/O ---------- DosDevConfig DosPhysicalDisk DosDevIOCtl Dynamic linking --------------- DosFreeModule DosQueryModuleName DosLoadModule DosQueryProcAddr DosQueryModuleHandle DosQueryProcType Errors ------ DosErrClass DosError Exceptions ---------- DosAcknowledgeSignalException DosSetExceptionHandler DosEnterMustComplete DosSetSignalExceptionFocus DosExitMustComplete DosUnsetExceptionHandler DosRaiseException DosUnwindException DosSendSignalException File system ----------- DosCancelLockRequest DosQueryFSAttach DosClose DosQueryFSInfo DosCopy DosQueryHType DosCreateDir DosQueryPathInfo DosCreatePipe DosQueryVerify DosDelete DosRead DosDeleteDir DosSetCurrentDir DosDupHandle DosSetDefaultDisk DosEditName DosSetFHState DosEnumAttribute DosSetFileInfo DosFindClose DosSetFileLocks DosFindFirst DosSetFilePtr DosFindNext DosSetFileSize DosForceDelete DosSetFSInfo DosFSAttach DosSetMaxFH DosFSCtl DosSetPathInfo DosMove DosSetRelMaxFH DosOpen DosSetVerify DosQueryCurrentDir DosShutdown DosQueryCurrentDisk DosResetBuffer DosQueryFHState DosWrite DosQueryFileInfo Help Manager ------------ DdfBeginList DdfSetFontStyle DdfBitmap DdfSetFormat DdfEndList DdfSetTextAlign DdfHyperText DdfText DdfInform WinAssociateHelpInstance DdfInitialize WinCreateHelpInstance DdfListItem WinCreateHelpTable DdfMetafile WinDestroyHelpInstance DdfPara WinLoadHelpTable DdfSetColor WinQueryHelpInstance DdfSetFont Memory management ----------------- DosAllocMem DosQueryMem DosAllocSharedMem DosSetMem DosFreeMem DosSubAllocMem DosGetNamedSharedMem DosSubFreeMem DosGetSharedMem DosSubSetMem DosGiveSharedMem DosSubUnsetMem Messages -------- DosGetMessage DosPutMessage DosInsertMessage DosQueryMessageCP Miscellanea ----------- DosQuerySysInfo DosSearchPath DosScanEnv Named pipes ----------- DosCallNPipe DosQueryNPipeInfo DosConnectNPipe DosQueryNPipeSemState DosCreateNPipe DosSetNPHState DosDisConnectNPipe DosSetNPipeSem DosPeekNPipe DosTransactNPipe DosQueryNPHState DosWaitNPipe National language support ------------------------- DosMapCase DosQueryCtryInfo DosQueryCollate DosQueryDBCSEnv DosQueryCp DosSetProcessCp Queues ------ DosCloseQueue DosPurgeQueue DosCreateQueue DosQueryQueue DosOpenQueue DosReadQueue DosPeekQueue DosWriteQueue Resources --------- DosFreeResource DosQueryResourceSize DosGetResource Semaphores ---------- DosAddMuxWaitSem DosOpenMuxWaitSem DosCloseEventSem DosPostEventSem DosCloseMutexSem DosQueryEventSem DosCloseMuxWaitSem DosQueryMutexSem DosCreateEventSem DosQueryMuxWaitSem DosCreateMutexSem DosReleaseMutexSem DosCreateMuxWaitSem DosRequestMutexSem DosDeleteMuxWaitSem DosResetEventSem DosOpenEventSem DosWaitEventSem DosOpenMutexSem DosWaitMuxWaitSem Sessions -------- DosQueryAppType DosStartSession DosSelectSession DosStopSession DosSetSession Tasking ------- DosBeep DosKillProcess DosCreateThread DosKillThread DosDebug DosResumeThread DosEnterCritSect DosSetPriority DosExecPgm DosSleep DosExit DosSuspendThread DosExitCritSect DosWaitChild DosExitList DosWaitThread DosGetInfoBlocks Timers ------ DosAsyncTimer DosStopTimer DosGetDateTime DosTmrQueryFreq DosStartTimer DosTmrQueryTime Virtual DOS machines -------------------- DosCloseVDD DosRequestVDD DosOpenVDD DosSetDOSProperty DosQueryDOSProperty Graphics Programming Interface ------------------------------ GpiAnimatePalette GpiQueryFaceString GpiAssociate GpiQueryFontAction GpiBeginArea GpiQueryFontFileDescriptions GpiBeginElement GpiQueryFontMetrics GpiBeginPath GpiQueryFonts GpiBitBlt GpiQueryFullFontFileDescs GpiBox GpiQueryGraphicsField GpiCallSegmentMatrix GpiQueryInitialSegmentAttrs GpiCharString GpiQueryKerningPairs GpiCharStringAt GpiQueryLineEnd GpiCharStringPos GpiQueryLineJoin GpiCharStringPosAt GpiQueryLineType GpiCloseFigure GpiQueryLineWidth GpiCloseSegment GpiQueryLineWidthGeom GpiCombineRegion GpiQueryLogColorTable GpiComment GpiQueryLogicalFont GpiConvert GpiQueryMarker GpiConvertWithMatrix GpiQueryMarkerBox GpiCopyMetaFile GpiQueryMarkerSet GpiCorrelateChain GpiQueryMetaFileBits GpiCorrelateFrom GpiQueryMetaFileLength GpiCorrelateSegment GpiQueryMix GpiCreateBitmap GpiQueryModelTransformMatrix GpiCreateLogColorTable GpiQueryNearestColor GpiCreateLogFont GpiQueryNumberSetIds GpiCreatePalette GpiQueryPS GpiCreateRegion GpiQueryPageViewport GpiCreatePS GpiQueryPalette GpiDeleteBitmap GpiQueryPaletteInfo GpiDeleteElement GpiQueryPattern GpiDeleteElementrange GpiQueryPatternRefPoint GpiDeleteElementsBetweenLabels GpiQueryPatternSet GpiDeleteMetaFile GpiQueryPel GpiDeletePalette GpiQueryPickAperturePosition GpiDeleteSegment GpiQueryPickApertureSize GpiDeleteSegments GpiQueryRealColors GpiDeleteSetId GpiQueryRegionBox GpiDestroyPS GpiQueryRegionRects GpiDestroyRegion GpiQueryRGBColor GpiDrawBits GpiQuerySegmentAttrs GpiDrawChain GpiQuerySegmentNames GpiDrawDynamics GpiQuerySegmentPriority GpiDrawFrom GpiQuerySegmentTransformMatrix GpiDrawSegment GpiQuerySetIds GpiElement GpiQueryStopDraw GpiEndArea GpiQueryTag GpiEndElement GpiQueryTextAlignment GpiEndPath GpiQueryTextBox GpiEqualRegion GpiQueryViewingLimits GpiErase GpiQueryViewingTransformMatrix GpiErrorSegmentData GpiQueryWidthTable GpiExcludeClipRectangle GpiRectInRegion GpiFillPath GpiRectVisible GpiFloodFill GpiRemoveDynamics GpiFrameRegion GpiResetBoundaryData GpiFullArc GpiResetPS GpiGetData GpiRestorePS GpiImage GpiRotate GpiIntersectClipRectangle GpiSaveMetaFile GpiLabel GpiSavePS GpiLine GpiScale GpiLoadBitmap GpiSelectPalette GpiLoadFonts GpiSetArcParams GpiLoadMetaFile GpiSetAttrMode GpiLoadPublicFonts GpiSetAttrs GpiMarker GpiSetBackColor GpiModifyPath GpiSetBackMix GpiMove GpiSetBitmap GpiOffsetClipRegion GpiSetBitmapBits GpiOffsetElementPointer GpiSetBitmapDimension GpiOffsetRegion GpiSetBitmapId GpiOpenSegment GpiSetCharAngle GpiOutlinePath GpiSetCharBox GpiPaintRegion GpiSetCharBreakExtra GpiPartialArc GpiSetCharDirection GpiPathToRegion GpiSetCharExtra GpiPlayMetaFile GpiSetCharMode GpiPointArc GpiSetCharSet GpiPolyFillet GpiSetCharShear GpiPolyFilletSharp GpiSetClipPath GpiPolygons GpiSetClipRegion GpiPolyLine GpiSetColor GpiPolyLineDisjoint GpiSetCp GpiPolyMarker GpiSetCurrentPosition GpiPolySpline GpiSetDefArcParams GpiPop GpiSetDefAttrs GpiPtInRegion GpiSetDefaultViewMatrix GpiPtVisible GpiSetDefTag GpiPutData GpiSetDefViewingLimits GpiQueryArcParams GpiSetDrawControl GpiQueryAttrMode GpiSetDrawingMode GpiQueryAttrs GpiSetEditMode GpiQueryBackColor GpiSetElementPointer GpiQueryBackMix GpiSetElementPointerAtLabel GpiQueryBitmapBits GpiSetGraphicsField GpiQueryBitmapDimension GpiSetInitialSegmentAttrs GpiQueryBitmapHandle GpiSetLineEnd GpiQueryBitmapInfoHeader GpiSetLineJoin GpiQueryBitmapParameters GpiSetLineType GpiQueryBoundaryData GpiSetLineWidth GpiQueryCharAngle GpiSetLineWidthGeom GpiQueryCharBox GpiSetMarker GpiQueryCharBreakExtra GpiSetMarkerBox GpiQueryCharDirection GpiSetMarkerSet GpiQueryCharExtra GpiSetMetaFileBits GpiQueryCharMode GpiSetMix GpiQueryCharSet GpiSetModelTransformMatrix GpiQueryCharShear GpiSetPageViewport GpiQueryCharStringPos GpiSetPaletteEntries GpiQueryCharStringPosAt GpiSetPattern GpiQueryClipBox GpiSetPatternRefPoint GpiQueryClipRegion GpiSetPatternSet GpiQueryColor GpiSetPel GpiQueryColorData GpiSetPickAperturePosition GpiQueryColorIndex GpiSetPickApertureSize GpiQueryCp GpiSetPS GpiQueryCurrentPosition GpiSetRegion GpiQueryDefArcParams GpiSetSegmentAttrs GpiQueryDefAttrs GpiSetSegmentPriority GpiQueryDefCharBox GpiSetSegmentTransformMatrix GpiQueryDefTag GpiSetStopDraw GpiQueryDefViewingLimits GpiSetTag GpiQueryDefaultViewMatrix GpiSetTextAlignment GpiQueryDevice GpiSetViewingLimits GpiQueryDeviceBitmapFormats GpiSetViewingTransformMatrix GpiQueryDrawControl GpiStrokePath GpiQueryDrawingMode GpiTranslate GpiQueryEditMode GpiUnloadFonts GpiQueryElement GpiUnloadPublicFonts GpiQueryElementPointer GpiWCBitBlt GpiQueryElementType Device Contexts --------------- DevCloseDC DevQueryCaps DevEscape DevQueryDeviceNames DevOpenDC DevQueryHardcopyCaps DevPostDeviceModes Presentation Manager -------------------- WinAddAtom WinQueryAtomName WinAlarm WinQueryAtomUsage WinBeginEnumWindows WinQueryCapture WinBeginPaint WinQueryClassInfo WinBroadcastMsg WinQueryClassName WinCalcFrameRect WinQueryClassThunkProc WinCallMsgFilter WinQueryClipbrdData WinCancelShutdown WinQueryClipbrdFmtInfo WinCloseClipbrd WinQueryClipbrdOwner WinCompareStrings WinQueryClipbrdViewer WinCopyAccelTable WinQueryCp WinCopyRect WinQueryCpList WinCpTranslateChar WinQueryCursorInfo WinCpTranslateString WinQueryDesktopBkgnd WinCreateAccelTable WinQueryDesktopWindow WinCreateAtomTable WinQueryDlgItemShort WinCreateCursor WinQueryDlgItemText WinCreateDlg WinQueryDlgItemTextLength WinCreateFrameControls WinQueryFocus WinCreateMenu WinQueryMsgPos WinCreateMsgQueue WinQueryMsgTime WinCreatePointer WinQueryObjectWindow WinCreatePointerIndirect WinQueryPointer WinCreateStdWindow WinQueryPointerInfo WinCreateWindow WinQueryPointerPos WinDdeInitiate WinQueryPresParam WinDdePostMsg WinQueryQueueInfo WinDdeRespond WinQueryQueueStatus WinDefWindowProc WinQuerySysColor WinDefDlgProc WinQuerySysModalWindow WinDeleteAtom WinQuerySysPointer WinDeleteLibrary WinQuerySystemAtomTable WinDeleteProcedure WinQuerySysValue WinDestroyAccelTable WinQueryUpdateRect WinDestroyAtomTable WinQueryUpdateRegion WinDestroyCursor WinQueryVersion WinDestroyMsgQueue WinQueryWindow WinDestroyPointer WinQueryWindowDC WinDestroyWindow WinQueryWindowModel WinDismissDlg WinQueryWindowPos WinDispatchMsg WinQueryWindowProcess WinDlgBox WinQueryWindowPtr WinDrawBitmap WinQueryWindowRect WinDrawBorder WinQueryWindowText WinDrawPointer WinQueryWindowTextLength WinDrawText WinQueryWindowThunkProc WinEmptyClipbrd WinQueryWindowULong WinEnablePhysInput WinQueryWindowUShort WinEnableWindow WinRealizePalette WinEnableWindowUpdate WinRegisterClass WinEndEnumWindows WinRegisterUserDatatype WinEndPaint WinRegisterUserMsg WinEnumClipbrdFmts WinReleaseHook WinEnumDlgItem WinReleasePS WinEqualRect WinRemovePresParam WinExcludeUpdateRegion WinRequestMutexSem WinFillRect WinSaveWindowPos WinFindAtom WinScrollWindow WinFlashWindow WinSendMsg WinFocusChange WinSendDlgItemMsg WinFreeErrorInfo WinSetAccelTable WinGetClipPS WinSetActiveWindow WinGetCurrentTime WinSetCapture WinGetDlgMsg WinSetClassMsgInterest WinGetErrorInfo WinSetClassThunkProc WinGetKeyState WinSetClipbrdData WinGetLastError WinSetClipbrdOwner WinGetMaxPosition WinSetClipbrdViewer WinGetMinPosition WinSetCp WinGetMsg WinSetDesktopBkgnd WinGetNextWindow WinSetDlgItemShort WinGetPkysKeyState WinSetDlgItemText WinGetPS WinSetFocus WinGetScreenPS WinSetHook WinGetSysBitmap WinSetKeyboardStateTable WinInflateRect WinSetMsgInterest WinInitialize WinSetMsgMode WinInSendMsg WinSetMultWindowPos WinIntersectRect WinSetOwner WinInvalidateRect WinSetParent WinInvalidateRegion WinSetPointer WinInvertRect WinSetPointerOwner WinIsChild WinSetPointerPos WinIsPhysInputEnabled WinSetPresParam WinIsRectEmpty WinSetRect WinIsThreadActive WinSetRectEmpty WinIsWindow WinSetSynchroMode WinIsWindowEnabled WinSetSysColors WinIsWindowShowing WinSetSysModalWindow WinIsWindowVisible WinSetSysValue WinLoadAccelTable WinSetWindowBits WinLoadDlg WinSetWindowPos WinLoadMenu WinSetWindowPtr WinLoadLibrary WinSetWindowText WinLoadMessage WinSetWindowThunkProc WinLoadPointer WinSetWindowULong WinLoadProcedure WinSetWindowUShort WinLoadString WinShowCursor WinLockVisRegions WinShowPointer WinLockWindowUpdate WinShowTrackRect WinMakePoints WinShowWindow WinMakeRect WinStartTimer WinMapDlgPoints WinStopTimer WinMapWindowPoints WinSubclassWindow WinMessageBox WinSubstituteStrings WinMultWindowsFromIDs WinSubtractRect WinNextChar WinTerminate WinOffsetRect WinTrackRect WinOpenClipBrd WinTranslateAccel WinOpenWindowDC WinUnionRect WinPeekMsg WinUpdateWindow WinPopupMenu WinUpper WinPostMsg WinUpperChar WinPostQueueMsg WinValidateRect WinPrevChar WinValidateRegion WinProcessDlg WinWaitEventSem WinPtInRect WinWaitMsg WinQueryAccelTable WinWaitMuxWaitSem WinQueryActiveWindow WinWindowFromDC WinQueryAnchorBlock WinWindowFromID WinQueryAtomLength WinWindowFromPoint Standard Dialogs ---------------- WinDefFileDlgProc WinFreeFileDlgList WinFileDlg Presentation Manager Shell -------------------------- WinAddSwitchEntry WinQueryTaskSizePos WinChangeSwitchEntry WinQueryTaskTitle WinCreateSwitchEntry WinRemoveSwitchEntry WinQuerySessionTitle WinSwitchToProgram WinQuerySwitchEntry WinStartApp WinQuerySwitchHandle WinTerminateApp WinQuerySwitchList Keyboard Subsystem ------------------ KbdCharIn KbdPeek KbdClose KbdRegister KbdDeRegister KbdSetCp KbdFlushBuffer KbdSetCustXt KbdFreeFocus KbdSetFgnd KbdGetCp KbdSetHWID KbdGetFocus KbdSetStatus KbdGetHWID KbdStringIn KbdGetStatus KbdSynch KbdOpen KbdXlate Video Subsystem --------------- VioCheckCharType VioSavRedrawWait VioDeRegister VioScrLock VioEndPopUp VioScrollDn VioGetAnsi VioScrollLf VioGetBuf VioScrollRt VioGetConfig VioScrollUp VioGetCp VioScrUnLock VioGetCurPos VioSetAnsi VioGetCurType VioSetCp VioGetFont VioSetCurPos VioGetMode VioSetCurType VioGetPhysBuf VioSetFont VioGlobalReg VioSetMode VioModeUndo VioShowBuf VioModeWait VioWrtCellStr VioPopUp VioWrtCharStr VioPrtSc VioWrtCharStrAttr VioPrtScToggle VioWrtNAttr VioReadCellStr VioWrtNCell VioReadCharStr VioWrtNChar VioRegister VioWrtTTY VioSavRedrawUndo Advanced Video -------------- VioAssociate VioQueryFonts VioCreateLogFont VioQuerySetIds VioCreatePS VioSetDeviceCellSize VioDeleteSetId VioSetOrg VioDestroyPS VioShowPS VioGetDeviceCellSize WinDefAVioWindowProc VioGetOrg Mouse Subsystem --------------- MouClose MouInitReal MouDeRegister MouOpen MouDrawPtr MouReadEventQue MouFlushQue MouRegister MouGetDevStatus MouRemovePtr MouGetEventMask MouSetDevStatus MouGetNumButtons MouSetEventMask MouGetNumMickeys MouSetPtrPos MouGetNumQueEl MouSetPtrShape MouGetPtrPos MouSetScaleFact MouGetPtrShape MouSetThreshold MouGetScaleFact MouSynch MouGetThreshold 7.2 Importing from OS/2 DLLs ---------------------------- All functions in the list above are defined in libos2.a and libos2.lib. To import functions not defined in libos2.a and libos2.lib, you have to create an import list file for these functions. See the emximp documentation for details. Please note that you cannot directly call 16-bit functions not listed above. See below for details. 7.3 Creating Presentation Manager applications using ld and emxbind ------------------------------------------------------------------- - #include <os2.h> - Link with libos2.a (done automatically when using GCC to link) - Use `rc -r' to compile the resource-definition file into a binary resource file (.res file) - Use `emxbind -ep' or a module definition file to set the application type - Use the -r option of emxbind to put the resources from the binary source file into the .exe file. If there's a .res file on the GCC or ld command line, it is automatically passed to emxbind Do not use rc to put the resources into the .exe file! Example: cd \emx\test rc -r pm1.rc gcc -o pm1 pm1.c emxbind -bp -rpm1.res /emx/bin/emxl pm1 Ditto, using a module definition file: cd \emx\test rc -r pm1.rc gcc -o pm1.exe pm1.c pm1.def pm1.res Example (compiling the `template' toolkit sample program): cd \toolkt20\c\samples\template copy ..\prodinfo.bmp rc -r main.rc gcc -s -o template.exe *.c template.def main.res 7.4 Creating Presentation Manager applications using emxomf and LINK386 ----------------------------------------------------------------------- - #include <os2.h> - Link with libos2.lib (done automatically when using GCC to link) - Use a module definition file which uses the WINDOWAPI keyword of the NAME statement - Use `rc -r' to compile the resource-definition file into a binary resource file (.res file) - Use `rc' or emxomfld to add the binary resource file to the .EXE file. Optionally, you can compile the resource-definition file and add it to the .EXE file using `rc' in one step. Using two steps is recommended in makefiles Example: cd \emx\test rc -r pm1.rc gcc -o pm1.exe pm1.c pm1.def pm1.res -Zomf Example (compiling the `template' toolkit sample program): cd \toolkt20\c\samples\template copy ..\prodinfo.bmp rc -r main.rc gcc -Zomf -o template.exe *.c template.def main.res If you want to use the -Zsys option, you should increase the stack size by editing the STACKSIZE statement in the .def file. Note that the command line arguments and the complete environment are copied to the stack! The stack size should be at least 32768. 7.5 Creating dynamic link libraries ----------------------------------- If you want to use C library functions (such as memory allocation and i/o functions) that need initialization, you have to write a library initialization function which initializes the library by calling _CRT_init(). See _DLL_InitTerm() for details. The default _DLL_InitTerm() function does nothing. Write a module definition file (.def file) that contains a LIBRARY statement and an EXPORTS statement. The EXPORTS statement has to list all functions to be exported by your DLL. The .def file should have the same name as the .dll file to be created. Compile and link your program using the -Zdll option of GCC. This option causes the dll0 startup to be used instead of crt0. Specify the name of the .def file on the GCC or ld command line, respectively. Linking with LINK386 is recommended for dynamic link libraries. Using ld and emxbind offers no advantages when creating dynamic link libraries. 7.5.1 Creating dynamic link libraries that use emxlibc.dll ---------------------------------------------------------- Dynamic link libraries that use emxlibc.dll are allowed to call all library functions, including stream I/O, as long as they're used together with programs and other dynamic link libraries that use emxlibc.dll. That is, all I/O done by C library functions must be done in a single place, emxlibc.dll. The relevant GCC command line options are -Zomf -Zmt. As the C library is initialized by the program using the DLL, your library initialization function must not call _CRT_init(). 7.5.2 Creating dynamic link libraries that don't use emxlibc.dll ---------------------------------------------------------------- When linking a dynamic link libraries statically with the C library, you have to keep in mind that the DLL and the program using the DLL don't share global variables such as errno, timezone, and -- very important -- the variables used for I/O. Therefore you should not call C I/O functions; use OS/2 API functions instead. Functions such as strcpy() that don't use global variables are safe to use. See /emx/test/dlltest1.c for an example. 7.6 Using the DLL version of the C library ------------------------------------------ To use emxlibc.dll, simply say -Zmt on the GCC command line. This links your program with libmt.a or libmt.lib, the import library for emxlibc.dll, instead of the static C library (libc, libgcc, libemx1). -Zmt can be used with methods (E1) and (E2). See the introduction for further information. Note that emxlibc.dll uses emx.dll. Thus, the restrictions of -Zsys do not apply. Do not redefine functions in your program which are contained in emxlibc.dll. Other functions in emxlibc.dll will continue to use the original versions in emxlibc.dll which will cause problems. If you have to replace library functions and want to use emxlibc.dll, create a new DLL (which must not be called emxlibc.dll), add your replacement functions and all the functions of emxlibc.dll except for the functions you're replacing. 7.7 Creating multi-threaded programs ------------------------------------ Multi-threaded programs have to use emxlibc.dll. Therefore you have to say -Zmt on the GCC command line. Use _beginthread() to start a new thread. Do not use DosCreateThread unless the new thread doesn't call C library functions. The C library functions in emxlibc.dll are not yet completely thread-safe: access to the stream I/O data should be serialized. The -Zmt option defines the __MT__ preprocessor macro. The C library header files check for __MT__ to use alternate definitions suitable for multi-threaded programs when -Zmt is used. Signal handling is currently implemented only for the main thread. A future version of emx will support per-thread signal handlers. Each thread has its own errno value. If you're very careful, you can write multi-threaded programs that don't use emxlibc.dll. Only the main thread is allowed to call library functions that have side effects, including functions that set errno. All other threads should use OS/2 API functions instead. 7.8 Calling 16-bit functions ---------------------------- Limited support for calling 16-bit functions has been introduced with emx 0.8f. You can call 16-bit OS/2 API functions and other 16-bit functions that use the pascal calling convention and are exported by a dynamic link library. As no changes have been made to GCC to support direct calls to 16-bit functions (this would require big changes to GCC), you have to call 16-bit functions by applying the following (awkward) macros and functions: _THUNK_FUNCTION(FUNCTION) This macro is used for declaring the 16-bit function. The function is declared as usual, using a prototype, but _THUNK_FUNCTION is applied to the function name. The 16-bit function must not be called directly. _THUNK_PROLOG(SIZE) This macro must be called first. SIZE is the number of bytes in the argument list of the 16-bit function. After _THUNK_PROLOG, the following macros are used to build the argument list. The macros are to be applied left-to-right, that is, the first argument is handled first. _THUNK_CHAR(ARG) Pass an 8-bit argument to the function. _THUNK_SHORT(ARG) Pass a 16-bit argument to the function. _THUNK_LONG(ARG) Pass a 32-bit argument to the function. _THUNK_FLAT(ARG) Pass a 32-bit (flat) pointer to the function. _THUNK_FAR16(ARG) Pass a 16:16-bit (far) pointer to the function. After building the argument list, the 16-bit function is called by invoking the following macro. _THUNK_CALL(FUNCTION) Call the 16-bit function FUNCTION. Do not apply _THUNK_FUNCTION to the function name. There should be no statements other than calls to the _THUNK macros between _THUNK_PROLOG and _THUNK_CALL. _THUNK_PROLOG starts an expression which is terminated by _THUNK_CALL. Therefore, the return value of the 16-bit function is returned by _THUNK_CALL and by the entire sequences of statements from _THUNK_PROLOG to _THUNK_CALL. The return value is the value returned by the 16-bit function in the DX and AX registers. If the function returns a 16-bit value, you have to typecast the return value to SHORT or USHORT to discard the upper 16 bits. See the description of _emx_16to32() and _emx_32to16() for converting 16-bit far pointers to 32-bit flat pointers and vice versa. This conversion is not done automatically. Example: #include <os2.h> /* define _THUNK macros */ /* Declare 16-bit function */ USHORT _THUNK_FUNCTION (Dos16Beep) (USHORT usFrequency, USHORT usDuration); void beep (int frequency, int duration) { _THUNK_PROLOG (2+2); _THUNK_SHORT (frequency); _THUNK_SHORT (duration); _THUNK_CALL (Dos16Beep); } See /emx/lib/os2/*.c for more examples. 8 Customizing ============= Default values are provided for the heap size, the stack size and the number of files that can be simultaneously open. The following sections describe how to increase the limits. 8.1 Increasing the heap size ---------------------------- The maximum size of the heap available for malloc() is fixed. The default for the combined size of the heap and stack is 8 MB under DOS. Use the -s# emx option (see `Using emx options') to increase the heap and stack size. The default heap size is 32 MB under OS/2. When using ld and emxbind, you can change the heap size with the -h# option of emxbind. When using emxomf and LINK386 without -Zsys, the heap size cannot be changed (currently). When using -Zsys, you have to build a new libsys.lib after changing /emx/lib/sys/init.c. The following line of that file defines the heap size: _sys_heap_size = 0x2000000; See build.doc on information about rebuilding libraries. 8.2 Increasing the stack size ----------------------------- The default for the combined size of the heap and stack is 8 MB under DOS. When using emxbind, the default stack size is 8 MB under OS/2. When using emxomf and LINK386, the default stack size is 8192 bytes under OS/2. This default stack size is too small. The stack size for DOS can be changed with the -s# emx option. emxbind can put this option into the executable file. The stack size for OS/2 can be changed with the -k# option of emxbind when using emxbind. When using LINK386, use the STACKSIZE statement in a module definition file. The stack size should be at least 32768 bytes. 8.3 Increasing the number of files ----------------------------------- Under DOS and when using emx.dll under OS/2, you can set the number of file handles supported by the emx runtime by setting the EMXOPT environment variable or by using emxbind to put emx options into the .exe file. The relevant option is -h#, see `Using emx options'. Note that you might have to change the FILES settings in the CONFIG.SYS file under DOS. The number of file handles and streams supported by the C library is given by the _NFILES constant in /emx/include/sys/emx.h. The default value is 40. After changing emx.h, you have to rebuild the libraries. (At least stdio.c and iodata.c in /emx/lib/io must be recompiled.) Note that at least three file handles (for stdin, stdout and stderr) are (almost) always predefined. When using the system call library (-Zsys, libsys.lib) you have to call DosSetMaxFH to increase the number of file handles. The number of file handles and streams supported by emxlibc.dll is 256. 9 Debugger (DOS) ================ emxd.exe contains a debugger, emx.exe doesn't. Use the -S option to enable the debugger. If you want to debug using a terminal, enter -S1 to use COM1, -S2 to use COM2. Command keys . display registers and next instruction : show CS:EIP and next instruction (toggle) <blank> 1 step 0 10 steps 1-9 1 to 9 steps C set breakpoint after next instruction and start program F display floating point (387) status N step without stopping F2 display registers and next instruction F5 start program without setting breakpoint F8 1 step F10 set breakpoint after next instruction and start program Commands: A address display info about address (virt/phys/external addresses) A range ditto, loop through range, adding 1000H B display breakpoints and watchpoints B address set breakpoint (default segment: CS) D continue last D command D address display hex dump: 16 lines (default segment: DS) D range display hex dump (default segment: DS) G start program G address set temporary breakpoint at given address (default segment: CS) and start program I display process table: process index, process id, parent process id, number of open files K display breakpoints and watchpoints K value delete breakpoint or watchpoint (by number) L value display info about selector L value value ditto, loop through range, adding 8 (not 4!) Q quit, return value 0 Q value quit with given return value R display registers and next instruction R reg value set register to value R condition set/reset processor flag S range list search memory U continue last U command U address unassemble (default segment: CS) V value display info about virtual address V value value ditto, loop through range, adding 1000H VP display info about pages that have physical memory assigned VP value display info by physical address VP value value ditto, loop through range, adding 1000H VX display info about pages that have an external address VX value display info by external address VX value value ditto, loop through range, adding 1000H W display breakpoints and watchpoints Wla address set watchpoint at given address (default segment: DS) l: B byte W word (address must be even) D dword (the 2 low bits of addr must = 0) a: R trap read & write accesses W trap write accesses X trap change X value Find symbol at address `value' or below Up to 3 breakpoints and watchpoints can be set. Address: [value:]value segment and offset symbol symbol (search symbol; if this fails, search _symbol) Condition: NC, CY, PE, PO, NA, AC, NZ, ZR, PL, NG, DI, EI, UP, DN, NV, OV Register: EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP, EFLAGS, AX, BX, CX, DX, SI, DI, BP, SP, IP, AL, AH, BL, BH, CL, CH, DL, DH, CS, DS, ES, FS, GS, SS Range: address address (same segments, second offset >= first offset, second selector should be omitted) List: value|'text' ... Value: Hexadecimal number, register name or character ('c') If the -S option is used, emx will display swapper statistics when returning to DOS. It displays Swapper statistics: F=f R=r W=w N=n S=s where f is the number of page faults, r is the number of swapper file reads, w is the number of swapper file writes, n is the number of times the swap space of present pages has been recycled, and s is the size of the swapper file. All numbers are decimal numbers. 10 Executable file format ========================= a.out see /emx/include/a_out.h exe OS/2 LX format with additional sections, see emxbind.doc 11 Known problems ================= - select(), sleep(), _sleep2() hold signals under DOS, that is, if the alarm() timer elapses, the signal handler for SIGALRM isn't called until the completion of those functions - when using the -C# emx option, memory allocated by an unsuccessful brk() or sbrk() call isn't freed. That is, as soon as a malloc() call fails, further calls will also fail. Actually, this isn't a bug -- it's a lacking feature - emx doesn't work under DOS if more than 16 MB of memory is installed - running emx programs by a DOS program started by an emx program seems not to work under certain circumstances - under circumstances not yet isolated, OS/2 crashes when running multiple emx applications. For instance, this happens when doing a parallel make with dmake. Under some versions of OS/2, only the emx applications freeze instead of OS/2. It has not been tested whether this problem still exists with emx 0.8f - breakpoints are shared by all instances of a program under OS/2 -- this is an OS/2 bug - _read_kbd() of the system call library (-Zsys) sometimes crashes the program (or even OS/2) if Ctrl-C or Ctrl-Break is pressed --------------------------- END OF EMXDEV.DOC ------------------------------