Category : OS/2 Files
Archive : EMXDEV8F.ZIP
Filename : EMXDEV.DOC
Output of file : EMXDEV.DOC contained in archive : EMXDEV8F.ZIP
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
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] [
[-r
emxbind [-b] [
[-r
-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[
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
-d[
read the module definition file
is `def'. If
extension is used instead. See below for details on module
definition files
-k
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
put resources from binary resource file
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
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
-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.
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
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
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
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
omitted, the
specify an extension for the input file to avoid overwriting the
input file!)
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
-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.
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 [
-q don't display title
path name of a bound .exe file to be read. The default extension
is `exe'
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 [
Usage (altering options):
emxbind -a [
-q don't display title
path name of a bound .exe file to be read or changed,
respectively. The default extension is `exe'
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 [
-q don't display title
path name of emxd.exe, emx.exe or emxl.exe. This DOS loader is
copied to the
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 [
-q don't display title
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
is given on the emxbind command line, the STUB statement is
ignored. If
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]
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
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
The name must end with `.imp'.
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
The name must end with `.imp'.
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
[-s]
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
emximp -o
name must end with `.a'.
must end with `.imp'.
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
The name must end with `.lib'.
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
The name must end with `.def'.
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
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
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#]
The default extension for
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
argument:
c Don't display warning when creating new library.
v Verbose output.
The following option must precede
-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
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
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
All the
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
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
#include
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
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
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
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
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
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
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
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
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
#include
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
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
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
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
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
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
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
void bzero (void *buffer, size_t n);
Set N bytes at BUFFER to 0.
See also: memset()
------------------------------------------------------------------------------
#include
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
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
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
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
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
#include
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
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
void clearerr (FILE *stream);
Clear the error and end-of-file indicators of STREAM.
See also: ferror(), feof()
------------------------------------------------------------------------------
#include
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
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
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
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
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
#include
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
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
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
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
double difftime (time_t t1, time_t t0);
Return the difference (in seconds) T1-T0 between T0 and T1.
------------------------------------------------------------------------------
#include
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
void _dt_free (struct _dt_tree *dt);
Deallocate the memory allocated by _dt_read() for the directory
tree DT.
See also: _dt_read()
------------------------------------------------------------------------------
#include
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
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
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
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
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
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
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
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
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
_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
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
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
_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
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
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
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
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
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
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
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
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
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
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
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
_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
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
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
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
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
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
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
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
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
/* 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
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
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
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
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
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
int fclose (FILE *stream);
Close the open stream STREAM. Return 0 if successful, EOF
otherwise.
See also: fcloseall(), fflush(), fopen()
------------------------------------------------------------------------------
#include
int fcloseall (void);
Close all open streams. Return the number streams closed or EOF
if an error occurs.
See also: fclose(), flushall(), fopen()
------------------------------------------------------------------------------
#include
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
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
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
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
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
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
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
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
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
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
int fileno (FILE *stream);
fileno() returns the file handle associated with STREAM.
See also: fdopen()
------------------------------------------------------------------------------
#include
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
#include
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
#include
#include
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
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
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
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