home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / emxtutor.zip / emxsrcd1.zip / emx / src / doc / emxlib.src < prev    next >
Text File  |  1998-12-21  |  661KB  |  22,708 lines
  1. ■c emxlib.src
  2.  
  3. ■text
  4. ===============================================================================
  5. emxlib.doc        emx 0.9d     C LIBRARY REFERENCE                  21-Dec-1998
  6. ===============================================================================
  7.                                      Copyright (c) 1990-1998 by Eberhard Mattes
  8. ■endtext
  9.  
  10. ■title emx 0.9d C Library Reference
  11.  
  12. ■format bold emx emxbind emxload ld
  13.  
  14. ■format tty .a .o .com .exe cmd.exe command.com
  15. ■format tty emx.dll emxlibc.dll emxlibcm.dll emxlibcs.dll
  16. ■format tty emxwrap.dll emxio.dll makefile emx.exe
  17. ■format tty sys.lib emx.a emx.lib emx2.a emx2.lib os2.a os2.lib
  18. ■format tty binmode.o binmode.obj
  19. ■format tty <a_out.h> <alloca.h> <ar.h> <assert.h> <conio.h> <ctype.h>
  20. ■format tty <curses.h> <dirent.h> <dos.h> <errno.h> <fcntl.h> <float.h>
  21. ■format tty <fnmatch.h> <ftw.h> <getopt.h> <glob.h> <graph.h> <grp.h>
  22. ■format tty <ieee.h> <io.h> <limits.h> <malloc.h> <math.h> <memory.h>
  23. ■format tty <os2.h> <os2emx.h> <os2thunk.h> <os2tk.h> <process.h> <pwd.h>
  24. ■format tty <setjmp.h> <sgtty.h> <share.h> <signal.h> <stdarg.h> <stddef.h>
  25. ■format tty <stdio.h> <stdlib.h> <string.h> <strings.h> <termcap.h>
  26. ■format tty <termio.h> <termios.h> <time.h> <umalloc.h> <unistd.h> <varargs.h>
  27. ■format tty <locale.h> <ulimit.h> <utime.h>
  28. ■format tty <emx/bigint.h> <emx/float.h> <emx/io.h> <emx/locale.h> <emx/nls.h>
  29. ■format tty <emx/pwd.h> <emx/startup.h> <emx/syscalls.h> <emx/thread.h>
  30. ■format tty <emx/time.h> <emx/umalloc.h>
  31. ■format tty <sys/builtin.h> <sys/dir.h> <sys/dirent.h>
  32. ■format tty <sys/dirtree.h> <sys/ea.h> <sys/ead.h> <sys/emxload.h>
  33. ■format tty <sys/fcntl.h> <sys/file.h> <sys/fmutex.h> <sys/hw.h> <sys/ioctl.h>
  34. ■format tty <sys/ipc.h> <sys/kbdscan.h> <sys/moddef.h> <sys/msg.h> <sys/nls.h>
  35. ■format tty <sys/param.h> <sys/process.h> <sys/ptrace.h> <sys/reg.h>
  36. ■format tty <sys/rmutex.h>
  37. ■format tty <sys/resource.h> <sys/select.h> <sys/signal.h> <sys/smutex.h>
  38. ■format tty <sys/socket.h> <sys/so_ioctl.h> <sys/stat.h> <sys/statfs.h>
  39. ■format tty <sys/termio.h> <sys/time.h> <sys/timeb.h> <sys/times.h>
  40. ■format tty <sys/types.h> <sys/uflags.h> <sys/uio.h> <sys/user.h> <sys/utime.h>
  41. ■format tty <sys/utsname.h> <sys/video.h> <sys/wait.h> <sys/winmgr.h>
  42.  
  43. ■format tty HPFS.IFS xf86sup.sys
  44.  
  45. ■format tty c_alias c_app c_dllnrt, c_dllrt c_dllso c_import c_static emx2
  46. ■format tty emxio moddef
  47.  
  48. ■format tty -Zmt -Zmtd -Zmts -Zomf -Zsys -Zbsd-signals -Zsysv-signals
  49. ■format tty -Zno-rte -Zso -Zcrtdll -Zbin-files -Zsmall-conv -pg
  50. ■format tty -l -lg -lgcc -lc -g -lwrap -lemxio -ltmalloc -mprobe
  51. ■format tty -lgraph -lvideo -lmoddef -lsocket -fpcc-struct-return
  52. ■format tty -c -p -t -ac -acm -ai -am -aw
  53.  
  54. ■format tty #define void volatile wchar_t jmp_buf sigjmp_buf sigset_t glob_t
  55.  
  56. ■format tty _DT_TREE _DT_NOCPDIR _EMXLOAD_INDEFINITE
  57. ■format tty MB_CUR_MAX MB_MAX_LEN
  58. ■format tty O_RDONLY O_WRONLY O_RDWR O_NDELAY O_APPEND O_CREAT O_TRUNC O_EXCL
  59. ■format tty O_BINARY O_TEXT O_NOINHERIT O_SYNC O_SIZE O_NONBLOCK
  60. ■format tty SH_DENYNO SH_DENYRD SH_DENYWR SH_DENYRW
  61. ■format tty F_OK R_OK W_OK X_OK
  62. ■format tty P_WAIT P_NOWAIT P_OVERLAY P_DEBUG P_DETACH _MEMDIF_EQ
  63. ■format tty P_SESSION P_PM P_DEFAULT P_FULLSCREEN P_WINDOWED P_MINIMIZE
  64. ■format tty P_MAXIMIZE P_BACKGROUND P_FOREGROUND P_NOCLOSE P_NOSESSION
  65. ■format tty P_QUOTE P_TILDE P_UNRELATED P_DEBUGDESC
  66. ■format tty NULL USE_OS2_TOOLKIT_HEADERS MAXNAMLEN _MAX_DRIVE _MAX_FNAME
  67. ■format tty  _MAX_EXT _MAX_DIR _MAX_PATH L_cuserid _PASSWORD_LEN MAXPATHLEN
  68. ■format tty RAND_MAX BUFSIZ L_tmpnam P_tmpdir TMP_MAX
  69. ■format tty HUGE_VAL HUGE_VALF HUGE_VALL CHAR_MAX
  70. ■format tty LONG_MIN LONG_MAX ULONG_MAX
  71. ■format tty LONG_LONG_MIN LONG_LONG_MAX ULONG_LONG_MAX
  72. ■format tty EOF CLK_TCK HZ CLOCKS_PER_SEC
  73. ■format tty FP_ZERO FP_SUBNORMAL FP_NORMAL FP_INFINITE FP_NAN DECIMAL_DIG
  74. ■format tty GETOPT_ANY GETOPT_KEEP GETOPT_UNIX
  75. ■format tty WNOHANG WUNTRACED
  76. ■format tty ARG_MAX CHILD_MAX NGROUPS_MAX OPEN_MAX STREAM_MAX
  77. ■format tty TZNAME_MAX LINK_MAX MAX_CANON MAX_INPUT NAME_MAX PATH_MAX
  78. ■format tty PIPE_BUF
  79. ■format tty _POSIX_JOB_CONTROL _POSIX_SAVED_IDS _POSIX_VERSION
  80. ■format tty _POSIX_CHOWN_RESTRICTED _POSIX_NO_TRUNC _POSIX_VDISABLE
  81. ■format tty _SC_ARG_MAX _SC_CHILD_MAX _SC_CLK_TCK _SC_NGROUPS_MAX
  82. ■format tty _SC_OPEN_MAX _SC_STREAM_MAX _SC_TZNAME_MAX _SC_JOB_CONTROL
  83. ■format tty _SC_SAVED_IDS _SC_VERSION
  84. ■format tty _PC_LINK_MAX _PC_MAX_CANON _PC_MAX_INPUT _PC_NAME_MAX
  85. ■format tty _PC_PATH_MAX _PC_PIPE_BUF _PC_CHOWN_RESTRICTED _PC_NO_TRUNC
  86. ■format tty _PC_VDISABLE
  87. ■format tty FNM_NOMATCH _FNM_MATCH _FNM_ERR
  88. ■format tty FNM_NOESCAPE FNM_PATHNAME FNM_PERIOD _FNM_POSIX
  89. ■format tty _FNM_OS2 _FNM_DOS _FNM_IGNORECASE _FNM_PATHPREFIX
  90. ■format tty GLOB_APPEND GLOB_DOOFFS GLOB_ERR GLOB_MARK GLOB_NOESCAPE
  91. ■format tty GLOB_NOCHECK GLOB_NOSORT GLOB_PERIOD
  92. ■format tty GLOB_ABEND GLOB_NOMATCH GLOB_NOSPACE
  93. ■format tty S_IREAD S_IWRITE S_IEXEC S_IFCHR S_ISCHR FD_SET FD_SETSIZE
  94. ■format tty IDEFAULT IDELETE IGNCR ISTRIP INLCR ICANON ISIG IUCLC ICRNL
  95. ■format tty ECHO ECHOK
  96. ■format tty VINTR VQUIT VERASE VEOF VKILL VEOL VMIN VTIME VSUSP VSTOP VSTART
  97. ■format tty TCIOFF TCION TCOOFF TCOON TCIFLUSH TCIOFLUSH TCOFLUSH
  98. ■format tty TCSANOW TCSADRAIN TCSAFLUSH
  99. ■format tty SIG_DFL SIG_IGN SIG_ERR SIG_ACK SIGABRT SIGALRM SIGBREAK SIGFPE
  100. ■format tty SIGILL SIGINT SIGPIPE SIGSEGV SIGCHLD SIGCLD SIGKILL SIGTERM
  101. ■format tty SIGQUIT SIGTRAP SIGEMT SIGBUS SIGSYS SIGUSR1 SIGUSR2 SIGHUP
  102. ■format tty SIGPTRACENOTIFY SIGWINCH
  103. ■format tty SA_NOCLDSTOP SA_SYSV SA_ACK SIG_BLOCK SIG_UNBLOCK SIG_SETMASK
  104. ■format tty TCGETA TCSETA TCSETAF TCSETAW TCFLSH TCSBRK TCXONC
  105. ■format tty FIONREAD FGETHTYPE
  106. ■format tty F_GETFL F_SETFL F_GETFD F_SETFD F_DUPFD FD_CLOEXEC
  107. ■format tty OS2_MODE DOS_MODE SEEK_SET SEEK_CUR SEEK_END HT_FILE
  108. ■format tty EPERM ENOENT ESRCH EINTR EIO E2BIG ENOEXEC EBADF ECHILD
  109. ■format tty EAGAIN ENOMEM EACCES EEXIST EXDEV ENOTDIR EISDIR EINVAL
  110. ■format tty EMFILE ENOTTY ENOSPC ESPIPE EROFS EPIPE EDOM ERANGE ENOSYS
  111. ■format tty ENAMETOOLONG EWOULDBLOCK
  112. ■format tty LC_ALL LC_COLLATE LC_CTYPE LC_MONETARY LC_NUMERIC LC_TIME
  113. ■format tty G_OUTLINE G_FILL G_MODE_OFF G_MODE_EGA_C G_MODE_EGA_E
  114. ■format tty G_MODE_VGA_H G_MODE_VGA_L G_SET_KEEP
  115. ■format tty _HEAPBADBEGIN _HEAPBADNODE _HEAPEMPTY _HEAPOK _HEAPBADEND
  116. ■format tty _BLOCK_CLEAN _HEAP_REGULAR _HEAP_TILED _HEAP_SHARED _HEAP_MIN_SIZE
  117. ■format tty _RUNTIME_HEAP _FORCE _FREEENTRY _USEDENTRY
  118. ■format tty FTW_D FTW_F FTW_NS FTW_DNR _IONBF _IOFBF _IOLBF
  119. ■format tty PTRACE_TRACEME PTRACE_PEEKTEXT PTRACE_PEEKDATA PTRACE_PEEKUSER
  120. ■format tty PTRACE_POKETEXT PTRACE_POKEDATA PTRACE_POKEUSER PTRACE_RESUME
  121. ■format tty PTRACE_EXIT PTRACE_STEP PTRACE_SESSION PTRACE_NOTIFICATION
  122. ■format tty PTRACE_CONT PTRACE_THAW PTRACE_FREEZE PTRACE_ATTACH PTRACE_DETACH
  123. ■format tty PTRACE_GETPID PTRACE_GETTID PTRACE_PIDTID
  124. ■format tty PTN_NONE PTN_THREAD_NEW PTN_THREAD_END PTN_MODULE_LOAD
  125. ■format tty PTN_MODULE_FREE PTN_PROC_NEW
  126. ■format tty PTNMOD_DLL PTNMOD_AOUT PTNPROC_FORK PTNPROC_AOUT
  127. ■format tty MCW_EM MCW_IC MCW_RC MCW_PC EM_INVALID EM_DENORMAL EM_ZERODIVIDE
  128. ■format tty EM_OVERFLOW EM_UNDERFLOW EM_INEXACT RC_NEAR RC_DOWN
  129. ■format tty RC_UP RC_CHOP PC_24 PC_53 PC_64
  130. ■format tty V_MONOCHROME V_COLOR_8 V_COLOR_12 BLINK INTENSITY
  131. ■format tty V_SCROLL_UP V_SCROLL_DOWN V_SCROLL_CLEAR
  132. ■format tty UL_GFILLIM UL_SFILLIM UL_GMEMLIM UL_NOFILES UL_OBJREST
  133. ■format tty _UF_SIG_MODEL _UF_SIG_EMX _UF_SIG_SYSV _UF_SIG_BSD
  134. ■format tty _UF_SBRK_MODEL _UF_SBRK_CONTIGUOUS _UF_SBRK_MONOTONOUS
  135. ■format tty _UF_SBRK_ARBITRARY
  136. ■format tty _UF_PTRACE_MODEL _UF_PTRACE_STANDARD _UF_PTRACE_NOTIFY
  137. ■format tty _UF_PTRACE_MULTITHREAD
  138. ■format tty _EAD_MERGE NDEBUG _FMC_SHARED _FMR_IGNINT _FMR_NOWAIT
  139. ■format tty _MD_BASE _MD_CODE _MD_DATA _MD_DESCRIPTION _MD_EXETYPE _MD_EXPORTS
  140. ■format tty _MD_HEAPSIZE _MD_IMPORTS _MD_LIBRARY _MD_NAME _MD_OLD _MD_PHYSICAL
  141. ■format tty _MD_PROTMODE _MD_REALMODE _MD_SEGMENTS _MD_STACKSIZE _MD_STUB
  142. ■format tty _MD_VIRTUAL
  143. ■format tty _MD_eof _MD_dot _MD_at _MD_equal _MD_number _MD_word
  144. ■format tty _MD_quote _MD_ioerror _MD_missingquote _MD_parseerror
  145. ■format tty _MDE_IO_ERROR _MDE_MISSING_QUOTE _MDE_EMPTY _MDE_NAME_EXPECTED
  146. ■format tty _MDE_STRING_EXPECTED _MDE_NUMBER_EXPECTED _MDE_DEVICE_EXPECTED
  147. ■format tty _MDE_EQUAL_EXPECTED _MDE_DOT_EXPECTED _MDE_STRING_TOO_LONG
  148. ■format tty _MDE_INVALID_ORDINAL _MDE_INVALID_STMT
  149. ■format tty _MDEP_ORDINAL _MDEP_RESIDENTNAME _MDEP_NONAME _MDEP_NODATA
  150. ■format tty _MDEP_PWORDS _MDIP_ORDINAL _MDIT_DEFAULT _MDIT_INSTANCE
  151. ■format tty _MDIT_GLOBAL _MDS_IOPL _MDS_MULTIPLE _MDS_SHARED _MDT_DEFAULT
  152. ■format tty _MDT_WINDOWAPI _MDT_WINDOWCOMPAT _MDT_NOTWINDOWCOMPAT
  153. ■format tty _MDX_OS2 _MDX_WINDOWS
  154.  
  155. ■format tty c_lflag c_oflag c_cflag c_cc c_line st_dev st_rdev st_ino umask
  156. ■format tty dstflag millitm time_t errno quot rem tms_utime
  157. ■format tty tm_hour tm_mday tm_min tm_mon tm_sec tm_year tm_wday
  158. ■format tty tm_yday tm_isdst gl_pathc gl_pathv gl_offs
  159. ■format tty sa_handler sa_mask sa_flags
  160.  
  161. ■format tty getch() getche()
  162. ■format tty __open() DosAllocMem DosAllocSharedMem DosCreateThread DosFreeMem
  163. ■format tty DosGetMessage DosGetNamedSharedMem DosGetSharedMem
  164. ■format tty DosGiveSharedMem DosQueryMessageCP DosExit
  165. ■format tty DosExecPgm DosSleep DosStartSession DosExitList DosOpen DosRead
  166. ■format tty DosResetBuffer
  167. ■format tty HMTX
  168. ■format tty ERROR_INVALID_HANDLE ERROR_INTERRUPT ERROR_TOO_MANY_HANDLES
  169. ■format tty ERROR_MUTEX_OWNED ERROR_ACCESS_DENIED ERROR_FILE_EXISTS
  170.  
  171. ■format tty _ea _ead fd_set ino_t wm_handle _dt_tree _far16ptr _dt_node
  172. ■format tty FEA2LIST FEALIST PFEA2LIST PFEALIST REGS
  173. ■format tty optarg opterr optind optopt optswchar optmode
  174. ■format tty _nls_tolower_tab _nls_toupper_tab _nls_ctype_tab
  175. ■format tty sys_errlist sys_nerr _emx_rev environ g_xsize g_ysize g_colors
  176. ■format tty _osmajor _osminor _osmode tzname stdin stdout stderr
  177. ■format tty _fmutex _rmutex _smutex Heap_t _HEAPSTATS
  178.  
  179. ■format tty BASE CODE DATA DESCRIPTION EXETYPE EXPORTS HEAPSIZE IMPORTS
  180. ■format tty LIBRARY NAME OLD PROTMODE REALMODE SEGMENTS STACKSIZE STUB
  181. ■format tty PHYSICAL VIRTUAL DEVICE
  182. ■format tty WINDOWS RESIDENTNAME NODATA NONAME MAXVAL NEWFILES NONE
  183.  
  184. ■format abbrev etc.
  185.  
  186. ■if text
  187. ■h= Table of Contents
  188. ■toc
  189. ■endif
  190.  
  191. ■h1 Introduction to the emx C Library Reference
  192. ■ipf
  193. :font facename=Helv size=24x14.:hp2.emx 0.9d C Library Reference
  194. :ehp2.
  195. :p.
  196. :font facename=Helv size=16x10.      Copyright (c) 1990-1998 by Eberhard Mattes
  197. :font facename=default size=0x0.
  198. :p.
  199. ■endipf
  200.  
  201. ■ipfminitoc
  202.  
  203. ■h2 Preliminary notes
  204.  
  205. ■itemize
  206. ■item
  207.  
  208.   `C90' is short for ISO 9899-1990, the ANSI/ISO standard for the C
  209.   programming language
  210.  
  211. ■item
  212.  
  213.   `C9X' is short for the upcoming version of ISO 9899
  214.  
  215. ■item
  216.  
  217.   Not all functions declared in the headers are implemented.
  218.  
  219. ■item
  220.  
  221.   By default, text mode is used for files.  See ■hpt{fread()} and
  222.   ■hpt{fwrite()} for details.  The default can be globally changed to
  223.   binary mode by linking with binmode.o or binmode.obj
  224.   (■hpt{-Zbin-files} option of GCC).
  225.  
  226. ■item
  227.  
  228.   See the description of ■hpt{g_mode()} for general information about
  229.   the graphics library.
  230.  
  231. ■item
  232.  
  233.   See the description of ■hpt{v_init()} for general information about
  234.   the video library.
  235.  
  236. ■item
  237.  
  238.   See the description of ■hpt{wm_init()} for general information about
  239.   the window manager functions.
  240.  
  241. ■enditemize
  242.  
  243.  
  244. ■h2 Libraries
  245.  
  246.   The following emx libraries are provided:
  247.  
  248. ■list
  249. ■item ■tt{st/c}
  250.  
  251.     The single-thread C library.  This library includes the ISO C
  252.     library functions, Unix extensions and emx extensions.  Only
  253.     functions are included which are common to all types of
  254.     applications and DLLs.  See also c_app, c_dllnrt, c_dllrt, and
  255.     c_dllso.
  256.  
  257. ■item ■tt{mt/c}
  258.  
  259.     The multithread C library.  See library ■tt{st/c}.  This library
  260.     is used instead of library ■tt{st/c} if the ■hpt{-Zmt} or
  261.     ■hpt{-Zmts} option is specified.
  262.  
  263. ■item c_alias
  264.  
  265.     Aliases for non-ISO-C symbols.  This library maps, for
  266.     instance, ■tt{eof()} to ■tt{_eof()}.  The static and dynamic C
  267.     libraries contain these symbols with one underscore prepended to
  268.     the names.  In consequence, redefining a non-ISO-C library
  269.     function should be possible even if the C library uses the
  270.     function internally.  (c_alias has not been merged into the
  271.     static, dynamic, and import libraries due to restrictions in
  272.     LINK386, ■bf{ar}, and ■hpt{emxomfar}.)
  273.  
  274. ■item ■tt{st/c_app}
  275.  
  276.     This library is used in addition to ■tt{st/c} for building a
  277.     single-thread statically linked application.
  278.  
  279. ■item ■tt{st/c_app_p}
  280.  
  281.     Like library ■tt{st/c_app}, with profiling hooks.  This library is
  282.     used instead of library ■tt{st/c_app} if the -pg option is
  283.     specified.
  284.  
  285. ■item ■tt{mt/c_app}
  286.  
  287.     This library is used in addition to ■tt{st/c} for building a
  288.     multithread statically linked application.
  289.  
  290. ■item ■tt{c_dllrt}
  291.  
  292.     This library is used in addition to ■tt{st/c} for building a
  293.     DLL without runtime environment.
  294.  
  295. ■item ■tt{st/c_dllrt}
  296.  
  297.     This library is used in addition to ■tt{st/c} for building a
  298.     single-thread custom C runtime DLL.
  299.  
  300. ■item ■tt{mt/c_dllrt}
  301.  
  302.     This library is used in addition to ■tt{mt/c} for building a
  303.     multithread custom C runtime DLL.
  304.  
  305. ■item ■tt{st/c_dllso}
  306.  
  307.     This library is used in addition to ■tt{mt/c} for building a
  308.     single-thread stand-alone DLL.  Such a DLL has its own runtime
  309.     environment.
  310.  
  311. ■item ■tt{mt/c_dllso}
  312.  
  313.     This library is used in addition to ■tt{mt/c} for building a
  314.     multithread stand-alone DLL.  Such a DLL has its own runtime
  315.     environment.
  316.  
  317. ■item ■tt{st/c_import}
  318.  
  319.     Import library for emxlibcs.dll.  This library is used instead of
  320.     libraries ■tt{c}, c_app, and ■tt{gcc} if the ■hpt{-Zcrtdll} option
  321.     without the ■hpt{-Zmt} option is specified.
  322.  
  323. ■item ■tt{mt/c_import}
  324.  
  325.     Import library for emxlibcm.dll.  This library is used instead of
  326.     libraries ■tt{c}, c_app, and ■tt{gcc} if the ■hpt{-Zcrtdll} and
  327.     ■hpt{-Zmt} options (or ■hpt{-Zmtd}) are specified.
  328.  
  329. ■item ■tt{st/c_p}
  330.  
  331.     The single-thread C library, with profiling hooks.  See library
  332.     ■tt{st/c}.  This library is used instead of library ■tt{st/c} if
  333.     the -pg option is specified.
  334.  
  335. ■item c_static
  336.  
  337.     Code which must be statically linked when linking the C library
  338.     dynamically.  This library is searched if the ■hpt{-Zcrtdll}
  339.     option of GCC is specified.
  340.  
  341. ■item ■tt{st/emx}
  342.  
  343.     System call interface to emx for single-thread programs.  For
  344.     instance, this library translates the __open() system call to
  345.     system call 0x2b of emx.  When using this library, emx.dll is
  346.     required under OS/2.  This library is always required for DOS
  347.     programs.
  348.  
  349. ■item ■tt{mt/emx}
  350.  
  351.     System call interface to emx for multithread programs.  For
  352.     instance, this library translates the __open() system call to
  353.     system call 0x2b of emx.  When using this library, emx.dll is
  354.     required.
  355.  
  356. ■item emx2
  357.  
  358.     Import library for emx.dll.  This library is used by libraries
  359.     emx.a, emx.lib, os2.a, and os2.lib (unless sys.lib is used, see
  360.     ■hpt{-Zsys}).
  361.  
  362. ■item emxio
  363.  
  364.     Import library for emxio.dll.  When using hardware port I/O
  365.     functions such as ■hpt{_outp8()} with non-standard libraries, you
  366.     may have to use this library.  With the standard emx libraries,
  367.     -lemxio is not required.  -lemxio must not be used if the program
  368.     should also run under DOS.
  369.  
  370. ■item ■tt{end.lib}
  371.  
  372.     Library defining the ■tt{edata}, ■tt{end}, and ■tt{etext} symbols.
  373.     ld automatically defines these symbols, therefore there is no
  374.     ■tt{end.a} library.  GCC uses ■tt{-lend} if -Zomf is given on the
  375.     command line.
  376.  
  377. ■item ■tt{g}
  378.  
  379.     Dummy debugging library.  GCC uses -lg if -g is given on the
  380.     command line.
  381.  
  382. ■item ■tt{gcc}
  383.  
  384.     Compiler helper functions for GCC.  The functions of library
  385.     ■tt{gcc} are duplicated in emxlibcm.dll and emxlibcs.dll.  As
  386.     library ■tt{gcc} requires functions from library ■tt{c} and
  387.     library ■tt{c} requires functions from library ■tt{gcc}, -lgcc
  388.     must be given twice on the command line of the Unix-style linker:
  389.     -lgcc -lc -lgcc.
  390.  
  391. ■item ■tt{gcc_p}
  392.  
  393.     Compiler helper functions for GCC, with profiling hooks.  See
  394.     library ■tt{gcc}.  This library is used instead of library
  395.     ■tt{gcc} if the -pg option is specified.
  396.  
  397. ■item ■tt{graph}
  398.  
  399.     Graphics library
  400.  
  401. ■item ■tt{m}
  402.  
  403.     Dummy math library.  This library is provided for makefile
  404.     compatibility; it isn't required as the math functions are
  405.     contained in library ■tt{c}.
  406.  
  407. ■item ■tt{st/malloc1}
  408.  
  409.     Old malloc() library of emx 0.9b and older, single-thread.  This
  410.     library is provided as fall back in case the new malloc()
  411.     implementation turns out not to work properly.
  412.  
  413. ■item ■tt{mt/malloc1}
  414.  
  415.     Old malloc() library of emx 0.9b and older, multithread.  This
  416.     library is provided as fall back in case the new malloc()
  417.     implementation turns out not to work properly.
  418.  
  419. ■item moddef
  420.  
  421.     Functions for reading module definition files.  See
  422.     ■hpt{_md_open()} for details.  This library can be used for
  423.     single-thread programs and multithread programs.
  424.  
  425. ■item ■tt{omflib}
  426.  
  427.     Functions for reading and creating OMF (Object Module Formats)
  428.     libraries, that is, ■tt{.lib} files.
  429.  
  430. ■item ■tt{os2}
  431.  
  432.     Import library for OS/2 API.  This library is not a pure import
  433.     library, it also contains static code for DosGetMessage and
  434.     DosQueryMessageCP and for the 32-bit wrappers.  emx2.a, emx2.lib,
  435.     or sys.lib is required by the 32-bit wrappers.
  436.  
  437. ■item ■tt{os2_p}
  438.  
  439.     Profiling hooks and import definitions for OS/2 API.  See library
  440.     ■tt{os2}.  This library is used instead of library ■tt{os2} if the
  441.     -pg option is specified.
  442.  
  443. ■item ■tt{socket}
  444.  
  445.     Socket library.
  446.  
  447. ■item ■tt{st/sys}
  448.  
  449.     System call emulation library for single-thread programs.  This
  450.     library is used instead of emx.a or emx.lib for creating
  451.     stand-alone OS/2 applications (■hpt{-Zsys}).  It is provided in
  452.     OMF style only (■tt{st/sys.lib}).
  453.  
  454. ■item ■tt{mt/sys}
  455.  
  456.     Multithread version of ■tt{st/sys} (see above).  This library is
  457.     provided in OMF style only (■tt{mt/sys.lib}).  It is used instead
  458.     of ■tt{st/sys.lib} if the ■hpt{-Zmt} option is specified.
  459.  
  460. ■item ■tt{tmalloc}
  461.  
  462.     Implement ■hpt{_tmalloc()} etc. on top of malloc() etc.  This
  463.     library is required if you replace the emx implementation of
  464.     malloc() with an implementation of malloc() (GNU malloc, for
  465.     instance) that has not _tmalloc() built in.
  466.  
  467. ■item ■tt{video}
  468.  
  469.     Video library.  This library contains the functions declared in
  470.     <sys/video.h> and <sys/winmgr.h>.
  471.  
  472. ■item ■tt{wrap}
  473.  
  474.     Import library for emxwrap.dll.  Use this library (-lwrap) to
  475.     reduce the size of your executable file when using 16-bit OS/2 API
  476.     functions.  If you don't use -lwrap, the wrapper functions are
  477.     taken from library ■tt{os2}.
  478.  
  479. ■endlist
  480.  
  481. ■h- The following dynamic link libraries are provided:
  482.  
  483. ■list
  484.  
  485. ■item emx.dll
  486.  
  487.     This is the emx run-time support.  The import library for emx.dll
  488.     is emx2.
  489.  
  490. ■item emxio.dll
  491.  
  492.     Access to hardware ports.  The import library for emxio.dll is
  493.     emxio.
  494.  
  495. ■item emxlibc.dll
  496.  
  497.     Forwarder DLL.  This DLL is provided to maintain compatibility of
  498.     existing applications using emxlibc.dll.  Entry points are
  499.     forwarded to emxlibcm.dll.
  500.  
  501. ■item emxlibcm.dll
  502.  
  503.     Multithread emx C library.  Contains all functions of the
  504.     libraries ■tt{mt/c}, ■tt{mt/c_dllrt}, and ■tt{gcc}.  For
  505.     compatibility with existing programs, emxlibcm.dll contains dummy
  506.     functions for port I/O, though these didn't work in emxlibc.dll of
  507.     emx 0.8e.  The import library for emxlibcm.dll is
  508.     ■tt{mt/c_import}.
  509.  
  510. ■item emxlibcs.dll
  511.  
  512.     Single-thread emx C library.  Contains all functions of the
  513.     libraries ■tt{st/c}, ■tt{st/c_dllrt}, and ■tt{gcc}.  The import
  514.     library for emxlibcs.dll is ■tt{st/c_import}.
  515.  
  516. ■item emxwrap.dll
  517.  
  518.     32-bit wrappers for 16-bit OS/2 API functions.  This DLL uses
  519.     emx.dll.  The import library for emxwrap.dll is ■tt{wrap}.  The
  520.     functions contained in emxwrap.dll are also available for static
  521.     linking in library ■tt{os2}.
  522.  
  523. ■endlist
  524.  
  525.  
  526. ■h2 Headers
  527.  
  528.   This section briefly describes the headers.
  529.  
  530. ■list
  531.  
  532. ■item <a_out.h>
  533.  
  534.     Contains definitions for the a.out file format (.o and executable
  535.     files).
  536.  
  537. ■item <alloca.h>
  538.  
  539.     Makes the ■hpt{alloca()} built-in function available.
  540.  
  541. ■item <ar.h>
  542.  
  543.     Contains definitions for the archive file format (.a files).
  544.  
  545. ■item <assert.h>
  546.  
  547.     Implements assertions for debugging (C90): ■hpt{assert()}.
  548.  
  549. ■item <conio.h>
  550.  
  551.     Defines getch() and getche() for porting MS-DOS programs.
  552.  
  553. ■item <ctype.h>
  554.  
  555.     Character classification macros and functions.  Letter case
  556.     conversion.  If you include this header, you get the macro
  557.     (and inline) versions of the routines.  Otherwise, you get the
  558.     function versions.
  559.  
  560.     C90 functions and macros: ■hpt{isalnum()}, ■hpt{isalpha()},
  561.     ■hpt{iscntrl()}, ■hpt{isdigit()}, ■hpt{isgraph()},
  562.     ■hpt{islower()}, ■hpt{isprint()}, ■hpt{ispunct()},
  563.     ■hpt{isspace()}, ■hpt{isupper()}, ■hpt{isxdigit()},
  564.     ■hpt{tolower()}, ■hpt{toupper()}.
  565.  
  566.     Additional functions and macros: ■hpt{isascii()},
  567.     ■hpt{_tolower()}, ■hpt{_toupper()}.
  568.  
  569. ■item <curses.h>
  570.  
  571.     Declarations and definitions of the BSD curses screen library.
  572.  
  573. ■item <dirent.h>
  574.  
  575.     Functions for reading directories.
  576.  
  577.     POSIX.1 functions: ■hpt{closedir()}, ■hpt{opendir()},
  578.     ■hpt{readdir()}, ■hpt{rewinddir()}.
  579.  
  580.     Additional functions: ■hpt{seekdir()}, ■hpt{telldir()}.
  581.  
  582. ■item <dos.h>
  583.  
  584.     Declares the ■hpt{_int86()} function and associated structures.
  585.  
  586. ■item <errno.h>
  587.  
  588.     Declares the ■hpt{errno} object and defines error code constants
  589.     (C90).
  590.  
  591. ■item <fcntl.h>
  592.  
  593.     Defines file mode constants such as O_RDONLY and other constants.
  594.     Declares the ■hpt{fcntl()} and ■hpt{flock()} functions.  Includes
  595.     <sys/fcntl.h>.
  596.  
  597. ■item <float.h>
  598.  
  599.     Floating point constants and functions for controlling the math
  600.     coprocessor (C90).
  601.  
  602.     Non-standard functions: ■hpt{_clear87()}, ■hpt{_control87()},
  603.     ■hpt{_fpreset()}, ■hpt{_status87()}.
  604.  
  605. ■item <fnmatch.h>
  606.  
  607.     Declares the ■hpt{fnmatch()} function and defines constants for
  608.     fnmatch() (POSIX.2).
  609.  
  610. ■item <ftw.h>
  611.  
  612.     File tree walk: ■hpt{ftw()}.  Apply a function to all files in a
  613.     directory tree.
  614.  
  615. ■item <getopt.h>
  616.  
  617.     Declares ■hpt{getopt()} for parsing command line options
  618.     (POSIX.2).
  619.  
  620. ■item <glob.h>
  621.  
  622.     Declares the ■hpt{glob()} and ■hpt{globfree()} functions and
  623.     defines the glob_t type and constants for glob() (POSIX.2).
  624.  
  625. ■item <graph.h>
  626.  
  627.     Declares the emx graphics library functions and defines associated
  628.     constants.
  629.  
  630.     Functions: ■hpt{g_box()}, ■hpt{g_clear()}, ■hpt{g_clip()},
  631.     ■hpt{g_ellipse()}, ■hpt{g_get()}, ■hpt{g_hline()}, ■hpt{g_line()},
  632.     ■hpt{g_lock()}, ■hpt{g_mode()}, ■hpt{g_modeset()},
  633.     ■hpt{g_polygon()}, ■hpt{g_set()}, ■hpt{g_triangle()},
  634.     ■hpt{g_unlock()}, ■hpt{g_unlockall()}, ■hpt{g_vgapal()},
  635.     ■hpt{g_vline()}, ■hpt{g_waitv()}, ■hpt{g_wmode()}.
  636.  
  637. ■item <grp.h>
  638.  
  639.     Declares the ■tt{getgrgid()} and ■tt{getgrnam()} functions and
  640.     defines ■tt{struct group} (POSIX.1).
  641.  
  642. ■item <ieee.h>
  643.  
  644.     Constants describing the IEEE floating point format used under emx.
  645.  
  646. ■item <io.h>
  647.  
  648.     Declares low-level I/O functions.
  649.  
  650.     Functions: ■hpt{access()}, ■hpt{chmod()}, ■hpt{chsize()},
  651.     ■hpt{close()}, ■hpt{creat()}, ■hpt{_crlf()}, ■hpt{dup()},
  652.     ■hpt{dup2()}, ■hpt{eof()}, ■hpt{filelength()}, ■hpt{fstat()},
  653.     ■hpt{fsync()}, ■hpt{ftruncate()}, ■hpt{_imphandle()},
  654.     ■hpt{ioctl()}, ■hpt{isatty()}, ■hpt{_isterm()}, ■hpt{lseek()},
  655.     ■hpt{mkstemp()}, ■hpt{mktemp()}, ■hpt{open()}, ■hpt{pipe()},
  656.     ■hpt{read()}, ■hpt{remove()}, ■hpt{rename()}, ■hpt{_seek_hdr()},
  657.     ■hpt{select()}, ■hpt{setmode()}, ■hpt{sopen()}, ■hpt{stat()},
  658.     ■hpt{tell()}, ■hpt{truncate()}, ■hpt{umask()}, ■hpt{unlink()},
  659.     ■hpt{write()}.
  660.  
  661. ■item <limits.h>
  662.  
  663.     Data type limit constants (C90).
  664.  
  665. ■item <locale.h>
  666.  
  667.     Functions and constants for localization.
  668.  
  669.     C90 functions: ■hpt{localeconv()}, ■hpt{setlocale()}.
  670.  
  671. ■item <malloc.h>
  672.  
  673.     Declares functions for dynamic memory allocation.  For
  674.     portability, use <stdlib.h> instead of <malloc.h>.
  675.  
  676.     C90 functions (note that <malloc.h> is not a C90 header):
  677.     ■hpt{calloc()}, ■hpt{free()}, ■hpt{malloc()}, ■hpt{realloc()}.
  678.  
  679.     Functions for allocating tiled memory: ■hpt{_tcalloc()},
  680.     ■hpt{_tfree()}, ■hpt{_tmalloc()}, ■hpt{_trealloc()}.
  681.  
  682.     Additional non-standard functions: ■hpt{_expand()},
  683.     ■hpt{_heapchk()}, ■hpt{_heapmin()}, ■hpt{_heapset()},
  684.     ■hpt{_msize()}.
  685.  
  686. ■item <math.h>
  687.  
  688.     Declares floating-point functions.
  689.  
  690.     C90 functions: ■hpt{acos()}, ■hpt{asin()}, ■hpt{atan()},
  691.     ■hpt{atan2()}, ■hpt{ceil()}, ■hpt{cos()}, ■hpt{cosh()},
  692.     ■hpt{exp()}, ■hpt{fabs()}, ■hpt{floor()}, ■hpt{fmod()},
  693.     ■hpt{frexp()}, ■hpt{ldexp()}, ■hpt{log()}, ■hpt{log10()},
  694.     ■hpt{modf()}, ■hpt{pow()}, ■hpt{sin()}, ■hpt{sinh()},
  695.     ■hpt{sqrt()}, ■hpt{tan()}, ■hpt{tanh()}.
  696.  
  697.     Functions proposed for C9X: ■hpt{acosl()}, ■hpt{asinl()},
  698.     ■hpt{atanl()}, ■hpt{atan2l()}, ■hpt{ceill()}, ■hpt{copysign()},
  699.     ■hpt{copysignf()}, ■hpt{copysignl()}, ■hpt{cosl()}, ■hpt{coshl()},
  700.     ■hpt{expl()}, ■hpt{fabsl()}, ■hpt{floorl()}, ■hpt{fmodl()},
  701.     ■hpt{frexpl()}, ■hpt{hypot()}, ■hpt{hypotl()}, ■hpt{ldexpl()},
  702.     ■hpt{logl()}, ■hpt{log10l()}, ■hpt{modfl()}, ■hpt{nextafter()},
  703.     ■hpt{nextafterf()}, ■hpt{nextafterl()}, ■hpt{powl()},
  704.     ■hpt{rint()}, ■hpt{rintl()}, ■hpt{sinl()}, ■hpt{sinhl()},
  705.     ■hpt{sqrtl()}, ■hpt{tanl()}, ■hpt{tanhl()}, ■hpt{trunc()},
  706.     ■hpt{truncl()}.
  707.  
  708.     Macros proposed for C9X: ■hpt{fpclassify()}, ■hpt{isfinite()},
  709.     ■hpt{isnan()}, ■hpt{isnormal()}, ■hpt{signbit()}.
  710.  
  711.     Other functions: ■hpt{atof()}, ■hpt{_atofl()}, ■hpt{cbrt()},
  712.     ■hpt{_cbrtl()}.
  713.  
  714. ■item <memory.h>
  715.  
  716.     Declares functions dealing with blocks of memory.  New programs
  717.     should use <string.h> instead.
  718.  
  719.     Functions: ■hpt{memccpy()}, ■hpt{memchr()}, ■hpt{memcmp()},
  720.     ■hpt{_memcount()}, ■hpt{memcpy()}, ■hpt{_memdif()},
  721.     ■hpt{memicmp()}, ■hpt{memmove()}, ■hpt{_memrchr()},
  722.     ■hpt{memset()}, ■hpt{_memswap()}.
  723.  
  724. ■item <os2.h>
  725.  
  726.     Include this header to get all or part of the OS/2 constants,
  727.     macros and functions.  Includes either <os2emx.h> or <os2tk.h>.
  728.     Either change <os2.h> or #define USE_OS2_TOOLKIT_HEADERS in your
  729.     source file to use the header files of the Programmer's Toolkit
  730.     for OS/2 2.x (an IBM product).
  731.  
  732. ■item <os2emx.h>
  733.  
  734.     A subset of the OS/2 definitions and declarations.  This header
  735.     file is included by <os2.h> unless you choose to use the header
  736.     files of the Programmer's Toolkit for OS/2 2.x (an IBM product).
  737.  
  738. ■item <os2thunk.h>
  739.  
  740.     Thunking support, included by <os2.h>.  You don't have to include
  741.     this header in your programs unless you want to create thunks
  742.     without including <os2.h>.
  743.  
  744. ■item <os2tk.h>
  745.  
  746.     Makes the header files of the Developer's Toolkit for OS/2 2.x
  747.     usable for emx and GCC.
  748.  
  749. ■item <process.h>
  750.  
  751.     Process management.  Includes <sys/process.h>.
  752.  
  753.     Functions: ■hpt{abort()}, ■hpt{atexit()}, ■hpt{execl()},
  754.     ■hpt{execle()}, ■hpt{execlp()}, ■hpt{execlpe()}, ■hpt{execv()},
  755.     ■hpt{execve()}, ■hpt{execvp()}, ■hpt{execvpe()}, ■hpt{exit()},
  756.     ■hpt{_exit()}, ■hpt{fork()}, ■hpt{getpid()}, ■hpt{getppid()},
  757.     ■hpt{spawnl()}, ■hpt{spawnle()}, ■hpt{spawnlp()},
  758.     ■hpt{spawnlpe()}, ■hpt{spawnv()}, ■hpt{spawnve()},
  759.     ■hpt{spawnvp()}, ■hpt{spawnvpe()}, ■hpt{system()}, ■hpt{wait()},
  760.     hpt{waitpid()}.
  761.  
  762. ■item <pwd.h>
  763.  
  764.     Password management.
  765.  
  766.     POSIX.1 functions: ■hpt{getpwnam()}, ■hpt{getpwuid()}.
  767.  
  768.     Additional functions: ■hpt{endpwent()}, ■hpt{getpass()},
  769.     ■hpt{_getpass1()}, ■hpt{_getpass2()}, ■hpt{getpwent()},
  770.     ■hpt{setpwent()}.
  771.  
  772. ■item <setjmp.h>
  773.  
  774.     Non-local jumps.  Defines jmp_buf and sigjmp_buf.
  775.  
  776.     C90 functions: ■hpt{longjmp()}, ■hpt{setjmp()}.
  777.  
  778.     POSIX.1 functions: ■hpt{siglongjmp()}, ■hpt{sigsetjmp()}.
  779.  
  780. ■item <sgtty.h>
  781.  
  782.     Empty file.  emx doesn't have a BSD-style general terminal interface.
  783.  
  784. ■item <share.h>
  785.  
  786.     Constants for file sharing.
  787.  
  788. ■item <signal.h>
  789.  
  790.     Signal processing.  Includes <sys/signal.h>.
  791.  
  792.     C90 functions: ■hpt{signal()}, ■hpt{raise()}.
  793.  
  794.     POSIX.1 functions: ■hpt{kill()}, ■hpt{pause()}, ■hpt{sigaction()},
  795.     ■hpt{sigaddset()}, ■hpt{sigdelset()}, ■hpt{sigemptyset()},
  796.     ■hpt{sigfillset()}, ■hpt{sigismember()}, ■hpt{sigpending()},
  797.     ■hpt{sigprocmask()}, ■hpt{sigsuspend()}.
  798.  
  799. ■item <stdarg.h>
  800.  
  801.     Macros to implement functions with variable number of arguments --
  802.     ISO C version.
  803.  
  804.     C90 macros: ■hpt{va_start()}, ■hpt{va_arg()}, ■hpt{va_end()}.
  805.  
  806. ■item <stddef.h>
  807.  
  808.     Various definitions.
  809.  
  810.     C90 macros: ■hpt{offsetof()}.
  811.  
  812.     Other macros: ■hpt{_threadid}.
  813.  
  814. ■item <stdio.h>
  815.  
  816.     Stream I/O library.
  817.  
  818.     C90 functions: ■hpt{clearerr()}, ■hpt{fclose()},
  819.     ■hpt{feof()}, ■hpt{ferror()}, ■hpt{fflush()}, ■hpt{fgetc()},
  820.     ■hpt{fgetpos()}, ■hpt{fgets()}, ■hpt{fopen()}, ■hpt{fprintf()},
  821.     ■hpt{fputc()}, ■hpt{fputs()}, ■hpt{fread()}, ■hpt{freopen()},
  822.     ■hpt{fscanf()}, ■hpt{fseek()}, ■hpt{fsetpos()}, ■hpt{ftell()},
  823.     ■hpt{fwrite()}, ■hpt{getc()}, ■hpt{getchar()}, ■hpt{gets()},
  824.     ■hpt{perror()}, ■hpt{printf()}, ■hpt{putc()}, ■hpt{putchar()},
  825.     ■hpt{puts()}, ■hpt{remove()}, ■hpt{rename()}, ■hpt{rewind()},
  826.     ■hpt{scanf()}, ■hpt{setbuf()}, ■hpt{setvbuf()}, ■hpt{sprintf()},
  827.     ■hpt{sscanf()}, ■hpt{tmpfile()}, ■hpt{tmpnam()}, ■hpt{ungetc()},
  828.     ■hpt{vfprintf()}, ■hpt{vprintf()}, ■hpt{vsprintf()}.
  829.  
  830.     POSIX.1 functions: ■hpt{fdopen()}, ■hpt{fileno()}.
  831.  
  832.     POSIX.2 functions: ■hpt{pclose()}, ■hpt{popen()}.
  833.  
  834.     Additional functions: ■hpt{cuserid()}, ■hpt{_fassign()},
  835.     ■hpt{fcloseall()}, ■hpt{fgetchar()}, ■hpt{flushall()},
  836.     ■hpt{fputchar()}, ■hpt{_fseek_hdr()}, ■hpt{_fsetmode()},
  837.     ■hpt{_fsopen()}, ■hpt{getw()}, ■hpt{_mfclose()}, ■hpt{_mfopen()},
  838.     ■hpt{putw()}, ■hpt{setbuffer()}, ■hpt{snprintf()},
  839.     ■hpt{tempnam()}, ■hpt{vfscanf()}, ■hpt{vscanf()},
  840.     ■hpt{vsnprintf()}, ■hpt{vsscanf()}.
  841.  
  842. ■item <stdlib.h>
  843.  
  844.     Various library functions and global variables.  Includes <malloc.h>.
  845.  
  846.     C90 string conversion functons: ■hpt{atof()}, ■hpt{atoi()},
  847.     ■hpt{atol()}, ■hpt{strtod()}, ■hpt{strtol()}, ■hpt{strtoul()}.
  848.  
  849.     C90 functions for generating pseudo-random sequences:
  850.     ■hpt{rand()}, ■hpt{srand()}.
  851.  
  852.     C90 memory management functions: ■hpt{calloc()}, ■hpt{free()},
  853.     ■hpt{malloc()}, ■hpt{realloc()}.
  854.  
  855.     C90 functions for searching and sorting: ■hpt{bsearch()},
  856.     ■hpt{qsort()}.
  857.  
  858.     C90 integer arithmetic functions: ■hpt{abs()}, ■hpt{div()},
  859.     ■hpt{labs()}, ■hpt{ldiv()}.
  860.  
  861.     C90 multibyte character functions: ■hpt{mblen()},
  862.     ■hpt{mbstowcs()}, ■hpt{mbtowc()}, ■hpt{wcstombs()},
  863.     ■hpt{wctomb()}.
  864.  
  865.     Other C90 functions: ■hpt{abort()}, ■hpt{atexit()}, ■hpt{exit()},
  866.     ■hpt{getenv()}, ■hpt{system()}.
  867.  
  868.     String conversion functions proposed for C9X: ■hpt{strtof()},
  869.     ■hpt{strtold()}.
  870.  
  871.     Additional string conversion functions (to and from strings):
  872.     ■hpt{_atofl()}, ■hpt{_atoll()}, ■hpt{gcvt()}, ■hpt{_itoa()},
  873.     ■hpt{_lltoa()}, ■hpt{_ltoa()}, ■hpt{_strtoll()},
  874.     ■hpt{_strtoull()}, ■hpt{_ulltoa()}, ■hpt{_ultoa()}.
  875.  
  876.     Additional functions for generating pseudo-random sequences:
  877.     ■tt{initstate()}, ■tt{random()}, ■tt{setstate()}, ■tt{srandom()}.
  878.  
  879.     Additional memory management functions: ■hpt{brk()},
  880.     ■hpt{_expand()}, ■hpt{_heapchk()}, ■hpt{_heapmin()},
  881.     ■hpt{_heapset()}, ■hpt{_msize()}, ■hpt{sbrk()}.
  882.  
  883.     Additional functions for allocating tiled memory:
  884.     ■hpt{_tcalloc()}, ■hpt{_tfree()}, ■hpt{_tmalloc()},
  885.     ■hpt{_trealloc()}.
  886.  
  887.     Additional functions for searching and sorting: ■tt{heapsort()}.
  888.  
  889.     Additional integer arithmetic functions: ■hpt{_lldiv()},
  890.     ■hpt{_uldiv()}, ■hpt{_ulldiv()}.
  891.  
  892.     Additional functions for managing directories and disk drives:
  893.     ■hpt{chdir()}, ■hpt{_chdir2()}, ■hpt{_chdrive()},
  894.     ■hpt{_filesys()}, ■hpt{getcwd()}, ■hpt{_getcwd1()},
  895.     ■hpt{_getcwd2()}, ■hpt{_getvol()}, ■hpt{getwd()}, ■hpt{mkdir()},
  896.     ■hpt{rmdir()}.
  897.  
  898.     Additional functions for processing file names: ■hpt{_abspath()},
  899.     ■hpt{_defext()}, ■hpt{_fncmp()}, ■hpt{_fnexplode()},
  900.     ■hpt{_fnexplodefree()}, ■hpt{_fngetdrive()}, ■hpt{_fnisabs()},
  901.     ■hpt{_fnisrel()}, ■hpt{_fnlwr()}, ■hpt{_fnlwr2()},
  902.     ■hpt{_fnslashify()}, ■hpt{_fullpath()}, ■hpt{_getdrive()},
  903.     ■hpt{_getext()}, ■hpt{_getext2()}, ■hpt{_getname()},
  904.     ■hpt{_makepath()}, ■hpt{_path()}, ■hpt{_remext()},
  905.     ■hpt{_rfnlwr()}, ■hpt{_sfnlwr()}, ■hpt{_splitpath()}.
  906.  
  907.     Additional functions for multithread programs:
  908.     ■hpt{_beginthread()}, ■hpt{_endthread()}, ■hpt{_gettid()},
  909.     ■hpt{_threadstore()}.
  910.  
  911.     Additional functions for managing the command line:
  912.     ■hpt{_envargs()}, ■hpt{_response()}, ■hpt{_wildcard()}.
  913.  
  914.     Miscellaneous additional functions: ■hpt{alarm()}, ■hpt{_core()},
  915.     ■hpt{_execname()}, ■hpt{_exit()}, ■hpt{getpagesize()},
  916.     ■hpt{_getsockhandle()}, ■hpt{perror()}, ■hpt{putenv()},
  917.     ■hpt{_read_kbd()}, ■hpt{_scrsize()}, ■hpt{_searchenv()},
  918.     ■hpt{_setsyserrno()}, ■hpt{sleep()}, ■hpt{_sleep2()},
  919.     ■hpt{_splitargs()}, ■hpt{swab()}, ■hpt{_swchar()},
  920.     ■hpt{_syserrno()}, ■hpt{ulimit()}.
  921.  
  922. ■item <string.h>
  923.  
  924.     This header declares functions for processing null-terminated
  925.     strings and for processing arrays of characters and objects
  926.     treated as arrays of characters.
  927.  
  928.     C90 functions for processing null-terminated strings:
  929.     ■hpt{strcat()}, ■hpt{strchr()}, ■hpt{strcmp()}, ■hpt{strcoll()},
  930.     ■hpt{strcpy()}, ■hpt{strcspn()}, ■hpt{strerror()}, ■hpt{strlen()},
  931.     ■hpt{strncat()}, ■hpt{strncmp()}, ■hpt{strncpy()},
  932.     ■hpt{strpbrk()}, ■hpt{strrchr()}, ■hpt{strspn()}, ■hpt{strstr()},
  933.     ■hpt{strtok()}, ■hpt{strxfrm()}.
  934.  
  935.     C90 functions for processing arrays of characters:
  936.     ■hpt{memchr()}, ■hpt{memcmp()}, ■hpt{memcpy()}, ■hpt{memmove()},
  937.     ■hpt{memset()}.
  938.  
  939.     Non-standard functions for processing null-terminated strings:
  940.     ■hpt{strdup()}, ■hpt{stricmp()}, ■hpt{strlwr()}, ■hpt{_strncpy()},
  941.     ■hpt{strnicmp()}, ■hpt{strnset()}, ■hpt{strrev()}, ■tt{strsep()},
  942.     ■hpt{strset()}, ■hpt{strupr()}.
  943.  
  944.     Non-standard functions for processing arrays of characters:
  945.     ■hpt{memccpy()}, ■hpt{_memcount()}, ■hpt{_memdif()},
  946.     ■hpt{memicmp()}, ■hpt{_memrchr()}, ■hpt{_memswap()}.
  947.  
  948. ■item <strings.h>
  949.  
  950.     This header defines the BSD string and memory functions and
  951.     includes <string.h>.
  952.  
  953.     BSD functions: ■hpt{bcmp()}, ■hpt{bcopy()}, ■hpt{bzero()},
  954.     ■hpt{ffs()}, ■hpt{index()}, ■hpt{rindex()}.
  955.  
  956. ■item <termcap.h>
  957.  
  958.     Terminal data base (FSF).
  959.  
  960. ■item <termio.h>
  961.  
  962.     Defines ■tt{struct termio} and constants for the ■hpt{general
  963.     terminal interface} (System V variant).  Includes <sys/termio.h>.
  964.  
  965. ■item <termios.h>
  966.  
  967.     Declares functions and defines ■tt{struct termios} and constants
  968.     for the ■hpt{general terminal interface} (POSIX.1 variant).
  969.  
  970.     POSIX.1 functions: ■hpt{cfgetispeed()}, ■hpt{cfgetospeed()},
  971.     ■hpt{cfsetispeed()}, ■hpt{cfsetospeed()}, ■hpt{tcdrain()},
  972.     ■hpt{tcflow()}, ■hpt{tcflush()}, ■hpt{tcgetattr()},
  973.     ■hpt{tcsendbreak()}, ■hpt{tcsetattr()}.
  974.  
  975. ■item <time.h>
  976.  
  977.     Functions and structures for converting time values between
  978.     various formats.
  979.  
  980.     C90 functions: ■hpt{asctime()}, ■hpt{ctime()}, ■hpt{clock()},
  981.     ■hpt{difftime()}, ■hpt{gmtime()}, ■hpt{localtime()},
  982.     ■hpt{mktime()}, ■hpt{strftime()}, ■hpt{time()}.
  983.  
  984.     POSIX.1 functions: ■hpt{tzset()}.
  985.  
  986.     Additional functions: ■hpt{strptime()}.
  987.  
  988. ■item <ulimit.h>
  989.  
  990.     Declares the ■hpt{ulimit()} function and defines constants for
  991.     ulimit().
  992.  
  993. ■item <umalloc.h>
  994.  
  995.     Declares heap-specific functions for dynamic memory allocation.
  996.     See ■hpt{_ucreate2()} for details.
  997.  
  998.     Functions for allocating memory: ■hpt{_ucalloc()},
  999.     ■hpt{_umalloc()}.
  1000.  
  1001.     Functions for allocating tiled memory: ■hpt{_utcalloc()},
  1002.     ■hpt{_utmalloc()}.
  1003.  
  1004.     Functions for maintaining heaps: ■hpt{_theapmin()},
  1005.     ■hpt{_uaddmem()}, ■hpt{_uclose()}, ■hpt{_ucreate()}
  1006.     ■hpt{_ucreate2()}, ■hpt{_udefault()}, ■hpt{_udestroy()},
  1007.     ■hpt{_uheapchk()}, ■hpt{_uheapmin()}, ■hpt{_uheapset()},
  1008.     ■hpt{_uopen()}, ■hpt{_utdefault()}.
  1009.  
  1010.     Functions for getting information about blocks and heaps:
  1011.     ■hpt{_mheap()}, ■hpt{_uheap_type()}, ■hpt{_uheap_walk()},
  1012.     ■hpt{_uheap_walk2()}, ■hpt{_ustats()}.
  1013.  
  1014.     Functions declared in <malloc.h> which can also be used on blocks
  1015.     allocated by heap-specific functions: ■hpt{_expand()},
  1016.     ■hpt{free()}, ■hpt{_msize()}, ■hpt{realloc()}.
  1017.  
  1018. ■item <unistd.h>
  1019.  
  1020.     Various POSIX.1-related definitions and declarations.
  1021.  
  1022.     POSIX.1 functions: ■hpt{access()}, ■hpt{alarm()}, ■hpt{chdir()},
  1023.     ■hpt{close()}, ■hpt{cuserid()}, ■hpt{dup()}, ■hpt{dup2()},
  1024.     ■hpt{execl()}, ■hpt{execle()}, ■hpt{execlp()}, ■hpt{execv()},
  1025.     ■hpt{execve()}, ■hpt{execvp()}, ■hpt{_exit()}, ■hpt{fork()},
  1026.     ■hpt{fpathconf()}, ■hpt{getcwd()}, ■tt{getegid()}, ■tt{geteuid()},
  1027.     ■tt{getgid()}, ■tt{getgroups()}, ■tt{getlogin()}, ■tt{getpgrp()},
  1028.     ■hpt{getpid()}, ■hpt{getppid()}, ■tt{getuid()}, ■hpt{isatty()},
  1029.     ■hpt{lseek()}, ■hpt{pathconf()}, ■hpt{pause()}, ■hpt{pipe()},
  1030.     ■hpt{read()}, ■hpt{rmdir()}, ■tt{setgid()}, ■tt{setpgid()},
  1031.     ■tt{setsid()}, ■tt{setuid()}, ■hpt{sleep()}, ■hpt{sysconf()},
  1032.     ■tt{tcgetpgrp()}, ■tt{tcsetpgrp()}, ■hpt{ttyname()},
  1033.     ■hpt{unlink()}, ■hpt{write()}.
  1034.  
  1035.     POSIX.2 functions: ■hpt{getopt()}.
  1036.  
  1037.     Additional functions: ■hpt{brk()}, ■hpt{getpass()},
  1038.     ■hpt{_getpass1()}, ■hpt{_getpass2()}, ■hpt{mkstemp()},
  1039.     ■hpt{mktemp()}, ■hpt{profil()}, ■hpt{sbrk()}.
  1040.  
  1041. ■item <utime.h>
  1042.  
  1043.     Declares ■hpt{utime()} and defines ■tt{struct utimbuf}.  Includes
  1044.     <sys/utime.h>.
  1045.  
  1046. ■item <varargs.h>
  1047.  
  1048.     Functions with variable number of arguments -- traditional Unix
  1049.     version.  New programs should use <stdarg.h> instead of
  1050.     <varargs.h>, therefore the macros of <varargs.h> are not
  1051.     documented here.
  1052.  
  1053. ■item <emx/bigint.h>
  1054.  
  1055.     Internal header file for the implementation of decimal to binary
  1056.     and binary to decimal conversions of floating point numbers.
  1057.     Application programs should never include this header -- it's used
  1058.     for library modules only.
  1059.  
  1060. ■item <emx/float.h>
  1061.  
  1062.     Internal header file for the implementation of floating point
  1063.     math.  Application programs should never include this header --
  1064.     it's used for library modules only.
  1065.  
  1066. ■item <emx/io.h>
  1067.  
  1068.     Internal header file for the implementation of low-level I/O and
  1069.     stream I/O.  Application programs should never include this header
  1070.     -- it's used for library modules only.
  1071.  
  1072. ■item <emx/nls.h>
  1073.  
  1074.     Internal header file for the implementation of some functions of
  1075.     <sys/nls.h>.  Application programs should never include this header --
  1076.     it's used for library modules only.
  1077.  
  1078. ■item <emx/pwd.h>
  1079.  
  1080.     Internal header file for the implementation of some functions of
  1081.     <pwd.h>.  Application programs should never include this header --
  1082.     it's used for library modules only.
  1083.  
  1084. ■item <emx/startup.h>
  1085.  
  1086.     Internal header file for the implementation of startup and cleanup
  1087.     code.  Application programs should never include this header --
  1088.     it's used for library modules only.
  1089.  
  1090. ■item <emx/syscalls.h>
  1091.  
  1092.     Declare emx syscall functions and defines constants and types for
  1093.     emx syscalls.  Application programs should never include this
  1094.     header -- it's used for library modules only.
  1095.  
  1096. ■item <emx/thread.h>
  1097.  
  1098.     Internal header file for the implementation of thread-local
  1099.     variables used by library functions.  Application programs should
  1100.     never include this header -- it's used for library modules only.
  1101.  
  1102. ■item <emx/time.h>
  1103.  
  1104.     Internal header file for the implementation of time-related
  1105.     library functions.  Application programs should never include this
  1106.     header -- it's used for library modules only.
  1107.  
  1108. ■item <emx/umalloc.h>
  1109.  
  1110.     Internal header file for the implementation of malloc().
  1111.     Application programs should never include this header -- it's used
  1112.     for library modules only.
  1113.  
  1114. ■item <sys/builtin.h>
  1115.  
  1116.     Defines inline assembly functions for some low-level tasks.
  1117.     Several of these functions are provided for compatibility with
  1118.     functions declared in the ■tt{<builtin.h>} header of IBM's Visual
  1119.     Age C++ 3.0 compiler (VAC++).
  1120.  
  1121.     Functions for RAM semaphores: ■hpt{__cxchg()}, ■hpt{__lxchg()},
  1122.     ■hpt{__sxchg()}.
  1123.  
  1124.     Functions for disabling and enabling interrupts:
  1125.     ■hpt{__disable()}, ■hpt{__enable()}.
  1126.  
  1127.     Functions for bit operations: ■hpt{_crotl()}, ■hpt{_crotr()},
  1128.     ■hpt{__fls()}, ■hpt{_lrotl()}, ■hpt{_lrotr()}, ■hpt{_srotl()},
  1129.     ■hpt{_srotr()}.
  1130.  
  1131. ■item <sys/dir.h>
  1132.  
  1133.     Prerequisite header: <sys/types.h>You should use <dirent.h>
  1134.     instead of <sys/dir.h>.
  1135.  
  1136.     Functions: ■hpt{closedir()}, ■hpt{readdir()}, ■hpt{rewinddir()},
  1137.     ■hpt{opendir()}, ■hpt{seekdir()}, ■hpt{telldir()}.
  1138.  
  1139. ■item <sys/dirent.h>
  1140.  
  1141.     Defines ■tt{struct dirent} and associated constants.  This header
  1142.     file is used by <dirent.h>, you don't have to include <sys/dirent.h>
  1143.     yourself.
  1144.  
  1145. ■item <sys/dirtree.h>
  1146.  
  1147.     Declares the emx directory tree functions and defines associated
  1148.     constants and types.
  1149.  
  1150.     Functions: ■hpt{_dt_free()}, ■hpt{_dt_read()}, ■hpt{_dt_sort()},
  1151.     ■hpt{_dt_split()}.
  1152.  
  1153. ■item <sys/ea.h>
  1154.  
  1155.     Defines ■tt{struct _ea} and declares the emx functions for
  1156.     low-level extended attributes handling.  See also <sys/ead.h> --
  1157.     don't confuse these two different approaches to extended
  1158.     attributes.
  1159.  
  1160.     Functions: ■hpt{_ea_free()}, ■hpt{_ea_get()}, ■hpt{_ea_put()},
  1161.     ■hpt{_ea_remove()}.
  1162.  
  1163. ■item <sys/ead.h>
  1164.  
  1165.     Declares the _ead type and the emx functions for high-level
  1166.     extended attributes handling via `EA descriptors'.  See also also
  1167.     <sys/ea.h> -- don't confuse these two different approaches to
  1168.     extended attributes.
  1169.  
  1170.     Functions: ■hpt{_ead_add()}, ■hpt{_ead_clear()},
  1171.     ■hpt{_ead_copy()}, ■hpt{_ead_count()}, ■hpt{_ead_create()},
  1172.     ■hpt{_ead_delete()}, ■hpt{_ead_destroy()},
  1173.     ■hpt{_ead_fea2list_size()}, ■hpt{_ead_fea2list_to_fealist()},
  1174.     ■hpt{_ead_fealist_to_fea2list()}, ■hpt{_ead_find()},
  1175.     ■hpt{_ead_get_fea2list()}, ■hpt{_ead_get_flags()},
  1176.     ■hpt{_ead_get_name()}, ■hpt{_ead_get_value()},
  1177.     ■hpt{_ead_name_len()}, ■hpt{_ead_read()}, ■hpt{_ead_replace()},
  1178.     ■hpt{_ead_sort()}, ■hpt{_ead_use_fea2list()},
  1179.     ■hpt{_ead_value_size()}, ■hpt{_ead_write()}.
  1180.  
  1181. ■item <sys/emxload.h>
  1182.  
  1183.     Declares functions for keeping programs in memory with
  1184.     ■tt{emxload.exe}.
  1185.  
  1186.     Functions: ■hpt{_emxload_env()}, ■hpt{_emxload_this()},
  1187.     ■hpt{_emxload_prog()}, ■hpt{_emxload_unload()},
  1188.     ■hpt{_emxload_list_start()}, ■hpt{_emxload_list_get()},
  1189.     ■hpt{_emxload_connect()}, ■hpt{_emxload_disconnect()},
  1190.     ■hpt{_emxload_stop()}.
  1191.  
  1192. ■item <sys/fcntl.h>
  1193.  
  1194.     Defines file mode constants such as O_RDONLY and other constants.
  1195.     Declares the ■hpt{fcntl()} and ■hpt{flock()} functions.  You
  1196.     should include <fcntl.h> instead.
  1197.  
  1198. ■item <sys/file.h>
  1199.  
  1200.     This header is provided for compatibility with Unix systems
  1201.     -- it includes <sys/fcntl.h>.
  1202.  
  1203. ■item <sys/fmutex.h>
  1204.  
  1205.     Prerequisite header: <sys/builtin.h>
  1206.  
  1207.     This header contains definitions and declarations for _fmutex
  1208.     semaphores.  _fmutex semaphores are fast RAM semaphores which
  1209.     control access to a resources shared by threads or processes.  See
  1210.     `■hpt{_fmutex semaphores}' for details.
  1211.  
  1212.     Functions: ■hpt{_fmutex_available()},
  1213.     ■hpt{_fmutex_checked_close()}, ■hpt{_fmutex_checked_create()},
  1214.     ■hpt{_fmutex_checked_open()}, ■hpt{_fmutex_checked_release()},
  1215.     ■hpt{_fmutex_checked_request()}, ■hpt{_fmutex_close()},
  1216.     ■hpt{_fmutex_create()}, ■hpt{_fmutex_dummy()},
  1217.     ■hpt{_fmutex_open()}, ■hpt{_fmutex_release()},
  1218.     ■hpt{_fmutex_request()}.
  1219.  
  1220. ■item <sys/hw.h>
  1221.  
  1222.     Declares the emx port access and memory access functions.
  1223.  
  1224.     Function: ■hpt{_inp8()}, ■hpt{_inp16()}, ■hpt{_inp32()},
  1225.     ■hpt{_inps8()}, ■hpt{_inps16()}, ■hpt{_inps32()},
  1226.     ■hpt{_memaccess()}, ■hpt{_outp8()}, ■hpt{_outp16()},
  1227.     ■hpt{_outp32()}, ■hpt{_outps8()}, ■hpt{_outps16()},
  1228.     ■hpt{_outps32()}, ■tt{_outpt()}, ■hpt{_outps8dac()},
  1229.     ■hpt{_portaccess()}, ■hpt{_wait0()}, ■hpt{_wait01()},
  1230.     ■hpt{_wait1()}, ■hpt{_wait10()}.
  1231.  
  1232. ■item <sys/ioctl.h>
  1233.  
  1234.     Declares the ■hpt{ioctl()} function and defines various constants
  1235.     to be used with ioctl().  This header includes <sys/so_ioctl.h> if
  1236.     a TCP/IP-related header such as <sys/socket.h> has been included
  1237.     before <sys/ioctl.h>.
  1238.  
  1239. ■item <sys/ipc.h>
  1240.  
  1241.     This header contains some definitions for System V IPC
  1242.     facilities.  However, these are not yet implemented in emx.
  1243.  
  1244. ■item <sys/kbdscan.h>
  1245.  
  1246.     Defines keyboard scan codes.
  1247.  
  1248. ■item <sys/moddef.h>
  1249.  
  1250.     Declares types and functions for reading module definition files.
  1251.  
  1252.     Functions: ■hpt{_md_close()}, ■hpt{_md_errmsg()},
  1253.     ■hpt{_md_get_linenumber()}, ■hpt{_md_get_number()},
  1254.     ■hpt{_md_get_string()}, ■hpt{_md_get_token()},
  1255.     ■hpt{_md_next_token()}, ■hpt{_md_open()}, ■hpt{_md_parse()},
  1256.     ■hpt{_md_use_file()}.
  1257.  
  1258. ■item <sys/msg.h>
  1259.  
  1260.     This header contains some definitions for System V message
  1261.     queues.  However, these are not yet implemented in emx.
  1262.  
  1263. ■item <sys/nls.h>
  1264.  
  1265.     Declares the emx national-language support functions and macros.
  1266.  
  1267.     Functions: ■hpt{_nls_init()}, ■hpt{_nls_strlwr()},
  1268.     ■hpt{_nls_strupr()}.
  1269.  
  1270.     Macros: ■hpt{_nls_tolower()}, ■hpt{_nls_toupper()},
  1271.     ■hpt{_nls_is_dbcs_lead()}.
  1272.  
  1273. ■item <sys/param.h>
  1274.  
  1275.     Defines constants such as MAXNAMLEN which describe system
  1276.     parameters.
  1277.  
  1278. ■item <sys/process.h>
  1279.  
  1280.     Process handling.  Application programs should include <process.h>
  1281.     instead.  See <process.h> for details.
  1282.  
  1283. ■item <sys/ptrace.h>
  1284.  
  1285.     Declares the ■hpt{ptrace()} function and defines associated
  1286.     constants.
  1287.  
  1288. ■item <sys/reg.h>
  1289.  
  1290.     Defines register offset constants.  These are usually used with
  1291.     ■hpt{ptrace()} and for reading core dump files.
  1292.  
  1293. ■item <sys/resource.h>
  1294.  
  1295.     This header is empty.
  1296.  
  1297. ■item <sys/rmutex.h>
  1298.  
  1299.     Prerequisite headers: <sys/builtin.h>, <sys/fmutex.h>
  1300.  
  1301.     This header contains definitions and declarations for _rmutex
  1302.     semaphores.  _rmutex semaphores are registered _fmutex semaphores.
  1303.     See `■hpt{_fmutex semaphores}' for details.
  1304.  
  1305.     Functions: ■hpt{_rmutex_available()},
  1306.     ■hpt{_rmutex_checked_close()}, ■hpt{_rmutex_checked_create()},
  1307.     ■hpt{_rmutex_checked_open()}, ■hpt{_rmutex_checked_release()},
  1308.     ■hpt{_rmutex_checked_request()}, ■hpt{_rmutex_close()},
  1309.     ■hpt{_rmutex_create()}, ■hpt{_rmutex_dummy()},
  1310.     ■hpt{_rmutex_open()}, ■hpt{_rmutex_release()},
  1311.     ■hpt{_rmutex_request()}.
  1312.  
  1313. ■item <sys/select.h>
  1314.  
  1315.     Defines the fd_set type and macros (FD_SET etc.) for ■hpt{select()}.
  1316.  
  1317. ■item <sys/signal.h>
  1318.  
  1319.     Functions and constants for signal processing.  Application
  1320.     programs should include <signal.h> instead.
  1321.  
  1322. ■item <sys/smutex.h>
  1323.  
  1324.     Prerequisite header: <sys/builtin.h>
  1325.  
  1326.     This header contains definitions and declarations for _smutex
  1327.     semaphores.  _smutex semaphores are very simple RAM semaphores
  1328.     which control access to a resources shared by threads or
  1329.     processes.  See `■hpt{_smutex semaphores}' for details.
  1330.  
  1331.     Functions: ■hpt{_smutex_available()}, ■hpt{_smutex_release()},
  1332.     ■hpt{_smutex_request()}.
  1333.  
  1334. ■item <sys/socket.h>
  1335.  
  1336.     Definitions and declarations related to sockets.
  1337.  
  1338. ■item <sys/so_ioctl.h>
  1339.  
  1340.     Socket-specific definitions for ioctl().  This header is
  1341.     automatically included by <sys/ioctl.h> if a TCP/IP-related header
  1342.     such as <sys/socket.h> has been included before <sys/ioctl.h>.
  1343.  
  1344. ■item <sys/stat.h>
  1345.  
  1346.     Prerequisite header: <sys/types.h>
  1347.  
  1348.     Defines ■tt{struct stat} for ■hpt{stat()} and ■hpt{fstat()}.
  1349.     Defines S_IREAD, S_IWRITE and S_IEXEC for ■hpt{open()}.  Defines
  1350.     S_IFCHR etc. constants and S_ISCHR etc. macros for checking file
  1351.     types.  Declares the stat() and fstat() functions.
  1352.  
  1353. ■item <sys/statfs.h>
  1354.  
  1355.     Declares ■tt{struct statfs} -- which is not yet supported by emx.
  1356.  
  1357. ■item <sys/termio.h>
  1358.  
  1359.     Defines ■tt{struct termio} and constants for the ■hpt{general
  1360.     terminal interface} (System V variant).
  1361.  
  1362. ■item <sys/time.h>
  1363.  
  1364.     Declares ■hpt{utimes()}, ■hpt{gettimeofday()} and
  1365.     ■hpt{settimeofday()}.
  1366.  
  1367. ■item <sys/timeb.h>
  1368.  
  1369.     Declares ■hpt{ftime()} and defines ■tt{struct timeb}.
  1370.  
  1371. ■item <sys/times.h>
  1372.  
  1373.     Prerequisite header: <time.h>
  1374.  
  1375.     Declares ■hpt{times()} and defines ■tt{struct tms}.
  1376.  
  1377. ■item <sys/types.h>
  1378.  
  1379.     Defines various types such as ino_t for <sys/stat.h>.  Defines the
  1380.     fd_set type and macros (FD_SET etc.) for ■hpt{select()}.
  1381.  
  1382. ■item <sys/uio.h>
  1383.  
  1384.     Declares ■tt{struct iovec} and the ■tt{readv()} and ■tt{writev()}
  1385.     functions.
  1386.  
  1387. ■item <sys/uflags.h>
  1388.  
  1389.     Declares the ■hpt{_uflags()} function and constants for _uflags().
  1390.  
  1391. ■item <sys/user.h>
  1392.  
  1393.     Declares ■tt{struct user} which is used by ■hpt{ptrace()} and in
  1394.     core dump files.  See also <sys/reg.h> and <sys/ptrace.h>.
  1395.  
  1396. ■item <sys/utime.h>
  1397.  
  1398.     Declares ■hpt{utime()} and defines ■tt{struct utimbuf}.  You
  1399.     should include <utime.h> instead.
  1400.  
  1401. ■item <sys/utsname.h>
  1402.  
  1403.     Declares ■hpt{uname()} and defines ■tt{struct utsname}.
  1404.  
  1405. ■item <sys/video.h>
  1406.  
  1407.     Declares the emx video library functions and defines associated
  1408.     constants.
  1409.  
  1410.     Functions: ■hpt{v_attrib()}, ■hpt{v_backsp()}, ■hpt{v_clear()},
  1411.     ■hpt{v_clreol()}, ■hpt{v_ctype()}, ■hpt{v_delline()},
  1412.     ■hpt{v_dimen()}, ■hpt{v_fclose()}, ■hpt{v_fopen()},
  1413.     ■hpt{v_getattr()}, ■hpt{v_getctype()}, ■hpt{v_getline()},
  1414.     ■hpt{v_getxy()}, ■hpt{v_gotoxy()}, ■hpt{v_hardware()},
  1415.     ■hpt{v_hidecursor()}, ■hpt{v_init()}, ■hpt{v_insline()},
  1416.     ■hpt{v_putc()}, ■hpt{v_putline()}, ■hpt{v_putm()},
  1417.     ■hpt{v_putmask()}, ■hpt{v_putn()}, ■hpt{v_puts()},
  1418.     ■hpt{v_scroll()}, ■hpt{v_scrollup()}, ■hpt{v_printf()},
  1419.     ■hpt{v_vprintf()}.
  1420.  
  1421. ■item <sys/wait.h>
  1422.  
  1423.     Declares ■hpt{wait()} and ■hpt{waitpid()}.  Defines constants and
  1424.     macros for using these functions.
  1425.  
  1426. ■item <sys/winmgr.h>
  1427.  
  1428.     Declares the emx window manager library functions and the
  1429.     wm_handle type.  Defines window manager constants.
  1430.  
  1431.     Functions for mangaging windows: ■hpt{wm_border()},
  1432.     ■hpt{wm_bottom()}, ■hpt{wm_close()}, ■hpt{wm_close_all()},
  1433.     ■hpt{wm_create()}, ■hpt{wm_delete()}, ■hpt{wm_dimen()},
  1434.     ■hpt{wm_down()}, ■hpt{wm_exit()}, ■hpt{wm_find()},
  1435.     ■hpt{wm_get_pos()}, ■hpt{wm_init()}, ■hpt{wm_move()},
  1436.     ■hpt{wm_open()}, ■hpt{wm_top()}, ■hpt{wm_up()}, ■hpt{wm_update()}.
  1437.  
  1438.     Functions for managing the cursor: ■hpt{wm_chide()},
  1439.     ■hpt{wm_ctype()}, ■hpt{wm_cursor()}, ■hpt{wm_cvis()},
  1440.     ■hpt{wm_get_cursor()}, ■hpt{wm_getx()}, ■hpt{wm_getxy()},
  1441.     ■hpt{wm_gety()}, ■hpt{wm_gotoxy()}.
  1442.  
  1443.     Functions for scrolling: ■hpt{wm_del_char()}, ■hpt{wm_del_line()},
  1444.     ■hpt{wm_ins_char()}, ■hpt{wm_ins_line()}, ■hpt{wm_scroll()},
  1445.  
  1446.     Functions for output to a window: ■hpt{wm_attrib()},
  1447.     ■hpt{wm_attrib_all()}, ■hpt{wm_backsp()}, ■hpt{wm_clear()},
  1448.     ■hpt{wm_clr_eol()}, ■hpt{wm_fclose()}, ■hpt{wm_fopen()},
  1449.     ■hpt{wm_get_attrib()}, ■hpt{wm_printf()}, ■hpt{wm_puta_at()},
  1450.     ■hpt{wm_putc()}, ■hpt{wm_putc_at()}, ■hpt{wm_putca()},
  1451.     ■hpt{wm_putca_at()}, ■hpt{wm_puts()}, ■hpt{wm_puts_at()},
  1452.     ■hpt{wm_putsa()}, ■hpt{wm_putsa_at()}, ■hpt{wm_vprintf()},
  1453.     ■hpt{wm_wrap()}.
  1454.  
  1455. ■endlist
  1456.  
  1457. ■h1 Dynamic memory allocation
  1458.  
  1459.   Dynamic memory allocation means allocation of objects at runtime
  1460.   where the lifetime of the objects is independent of the nesting of
  1461.   blocks and functions.
  1462.  
  1463. ■ipfminitoc
  1464.  
  1465. ■h2 Allocating blocks
  1466.  
  1467.   The ■hpt{malloc()} function is used to dynamically allocate an
  1468.   object.  You pass the size of the object to malloc() and malloc will
  1469.   return a pointer to a block of memory allocated from a heap.  The
  1470.   contents of the block are indeterminate.  If you need a block of
  1471.   memory initialized to zeros, use the ■hpt{calloc()} function.
  1472.   calloc() takes two arguments: the number of objects and the size of
  1473.   one object.  The size of the block is the product of the two
  1474.   numbers.  Using calloc() can be more efficient than calling malloc()
  1475.   and zeroing the block with memset() because calloc() can avoid
  1476.   zeroing the block if it knows that it already is zeroed.
  1477.  
  1478. ■h2 Deallocating (freeing) blocks
  1479.  
  1480.   When you no longer need the object, you can deallocate it by passing
  1481.   a pointer to the object to the ■hpt{free()} function.  After
  1482.   deallocating a block, you must no longer use the block.  (Strictly,
  1483.   you are even no longer allowed to use the pointer to the block.)
  1484.   The memory block can be reused later by malloc() etc. for other
  1485.   dynamically allocated objects.
  1486.  
  1487. ■h2 Resizing blocks
  1488.  
  1489.   The size of blocks allocated with malloc() etc. can be changed with
  1490.   the ■hpt{realloc()} function.  Quite often, the size of a block
  1491.   cannot be changed in place, that is, the block must be moved to
  1492.   another location in the heap.  Therefore, realloc() returns a
  1493.   pointer to the new location of block, which might happen to be equal
  1494.   to the old one.
  1495.  
  1496.   The ■hpt{_expand()} function attempts to resize a block in place,
  1497.   that is, without moving it.  In most cases, blocks cannot be resized
  1498.   in place.  If resizing the block fails, _expand() does not move the
  1499.   block to another location.
  1500.  
  1501. ■h2 ISO 9899 standard
  1502.  
  1503.   Whenever possible, you should use only calloc(), free(), malloc(),
  1504.   and realloc() for dynamic memory allocation.  All other functions
  1505.   described here are not defined by the ISO standard for the C
  1506.   programming language.
  1507.  
  1508. ■h2 Tiled memory
  1509.  
  1510.   16-bit OS/2 API functions have special requirements for the
  1511.   alignment of objects.  A `tiled' object is an object which meets
  1512.   these requirements.  The ■hpt{_tmalloc()} function dynamically
  1513.   allocates a tiled object from the tiled default heap.  The
  1514.   ■hpt{_tcalloc()} function allocates a tiled object initialized to
  1515.   zeros.  The ■hpt{_trealloc()} function resizes a tiled object -- the
  1516.   object will remain tiled.  The ■hpt{_tfree()} function deallocates a
  1517.   tiled object allocated with _tmalloc() or _tcalloc().
  1518.  
  1519. ■h2 Multiple heaps
  1520.  
  1521.   The emx C library maintains a runtime heap, from which malloc()
  1522.   allocates by default and a tiled runtime heap, from which _tmalloc()
  1523.   allocates by default.  (These two runtime heaps happen to be
  1524.   identical in the current implementation, so there's in fact only one
  1525.   runtime heap.)
  1526.  
  1527.   However, you can create your own heaps in addition to the runtime
  1528.   heaps.  The interface to multiple heaps is more or less compatible
  1529.   to the one of IBM's Visual Age C++ compiler.  Definitions and
  1530.   declarations for using multiple heaps are in the <umalloc.h> header.
  1531.  
  1532.   To create a heap, you have to reserve a memory area for the heap.
  1533.   This memory area can be statically allocated, obtained with
  1534.   ■hpt{sbrk()}, obtained with DosAllocMem, or even allocated from
  1535.   another heap.  The ■hpt{_ucreate()} function creates a heap in the
  1536.   memory area you provide and returns a pointer to the new heap.
  1537.   Before using the new heap, you have to open the heap by calling
  1538.   ■hpt{_uopen()}.
  1539.  
  1540.   To allocate from a specific heap, call ■hpt{_umalloc()} instead of
  1541.   malloc(), passing a pointer to the heap as first argument.
  1542.   ■hpt{_ucalloc()} allocates a zero-initialized block from the heaü
  1543.   pointed to by the first argument.
  1544.  
  1545.   You can use realloc() to resize a block of any heap -- realloc()
  1546.   automatically determines from which heap the block has been
  1547.   allocated and will keep the block in that heap.  You can use free()
  1548.   to deallocate a block from any heap -- free() automatically
  1549.   determines from which heap the block has been allocated.
  1550.  
  1551.   If you no longer need a heap, you can close it with ■hpt{_uclose()}
  1552.   and then destroy it with ■hpt{_udestroy()}.  You are responsible for
  1553.   deallocating the memory area in which the heap was created; if you
  1554.   allocated the memory area with DosAllocMem, deallocate it with
  1555.   DosFreeMem.
  1556.  
  1557.   Note that only memory obtained with brk() and sbrk() is dumped into
  1558.   the core file.  Heaps in memory objects allocated with DosAllocMem
  1559.   are not visible when performing post-mortem debugging.
  1560.  
  1561. ■h2 Tiled heaps
  1562.  
  1563.   The ■hpt{_utmalloc()} function allocates a tiled object from a heap
  1564.   which is not tiled.  Objects allocated with ■hpt{_utmalloc()} can be
  1565.   resized with realloc() and can be dealllocated with free().
  1566.   ■hpt{_utcalloc()} allocates a tiled object initialized to zeros.
  1567.   Note that allocating tiled objects from a regular (untiled) heap may
  1568.   increase fragmentation of the heap.
  1569.  
  1570.   You can create a tiled heap by passing the _HEAP_TILED flag to
  1571.   _ucreate().  All objects allocated from a tiled heap are tiled
  1572.   objects.  Again, realloc() and free() can be used instead of
  1573.   _trealloc() and _tfree(), respectively.
  1574.  
  1575. ■h2 Default heaps
  1576.  
  1577.   The main thread and each thread created with ■hpt{_beginthread()}
  1578.   has its own two pointers to its two default heaps (regular and
  1579.   tiled), that is, different threads can have different default heaps.
  1580.   Do not confuse the default heaps of a thread with the runtime heaps;
  1581.   the runtime heaps are special heaps maintained by the C library.
  1582.   Initially, each thread has the runtime heap as its default heap and
  1583.   the tiled runtime heap as its tiled default heap.  (Note that the
  1584.   two runtime heaps happen to be identical in the current
  1585.   implementation, that is, the two heap pointers of a thread initially
  1586.   point to the same heap, the runtime heap.)
  1587.  
  1588.   For each thread, you can select a default heap with the
  1589.   ■hpt{_udefault()} function which takes a pointer to the heap to be
  1590.   used.  After selecting a default heap for a thread, all malloc()
  1591.   calls in that thread will allocate memory from the selected heap.
  1592.   You can switch back to the runtime heap by passing _RUNTIME_HEAP to
  1593.   _udefault(); _RUNTIME_HEAP is a pointer to the runtime heap.
  1594.  
  1595.   For each thread, you can select a tiled default heap with the
  1596.   ■hpt{_utdefault()} function which takes a pointer to the heap to be
  1597.   used.  After selecting a tiled default heap for a thread, all
  1598.   _tmalloc() calls in that thread will allocate memory from the
  1599.   selected heap.
  1600.  
  1601.   If a tiled heap is selected as default heap with _udefault(),
  1602.   malloc() always allocates tiled objects.
  1603.  
  1604. ■h2 Shared heaps
  1605.  
  1606.   Heaps created with _ucreate() can be shared between processes.  To
  1607.   create a shared heap, allocate shared memory with DosAllocSharedMem
  1608.   and pass the _HEAP_SHARED flag to _ucreate().  Each process (except
  1609.   the process which created the shared memory object) which wants to
  1610.   access such a shared heap must first obtain access to the shared
  1611.   memory allocated with DosAllocSharedMem.  This is done with
  1612.   DosGetNamedSharedMem, DosGetSharedMem, or DosGiveSharedMem.  Then,
  1613.   each process, including the process which created the heap, must
  1614.   obtain access to the heap.  This is done with _uopen().  _udefault()
  1615.   can be used to use a shared heap as default heap.
  1616.  
  1617.   If a shared heap is no longer needed by a process, that process
  1618.   should close the heap with _uclose() and relinquish access to the
  1619.   shared memory object with DosFreeMem.  After all processes,
  1620.   including the process which created the heap, have closed the heap
  1621.   with _uclose(), the heap can be destroyed with _udestroy().
  1622.  
  1623. ■h2 Checking heaps
  1624.  
  1625.   Heap corruption is a quite common problem of C programs.  To track
  1626.   down such errors, you can periodically call the ■hpt{_heapchk()}
  1627.   function to check the default heap and the tiled default heap of the
  1628.   current thread for consistency.  The ■hpt{_uheapchk()} function
  1629.   checks a specific heap.
  1630.  
  1631.   Sometimes, programs erroneously depend on the contents of
  1632.   dynamically allocated blocks.  To debug these problems, you can call
  1633.   ■hpt{_heapset()} to fill all bytes of all free blocks of the default
  1634.   heap and the tiled default heap with a certain value.
  1635.   ■hpt{_uheapset()} does the same thing for a specific heap.
  1636.  
  1637.   The ■hpt{_heap_walk()} function calls a user-supplied function for
  1638.   each block of the default heap and the tiled default heap, passing
  1639.   the address, size, and status (used or free) of one block per call.
  1640.   This can be used to identify memory leaks.  The ■hpt{_uheap_walk()}
  1641.   function does the same thing for a specific heap.
  1642.  
  1643. ■h2 Other heap-related functions
  1644.  
  1645.   The ■hpt{_heapmin()} function attempts to minimize the size of the
  1646.   default heap by deallocating memory areas which are not used for any
  1647.   blocks.  The ■hpt{_theapmin()} function attempts to minimize the
  1648.   tiled default heap.  The ■hpt{_uheapmin()} function attempts to
  1649.   minimize a specific heap.
  1650.  
  1651.   You can add memory to a heap by calling the ■hpt{_uaddmem()}
  1652.   function.  For instance, the memory area passed to _uaddmem() can be
  1653.   allocated with DosAllocMem.
  1654.  
  1655.   The ■hpt{_msize()} function returns the size of the block pointed to
  1656.   by its argument.  The ■hpt{_mheap()} function returns a pointer to
  1657.   the heap containing the block pointed to by its argument.  For both
  1658.   functions, the pointer must point to a used object of a heap.
  1659.  
  1660.   The ■hpt{_ustats()} function reports the amount of memory used for a
  1661.   heap, the total number of allocated bytes, the size of the biggest
  1662.   free block, etc.
  1663.  
  1664. ■h2 Why multiple heaps?
  1665.  
  1666.   Using multiple heaps has several advantages:
  1667.  
  1668. ■itemize
  1669.  
  1670.   If you need a lot of objects of the same size, you can reduce
  1671.   fragmentation of memory by creating a separate heap for those
  1672.   objects.  Using separate heaps for untiled and tiled objects also
  1673.   reduces fragmentation.
  1674.  
  1675. ■item
  1676.  
  1677.   By having different heaps for different threads, access to the heaps
  1678.   does not have to be serialized, making the application more
  1679.   efficient, especially on machines with multiple CPUs.  Moreover, the
  1680.   probability of one thread corrupting another thread's objects is
  1681.   reduced if objects are allocated in different heaps for different
  1682.   threads.
  1683.  
  1684. ■item
  1685.  
  1686.   You can deallocate all objects of a heap at once, by destroying the
  1687.   heap.  Though this is not good programming practice, you can use
  1688.   this scheme if you can't keep track of all the pointers.
  1689.  
  1690. ■item
  1691.  
  1692.   You can create heaps shared by multiple processes.
  1693.  
  1694. ■enditemize
  1695.  
  1696. ■h2 Non-contiguous heaps
  1697.  
  1698.   The malloc() implementation of the emx C library supports
  1699.   non-contiguous memory.  A heap can consist of several non-contiguous
  1700.   segments.
  1701.  
  1702.   Currently, there are some restrictions when using a non-contiguous
  1703.   heap.  See sbrk() for details.
  1704.  
  1705.  
  1706. ■h2 Replacing malloc()
  1707.  
  1708.   You can replace the emx implementation of malloc() with an alternate
  1709.   implementation of malloc() such as GNU malloc.  This is done by
  1710.   linking with that alternate malloc() library.  Additionally, you
  1711.   have to link with the ■tt{tmalloc} library which implements
  1712.   _tmalloc() etc. on top of malloc().  Example:
  1713.  
  1714. ■example
  1715. gcc -o program.exe src1.c src2.c -lvideo -ltmalloc gmalloc.a
  1716. ■endexample
  1717.  
  1718.   If the linker complains about malloc() being multiply defined, you
  1719.   probably forgot to link with the ■tt{tmalloc} library.  (There is a
  1720.   hack in the emx C library which tries to provoke this behavior to
  1721.   guard against forgetting to link with the ■tt{tmalloc} library.)
  1722.  
  1723.   You must not replace the emx implementation of malloc() if you are
  1724.   using a C runtime DLL (emxlibcs.dll, for instance) unless you
  1725.   replace malloc() in that library.  The application and all DLLs
  1726.   (with the exception of stand-alone DLLs) must use the same
  1727.   implementation of malloc().
  1728.  
  1729.  
  1730. ■h1 General terminal interface
  1731. ■label General terminal interface
  1732. ■label general terminal interface
  1733.  
  1734.   Both the System V and POSIX.1 terminal interfaces are supported by
  1735.   emx.
  1736.  
  1737.   Currently, only the keyboard device is supported.  The file
  1738.   descriptor used by the terminal interface must refer to the
  1739.   keyboard.  Moreover, the file descriptor must currently be 0 under
  1740.   DOS.
  1741.  
  1742.   Both terminal interfaces are not supported with the system call
  1743.   library sys.lib (■hpt{-Zsys}).
  1744.  
  1745.   The main implementation-specific difference between the two
  1746.   interfaces is the usage of the IDEFAULT bit of the c_lflag member of
  1747.   ■tt{struct termio} and ■tt{struct termios} for diabling the general
  1748.   terminal interface.  The POSIX.1 terminal interface does not use the
  1749.   IDEFAULT bit.
  1750.  
  1751. ■ipfminitoc
  1752.  
  1753. ■h2 System V terminal interface
  1754.  
  1755.   The System V terminal interface uses the TCGETA, TCSETA, TCSETAF,
  1756.   TCSETAW, TCFLSH, TCSBRK, and TCXONC requests of ■hpt{ioctl()} for
  1757.   controlling terminals.  The TCGETA, TCSETA, TCSETAF, and TCSETAW
  1758.   requests employ the following structure defined in <sys/termio.h>:
  1759.  
  1760. ■example
  1761. struct termio
  1762. {
  1763.   unsigned int  c_iflag;      /* input modes */
  1764.   unsigned int  c_oflag;      /* output modes */
  1765.   unsigned int  c_cflag;      /* control modes */
  1766.   unsigned int  c_lflag;      /* local modes */
  1767.   unsigned int  c_line;       /* unused */
  1768.   unsigned char c_cc[NCC];    /* control characters etc. */
  1769. };
  1770. ■endexample
  1771.  
  1772.   If c_lflag includes IDEFAULT, the default operating system input
  1773.   method is used (including line editing).  Input is always done line
  1774.   by line.  All other fields of the ■tt{termio} structure are ignored
  1775.   in this case.
  1776.  
  1777.   If c_lflag does not include IDEFAULT, UNIX-like input processing is
  1778.   performed.
  1779.  
  1780.   All bits of c_oflag, c_cflag, and c_line are currently ignored.
  1781.  
  1782.  
  1783. ■h2 POSIX.1 terminal interface
  1784.  
  1785.   The POSIX.1 terminal interface uses ■hpt{cfgetispeed()},
  1786.   ■hpt{cfgetospeed()}, ■hpt{cfsetispeed()}, ■hpt{cfsetospeed()},
  1787.   ■hpt{tcdrain()}, ■hpt{tcflow()}, ■hpt{tcflush()}, ■hpt{tcgetattr()},
  1788.   ■hpt{tcsendbreak()}, and ■hpt{tcsetattr()}.
  1789.  
  1790.   The tcgetattr() and tcsetattr() functions employ the following
  1791.   structure defined in <termios.h>:
  1792.  
  1793. ■example
  1794. struct termios
  1795. {
  1796.   tcflag_t c_iflag;           /* input modes */
  1797.   tcflag_t c_oflag;           /* output modes */
  1798.   tcflag_t c_cflag;           /* control modes */
  1799.   tcflag_t c_lflag;           /* local modes */
  1800.   cc_t c_cc[NCCS];            /* control characters etc. */
  1801.   int c_reserved[4];          /* currently unused */
  1802. };
  1803. ■endexample
  1804.  
  1805.   The POSIX.1 terminal interface is enabled by calling tcsetattr().
  1806.   Before the first invocation of tcsetattr(), the default operating
  1807.   system input method is used (including line editing).
  1808.  
  1809.   All bits of c_oflag, and c_cflag are currently ignored.
  1810.  
  1811.  
  1812. ■h2 Terminal parameters
  1813.  
  1814.   This description applies to both the System V and the POSIX.1
  1815.   terminal interfaces, unless otherwise indicated.
  1816.  
  1817.   The following bits of c_iflag are used by emx in the following
  1818.   sequence:
  1819.  
  1820. ■description
  1821.  
  1822. ■item IDELETE
  1823.  
  1824.   Backspace key generates DEL character (emx extension)
  1825.  
  1826. ■item ISTRIP
  1827.  
  1828.   Clear bit 7 of all input characters
  1829.  
  1830. ■item INLCR
  1831.  
  1832.   Translate linefeed into carriage return
  1833.  
  1834. ■item IGNCR
  1835.  
  1836.   Ignore carriage return
  1837.  
  1838. ■item ICRNL
  1839.  
  1840.   Translate carriage return into linefeed
  1841.  
  1842. ■item IUCLC
  1843.  
  1844.   Convert upper case letters (A-Z) into lower case (a-z)
  1845.  
  1846. ■enddescription
  1847.  
  1848.   If IDELETE is set, the two meanings of the backspace key (the one
  1849.   above the Return key) are swapped: Backspace generates DEL and
  1850.   Ctrl-Backspace generates Ctrl-H.  If IDELETE is not set, Backspace
  1851.   generates Ctrl-H and Ctrl-Backspace generates DEL.  The IDELETE bit
  1852.   applies only to the backspace key and does not affect other methods
  1853.   of entering Ctrl-H or DEL.
  1854.  
  1855.   The following bits of c_lflag are used by emx:
  1856.  
  1857. ■description
  1858. ■item IDEFAULT
  1859.  
  1860.   Disable special processing for the terminal interface (emx
  1861.   extension, this bit is always clear for the POSIX.1 terminal
  1862.   interface).  If this bit is set, the default operating system input
  1863.   method is used (including line editing).  For the System V
  1864.   terminal interface, this bit is initially set
  1865.  
  1866. ■item ISIG
  1867.  
  1868.   Enable signal processing (see VINTR and VQUIT)
  1869.  
  1870. ■item ICANON
  1871.  
  1872.   Read input line by line, enable line editing
  1873.  
  1874. ■item ECHO
  1875.  
  1876.   Echo input
  1877.  
  1878. ■item ECHOK
  1879.  
  1880.   Echo CR/LF after VKILL
  1881.  
  1882. ■enddescription
  1883.  
  1884.   The c_cc array contains control characters.  If an element of c_cc
  1885.   is set to zero (for the System V terminal interface) or
  1886.   _POSIX_VDISABLE (for the POSIX.1 terminal interface), no character
  1887.   will trigger the action associated with that element.
  1888.  
  1889. ■description
  1890. ■item VINTR
  1891.  
  1892.   Generate SIGINT (in thread 1) if ISIG is set in c_iflag
  1893.  
  1894. ■item VQUIT
  1895.  
  1896.   Generate SIGQUIT (in thread 1) if ISIG is set in c_iflag
  1897.  
  1898. ■enddescription
  1899.  
  1900.   The following characters are used if ICANON is set:
  1901.  
  1902. ■description
  1903. ■item VERASE
  1904.  
  1905.   Delete one character to the left (default: Ctrl-H)
  1906.  
  1907. ■item VKILL
  1908.  
  1909.   Deletes the entire input line (default: Ctrl-U)
  1910.  
  1911. ■item VEOF
  1912.  
  1913.   Indicates end of file (default: Ctrl-D)
  1914.  
  1915. ■item VEOL
  1916.  
  1917.   Indicates end of line (default: none)
  1918.  
  1919. ■item VSUSP
  1920.  
  1921.   Stop process (POSIX.1, ignored by emx)
  1922.  
  1923. ■item VSTOP
  1924.  
  1925.   Suspend output (POSIX.1, ignored by emx)
  1926.  
  1927. ■item VSTART
  1928.  
  1929.   Resume output (POSIX.1, ignored by emx)
  1930.  
  1931. ■enddescription
  1932.  
  1933.   The VERASE, VKILL and VEOF characters can be escaped by preceding
  1934.   them with a backslash.  End of file at the beginning of a line is
  1935.   usually interpreted as end of input.
  1936.  
  1937.   The following elements are used if ICANON is not set:
  1938.  
  1939. ■description
  1940. ■item VMIN
  1941.  
  1942.   Minimum number of characters to be read (default: 6)
  1943.  
  1944. ■item VTIME
  1945.  
  1946.   Time-Out in 0.1 seconds (default: 1)
  1947.  
  1948. ■enddescription
  1949.  
  1950.   Note that VMIN and VTIME are not equal to VEOF and VEOL,
  1951.   respectively.  Unix uses the VEOF field for both VEOF and VMIN, the
  1952.   VEOL field for both VEOL and VTIME.  emx uses separate fields for
  1953.   the four values.
  1954.  
  1955.   There are four cases for VMIN and VTIME (that is, ■tt{c_cc[VMIN]}
  1956.   and ■tt{c_cc[VTIME]}):
  1957.  
  1958. ■list
  1959.  
  1960. ■item ■tt{VMIN = 0, VTIME = 0}
  1961.  
  1962.   Return all the characters stored in the input buffer.  If there are
  1963.   no characters in the buffer, read() returns immediately.  read()
  1964.   doesn't wait for input.
  1965.  
  1966. ■item ■tt{VMIN = 0, VTIME > 0}
  1967.  
  1968.   Return after at least one character has been received or after
  1969.   waiting for VTIME * 0.1 seconds, whichever happens first.  In the
  1970.   latter case, read() will return 0.
  1971.  
  1972. ■item ■tt{VMIN > 0, VTIME = 0}
  1973.  
  1974.   Return after at least VMIN characters have been received.
  1975.  
  1976. ■item ■tt{VMIN > 0, VTIME > 0}
  1977.  
  1978.   Return after at least VMIN characters have been received or if no
  1979.   characters have been received for VMIN * 0.1 seconds after receipt
  1980.   of a character (the time-out applies after at least one character
  1981.   has been received and is reset after each character).
  1982.  
  1983. ■endlist
  1984.  
  1985.   In all cases, read() will return as many characters as are available
  1986.   in the input buffer, up to the number of characters requested in the
  1987.   read() call.
  1988.  
  1989.   If O_NONBLOCK (alias O_NDELAY) has been set for the file descriptor
  1990.   with ■hpt{fcntl()}, read() will always immediately return.  If there
  1991.   is not enough data available with respect to VMIN, read() will
  1992.   immediately return -1 and set errno to EAGAIN.
  1993.  
  1994.   If the general terminal interface is enabled, the text/binary mode
  1995.   of the handle is ignored: the conversions are controlled by c_iflag,
  1996.   including CR-to-LF conversion and the end-of-file character.
  1997.  
  1998.   If ICANON is not set, function keys are returned as two characters.
  1999.   The first one is a null (■tt{'\0'}) character, the second one is the
  2000.   scan code.  See <sys/kbdscan.h> for scan codes.
  2001.  
  2002.  
  2003. ■h1 Signal processing
  2004. ■label signal processing
  2005.  
  2006.  
  2007.   Signals are conditions that may be reported synchronously or
  2008.   asynchronously during program execution.  Each signal is associated
  2009.   with a signal action, which specifies what action to perform when
  2010.   the signal occurs.
  2011.  
  2012. ■ipfminitoc
  2013.  
  2014. ■h2 Signal actions
  2015.  
  2016.   Each signal is associated with one of the following actions:
  2017.  
  2018. ■description
  2019. ■item SIG_DFL
  2020.  
  2021.   Default signal action.  The action depends on the signal, see the
  2022.   table below.
  2023.  
  2024. ■item SIG_IGN
  2025.  
  2026.   Ignore the signal.
  2027.  
  2028. ■item signal-catching function
  2029.  
  2030.   Upon receipt of the signal, a signal-catching function (also known
  2031.   as signal handler) is called.  The signal number is passed as the
  2032.   only argument to the signal-catching function.  Before the
  2033.   signal-catching funcion is called, the signal is blocked or the
  2034.   signal action is reset to SIG_DFL, depending on the signal
  2035.   processing model.
  2036.  
  2037. ■enddescription
  2038.  
  2039.   The signal action can be changed with the ■hpt{signal()} and
  2040.   ■hpt{sigaction()} functions.  The signal action for SIGKILL is
  2041.   SIG_DFL and cannot be changed.  Signal actions are private to each
  2042.   thread of multithread programs.
  2043.  
  2044.   If a signal which isn't ignored (that is, SIG_DFL or handler
  2045.   installed) occurs while calling read() with the ■hpt{general
  2046.   terminal interface} enabled, -1 will be returned by read() and errno
  2047.   will be set to EINTR.  The buffer will flushed.
  2048.  
  2049.   For all signals, the initial signal handler is SIG_DFL (unless
  2050.   SIG_IGN is inherited from the parent process), sa_mask is 0, and
  2051.   sa_flags is SA_ACK.  Initially, all signals are not blocked.
  2052.  
  2053.   Only certain library functions can be called by a signal-catching
  2054.   function.  All other library functions are considered to be unsafe.
  2055.   Calling an unsafe function in a signal-catching function which
  2056.   interrupted an unsafe function causes undefined behavior.
  2057.  
  2058. ■c TODO: List of reentrant functions
  2059.  
  2060. ■c _exit() access() alarm() cfgetispeed() cfgetospeed() cfsetispeed()
  2061. ■c cfsetospeed() chdir() chmod() chown() close() creat() dup2() dup()
  2062. ■c execle() execve() fcntl() fork() fstat() getegid() geteuid()
  2063. ■c getgid() getgroups() getpgrp() getpid() getppid() getuid() kill()
  2064. ■c link() lseek() mkdir() mkfifo() open() pathconf() pause() pipe()
  2065. ■c read() rename() rmdir() setgid() setpgid() setsid() setuid() sigaction()
  2066. ■c sigaddset() sigdelset() sigemptyset() sigfillset() sigismember()
  2067. ■c sigpending() sigprocmask() sigsuspend() sleep() stat() sysconf()
  2068. ■c tcdrain() tcflow() tcflush() tcgetattr() tcgetpgrp() tcsendbreak()
  2069. ■c tcsetattr() tcsetpgrp() time() times() umask() uname() unlink()
  2070. ■c utime() wait() waitpid() write()
  2071.  
  2072. ■h2 Blocking signals
  2073.  
  2074.   Signals can be blocked with the ■hpt{sigprocmask()} function.  If a
  2075.   signal is generated while it is blocked, it won't be delivered until
  2076.   unblocked, that is, the generated signal will be pending while the
  2077.   signal is blocked.  As soon as the signal is unblocked, the pending
  2078.   signal will be delivered.  At most one signal of each kind can be
  2079.   pending, that is, if a signal is generated twice while it is
  2080.   blocked, it will be delivered only once as soon as it will be
  2081.   unblocked.  However, SIGCHLD will be stay pending until termination
  2082.   status for all terminated child processes has been fetched with
  2083.   wait() or waitpid().  The action taken on delivery is determined by
  2084.   the signal action in effect when the signal is delivered, not when
  2085.   the signal is generated.  If a signal like SIGILL is caused by an
  2086.   exception while it is blocked, the default action will be taken.
  2087.  
  2088.  
  2089. ■h2 Signal processing models
  2090.  
  2091.   The following signal processing models are available:
  2092.  
  2093. ■description
  2094. ■item emx
  2095.   On entry to a signal handler, the signal is blocked.  To unblock
  2096.   (acknowledge) the signal,
  2097. ■example
  2098. signal (signo, SIG_ACK);
  2099. ■endexample
  2100.   must be called (by the signal handler, usually), otherwise that
  2101.   signal cannot be delivered again.  For compatibility with existing
  2102.   emx programs, this model is the default.
  2103.  
  2104. ■item System V
  2105.   On entry to a signal handler, the action for the signal is set to
  2106.   SIG_DFL.  The signal handler has to be reinstalled with sigaction()
  2107.   or signal().  Note that there is a timing window; for instance, the
  2108.   process will be terminated if two SIGINT signals occur in quick
  2109.   succession.
  2110.  
  2111. ■item BSD and POSIX.1
  2112.   On entry to a signal handler, the signal is blocked.  It will be
  2113.   unblocked automatically when the signal handler returns.
  2114. ■enddescription
  2115.  
  2116.   With the system call library sys.lib (■hpt{-Zsys}), only the
  2117.   `emx' signal processing model is available with signal(); however,
  2118.   sigaction() is fully supported.
  2119.  
  2120.   When using ■hpt{signal()} to install a signal handler, the signal
  2121.   processing model for that signal is by default `emx'.  To use the
  2122.   `System V' model for signal(), link with ■tt{sigsysv.o} by using the
  2123.   -Zsysv-signals option of GCC.  To use the `BSD' model for signal(),
  2124.   link with ■tt{sigbsd.o} by using the -Zbsd-signals option of GCC.
  2125.   -Zsysv-signals and -Zbsd-signals cannot be used with -Zsys.
  2126.  
  2127.   When using ■hpt{sigaction()} to install a signal handler, the signal
  2128.   processing model for that signal is `BSD', which conforms to
  2129.   POSIX.1.  The `emx' model can be selected by setting the SA_ACK bit of
  2130.   the sa_flags member of ■tt{struct sigaction}.  The `System V' model
  2131.   can be selected by setting the SA_SYSV bit of the sa_flags member of
  2132.   ■tt{struct sigaction}.
  2133.  
  2134. ■h2 Available signals
  2135.  
  2136.   The following signals are defined by emx:
  2137.  
  2138. ■example
  2139. Signal   │  SIG_DFL  │ Standard │ Description
  2140. ─────────┼───────────┼──────────┼──────────────────────────────────────────
  2141. SIGHUP   │ terminate │ POSIX.1  │ Hangup
  2142. SIGINT   │ terminate │ C90      │ Interrupt (Ctrl-C or Ctrl-Break)
  2143. SIGQUIT  │   core    │ POSIX.1  │ Quit
  2144. SIGILL   │   core    │ C90      │ Illegal instruction
  2145. SIGTRAP  │   core    │          │ Single step (debugging)
  2146. SIGABRT  │   core    │ C90      │ abort ()
  2147. SIGEMT   │   core    │          │ EMT instruction
  2148. SIGFPE   │   core    │ C90      │ Floating point exception
  2149. SIGKILL  │ terminate │ POSIX.1  │ Kill process, cannot be caught or ignored
  2150. SIGBUS   │   core    │          │ Bus error
  2151. SIGSEGV  │   core    │ C90      │ Segmentation violation
  2152. SIGSYS   │   core    │          │ Invalid argument to system call
  2153. SIGPIPE  │ terminate │ POSIX.1  │ Broken pipe
  2154. SIGALRM  │ terminate │ POSIX.1  │ Alarm lock
  2155. SIGTERM  │ terminate │ C90      │ Termination, process killed
  2156. SIGUSR1  │  ignore   │ POSIX.1  │ User-defined signal #1
  2157. SIGUSR2  │  ignore   │ POSIX.1  │ User-defined signal #2
  2158. SIGCHLD  │  ignore   │ POSIX.1  │ Death of a child process
  2159. SIGCLD   │  ignore   │ SysV     │ Synonym for SIGCHLD
  2160. SIGBREAK │ terminate │          │ Break (Ctrl-Break)
  2161. SIGWINCH │  ignore   │          │ Window size changed
  2162. ■endexample
  2163.  
  2164.     The SIG_DFL column gives the default action for the signals, that
  2165.     is, when the signal action is SIG_DFL:
  2166.  
  2167. ■description
  2168. ■item terminate
  2169.  
  2170.     Terminate the process with return code 3.
  2171.  
  2172. ■item core
  2173.  
  2174.     Dump core and terminate the process.  A file whose name is
  2175.     `■tt{core}' will be written in the current working directory.  A
  2176.     `■tt{core}' file contains a memory dump and the values of the
  2177.     registers at the time the signal was delivered.  It can be used
  2178.     for post-mortem debugging.  If LINK386 was used for linking, no
  2179.     core dump file will be written.
  2180.  
  2181. ■item ignore
  2182.  
  2183.     The signal is ignored, the process will be continued at the place
  2184.     it was interrupted.
  2185.  
  2186. ■enddescription
  2187.  
  2188. ■h2 Catching signals
  2189.  
  2190.   You can use ■hpt{sigaction()} or ■hpt{signal()} to set signal
  2191.   handlers for all signals but SIGKILL.
  2192.  
  2193.   If a signal handler returns, further processing depends on how the
  2194.   signal was generated.  If the signal was generated by raise() or
  2195.   kill(), processing will continue where it was interrupted.  If the
  2196.   signal was generated by an exception (this applies to signals
  2197.   SIGILL, SIGSEGV, SIGFPE), core will be dumped and the process will
  2198.   be terminated with return code 3.
  2199.  
  2200.   If LINK386 was used for linking, no core dump file will be written.
  2201.  
  2202.   In the `emx' signal model, the signal handler should call
  2203.  
  2204. ■example
  2205. signal (signal_number, SIG_ACK);
  2206. ■endexample
  2207.  
  2208.   before returning to unblock the signal.  In the `System V' signal
  2209.   model, the signal handler should reinstall itself as soon as
  2210.   possible.  However, for SIGCHLD and SIGCLD, wait() or waitpid() must
  2211.   be called before reinstalling the signal handler.
  2212.  
  2213.   In the `BSD' and `POSIX.1' signal models, the signal handler need
  2214.   not unblock the signal as the signal mask which was active before
  2215.   calling the signal handler is reinstalled after the signal handler
  2216.   returns.
  2217.  
  2218.   A signal handler usually looks like this in the `emx' signal model:
  2219.  
  2220. ■example
  2221. void handler (int signo)
  2222. {
  2223.   /* Do the work here, the signal is blocked */
  2224.   signal (signo, SIG_ACK);
  2225. }
  2226. ■endexample
  2227.  
  2228.   A signal handler usually looks like this in the `System V' signal
  2229.   model:
  2230.  
  2231. ■example
  2232. void handler (int signo)
  2233. {
  2234.   /* Call wait() or waitpid() here for SIGCHLD aka SIGCLD */
  2235.   signal (signo, handler);
  2236.   /* Do other work here (the signal is not blocked!) */
  2237. }
  2238. ■endexample
  2239.  
  2240.   A signal handler usually looks like this in the `BSD' and `POSIX.1'
  2241.   signal models:
  2242.  
  2243. ■example
  2244. void handler (int signo)
  2245. {
  2246.   /* Do the work here, the signal is blocked */
  2247. }
  2248. ■endexample
  2249.  
  2250.   Do not use floating point math in a signal handler if the signal
  2251.   handler will return to the interrupted code.  File I/O in the signal
  2252.   handler is also dangerous because a file I/O function could have
  2253.   been interrupted by the signal.
  2254.  
  2255.   Only one signal of any type may be pending.  However, SIGCHLD will
  2256.   be stay pending until termination status for all terminated child
  2257.   processes has been fetched with wait() or waitpid().
  2258.  
  2259. ■h2 Signals generated by the system
  2260.  
  2261.   The following signals can be generated by the system:
  2262.  
  2263. ■description
  2264. ■item SIGINT
  2265.   Ctrl-C typed by user (or VINTR, see `■hpt{General terminal interface}')
  2266. ■item SIGQUIT
  2267.   VQUIT character entered (see `■hpt{General terminal interface}')
  2268. ■item SIGILL
  2269.   Illegal instruction
  2270. ■item SIGFPE
  2271.   Floating point exception or division by zero
  2272. ■item SIGSEGV
  2273.   Segmentation violation
  2274. ■item SIGPIPE
  2275.   An attempt is made to write to a pipe or named pipe that is not
  2276.   open for reading by any process
  2277. ■item SIGALRM
  2278.   alarm() timer expired
  2279. ■item SIGTERM
  2280.   Process termination request
  2281. ■item SIGCHLD
  2282.   Termination status for a child process is available
  2283. ■item SIGBREAK
  2284.   Ctrl-Break typed by user
  2285. ■enddescription
  2286.  
  2287.   Note that SIGWINCH is not generated by the system.
  2288.  
  2289.   The signals SIGINT, SIGQUIT, SIGALRM, SIGTERM, SIGCHLD and SIGBREAK
  2290.   are generated in the main thread (thread 1).
  2291.  
  2292.   The signals SIGILL, SIGFPE and SIGSEGV are generated in the thread
  2293.   which caused the exception. If generated by an exception, these
  2294.   signals are delivered even if blocked and SIG_IGN is treated like
  2295.   SIG_DFL (however, under OS/2, the core dump will be suppressed by
  2296.   SIG_IGN).
  2297.  
  2298. ■h3 SIGINT and SIGBREAK
  2299.  
  2300.   If you want to trap Ctrl-C and Ctrl-Break, register a signal handler
  2301.   for both SIGINT and SIGBREAK.  Note that typing Ctrl-Break generates
  2302.   SIGINT unless termio is used under OS/2 with the IDEFAULT bit reset.
  2303.   With a future release of emx, Ctrl-Break may generate SIGBREAK in
  2304.   all cases.  Under DOS, SIGINT generated by Ctrl-Break is delivered on
  2305.   return from the next system call or on return to protected mode from
  2306.   the next hardware interrupt, whichever comes first; SIGINT generated
  2307.   by Ctrl-C is delivered on return from the next system call which
  2308.   uses a DOS call which checks for Ctrl-C.  Under OS/2, SIGINT is
  2309.   generated and delivered asynchronously.
  2310.  
  2311. ■h3 SIGFPE
  2312.  
  2313.   By default, all floating point exceptions are masked: The
  2314.   coprocessor will perform a default action (replace the result with
  2315.   a NaN, for instance) and continue without generating SIGFPE.  Use
  2316.   ■hpt{_control87()} to enable floating point exceptions.  However,
  2317.   SIGFPE is not reliable.  Under DOS, SIGFPE is not supported for
  2318.   machines not compatible enough with the industry standard.
  2319.  
  2320. ■h3 SIGTERM
  2321.  
  2322.   SIGTERM is implemented only under OS/2.  It is sent to a process if
  2323.   the user or another process requests the termination of the process.
  2324.   Continuing the process by calling longjmp() is not a good idea.
  2325.  
  2326. ■h3 SIGCHLD
  2327.  
  2328.   SIGCHLD will be generated again if there is termination status
  2329.   available for a child process on return from the signal handler for
  2330.   SIGCHLD or when unblocking SIGCHLD or when, for the `System V'
  2331.   signal processing model, installing a signal handler for SIGCHLD.
  2332.   That is, the signal handler must call wait() or waitpid() before
  2333.   returning or unblocking the signal to avoid infinite invocation of
  2334.   the signal handler.
  2335.  
  2336.   Note that SIGCHLD and SIGCLD are synonyms; both names refer to the
  2337.   same signal.
  2338.  
  2339.   In contrast to System V, emx currently treats SIG_DFL and SIG_IGN
  2340.   identically for SIGCHLD, that is, child processes are turned into
  2341.   zombies when they terminate even if the action for SIGCHLD is
  2342.   SIG_IGN.  Moreover, the behavior of wait() and waitpid() is not
  2343.   affected by the action for SIGCHLD.
  2344.  
  2345.   With the system call library sys.lib (■hpt{-Zsys}), SIGCHLD is
  2346.   not generated by the system.
  2347.  
  2348. ■h3 SIGTRAP
  2349.  
  2350.   In addition to the signals which can be generated by the system, the
  2351.   SIGTRAP signal can be returned by ■hpt{wait()} when using
  2352.   ■hpt{ptrace()}.  SIGTRAP is returned after single-stepping one
  2353.   instruction.
  2354.  
  2355. ■h2 Sending signals to other processes
  2356.  
  2357.   Due to OS/2 restrictions, only SIGINT and SIGBREAK can be sent to
  2358.   arbitrary child processes.  A process can send the other signals
  2359.   only to itself, see ■hpt{raise()}, or to other emx programs (which
  2360.   use emx.dll under OS/2) being immediate children of the process.
  2361.  
  2362. ■h2 Inheriting signal handlers
  2363.  
  2364.   Programs which use emx.dll or emx.exe inherit the signal actions of
  2365.   the parent process if the parent process also uses emx.dll or
  2366.   emx.exe: Signals set to SIG_IGN in the parent process will be set to
  2367.   SIG_IGN in the child process, signals set to SIG_DFL in the parent
  2368.   process will be set to SIG_DFL in the child process, signals caught
  2369.   in the child process will be set to SIG_DFL in the child process.
  2370.  
  2371.   Programs which don't use emx.dll or emx.exe or have not been started
  2372.   by a program which uses emx.dll or emx.exe will have all signal
  2373.   actions set to SIG_DFL initially.
  2374.  
  2375.   Processes created by fork() inherit all signal settings (including
  2376.   sa_mask and sa_flags) of their parent process.
  2377.  
  2378.  
  2379. ■h1 Sockets
  2380.  
  2381.   emx includes support for sockets of IBM TCP/IP for OS/2 (including
  2382.   the Internet Access Kit of OS/2 3.0).  The headers files are derived
  2383.   from NetBSD and are packaged in ■tt{bsddev.zip}.  Some manual pages
  2384.   are packaged in ■tt{bsddoc.zip}.
  2385.  
  2386.   To use IBM TCP/IP 4.0, you must compile your applications with
  2387.   ■tt{-DTCPIPV4}.  Programs which use ■tt{<net/if.h>} are compatible
  2388.   either with TCP/IP 4.0 or older versions, not both.
  2389.  
  2390.   Use the -lsocket option to link with the socket library.  Note that
  2391.   -lsocket, like all -l option, should be given ■em{after} the source
  2392.   files:
  2393.  
  2394. ■example
  2395. gcc mymain.c mysub.c -lsocket
  2396. ■endexample
  2397.  
  2398.   emx tries to provide seamless support for sockets, like Unix systems
  2399.   do.  This approach is quite different from the one taken by IBM's
  2400.   TCP/IP for OS/2 Toolkit.
  2401.  
  2402.   Sockets are not supported with the system call library sys.lib
  2403.   (■hpt{-Zsys}).
  2404.  
  2405.   The header <sys/so_ioctl.h>, which includes TCP/IP-specific
  2406.   definitions for ioctl(), is included by <sys/ioctl.h> only if a
  2407.   TCP/IP-related header such as <sys/socket.h> has been
  2408.   included before <sys/ioctl.h>.  If you don't want to reorder the
  2409.   ■tt{#include} directives, define the symbol ■tt{_EMX_TCPIP} before
  2410.   including <sys/ioctl.h>, or include <sys/so_ioctl.h> directly
  2411.   (however, the last alternative is not recommended).
  2412.  
  2413. ■ipfminitoc
  2414.  
  2415. ■h2 Porting Unix applications
  2416.  
  2417.   When porting Unix applications, please note the following
  2418.   restrictions:
  2419.  
  2420. ■itemize
  2421. ■item
  2422.   Socket handles are not inherited across ■hpt{exec*()} and
  2423.   ■hpt{spawn*()}.  (Note that a process created by ■hpt{fork()}
  2424.   inherits the socket handles of its parent process.)  Inheriting
  2425.   socket handles is planned for a future release of emx.
  2426.  
  2427. ■item
  2428.   The size of messages is restricted to 32767 bytes (this is a
  2429.   limitation of IBM TCP/IP for OS/2).
  2430.  
  2431. ■item
  2432.   Initially, sockets are in binary mode.  Use ■hpt{setmode()} to
  2433.   switch to text mode.  Text mode applies to read() and write(), only.
  2434.   ■tt{recv()} and ■tt{send()} always use binary mode.
  2435.  
  2436. ■item
  2437.   The functions ■tt{recvmsg()}, ■tt{sendmsg()}, and
  2438.   ■tt{socketpair()} are not implemented.
  2439.  
  2440. ■enditemize
  2441.  
  2442. ■h2 Porting OS/2 applications
  2443.  
  2444.   When porting OS/2 applications written for IBM's TCP/IP for OS/2
  2445.   Toolkit, please note the following differences:
  2446.  
  2447. ■itemize
  2448. ■item
  2449.   Socket handles and file handles share a common handle space which is
  2450.   managed by emx.dll.  To obtain the internal socket handle (used by
  2451.   IBM TCP/IP for OS/2) associated with a handle, use the
  2452.   ■hpt{_getsockhandle()} function.
  2453.  
  2454. ■item
  2455.   ■tt{sock_init()} is not required and not implemented.
  2456.  
  2457. ■item
  2458.   Use ■hpt{close()} instead of ■tt{soclose()}.
  2459.  
  2460. ■item
  2461.   You can use ■hpt{read()} and ■hpt{write()} on sockets.
  2462.  
  2463. ■item
  2464.   The ■hpt{select()} function uses BSD semantics (except for the
  2465.   return value) and works for sockets and some other types of file
  2466.   handles.
  2467.  
  2468. ■item
  2469.   Use ■hpt{errno} instead of ■tt{sock_errno()}, and ■hpt{perror()}
  2470.   instead of ■tt{psock_errno()}.
  2471.  
  2472. ■item
  2473.   ■hpt{ioctl()} of emx takes three arguments whereas the ioctl()
  2474.   function of the IBM TCP/IP for OS/2 Toolkit takes four arguments.
  2475.  
  2476. ■item
  2477.   The functions ■tt{recvmsg()}, ■tt{sendmsg()}, and
  2478.   ■tt{socketpair()} are not implemented.
  2479.  
  2480. ■enditemize
  2481.  
  2482.  
  2483. ■h1 Floating-point math
  2484.  
  2485.   Applications which need to conform to IEEE 754 to obtain the same
  2486.   results across architectures should call ■hpt{_control87()} to
  2487.   change the precision to a mantissa size of 53 bits:
  2488.  
  2489. ■example
  2490. _control87 (PC_53, MCW_PC);
  2491. ■endexample
  2492.  
  2493.   The default precision is 64 bits.
  2494.  
  2495.   By default, all floating-point exceptions are masked off.  You can
  2496.   use ■tt{_control87()} to enable floating-point exceptions.  SIGFPE
  2497.   will be raised if an unmasked floating-point exception occurs.
  2498.  
  2499.   Decimal to binary conversions (scanf(), strtod(), ...) and binary to
  2500.   decimal conversions (gcvt(), printf(), ...) by default conform to
  2501.   IEEE 754.  Conversion from decimal to binary does not round
  2502.   correctly if the decimal number has more than DECIMAL_DIG
  2503.   significant digits.  Currently, conversion always rounds to
  2504.   nearest/even, no matter what rounding mode is selected.
  2505.  
  2506.   The IEEE 754 conversion routines are slow and big.  To use the
  2507.   faster and smaller, but inaccurate, conversion routines, use the
  2508.   -Zsmall-conv option of GCC.  This saves about 14KB for programs
  2509.   which use binary to decimal conversions, about 11KB for programs
  2510.   which use decimal to binary conversions, and about 15KB for programs
  2511.   which use both.
  2512.  
  2513. ■h1 Mutex semaphores
  2514.  
  2515.   In addition to OS/2's mutex semaphores (HMTX), the emx runtime
  2516.   library offers three types of mutex semaphores: _fmutex semaphores,
  2517.   _rmutex semaphores, and _smutex semaphores.
  2518.  
  2519.   A mutex semaphore has two states: available and owned.  At most one
  2520.   thread can own a mutex semaphore.  If a thread request ownership of
  2521.   a mutex semaphore which is already owned, the thread will be
  2522.   suspended until the semaphores becomes available.  When ownership of
  2523.   a mutex semaphore is relinquished, exactly one of the threads
  2524.   waiting for the semaphore will become the new owner and will resume
  2525.   execution.
  2526.  
  2527.   For all three types of emx semaphores, ownership of a semaphore is
  2528.   not tied to a thread, that is, it's not a thread which owns the
  2529.   semaphore.  This is in contrast to OS/2's mutex semaphores.
  2530.   Deadlock will occur if ownership of a semaphore is requested twice
  2531.   for the same semaphore by the same thread without relinquishing
  2532.   ownership of the semaphore between the two request.  This fact is
  2533.   important to keep in mind in presence of signals.  Signal handlers
  2534.   must not request semaphores which can be owned by the interrupted
  2535.   code.  You might want to block signals before requesting ownership
  2536.   of an emx semaphore.
  2537.  
  2538. ■ipfminitoc
  2539.  
  2540. ■h2 _fmutex semaphores
  2541. ■label _fmutex semaphores
  2542.  
  2543.   _fmutex semaphores are fast RAM semaphores which control access to a
  2544.   resource shared by threads or processes.  _fmutex semaphores must be
  2545.   created with ■hpt{_fmutex_create()}. The ■hpt{_fmutex_request()}
  2546.   function is used to request ownership of an _fmutex semaphore: If
  2547.   the semaphore is available, it will be set to owned and
  2548.   _fmutex_request() will return immediately.  If the semaphore is
  2549.   owned, _fmutex_request() will block while the semaphore is owned.
  2550.   When the semaphore becomes available, one of the threads blocking in
  2551.   _fmutex_request() will unblock and become the owner of the
  2552.   semaphore.  Ownership of an _fmutex semaphore is relinquished with
  2553.   ■hpt{_fmutex_release()}.  If another thread blocks in
  2554.   _fmutex_request(), _fmutex_release() will unblock one of the
  2555.   blocking threads.
  2556.  
  2557.   ■hpt{_fmutex_open()} obtains access to a shared _fmutex semaphore
  2558.   created by another process.  All threads of the process which called
  2559.   _fmutex_create() have access to the semaphore without calling
  2560.   _fmutex_open().  ■hpt{_fmutex_close()} closes an _fmutex semaphore.
  2561.   Destroying _fmutex objects without calling _fmutex_close() will
  2562.   cause a semaphore leak.  ■hpt{_fmutex_available()} returns the
  2563.   status of an _fmutex semaphore without blocking and without changing
  2564.   the state of the semaphore.
  2565.  
  2566.   Unlike _rmutex semaphores, _fmutex semaphores are not inherited by
  2567.   child processes created with fork().  In most cases, _fmutex
  2568.   semaphores cannot be used by programs which use fork().
  2569.  
  2570. ■h2 _rmutex semaphores
  2571. ■label _rmutex semaphores
  2572.  
  2573.   _rmutex semaphores are fast RAM semaphores like _fmutex semaphores.
  2574.   However, the runtime library keeps track of _rmutex semaphores (the
  2575.   `■tt{r}' is for `registered'); in consequence, _rmutex semaphores
  2576.   are inherited by child processes created with fork().  However, this
  2577.   applies only to non-shared _rmutex semaphores; shared _rmutex
  2578.   semaphores (created with the _FMC_SHARED flag) behave like _fmutex
  2579.   semaphores.  Copying and assigning _rmutex semaphores is not
  2580.   allowed.  An _rmutex object must not go out of scope or be
  2581.   deallocated while the _rmutex semaphore is open; you must close the
  2582.   semaphore before destroying the object!  _rmutex semaphores must be
  2583.   created with ■hpt{_rmutex_create()}.
  2584.  
  2585. ■h2 _smutex semaphores
  2586. ■label _smutex semaphores
  2587.  
  2588.   _smutex semaphores are very simple RAM semaphores which control
  2589.   access to a resource shared by threads or processes.  These
  2590.   semaphores need not be created and destroyed, _smutex objects just
  2591.   have to be initialized to zero.  _smutex semaphores are implemented
  2592.   with looping and DosSleep.  Therefore, they should be used only if a
  2593.   collision is very unlikely, for instance, during initializing.  In
  2594.   all other cases, _fmutex, _rmutex, or HMTX semaphores should be
  2595.   used.
  2596.  
  2597.   An _smutex semaphore is available if object of type _smutex is
  2598.   (explicitely or implicitely initialized to) zero.  The
  2599.   ■hpt{_smutex_request()} function is used to request ownership of an
  2600.   _smutex semaphore: If the semaphore is available, it will be set to
  2601.   owned and _smutex_request() will return immediately.  If the
  2602.   semaphore is owned, _smutex_request() will not return while the
  2603.   semaphore is owned.  When the semaphore becomes available, one of
  2604.   the threads blocking in _smutex_request() will unblock sooner or
  2605.   later and will become the owner of the semaphore.  Ownership of an
  2606.   _smutex semaphore is relinquished with ■hpt{_smutex_release()}.
  2607.   ■hpt{_smutex_available()} returns the status of an _smutex semaphore
  2608.   without blocking and without changing the state of the semaphore.
  2609.   An _smutex semaphore can be used by multiple processes if the
  2610.   _smutex object is in shared memory.
  2611.  
  2612.  
  2613. ■h1 Function reference
  2614. ■i1 Functions
  2615.  
  2616.   The functions are listed almost alphabetically.
  2617. ■if text
  2618.   The origin of most of the functions is shown in [brackets] at the
  2619.   end of the first line.  Functions which are not available or are
  2620.   limited with the system call library (-Zsys, sys.lib) are marked
  2621.   * in [brackets].
  2622. ■else
  2623.   Functions which are not available or are limited with the system
  2624.   call library (■hpt{-Zsys}, sys.lib) are marked * in the `Compatibility'
  2625.   section.
  2626. ■endif
  2627.  
  2628.  
  2629. ■function abort()
  2630. ■compat C90 POSIX.1
  2631. ■headers
  2632. #include <stdlib.h>
  2633. ■endheaders
  2634.  
  2635. ■prototype
  2636. void abort (void);
  2637. ■endprototype
  2638.  
  2639.     abort() causes abnormal termination of the process, unless the
  2640.     signal SIGABRT is caught, and not blocked, and the signal handler
  2641.     does not return.  If SIGABRT is blocked, the signal handler won't
  2642.     be called.
  2643.  
  2644.     If abort() causes termination of the process, open streams and
  2645.     file handles will be closed prior to termination of the process.
  2646.     The process is terminated by calling ■tt{raise (SIGABRT)} with the
  2647.     signal action associated with SIGABRT being set to SIG_DFL.
  2648.  
  2649. ■returnvalue
  2650.  
  2651.     abort() does not return.
  2652.  
  2653. ■implementation
  2654.  
  2655.     The default action for SIGABRT is to display the message
  2656.  
  2657. ■example
  2658. Abnormal program termination
  2659. ■endexample
  2660.  
  2661.     and dump core (for post mortem debugging) and terminate the
  2662.     process with return code 3.
  2663.  
  2664. ■seealso exit() _exit() raise() sigaction() signal()
  2665.  
  2666.  
  2667. ■function abs()
  2668. ■compat C90
  2669. ■headers
  2670. #include <stdlib.h>     /* use this */
  2671. #include <math.h>       /* or this */
  2672. ■endheaders
  2673.  
  2674. ■param N
  2675. ■prototype
  2676. int abs (int N);
  2677. ■endprototype
  2678.  
  2679.     Return the absolute value of N: If N is negative, -■pa{N} is
  2680.     returned.  Otherwise, N is returned.
  2681.  
  2682. ■returnvalue
  2683.  
  2684.     abs() returns the absolute value of its argument.
  2685.  
  2686. ■implementation
  2687.  
  2688.     In-line code is generated for this function.
  2689.  
  2690. ■seealso fabs() labs()
  2691.  
  2692.  
  2693. ■function _abspath()
  2694. ■compat emx
  2695. ■headers
  2696. #include <stdlib.h>
  2697. ■endheaders
  2698.  
  2699. ■param DST SRC SIZE
  2700. ■prototype
  2701. int _abspath (char *DST, const char *SRC, int SIZE);
  2702. ■endprototype
  2703.  
  2704.     Construct an absolute path name for the file name or directory
  2705.     name pointed to by SRC.  The absolute path name is written to the
  2706.     array pointed to by DST.  It is assumed that there are SIZE bytes
  2707.     available at DST, this includes the terminating null character.
  2708.     If there is an error, -1 is returned.  If _abspath() succeeds, 0
  2709.     is returned.  If SIZE is too small, errno is set to ERANGE and -1
  2710.     is returned.  DST can be identical to SRC.  Backslashes are
  2711.     translated into forward slashes.  The absolute path name is not
  2712.     translated to lower case.  If the string pointed to by SRC ends
  2713.     with a slash or backslash, the string pointed to by DST will end
  2714.     with a slash.
  2715.  
  2716.     In contrast to _fullpath(), _abspath() works with non-existing
  2717.     paths: it accesses the appropriate drive only for finding out the
  2718.     current working directory if necessary.
  2719.  
  2720.     _abspath() properly handles DBCS characters.
  2721.  
  2722. ■returnvalue
  2723. ■description
  2724. ■item 0
  2725.     success
  2726. ■item -1
  2727.     error
  2728. ■enddescription
  2729.  
  2730. ■seealso _fnisabs() _fnisrel() _fullpath() _nls_init()
  2731.  
  2732.  
  2733. ■function access()
  2734. ■compat UNIX
  2735. ■headers
  2736. #include <io.h>
  2737. ■endheaders
  2738.  
  2739. ■param NAME MODE
  2740. ■prototype
  2741. int access (const char *NAME, int MODE);
  2742. ■endprototype
  2743.  
  2744.     Check whether MODE access is allowed for the file or directory
  2745.     whose name is in the string pointed to NAME.  If MODE is F_OK (0),
  2746.     access() checks only for existence of the file or directory.  If
  2747.     MODE is W_OK (2), access() checks for write permission.  If MODE
  2748.     is R_OK (4), access() checks for read permission (always granted
  2749.     under DOS and OS/2 if the file exists).  If MODE is ■tt{R_OK|W_OK}
  2750.     (6), access() checks for read and write permission.
  2751.  
  2752. ■returnvalue
  2753.  
  2754.     access() returns 0 if the file or directory is accessible in mode
  2755.     MODE.  Otherwise, access() set errno and returns -1.
  2756.  
  2757. ■errors
  2758.  
  2759. ■description
  2760.  
  2761. ■item EACCES
  2762.  
  2763.     Access to the file or directory is not permitted
  2764.  
  2765. ■item ENAMETOOLONG
  2766.  
  2767.     The file or directory name is too long
  2768.  
  2769. ■item ENOENT
  2770.  
  2771.     The file or directory does not exist
  2772.  
  2773. ■enddescription
  2774.  
  2775. ■restrictions
  2776.  
  2777.     access() does not work with devices (errno is set to ENOENT).
  2778.     X_OK is ignored.
  2779.  
  2780. ■seealso open() stat()
  2781.  
  2782.  
  2783. ■function alarm()
  2784. ■compat UNIX *
  2785. ■headers
  2786. #include <stdlib.h>
  2787. ■endheaders
  2788.  
  2789. ■param SEC
  2790. ■prototype
  2791. unsigned alarm (unsigned SEC);
  2792. ■endprototype
  2793.  
  2794.     Cause SIGALRM to be generated after SEC seconds have expired.
  2795.     alarm() returns immediately after setting the alarm clock.  There
  2796.     is only one alarm clock; when calling alarm() while the alarm
  2797.     clock is running the time will be reset to the new value.  If SEC
  2798.     is zero, the alarm clock will be stopped.
  2799.  
  2800. ■returnvalue
  2801.  
  2802.     alarm() returns the number of seconds remaining on the alarm clock
  2803.     before setting the new value.
  2804.  
  2805. ■implementation
  2806.  
  2807.     In a multithread process, there is a single alarm clock which
  2808.     can be set from all the threads.  SIGALRM is always generated and
  2809.     delivered in the main thread (thread 1).
  2810.  
  2811. ■restrictions
  2812.  
  2813.     alarm() is not available with the system call library sys.lib
  2814.     (■hpt{-Zsys}).
  2815.  
  2816.     Under DOS, SIGALRM is not delivered until return from DOS if the
  2817.     timer expired during a DOS call.
  2818.  
  2819. ■seealso raise() sigaction() signal() sleep() _sleep2()
  2820.  
  2821.  
  2822. ■function alloca()
  2823. ■headers
  2824. #include <alloca.h>
  2825. ■endheaders
  2826.  
  2827. ■param N
  2828. ■prototype
  2829. void *alloca (size_t N);
  2830. ■endprototype
  2831.  
  2832.     Allocate N bytes from the current stack frame.  The memory space
  2833.     allocated by alloca() will be freed on exit from the current
  2834.     function.  Do not pass the pointer returned by alloca() to free().
  2835.  
  2836. ■returnvalue
  2837.  
  2838.     alloca() returns a pointer to a block of memory in the stack.
  2839.  
  2840. ■restrictions
  2841.  
  2842.     This note applies only if you need stack probes (■hpt{-mprobe}
  2843.     option of GCC):
  2844.  
  2845.     If alloca() with constant argument occurs in the first statement
  2846.     of a function with less than 4096 bytes of local data or if two
  2847.     calls to alloca() with constant arguments occur twice in a row
  2848.     without accessing the memory pointed to by the return value of the
  2849.     first call, you have to change your code to make GCC generate
  2850.     correct stack probes.  This can be done by storing a dummy value
  2851.     to the return value of alloca().  Example:
  2852.  
  2853. ■example
  2854. p = alloca (0xf00);
  2855. {char *fix=alloca (0); *fix = 0;}
  2856. q = alloca (0xf00);
  2857. ■endexample
  2858.  
  2859. ■seealso malloc() _tmalloc()
  2860.  
  2861. ■samplecode
  2862. void test (void)
  2863. {
  2864.   char local[0xf00], *p;
  2865.  
  2866.   {char *fix=alloca (0); *fix = 0;}
  2867.   p = alloca (0xf00);
  2868.   /*...*/
  2869. }
  2870. ■endsamplecode
  2871.  
  2872.  
  2873. ■function asctime()
  2874. ■compat C90
  2875. ■headers
  2876. #include <time.h>
  2877. ■endheaders
  2878.  
  2879. ■param T
  2880. ■prototype
  2881. char *asctime (const struct tm *T);
  2882. ■endprototype
  2883.  
  2884.     Convert the time and date in the structure pointed to by T to a
  2885.     string.  A pointer to the string is returned.  There is only one
  2886.     memory location for the ctime() and asctime() results, a call to
  2887.     ctime() or asctime() overwrites the result of a previous calls to
  2888.     ctime() or asctime().  As localtime() is called by ctime(), the
  2889.     memory location shared by localtime(), gmtime(), and mktime() is
  2890.     overwritten.  The string looks like
  2891.  
  2892. ■example
  2893. "Sun Mar  2 07:59:18 1992\n"
  2894. ■endexample
  2895.  
  2896.     with a terminating null character.  All fields have fixed width.
  2897.  
  2898. ■returnvalue
  2899.  
  2900.     asctime() returns a pointer to a string containing the textual
  2901.     representation of its argument.
  2902.  
  2903. ■seealso ctime() gmtime() localtime() mktime()
  2904.  
  2905.  
  2906. ■function acos() asin() atan() atan2() acosl() asinl() atanl() atan2l()
  2907. ■compat C90 C9X
  2908. ■headers
  2909. #include <math.h>
  2910. ■endheaders
  2911.  
  2912. ■param X Y
  2913. ■prototype
  2914. double acos (double X);
  2915. double asin (double X);
  2916. double atan (double X);
  2917. double atan2 (double Y, double X);
  2918.  
  2919. long double acosl (long double X);
  2920. long double asinl (long double X);
  2921. long double atanl (long double X);
  2922. long double atan2l (long double Y, long double X);
  2923. ■endprototype
  2924.  
  2925.     asin(), acos(), and atan() compute the arc sine, arc cosine and
  2926.     arc tangent of X, respectively.  atan2() computes the arctangent
  2927.     of ■pa{Y}/■pa{X}, using the signs of Y and X to determine the
  2928.     quadrant.  If X is outside [-1,1], asin() and acos() return a NaN
  2929.     and set errno to EDOM.
  2930.  
  2931.     acosl(), asinl(), atanl() and atan2l() use the ■tt{long double}
  2932.     format.
  2933.  
  2934. ■returnvalue
  2935.  
  2936.     acos(), asin(), atan() and atan2() return the arc sine, arc cosine
  2937.     or arc tangent, respectively, of their argument.  These functions
  2938.     return a NaN on error.
  2939.  
  2940. ■seealso cos() sin() tan()
  2941.  
  2942.  
  2943. ■function assert()
  2944. ■compat C90
  2945. ■headers
  2946. #include <assert.h>
  2947. ■endheaders
  2948.  
  2949. ■param EXP FILE LINE
  2950. ■prototype
  2951. void assert (int EXP);
  2952. ■endprototype
  2953.  
  2954.     If the preprocessor macro NDEBUG is defined at the time <assert.h>
  2955.     is included, assert() does nothing.  Otherwise, if EXP is zero,
  2956.     the message
  2957.  
  2958. ■typewriter
  2959.     Assertion failed: ■pa{EXP}, file ■pa{FILE}, line ■pa{LINE}
  2960. ■endtypewriter
  2961.  
  2962.     is displayed and the program is aborted by calling abort().  EXP,
  2963.     FILE and LINE are replaced with EXP (as text), the source file
  2964.     name and the source line number, respectively.  If EXP is
  2965.     non-zero, nothing is done.
  2966.  
  2967. ■seealso abort()
  2968.  
  2969.  
  2970. ■function atexit()
  2971. ■compat C90
  2972. ■headers
  2973. #include <stdlib.h>
  2974. ■endheaders
  2975.  
  2976. ■param FUNC
  2977. ■prototype
  2978. int atexit (void (*FUNC)(void));
  2979. ■endprototype
  2980.  
  2981.     The function FUNC will be called when the process is terminated.
  2982.     The last function installed by calling atexit() will be called
  2983.     first.
  2984.  
  2985. ■returnvalue
  2986. ■description
  2987. ■item 0
  2988.     success
  2989. ■item -1
  2990.     error
  2991. ■enddescription
  2992.  
  2993. ■implementation
  2994.  
  2995.     Up to 32 functions can be installed.
  2996.  
  2997. ■seealso abort() exit() _exit()
  2998.  
  2999.  
  3000. ■function atof() atoi() atol() _atofl() _atoll()
  3001. ■compat C90
  3002. ■headers
  3003. #include <stdlib.h>
  3004. #include <math.h>  /* alternate include file for atof() */
  3005. ■endheaders
  3006.  
  3007. ■param STRING
  3008. ■prototype
  3009. double atof (const char *STRING);
  3010. int atoi (const char *STRING);
  3011. long atol (const char *STRING);
  3012.  
  3013. long double _atofl (const char *STRING);
  3014. long long _atoll (const char *STRING);
  3015. ■endprototype
  3016.  
  3017.     Convert the textual, decimal representation of a number in the
  3018.     string pointed to by STRING to a number.  Leading whitespace is
  3019.     ignored.  If the string cannot be converted, 0 (or 0.0) is
  3020.     returned.  The value of errno is not reliable.
  3021.  
  3022.     The decimal point character of the current locale is used by
  3023.     atof() and _atofl().
  3024.  
  3025.     _atofl() uses the ■tt{long double} format and is not an ISO C
  3026.     function.  _atoll() uses the ■tt{long long} format and is not an
  3027.     ISO C function.
  3028.  
  3029. ■returnvalue
  3030.  
  3031.     These functions return their argument as number.  They return 0
  3032.     (or 0.0) on error.
  3033.  
  3034. ■seealso _ltoa() scanf() setlocale() strtod() strtol()
  3035.  
  3036.  
  3037. ■function bcmp()
  3038. ■compat BSD
  3039. ■headers
  3040. #include <strings.h>
  3041. ■endheaders
  3042.  
  3043. ■param BUFFER1 BUFFER2 N
  3044. ■prototype
  3045. int bcmp (const void *BUFFER1, const void *BUFFER2, size_t N);
  3046. ■endprototype
  3047.  
  3048.     Compare the first N bytes at BUFFER1 to the first N bytes at
  3049.     BUFFER2.  If the two buffers are identical (or if N is zero), 0 is
  3050.     returned.  Otherwise, a non-zero value is returned.
  3051.  
  3052. ■returnvalue
  3053. ■description
  3054. ■item 0
  3055.     the buffers are identical
  3056. ■item non-0
  3057.     the buffers are different
  3058. ■enddescription
  3059.  
  3060. ■seealso memcmp()
  3061.  
  3062.  
  3063. ■function bcopy()
  3064. ■compat BSD
  3065. ■headers
  3066. #include <strings.h>
  3067. ■endheaders
  3068.  
  3069. ■param SRC DST N
  3070. ■prototype
  3071. void bcopy (const void *SRC, void *DST, size_t N);
  3072. ■endprototype
  3073.  
  3074.     Copy memory.  Copy N bytes from SRC to DST.
  3075.  
  3076. ■implementation
  3077.  
  3078.     The two regions may overlap.
  3079.  
  3080. ■seealso memcpy() memmove()
  3081.  
  3082.  
  3083. ■function _beginthread()
  3084. ■compat PC
  3085. ■headers
  3086. #include <stdlib.h>
  3087. ■endheaders
  3088.  
  3089. ■param START ARG STACK STACK_SIZE ARG_LIST
  3090. ■prototype
  3091. int _beginthread (void (*START)(void *ARG), void *STACK, unsigned STACK_SIZE,
  3092.                   void *ARG_LIST);
  3093. ■endprototype
  3094.  
  3095.     Start a thread.  START is the start address (a function).
  3096.     ARG_LIST will be passed in the ARG parameter of the START
  3097.     function.  STACK is ignored, using NULL is recommended.
  3098.     STACK_SIZE is the size of the stack for the new thread.  When the
  3099.     START function returns, the thread is terminated by an automatic
  3100.     call to _endthread().  A thread can also terminate itself by
  3101.     calling _endthread().  If successful, _beginthread() returns the
  3102.     thread ID.  On error, _beginthread() sets errno and returns -1.
  3103.     The stack allocated for the new thread is completely committed,
  3104.     that is, stack probes are not required.
  3105.  
  3106.     _beginthread() is preferred over DosCreateThread because it
  3107.     initializes the C library.
  3108.  
  3109. ■returnvalue
  3110.  
  3111.     _beginthread() returns the thread ID of the new thread.  It
  3112.     returns -1 on error.
  3113.  
  3114. ■restrictions
  3115.  
  3116.     _beginthread() is available in the multithread libraries only
  3117.     (-Zmt, -Zmts, or -Zmtd).
  3118.  
  3119. ■hints
  3120.  
  3121.      STACK_SIZE should be at least 32768.  Specifying a big stack size
  3122.      doesn't hurt.
  3123.  
  3124. ■seealso _endthread() _gettid() _threadid _threadstore()
  3125.  
  3126.  
  3127. ■function brk()
  3128. ■compat UNIX
  3129. ■headers
  3130. #include <stdlib.h>
  3131. ■endheaders
  3132.  
  3133. ■param ADDR
  3134. ■prototype
  3135. void *brk (void *ADDR);
  3136. ■endprototype
  3137.  
  3138.     Change the end address of the data segment to ADDR.  On success,
  3139.     brk() returns 0, cast as pointer.  Otherwise, -1 cast as pointer
  3140.     is returned and errno set to ENOMEM.  Please don't use brk() --
  3141.     use malloc() instead for memory allocation.
  3142.  
  3143.     brk() never allocates non-contiguous memory; in consequence,
  3144.     allocation with brk() is limited by the size of the memory object
  3145.     of the heap.  On the other hand, sbrk() may add memory objects to
  3146.     the heap if non-contiguous allocation has been enabled with
  3147.     _uflags().  Setting back the memory limit into a gap produced
  3148.     non-contiguous allocation by sbrk() is not possible.  However,
  3149.     brk() can be used to deallocate memory objects allocated by
  3150.     sbrk().
  3151.  
  3152. ■returnvalue
  3153. ■list
  3154. ■item ■tt{(void *)0}
  3155.     success
  3156. ■item ■tt{(void *)-1}
  3157.     error
  3158. ■endlist
  3159.  
  3160. ■seealso malloc() sbrk() _uflags() ulimit()
  3161.  
  3162.  
  3163. ■function bsearch()
  3164. ■compat C90
  3165. ■headers
  3166. #include <stdlib.h>
  3167. ■endheaders
  3168.  
  3169. ■param KEY BASE NUM WIDTH COMPARE ELEMENT
  3170. ■prototype
  3171. void *bsearch (const void *KEY, const void *BASE, size_t NUM, size_t WIDTH,
  3172.                int (*COMPARE)(const void *KEY, const void *ELEMENT));
  3173. ■endprototype
  3174.  
  3175.     Perform a binary search on the sorted array BASE to find KEY.  The
  3176.     array has NUM elements of size WIDTH bytes each.  bsearch() calls
  3177.     COMPARE to compare an array element pointed to by ELEMENT with
  3178.     KEY.  COMPARE should return 0 if KEY and ELEMENT are equal; a
  3179.     negative value, if KEY is smaller than ELEMENT; a positive value
  3180.     if KEY is greater than ELEMENT with respect to the sorting order
  3181.     of BASE.  If there are multiple occurrences of KEY in BASE,
  3182.     bsearch() returns a pointer to any one of the entries.  If the
  3183.     array pointed to by BASE is not sorted, bsearch() does not work.
  3184.  
  3185. ■returnvalue
  3186.  
  3187.     bsearch() returns a pointer to an occurrence of KEY in
  3188.     the array.  If KEY is not found, bsearch() returns NULL.
  3189.  
  3190. ■seealso qsort()
  3191.  
  3192.  
  3193. ■function bzero()
  3194. ■compat BSD
  3195. ■headers
  3196. #include <strings.h>
  3197. ■endheaders
  3198.  
  3199. ■param BUFFER N
  3200. ■prototype
  3201. void bzero (void *BUFFER, size_t N);
  3202. ■endprototype
  3203.  
  3204.     Set N bytes at BUFFER to 0.
  3205.  
  3206. ■seealso calloc() memset()
  3207.  
  3208.  
  3209. ■function calloc()
  3210. ■compat C90
  3211. ■headers
  3212. #include <stdlib.h>
  3213. ■endheaders
  3214.  
  3215. ■param ELEMENTS SIZE
  3216. ■prototype
  3217. void *calloc (size_t ELEMENTS, size_t SIZE);
  3218. ■endprototype
  3219.  
  3220.     Allocate a block of memory big enough for holding ELEMENTS
  3221.     elements of SIZE bytes each.  calloc() fills the block with zeros.
  3222.     If there is an error, calloc() returns NULL.
  3223.  
  3224. ■implementation
  3225.  
  3226.     calloc() allocates from the default heap of the current thread.
  3227.     If at least one argument is zero, calloc() returns a non-NULL
  3228.     pointer if there's enough space left in the heap for a block of
  3229.     the minimum size.
  3230.  
  3231. ■returnvalue
  3232.  
  3233.     calloc() returns a pointer to a newly allocated block of memory.
  3234.     On error, calloc() returns NULL.
  3235.  
  3236. ■seealso free() malloc() _msize() _tcalloc() _ucalloc() _udefault()
  3237.  
  3238.  
  3239. ■function cbrt() _cbrtl()
  3240. ■headers
  3241. #include <math.h>
  3242. ■endheaders
  3243.  
  3244. ■param X
  3245. ■prototype
  3246. double cbrt (double X);
  3247. long double _cbrtl (long double X);
  3248. ■endprototype
  3249.  
  3250.     Compute the cube root of X.  This is done by calling
  3251.     pow() and adjusting the sign.
  3252.  
  3253.     _cbrtl() uses the ■tt{long double} format and is an ■bf{emx}-specific
  3254.     function.
  3255.  
  3256. ■returnvalue
  3257.  
  3258.     cbrt() returns the cube root of its argument.
  3259.  
  3260. ■seealso pow() sqrt()
  3261.  
  3262.  
  3263. ■function ceil() ceill()
  3264. ■compat C90 C9X
  3265. ■headers
  3266. #include <math.h>
  3267. ■endheaders
  3268.  
  3269. ■param X
  3270. ■prototype
  3271. double ceil (double X);
  3272. long double ceill (long double X);
  3273. ■endprototype
  3274.  
  3275.     Compute the smallest integer that is greater than or equal to X
  3276.     (round up).
  3277.  
  3278.     ceill() uses the ■tt{long double} format.
  3279.  
  3280. ■returnvalue
  3281.  
  3282.     ceil() returns as floating-point number the smallest integer that
  3283.     is greater than or equal to X.
  3284.  
  3285. ■seealso floor() rint() trunc()
  3286.  
  3287.  
  3288. ■function cfgetispeed() cfgetospeed()
  3289. ■compat POSIX.1 *
  3290. ■headers
  3291. #include <termios.h>
  3292. ■endheaders
  3293.  
  3294. ■param PTERMIOS
  3295. ■prototype
  3296. speed_t cfgetispeed (const struct termios *ptermios);
  3297. speed_t cfgetospeed (const struct termios *ptermios);
  3298. ■endprototype
  3299.  
  3300.     cfgetispeed() returns the input bit rate stored in the structure
  3301.     pointed to by PTERMIOS.
  3302.  
  3303.     cfgetospeed() returns the output bit rate stored in the structure
  3304.     pointed to by PTERMIOS.
  3305.  
  3306.     See `■hpt{General terminal interface}' for details.
  3307.  
  3308. ■returnvalue
  3309.  
  3310.     cfgetispeed() and cfgetospeed() return a bit rate.  Bit rates are
  3311.     represented by the symbols ■tt{B0} through ■tt{B38400}.
  3312.  
  3313. ■restrictions
  3314.  
  3315.     Asynchronous lines are not yet supported.
  3316.  
  3317. ■seealso cfsetispeed() cfsetospeed() tcgetattr() tcsetattr()
  3318.  
  3319.  
  3320. ■function cfsetispeed() cfsetospeed()
  3321. ■compat POSIX.1 *
  3322. ■headers
  3323. #include <termios.h>
  3324. ■endheaders
  3325.  
  3326. ■param PTERMIOS SPEED
  3327. ■prototype
  3328. int cfsetispeed (struct termios *ptermios, speed_t speed);
  3329. int cfsetospeed (struct termios *ptermios, speed_t speed);
  3330. ■endprototype
  3331.  
  3332.     cfsetispeed() and cfsetospeed() set the input bit rate and output
  3333.     bit rate, respectively, in the structure pointed to by PTERMIOS
  3334.     from the value of SPEED.  Bit rates are represented by the symbols
  3335.     ■tt{B0} through ■tt{B38400}.
  3336.  
  3337.     See `■hpt{General terminal interface}' for details.
  3338.  
  3339. ■returnvalue
  3340.  
  3341.     cfsetispeed() and cfsetospeed() return 0 if successful.
  3342.     Otherwise, cfsetispeed() and cfsetospeed() set errno and return
  3343.     -1.
  3344.  
  3345. ■errors
  3346. ■description
  3347. ■item EINVAL
  3348.   The bit rate SPEED is not valid.
  3349. ■enddescription
  3350.  
  3351. ■restrictions
  3352.  
  3353.     Asynchronous lines are not yet supported.
  3354.  
  3355. ■seealso cfgetispeed() cfgetospeed() tcgetattr() tcsetattr()
  3356.  
  3357.  
  3358. ■function chdir()
  3359. ■compat UNIX
  3360. ■headers
  3361. #include <stdlib.h>
  3362. ■endheaders
  3363.  
  3364. ■param NAME
  3365. ■prototype
  3366. int chdir (const char *NAME);
  3367. ■endprototype
  3368.  
  3369.     Change to directory whose name is in the string pointed to by
  3370.     NAME.  If the name contains a drive letter, the working directory
  3371.     on that drive is changed, but the selected drive does not change.
  3372.  
  3373.     chdir() properly handles DBCS characters.
  3374.  
  3375. ■returnvalue
  3376. ■description
  3377. ■item 0
  3378.     success
  3379. ■item -1
  3380.     error
  3381. ■enddescription
  3382.  
  3383. ■restrictions
  3384.  
  3385.     Under DOS, the current working directory is not a property of a
  3386.     process, it is a system-wide property.  That may change in a future
  3387.     release of emx.  ■tt{chdir ("..")} fails if the current working
  3388.     directory is the root directory.
  3389.  
  3390. ■seealso _chdir2() getcwd() _nls_init()
  3391.  
  3392.  
  3393. ■function _chdir2()
  3394. ■compat emx
  3395. ■headers
  3396. #include <stdlib.h>
  3397. ■endheaders
  3398.  
  3399. ■param NAME
  3400. ■prototype
  3401. int _chdir2 (const char *NAME);
  3402. ■endprototype
  3403.  
  3404.     Change to the directory whose name is in the string pointed to by
  3405.     NAME.  If the name contains a drive letter, that drive is selected
  3406.     before changing to the directory.  If the name contains a drive
  3407.     letter, the directory can be omitted:
  3408.  
  3409.     _chdir2() properly handles DBCS characters.
  3410.  
  3411. ■example
  3412. _chdir2 ("c:")
  3413. ■endexample
  3414.  
  3415.     is equivalent to
  3416.  
  3417. ■example
  3418. _chdrive ('C')
  3419. ■endexample
  3420.  
  3421. ■returnvalue
  3422. ■description
  3423. ■item 0
  3424.     success
  3425. ■item -1
  3426.     error
  3427. ■enddescription
  3428.  
  3429. ■restrictions
  3430.  
  3431.     Under DOS, the current working directory and the default drive is
  3432.     not a property of a process, it's a system-wide property.  That
  3433.     may change in a future release of emx.  ■tt{_chdir ("..")} fails
  3434.     if the current working directory is the root directory.
  3435.  
  3436.  
  3437. ■seealso chdir() getcwd() _nls_init()
  3438.  
  3439.  
  3440. ■function _chdrive()
  3441. ■compat PC
  3442. ■headers
  3443. #include <stdlib.h>
  3444. ■endheaders
  3445.  
  3446. ■param DRIVE
  3447. ■prototype
  3448. int _chdrive (char DRIVE);
  3449. ■endprototype
  3450.  
  3451.     Make the disk drive DRIVE the default drive.  DRIVE must be in
  3452.     ■tt{'A'} through ■tt{'Z'} or in ■tt{'a'} through ■tt{'z'}.
  3453.  
  3454. ■returnvalue
  3455.  
  3456.     _chdrive() always returns 0, even if the drive does not exist.
  3457.  
  3458. ■seealso _chdir2() _getdrive()
  3459.  
  3460.  
  3461. ■function chmod()
  3462. ■compat UNIX
  3463. ■headers
  3464. #include <io.h>
  3465. #include <sys/stat.h>
  3466. ■endheaders
  3467.  
  3468. ■param NAME PMODE
  3469. ■prototype
  3470. int chmod (const char *NAME, int PMODE);
  3471. ■endprototype
  3472.  
  3473.     Change permission settings of the file whose name is in the string
  3474.     pointed to by NAME to PMODE.  There is only one permission bit
  3475.     under OS/2 and DOS, the read-only attribute.  The read-only bit is
  3476.     set if S_IWRITE is not included in PMODE.  Either specify
  3477.     ■tt{S_IREAD|S_IWRITE} or ■tt{S_IREAD} for PMODE.
  3478.  
  3479. ■returnvalue
  3480. ■description
  3481. ■item 0
  3482.     success
  3483. ■item -1
  3484.     error
  3485. ■enddescription
  3486.  
  3487. ■restrictions
  3488.  
  3489.     Only the S_IWRITE bit of PMODE is used.
  3490.  
  3491. ■seealso creat() open() stat() umask()
  3492.  
  3493.  
  3494. ■function chsize()
  3495. ■compat PC
  3496. ■headers
  3497. #include <io.h>
  3498. ■endheaders
  3499.  
  3500. ■param HANDLE SIZE
  3501. ■prototype
  3502. int chsize (int HANDLE, long SIZE);
  3503. ■endprototype
  3504.  
  3505.     Change the length of the file associated with HANDLE to SIZE
  3506.     bytes.  The position of the file pointer is undefined after
  3507.     calling this function.  If SIZE is greater than the current length
  3508.     of the file, bytes of zeros are appended.  HANDLE must be open for
  3509.     writing.
  3510.  
  3511. ■returnvalue
  3512. ■description
  3513. ■item 0
  3514.     success
  3515. ■item -1
  3516.     error
  3517. ■enddescription
  3518.  
  3519. ■seealso ftruncate() lseek()
  3520.  
  3521.  
  3522. ■function _clear87()
  3523. ■compat PC
  3524. ■headers
  3525. #include <float.h>
  3526. ■endheaders
  3527.  
  3528. ■prototype
  3529. unsigned _clear87 (void);
  3530. ■endprototype
  3531.  
  3532.     Clear the coprocessor status word.
  3533.  
  3534. ■returnvalue
  3535.  
  3536.     _clear87() returns the previous value of the status word.
  3537.  
  3538. ■seealso _control87() _fpreset() _status87()
  3539.  
  3540.  
  3541. ■function clearerr()
  3542. ■compat C90
  3543. ■headers
  3544. #include <stdio.h>
  3545. ■endheaders
  3546.  
  3547. ■param STREAM
  3548. ■prototype
  3549. void clearerr (FILE *STREAM);
  3550. ■endprototype
  3551.  
  3552.     Clear the error and end-of-file indicators of STREAM.
  3553.  
  3554. ■seealso ferror() feof()
  3555.  
  3556.  
  3557. ■function clock()
  3558. ■compat C90
  3559. ■headers
  3560. #include <time.h>
  3561. ■endheaders
  3562.  
  3563. ■prototype
  3564. clock_t clock (void);
  3565. ■endprototype
  3566.  
  3567.     clock() returns the amount of processor time (timer ticks) used by
  3568.     the calling process since the process has been started.  There are
  3569.     CLOCKS_PER_SEC timer ticks per second.
  3570.  
  3571. ■returnvalue
  3572.  
  3573.     clock() returns the number of timer ticks used by the process.
  3574.  
  3575. ■restrictions
  3576.  
  3577.     clock() returns the time elapsed, not the CPU time.
  3578.  
  3579. ■seealso time()
  3580.  
  3581.  
  3582. ■function close()
  3583. ■compat UNIX
  3584. ■headers
  3585. #include <io.h>
  3586. ■endheaders
  3587.  
  3588. ■param HANDLE
  3589. ■prototype
  3590. int close (int HANDLE);
  3591. ■endprototype
  3592.  
  3593.     Close the file associated with the handle HANDLE.
  3594.  
  3595. ■returnvalue
  3596. ■description
  3597. ■item 0
  3598.     success
  3599. ■item -1
  3600.     error
  3601. ■enddescription
  3602.  
  3603. ■seealso dup() open()
  3604.  
  3605.  
  3606. ■function _control87()
  3607. ■compat PC
  3608. ■headers
  3609. #include <float.h>
  3610. ■endheaders
  3611.  
  3612. ■param NEW_CW MASK
  3613. ■prototype
  3614. unsigned _control87 (unsigned NEW_CW, unsigned MASK);
  3615. ■endprototype
  3616.  
  3617.     Set the coprocessor control word.  Bits of the control word set in
  3618.     MASK are replaced with the matching bits of NEW_CW:
  3619.  
  3620. ■example
  3621. cw = ((cw & ~mask) | (new_cw & mask));
  3622. ■endexample
  3623.  
  3624.     If MASK is 0, the control word is not changed.  MASK should be one
  3625.     of the following symbols:
  3626. ■description
  3627. ■item MCW_EM
  3628.   Exception masks
  3629. ■item MCW_IC
  3630.   Infinity control (ignored by the 387 and later)
  3631. ■item MCW_RC
  3632.   Rounding control
  3633. ■item MCW_PC
  3634.   Precision control
  3635. ■enddescription
  3636.   To pass multiple values in NEW_CW, use the ■tt{|} operator to
  3637.   combine the symbols described below.
  3638.  
  3639.   If MASK includes MCW_EM, any combination of the following symbols,
  3640.   including none (0), can be used in NEW_CW.  If one of these symbol
  3641.   is included, the corresponding exception is masked off, that is, the
  3642.   coprocessor will take a corrective action and continue.  If an
  3643.   exception is not masked off, SIGFPE will be generated by that
  3644.   exception.
  3645. ■description
  3646. ■item EM_INVALID
  3647.   Invalid operation (corrective action: return a NaN)
  3648. ■item EM_DENORMAL
  3649.   Denormalized operand (corrective action: use
  3650.   gradual underflow)
  3651. ■item EM_ZERODIVIDE
  3652.   Division by zero (corrective action: return infinity)
  3653. ■item EM_OVERFLOW
  3654.   Overflow (corrective action: return infinity)
  3655. ■item EM_UNDERFLOW
  3656.   Underflow (corrective action: return a denormal or zero)
  3657. ■item EM_INEXACT
  3658.   Precision lost (corrective action: ignore)
  3659. ■enddescription
  3660.   By default, all floating-point exceptions are masked off.
  3661.  
  3662.   If MASK includes MCW_RC, exactly one of the following symbols should
  3663.   be used in NEW_CW:
  3664. ■description
  3665. ■item RC_NEAR
  3666.   Round to nearest or even (default)
  3667. ■item RC_DOWN
  3668.   Round down toward -infinity
  3669. ■item RC_UP
  3670.   Round up toward infinity
  3671. ■item RC_CHOP
  3672.   Chop by truncating toward zero
  3673. ■enddescription
  3674.  
  3675.   If MASK includes MCW_PC, exactly one of the following symbols should
  3676.   be used in NEW_CW:
  3677. ■description
  3678. ■item PC_24
  3679.   24-bit mantissa
  3680. ■item PC_53
  3681.   53-bit mantissa
  3682. ■item PC_64
  3683.   64-bit mantissa (default)
  3684. ■enddescription
  3685.   Only addition, subtraction, multiplication, division, and sqrt() are
  3686.   affected by the precision-control bits.  Note that IEEE 754 requires
  3687.   PC_53, which is not the default setting.
  3688.  
  3689. ■returnvalue
  3690.  
  3691.     _control87() returns the previous value of the control word.
  3692.  
  3693. ■seealso _clear87() _fpreset()
  3694.  
  3695. ■samplecode
  3696. _control87 (PC_53, MCW_PC);     /* Round to 64-bit double */
  3697. ■endsamplecode
  3698.  
  3699.  
  3700. ■function copysign() copysignf() copysignl()
  3701. ■compat C9X
  3702. ■headers
  3703. #include <math.h>
  3704. ■endheaders
  3705.  
  3706. ■param X Y
  3707. ■prototype
  3708. double copysign (double X, double Y);
  3709. float copysignf (float X, float Y);
  3710. long double copysignl (long double X, long double Y);
  3711. ■endprototype
  3712.  
  3713.     Return a value with the magnitude of X and the sign bit of Y.
  3714.  
  3715. ■returnvalue
  3716.  
  3717.     copysign() returns a value with the magnitude of X and the sign
  3718.     bit of Y.
  3719.  
  3720.  
  3721. ■seealso fpclassify() nextafter() signbit()
  3722.  
  3723.  
  3724. ■function _core()
  3725. ■compat emx *
  3726. ■headers
  3727. #include <stdlib.h>
  3728. ■endheaders
  3729.  
  3730. ■param HANDLE
  3731. ■prototype
  3732. int _core (int HANDLE);
  3733. ■endprototype
  3734.  
  3735.     Write a core dump to the file associated with HANDLE.  HANDLE must
  3736.     be open for writing.  The core dump file can be used later for
  3737.     debugging or for creating another .exe file which includes the
  3738.     data as saved when _core() was called.
  3739.  
  3740. ■returnvalue
  3741. ■description
  3742. ■item 0
  3743.     success
  3744. ■item -1
  3745.     error
  3746. ■enddescription
  3747.  
  3748. ■restrictions
  3749.  
  3750.     _core() works only in programs linked with ld.  It does not work
  3751.     in programs linked with LINK386.  _core() is not available with
  3752.     the system call library sys.lib (■hpt{-Zsys}).
  3753.  
  3754. ■seealso close() open() raise() sigaction() signal()
  3755.  
  3756.  
  3757. ■function cos() sin() tan() cosl() sinl() tanl()
  3758. ■compat C90 C9X
  3759. ■headers
  3760. #include <math.h>
  3761. ■endheaders
  3762.  
  3763. ■param X
  3764. ■prototype
  3765. double cos (double X);
  3766. double sin (double X);
  3767. double tan (double X);
  3768.  
  3769. long double cosl (long double X);
  3770. long double sinl (long double X);
  3771. long double tanl (long double X);
  3772. ■endprototype
  3773.  
  3774.     cos(), sin(), and tan() compute the sine, cosine and tangent of X,
  3775.     respectively.
  3776.  
  3777.     cosl(), sinl() and tanl() use the ■tt{long double} format.
  3778.  
  3779. ■returnvalue
  3780.  
  3781.     The cos(), sin() and tan() functions return the cosine, sine and
  3782.     tangent, respectively, of their argument.
  3783.  
  3784. ■implementation
  3785.  
  3786.     If the absolute value of X is greater than or equal to 2^63,
  3787.     sin(), sinl(), tan(), and tanl() return 0.0, cos() and cosl()
  3788.     return 1.0.
  3789.  
  3790. ■seealso acos() asin() atan()
  3791.  
  3792.  
  3793. ■function cosh() sinh() tanh() coshl() sinhl() tanhl()
  3794. ■compat C90 C9X
  3795. ■headers
  3796. #include <math.h>
  3797. ■endheaders
  3798.  
  3799. ■param X
  3800. ■prototype
  3801. double cosh (double X);
  3802. double sinh (double X);
  3803. double tanh (double X);
  3804.  
  3805. long double coshl (long double X);
  3806. long double sinhl (long double X);
  3807. long double tanhl (long double X);
  3808. ■endprototype
  3809.  
  3810.     cosh(), sinh(), and tanh() compute the hyperbolic cosine,
  3811.     hyperbolic sine and hyperbolic tangent of X, respectively.  On
  3812.     overflow, +INF or -INF is returned and errno set to ERANGE.
  3813.  
  3814.     coshl(), sinhl() and tanhl() use the ■tt{long double} format.
  3815.  
  3816. ■returnvalue
  3817.  
  3818.     The cosh(), sinh() and tanh() functions return the hyperbolic
  3819.     cosine, hyperbolic sine and hyperbolic tangent, respectively, of
  3820.     their argument.  These functions return NaN on error.
  3821.  
  3822. ■seealso exp()
  3823.  
  3824.  
  3825. ■function creat()
  3826. ■compat UNIX
  3827. ■headers
  3828. #include <io.h>
  3829. #include <sys/stat.h>
  3830. ■endheaders
  3831.  
  3832. ■param NAME PMODE
  3833. ■prototype
  3834. int creat (const char *NAME, int PMODE);
  3835. ■endprototype
  3836.  
  3837.     Create a file whose name is in the string pointed to by NAME with
  3838.     permission settings PMODE.  This is equivalent to
  3839.  
  3840. ■typewriter
  3841.   open (■pa{name}, O_WRONLY|O_TRUNC|O_CREAT, ■pa{pmode})
  3842. ■endtypewriter
  3843.  
  3844. ■returnvalue
  3845.  
  3846.     creat() returns a file handle of the new file.  On error, creat()
  3847.     sets errno and returns -1.
  3848.  
  3849. ■seealso open()
  3850.  
  3851.  
  3852. ■function _crlf()
  3853. ■compat emx
  3854. ■headers
  3855. #include <io.h>
  3856. ■endheaders
  3857.  
  3858. ■param BUF SIZE NEW_SIZE
  3859. ■prototype
  3860. int _crlf (char *BUF, size_t SIZE, size_t *NEW_SIZE);
  3861. ■endprototype
  3862.  
  3863.     Translate CR/LF pairs to newline characters.  The conversion is
  3864.     done in-place in the array of SIZE characters pointed to by BUF.
  3865.     The new size is stored to *NEW_SIZE.
  3866.  
  3867. ■returnvalue
  3868.  
  3869.     _crlf() returns 1 if the buffer ends with a CR.  Otherwise,
  3870.     _crlf() returns 0.
  3871.  
  3872. ■seealso fread() _fsetmode() read() setmode()
  3873.  
  3874.  
  3875. ■function _crotl() _crotr()
  3876. ■compat VAC++
  3877. ■headers
  3878. #include <sys/builtin.h>
  3879. ■endheaders
  3880.  
  3881. ■param VALUE SHIFT
  3882. ■prototype
  3883. unsigned char _crotl (unsigned char VALUE, int SHIFT);
  3884. unsigned char _crotr (unsigned char VALUE, int SHIFT);
  3885. ■endprototype
  3886.  
  3887.     _crotl() returns VALUE (8 bits) rotated left by SHIFT bits.  If
  3888.     SHIFT is 1, bit 6 is returned as bit 7, bit 5 is returned as bit
  3889.     6, and so on, bit 0 is returned as bit 1, and bit 7 is returned as
  3890.     bit 0.
  3891.  
  3892.     _crotr() returns VALUE (8 bits) rotated right by SHIFT bits.  If
  3893.     SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
  3894.     1, and so on, bit 7 is returned as bit 6, and bit 0 is returned as
  3895.     bit 7.
  3896.  
  3897.     SHIFT should be 0 through 7.
  3898.  
  3899.     These functions are implemented as inline functions.
  3900.  
  3901. ■seealso _lrotl() _lrotr() _srotl() _srotr()
  3902.  
  3903.  
  3904. ■function _CRT_init() _CRT_term()
  3905. ■compat OS/2
  3906.  
  3907. ■prototype
  3908. int _CRT_init (void);
  3909. void _CRT_term (void);
  3910. ■endprototype
  3911.  
  3912.     These two functions are provided for being called from
  3913.     _DLL_InitTerm(), the DLL initialization and termination function.
  3914.  
  3915.     _CRT_init() initializes the C run-time library if it has not yet
  3916.     been initialized.
  3917.  
  3918.     _CRT_term() terminates the C run-time library if it has not yet
  3919.     been terminated.
  3920.  
  3921. ■returnvalue
  3922.  
  3923.     _CRT_init() returns
  3924.  
  3925. ■description
  3926. ■item 0
  3927.     if successful
  3928. ■item -1
  3929.     on error
  3930. ■enddescription
  3931.  
  3932. ■seealso _DLL_InitTerm() __ctordtorInit() __ctordtorTerm()
  3933.  
  3934. ■samplefile /emx/test/testdll1.c
  3935.  
  3936.  
  3937. ■function ctime()
  3938. ■compat C90
  3939. ■headers
  3940. #include <time.h>
  3941. ■endheaders
  3942.  
  3943. ■param T
  3944. ■prototype
  3945. char *ctime (const time_t *T);
  3946. ■endprototype
  3947.  
  3948.     Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
  3949.     Coordinated Universal Time (UTC, GMT) in the variable pointed to
  3950.     by T to a string representing that moment for the local timezone.
  3951.     A pointer to the string is returned.  There is only one memory
  3952.     location for the ctime() and asctime() results, a call to ctime()
  3953.     or asctime() overwrites the result of a previous calls to ctime()
  3954.     or asctime().  As localtime() is called by ctime(), the memory
  3955.     location shared by localtime(), gmtime(), and mktime() is
  3956.     overwritten.  The string looks like
  3957.  
  3958. ■example
  3959. "Sun Mar  2 07:59:18 1992\n"
  3960. ■endexample
  3961.  
  3962.     with a terminating null character.  All fields have fixed width.
  3963.  
  3964. ■returnvalue
  3965.  
  3966.     ctime() returns a pointer to a string containing the textual
  3967.     representation of its argument.
  3968.  
  3969. ■seealso asctime() gmtime() localtime() mktime()
  3970.  
  3971.  
  3972. ■function __ctordtorInit() __ctordtorTerm()
  3973. ■compat OS/2
  3974.  
  3975. ■prototype
  3976. void __ctordtorInit (void);
  3977. void __ctordtorTerm (void);
  3978. ■endprototype
  3979.  
  3980.     These two functions are provided for being called from
  3981.     _DLL_InitTerm(), the DLL initialization and termination function.
  3982.  
  3983.     __ctordtorInit() invokes the constructors for the static objects
  3984.     of the DLL.  You should call __ctordtorInit() after calling
  3985.     _CRT_init().
  3986.  
  3987.     __ctordtorTerm() invokes the destructors for the static objects of
  3988.     the DLL.  You should call __ctordtorTerm() before calling
  3989.     _CRT_term().
  3990.  
  3991. ■seealso _CRT_init() _CRT_term() _DLL_InitTerm()
  3992.  
  3993.  
  3994. ■function cuserid()
  3995. ■compat UNIX
  3996. ■headers
  3997. #include <stdio.h>              /* prototype and L_cuserid constant */
  3998. #include <unistd.h>             /* prototype */
  3999. ■endheaders
  4000.  
  4001.  
  4002. ■param BUFFER
  4003. ■prototype
  4004. char *cuserid (char *BUFFER);
  4005. ■endprototype
  4006.  
  4007.     Return the login name of the owner of current process.  If BUFFER
  4008.     is NULL, a pointer to a statically allocated buffer is returned.
  4009.     Otherwise, the login name is copied to the array pointed to by
  4010.     BUFFER.  The array must be big enough to hold L_cuserid
  4011.     characters.  If there is an error, NULL is returned.
  4012.  
  4013. ■implementation
  4014.  
  4015.     The emx implementation of cuserid() takes the login name from the
  4016.     USER environment variable.  If that environment variable is not
  4017.     defined, the login name is ■tt{"root"}.
  4018.  
  4019. ■returnvalue
  4020.  
  4021.     cuserid() returns BUFFER if BUFFER is not a null pointer.
  4022.     cuserid() returns a pointer to a statically allocated buffer if
  4023.     BUFFER is NULL.  cuserid() returns NULL on error.
  4024.  
  4025. ■seealso getpwent()
  4026.  
  4027.  
  4028. ■function __cxchg() __lxchg() __sxchg() 
  4029. ■compat VAC++
  4030. ■headers
  4031. #include <sys/builtin.h>
  4032. ■endheaders
  4033.  
  4034. ■param P V
  4035. ■prototype
  4036. signed char __cxchg (volatile signed char *p, signed char v);
  4037. int         __lxchg (volatile int *p,         int v);
  4038. short       __sxchg (volatile short *p,       short v);
  4039. ■endprototype
  4040.  
  4041.     These functions atomically store V in the object pointed to by P
  4042.     and return the previous value of that object.  As this operation
  4043.     is done atomically, these functions can be used for implementing
  4044.     semaphores.  In fact, __cxchg() is used for implementing _fmutex
  4045.     and _smutex semaphores.
  4046.  
  4047.     These functions are implemented as inline functions.
  4048.  
  4049. ■returnvalue
  4050.  
  4051.     These functions return the previous value of the object pointed to
  4052.     by P.
  4053.  
  4054. ■seealso _fmutex_request() _smutex_request()
  4055.  
  4056.  
  4057. ■function _defext()
  4058. ■compat emx
  4059. ■headers
  4060. #include <stdlib.h>
  4061. ■endheaders
  4062.  
  4063. ■param DST EXT
  4064. ■prototype
  4065. void _defext (char *DST, const char *EXT);
  4066. ■endprototype
  4067.  
  4068.     Add the default extension EXT to the file name pointed to by DST.
  4069.     If the file name part of the string pointed to by DST contains an
  4070.     extension (including the empty extension), nothing will be done.
  4071.     Otherwise, a dot and the string pointed to by EXT will be
  4072.     appended.
  4073.  
  4074.     _defext() properly handles DBCS characters.
  4075.  
  4076. ■seealso _getext() _nls_init() _remext() _splitpath()
  4077.  
  4078.  
  4079. ■function difftime()
  4080. ■compat C90
  4081. ■headers
  4082. #include <time.h>
  4083. ■endheaders
  4084.  
  4085. ■param T1 T0
  4086. ■prototype
  4087. double difftime (time_t T1, time_t T0);
  4088. ■endprototype
  4089.  
  4090.     Compute the difference (in seconds) between two time values.
  4091.  
  4092. ■returnvalue
  4093.  
  4094.     difftime() returns the difference (in seconds) ■pa{T1}-■pa{T0}
  4095.     between T0 and T1.
  4096.  
  4097.  
  4098. ■function __disable() __enable()
  4099. ■compat VAC++
  4100. ■headers
  4101. #include <sys/builtin.h>
  4102. ■endheaders
  4103.  
  4104. ■prototype
  4105. void __disable (void);
  4106. void __enable (void);
  4107. ■endprototype
  4108.  
  4109.     __disable() disables interrupts, __enable() enables interrupts.
  4110.     Note that these functions cause an access violation unless dirty
  4111.     tricks are used (see xf86sup.sys).
  4112.  
  4113.     These functions are implemented as inline functions.
  4114.  
  4115.  
  4116. ■function div() ldiv()
  4117. ■compat C90
  4118. ■headers
  4119. #include <stdlib.h>
  4120. ■endheaders
  4121.  
  4122. ■param NUM DEN
  4123. ■prototype
  4124. div_t div (int NUM, int DEN);
  4125. ldiv_t ldiv (long NUM, long DEN);
  4126. ■endprototype
  4127.  
  4128.     Perform an integer division, dividing NUM by DEN.  The quotient
  4129.     and the remainder are returned in the quot and rem fields,
  4130.     respectively.
  4131.  
  4132.     The following table shows the signs of quot and rem depending on
  4133.     the signs of NUM and DEN:
  4134.  
  4135. ■example
  4136. NUM DEN │ quot rem
  4137. ────────┼─────────
  4138.  +   +  │  +    +
  4139.  +   -  │  -    +
  4140.  -   +  │  -    -
  4141.  -   -  │  +    -
  4142. ■endexample
  4143.  
  4144.     ■bf{Note:} Do not use the -fpcc-struct-return option of GCC.
  4145.  
  4146. ■returnvalue
  4147.  
  4148.     div() and ldiv() return a structure which contains the quotient
  4149.     and the remainder in the quot and rem fields, respectively.
  4150.  
  4151. ■seealso _lldiv() _uldiv() _ulldiv()
  4152.  
  4153.  
  4154. ■function _DLL_InitTerm()
  4155. ■compat OS/2
  4156.  
  4157. ■param MOD_HANDLE FLAG
  4158. ■prototype
  4159. unsigned long _DLL_InitTerm (unsigned long MOD_HANDLE, unsigned long FLAG);
  4160. ■endprototype
  4161.  
  4162.     _DLL_InitTerm() is the library initialization and termination
  4163.     function for dynamic link libraries.  It is called by the
  4164.     operating system to initialize the library (if FLAG is zero) or to
  4165.     terminate the library (if FLAG is one).  MOD_HANDLE is the module
  4166.     handle of the dynamic link library.
  4167.  
  4168.     For all types of DLLs, the default _DLL_InitTerm() function calls
  4169.     __ctordtorInit() and __ctordtorTerm().  _CRT_init() is called for
  4170.     all types of DLLs except for DLLs without runtime environment
  4171.     (-Zno-rte).  _CRT_term() is called for stand-alone DLLs (-Zso) and
  4172.     for custom C runtime DLLs.
  4173.  
  4174.     If you write your own _DLL_InitTerm() to perform additional
  4175.     actions, don't forget to call _CRT_init() -- if required -- to
  4176.     initialize the runtime environment and to call __ctordtorInit()
  4177.     (after calling _CRT_init()) to invoke the static constructors of
  4178.     the DLL.  On termination (FLAG is one), you should call
  4179.     _CRT_term() in DLLs which include a C runtime environment .  To
  4180.     invoke the static destructors of the DLL, call __ctordtorTerm()
  4181.     before calling _CRT_term().
  4182.  
  4183.     If the DLL shares the heap with the program (for instance, if both
  4184.     use emxlibcs.dll) and if _DLL_InitTerm() uses the heap (by calling
  4185.     sbrk(), malloc(), etc.), fork() will always fail for that program.
  4186.  
  4187. ■returnvalue
  4188.  
  4189.     _DLL_InitTerm() should return 1 to indicate success.  On failure,
  4190.     _DLL_InitTerm() should return 0.
  4191.  
  4192. ■seealso _CRT_init() _CRT_term() __ctordtorInit() __ctordtorTerm() fork()
  4193.  
  4194. ■samplecode
  4195. /* This is the default _DLL_InitTerm() function for
  4196.    stand-alone dynamic link libraries. */
  4197.  
  4198. int _CRT_init (void);
  4199. void _CRT_term (void);
  4200. void __ctordtorInit (void);
  4201. void __ctordtorTerm (void);
  4202.  
  4203. unsigned long _DLL_InitTerm (unsigned long mod_handle,
  4204.                              unsigned long flag)
  4205. {
  4206.   switch (flag)
  4207.     {
  4208.     case 0:
  4209.       if (_CRT_init () != 0)
  4210.         return 0;
  4211.       __ctordtorInit ();
  4212.      return 1;
  4213.     case 1:
  4214.       __ctordtorTerm ();
  4215.       _CRT_term ();
  4216.       return 1;
  4217.     default:
  4218.       return 0;
  4219.     }
  4220.   return 1;
  4221. }
  4222. ■endsamplecode
  4223.  
  4224.  
  4225. ■function _dt_free()
  4226. ■compat emx
  4227. ■headers
  4228. #include <sys/dirtree.h>
  4229. ■endheaders
  4230.  
  4231. ■param DT
  4232. ■prototype
  4233. void _dt_free (struct _dt_tree *DT);
  4234. ■endprototype
  4235.  
  4236.     Deallocate the memory allocated by _dt_read() for the directory
  4237.     tree DT.
  4238.  
  4239. ■seealso _dt_read()
  4240.  
  4241.  
  4242. ■function _dt_read()
  4243. ■compat emx
  4244. ■headers
  4245. #include <sys/dirtree.h>
  4246. ■endheaders
  4247.  
  4248. ■param DIR MASK FLAGS
  4249. ■prototype
  4250. struct _dt_tree *_dt_read (const char *DIR, const char *MASK, unsigned FLAGS);
  4251. ■endprototype
  4252.  
  4253.     Create a directory tree in memory.  The tree consists of a linked
  4254.     list of _dt_node structures.  Subtrees are attached to the
  4255.     ■tt{sub} field of _dt_node structures for directories.  Files
  4256.     matching the wildcard in the string pointed to by MASK in the
  4257.     directory whose name is in the string pointed to by DIR are put
  4258.     into the tree.  If FLAGS includes _DT_TREE, all subdirectories of
  4259.     DIR are also scanned for files and directories matching the
  4260.     wildcard.  If _DT_TREE is not included, the subdirectories of the
  4261.     directory are not scanned.  If FLAGS includes _DT_NOCPDIR, the `.'
  4262.     and `..'  entries are omitted.
  4263.  
  4264.     _fnlwr() is used to convert file names to lower case on
  4265.     upper-case-only file systems.  _dt_read() properly handles DBCS
  4266.     characters.
  4267.  
  4268. ■returnvalue
  4269.  
  4270.     If successful, _dt_read() returns a pointer to a _dt_tree
  4271.     structure.  The ■tt{tree} field of that structure is the root of
  4272.     the tree.  On error, _dt_read() sets the errno variable and
  4273.     returns NULL.
  4274.  
  4275. ■seealso _dt_free() _dt_sort() _dt_split() _fnlwr() _fnexplode() _nls_init()
  4276.  
  4277. ■samplefile /emx/test/dttest.c
  4278.  
  4279.  
  4280. ■function _dt_sort()
  4281. ■compat emx
  4282. ■headers
  4283. #include <sys/dirtree.h>
  4284. ■endheaders
  4285.  
  4286. ■param DT SPEC
  4287. ■prototype
  4288. void _dt_sort (struct _dt_tree *DT, const char *SPEC);
  4289. ■endprototype
  4290.  
  4291.     Sort the directory tree DT according to the string pointed to by
  4292.     SPEC.  DT is a directory tree created by _dt_read().  SPEC points
  4293.     to a string of characters which is read from left to right.  Each
  4294.     character tells _dt_sort() how to compare two tree nodes.  If the
  4295.     nodes compare equal, the next character is examined.  This is
  4296.     repeated until the two nodes are different according to the
  4297.     sorting criterion indicated by a character of the string pointed
  4298.     to by SPEC or the end of the SPEC string is reached.  If the end
  4299.     of the string pointed to by SPEC is reached, the two nodes are
  4300.     considered equal and the two nodes are put in an arbitrary order.
  4301.     The following characters are defined in the string pointed to by
  4302.     SPEC:
  4303.  
  4304. ■description
  4305. ■item e
  4306.  
  4307.     File name extensions are compared, ascending ASCII order
  4308.  
  4309. ■item E
  4310.  
  4311.     File name extensions are compared, descending ASCII order
  4312.  
  4313. ■item f
  4314.  
  4315.     Directories are placed before files
  4316.  
  4317. ■item F
  4318.  
  4319.     Files are placed before directories
  4320.  
  4321. ■item n
  4322.  
  4323.     File names are compared, ascending ASCII order
  4324.  
  4325. ■item N
  4326.  
  4327.     File names are compared, descending ASCII order
  4328.  
  4329. ■item s
  4330.  
  4331.     File size is compared, ascending
  4332.  
  4333. ■item S
  4334.  
  4335.     File size is compared, descending
  4336.  
  4337. ■item t
  4338.  
  4339.     Time stamps (last modification) are compared, ascending
  4340.  
  4341. ■item T
  4342.  
  4343.     Time stamps (last modification) are compared, descending
  4344.  
  4345. ■enddescription
  4346.  
  4347.     All other characters are ignored.  _fncmp() is used for comparing
  4348.     file names.  If _fncmp() returns 0, strcmp() is used in addition.
  4349.     Then, strcmp() can return a non-zero value only if the current
  4350.     code page does not match the code page used for creating the
  4351.     directory entries.
  4352.  
  4353. ■seealso _dt_read() _fncmp()
  4354.  
  4355.  
  4356. ■function _dt_split()
  4357. ■compat emx
  4358. ■headers
  4359. #include <sys/dirtree.h>
  4360. ■endheaders
  4361.  
  4362. ■param SRC DIR MASK
  4363. ■prototype
  4364. int _dt_split (const char *SRC, char *DIR, char *MASK);
  4365. ■endprototype
  4366.  
  4367.     Split the path name pointed to by SRC into a directory part and a
  4368.     name part for _dt_read().  The directory part is stored to the
  4369.     array pointed to by DIR, the name part is stored to the array
  4370.     pointed to by MASK.  If the string pointed to by SRC is the name
  4371.     of a directory, the array pointed to by MASK is set to ■tt{"*.*"}.
  4372.  
  4373.     _dt_split() properly handles DBCS characters.
  4374.  
  4375. ■returnvalue
  4376. ■description
  4377. ■item 0
  4378.     success
  4379. ■item -1
  4380.     error (errno set)
  4381. ■enddescription
  4382.     
  4383. ■seealso _dt_read() _nls_init()
  4384.  
  4385.  
  4386. ■function dup() dup2()
  4387. ■compat UNIX
  4388. ■headers
  4389. #include <io.h>
  4390. ■endheaders
  4391.  
  4392. ■param HANDLE HANDLE1 HANDLE2
  4393. ■prototype
  4394. int dup (int HANDLE);
  4395. int dup2 (int HANDLE1, int HANDLE2);
  4396. ■endprototype
  4397.  
  4398.     Create a duplicate of the file handle HANDLE or HANDLE1,
  4399.     respectively, that is, another handle that refers to the same file
  4400.     or device or pipe as the handle given.  Both handles share the
  4401.     same file pointer.  dup() chooses the lowest numbered available
  4402.     handle.  dup2() uses HANDLE2 for the new file handle.  If HANDLE2
  4403.     is open when dup2() is called, it will be closed by dup2() unless
  4404.     HANDLE1 is invalid or identical to HANDLE2.
  4405.  
  4406.     If HANDLE1 is a valid open file handle and is equal to HANDLE2,
  4407.     dup2() returns HANDLE2 without closing it.
  4408.  
  4409. ■returnvalue
  4410.  
  4411.     dup() and dup2() return the new file handle (which is HANDLE2 if
  4412.     dup2() succeeds).  They return -1 on error.
  4413.  
  4414. ■errors
  4415. ■description
  4416. ■item EBADF
  4417.     The HANDLE or HANDLE1 argument is not a valid open file descriptor
  4418.     or HANDLE2 is out of range.
  4419. ■item EMFILE
  4420.     No file descriptor is available.
  4421. ■enddescription
  4422.  
  4423. ■restrictions
  4424.  
  4425.     Duplicated file handles should share the file status flags
  4426.     O_APPEND and O_NONBLOCK; however, dup() and dup2() just copy the
  4427.     file status flags, changing the file status flags after
  4428.     duplicating a file handle does not affect the other file handle.
  4429.  
  4430.     dup2() currently doesn't work correctly under DOS.
  4431.  
  4432. ■seealso close() fcntl() open()
  4433.  
  4434.  
  4435. ■function _ea_free()
  4436. ■compat emx
  4437. ■headers
  4438. #include <sys/ea.h>
  4439. ■endheaders
  4440.  
  4441. ■param PTR
  4442. ■prototype
  4443. void _ea_free (struct _ea *PTR);
  4444. ■endprototype
  4445.  
  4446.     Free the memory allocated for the value of an extended attribute
  4447.     stored in the structure pointed to by PTR.  If the ■tt{value}
  4448.     field of the structure is non-■tt{NULL}, free() is called for that
  4449.     pointer.  Then, the ■tt{value} field is set to NULL.
  4450.  
  4451. ■seealso _ea_get()
  4452.  
  4453.  
  4454. ■function _ea_get()
  4455. ■compat emx
  4456. ■headers
  4457. #include <sys/ea.h>
  4458. ■endheaders
  4459.  
  4460. ■param DST PATH HANDLE NAME
  4461. ■prototype
  4462. int _ea_get (struct _ea *DST, const char *PATH, int HANDLE,
  4463.              const char *NAME);
  4464. ■endprototype
  4465.  
  4466.     Retrieve the extended attribute whose name is in the string
  4467.     pointed to by NAME of a file or directory.  If PATH is
  4468.     non-■tt{NULL}, an extended attribute of the file or directory
  4469.     whose name is in the string pointed to by PATH is retrieved.
  4470.     Otherwise, an extended attribute of the file referred to by HANDLE
  4471.     is retrieved.  The letter case of NAME is ignored.  The flags, the
  4472.     value and the size of the value of the extended attribute is
  4473.     copied to the structure pointed to by DST.  If the extended
  4474.     attribute does not exist, the ■tt{size} member of the structure
  4475.     pointed to by DST is set to 0 and the ■tt{value} member of the
  4476.     structure pointed to by DST is set to NULL.  _ea_get() allocates
  4477.     memory for the value of the extended attribute by calling
  4478.     malloc().  The structure declaration is:
  4479.  
  4480. ■example
  4481. struct _ea
  4482. {
  4483.   int flags;
  4484.   int size;
  4485.   void *value;
  4486. };
  4487. ■endexample
  4488.  
  4489.     The ■tt{flags} member contains the flags byte of the extended
  4490.     attribute (only bits 0 through 7 of ■tt{flags} are used).
  4491.     Currently, OS/2 defines only bit 7: it's set for critical EAs.
  4492.     ■tt{size} is the length of the value in bytes.  The ■tt{value}
  4493.     member points to the (binary) value of the extended attribute.
  4494.  
  4495.     Use _ead_read() to retrieve all the extended attributes of a file
  4496.     or directory.
  4497.  
  4498. ■returnvalue
  4499. ■description
  4500. ■item 0
  4501.     success or EA not found
  4502. ■item -1
  4503.     error
  4504. ■enddescription
  4505.  
  4506. ■seealso _ea_free() _ea_put() _ead_read()
  4507.  
  4508.  
  4509. ■function _ea_put()
  4510. ■compat emx
  4511. ■headers
  4512. #include <sys/ea.h>
  4513. ■endheaders
  4514.  
  4515. ■param SRC PATH HANDLE NAME
  4516. ■prototype
  4517. int _ea_put (struct _ea *SRC, const char *PATH, int HANDLE,
  4518.              const char *NAME);
  4519. ■endprototype
  4520.  
  4521.     Add an extended attribute to a file or directory.  If PATH is
  4522.     non-■tt{NULL}, the extended attribute is added to the file or
  4523.     directory whose name is in the string pointed to by PATH.
  4524.     Otherwise, the extended attribute is added to the file referred to
  4525.     by HANDLE which must be open for writing.  The string pointed to
  4526.     by NAME contains the name of the extended attribute.  The letter
  4527.     case of the name is ignored.  SRC points to an _ea structure which
  4528.     holds the flags, size and value of the extended attribute to be
  4529.     added.  If the ■tt{size} member is 0, the extended attribute is
  4530.     removed.  Bits 0 though 7 of ■tt{flags} contain the flags byte for
  4531.     the extended attribute.  Currently, OS/2 defines only bit: the
  4532.     critical EA bit.  The ■tt{flags} member should be zero unless you
  4533.     exactly know what you are doing.
  4534.  
  4535.     Use _ead_write() to replace or update multiple extended attributes
  4536.     at once.
  4537.  
  4538. ■returnvalue
  4539. ■description
  4540. ■item 0
  4541.     success
  4542. ■item -1
  4543.     error (errno is set)
  4544. ■enddescription
  4545.  
  4546. ■seealso _ea_get() _ea_remove() _ead_write()
  4547.  
  4548.  
  4549. ■function _ea_remove()
  4550. ■compat emx
  4551. ■headers
  4552. #include <sys/ea.h>
  4553. ■endheaders
  4554.  
  4555. ■param PATH HANDLE NAME
  4556. ■prototype
  4557. int _ea_remove (const char *PATH, int HANDLE, const char *NAME);
  4558. ■endprototype
  4559.  
  4560.     Remove the extended attribute whose name is in the string pointed
  4561.     to by NAME from a file or directory.  If PATH is non-■tt{NULL},
  4562.     the extended attribute is removed from the file or directory whose
  4563.     name is in the string pointed to by PATH.  Otherwise, the extended
  4564.     attribute is removed from the file referred to by HANDLE.  The
  4565.     letter case of the string pointed to by NAME is ignored.  Removing
  4566.     a non-existing extended attribute of an existing file or directory
  4567.     is not an error.
  4568.  
  4569. ■returnvalue
  4570. ■description
  4571. ■item 0
  4572.     success
  4573. ■item -1
  4574.     error (errno is set)
  4575. ■enddescription
  4576.  
  4577. ■seealso _ea_put() _ead_write()
  4578.  
  4579.  
  4580. ■function _ead_add()
  4581. ■compat emx
  4582. ■headers
  4583. #include <sys/ead.h>
  4584. ■endheaders
  4585.  
  4586. ■param EAD NAME FLAGS VALUE SIZE
  4587. ■prototype
  4588. int _ead_add (_ead EAD, const char *NAME, int FLAGS, const void *VALUE,
  4589.               int SIZE);
  4590. ■endprototype
  4591.  
  4592.     Add the extended attribute whose name is in the string pointed to
  4593.     by NAME to the extended attributes descriptor EAD.  NAME should
  4594.     point to a null-terminated string.  The value of the extended
  4595.     attribute is set to SIZE bytes of the array pointed to by VALUE.
  4596.     The flags byte of the extended attribute is set to FLAGS.  Only
  4597.     bits 0 through 7 of FLAGS are used.  Currently, OS/2 defines only
  4598.     bit 7 of the flags byte: it's the critical EA bit.  FLAGS should
  4599.     be zero unless you exactly know what you are doing.  If an
  4600.     extended attribute with the name in the string pointed to by NAME
  4601.     already exists in EAD, it is updated with FLAGS, SIZE and the
  4602.     array pointed to by VALUE.  The extended attributes on disk are
  4603.     not affected.  After calling _ead_add(), the pointers returned by
  4604.     previous invocations of _ead_get_fea2list(), _ead_get_name() and
  4605.     _ead_get_value() will be invalid.  As _ead_add() does a
  4606.     case-sensitive search, you should pass an upper-case names in the
  4607.     string pointed to by NAME.  If there are two extended attributes
  4608.     in an extended attributes descriptor whose names differ only in
  4609.     letter case, only one of both will be written to the disk by
  4610.     _ead_write().
  4611.  
  4612. ■returnvalue
  4613.  
  4614.     _ead_add() returns the index of the new (or updated) extended
  4615.     attribute.  On error, _ead_add() sets errno and returns a negative
  4616.     value.
  4617.  
  4618. ■seealso _ead_delete() _ead_replace() _ead_write() _nls_strupr()
  4619.  
  4620.  
  4621. ■function _ead_clear()
  4622. ■compat emx
  4623. ■headers
  4624. #include <sys/ead.h>
  4625. ■endheaders
  4626.  
  4627. ■param EAD
  4628. ■prototype
  4629. void _ead_clear (_ead EAD);
  4630. ■endprototype
  4631.  
  4632.     Discard the extended attributes of the extended attributes
  4633.     descriptor EAD.  After calling _ead_clear(), _ead_count() will
  4634.     return 0 for EAD.  The extended attributes on disk are not
  4635.     modified.  After calling _ead_clear(), do not use pointers
  4636.     returned by _ead_get_name(), _ead_get_value() and
  4637.     _ead_get_fea2list() for that descriptor.
  4638.  
  4639.  
  4640. ■seealso _ead_create() _ead_destroy() _ead_read()
  4641.  
  4642.  
  4643. ■function _ead_copy()
  4644. ■compat emx
  4645. ■headers
  4646. #include <sys/ead.h>
  4647. ■endheaders
  4648.  
  4649. ■param DST_EAD SRC_EAD SRC_INDEX
  4650. ■prototype
  4651. int _ead_copy (_ead DST_EAD, _ead SRC_EAD, int SRC_INDEX);
  4652. ■endprototype
  4653.  
  4654.     Copy the extended attribute SRC_INDEX from the extended attributes
  4655.     descriptor SRC_EAD to the extended attributes descriptor DST_EAD.
  4656.     If SRC_INDEX is 0, all extended attributes of SRC_EAD are copied
  4657.     to DST_EAD.  Otherwise, SRC_INDEX must be a number between 1 and
  4658.     the number of extended attributes of SRC_EAD.  _ead_copy() uses
  4659.     _ead_add() to copy the extended attributes.  The extended
  4660.     attributes on disk are not affected.
  4661.  
  4662. ■returnvalue
  4663. ■description
  4664. ■item 0
  4665.     success
  4666. ■item -1
  4667.     error (errno is set)
  4668. ■enddescription
  4669.  
  4670. ■seealso _ead_add()
  4671.  
  4672.  
  4673. ■function _ead_count()
  4674. ■compat emx
  4675. ■headers
  4676. #include <sys/ead.h>
  4677. ■endheaders
  4678.  
  4679. ■param EAD
  4680. ■prototype
  4681. int _ead_count (_ead EAD);
  4682. ■endprototype
  4683.  
  4684.     Get the number of extended attributes available from the
  4685.     extended attributes descriptor EAD.
  4686.  
  4687. ■returnvalue
  4688.  
  4689.     _ead_count() returns the number of extended attributes available
  4690.     from the extended attributes descriptor EAD.
  4691.  
  4692. ■seealso _ead_create() _ead_get_name() _ead_get_value()
  4693.  
  4694.  
  4695. ■function _ead_create()
  4696. ■compat emx
  4697. ■headers
  4698. #include <sys/ead.h>
  4699. ■endheaders
  4700.  
  4701. ■prototype
  4702. _ead _ead_create (void)
  4703. ■endprototype
  4704.  
  4705.     Create an extended attributes descriptor.  Such a descriptor is
  4706.     used for handling the extended attributes of files and
  4707.     directories.  Use _ead_destroy() if you no longer need the
  4708.     descriptor.  To copy all the extended attributes of a file or a
  4709.     directory to an extended attributes descriptor, use _ead_read().
  4710.     Initially, no extended attributes are held by an extended
  4711.     attributes descriptor.
  4712.  
  4713. ■returnvalue
  4714.  
  4715.     _ead_create() returns a descriptor which can be used by the other
  4716.     functions for handling extended attributes.  On error,
  4717.     _ead_create() sets errno and returns NULL.
  4718.  
  4719. ■seealso _ead_destroy() _ead_get_name() _ead_get_value() _ead_read()
  4720.  
  4721. ■samplefile /emx/samples/eatool.c
  4722.  
  4723.  
  4724. ■function _ead_delete()
  4725. ■compat emx
  4726. ■headers
  4727. #include <sys/ead.h>
  4728. ■endheaders
  4729.  
  4730. ■param EAD INDEX
  4731. ■prototype
  4732. int _ead_delete (_ead EAD, int INDEX);
  4733. ■endprototype
  4734.  
  4735.     Delete the extended attribute INDEX from the extended attributes
  4736.     descriptor EAD.  INDEX must be a number between 1 and the number
  4737.     of extended attributes of EAD.  After calling _ead_delete(), the
  4738.     pointers returned by previous invocations of _ead_get_fea2list(),
  4739.     _ead_get_name() and _ead_get_value() will be invalid.  Moreover,
  4740.     _ead_delete() invalidates index numbers.
  4741.  
  4742. ■returnvalue
  4743.  
  4744.     _ead_delete() returns 0 if successful.  On error, _ead_delete()
  4745.     sets errno and returns a negative number.
  4746.  
  4747. ■seealso _ead_add() _ead_find()
  4748.  
  4749.  
  4750. ■function _ead_destroy()
  4751. ■compat emx
  4752. ■headers
  4753. #include <sys/ead.h>
  4754. ■endheaders
  4755.  
  4756. ■param EAD
  4757. ■prototype
  4758. void _ead_destroy (_ead EAD);
  4759. ■endprototype
  4760.  
  4761.     Invalidate the extended attributes descriptor EAD which has been
  4762.     created by _ead_create().  All memory associated with EAD is
  4763.     released.  EAD must not be NULL.  After calling _ead_destroy(),
  4764.     EAD is invalid and can no longer be used.  After calling
  4765.     _ead_destroy(), do not use pointers returned by _ead_get_name(),
  4766.     _ead_get_value() and _ead_get_fea2list() for that descriptor.
  4767.  
  4768. ■seealso _ead_clear() _ead_create()
  4769.  
  4770.  
  4771. ■function _ead_fea2list_size()
  4772. ■compat emx
  4773. ■headers
  4774. #include <sys/ead.h>
  4775. ■endheaders
  4776.  
  4777. ■param EAD
  4778. ■prototype
  4779. int _ead_fea2list_size (_ead EAD);
  4780. ■endprototype
  4781.  
  4782.     Get the size of the FEA2LIST of the extended attributes
  4783.     descriptor EAD.  If EAD doesn't hold any extended attributes, the
  4784.     size is 0.
  4785.  
  4786. ■returnvalue
  4787.  
  4788.     _ead_fea2list_size() returns the size of the FEA2LIST of the
  4789.     extended attributes descriptor EAD.  _ead_fea2list_size() returns
  4790.     0 if EAD doesn't hold any extended attributes.
  4791.  
  4792. ■seealso _ead_get_fea2list()
  4793.  
  4794.  
  4795. ■function _ead_fea2list_to_fealist()
  4796. ■compat emx
  4797. ■headers
  4798. #include <sys/ead.h>
  4799. ■endheaders
  4800.  
  4801. ■param SRC
  4802. ■prototype
  4803. void *_ead_fea2list_to_fealist (const void *SRC);
  4804. ■endprototype
  4805.  
  4806.     Convert the FEA2LIST SRC (OS/2 2.x format) to a FEALIST (OS/2 1.2
  4807.     format).  SRC must not be NULL.  This function allocates memory
  4808.     with malloc() to hold the converted list.  A pointer to the
  4809.     converted list is returned.  If you no longer need the buffer
  4810.     allocated by this function, you should deallocate it with free().
  4811.     SRC is of type PFEA2LIST, the return value is of type PFEALIST.
  4812.     To avoid having to include <os2.h> when including <sys/ead.h>, void
  4813.     pointers are used instead.
  4814.  
  4815. ■returnvalue
  4816.  
  4817.     _ead_fea2list_to_fealist() returns a pointer to a FEALIST,
  4818.     allocated with malloc().  On error, _ead_fea2list_to_fealist()
  4819.     sets errno and returns NULL.
  4820.  
  4821. ■seealso _ead_fealist_to_fea2list() _ead_get_fea2list()
  4822.  
  4823.  
  4824. ■function _ead_fealist_to_fea2list()
  4825. ■compat emx
  4826. ■headers
  4827. #include <sys/ead.h>
  4828. ■endheaders
  4829.  
  4830. ■param SRC
  4831. ■prototype
  4832. void *_ead_fealist_to_fea2list (const void *SRC);
  4833. ■endprototype
  4834.  
  4835.     Convert the FEALIST SRC (OS/2 1.2 format) to a FEA2LIST (OS/2 2.x
  4836.     format).  SRC must not be NULL.  This function allocates memory
  4837.     with malloc() to hold the converted list.  A pointer to the
  4838.     converted list is returned.  If you no longer need the buffer
  4839.     allocated by this function, you should deallocate it with free().
  4840.     SRC is of type PFEALIST, the return value is of type PFEA2LIST.
  4841.     To avoid having to include <os2.h> when including <sys/ead.h>, void
  4842.     pointers are used instead.
  4843.  
  4844. ■returnvalue
  4845.  
  4846.     _ead_fealist_to_fea2list() returns a pointer to a FEA2LIST,
  4847.     allocated with malloc().  On error, _ead_fealist_to_fea2list()
  4848.     sets errno and returns NULL.
  4849.  
  4850. ■seealso _ead_fea2list_to_fealist()
  4851.  
  4852.  
  4853. ■function _ead_find()
  4854. ■compat emx
  4855. ■headers
  4856. #include <sys/ead.h>
  4857. ■endheaders
  4858.  
  4859. ■param EAD NAME
  4860. ■prototype
  4861. int _ead_find (_ead EAD, const char *NAME);
  4862. ■endprototype
  4863.  
  4864.     Retrieve the index of the extended attribute whose name is in the
  4865.     string pointed to by NAME of the extended attributes descriptor
  4866.     EAD.  NAME should point to a null-terminated string.  If there is
  4867.     no such extended attribute, errno is set to ENOENT and -1 is
  4868.     returned.  Otherwise, a number between 1 and the number of
  4869.     extended attributes of EAD is returned.  Note that OS/2 converts
  4870.     names of extended attributes to upper case when writing them to
  4871.     the disk.  As _ead_find() does a case-sensitive compare,
  4872.     lower-case names are not found.
  4873.  
  4874. ■returnvalue
  4875.  
  4876.     _ead_find() returns the index of the extended attribute.  If the
  4877.     extended attribute is not found, _ead_find() returns -1.
  4878.  
  4879. ■seealso _ead_count() _ead_get_name() _ead_get_value() _nls_strupr()
  4880.  
  4881.  
  4882. ■function _ead_get_fea2list()
  4883. ■compat emx
  4884. ■headers
  4885. #include <sys/ead.h>
  4886. ■endheaders
  4887.  
  4888. ■param EAD
  4889. ■prototype
  4890. const void *_ead_get_fea2list (_ead EAD);
  4891. ■endprototype
  4892.  
  4893.     Retrieve a pointer to the FEA2LIST of the extended attributes
  4894.     descriptor EAD.  You should cast the return value to PFEA2LIST.
  4895.     The return type of _ead_get_fea2list() is not PFEA2LIST to be able
  4896.     to include <sys/ead.h> without having to include <os2.h>.  The pointer
  4897.     points to memory allocated by the extended attributes functions --
  4898.     do not use the pointer after calling _ead_add(), _ead_clear(),
  4899.     _ead_copy(), _ead_delete(), _ead_destroy() or _ead_replace() and
  4900.     do not write to the buffer.
  4901.  
  4902. ■returnvalue
  4903.  
  4904.     _ead_get_fea2list() returns a pointer to the FEA2LIST of the
  4905.     extended attributes descriptor EAD.
  4906.  
  4907. ■seealso _ead_fea2list_size() _ead_fea2list_to_fealist()
  4908.  
  4909.  
  4910. ■function _ead_get_flags()
  4911. ■compat emx
  4912. ■headers
  4913. #include <sys/ead.h>
  4914. ■endheaders
  4915.  
  4916. ■param EAD INDEX
  4917. ■prototype
  4918. int _ead_get_flags (_ead EAD, int INDEX);
  4919. ■endprototype
  4920.  
  4921.     Get the ■tt{flags} byte of the extended attribute INDEX of the
  4922.     extended attributes descriptor EAD.  INDEX must be a number
  4923.     between 1 and the number of extended attributes of EAD.  On error,
  4924.     errno is set and -1 is returned.
  4925.  
  4926. ■returnvalue
  4927.  
  4928.     _ead_get_flags() returns the ■tt{flags} by of an extended
  4929.     attribute.  On error, _ead_get_flags() returns -1.
  4930.  
  4931. ■seealso _ead_count() _ead_get_value()
  4932.  
  4933.  
  4934. ■function _ead_get_name()
  4935. ■compat emx
  4936. ■headers
  4937. #include <sys/ead.h>
  4938. ■endheaders
  4939.  
  4940. ■param EAD INDEX
  4941. ■prototype
  4942. const char *_ead_get_name (_ead EAD, int INDEX);
  4943. ■endprototype
  4944.  
  4945.     Return a pointer to the name of the extended attribute INDEX of
  4946.     the extended attributes descriptor EAD.  INDEX must be a number
  4947.     between 1 and the number of extended attributes of EAD.  The
  4948.     pointer points to memory allocated by the extended attributes
  4949.     functions -- do not use the pointer after calling _ead_add(),
  4950.     _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or
  4951.     _ead_replace() and do not write to the buffer.  On error, errno is
  4952.     set and NULL is returned.
  4953.  
  4954. ■returnvalue
  4955.  
  4956.     _ead_get_name() returns a pointer to the name of an extended
  4957.     attribute.  On error, _ead_get_name() returns NULL.
  4958.  
  4959. ■seealso _ead_count() _ead_name_len()
  4960.  
  4961.  
  4962. ■function _ead_get_value()
  4963. ■compat emx
  4964. ■headers
  4965. #include <sys/ead.h>
  4966. ■endheaders
  4967.  
  4968. ■param EAD INDEX
  4969. ■prototype
  4970. const void *_ead_get_value (_ead EAD, int INDEX);
  4971. ■endprototype
  4972.  
  4973.     Return a pointer to the value of the extended attribute INDEX of
  4974.     the extended attributes descriptor EAD.  INDEX must be a number
  4975.     between 1 and the number of extended attributes of EAD.  The
  4976.     pointer points to memory allocated by the extended attributes
  4977.     functions -- do not use the pointer after calling _ead_add(),
  4978.     _ead_clear(), _ead_copy(), _ead_delete(), _ead_destroy() or
  4979.     _ead_replace() and do not write to the buffer.  On error, errno is
  4980.     set and NULL is returned.
  4981.  
  4982. ■returnvalue
  4983.  
  4984.     _ead_get_value() returns a pointer to the value of an extended
  4985.     attribute.  On error, _ead_get_value() returns NULL.
  4986.  
  4987. ■seealso _ead_count() _ead_find() _ead_get_flags() _ead_value_size()
  4988.  
  4989.  
  4990. ■function _ead_name_len()
  4991. ■compat emx
  4992. ■headers
  4993. #include <sys/ead.h>
  4994. ■endheaders
  4995.  
  4996. ■param EAD INDEX
  4997. ■prototype
  4998. int _ead_name_len (_ead EAD, int INDEX);
  4999. ■endprototype
  5000.  
  5001.     Get the length of the name of the extended attribute INDEX of the
  5002.     extended attributes descriptor EAD.  If INDEX is 0, the total
  5003.     length of all the names is returned, not including the terminating
  5004.     null characters.  Otherwise, INDEX must be a number between 1 and
  5005.     the number of extended attributes of EAD; the length of the name
  5006.     of the ■pa{INDEX}th extended attribute is returned.  The
  5007.     terminating null character is not included in the length.  On
  5008.     error, errno is set and -1 is returned.
  5009.  
  5010. ■returnvalue
  5011.  
  5012.     _ead_name_len() returns the length of the name of an extended
  5013.     attribute.  On error, _ead_name_len() returns -1.
  5014.  
  5015. ■seealso _ead_count() _ead_get_name()
  5016.  
  5017.  
  5018. ■function _ead_read()
  5019. ■compat emx
  5020. ■headers
  5021. #include <sys/ead.h>
  5022. ■endheaders
  5023.  
  5024. ■param EAD PATH HANDLE FLAGS
  5025. ■prototype
  5026. int _ead_read (_ead EAD, const char *PATH, int HANDLE, int FLAGS);
  5027. ■endprototype
  5028.  
  5029.     Copy the extended attributes of a file or directory to the
  5030.     extended attributes descriptor EAD.  The extended attributes held
  5031.     previously by EAD are discarded.  If PATH is not NULL, the
  5032.     extended attributes of file or directory whose name is in the
  5033.     string pointed to by PATH are copied to EAD.  If PATH is NULL, the
  5034.     extended attributes of the file referred to by the file handle
  5035.     HANDLE are copied to EAD.  FLAGS is not yet used and must be 0.
  5036.     _ead_read() calls _ead_clear(), reads all the extended attributes
  5037.     and stores them in memory.  Use _ead_destroy() to deallocate that
  5038.     memory and invalidate EAD.  When using a non-■tt{NULL} PATH,
  5039.     _ead_read() does not lock the file while while reading the
  5040.     extended attributes.  You might want to open a handle in
  5041.     deny-write mode and pass it in HANDLE to avoid problems due to
  5042.     other threads or processes modifying the extended attributes while
  5043.     _ead_read() is reading.  This doesn't work with and isn't required
  5044.     for directories.  _ead_read() can also be used under DOS though no
  5045.     extended attributes will be copied.  Therefore, your program
  5046.     doesn't have to decide whether to use these functions or not.
  5047.  
  5048.     Use _ea_get() to retrieve extended attributes one by one.
  5049.  
  5050. ■returnvalue
  5051.  
  5052.   If successful, _ead_read() returns 0.  On error, _ead_read() sets
  5053.   errno and returns a negative number.
  5054.  
  5055. ■seealso _ea_get() _ead_create() _ead_destroy() _ead_get_name() _ead_get_value() _ead_write()
  5056.  
  5057. ■function _ead_replace()
  5058. ■compat emx
  5059. ■headers
  5060. #include <sys/ead.h>
  5061. ■endheaders
  5062.  
  5063. ■param EAD INDEX FLAGS VALUE SIZE
  5064. ■prototype
  5065. int _ead_replace (_ead EAD, int INDEX, int FLAGS, const void *VALUE,
  5066.                   int SIZE);
  5067. ■endprototype
  5068.  
  5069.     Update the extended attribute INDEX of the extended attributes
  5070.     descriptor EAD with FLAGS and SIZE bytes of VALUE.  INDEX must be
  5071.     a number between 1 and the number of extended attributes of EAD.
  5072.     The extended attributes on disk are not affected.  After calling
  5073.     _ead_replace(), the pointers returned by previous invocations of
  5074.     _ead_get_fea2list(), _ead_get_name() and _ead_get_value() will be
  5075.     invalid.
  5076.  
  5077. ■returnvalue
  5078.  
  5079.     On success, _ead_replace() returns 0.  On error, _ead_replace()
  5080.     sets errno and returns a negative value.
  5081.  
  5082. ■seealso _ead_add() _ead_write()
  5083.  
  5084.  
  5085. ■function _ead_sort()
  5086. ■compat emx
  5087. ■headers
  5088. #include <sys/ead.h>
  5089. ■endheaders
  5090.  
  5091. ■param EAD
  5092. ■prototype
  5093. void _ead_sort (_ead EAD);
  5094. ■endprototype
  5095.  
  5096.     Sort by name the extended attributes of the extended attributes
  5097.     descriptor EAD.  Sorting is done in memory -- the extended
  5098.     attributes on disk are not affected.  After calling _ead_sort(),
  5099.     index 1 refers to the extended attribute with the lexically
  5100.     smallest name.  strcmp() is used for comparing names.  _ead_sort()
  5101.     sorts the index, not the extended attributes proper.  Therefore,
  5102.     all functions that modify the extended attributes of EAD undo the
  5103.     effect of _ead_sort().
  5104.  
  5105. ■seealso _ead_create() _ead_get_name() _ead_read()
  5106.  
  5107.  
  5108. ■function _ead_use_fea2list()
  5109. ■compat emx
  5110. ■headers
  5111. #include <sys/ead.h>
  5112. ■endheaders
  5113.  
  5114. ■param EAD SRC
  5115. ■prototype
  5116. int _ead_use_fea2list (_ead EAD, const void *SRC);
  5117. ■endprototype
  5118.  
  5119.     Copy all the extended attributes from the FEA2LIST SRC (OS/2 2.x
  5120.     format) to the extended attributes descriptor EAD.  All extended
  5121.     attributes previously held by EAD are discarded.  The extended
  5122.     attributes on the disk are not affected.
  5123.  
  5124. ■returnvalue
  5125.  
  5126.     If successful, _ead_use_fea2list() returns 0.  Otherwise,
  5127.     _ead_use_fea2list() sets errno and returns a negative value.
  5128.  
  5129. ■seealso _ead_write()
  5130.  
  5131.  
  5132. ■function _ead_value_size()
  5133. ■compat emx
  5134. ■headers
  5135. #include <sys/ead.h>
  5136. ■endheaders
  5137.  
  5138. ■param EAD INDEX
  5139. ■prototype
  5140. int _ead_value_size (_ead EAD, int INDEX);
  5141. ■endprototype
  5142.  
  5143.     Get the size of the extended attribute INDEX of the extended
  5144.     attributes descriptor EAD.  If INDEX is 0, the total size of all
  5145.     the values of EAD is returned.  Otherwise, INDEX must be a number
  5146.     between 1 and the number of extended attributes of EAD; the size
  5147.     of the ■tt{INDEX}th extended attribute is returned.  On error,
  5148.     errno is set and -1 is returned.
  5149.  
  5150. ■returnvalue
  5151.  
  5152.     _ead_value_size() returns the length of the value of an extended
  5153.     attribute.  On error, _ead_value_size() returns -1.
  5154.  
  5155. ■seealso _ead_count() _ead_get_value()
  5156.  
  5157.  
  5158. ■function _ead_write()
  5159. ■compat emx
  5160. ■headers
  5161. #include <sys/ead.h>
  5162. ■endheaders
  5163.  
  5164. ■param EAD PATH HANDLE FLAGS
  5165. ■prototype
  5166. int _ead_write (_ead EAD, const char *PATH, int HANDLE, int FLAGS);
  5167. ■endprototype
  5168.  
  5169.     Write all the extended attributes of the extended attributes
  5170.     descriptor EAD to the file or directory whose name is in the
  5171.     string pointed to by PATH or to the file associated with HANDLE.
  5172.     The extended attributes previously attached to that file or
  5173.     directory are discarded and replaced by the extended attributes of
  5174.     EAD if FLAGS is 0.  This is done by deleting the extended
  5175.     attributes of the file or directory which are not in EAD.  If
  5176.     FLAGS is _EAD_MERGE, the extended attributes of the file or
  5177.     directory which are also present in EAD are replaced by those of
  5178.     EAD.  Extended attributes of EAD which are not attached to the
  5179.     file or directory are added to the extended attributes of the file
  5180.     or directory.  If PATH is non-■tt{NULL}, the extended attributes
  5181.     are written to the file or directory whose name is in the string
  5182.     pointed to by PATH.  If PATH is NULL, the extended attributes are
  5183.     written to the file referred to by the file handle HANDLE.  The
  5184.     extended attributes of EAD are not modified.
  5185.  
  5186.     Use _ea_put() to add or update extended attributes one by one.
  5187.  
  5188. ■returnvalue
  5189.  
  5190.   _ead_write() returns 0 if successful.  On error, _ead_write() sets
  5191.   errno and returns a negative value.  Under DOS, _ead_write() does
  5192.   nothing and always returns 0.
  5193.  
  5194. ■seealso _ea_put() _ead_clear() _ead_read() _ead_use_fea2list()
  5195.  
  5196.  
  5197. ■function _emx_16to32() _emx_32to16()
  5198. ■compat emx
  5199. ■headers
  5200. #include <os2.h>
  5201. ■endheaders
  5202.  
  5203. ■param PTR
  5204. ■prototype
  5205. void *_emx_16to32 (_far16ptr PTR);
  5206. _far16ptr _emx_32to16 (void *PTR);
  5207. ■endprototype
  5208.  
  5209.     _emx_16to32() converts a 16-bit far pointer (16:16 format) to a
  5210.     32-bit flat pointer.
  5211.  
  5212.     _emx_32to16() converts a 32-bit flat pointer to a 16-bit far
  5213.     pointer (16:16 format).
  5214.  
  5215.     The type _far16ptr is used for 16-bit far pointers.
  5216.  
  5217. ■returnvalue
  5218.  
  5219.     _emx_16to32() returns a 32-bit flat pointer.
  5220.     _emx_32to16() returns a 16-bit far pointer.
  5221.  
  5222.     
  5223. ■function _emxload_connect() _emxload_disconnect()
  5224. ■compat emx
  5225. ■headers
  5226. #include <sys/emxload.h>
  5227. ■endheaders
  5228.  
  5229. ■prototype
  5230. int _emxload_connect (void)
  5231. int _emxload_disconnect (void)
  5232. ■endprototype
  5233.  
  5234.     Call _emxload_connect() to explicitly connect to the emxload
  5235.     server process.  The connection will be kept open until
  5236.     _emxload_disconnect() or _emxload_stop() is called to terminate
  5237.     the connection.  A counter is maintained which is incremented for
  5238.     each successful call to _emxload_connect() and decremented by each
  5239.     successful call to _emxload_disconnect().  The connection is
  5240.     closed when the counter reaches zero.
  5241.  
  5242.     If _emxload_connect() has not been called, _emxload_env(),
  5243.     _emxload_prog(), _emxload_this(), _emxload_stop() and
  5244.     _emxload_unload() open and close a temporary connection to the
  5245.     emxload server process.
  5246.  
  5247.     The emxload server process is started by _emxload_connect() if the
  5248.     emxload server process is not already running.
  5249.  
  5250. ■returnvalue
  5251. ■description
  5252. ■item 0
  5253.     connection sucessfully established or closed
  5254. ■item -1
  5255.     the emxload server process could not be started
  5256. ■enddescription
  5257.  
  5258. ■restrictions
  5259.  
  5260.     Under DOS, _emxload_connect() and _emxload_disconnect() do nothing
  5261.     and return -1.
  5262.  
  5263. ■seealso _emxload_disconnect() _emxload_prog() _emxload_stop()
  5264.  
  5265.  
  5266. ■function _emxload_env()
  5267. ■compat emx
  5268. ■headers
  5269. #include <sys/emxload.h>
  5270. ■endheaders
  5271.  
  5272. ■param NAME
  5273. ■prototype
  5274. int _emxload_env (const char *NAME)
  5275. ■endprototype
  5276.  
  5277.     Keep (another copy of) the current program in memory if the
  5278.     environment variable whose name is in the string pointed to by
  5279.     NAME is set and contains a number.  That number specifies the
  5280.     number of minutes the process should be kept in memory.
  5281.  
  5282.     The emxload server process is started by _emxload_env() if the
  5283.     environment variable is valid and the emxload server process is
  5284.     not already running.
  5285.  
  5286. ■returnvalue
  5287. ■description
  5288. ■item 0
  5289.     request successfully sent to the emxload server process
  5290. ■item -1
  5291.     error: the environment variable is not set, or does not contain a
  5292.     valid number or the emxload server process could not be started
  5293. ■enddescription
  5294.  
  5295. ■restrictions
  5296.  
  5297.     Under DOS, _emxload_env() does nothing and returns -1.
  5298.  
  5299. ■seealso _emxload_prog() _emxload_this() _emxload_unload()
  5300.  
  5301.  
  5302. ■function _emxload_list_start() _emxload_list_get()
  5303. ■compat emx
  5304. ■headers
  5305. #include <sys/emxload.h>
  5306. ■endheaders
  5307.  
  5308. ■param BUF BUF_SIZE PSECONDS
  5309. ■prototype
  5310. int _emxload_list_start (void);
  5311. int _emxload_list_get (char *BUF, size_t BUF_SIZE, int *PSECONDS);
  5312. ■endprototype
  5313.  
  5314.     Get a list of all preloaded programs.  To start the list, call
  5315.     _emxload_list_start().  If _emxload_list_start() returns 0, call
  5316.     _emxload_list_get() to receive the names and timeouts of the
  5317.     preloaded programs until _emxload_list_get() returns a non-zero value.
  5318.  
  5319.     _emxload_list_get() stores the complete path name of the program
  5320.     to the array pointed to by BUF.  BUF_SIZE is the size of the
  5321.     array, including the trailing null character.  The number of
  5322.     seconds remaining until automatic unloading is stored to the
  5323.     integer pointed to by PSECONDS.  If automatic unloading is
  5324.     disabled for that program, _EMXLOAD_INDEFINITE is stored.
  5325.  
  5326.     If you stop calling _emxload_list_get() before information about
  5327.     all the programs has been transferred, you should call
  5328.     _emxload_disconnect() to close the connection.  Calling
  5329.     _emxload_disconnect() is not required if _emxload_list_start()
  5330.     returns a non-zero value or after _emxload_list_get() returns a
  5331.     non-zero value.
  5332.  
  5333.     Do not call _emxload_list_get() without prior calling
  5334.     _emxload_list_start().  Do not call _emxload_list_get() if the
  5335.     previous call to _emxload_list_start() or _emxload_list_get()
  5336.     returned a non-zero value.
  5337.  
  5338. ■returnvalue
  5339. ■description
  5340. ■item 0
  5341.     request processed successfully
  5342. ■item -1
  5343.     an error occured
  5344. ■item 1
  5345.     end of the list of programs (_emxload_list_get() only)
  5346. ■enddescription
  5347.  
  5348. ■restrictions
  5349.  
  5350.     Under DOS, _emxload_list_start() and _emxload_list_get() do
  5351.     nothing and return -1.
  5352.  
  5353. ■seealso _emxload_prog() _emxload_disconnect()
  5354.  
  5355.  
  5356. ■function _emxload_prog()
  5357. ■compat emx
  5358. ■headers
  5359. #include <sys/emxload.h>
  5360. ■endheaders
  5361.  
  5362. ■param NAME SECONDS
  5363. ■prototype
  5364. int _emxload_prog (const char *NAME, int SECONDS)
  5365. ■endprototype
  5366.  
  5367.     Keep a program in memory for SECONDS seconds.  NAME points to a
  5368.     string containing the file name of the program.  If SECONDS is
  5369.     _EMXLOAD_INDEFINITE, the program will not be unloaded
  5370.     automatically.  The default extension of the name is .exe, the
  5371.     PATH environment variable is used for finding the executable file.
  5372.  
  5373.     The emxload server process is started by _emxload_prog() if
  5374.     SECONDS and the string pointed to by NAME are valid and the
  5375.     emxload server process is not already running.
  5376.  
  5377. ■returnvalue
  5378. ■description
  5379. ■item 0
  5380.     request successfully sent to the emxload server process
  5381. ■item -1
  5382.     error: the program has not been found or the emxload server process
  5383.     could not be started
  5384. ■enddescription
  5385.  
  5386. ■restrictions
  5387.  
  5388.     Under DOS, _emxload_prog() does nothing and returns -1.
  5389.  
  5390. ■seealso _emxload_connect() _emxload_env() _emxload_list_start() _emxload_this() _emxload_unload()
  5391.  
  5392.  
  5393. ■function _emxload_stop()
  5394. ■compat emx
  5395. ■headers
  5396. #include <sys/emxload.h>
  5397. ■endheaders
  5398.  
  5399. ■param WAIT_FLAG
  5400. ■prototype
  5401. int _emxload_stop (int WAIT_FLAG)
  5402. ■endprototype
  5403.  
  5404.     Stop the emxload server process.  All preloaded programs will be
  5405.     unloaded.  If WAIT_FLAG is zero, _emxload_stop() returns
  5406.     immediately after sending the request to the server.  If WAIT_FLAG
  5407.     is non-zero, _emxload_stop() waits until the server process no
  5408.     longer exists.
  5409.  
  5410. ■returnvalue
  5411. ■description
  5412. ■item 0
  5413.     emxload server process stopped
  5414. ■item -1
  5415.     the emxload server process was not running or could not be stopped
  5416. ■enddescription
  5417.  
  5418. ■restrictions
  5419.  
  5420.     Under DOS, _emxload_stop() does nothing and returns -1.
  5421.  
  5422. ■seealso _emxload_connect()
  5423.  
  5424.  
  5425. ■function _emxload_this()
  5426. ■compat emx
  5427. ■headers
  5428. #include <sys/emxload.h>
  5429. ■endheaders
  5430.  
  5431. ■param SECONDS
  5432. ■prototype
  5433. int _emxload_this (int SECONDS)
  5434. ■endprototype
  5435.  
  5436.     Keep (another copy of) the current program in memory for SECONDS
  5437.     seconds.  If SECONDS is _EMXLOAD_INDEFINITE, the program will not
  5438.     be unloaded automatically.
  5439.  
  5440.     The emxload server process is started by _emxload_this() if
  5441.     SECONDS is valid and the emxload server process is not already
  5442.     running.
  5443.  
  5444. ■returnvalue
  5445. ■description
  5446. ■item 0
  5447.     request successfully sent to the emxload server process
  5448. ■item -1
  5449.     error: SECONDS is invalid or the emxload server process could
  5450.     not be started
  5451. ■enddescription
  5452.  
  5453. ■restrictions
  5454.  
  5455.     Under DOS, _emxload_this() does nothing and returns -1.
  5456.  
  5457. ■seealso _emxload_env() _emxload_prog() _emxload_unload()
  5458.  
  5459.  
  5460. ■function _emxload_unload()
  5461. ■compat emx
  5462. ■headers
  5463. #include <sys/emxload.h>
  5464. ■endheaders
  5465.  
  5466. ■param NAME WAIT_FLAG
  5467. ■prototype
  5468. int _emxload_unload (const char *NAME, int WAIT_FLAG)
  5469. ■endprototype
  5470.  
  5471.     Unload a preloaded program.  NAME points to a string containing
  5472.     the file name of the program.  The default extension for the file
  5473.     name is .exe, the PATH environment variable is used for finding
  5474.     the executable file.  If WAIT_FLAG is zero, _emxload_unload()
  5475.     returns immediately after sending the request to the server.  If
  5476.     WAIT_FLAG is non-zero, _emxload_unload() waits until the server
  5477.     process has unloaded the program.
  5478.  
  5479. ■returnvalue
  5480. ■description
  5481. ■item 0
  5482.     request successfully sent to the emxload server process
  5483. ■item -1
  5484.     error: the program has not been found
  5485. ■enddescription
  5486.  
  5487. ■restrictions
  5488.  
  5489.     Under DOS, _emxload_unload() does nothing and returns -1.
  5490.  
  5491. ■seealso _emxload_prog() _emxload_stop()
  5492.  
  5493.  
  5494. ■function _endthread()
  5495. ■compat PC
  5496. ■headers
  5497. #include <stdlib.h>
  5498. ■endheaders
  5499.  
  5500. ■prototype
  5501. void _endthread (void);
  5502. ■endprototype
  5503.  
  5504.     A thread that has been created by _beginthread() can call
  5505.     _endthread() to end its execution.  A thread also ends when the
  5506.     function started with _beginthread() returns.  In that case,
  5507.     _endthread() will be called automatically.  Terminating the main
  5508.     thread (thread 1) of a process terminates the process (return
  5509.     value will be 0).  Do not use DosExit to end a thread started by
  5510.     _beginthread().
  5511.  
  5512.     _endthread() is available only in the multithread libraries (-Zmt,
  5513.     -Zmts, or -Zmtd).
  5514.  
  5515. ■seealso _beginthread()
  5516.  
  5517.  
  5518. ■function _envargs()
  5519. ■compat emx
  5520. ■headers
  5521. #include <stdlib.h>
  5522. ■endheaders
  5523.  
  5524. ■param ARGCP ARGVP NAME
  5525. ■prototype
  5526. void _envargs (int *ARGCP, char ***ARGVP, const char *NAME);
  5527. ■endprototype
  5528.  
  5529.     Take arguments from the environment variable whose name is in the
  5530.     string pointed to by NAME and insert them before the arguments
  5531.     given on the command line.  If you want to get arguments from the
  5532.     environment variable MYPROGOPT, insert
  5533.  
  5534. ■example
  5535. _envargs (&argc, &argv, "MYPROGOPT");
  5536. ■endexample
  5537.  
  5538.     at the beginning of main().  The contents of the environment
  5539.     variable is parsed the same way as the command line, including
  5540.     quoting.  If you call _response() or _wildcard() after _envargs(),
  5541.     the arguments taken from the environment variable are treated like
  5542.     command line arguments, that is, _wildcard() will expand wildcards
  5543.     in the value of the environment variable unless they are quoted.
  5544.  
  5545.     If the environment variable is not defined or if there is not
  5546.     enough memory, _envargs() does not modify *ARGCP and *ARGVP.
  5547.  
  5548. ■seealso getenv() main() _response() _wildcard()
  5549.  
  5550.  
  5551. ■function eof()
  5552. ■compat PC
  5553. ■headers
  5554. #include <io.h>
  5555. ■endheaders
  5556.  
  5557. ■param HANDLE
  5558. ■prototype
  5559. int eof (int HANDLE);
  5560. ■endprototype
  5561.  
  5562.     Check whether the current position of HANDLE is at the end of the
  5563.     file or not.
  5564.  
  5565. ■returnvalue
  5566. ■description
  5567. ■item 1
  5568.     at end of file
  5569. ■item 0
  5570.     not at end of file
  5571. ■item -1
  5572.     error
  5573. ■enddescription
  5574.  
  5575.  
  5576. ■function _errno()
  5577. ■compat emx
  5578. ■headers
  5579. #include <errno.h>
  5580. ■endheaders
  5581.  
  5582. ■prototype
  5583. int *_errno (void);
  5584. ■endprototype
  5585.  
  5586.     Return the address of the errno value.  In single-thread
  5587.     programs, errno is a variable, in multithread programs, errno
  5588.     is an lvalue that depends on the thread number.  In consequence,
  5589.     you cannot create a library that uses errno and can be used for
  5590.     both single-thread and multithread programs.  To solve this
  5591.     problem, the _errno() function has been provided: it returns a
  5592.     pointer to the errno value in both single-thread and
  5593.     multithread programs.  Use the option
  5594.  
  5595. ■example
  5596. -D__ST_MT_ERRNO__
  5597. ■endexample
  5598.  
  5599.     on the GCC command line to define errno to call _errno().
  5600.     However, using _errno() doesn't remove any other reasons why your
  5601.     library might not be thread-safe.
  5602.  
  5603. ■seealso errno
  5604.  
  5605.  
  5606. ■function exec*() execl() execle() execlp() execlpe() execv() execve() execvp() execvpe()
  5607. ■compat UNIX
  5608. ■headers
  5609. #include <process.h>
  5610. ■endheaders
  5611.  
  5612. ■param NAME ARG0 ARGV ENVP
  5613. ■prototype
  5614. int execl (const char *NAME, const char *ARG0, ...);
  5615. int execle (const char *NAME, const char *ARG0, ...);
  5616. int execlp (const char *NAME, const char *ARG0, ...);
  5617. int execlpe (const char *NAME, const char *ARG0, ...);
  5618. int execv (const char *NAME, char * const ARGV[]);
  5619. int execve (const char *NAME, char * const ARGV[], char * const ENVP[]);
  5620. int execvp (const char *NAME, char * const ARGV[]);
  5621. int execvpe(const char *NAME, char * const ARGV[], char * const ENVP[]);
  5622. ■endprototype
  5623.  
  5624.     Replace calling process with a new process.  The calling process
  5625.     terminates after starting the new process.  NAME points to a
  5626.     string containing the name of the executable file to run.
  5627.  
  5628.     Use execl(), execle(), execlp() or execlpe() for passing a fixed
  5629.     number of arguments.  ARG0 points to a string containing the 0th
  5630.     argument which is the program name, by convention.  Following
  5631.     ARG0, pointers to the argument strings are passed.  After the last
  5632.     argument pointer, a null pointer cast to `■tt{char *}' must be
  5633.     following.  At least ARG0 must be specified.
  5634.  
  5635.     Use execv(), execve(), execvp() or execvpe() for passing a
  5636.     variable number of arguments.  ARGV points to an array of pointers
  5637.     to strings.  The first entry is the program name, by convention.
  5638.     The last argument must be followed by a null pointer.
  5639.  
  5640.     execl(), execlp(), execv() and execvp() pass the environment of
  5641.     the current process to the new process.  To pass a different
  5642.     environment to the new process, pass a pointer to an array of
  5643.     pointers to strings after the null argument pointer of execle()
  5644.     and execlpe() or pass the pointer in the ENVP argument of execve()
  5645.     and execvpe().  The last pointer to an environment string in the
  5646.     array must be followed by a null pointer.
  5647.  
  5648.     If both the old process and the new process use emx.exe or
  5649.     emx.dll, the new process will inherit the signal actions of the
  5650.     old process: Signals set to SIG_IGN in the old process will be set
  5651.     to SIG_IGN in the new process, signals set to SIG_DFL in the old
  5652.     process will be set to SIG_DFL in the new process, signals caught
  5653.     in the old process will be set to SIG_DFL in the new process.
  5654.  
  5655.     When the new process ends, the parent process will be notified by
  5656.     SIGCHLD and wait() will return the original process ID.
  5657.  
  5658. ■returnvalue
  5659.  
  5660.     These functions return -1 if an error occurs.  On success, they do
  5661.     not return.
  5662.  
  5663. ■restrictions
  5664.  
  5665.     Native DOS programs cannot be run.  The new process gets a new
  5666.     process ID.  Unless the new process is an emx program (using
  5667.     emx.dll or emx.exe), the actions for all signals are reset to
  5668.     SIG_DFL in the new process
  5669.  
  5670. ■seealso fork() sigaction() signal() spawn*() wait() waitpid()
  5671.  
  5672.  
  5673. ■function _execname()
  5674. ■compat emx
  5675. ■headers
  5676. #include <stdlib.h>
  5677. ■endheaders
  5678.  
  5679. ■param BUF BUFSIZE
  5680. ■prototype
  5681. int _execname (char *BUF, size_t BUFSIZE);
  5682. ■endprototype
  5683.  
  5684.     Copy the full path name of the executable file for the current
  5685.     process to the array pointed to by BUF.  It is assumed that there
  5686.     are BUFSIZE bytes available at BUF, including the terminating null
  5687.     character.
  5688.  
  5689. ■returnvalue
  5690.  
  5691.     _execname() returns 0 on success, -1 on error (buffer too small,
  5692.     for instance).
  5693.  
  5694. ■restrictions
  5695.  
  5696.     _execname() is not yet implemented under DOS.
  5697.  
  5698. ■seealso main()
  5699.  
  5700.  
  5701. ■function exit()
  5702. ■compat C90
  5703. ■headers
  5704. #include <stdlib.h>
  5705. ■endheaders
  5706.  
  5707. ■param RET
  5708. ■prototype
  5709. void exit (int RET);
  5710. ■endprototype
  5711.  
  5712.     Flush streams, remove temporary files, call functions set by
  5713.     atexit() and terminate the current process.  The return code RET
  5714.     is passed to the parent process.  If RET is negative or greater
  5715.     than 255, 255 will be used instead to avoid returning 0 (success)
  5716.     for non-zero RET due to truncation to 8 bits.
  5717.  
  5718. ■seealso abort() atexit() _exit()
  5719.  
  5720.  
  5721. ■function _exit()
  5722. ■compat UNIX
  5723. ■headers
  5724. #include <stdlib.h>
  5725. ■endheaders
  5726.  
  5727. ■param RET
  5728. ■prototype
  5729. void _exit (int RET);
  5730. ■endprototype
  5731.  
  5732.     Terminate the process without flushing streams, removing temporary
  5733.     files or calling functions set by atexit().  The return code RET
  5734.     is passed to the parent process.  If RET is negative or greater
  5735.     than 255, 255 will be used instead to avoid returning 0 (success)
  5736.     for non-zero RET due to truncation to 8 bits.
  5737.  
  5738. ■seealso abort() atexit() exit()
  5739.  
  5740.  
  5741. ■function exp() expl()
  5742. ■compat C90 C9X
  5743. ■headers
  5744. #include <math.h>
  5745. ■endheaders
  5746.  
  5747. ■param X
  5748. ■prototype
  5749. double exp (double X);
  5750. long double expl (long double X);
  5751. ■endprototype
  5752.  
  5753.     exp() computes the exponential function of X.  On overflow, +INF
  5754.     is returned and errno set to ERANGE.
  5755.  
  5756.     expl() uses the ■tt{long double} format.
  5757.  
  5758. ■returnvalue
  5759.  
  5760.     exp() returns e^■pa{X}.  On overflow, exp() returns +INF.
  5761.  
  5762.  
  5763. ■seealso log() pow()
  5764.  
  5765.  
  5766. ■function _expand()
  5767. ■compat PC
  5768. ■headers
  5769. #include <stdlib.h>
  5770. ■endheaders
  5771.  
  5772. ■param MEM NEW_SIZE
  5773. ■prototype
  5774. void *_expand (void *MEM, size_t NEW_SIZE);
  5775. ■endprototype
  5776.  
  5777.     Try to expand the memory block pointed to by MEM to the new size
  5778.     NEW_SIZE.  If the block cannot be expanded, NULL is returned.
  5779.     Otherwise, MEM is returned.  Please do not use this function --
  5780.     use realloc() instead.
  5781.  
  5782. ■returnvalue
  5783.  
  5784.     _expand() returns MEM if the block could be resized.  Otherwise,
  5785.     _expand() returns NULL.
  5786.  
  5787. ■seealso realloc()
  5788.  
  5789.  
  5790. ■function fabs() fabsl()
  5791. ■compat C90 C9X
  5792. ■headers
  5793. #include <math.h>
  5794. ■endheaders
  5795.  
  5796. ■param X
  5797. ■prototype
  5798. double fabs (double X);
  5799. long double fabsl (long double X);
  5800. ■endprototype
  5801.  
  5802.     Return the absolute value of X: If X is negative, -■pa{X} is returned.
  5803.     Otherwise, X is returned.
  5804.  
  5805.     fabsl() uses the ■tt{long double} format.
  5806.  
  5807. ■returnvalue
  5808.  
  5809.     fabs() returns the absolute value of its argument.
  5810.  
  5811. ■seealso abs() labs()
  5812.  
  5813.  
  5814. ■function _fassign()
  5815. ■compat emx
  5816. ■headers
  5817. #include <stdio.h>
  5818. ■endheaders
  5819.  
  5820. ■param TARGET SOURCE
  5821. ■prototype
  5822. FILE *_fassign (FILE *TARGET, FILE *SOURCE);
  5823. ■endprototype
  5824.  
  5825.     Replace the stream pointed to by TARGET with the stream pointed to
  5826.     by SOURCE.  After a successful call of _fassign(), the stream
  5827.     pointed to by SOURCE is no longer available and the stream pointed
  5828.     to by TARGET is associated with the file with which the stream
  5829.     pointed to by SOURCE was associated.  _fassign() closes the file
  5830.     previously associated with the stream pointed to by TARGET.
  5831.  
  5832.     If TARGET and SOURCE are equal and both point to a stream,
  5833.     _fassign() does nothing.
  5834.  
  5835. ■returnvalue
  5836.  
  5837.     _fsasign() returns TARGET if successful.  _fassign() returns NULL
  5838.     on error.
  5839.  
  5840. ■seealso freopen() _mfopen() v_fopen() wm_fopen()
  5841.  
  5842. ■samplecode
  5843. #include <stdio.h>
  5844. #include <sys/winmgr.h>
  5845.  
  5846. wm_handle wh_stderr;
  5847.  
  5848. void init (void)
  5849. {
  5850.   FILE *f;
  5851.  
  5852.   /*...*/
  5853.   f = wm_fopen (wh_stderr);
  5854.   _fassign (stderr, f);
  5855. }
  5856. ■endsamplecode
  5857.  
  5858.  
  5859. ■function fclose()
  5860. ■compat C90
  5861. ■headers
  5862. #include <stdio.h>
  5863. ■endheaders
  5864.  
  5865. ■param STREAM
  5866. ■prototype
  5867. int fclose (FILE *STREAM);
  5868. ■endprototype
  5869.  
  5870.     Flush and close the stream STREAM.  STREAM must be open prior to
  5871.     calling fclose().  If the stream buffer was automatically
  5872.     allocated, it will be deallocated.  If the stream was created with
  5873.     tmpfile(), the temporary file will be deleted.
  5874.  
  5875. ■returnvalue
  5876. ■description
  5877. ■item 0
  5878.   success
  5879. ■item EOF
  5880.   error
  5881. ■enddescription
  5882.  
  5883. ■seealso fcloseall() fflush() fopen() tmpfile()
  5884.  
  5885.  
  5886. ■function fcloseall()
  5887. ■compat PC
  5888. ■headers
  5889. #include <stdio.h>
  5890. ■endheaders
  5891.  
  5892. ■prototype
  5893. int fcloseall (void);
  5894. ■endprototype
  5895.  
  5896.     Close all open streams.
  5897.  
  5898. ■returnvalue
  5899.  
  5900.     fcloseall() returns the number of streams closed.  On error,
  5901.     fcloseall() returns EOF.
  5902.  
  5903. ■seealso fclose() flushall() fopen()
  5904.  
  5905.  
  5906. ■function fcntl()
  5907. ■compat BSD *
  5908. ■headers
  5909. #include <fcntl.h>
  5910. ■endheaders
  5911.  
  5912. ■param HANDLE REQUEST ARG
  5913. ■prototype
  5914. int fcntl (int HANDLE, int REQUEST);
  5915. int fcntl (int HANDLE, int REQUEST, int ARG);
  5916. ■endprototype
  5917.  
  5918.     File control.  The following REQUEST codes are implemented
  5919.     (partially):
  5920.  
  5921. ■description
  5922. ■item F_DUPFD
  5923.  
  5924.     Create a duplicate of the file handle HANDLE, that is, another
  5925.     handle that refers to the same file or device or pipe as HANDLE.
  5926.     Both handles share the same file pointer.  The lowest numbered
  5927.     available file handle greater than or equal to ARG will be used
  5928.     and returned.
  5929.  
  5930. ■item F_GETFL
  5931.  
  5932.     Return the file flags of the file associated with HANDLE.
  5933.     Currently, only two file flags are supported by fcntl(): O_APPEND
  5934.     and O_NONBLOCK (alias O_NDELAY).
  5935.  
  5936. ■item F_SETFL
  5937.  
  5938.     Set the file flags of the file associated with HANDLE.  Currently,
  5939.     only two file flags are supported by fcntl(): O_APPEND and
  5940.     O_NONBLOCK (alias O_NDELAY).  O_NONBLOCK has an effect only if
  5941.     HANDLE is 0 and HANDLE refers to the keyboard and the IDEFAULT and
  5942.     ICANON bits are not set.  O_NONBLOCK also works for pipes created
  5943.     by emx programs, for named pipes, and for sockets.  See
  5944.     `■hpt{General terminal interface}' and ■hpt{read()}.
  5945.  
  5946. ■item F_GETFD
  5947.  
  5948.     Return file descriptor flags.  If the return value includes
  5949.     FD_CLOEXEC (close-on-exec flag), HANDLE will not be inherited by
  5950.     child processes created with ■hpt{exec*()} and ■hpt{spawn*()}.
  5951.  
  5952. ■item F_SETFD
  5953.  
  5954.     Set file-descriptor flags.  If the flags include FD_CLOEXEC,
  5955.     (close-on-exec flag), HANDLE will not be inherited by child
  5956.     processes created with ■hpt{exec*()} and ■hpt{spawn*()}.
  5957.  
  5958. ■enddescription
  5959.  
  5960. ■returnvalue
  5961.  
  5962.     On error, fcntl() sets errno and returns -1.  Otherwise, fcntl()
  5963.     returns 0 unless a different return value is defined above.
  5964.  
  5965. ■errors
  5966. ■description
  5967. ■item EBADF
  5968.     The HANDLE argument is not a valid open file descriptor.
  5969. ■item EINVAL
  5970.     REQUEST is invalid.
  5971.  
  5972.     REQUEST is F_DUPFD and ARG is out of range.
  5973.  
  5974.     REQUEST is F_SETFL and ARG is not a combination of supported
  5975.     flags.
  5976.  
  5977. ■item EMFILE
  5978.     REQUEST is F_DUPFD and no file descriptor greater than or equal to
  5979.     ARG is available.
  5980. ■enddescription
  5981.  
  5982. ■restrictions
  5983.  
  5984.     O_NONBLOCK is not supported by the system call library sys.lib
  5985.     (■hpt{-Zsys}).
  5986.  
  5987.     Duplicated file handles should share the file status flags
  5988.     O_APPEND and O_NONBLOCK; however, F_DUPFD, dup(), and dup2() just
  5989.     copy the file status flags, changing the file status flags after
  5990.     duplicating a file handle does not affect the other file handle.
  5991.  
  5992.     F_GETFL should return the access mode but doesn't.
  5993.  
  5994.     Under DOS, FD_CLOEXEC is currently ignored for child processes
  5995.     which are DOS programs (vs. emx programs).
  5996.  
  5997. ■seealso dup() ioctl() open() read()
  5998.  
  5999.  
  6000. ■function fdopen()
  6001. ■compat UNIX
  6002. ■headers
  6003. #include <stdio.h>
  6004. ■endheaders
  6005.  
  6006. ■param HANDLE MODE
  6007. ■prototype
  6008. FILE *fdopen (int HANDLE, const char *MODE);
  6009. ■endprototype
  6010.  
  6011.     Create a stream for the file handle HANDLE.  The flags in the mode
  6012.     string pointed to by MODE should match the mode used for opening
  6013.     the file handle HANDLE.  If ■tt{b} or ■tt{t} is used in the mode
  6014.     string, the handle will be changed using setmode() to O_BINARY or
  6015.     O_TEXT mode, respectively.  If neither ■tt{b} nor ■tt{t} is used,
  6016.     the translation mode is not changed.  You should not rely on this
  6017.     behavior: always specify the desired translation mode.
  6018.  
  6019. ■returnvalue
  6020.  
  6021.     fdopen() returns a new stream.  On error, fdopen() returns NULL.
  6022.  
  6023. ■seealso fopen() open()
  6024.  
  6025.  
  6026. ■function ferror() feof()
  6027. ■compat C90
  6028. ■headers
  6029. #include <stdio.h>
  6030. ■endheaders
  6031.  
  6032. ■param STREAM
  6033. ■prototype
  6034. int ferror (FILE *STREAM);
  6035. int feof (FILE *STREAM);
  6036. ■endprototype
  6037.  
  6038.     ferror() checks STREAM for an error condition.  feof() checks
  6039.     STREAM for an end-of-file condition.
  6040.  
  6041. ■returnvalue
  6042.  
  6043.     ferror() returns a non-zero value if the error indicator of STREAM
  6044.     is set.  Otherwise, ferror() returns zero.  feof() returns a
  6045.     non-zero value if the end-of-file indicator of STREAM is set.
  6046.     Otherwise, feof() returns zero.
  6047.  
  6048. ■hints
  6049.  
  6050.     The end-of-file indicator is not set if the file position
  6051.     indicator reaches the end of the file; rather, it is set when
  6052.     attempting to read past end-of-file.
  6053.  
  6054. ■seealso clearerr() fgetc() rewind()
  6055.  
  6056.  
  6057. ■function fflush()
  6058. ■compat C90
  6059. ■headers
  6060. #include <stdio.h>
  6061. ■endheaders
  6062.  
  6063. ■param STREAM
  6064. ■prototype
  6065. int fflush (FILE *STREAM);
  6066. ■endprototype
  6067.  
  6068.     If STREAM is an output stream or an update stream in write mode,
  6069.     write unwritten data of STREAM's buffer to its file.  If STREAM is
  6070.     NULL, fflush() is applied to all open output streams and update
  6071.     streams in write mode.
  6072.  
  6073.     If STREAM is an update stream in write mode, the next operation on
  6074.     STREAM may be input or output.
  6075.  
  6076. ■returnvalue
  6077.  
  6078.     fflush() returns EOF if a write error occurs, otherwise zero.
  6079.  
  6080. ■implementation
  6081.  
  6082.     If STREAM is an input stream, fflush() discards the buffer
  6083.     contents and undoes any effects of ungetc().  If the stream is
  6084.     connected to a disk file, the buffer will be refilled (no data
  6085.     lost) on the next input operation.  If the stream is connected to
  6086.     a character device, a pipe, or a socket, the buffer contents will
  6087.     be lost.  (Note that this does not clear the type-ahead buffer of
  6088.     the keyboard device!  Only the data which has been read into the
  6089.     buffer will be discarded.)
  6090.  
  6091. ■hints
  6092.  
  6093.     Use fflush() for switching an update stream from write mode to
  6094.     read mode: output may not be directly followed by input --
  6095.     fflush(), fseek(), fsetpos(), or rewind() must be called between
  6096.     output and input.
  6097.  
  6098.     Use fflush() to force output (for instance, a prompt) of a
  6099.     buffered stream to a device: you should do
  6100. ■example
  6101. fflush (stdout);
  6102. ■endexample
  6103.     before getting input from stdin, in case stdout is connected to a
  6104.     pipe (a stream connected to a pipe is buffered by default).
  6105.  
  6106. ■seealso fclose() fopen() fseek() ungetc()
  6107.  
  6108.  
  6109. ■function ffs()
  6110. ■compat BSD
  6111. ■headers
  6112. #include <strings.h>
  6113. ■endheaders
  6114.  
  6115. ■param I
  6116. ■prototype
  6117. int ffs (int I);
  6118. ■endprototype
  6119.  
  6120.     Find the first (least significant, right-most) bit in I which is
  6121.     set and return the index of that bit.  The least significant bit
  6122.     is numbered 1, the most significant bit is numbered 32.
  6123.  
  6124. ■returnvalue
  6125.  
  6126.     ffs() returns the smallest number ■pa{N} for which bit ■pa{N} is
  6127.     set in I (the least significant bit is numbered 1).  If there are
  6128.     no bits set in I (that is, I is zero), ffs() returns zero.
  6129.  
  6130. ■seealso __fls()
  6131.  
  6132.  
  6133. ■function fgetc()
  6134. ■compat C90
  6135. ■headers
  6136. #include <stdio.h>
  6137. ■endheaders
  6138.  
  6139. ■param STREAM
  6140. ■prototype
  6141. int fgetc (FILE *STREAM);
  6142. ■endprototype
  6143.  
  6144.     Read the next character (as ■tt{unsigned char} converted to an
  6145.     ■tt{int}) from the input stream STREAM and advance the file
  6146.     position indicator of the stream (if defined).  All input from
  6147.     streams takes place as if characters were read by successive calls
  6148.     to fgetc().
  6149.  
  6150.     fgetc() is a function, in contrast to getc().
  6151.  
  6152. ■returnvalue
  6153.  
  6154.     fgetc() returns the next character from the stream.  If the stream
  6155.     is at end-of-file (before fgetc() is called), fgetc() sets the
  6156.     end-of-file indicator of the stream and returns EOF.  If a read
  6157.     error occurs, fgetc() sets the error indicator of the stream and
  6158.     returns EOF.
  6159.  
  6160. ■hints
  6161.  
  6162.     Use feof() and ferror() to distinguish an end-of-file condition
  6163.     from a read error.
  6164.  
  6165.     If you assign the return value of fgetc() to a ■tt{char} variable,
  6166.     you cannot compare it to EOF.  Use an ■tt{int} variable instead.
  6167.  
  6168. ■seealso feof() ferror() fgetchar() getc() getchar()
  6169.  
  6170.  
  6171. ■function fgetchar()
  6172. ■compat PC
  6173. ■headers
  6174. #include <stdio.h>
  6175. ■endheaders
  6176.  
  6177. ■prototype
  6178. int fgetchar (void);
  6179. ■endprototype
  6180.  
  6181.     fgetchar() is equivalent to ■tt{fgetc (stdin)}.
  6182.  
  6183. ■returnvalue
  6184.  
  6185.     fgetchar() returns the next character from stdin.  If stdin is at
  6186.     end-of-file (before fgetchar() is called), fgetchar() sets the
  6187.     end-of-file indicator of stdin and returns EOF.  If a read error
  6188.     occurs, fgetchar() sets the error indicator of stdin and returns
  6189.     EOF.
  6190.  
  6191. ■hints
  6192.  
  6193.     Use getchar() or ■tt{fgetc(stdin)} instead of fgetchar() as
  6194.     fgetchar() is not portable.
  6195.  
  6196. ■seealso fgetc() getchar()
  6197.  
  6198.  
  6199. ■function fgetpos()
  6200. ■compat C90
  6201. ■headers
  6202. #include <stdio.h>
  6203. ■endheaders
  6204.  
  6205. ■param STREAM POS
  6206. ■prototype
  6207. int fgetpos (FILE *STREAM, fpos_t *POS);
  6208. ■endprototype
  6209.  
  6210.     Store the current position of the file pointer of the file STREAM
  6211.     in the variable pointed to by POS.
  6212.  
  6213. ■returnvalue
  6214. ■description
  6215. ■item 0
  6216.     success
  6217. ■item non-0
  6218.     error
  6219. ■enddescription
  6220.  
  6221. ■restrictions
  6222.  
  6223.     fgetpos() does not work for text-mode streams unless either CR/LF
  6224.     pairs or LF only is used for all lines of the file.  If there are
  6225.     lines terminated with CR/LF and lines terminated with LF,
  6226.     fgetpos() does not work correctly.
  6227.  
  6228. ■seealso fsetpos() ftell()
  6229.  
  6230.  
  6231. ■function fgets()
  6232. ■compat C90
  6233. ■headers
  6234. #include <stdio.h>
  6235. ■endheaders
  6236.  
  6237. ■param BUFFER N STREAM
  6238. ■prototype
  6239. char *fgets (char *BUFFER, int N, FILE *STREAM);
  6240. ■endprototype
  6241.  
  6242.     Read a string from STREAM to the array pointed to by BUFFER.  Stop
  6243.     after reading ■pa{N}-1 characters or after a newline character has
  6244.     been read.  A null character is appended.
  6245.  
  6246. ■returnvalue
  6247.  
  6248.     fgets() returns BUFFER.  If end of file occurs before any
  6249.     character has been read, the array pointed to by BUFFER will
  6250.     remain unchanged and fgets() will return NULL.  If a read error
  6251.     occurs, fgets() will return NULL.
  6252.  
  6253. ■seealso gets() scanf()
  6254.  
  6255.  
  6256. ■function filelength()
  6257. ■compat PC
  6258. ■headers
  6259. #include <io.h>
  6260. ■endheaders
  6261.  
  6262. ■param HANDLE
  6263. ■prototype
  6264. long filelength (int HANDLE);
  6265. ■endprototype
  6266.  
  6267.     Get the length of the file HANDLE, in bytes.
  6268.  
  6269. ■returnvalue
  6270.  
  6271.     filelength() returns the length of the file HANDLE.  If there is
  6272.     an error, filelength() returns -1.
  6273.  
  6274. ■seealso chsize() ftruncate() lseek()
  6275.  
  6276.  
  6277. ■function fileno()
  6278. ■compat UNIX
  6279. ■headers
  6280. #include <stdio.h>
  6281. ■endheaders
  6282.  
  6283. ■param STREAM
  6284. ■prototype
  6285. int fileno (FILE *STREAM);
  6286. ■endprototype
  6287.  
  6288.     Get the file handle associated with STREAM.
  6289.  
  6290. ■returnvalue
  6291.  
  6292.     fileno() returns the file handle associated with STREAM.
  6293.  
  6294. ■seealso fdopen()
  6295.  
  6296.  
  6297. ■function _filesys()
  6298. ■compat emx
  6299. ■headers
  6300. #include <stdlib.h>
  6301. ■endheaders
  6302.  
  6303. ■param DRIVE NAME SIZE
  6304. ■prototype
  6305. int _filesys (const char *DRIVE, char *NAME, size_t SIZE);
  6306. ■endprototype
  6307.  
  6308.     Copy the file system type of the disk drive whose name is in the
  6309.     string pointed to by DRIVE to the array pointed to by NAME.  The
  6310.     size of the array is SIZE bytes.  DRIVE must point to a drive
  6311.     letter followed by a colon.  Examples for file system types are:
  6312.     FAT, LAN, HPFS, CDFS, NFS.
  6313.  
  6314. ■returnvalue
  6315.  
  6316. ■description
  6317. ■item 0
  6318.     Success.  The file system type has been copied to NAME.
  6319. ■item -1
  6320.     Error.  errno contains the error number.
  6321. ■enddescription
  6322.  
  6323. ■seealso _fnlwr()
  6324.  
  6325. ■samplecode
  6326. char drive[3] = "C:";
  6327. char fsys[16];
  6328.  
  6329. if (_filesys (drive, fsys, sizeof (fsys)) != 0)
  6330.   perror ("_filesys");
  6331. else
  6332.   printf ("File system: %s\n", fsys);
  6333. ■endsamplecode
  6334.  
  6335.     Typical output of the example:
  6336.  
  6337. ■example
  6338. File system: FAT
  6339. ■endexample
  6340.  
  6341.  
  6342. ■function flock()
  6343. ■compat UNIX
  6344. ■headers
  6345. #include <fcntl.h>
  6346. ■endheaders
  6347.  
  6348. ■param HANDLE OPERATION
  6349. ■prototype
  6350. int flock (int HANDLE, int OPERATION)
  6351. ■endprototype
  6352.  
  6353.     Perform file locking.
  6354.  
  6355. ■returnvalue
  6356. ■description
  6357. ■item 0
  6358.     success
  6359. ■item -1
  6360.     error
  6361. ■enddescription
  6362.  
  6363. ■restrictions
  6364.  
  6365.     flock() is not yet implemented (dummy function).
  6366.  
  6367.  
  6368. ■function floor() floorl()
  6369. ■compat C90 C9X
  6370. ■headers
  6371. #include <math.h>
  6372. ■endheaders
  6373.  
  6374. ■param X
  6375. ■prototype
  6376. double floor (double X);
  6377. long double floorl (long double X);
  6378. ■endprototype
  6379.  
  6380.     Compute the largest integer that is less than or equal to X (round
  6381.     down).
  6382.  
  6383.     floorl() uses the ■tt{long double} format.
  6384.  
  6385. ■returnvalue
  6386.  
  6387.     Return as floating-point number the largest integer that is less
  6388.     than or equal to X.
  6389.  
  6390. ■seealso ceil() rint() trunc()
  6391.  
  6392.  
  6393. ■function __fls()
  6394. ■compat emx
  6395. ■headers
  6396. #include <sys/builtin.h>
  6397. ■endheaders
  6398.  
  6399. ■param I
  6400. ■prototype
  6401. int __fls (int I);
  6402. ■endprototype
  6403.  
  6404.     Find the last (most significant, left-most) bit in I which is
  6405.     set and return the index of that bit.  The most significant bit
  6406.     is numbered 32, the least significant bit is numbered 1.
  6407.  
  6408.     This function is implemented as inline function.
  6409.  
  6410. ■returnvalue
  6411.  
  6412.     __fls() returns the greatest number ■pa{N} for which bit ■pa{N} is
  6413.     set in I (the least significant bit is numbered 1).  If there are
  6414.     no bits set in I (that is, I is zero), __fls() returns zero.
  6415.  
  6416. ■seealso ffs()
  6417.  
  6418.  
  6419. ■function flushall()
  6420. ■compat PC
  6421. ■headers
  6422. #include <stdio.h>
  6423. ■endheaders
  6424.  
  6425. ■prototype
  6426. int flushall (void);
  6427. ■endprototype
  6428.  
  6429.     Flush the buffers of all open streams.  Write the buffers of
  6430.     streams open for writing to their files, clear the buffers of
  6431.     streams open for reading.
  6432.  
  6433.     Locked streams are ignored; therefore, flushall() can be called in
  6434.     signal handlers.
  6435.  
  6436. ■returnvalue
  6437.  
  6438.     flushall() returns the number of open streams.
  6439.  
  6440. ■hints
  6441.  
  6442.     If you don't need the return value (that is, the number of open
  6443.     streams) and deadlock on locked streams cannot occur, you should
  6444.     use
  6445. ■example
  6446. fflush (NULL)
  6447. ■endexample
  6448.     instead of flushall().
  6449.  
  6450. ■seealso fflush()
  6451.  
  6452.  
  6453. ■function fmod() fmodl()
  6454. ■compat C90 C9X
  6455. ■headers
  6456. #include <math.h>
  6457. ■endheaders
  6458.  
  6459. ■param X Y
  6460. ■prototype
  6461. double fmod (double X, double Y);
  6462. long double fmodl (long double X, long double Y);
  6463. ■endprototype
  6464.  
  6465.     Compute remainder of ■pa{X}/■pa{Y}.  The return value z is
  6466.     calculated such that X = i * Y + z, where i is an integer, z has
  6467.     the same sign as X and |z| < |■pa{Y}|.  If Y is 0.0, fmod()
  6468.     returns 0.0.
  6469.  
  6470.     fmodl() uses the ■tt{long double} format.
  6471.  
  6472. ■returnvalue
  6473.  
  6474.     See above.
  6475.  
  6476.  
  6477. ■function _fmutex_available()
  6478. ■compat emx
  6479. ■headers
  6480. #include <sys/builtin.h>
  6481. #include <sys/fmutex.h>
  6482. ■endheaders
  6483.  
  6484. ■param SEM
  6485. ■prototype
  6486. int _fmutex_available (_fmutex *SEM);
  6487. ■endprototype
  6488.  
  6489.     Check if the _fmutex semaphore pointed to by SEM is available or
  6490.     owned, without changing the state of the semaphore and without
  6491.     blocking.  Return zero if the semaphore is owned, return a
  6492.     non-zero value if the semaphore is available.  Note that
  6493.     _fmutex_available() just returns a snapshot of the state of the
  6494.     semaphore; in presence of other threads or, in case of a shared
  6495.     semaphore, other processes, the state may change at any time, even
  6496.     before _fmutex_available() returns. This function can be used to
  6497.     avoid deadlock.
  6498.  
  6499. ■returnvalue
  6500.  
  6501.     _fmutex_available() returns a non-zero value if the semaphore is
  6502.     available.  _fmutex_available() returns 0 if the semaphore is
  6503.     owned.  The return value is undefined if the object pointed to by
  6504.     SEM has not been initialized by _fmutex_create().
  6505.  
  6506. ■seealso _fmutex_close() _fmutex_create() _fmutex_open() _fmutex_release() _fmutex_request() _rmutex_available() _smutex_available()
  6507.  
  6508.  
  6509. ■function _fmutex_close() _fmutex_checked_close()
  6510. ■compat emx
  6511. ■headers
  6512. #include <sys/builtin.h>
  6513. #include <sys/fmutex.h>
  6514. ■endheaders
  6515.  
  6516. ■param SEM
  6517. ■prototype
  6518. unsigned _fmutex_close (_fmutex *SEM);
  6519. void _fmutex_checked_close (_fmutex *SEM);
  6520. ■endprototype
  6521.  
  6522.     Close an _fmutex semaphore.  SEM should point to an _fmutex object
  6523.     initialized by _fmutex_create().  If there have been ■pa{N} calls
  6524.     to ■hpt{_fmutex_open()} for this semaphore, ■pa{N}+1 calls to
  6525.     _fmutex_close() are required to destroy the semaphore, one call
  6526.     for ■hpt{_fmutex_create()} and one call per _fmutex_open().  The
  6527.     semaphore can no longer be used after it has been destroyed.
  6528.  
  6529.     _fmutex_checked_close() does not return an error code; it calls
  6530.     abort() on failure.
  6531.  
  6532. ■returnvalue
  6533.  
  6534.     _fmutex_close() returns 0 if successful.  Otherwise,
  6535.     _fmutex_close() returns an OS/2 error code defined in <os2.h> such
  6536.     as ERROR_INVALID_HANDLE.  Under DOS, _fmutex_close() always
  6537.     returns 0.
  6538.  
  6539. ■seealso abort() atexit() _fmutex_available() _fmutex_create() _fmutex_open() _fmutex_release() _fmutex_request() _rmutex_close()
  6540.  
  6541.  
  6542. ■function _fmutex_create() _fmutex_checked_create()
  6543. ■compat emx
  6544. ■headers
  6545. #include <sys/builtin.h>
  6546. #include <sys/fmutex.h>
  6547. ■endheaders
  6548.  
  6549. ■param SEM FLAGS
  6550. ■prototype
  6551. unsigned _fmutex_create (_fmutex *SEM, unsigned FLAGS);
  6552. void _fmutex_checked_create (_fmutex *SEM, unsigned FLAGS);
  6553. ■endprototype
  6554.  
  6555.     Create an _fmutex semaphore.  SEM points to the _fmutex object to
  6556.     be initialized.  The semaphore is local to the process if FLAGS is
  6557.     0.  The semaphore can be shared by multiple processes if FLAGS is
  6558.     _FMC_SHARED.  A shared _fmutex semaphore must be located in shared
  6559.     memory (that is, SEM must point to an object in shared memory).
  6560.  
  6561.     _fmutex_checked_create() does not return an error code; it calls
  6562.     abort() on failure.
  6563.  
  6564. ■returnvalue
  6565.  
  6566.     _fmutex_create() returns 0 if successful.  Otherwise,
  6567.     _fmutex_create() returns an OS/2 error code defined in <os2.h>
  6568.     such as ERROR_TOO_MANY_HANDLES.  Under DOS, _fmutex_create()
  6569.     always returns 0.
  6570.  
  6571. ■seealso abort() _fmutex_available() _fmutex_close() _fmutex_dummy() _fmutex_open() _fmutex_release() _fmutex_request() _rmutex_create()
  6572.  
  6573.  
  6574. ■function _fmutex_dummy()
  6575. ■compat emx
  6576. ■headers
  6577. #include <sys/builtin.h>
  6578. #include <sys/fmutex.h>
  6579. ■endheaders
  6580.  
  6581. ■param SEM
  6582. ■prototype
  6583. void _fmutex_dummy (_fmutex *SEM);
  6584. ■endprototype
  6585.  
  6586.     Create a dummy _fmutex semaphore.  SEM points to the _fmutex
  6587.     object to be initialized.  Behavior is undefined if ownership of a
  6588.     dummy _fmutex semaphore is requested when the semaphore is owned.
  6589.     _fmutex_close() must not be called on a dummy _fmutex semaphore.
  6590.  
  6591. ■seealso _fmutex_create() _rmutex_dummy()
  6592.  
  6593.  
  6594. ■function _fmutex_open() _fmutex_checked_open()
  6595. ■compat emx
  6596. ■headers
  6597. #include <sys/builtin.h>
  6598. #include <sys/fmutex.h>
  6599. ■endheaders
  6600.  
  6601. ■param SEM
  6602. ■prototype
  6603. unsigned _fmutex_open (_fmutex *SEM);
  6604. void _fmutex_checked_open (_fmutex *SEM);
  6605. ■endprototype
  6606.  
  6607.     Open an _fmutex semaphore.  SEM should point to an _fmutex object
  6608.     initialized by ■hpt{_fmutex_create()}.  _fmutex_open() is used to
  6609.     obtain access to a shared _fmutex semaphore created by another
  6610.     process.  All threads of the process which called _fmutex_create()
  6611.     have access to the semaphore without calling _fmutex_open().  Call
  6612.     ■hpt{_fmutex_close()} when you no longer need access to the
  6613.     semaphore.
  6614.  
  6615.     _fmutex_checked_open() does not return an error code; it calls
  6616.     abort() on failure.
  6617.  
  6618. ■returnvalue
  6619.  
  6620.     _fmutex_open() returns 0 if successful.  Otherwise, _fmutex_open()
  6621.     returns an OS/2 error code defined in <os2.h> such as
  6622.     ERROR_INVALID_HANDLE.  Under DOS, _fmutex_open() always returns 0.
  6623.  
  6624. ■seealso abort() atexit() _fmutex_available() _fmutex_close() _fmutex_create() _fmutex_release() _fmutex_request() _rmutex_open()
  6625.  
  6626.  
  6627. ■function _fmutex_release() _fmutex_checked_release()
  6628. ■compat emx
  6629. ■headers
  6630. #include <sys/builtin.h>
  6631. #include <sys/fmutex.h>
  6632. ■endheaders
  6633.  
  6634. ■param SEM
  6635. ■prototype
  6636. unsigned _fmutex_release (_fmutex *SEM);
  6637. void _fmutex_checked_release (_fmutex *SEM);
  6638. ■endprototype
  6639.  
  6640.     Relinquish ownership of the _fmutex semaphore pointed to by SEM.
  6641.     If another thread blocks in ■hpt{_fmutex_request()} for this
  6642.     semaphore, _fmutex_release() will unblock one of the blocking
  6643.     threads.  The semaphore should be owned when _fmutex_release() is
  6644.     called.  Though not strictly necessary, ownership of the semaphore
  6645.     should have been requested by the same thread.
  6646.  
  6647.     _fmutex_checked_release() does not return an error code; it calls
  6648.     abort() on failure.  Note that _fmutex_checked_release() is slower
  6649.     than _fmutex_release() because it is not inlined.
  6650.  
  6651. ■returnvalue
  6652.  
  6653.     _fmutex_release() returns 0 if successful.  Otherwise,
  6654.     _fmutex_release() returns an OS/2 error code defined in <os2.h>
  6655.     such as ERROR_TOO_MANY_HANDLES.
  6656.  
  6657. ■seealso abort() __cxchg() _fmutex_available() _fmutex_close() _fmutex_create() _fmutex_open() _fmutex_request() _rmutex_release()
  6658.  
  6659.  
  6660. ■function _fmutex_request() _fmutex_checked_request()
  6661. ■compat emx
  6662. ■headers
  6663. #include <sys/builtin.h>
  6664. #include <sys/fmutex.h>
  6665. ■endheaders
  6666.  
  6667. ■param SEM FLAGS
  6668. ■prototype
  6669. unsigned _fmutex_request (_fmutex *SEM, unsigned FLAGS);
  6670. void _fmutex_checked_request (_fmutex *SEM, unsigned FLAGS);
  6671. ■endprototype
  6672.  
  6673.     Request ownership of the _fmutex semaphore pointed to by SEM.  If
  6674.     FLAGS is 0, _fmutex_request() returns ERROR_INTERRUPT if
  6675.     interrupted by a signal while blocking.  FLAGS is zero or a set of
  6676.     flags combined with the ■tt{|} operator.  If FLAGS includes
  6677.     _FMR_IGNINT, _fmutex_request() does not return if a signal occurs
  6678.     while blocking.  If FLAGS includes _FMR_NOWAIT and the semaphore
  6679.     is owned, _fmutex_request() returns immediately ERROR_MUTEX_OWNED.
  6680.  
  6681.     _fmutex_checked_request() does not return an error code; it calls
  6682.     abort() on failure.  Note that _fmutex_checked_request() is slower
  6683.     than _fmutex_request() because it is not inlined.
  6684.  
  6685.     If the semaphore is available, it will be set to owned and
  6686.     _fmutex_request() will return immediately.  If the semaphore is
  6687.     owned, _fmutex_request() will block while the semaphore is owned.
  6688.     When ■hpt{_fmutex_release()} is called for the semaphore, one of
  6689.     the threads blocking in _fmutex_request() for this semaphore will
  6690.     wake up and gain ownership of the semaphore.
  6691.  
  6692.     Note that ownership of an _fmutex semaphore is not tied to a
  6693.     thread, that is, it's not a thread which owns the semaphore.  This
  6694.     is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
  6695.     occur if _fmutex_request() is called twice for the same semaphore
  6696.     by the same thread without an intervening call to
  6697.     _fmutex_release().  This fact is important to keep in mind in
  6698.     presence of signals.  Signal handlers must not request semaphores
  6699.     which can be owned by the interrupted code.  You might want to
  6700.     block signals before requesting ownership of an _fmutex semaphore.
  6701.  
  6702. ■returnvalue
  6703.  
  6704.     _fmutex_request() returns 0 if successful.  Otherwise,
  6705.     _fmutex_request() returns an OS/2 error code defined in <os2.h>
  6706.     such as ERROR_INTERRUPT.
  6707.  
  6708. ■restrictions
  6709.  
  6710.     Under DOS, _fmutex_request() and _fmutex_checked_request() crash
  6711.     if the semaphore is already owned.
  6712.  
  6713. ■seealso abort() __cxchg() _fmutex_available() _fmutex_close() _fmutex_create() _fmutex_open() _fmutex_release() _rmutex_request()
  6714.  
  6715.  
  6716. ■function _fncmp()
  6717. ■compat emx
  6718. ■headers
  6719. #include <stdlib.h>
  6720. ■endheaders
  6721.  
  6722. ■param STRING1 STRING2
  6723. ■prototype
  6724. int _fncmp (const unsigned char *STRING1, const unsigned char *STRING2);
  6725. ■endprototype
  6726.  
  6727.     _fncmp() compares the two file name strings pointed to by STRING1
  6728.     and STRING2 and returns zero if the two strings are identical
  6729.     after conversion to upper case.  Otherwise, a non-zero value is
  6730.     returned which is negative if the string pointed to by STRING1 is
  6731.     less than the string pointed to by STRING2 and positive if the
  6732.     string pointed to by STRING1 is greater than the string pointed to
  6733.     by STRING2 after conversion to upper case.  Conversion to upper
  6734.     case includes accented characters etc., depending on the current
  6735.     country code and code page, DBCS characters are compared as is.
  6736.  
  6737. ■returnvalue
  6738. ■description
  6739. ■item <0
  6740.    1st string < 2nd string
  6741. ■item =0
  6742.    1st string = 2nd string
  6743. ■item >0
  6744.    1st string > 2nd string
  6745. ■enddescription
  6746.  
  6747. ■seealso _nls_init() _nls_strupr() strcmp()
  6748.  
  6749.  
  6750. ■function _fnexplode() _fnexplodefree()
  6751. ■compat emx
  6752. ■headers
  6753. #include <stdlib.h>
  6754. ■endheaders
  6755.  
  6756. ■param MASK LIST
  6757. ■prototype
  6758. char **_fnexplode (const char *MASK);
  6759. void _fnexplodefree (char **LIST);
  6760. ■endprototype
  6761.  
  6762.     Wildcard expansion of MASK.  _fnexplode() returns a vector
  6763.     containing pointers to the file name strings.  The list includes
  6764.     directories.  Hidden and system files are omitted.  The end of the
  6765.     list is marked by a NULL pointer.  On error, NULL is returned.
  6766.     MASK not being a wildcard or no files matching MASK is treated as
  6767.     error.  Memory is allocated with malloc().
  6768.  
  6769.     _fnlwr() is used to convert file names to lower case on
  6770.     upper-case-only file systems.
  6771.  
  6772.     Use _fnexplodefree() to free the memory allocated for a file name
  6773.     list.
  6774.  
  6775. ■returnvalue
  6776.  
  6777.     _fnexplode() returns a vector containing pointers to file name
  6778.     strings.
  6779.  
  6780. ■seealso _dt_read() _fnlwr() glob() opendir() _wildcard()
  6781.  
  6782. ■samplefile /emx/samples/eatool.c
  6783.  
  6784.  
  6785. ■function _fngetdrive()
  6786. ■compat emx
  6787. ■headers
  6788. #include <stdlib.h>
  6789. ■endheaders
  6790.  
  6791. ■param SRC
  6792. ■prototype
  6793. char _fngetdrive (const char *SRC);
  6794. ■endprototype
  6795.  
  6796.     Extract the drive name of the path name SRC.
  6797.  
  6798. ■returnvalue
  6799.  
  6800.     _fngetdrive () return as upper-case letter the drive name in the
  6801.     path name pointed to by SRC.  If the string does not contain a
  6802.     drive name, _fngetdrive() returns 0.
  6803.  
  6804. ■seealso _fnisabs() _fnisrel() _getdrive()
  6805.  
  6806. ■samplecode
  6807. /* this fails if the -r emx option is used */
  6808.  
  6809. char *fname, drive;
  6810.  
  6811. drive = _fngetdrive (fname);
  6812. if (drive == 0)
  6813.   drive = _getdrive ();
  6814. ■endsamplecode
  6815.  
  6816.  
  6817. ■function _fnisabs() _fnisrel()
  6818. ■compat emx
  6819. ■headers
  6820. #include <stdlib.h>
  6821. ■endheaders
  6822.  
  6823. ■param NAME
  6824. ■prototype
  6825. int _fnisabs (const char *NAME);
  6826. int _fnisrel (const char *NAME);
  6827. ■endprototype
  6828.  
  6829.     _fnisabs() returns a non-zero value if the string pointed to by
  6830.     NAME is an absolute file name.  Otherwise, it returns 0.  Absolute
  6831.     file names start with \ or /, optionally preceded by a drive name.
  6832.     If _fnisabs() returns a non-zero value, the location of the file
  6833.     whose name is in the string pointed to by NAME does not depend on
  6834.     the current working directory (though it may depend on the current
  6835.     drive).
  6836.  
  6837.     _fnisrel() returns a non-zero value if the string pointed to by
  6838.     NAME is a relative file name.  Otherwise is returns 0.  Relative
  6839.     file names do not start with \ or / or a drive name.  If
  6840.     _fnisrel() returns a non-zero value, you can prepend a directory
  6841.     to the string pointed to by NAME.
  6842.  
  6843.     Note that both _fnisabs() and _fnisrel() return 0 for path names
  6844.     which start with a drive name not followed by \ or /.
  6845.  
  6846. ■example
  6847. name                  │ _fnisabs (name) │ _fnisrel (name)
  6848. ──────────────────────┼─────────────────┼────────────────
  6849. "\\"                  │ non-zero        │ zero
  6850. "/etc/passwd"         │ non-zero        │ zero
  6851. "c:\\foo\\bar"        │ non-zero        │ zero
  6852. "c:/"                 │ non-zero        │ zero
  6853. "foo"                 │ zero            │ non-zero
  6854. "foo/bar"             │ zero            │ non-zero
  6855. "c:foo"               │ zero            │ zero
  6856. "d:"                  │ zero            │ zero
  6857. ""                    │ zero            │ zero
  6858. ■endexample
  6859.  
  6860. ■returnvalue
  6861.  
  6862.     _fnisabs() returns a non-zero value if the string pointed to by
  6863.     NAME is an absolute file name.  Otherwise, _fnisabs() returns 0.
  6864.  
  6865.     _fnisrel() returns a non-zero value if the string pointed to by
  6866.     NAME is a relative file name.  Otherwise _fnisrel() returns 0.
  6867.  
  6868. ■seealso _abspath() _fngetdrive()
  6869.  
  6870.  
  6871. ■function _fnlwr() _fnlwr2() _rfnlwr() _sfnlwr()
  6872. ■compat emx
  6873. ■headers
  6874. #include <stdlib.h>
  6875. ■endheaders
  6876.  
  6877. ■param NAME BASE
  6878. ■prototype
  6879. void _fnlwr (char *NAME);
  6880. void _fnlwr2 (char *NAME, const char *BASE);
  6881. void _rfnlwr (void);
  6882. void _sfnlwr (const char *NAME);
  6883. ■endprototype
  6884.  
  6885.     _fnlwr() converts the file name pointed to by NAME to lower case
  6886.     unless the file system is case preserving.  Accented characters
  6887.     etc. are converted as well, DBCS characters are not changed.  If
  6888.     the file name does not contain a drive letter, it is assumed to
  6889.     refer to the drive set by _sfnlwr().  To save time, _fnlwr()
  6890.     caches information about file systems.  If the file system of a
  6891.     drive changes or if the current drive changes, you should call
  6892.     _rfnlwr() to reset the cache.  _sfnlwr() takes the drive name from
  6893.     the string pointed to by NAME for future _fnlwr() calls.  If
  6894.     _sfnlwr() hasn't been called since the last call to _rfnlwr() or
  6895.     if the file name does not contain a drive letter, _fnlwr() uses
  6896.     the current drive.
  6897.  
  6898.     _fnlwr2() is a variant of _fnlwr() which should be used when
  6899.     converting only a suffix of a path name to lower case.  NAME
  6900.     points to the suffix, BASE points to the beginning of the path
  6901.     name.  The string pointed to by BASE is used for getting the drive
  6902.     letter.
  6903.  
  6904. ■hints
  6905.  
  6906.     _fnlwr2() should be used instead of _sfnlwr() and _fnlwr()
  6907.     whenever possible.
  6908.  
  6909. ■seealso _filesys() _nls_init() _nls_strlwr()
  6910.  
  6911.  
  6912. ■function fnmatch()
  6913. ■compat POSIX.2
  6914. ■headers
  6915. #include <fnmatch.h>
  6916. ■endheaders
  6917.  
  6918. ■param PATTERN NAME FLAGS
  6919. ■prototype
  6920. int fnmatch (const char *PATTERN, const char *NAME, int FLAGS);
  6921. ■endprototype
  6922.  
  6923.     The fnmatch() function checks the string pointed to by NAME to see
  6924.     if it matches the file name pattern pointed to by the PATTERN
  6925.     argument.  The interpretation of the strings pointed to by PATTERN
  6926.     and NAME are is modified by FLAGS, which is the bitwise OR of zero
  6927.     or more of the following flags:
  6928.  
  6929. ■description
  6930. ■item FNM_NOESCAPE
  6931.  
  6932.     If FNM_NOESCAPE is ■em{not} set, a backslash character (`■tt{\}')
  6933.     in the string pointed to by PATTERN followed by any other character
  6934.     matches that second character in the string pointed to by NAME.
  6935.     In particular, `■tt{\\}' matches a backslash in the string pointed
  6936.     to by NAME.
  6937.  
  6938.     If FNM_NOESCAPE is set, a backslash character in the string
  6939.     pointed to by PATTERN is treated as an ordinary character.
  6940.  
  6941. ■item FNM_PATHNAME
  6942.  
  6943.     If FNM_PATHNAME is set, a slash character (`■tt{/}') in the string
  6944.     pointed to by NAME must be explicitely matched by a slash in the
  6945.     string pointed to by PATTERN; it is not matched by `■tt{?}',
  6946.     `■tt{*}', or `■tt{[]}' in the string pointed to by PATTERN.
  6947.  
  6948.     If FNM_PATHNAME is not set, a slash character in the string
  6949.     pointed to by NAME is treated as an ordinary character.
  6950.  
  6951.     If _FNM_OS2 or _FNM_DOS is set, the backslash character is treated
  6952.     like a slash, with repect to FNM_PATHNAME.
  6953.  
  6954. ■item FNM_PERIOD
  6955.  
  6956.     If FNM_PERIOD is set, then a `leading' period character (`■tt{.}')
  6957.     in the string pointed to by NAME matches a period (but not
  6958.     `■tt{?}', `■tt{*}', and `■tt{[]}') in the string pointed to by
  6959.     PATTERN.  The meaning of `leading' depends on FNM_PATHNAME: If
  6960.     FNM_PATHNAME is set, a period is `leading' if it is the first
  6961.     character in the string pointed to by NAME or if it immediately
  6962.     follows a slash.  If FNM_PATHNAME is not set, a period is
  6963.     `leading' if it is the first character of the string pointed to by
  6964.     NAME.
  6965.  
  6966.     If FNM_PERIOD is not set, a period in the string pointed to by
  6967.     NAME is treated as an ordinary character.
  6968.  
  6969. ■item _FNM_IGNORECASE
  6970.  
  6971.     If _FNM_IGNORECASE is set, letter case is ignored, that is, lower
  6972.     case letters match the corresponding upper case letters.  If
  6973.     _FNM_IGNORECASE is not set, lower case letters and upper case
  6974.     letters are distinct.
  6975.  
  6976.     _FNM_IGNORECASE is an emx extension.
  6977.  
  6978. ■item _FNM_PATHPREFIX
  6979.  
  6980.     If _FNM_PATHPREFIX is set, the string pointed to by PATTERN may match
  6981.     a complete path prefix of the string pointed to by NAME, that is,
  6982.     the string pointed to by NAME can have additional path components
  6983.     at the end.
  6984.  
  6985.     _FNM_PATHPREFIX is an emx extension.
  6986.  
  6987. ■item _FNM_POSIX
  6988.  
  6989.     If _FNM_POSIX is set, or none of _FNM_OS2 and _FNM_DOS are set,
  6990.     fnmatch() has POSIX.2 semantics.
  6991.  
  6992.     _FNM_POSIX is an emx extension.
  6993.  
  6994. ■item _FNM_OS2
  6995.  
  6996.     If _FNM_OS2 is set, fnmatch() has OS/2 semantics: Path components
  6997.     in the string pointed to by NAME have an implicit period at the
  6998.     end if they don't contain a period.  A period at the end of a
  6999.     component in the string pointed to by PATTERN may match zero
  7000.     characters at the end of a component of the string pointed to by
  7001.     NAME.  `■tt{?}' may match zero characters at the end of a
  7002.     component of the string pointed to by NAME or before a period.
  7003.     ■tt{"/*/"} does not match UNC names.  `■tt{[}' in the string
  7004.     pointed to by PATTERN is treated as an ordinary character.  `■tt{\}'
  7005.     is a path separator.  _FNM_NOESCAPE implied.
  7006.  
  7007.     _FNM_OS2 is an emx extension.  At most one of _FNM_POSIX,
  7008.     _FNM_OS2, and _FNM_DOS can be set.
  7009.  
  7010. ■item _FNM_DOS
  7011.  
  7012.     If _FNM_OS2 is set, fnmatch() has DOS semantics: Path components
  7013.     in the string pointed to by NAME have an implicit period at the
  7014.     end if they don't contain a period.  A period at the end of a
  7015.     component in the string pointed to by PATTERN may match zero
  7016.     characters at the end of a component of the string pointed to by
  7017.     NAME.  `■tt{?}' may match zero characters at the end of a
  7018.     component of the string pointed to by NAME or before a period.
  7019.     `■tt{*}' does not match a period.  ■tt{"/*/"} does not match UNC
  7020.     names.  `■tt{[}' in the string pointed to by PATTERN is treated as an
  7021.     ordinary character.  `■tt{\}' is a path separator.  _FNM_NOESCAPE
  7022.     is implied.
  7023.  
  7024.     _FNM_DOS is an emx extension.  At most one of _FNM_POSIX,
  7025.     _FNM_OS2, and _FNM_DOS can be set.
  7026.  
  7027. ■enddescription
  7028.  
  7029.     The characters `■tt{?}', `■tt{*}', and `■tt{[]}' are interpreted
  7030.     as wildcard characters in the pattern.  `■tt{?}' matches one
  7031.     character, `■tt{*}' matches zero or more characters.  For
  7032.     _FNM_POSIX, `■tt{[]}' matches the set of characters listed between
  7033.     the brackets, ranges (such as `■tt{[0-9]}') are allowed.  If the
  7034.     first character after `■tt{[}' is `■tt{!}', all characters
  7035.     ■em{not} in the set match the set.  DBCS characters are not
  7036.     allowed in sets.
  7037.  
  7038. ■returnvalue
  7039.  
  7040.     fnmatch() returns 0 if the string pointed to by NAME matches the
  7041.     string pointed to by PATTERN.  fnmatch() returns FNM_NOMATCH if the
  7042.     string pointed to by NAME does not match the string pointed to by
  7043.     PATTERN.  fnmatch() returns another non-zero value on error.
  7044.  
  7045. ■implementation
  7046.  
  7047.     If the first character after `■tt{[}' is `■tt{^}', all characters
  7048.     ■em{not} in the set match the set.
  7049.  
  7050. ■bugs
  7051.  
  7052.     Ranges in `■tt{[]}' which include letters don't work correctly if
  7053.     _FNM_IGNORECASE is set.
  7054.  
  7055. ■seealso glob() _nls_tolower()
  7056.  
  7057.  
  7058. ■function _fnslashify()
  7059. ■compat emx
  7060. ■headers
  7061. #include <stdlib.h>
  7062. ■endheaders
  7063.  
  7064. ■param NAME
  7065. ■prototype
  7066. char *_fnslashify (char *NAME);
  7067. ■endprototype
  7068.  
  7069.     _fnslashify() replaces backslashes by slashes in the string pointed to
  7070.     by NAME.
  7071.  
  7072.     _fnslashify() properly handles DBCS characters.
  7073.  
  7074. ■returnvalue
  7075.  
  7076.    _fnslashify() returns NAME.
  7077.  
  7078. ■seealso _nls_init()
  7079.  
  7080.  
  7081. ■function fopen()
  7082. ■compat C90
  7083. ■headers
  7084. #include <stdio.h>
  7085. ■endheaders
  7086.  
  7087. ■param FNAME MODE
  7088. ■prototype
  7089. FILE *fopen (const char *FNAME, const char *MODE);
  7090. ■endprototype
  7091.  
  7092.     Open a stream.  FNAME points to a string giving the name of the
  7093.     file, MODE points to a string which specifies the file mode:
  7094.  
  7095. ■list
  7096. ■item ■tt{r}
  7097.  
  7098.     Open the file for reading.  The file must exist.
  7099.  
  7100. ■item ■tt{w}
  7101.  
  7102.     Open the file for writing.  If the file exists, it will be
  7103.     truncated to 0 bytes, destroying its contents.  If the file does
  7104.     not exist, it will be created.
  7105.  
  7106. ■item ■tt{a}
  7107.  
  7108.     Open the file for appending.  Writing will always take place at
  7109.     the end of the file.  If the file does not exist, it will be
  7110.     created.
  7111.  
  7112. ■item ■tt{r+}
  7113.  
  7114.     Open the file for both reading and writing.  The file must exist.
  7115.  
  7116. ■item ■tt{w+}
  7117.  
  7118.     Open the file for both reading and writing.  If the file exists,
  7119.     it will be truncated to 0 bytes, destroying its contents.  If the
  7120.     file does not exist, it will be created.
  7121.  
  7122. ■item ■tt{a+}
  7123.  
  7124.     Open the file for both reading and appending.  Writing will always
  7125.     take place at the end of the file.  If the file does not exist, it
  7126.     will be created.
  7127.  
  7128. ■endlist
  7129.  
  7130.     There are two additional MODE flags which can be appended to one
  7131.     of the above modes: ■tt{t} for text mode, ■tt{b} for binary mode.
  7132.     Text mode, which is the default, skips CR characters on input and
  7133.     converts newline characters to CR/LF pairs on output.  If the last
  7134.     character of a file is Ctrl-Z, it is discarded on input.  Binary
  7135.     mode disables these transformations.
  7136.  
  7137.     The file is opened in the sharing mode SH_DENYNO, see
  7138.     ■hpt{sopen()}.  If you want to use a different sharing mode, use
  7139.     ■hpt{_fsopen()}.
  7140.  
  7141. ■returnvalue
  7142.  
  7143.     fopen() returns a new stream.  On error, fopen() returns NULL.
  7144.  
  7145. ■seealso fclose() fdopen() freopen() _fsopen() sopen()
  7146.  
  7147.  
  7148. ■function fork()
  7149. ■compat POSIX.1 *
  7150. ■headers
  7151. #include <unistd.h>
  7152. ■endheaders
  7153.  
  7154. ■prototype
  7155. int fork (void);
  7156. ■endprototype
  7157.  
  7158.     Duplicate the current process.  A child process is created which is a
  7159.     copy of the calling process.  Both the parent process and the
  7160.     child process resume at the point where fork() was called.  The
  7161.     child process inherits the following attributes of the parent
  7162.     process:
  7163.  
  7164. ■itemize
  7165.  
  7166. ■item
  7167.  
  7168.     environment
  7169.  
  7170. ■item
  7171.  
  7172.     dynamically loaded DLLs created with emx 0.9c or later
  7173.  
  7174. ■item
  7175.  
  7176.     memory (data segment, heap, stack, and data segments of DLLs
  7177.     created with emx 0.9c or later)
  7178.  
  7179. ■item
  7180.  
  7181.     signal actions
  7182.  
  7183. ■item
  7184.  
  7185.     file handles
  7186.  
  7187. ■item
  7188.  
  7189.     current working directories
  7190.  
  7191. ■item
  7192.  
  7193.     umask
  7194.  
  7195. ■item
  7196.     flags set with _uflags()
  7197.  
  7198. ■item
  7199.  
  7200.     break points.  This is an OS/2 bug.  To debug a program containing
  7201.     fork(), set a breakpoint in the branch of execution that's
  7202.     executed only in the parent process
  7203.  
  7204. ■enditemize
  7205.  
  7206.     The new process differs from the parent process in the following
  7207.     ways:
  7208.  
  7209. ■itemize
  7210.  
  7211. ■item
  7212.  
  7213.     the child process has a unique process ID
  7214.  
  7215. ■item
  7216.  
  7217.     the child process has a different parent process ID (the process
  7218.     ID of the parent process)
  7219.  
  7220. ■item
  7221.  
  7222.     the child process has copies of the file descriptors of the parent
  7223.     process.  The file pointers are shared
  7224.  
  7225. ■item
  7226.  
  7227.     Terminal settings are reset in the child process (that is, the
  7228.     IDEFAULT bit is set)
  7229.  
  7230. ■item
  7231.  
  7232.     all resources allocated using OS/2 calls (except for DLLs created
  7233.     with emx 0.9c or later) are not inherited by the child process:
  7234.     semaphores, queues, threads, memory, file handles, etc■.
  7235.  
  7236. ■item
  7237.  
  7238.     the alarm clock is turned off
  7239.  
  7240. ■item
  7241.  
  7242.     the CPU time (returned by ■hpt{clock()}) is set to 0
  7243.  
  7244. ■item
  7245.  
  7246.     non-shared _rmutex semaphores
  7247.  
  7248. ■enditemize
  7249.  
  7250.     When the new process terminates, SIGCHLD is sent to the process
  7251.     which forked that process.
  7252.  
  7253. ■returnvalue
  7254.  
  7255.     On success, fork() returns the process ID of the new process to
  7256.     the calling process, 0 to the new process.  On error, fork()
  7257.     returns -1.
  7258.  
  7259. ■restrictions
  7260.  
  7261.     fork() is not implemented for DOS.  fork() works only in programs
  7262.     linked by ld.  It does not work in programs linked by LINK386.
  7263.     fork() is not available with the system call library sys.lib
  7264.     (■hpt{-Zsys}).
  7265.  
  7266.     The data segments of dynamic link libraries created with emx 0.9c
  7267.     or later are copied, therefore fork() can be used with the
  7268.     ■hpt{-Zcrtdll} option of GCC and with DLLs created with emx 0.9c
  7269.     and later.  However, data segments of DLLs not created with emx or
  7270.     created with emx 0.9b or older are not duplicated, therefore
  7271.     fork() does not work correctly when using such DLLs.
  7272.  
  7273.     fork() is very inefficient for OS/2.  To start a child process,
  7274.     use spawn*() instead of fork() and exec*().
  7275.  
  7276.     If the parent process uses the ■hpt{general terminal interface}
  7277.     for the keyboard, the child process cannot read from the keyboard
  7278.     using ■hpt{_read_kbd()}, the general terminal interface, or the
  7279.     ■tt{Kbd} OS/2 API functions.
  7280.  
  7281.     If the process has a non-contiguous heap (that is, multiple heap
  7282.     objects), fork() will fail.  Increase the initial heap size to
  7283.     work around this problem.  If any DLL used by the program shares
  7284.     the heap with the program and uses the heap in _DLL_InitTerm() by
  7285.     calling sbrk(), malloc(), etc., fork() will fail.  In both cases,
  7286.     fork() will return -1 and set errno to ENOMEM.
  7287.  
  7288. ■seealso alarm() exec*() _rmutex_create() sbrk() sigaction() signal() spawn*() _uflags() wait() waitpid()
  7289.  
  7290.  
  7291. ■function fpclassify()
  7292. ■compat C9X
  7293. ■headers
  7294. #include <math.h>
  7295. ■endheaders
  7296.  
  7297. ■param X
  7298. ■prototype
  7299. int fpclassify (float X);
  7300. int fpclassify (double X);
  7301. int fpclassify (long double X);
  7302. ■endprototype
  7303.  
  7304.     Classify X as zero (FP_ZERO), subnormal (FP_SUBNORMAL), normal
  7305.     (FP_NORMAL), infinite (FP_INFINITE), or NaN (FP_NAN).  The
  7306.     argument X must be of a floating-point type.  Classification is
  7307.     based on the type of the argument.
  7308.  
  7309. ■returnvalue
  7310.  
  7311.     fpclassify() returns the value of one of the following macros:
  7312.     FP_ZERO, FP_SUBNORMAL, FP_NORMAL, FP_INFINITE, FP_NAN.
  7313.  
  7314. ■seealso copysign() isfinite() isnan() isnormal() signbit()
  7315.  
  7316.  
  7317. ■function _fpreset()
  7318. ■compat PC
  7319. ■headers
  7320. #include <float.h>
  7321. ■endheaders
  7322.  
  7323. ■prototype
  7324. void _fpreset (void);
  7325. ■endprototype
  7326.  
  7327.     Reset the floating point coprocessor.
  7328.  
  7329. ■seealso _clear87() _control87()
  7330.  
  7331.  
  7332. ■function fprintf()
  7333. ■compat C90
  7334. ■headers
  7335. #include <stdio.h>
  7336. ■endheaders
  7337.  
  7338. ■param STREAM FORMAT
  7339. ■prototype
  7340. int fprintf (FILE *STREAM, const char *FORMAT, ...);
  7341. ■endprototype
  7342.  
  7343.     Formatted output to the stream STREAM.  See printf() for details.
  7344.  
  7345. ■returnvalue
  7346.  
  7347.     On success, fprintf() returns the number of characters written to
  7348.     STREAM.  On error, fprintf() returns EOF.
  7349.  
  7350. ■seealso fscanf() printf()
  7351.  
  7352.  
  7353. ■function fputc()
  7354. ■compat C90
  7355. ■headers
  7356. #include <stdio.h>
  7357. ■endheaders
  7358.  
  7359. ■param C STREAM
  7360. ■prototype
  7361. int fputc (int C, FILE *STREAM);
  7362. ■endprototype
  7363.  
  7364.     Write the character C (converted to an ■tt{unsigned char}) to the
  7365.     output stream STREAM and advance the file position indicator of
  7366.     the stream (if defined).  All output to streams takes place as if
  7367.     characters were written by successive calls to fputc().
  7368.  
  7369.     fputc() is a function, in contrast to putc().
  7370.  
  7371. ■returnvalue
  7372.  
  7373.     fputc() returns the character written.  On error, fputc() sets the
  7374.     error indicator of the stream and returns EOF.
  7375.  
  7376. ■seealso ferror() fprintf() fputchar() fputs() putc() putchar()
  7377.  
  7378.  
  7379. ■function fputchar()
  7380. ■compat PC
  7381. ■headers
  7382. #include <stdio.h>
  7383. ■endheaders
  7384.  
  7385. ■param C
  7386. ■prototype
  7387. int fputchar (int C);
  7388. ■endprototype
  7389.  
  7390.     ■tt{fputchar (c)} is equivalent to ■tt{fputc (c, stdout)}.
  7391.  
  7392. ■returnvalue
  7393.  
  7394.     fputchar() returns the character written.  On error, fputchar()
  7395.     sets the error indicator of stdout and returns EOF.
  7396.  
  7397. ■hints
  7398.  
  7399.     Use putchar() or ■tt{fputc (c, stdout)} instead of fputchar() as
  7400.     fputchar() is not portable.
  7401.  
  7402. ■seealso fputc() putchar()
  7403.  
  7404.  
  7405. ■function fputs()
  7406. ■compat C90
  7407. ■headers
  7408. #include <stdio.h>
  7409. ■endheaders
  7410.  
  7411. ■param STRING STREAM
  7412. ■prototype
  7413. int fputs (const char *STRING, FILE *STREAM);
  7414. ■endprototype
  7415.  
  7416.     Write the string pointed to by STRING to STREAM.  In contrast to
  7417.     puts(), a newline character is not appended automatically.
  7418.  
  7419. ■returnvalue
  7420.  
  7421.     fputs() returns a non-negative value if successful.  On error,
  7422.     fputs() returns EOF.
  7423.  
  7424. ■seealso fgets() fputc() printf() puts() setvbuf()
  7425.  
  7426.  
  7427. ■function fread()
  7428. ■compat C90
  7429. ■headers
  7430. #include <stdio.h>
  7431. ■endheaders
  7432.  
  7433. ■param BUFFER SIZE COUNT STREAM
  7434. ■prototype
  7435. size_t fread (void *BUFFER, size_t SIZE, size_t COUNT, FILE *STREAM);
  7436. ■endprototype
  7437.  
  7438.     Read up to COUNT elements whose size is SIZE from STREAM to the
  7439.     array pointed to by BUFFER.  The file pointer is incremented by
  7440.     the number of bytes read.  If STREAM has been opened in text mode,
  7441.     CR/LF pairs are translated to newline characters and a Ctrl-Z
  7442.     character is discarded if it is the last character of the file.
  7443.     If fread() fails, the position of the file pointer will be
  7444.     undefined.
  7445.  
  7446. ■returnvalue
  7447.  
  7448.     fread() returns the number of elements successfully read, which
  7449.     may be less than COUNT if an error occurs or if the end of the
  7450.     file is reached.  Use ferror() and feof() to distinguish between
  7451.     these two conditions.
  7452.  
  7453.     Text mode translation does not affect the return value -- SIZE and
  7454.     COUNT are applied after translation.
  7455.  
  7456. ■seealso fgetc() fgets() _fsetmode() fwrite()
  7457.  
  7458.  
  7459. ■function free()
  7460. ■compat C90
  7461. ■headers
  7462. #include <stdlib.h>
  7463. ■endheaders
  7464.  
  7465. ■param MEM
  7466. ■prototype
  7467. void free (void *MEM);
  7468. ■endprototype
  7469.  
  7470.     Deallocate the block of memory pointed to by MEM.  MEM must point
  7471.     to a block which is still in use (that is, has not been freed) and
  7472.     must have been returned by calloc(), malloc(), realloc(),
  7473.     _tcalloc(), _tmalloc(), _trealloc(), _ucalloc(), _umalloc(),
  7474.     _utcalloc(), or _utmalloc().  Do not use the memory pointed to by
  7475.     MEM after calling free().  If MEM is NULL, free() does nothing.
  7476.  
  7477. ■seealso calloc() _heapmin() malloc() realloc() _tfree() _umalloc()
  7478.  
  7479.  
  7480. ■function freopen()
  7481. ■compat C90
  7482. ■headers
  7483. #include <stdio.h>
  7484. ■endheaders
  7485.  
  7486. ■param FNAME MODE STREAM
  7487. ■prototype
  7488. FILE *freopen (const char *FNAME, const char *MODE, FILE *STREAM);
  7489. ■endprototype
  7490.  
  7491.     Open the file whose name is in the string pointed to by FNAME in
  7492.     the mode given by the string pointed to by MODE (see
  7493.     ■hpt{fopen()}) and associate STREAM with that file.  If STREAM is
  7494.     associated with a file when freopen() is called, freopen() will
  7495.     close the file, ignoring any errors, before opening the file whose
  7496.     name is in the string pointed to by FNAME.
  7497.  
  7498. ■returnvalue
  7499.  
  7500.     If successful, freopen() returns STREAM.  On error, freopen()
  7501.     returns NULL.
  7502.  
  7503. ■hints
  7504.  
  7505.     The major application of freopen() is to redirect stdin, stdout,
  7506.     or stderr.
  7507.  
  7508. ■seealso _fassign() fclose() fopen() stderr
  7509.  
  7510.  
  7511. ■function frexp() frexpl()
  7512. ■compat C90 C9X
  7513. ■headers
  7514. #include <math.h>
  7515. ■endheaders
  7516.  
  7517. ■param X EXP_PTR
  7518. ■prototype
  7519. double frexp (double X, int *EXP_PTR);
  7520. long double frexpl (long double X, int *EXP_PTR);
  7521. ■endprototype
  7522.  
  7523.     Extract mantissa and exponent of X.  The mantissa is returned, the
  7524.     exponent, an integer, is stored to *EXP_PTR.  The following holds
  7525.     for the mantissa m: 0.5 <= |m| < 1.0.  If X is zero, both the
  7526.     mantissa and the exponent are 0.
  7527.  
  7528.     frexpl() uses the ■tt{long double} format.
  7529.  
  7530. ■returnvalue
  7531.  
  7532.     frexp() returns the mantissa of X.
  7533.  
  7534. ■seealso ldexp() log()
  7535.  
  7536.  
  7537. ■function fscanf()
  7538. ■compat C90
  7539. ■headers
  7540. #include <stdio.h>
  7541. ■endheaders
  7542.  
  7543. ■param STREAM FORMAT
  7544. ■prototype
  7545. int fscanf (FILE *STREAM, const char *FORMAT, ...);
  7546. ■endprototype
  7547.  
  7548.     The stream STREAM is read and input is parsed according to the
  7549.     format string FORMAT.  For each field in the string pointed to by
  7550.     FORMAT there must be a pointer to the location receiving the
  7551.     value.  The pointers are passed after the FORMAT argument.
  7552.  
  7553. ■returnvalue
  7554.  
  7555.     If successful, fscanf() returns the number of fields converted.
  7556.     On error, fscanf() returns EOF.
  7557.  
  7558. ■seealso fprintf() scanf()
  7559.  
  7560.  
  7561. ■function fseek()
  7562. ■compat C90
  7563. ■headers
  7564. #include <stdio.h>
  7565. ■endheaders
  7566.  
  7567. ■param STREAM OFFSET ORIGIN
  7568. ■prototype
  7569. int fseek (FILE *STREAM, long OFFSET, int ORIGIN);
  7570. ■endprototype
  7571.  
  7572.     fseek() moves the file pointer of STREAM.  The new position OFFSET
  7573.     is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative
  7574.     to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is
  7575.     relative to the current position, if ORIGIN is SEEK_END, OFFSET is
  7576.     relative to the end of the file.  The file pointer cannot be moved
  7577.     before the beginning of the file.
  7578.  
  7579.     For text-mode streams, OFFSET must be either zero (with ORIGIN
  7580.     equal to SEEK_SET, SEEK_CUR, or SEEK_END) or a value returned by a
  7581.     call to ftell() on the same stream (with ORIGIN equal to
  7582.     SEEK_SET).
  7583.  
  7584.     If successful, fseek() resets the end-of-file indicator of the
  7585.     stream and undoes ungetc().  If STREAM is open for reading and
  7586.     writing (update), the next operation after fseek() can be either
  7587.     input or output.
  7588.  
  7589. ■returnvalue
  7590. ■description
  7591. ■item 0
  7592.     success
  7593. ■item non-0
  7594.     error
  7595. ■enddescription
  7596.  
  7597. ■implementation
  7598.  
  7599.     For binary-mode streams, the file position can be set beyond end
  7600.     of file; the data between end of file and the new position is
  7601.     undefined.
  7602.  
  7603.     For text-mode streams ending with a Ctrl-Z, SEEK_END is not
  7604.     allowed.
  7605.  
  7606. ■restrictions
  7607.  
  7608.     fseek() does not work for text-mode streams unless either CR/LF
  7609.     pairs or LF only is used for all lines of the file.  If there are
  7610.     lines terminated with CR/LF and lines terminated with LF, fseek()
  7611.     does not work correctly.
  7612.  
  7613. ■seealso chsize() fgetpos() fsetpos() ftell() lseek() rewind()
  7614.  
  7615.  
  7616. ■function _fseek_hdr()
  7617. ■compat emx
  7618. ■headers
  7619. #include <stdio.h>
  7620. ■endheaders
  7621.  
  7622. ■param STREAM
  7623. ■prototype
  7624. int _fseek_hdr (FILE *STREAM);
  7625. ■endprototype
  7626.  
  7627.     Move the file pointer of STREAM to the a.out header of an
  7628.     executable file (a.out or bound .exe).  _fseek_hdr() assumes that
  7629.     the file pointer points to the beginning of the header (ie, the
  7630.     beginning of the file).  If no header is found, the file pointer
  7631.     will be repositioned to the original position.
  7632.  
  7633. ■returnvalue
  7634. ■description
  7635. ■item 0
  7636.     success
  7637. ■item -1
  7638.     error (errno is set)
  7639. ■enddescription
  7640.  
  7641. ■seealso _seek_hdr()
  7642.  
  7643.  
  7644. ■function _fsetmode()
  7645. ■compat emx
  7646. ■headers
  7647. #include <stdio.h>
  7648. ■endheaders
  7649.  
  7650. ■param STREAM MODE
  7651. ■prototype
  7652. int _fsetmode (FILE *STREAM, const char *MODE);
  7653. ■endprototype
  7654.  
  7655.     Change the text/binary mode of a stream.  MODE must point either
  7656.     to ■tt{"b"} or to ■tt{"t"}.  _fsetmode() is usually used to switch
  7657.     stdin or stdout to binary mode.
  7658.  
  7659. ■returnvalue
  7660. ■description
  7661. ■item 0
  7662.     success
  7663. ■item -1
  7664.     error
  7665. ■enddescription
  7666.  
  7667. ■restrictions
  7668.  
  7669.     Do not call _fsetmode() on a stream with non-empty buffer.  If
  7670.     there is data in the buffer (either data to be read or data to be
  7671.     written), call fflush() before _fsetmode().  Otherwise, future
  7672.     behavior of the stream will be undefined.
  7673.  
  7674. ■seealso fopen()
  7675.  
  7676.  
  7677. ■function fsetpos()
  7678. ■compat C90
  7679. ■headers
  7680. #include <stdio.h>
  7681. ■endheaders
  7682.  
  7683. ■param STREAM POS
  7684. ■prototype
  7685. int fsetpos (FILE *STREAM, const fpos_t *POS);
  7686. ■endprototype
  7687.  
  7688.     Restore the position of the file pointer of the file STREAM to the
  7689.     position saved by fgetpos() in the variable pointed to by POS.
  7690.  
  7691. ■returnvalue
  7692. ■description
  7693. ■item 0
  7694.     success
  7695. ■item non-0
  7696.     error
  7697. ■enddescription
  7698.  
  7699. ■restrictions
  7700.  
  7701.     fsetpos() does not work for text-mode streams unless either CR/LF
  7702.     pairs or LF only is used for all lines of the file.  If there are
  7703.     lines terminated with CR/LF and lines terminated with LF,
  7704.     fsetpos() does not work correctly.
  7705.  
  7706. ■seealso fgetpos() fseek()
  7707.  
  7708.  
  7709. ■function _fsopen()
  7710. ■compat PC
  7711. ■headers
  7712. #include <stdio.h>
  7713. #include <share.h>
  7714. ■endheaders
  7715.  
  7716. ■param FNAME MODE SHFLAG
  7717. ■prototype
  7718. FILE *_fsopen (const char *FNAME, const char *MODE, int SHFLAG);
  7719. ■endprototype
  7720.  
  7721.     Open a stream.  FNAME points to a string giving the name of the
  7722.     file, MODE points to a string which specifies the file mode, see
  7723.     ■hpt{fopen()} for details.
  7724.  
  7725.     The sharing mode of the file is given by SHFLAG.  The following
  7726.     sharing modes are available:
  7727.  
  7728. ■description
  7729.  
  7730. ■item SH_DENYRW
  7731.  
  7732.     Deny read and write access
  7733.  
  7734. ■item SH_DENYRD
  7735.  
  7736.     Deny read access (permit write access)
  7737.  
  7738. ■item SH_DENYWR
  7739.  
  7740.     Deny write access (permit read access)
  7741.  
  7742. ■item SH_DENYNO
  7743.  
  7744.     Deny nothing (permit read and write access)
  7745.  
  7746. ■enddescription
  7747.  
  7748. ■returnvalue
  7749.  
  7750.     _fsopen() returns a new stream.  On error, _fsopen() returns NULL.
  7751.  
  7752. ■seealso fopen() sopen()
  7753.  
  7754.  
  7755. ■function fstat()
  7756. ■compat UNIX
  7757. ■headers
  7758. #include <io.h>
  7759. #include <sys/types.h>
  7760. #include <sys/stat.h>
  7761. ■endheaders
  7762.  
  7763. ■param HANDLE BUFFER
  7764. ■prototype
  7765. int fstat (int HANDLE, struct stat *BUFFER);
  7766. ■endprototype
  7767.  
  7768.     Retrieve information about the open file HANDLE.  fstat() will put
  7769.     the data into the structure pointed to by BUFFER.
  7770.  
  7771.     See ■hpt{stat()} for a description of ■tt{struct stat}.
  7772.  
  7773. ■returnvalue
  7774. ■description
  7775. ■item 0
  7776.     success
  7777. ■item -1
  7778.     error (errno is set)
  7779. ■enddescription
  7780.  
  7781. ■restrictions
  7782.  
  7783.     st_dev and st_rdev are set to zero.  Each call to fstat() returns
  7784.     a different value for st_ino.
  7785.  
  7786. ■seealso ioctl() stat() ttyname()
  7787.  
  7788.  
  7789. ■function fsync()
  7790. ■compat BSD
  7791. ■headers
  7792. #include <io.h>
  7793. ■endheaders
  7794.  
  7795. ■param HANDLE
  7796. ■prototype
  7797. int fsync (int HANDLE);
  7798. ■endprototype
  7799.  
  7800.     Flush the buffers associated with HANDLE and update the directory.
  7801.  
  7802. ■returnvalue
  7803. ■description
  7804. ■item 0
  7805.     success
  7806. ■item -1
  7807.     error
  7808. ■enddescription
  7809.  
  7810. ■restrictions
  7811.  
  7812.     fsync() is currently not implemented for DOS: errno is set to
  7813.     ENOSYS.
  7814.  
  7815.     Due to a bug in HPFS.IFS, calling fsync() can be quite dangerous.
  7816.     If HPFS.IFS has the bug, and fsync() (i.e., DosResetBuffer) is
  7817.     called after writing to a file, and Ctrl+Alt+Del is pressed while
  7818.     the file is still open, HPFS.IFS will corrupt the allocation
  7819.     bitmap of the partition containing that file.  This may damange
  7820.     existing and future files and directories.  The bug is present in
  7821.     all HPFS.IFS versions of (at least) OS/2 2.0 through OS/2 Warp
  7822.     3.0, red box of 1994.  That HPFS.IFS bug seems to be fixed in
  7823.     FixPak XR_W005 and later.  Performing a system shutdown instead of
  7824.     pressing Ctrl+Alt+Del causes the same problem if the process that
  7825.     wrote to the file and called fsync() or DosResetBuffer cannot be
  7826.     killed.  As you cannot assume that the user of your application
  7827.     has a working HPFS.IFS, better don't call fsync() and
  7828.     DosResetBuffer.
  7829.  
  7830.  
  7831. ■function ftell()
  7832. ■compat C90
  7833. ■headers
  7834. #include <stdio.h>
  7835. ■endheaders
  7836.  
  7837. ■param STREAM
  7838. ■prototype
  7839. long ftell (FILE *STREAM);
  7840. ■endprototype
  7841.  
  7842.     ftell() retrieves the current position of the file pointer of
  7843.     STREAM.  
  7844.  
  7845. ■returnvalue
  7846.  
  7847.     ftell() returns the current position of the file pointer of
  7848.     STREAM, in characters.  On error, ftell() returns -1.
  7849.  
  7850. ■restrictions
  7851.  
  7852.     ftell() does not work for text-mode streams unless either CR/LF
  7853.     pairs or LF only is used for all lines of the file.  If there are
  7854.     lines terminated with CR/LF and lines terminated with LF,
  7855.     ftell() does not work correctly.
  7856.  
  7857. ■seealso fgetpos() fseek()
  7858.  
  7859.  
  7860. ■function ftime()
  7861. ■compat SysV
  7862. ■headers
  7863. #include <sys/timeb.h>
  7864. ■endheaders
  7865.  
  7866. ■param PTR
  7867. ■prototype
  7868. void ftime (struct timeb *PTR);
  7869. ■endprototype
  7870.  
  7871.     Get the current time and store it to the structure pointed to by PTR.
  7872.     That structure has the following fields:
  7873.  
  7874. ■list
  7875.  
  7876. ■item dstflag
  7877.  
  7878.     Non-zero if daylight saving time is active for the local timezone.
  7879.  
  7880. ■item millitm
  7881.  
  7882.     Milliseconds of current time.
  7883.  
  7884. ■item ■tt{time}
  7885.  
  7886.     Current time in seconds since 00:00:00 1-Jan-1970 Coordinated
  7887.     Universal Time (UTC, GMT).
  7888.  
  7889. ■item ■tt{timezone}
  7890.  
  7891.     Difference between UTC and local time in minutes.  Positive values
  7892.     are to the west of the Prime Meridian.
  7893.  
  7894. ■endlist
  7895.  
  7896.     See ■hpt{tzset()} for a description of the TZ environment
  7897.     variable.
  7898.  
  7899. ■seealso gettimeofday() settimeofday() time() tzset()
  7900.  
  7901.  
  7902. ■function ftruncate()
  7903. ■compat BSD
  7904. ■headers
  7905. #include <io.h>
  7906. ■endheaders
  7907.  
  7908. ■param HANDLE LENGTH
  7909. ■prototype
  7910. int ftruncate (int HANDLE, long LENGTH);
  7911. ■endprototype
  7912.  
  7913.     Truncate the file associated with HANDLE to at most LENGTH bytes.
  7914.     The position of the file pointer is undefined after calling this
  7915.     function.  If LENGTH is greater than the current length of the
  7916.     file, the length is not changed.  HANDLE must be open for writing.
  7917.  
  7918. ■returnvalue
  7919. ■description
  7920. ■item 0
  7921.     success
  7922. ■item -1
  7923.     error
  7924. ■enddescription
  7925.  
  7926. ■seealso chsize() truncate()
  7927.  
  7928.  
  7929. ■function ftw()
  7930. ■compat UNIX
  7931. ■headers
  7932. #include <sys/types.h>
  7933. #include <sys/stat.h>
  7934. #include <ftw.h>
  7935. ■endheaders
  7936.  
  7937. ■param PATH FN NAME STAT_PTR FLAG DEPTH
  7938. ■prototype
  7939. int ftw (const char *PATH,
  7940.          int (*FN)(const char *NAME, const struct stat *STAT_PTR, int FLAG),
  7941.          int DEPTH);
  7942. ■endprototype
  7943.  
  7944.     Call FN for all entries of the directory tree whose root directory
  7945.     is in the string pointed to by PATH.  Directories are visited
  7946.     before the entries they contain.  FN is not called for the
  7947.     directories `.' and `..'.  A pointer to a string holding the name
  7948.     of the entry is passed in NAME.  Forward slashes are used to
  7949.     separate directories (backslashes in PATH are not converted to
  7950.     forward slashes).  _fnlwr() is called to convert the file names to
  7951.     lower case on upper-case-only file systems.  A structure filled in
  7952.     by stat() is pointed to by STAT_PTR.  FLAG is one of the
  7953.     following:
  7954.  
  7955. ■description
  7956.  
  7957. ■item FTW_D
  7958.  
  7959.     NAME is a directory
  7960.  
  7961. ■item FTW_F
  7962.  
  7963.     NAME is a file
  7964.  
  7965. ■item FTW_NS
  7966.  
  7967.     stat() failed, the contents of structure pointed to by STAT_PTR
  7968.     are undefined
  7969.  
  7970. ■item FTW_DNR
  7971.  
  7972.     the directory whose name is in the string pointed to by NAME is
  7973.     unreadable (does not happen under DOS and OS/2)
  7974.  
  7975. ■enddescription
  7976.  
  7977.     If FN returns 0, ftw() continues.  Otherwise, ftw() terminates and
  7978.     returns the value returned by FN.
  7979.  
  7980.     The DEPTH argument is ignored by this implementation of ftw().  In
  7981.     other implementations, DEPTH is used to restrict the number of
  7982.     file handles used by ftw(): one file handle is required for each
  7983.     level.  If DEPTH is less than the number of levels, ftw() will be
  7984.     slow.
  7985.  
  7986.     ftw() properly handles DBCS characters.
  7987.  
  7988. ■returnvalue
  7989.  
  7990.     If FN returns a non-zero value, ftw() returns that value.
  7991.     Otherwise, ftw() returns 0.  On error, ftw() returns -1.
  7992.  
  7993.  
  7994. ■seealso _fnlwr() _nls_init() opendir()
  7995.  
  7996. ■samplefile /emx/test/ftwtest.c
  7997.  
  7998.  
  7999. ■function _fullpath()
  8000. ■compat PC
  8001. ■headers
  8002. #include <stdlib.h>
  8003. ■endheaders
  8004.  
  8005. ■param DST SRC SIZE
  8006. ■prototype
  8007. int _fullpath (char *DST, const char *SRC, int SIZE);
  8008. ■endprototype
  8009.  
  8010.     Construct an absolute path name for the file name or directory
  8011.     name pointed to by SRC.  The absolute path name is written to the
  8012.     array pointed to by DST.  It is assumed that there are SIZE bytes
  8013.     available at DST, this includes the terminating null character.
  8014.     DST can be identical to SRC.  Backslashes are translated into
  8015.     forward slashes.  The absolute path name is not translated to
  8016.     lower case.
  8017.  
  8018.     _fullpath() accesses the appropriate drive.  It fails if a
  8019.     directory does not exist unless the non-existing directory is the
  8020.     last member of the resulting path name.
  8021.  
  8022.     _fullpath() properly handles DBCS characters.
  8023.  
  8024. ■returnvalue
  8025.  
  8026.   If successful, _fullpath() returns 0.  If there is an error,
  8027.   _fullpath() returns -1.  If SIZE is too small, _fullpath() sets
  8028.   errno to ERANGE and returns -1.
  8029.  
  8030. ■seealso _abspath() _nls_init()
  8031.  
  8032.  
  8033. ■function fwrite()
  8034. ■compat C90
  8035. ■headers
  8036. #include <stdio.h>
  8037. ■endheaders
  8038.  
  8039. ■param BUFFER SIZE COUNT STREAM
  8040. ■prototype
  8041. size_t fwrite (const void *BUFFER, size_t SIZE, size_t COUNT, FILE *STREAM);
  8042. ■endprototype
  8043.  
  8044.     Write COUNT elements whose size is SIZE from the array pointed to
  8045.     by BUFFER to STREAM.  The file pointer is incremented by the
  8046.     number of bytes written.  If fwrite() fails, the value of the file
  8047.     pointer is undefined.  If STREAM has been opened in text mode,
  8048.     newline characters are translated to CR/LF pairs.
  8049.  
  8050. ■returnvalue
  8051.  
  8052.     fwrite() returns the number of elements successfully written,
  8053.     which will be less than COUNT if an error occurs.  Text mode
  8054.     translation does not affect the return value -- SIZE and COUNT are
  8055.     applied before the translation.
  8056.  
  8057. ■seealso fputc() fputs() fread() _fsetmode() printf() setvbuf()
  8058.  
  8059.  
  8060. ■function g_box()
  8061. ■compat emx
  8062. ■headers
  8063. #include <graph.h>
  8064. ■endheaders
  8065.  
  8066. ■param X0 Y0 X1 Y1 COLOR FILL_FLAG
  8067. ■prototype
  8068. void g_box (int X0, int Y0, int X1, int Y1, int COLOR, int FILL_FLAG);
  8069. ■endprototype
  8070.  
  8071.     Draw a box which has the four vertices (X0,Y0), (X0,Y1), (X1, Y0)
  8072.     and (X1, Y1).  If FILL_FLAG is G_OUTLINE, the outline is drawn,
  8073.     that is, four lines between the vertices.  If FILL_FLAG is G_FILL,
  8074.     the interior of the box is filled.  The color COLOR is used for
  8075.     drawing.
  8076.  
  8077. ■seealso g_clip()
  8078.  
  8079.  
  8080. ■function g_clear()
  8081. ■compat emx
  8082. ■headers
  8083. #include <graph.h>
  8084. ■endheaders
  8085.  
  8086. ■param COLOR
  8087. ■prototype
  8088. void g_clear (int COLOR);
  8089. ■endprototype
  8090.  
  8091.     Clear the screen (graphics mode, only).  All pixels are set to the
  8092.     color COLOR.  The clipping rectangle is ignored.
  8093.  
  8094.  
  8095. ■function g_clip()
  8096. ■compat emx
  8097. ■headers
  8098. #include <graph.h>
  8099. ■endheaders
  8100.  
  8101. ■param X0 Y0 X1 Y1
  8102. ■prototype
  8103. void g_clip (int X0, int Y0, int X1, int Y1);
  8104. ■endprototype
  8105.  
  8106.     Define the clipping rectangle.  Only pixels with X coordinate
  8107.     between X0 and X1 (inclusive) and with Y coordinate between Y0 and
  8108.     Y1 (inclusive) are drawn.  No drawing is performed outside that
  8109.     clipping rectangle.  After switching to graphics mode with
  8110.     g_mode(), the clipping rectangle is set to the entire screen.
  8111.     This is equivalent to calling
  8112.  
  8113. ■example
  8114. g_clip (0, 0, g_xsize-1, g_ysize-1);
  8115. ■endexample
  8116.  
  8117. ■seealso g_mode() g_xsize g_ysize
  8118.  
  8119.  
  8120. ■function g_ellipse()
  8121. ■compat emx
  8122. ■headers
  8123. #include <graph.h>
  8124. ■endheaders
  8125.  
  8126. ■param CX CY RX RY COLOR FILL_FLAG
  8127. ■prototype
  8128. void g_ellipse (int CX, int CY, int RX, int RY, int COLOR, int FILL_FLAG);
  8129. ■endprototype
  8130.  
  8131.     Draw an ellipse or a circle.  One axis is horizontal, the other
  8132.     one vertical.  The center of the ellipse is at (CX,CY).  The
  8133.     horizontal radius is RX, the vertical radius is RY.  It's
  8134.     impossible to draw an ellipse with even length of an axis.  If
  8135.     FILL_FLAG is G_OUTLINE, the outline of the ellipse is drawn.  If
  8136.     FILL_FLAG is G_FILL, the interior of the ellipse is filled.  The
  8137.     color COLOR is used for drawing.
  8138.  
  8139. ■seealso g_clip()
  8140.  
  8141.  
  8142. ■function g_get()
  8143. ■compat emx
  8144. ■headers
  8145. #include <graph.h>
  8146. ■endheaders
  8147.  
  8148. ■param X Y
  8149. ■prototype
  8150. int g_get (int X, int Y);
  8151. ■endprototype
  8152.  
  8153.     Return the color of the pixel at (X,Y).  If (X,Y) is outside the
  8154.     clipping rectangle, -1 is returned.
  8155.  
  8156. ■seealso g_clip() g_set()
  8157.  
  8158.  
  8159. ■function g_hline()
  8160. ■compat emx
  8161. ■headers
  8162. #include <graph.h>
  8163. ■endheaders
  8164.  
  8165. ■param Y X0 X1 COLOR
  8166. ■prototype
  8167. void g_hline (int Y, int X0, int X1, int COLOR);
  8168. ■endprototype
  8169.  
  8170.     Draw a horizontal line between (X0,Y) and (X1,Y).  The color COLOR
  8171.     is used for drawing.
  8172.  
  8173. ■seealso g_box() g_clip() g_line() g_vline()
  8174.  
  8175.  
  8176. ■function g_line()
  8177. ■compat emx
  8178. ■headers
  8179. #include <graph.h>
  8180. ■endheaders
  8181.  
  8182. ■param X0 Y0 X1 Y1 COLOR
  8183. ■prototype
  8184. void g_line (int X0, int Y0, int X1, int Y1, int COLOR);
  8185. ■endprototype
  8186.  
  8187.     Draw a line of arbitrary slope between (X0,Y0) and (X1,Y1).  The
  8188.     color COLOR is used for drawing.  To draw horizontal or vertical
  8189.     lines, you should use g_hline() and g_vline(), respectively, which
  8190.     are specialized functions optimized for speed.
  8191.  
  8192. ■seealso g_clip() g_hline() g_polygon() g_triangle() g_vline()
  8193.  
  8194.  
  8195. ■function g_lock()
  8196. ■compat emx
  8197. ■headers
  8198. #include <graph.h>
  8199. ■endheaders
  8200.  
  8201. ■prototype
  8202. void g_lock (void);
  8203. ■endprototype
  8204.  
  8205.     Lock the screen.  Under OS/2, the screen must be locked while
  8206.     access graphics memory.  All the graphics drawing functions lock
  8207.     the screen, draw, and unlock the screen unless it's already
  8208.     locked.  To avoid the overhead of locking and unlocking for each
  8209.     function call, you can lock and unlock the screen yourself when
  8210.     performing many successive drawing operations.  Note that you
  8211.     should not lock the screen for more than a few seconds.  g_lock()
  8212.     increments a counter, which is initialized to zero by g_mode().
  8213.     The screen is locked while the counter is non-zero.  g_unlock()
  8214.     decrements the counter and unlocks the screen if the counter
  8215.     reaches zero.
  8216.  
  8217. ■seealso g_unlock()
  8218.  
  8219.  
  8220. ■function g_mode()
  8221. ■compat emx
  8222. ■headers
  8223. #include <graph.h>
  8224. ■endheaders
  8225.  
  8226. ■param MODE
  8227. ■prototype
  8228. int g_mode (int MODE);
  8229. ■endprototype
  8230.  
  8231.     Select graphics mode.  If MODE is G_MODE_OFF, graphics mode is
  8232.     turned off and 0 is returned.  Other values of MODE select the
  8233.     following graphics modes:
  8234.  
  8235. ■description
  8236. ■item G_MODE_EGA_C
  8237.     640x200 EGA mode with 16 colors
  8238. ■item G_MODE_EGA_E
  8239.     640x350 EGA mode with 16 colors
  8240. ■item G_MODE_VGA_H
  8241.     640x480 VGA mode with 16 colors
  8242. ■item G_MODE_VGA_L
  8243.     320x200 VGA mode with 256 colors
  8244. ■enddescription
  8245.  
  8246.     The global variables g_xsize, g_ysize and g_colors are set.  The
  8247.     clipping rectangle is set to the entire screen.
  8248.  
  8249.     General information about the graphics library: Programs using the
  8250.     graphics library work both under DOS and in OS/2 full-screen
  8251.     sessions.  The coordinates of the screen are (0,0) (upper left)
  8252.     through (■tt{g_xsize}-1,■tt{g_ysize}-1) (lower right).  You have
  8253.     to link with -lgraph.  Under DOS, emx option -acm is required, see
  8254.     `■hpt{Using emx options}'.
  8255.  
  8256. ■returnvalue
  8257.  
  8258.   If switching to graphics mode succeeds, gmode() returns 1.
  8259.   Otherwise, gmode() returns 0.
  8260.  
  8261. ■seealso g_clip() g_modeset() g_colors g_xsize g_ysize
  8262.  
  8263. ■samplefile /emx/samples/graph.c
  8264.  
  8265.  
  8266. ■function g_modeset()
  8267. ■compat emx
  8268. ■headers
  8269. #include <graph.h>
  8270. ■endheaders
  8271.  
  8272. ■param MODE FLAG
  8273. ■prototype
  8274. int g_modeset (int MODE, int FLAG);
  8275. ■endprototype
  8276.  
  8277.     Modify a graphics mode number.  The mode number to be modified is
  8278.     passed in MODE, the value passed in FLAG specifies how to modify
  8279.     the mode number: G_SET_KEEP causes the mode number to be not
  8280.     modified.
  8281.  
  8282.     The global variables g_xsize, g_ysize and g_colors are set.
  8283.  
  8284. ■returnvalue
  8285.  
  8286.     g_modeset() returns the new mode number.  On failure, g_modeset()
  8287.     returns G_MODE_OFF.
  8288.  
  8289. ■restrictions
  8290.  
  8291.     As only G_SET_KEEP is implemented, g_modeset() is useless.  It's
  8292.     included for compatibility with existing programs.
  8293.  
  8294. ■seealso g_mode() g_colors g_xsize g_ysize
  8295.  
  8296.  
  8297. ■function g_polygon()
  8298. ■compat emx
  8299. ■headers
  8300. #include <graph.h>
  8301. ■endheaders
  8302.  
  8303. ■param X Y N COLOR FILL_FLAG
  8304. ■prototype
  8305. void g_polygon (const int *X, const int *Y, int N, int COLOR,
  8306.                 int FILL_FLAG);
  8307. ■endprototype
  8308.  
  8309.     Draw a polygon.  The N vertices are stored in the X and Y arrays:
  8310.     (■pa{X}[i],■pa{Y}[i]) for i = 0, ..., ■pa{N}-1.  If FILL_FLAG is
  8311.     G_OUTLINE, the outline of the polygon is drawn, that is, a line
  8312.     from vertex 0 to vertex 1, from vertex 1 to vertex 2, ..., vertex
  8313.     ■pa{N}-2 to vertex ■pa{N}-1, vertex ■pa{N}-1 to vertex 0.  If
  8314.     FILL_FLAG is G_FILL, the interior of the polygon is filled.  A
  8315.     point is defined to be in the interior of the polygon, if an
  8316.     infinite line to any side of that pixel intersects the polygon an
  8317.     odd number of times.  The color COLOR is used for drawing.
  8318.  
  8319. ■seealso g_clip() g_line() g_triangle()
  8320.  
  8321.  
  8322. ■function g_set()
  8323. ■compat emx
  8324. ■headers
  8325. #include <graph.h>
  8326. ■endheaders
  8327.  
  8328. ■param X Y COLOR
  8329. ■prototype
  8330. void g_set (int X, int Y, int COLOR);
  8331. ■endprototype
  8332.  
  8333.     Set the pixel (X,Y) to the color COLOR.
  8334.  
  8335. ■seealso g_clip() g_get()
  8336.  
  8337.  
  8338. ■function g_triangle()
  8339. ■compat emx
  8340. ■headers
  8341. #include <graph.h>
  8342. ■endheaders
  8343.  
  8344. ■param X0 Y0 X1 Y1 X2 Y2 COLOR FILL_FLAG
  8345. ■prototype
  8346. void g_triangle (int X0, int Y0, int X1, int Y1, int X2, int Y2, int COLOR,
  8347.                  int FILL_FLAG);
  8348. ■endprototype
  8349.  
  8350.     Draw a triangle.  The vertices are (X0,Y0), (X1,Y1) and (X2,Y2).
  8351.     If FILL_FLAG is G_OUTLINE, the outline of the triangle is drawn,
  8352.     that is, a line from (X0,Y0) to (X1,Y1), a line from (X1,Y1) to
  8353.     (X2,Y2) and a line from (X2,Y2) to (X0,Y0).  If FILL_FLAG is
  8354.     G_FILL, the interior of the triangle is filled.  The color COLOR
  8355.     is used for drawing.
  8356.  
  8357. ■seealso g_clip() g_line() g_polygon()
  8358.  
  8359.  
  8360. ■function g_unlock() g_unlockall()
  8361. ■compat emx
  8362. ■headers
  8363. #include <graph.h>
  8364. ■endheaders
  8365.  
  8366. ■prototype
  8367. void g_unlock (void);
  8368. void g_unlockall (void);
  8369. ■endprototype
  8370.  
  8371.     Unlock the screen.  g_unlock() undoes one invocation of g_lock()
  8372.     by decrementing the counter incremented by g_lock().  If the
  8373.     counter reaches zero, the screen is unlocked.  If the counter
  8374.     already was zero, the counter is not changed.  g_unlockall()
  8375.     undoes all invocations of g_lock() by resetting the counter to
  8376.     zero and unlocking the screen if the counter was non-zero.
  8377.  
  8378. ■seealso g_lock()
  8379.  
  8380.  
  8381. ■function g_vgapal()
  8382. ■compat emx
  8383. ■headers
  8384. #include <graph.h>
  8385. ■endheaders
  8386.  
  8387. ■param PAL FIRST N WAIT_FLAG
  8388. ■prototype
  8389. void g_vgapal (const char *PAL, int FIRST, int N, int WAIT_FLAG);
  8390. ■endprototype
  8391.  
  8392.     Set the VGA palette.  This function sets N (1 through 256) DAC
  8393.     registers starting with register FIRST (0 through 255).  For each
  8394.     register, 3 bytes are taken from the array pointed to by PAL: red,
  8395.     green, blue.  Each byte should have a value between 0 and 63,
  8396.     inclusive.  If WAIT_FLAG is non-zero, g_vgapal() waits for the
  8397.     vertical retrace to avoid snow on the screen, see ■hpt{g_waitv()}.
  8398.     Under DOS, emx option -ai is required, see `■hpt{Using emx
  8399.     options}'.  Under OS/2, emxio.dll is required.
  8400.  
  8401. ■seealso g_waitv() _outps8dac()
  8402.  
  8403.  
  8404. ■function g_vline()
  8405. ■compat emx
  8406. ■headers
  8407. #include <graph.h>
  8408. ■endheaders
  8409.  
  8410. ■param X Y0 Y1 COLOR
  8411. ■prototype
  8412. void g_vline (int X, int Y0, int Y1, int COLOR);
  8413. ■endprototype
  8414.  
  8415.     Draw a vertical line between (X,Y0) and (X,Y1).  The color COLOR
  8416.     is used for drawing.
  8417.  
  8418. ■seealso g_box() g_clip() g_hline() g_line()
  8419.  
  8420.  
  8421. ■function g_waitv()
  8422. ■compat emx
  8423. ■headers
  8424. #include <graph.h>
  8425. ■endheaders
  8426.  
  8427. ■prototype
  8428. void g_waitv (void);
  8429. ■endprototype
  8430.  
  8431.     Wait for vertical retrace.  Under DOS, emx option -ai is required,
  8432.     see `■hpt{Using emx options}'.  Under OS/2, emxio.dll is required.
  8433.     Note that this function eats a lot of CPU time.
  8434.  
  8435. ■seealso g_vgapal() _wait01()
  8436.  
  8437.  
  8438. ■function g_wmode()
  8439. ■compat emx
  8440. ■headers
  8441. #include <graph.h>
  8442. ■endheaders
  8443.  
  8444. ■param WMODE
  8445. ■prototype
  8446. void g_wmode (int WMODE);
  8447. ■endprototype
  8448.  
  8449.     Select a `writing mode'.  This is not yet implemented.
  8450.  
  8451.  
  8452. ■function gcvt()
  8453. ■compat UNIX
  8454. ■headers
  8455. #include <stdlib.h>
  8456. ■endheaders
  8457.  
  8458. ■param VALUE DIGITS BUFFER
  8459. ■prototype
  8460. char *gcvt (double VALUE, int DIGITS, char *BUFFER);
  8461. ■endprototype
  8462.  
  8463.     Convert the floating point number VALUE to a null-terminated
  8464.     string of ASCII digits in the array pointed to by BUFFER, using
  8465.     exponential-decimal format or floating-decimal and return a
  8466.     pointer to BUFFER.  gcvt() produces DIGITS significant digits.
  8467.     Trailing zeros and a trailing decimal point are removed.  The
  8468.     array pointed to by BUFFER must be big enough for holding the
  8469.     string.
  8470.  
  8471.     The decimal point character of the current locale is used.
  8472.  
  8473.     Exponential format is used if the absolute value of VALUE is less
  8474.     than 0.1 or if the exponent is greater than or equal to DIGITS.
  8475.  
  8476.     The empty string is stored to the array pointed to by BUFFER if
  8477.     DIGITS is less than one.
  8478.  
  8479. ■returnvalue
  8480.  
  8481.     gcvt() returns BUFFER.
  8482.  
  8483. ■restrictions
  8484.  
  8485.     NaN and other special values are not yet handled correctly.
  8486.  
  8487. ■seealso setlocale() sprintf()
  8488.  
  8489.  
  8490. ■function getc()
  8491. ■compat C90
  8492. ■headers
  8493. #include <stdio.h>
  8494. ■endheaders
  8495.  
  8496. ■param STREAM
  8497. ■prototype
  8498. int getc (FILE *STREAM);
  8499. ■endprototype
  8500.  
  8501.     Read the next character (as ■tt{unsigned char} converted to an
  8502.     ■tt{int}) from the input stream STREAM and advance the file
  8503.     position indicator of the stream (if defined).  getc() is
  8504.     equivalent to fgetc().
  8505.  
  8506.     getc() may be implemented as macro, in contrast to fgetc().  In
  8507.     consequence, getc() may evaluate its argument more than once.
  8508.  
  8509. ■returnvalue
  8510.  
  8511.     getc() returns the next character from the stream.  If the stream
  8512.     is at end-of-file (before getc() is called), getc() sets the
  8513.     end-of-file indicator of the stream and returns EOF.  If a read
  8514.     error occurs, getc() sets the error indicator of the stream and
  8515.     returns EOF.
  8516.  
  8517. ■implementation
  8518.  
  8519.     getc() is implemented as in-line function for single-thread
  8520.     programs.
  8521.  
  8522. ■hints
  8523.  
  8524.     Use getc() instead of fgetc() if you want to read a lot of
  8525.     characters.
  8526.  
  8527.     The argument of getc() should not be an expression with side
  8528.     effects.
  8529.  
  8530. ■seealso fgetc() getchar()
  8531.  
  8532.  
  8533. ■function getchar()
  8534. ■compat C90
  8535. ■headers
  8536. #include <stdio.h>
  8537. ■endheaders
  8538.  
  8539. ■prototype
  8540. int getchar (void);
  8541. ■endprototype
  8542.  
  8543.     getchar() is equivalent to ■tt{getc (stdin)}.
  8544.  
  8545. ■returnvalue
  8546.  
  8547.     getchar() returns the next character from stdin.  If stdin is at
  8548.     end-of-file (before getchar() is called), getchar() sets the
  8549.     end-of-file indicator of stdin and returns EOF.  If a read error
  8550.     occurs, getchar() sets the error indicator of stdin and returns
  8551.     EOF.
  8552.  
  8553. ■implementation
  8554.  
  8555.     getchar() is implemented as in-line function for single-thread
  8556.     programs.
  8557.  
  8558. ■hints
  8559.  
  8560.     Use getchar() instead of ■tt{fgetc(stdin)} if you want to read a
  8561.     lot of characters.
  8562.  
  8563. ■seealso fgetc() getc()
  8564.  
  8565.  
  8566. ■function getcwd()
  8567. ■compat POSIX.1
  8568. ■headers
  8569. #include <stdlib.h>
  8570. ■endheaders
  8571.  
  8572. ■param BUFFER SIZE
  8573. ■prototype
  8574. char *getcwd (char *BUFFER, size_t SIZE);
  8575. ■endprototype
  8576.  
  8577.     getcwd() retrieves the name of the current working directory
  8578.     (excluding the drive name) and stores it to the array pointed to
  8579.     by BUFFER.  It is assumed that there are SIZE bytes available at
  8580.     BUFFER.  This includes the terminating 0.  If BUFFER is NULL, an
  8581.     array of suitable size, but at least SIZE bytes, is allocated with
  8582.     malloc().  getcwd() translates backslashes into forward slashes.
  8583.     It does not translate upper-case directory names to lower case.
  8584.  
  8585.     _getcwd() properly handles DBCS characters.
  8586.  
  8587. ■returnvalue
  8588.  
  8589.     If successful, getcwd() returns BUFFER, or a buffer allocated with
  8590.     malloc() if BUFFER is NULL.  On error, getcwd() sets errno and
  8591.     returns NULL.
  8592.  
  8593. ■errors
  8594. ■description
  8595. ■item EINVAL
  8596.   SIZE is zero
  8597. ■item ENOMEM
  8598.   BUFFER is NULL and malloc() failed
  8599. ■item ERANGE
  8600.   BUFFER is not NULL and SIZE is positive and the length of the
  8601.   pathname plus 1 is greater than SIZE
  8602. ■enddescription
  8603.  
  8604. ■seealso chdir() _getcwd1() _getcwd2() getwd() _nls_init()
  8605.  
  8606.  
  8607. ■function _getcwd1()
  8608. ■compat emx
  8609. ■headers
  8610. #include <stdlib.h>
  8611. ■endheaders
  8612.  
  8613. ■param BUFFER DRIVE
  8614. ■prototype
  8615. int _getcwd1 (char *BUFFER, char DRIVE);
  8616. ■endprototype
  8617.  
  8618.     _getcwd1() retrieves the name of the current working directory
  8619.     (starting with a slash, excluding the drive name) of drive DRIVE
  8620.     and stores it to the array pointed to by BUFFER.  If DRIVE is 0,
  8621.     the currently selected drive is used.  Otherwise, DRIVE must be in
  8622.     ■tt{'A'} through ■tt{'Z'}.  It is assumed that there are enough
  8623.     bytes available at BUFFER.  _getcwd1() translates backslashes into
  8624.     forward slashes.  It does not translate upper-case directory names
  8625.     to lower case.
  8626.  
  8627.     _getcwd1() properly handles DBCS characters.
  8628.  
  8629. ■returnvalue
  8630. ■description
  8631. ■item 0
  8632.     success
  8633. ■item -1
  8634.     error
  8635. ■enddescription
  8636.  
  8637. ■seealso chdir() getcwd() _getcwd2() _nls_init()
  8638.  
  8639.  
  8640. ■function _getcwd2()
  8641. ■compat emx
  8642. ■headers
  8643. #include <stdlib.h>
  8644. ■endheaders
  8645.  
  8646. ■param BUFFER SIZE
  8647. ■prototype
  8648. char *_getcwd2 (char *BUFFER, int SIZE);
  8649. ■endprototype
  8650.  
  8651.     _getcwd2() retrieves the name of the current working directory
  8652.     (including the drive name) and stores it to the array pointed to
  8653.     by BUFFER.  It is assumed that there are SIZE bytes available at
  8654.     BUFFER.  This includes the terminating 0.  If BUFFER is NULL, an
  8655.     array of suitable size, but at least SIZE bytes, is allocated with
  8656.     malloc().  _getcwd2() translates backslashes into forward slashes.
  8657.     It does not translate upper-case directory names to lower case.
  8658.  
  8659.     _getcwd2() properly handles DBCS characters.
  8660.  
  8661. ■returnvalue
  8662.  
  8663.     If successful, _getcwd2() returns BUFFER, or a buffer allocated
  8664.     with malloc() if BUFFER is NULL.  On error, _getcwd2() sets errno
  8665.     and returns NULL.
  8666.  
  8667. ■errors
  8668. ■description
  8669. ■item EINVAL
  8670.   SIZE is zero
  8671. ■item ENOMEM
  8672.   BUFFER is NULL and malloc() failed
  8673. ■item ERANGE
  8674.   BUFFER is not NULL and SIZE is positive and the length of the
  8675.   pathname plus 3 is greater than SIZE
  8676. ■enddescription
  8677.  
  8678. ■seealso chdir() getcwd() _getcwd1() _nls_init()
  8679.  
  8680.  
  8681. ■function _getdrive()
  8682. ■compat PC
  8683. ■headers
  8684. #include <stdlib.h>
  8685. ■endheaders
  8686.  
  8687. ■prototype
  8688. char _getdrive (void);
  8689. ■endprototype
  8690.  
  8691.     Get the currently selected drive.
  8692.  
  8693. ■returnvalue
  8694.  
  8695.     _getdrive() returns as upper-case letter the currently selected
  8696.     drive.
  8697.  
  8698. ■seealso _chdir2() _chdrive() _getcwd2()
  8699.  
  8700.  
  8701. ■function getenv()
  8702. ■compat C90
  8703. ■headers
  8704. #include <stdlib.h>
  8705. ■endheaders
  8706.  
  8707. ■param NAME
  8708. ■prototype
  8709. char *getenv (const char *NAME);
  8710. ■endprototype
  8711.  
  8712.     Find NAME in the environment.
  8713.  
  8714. ■returnvalue
  8715.  
  8716.     If the variable is found, getenv() returns a pointer to the
  8717.     value.  Otherwise, getenv() returns NULL.
  8718.  
  8719. ■seealso environ putenv()
  8720.  
  8721.  
  8722. ■function _getext() _getext2()
  8723. ■compat emx
  8724. ■headers
  8725. #include <stdlib.h>
  8726. ■endheaders
  8727.  
  8728. ■param PATH
  8729. ■prototype
  8730. char *_getext (const char *PATH);
  8731. char *_getext2 (const char *PATH);
  8732. ■endprototype
  8733.  
  8734.     _getext() and _getext2() return a pointer to the extension of the
  8735.     file name pointed to by PATH.  The pointer points to the dot
  8736.     character that starts the extension.  If there is no extension,
  8737.     _getext() returns NULL and _getext2() returns the empty string
  8738.     ■tt{""}.  If the last member of the string pointed to by PATH
  8739.     starts with a dot (■tt{"/usr/mattes/.profile"}, for instance),
  8740.     _getext() returns NULL and _getext2() returns the empty string
  8741.     ■tt{""}.
  8742.  
  8743.     _getext() and _getext2() properly handle DBCS characters.
  8744.  
  8745. ■returnvalue
  8746.  
  8747.     See above.
  8748.  
  8749. ■seealso _defext() _getname() _nls_init() _remext() _splitpath()
  8750.  
  8751.  
  8752. ■function _getname()
  8753. ■compat emx
  8754. ■headers
  8755. #include <stdlib.h>
  8756. ■endheaders
  8757.  
  8758. ■param PATH
  8759. ■prototype
  8760. char *_getname (const char *PATH);
  8761. ■endprototype
  8762.  
  8763.     Return a pointer to the name part (last component, including the
  8764.     extension) of the file name pointed to by PATH.  The pointer
  8765.     returned by _getname() points to the character after the last path
  8766.     separator (slash, backslash and colon).  If there is no path
  8767.     separator, PATH is returned.
  8768.  
  8769.     _getname() properly handles DBCS characters.
  8770.  
  8771. ■returnvalue
  8772.  
  8773.     See above.
  8774.  
  8775. ■seealso _getext() _nls_init() _remext() _splitpath()
  8776.  
  8777. ■samplecode
  8778. int main (int argc, char *argv[])
  8779. {
  8780.   argv[0] = _getname (argv[0]);   /* Remove pathname */
  8781.   ...
  8782. }
  8783. ■endsamplecode
  8784.  
  8785.  
  8786. ■function getopt()
  8787. ■compat POSIX.2
  8788. ■headers
  8789. #include <unistd.h>     /* without extensions */
  8790. #include <getopt.h>     /* with extensions */
  8791. ■endheaders
  8792.  
  8793. ■param ARGC ARGV OPT_STR
  8794. ■prototype
  8795. int getopt (int ARGC, char **ARGV, const char *OPT_STR);
  8796. ■endprototype
  8797.  
  8798.     Parse command line options.  ARGC is the number of argument
  8799.     strings, ARGV points to an array of pointers to argument strings,
  8800.     OPT_STR points to a string describing the available options.
  8801.     Typically, the ARGC and ARGV arguments of main() are passed to
  8802.     getopt().  Each option is of one of the following types:
  8803.  
  8804. ■itemize
  8805. ■item
  8806.  
  8807.     option without argument: the option letter is listed in the string
  8808.     pointed to by OPT_STR;
  8809.  
  8810. ■item
  8811.  
  8812.     option with mandatory argument: the option letter in the string
  8813.     pointed to by OPT_STR is followed by a colon
  8814.  
  8815. ■item
  8816.  
  8817.     option with optional argument: the option letter in the string
  8818.     pointed to by OPT_STR is followed by two colons.
  8819.  
  8820. ■enditemize
  8821.  
  8822.     For instance,
  8823.  
  8824. ■example
  8825. c = getopt (argc, argv, "abc:d::v");
  8826. ■endexample
  8827.  
  8828.     defines five options: -a, -b, -c and -v don't take arguments, -c
  8829.     takes a mandatory argument, -d takes an optional argument.
  8830.  
  8831.     Before the first call to getopt(), the global variable optind must
  8832.     be set to 0 (that's the initial value, see also bugs below).
  8833.     Calling getopt() parses the next command line option.  If there
  8834.     are no more command line options, getopt() returns -1.  After
  8835.     calling getopt(), optind is the index of the next command line
  8836.     argument.  After calling getopt(), the global variable optarg
  8837.     points to the argument of the option.  If there is no argument,
  8838.     optarg is NULL.
  8839.  
  8840.     There are three modes of operation, which are controlled by the
  8841.     global variable optmode declared in <getopt.h>:
  8842.  
  8843. ■description
  8844. ■item GETOPT_UNIX
  8845.  
  8846.     Options are at the start of the command line.  When the first
  8847.     non-option is reached, parsing options stops and getopt() returns
  8848.     -1.  GETOPT_UNIX is the default.
  8849.  
  8850. ■item GETOPT_ANY
  8851.  
  8852.     Options may appear anywhere on the command line.  ARGV is
  8853.     reordered to move the non-options to the end.  When there are no
  8854.     more options, getopt() returns -1.  The remaining arguments are
  8855.     all the arguments of the command line which are not options.
  8856.  
  8857. ■item GETOPT_KEEP
  8858.  
  8859.     Options may appear anywhere on the command line.  If the current
  8860.     argument is not an option, getopt() returns 0.  optarg will point
  8861.     to the argument.  The next call to getopt() examines the next
  8862.     command line argument.
  8863.  
  8864. ■enddescription
  8865.  
  8866.     The behavior on error (invalid option or missing argument) depends
  8867.     on the global variable opterr (which is non-zero unless set by the
  8868.     application) and the first character of the string pointed to by
  8869.     OPT_STR: If the global variable opterr is non-zero and the first
  8870.     character of the string pointed to by OPT_STR is not a colon,
  8871.     getopt() writes an appropriate error message to stderr and returns
  8872.     ■tt{'?'} or ■tt{':'}.  If opterr is zero and the first character
  8873.     of the string pointed to by OPT_STR is not a colon, getopt() does
  8874.     not display an error message and returns ■tt{'?'}.  If the first
  8875.     character of the string pointed to by OPT_STR is a colon, getopt()
  8876.     does not display an error message and returns ■tt{'?'} or
  8877.     ■tt{':'}.  In all cases, the global variable optopt is set to the
  8878.     character code of the option which caused the error.  The error
  8879.     message includes the program name which is taken from
  8880.     ■pa{ARGV}■tt{[0]}.
  8881.  
  8882.     The global variable optswchar declared in <getopt.h> is a string of
  8883.     characters which start options.  The default value is ■tt{"-"},
  8884.     that is, options are started by hyphens.  You might want to assign
  8885.     ■tt{"-/"} or ■tt{"/"} to optswchar.
  8886.  
  8887.     If a command line argument consists of two equal switch characters
  8888.     (see optswchar), the remaining command line arguments are not
  8889.     treated as options.
  8890.  
  8891.     Options may be clustered, that is, if an option does not take an
  8892.     argument, getopt() treats the following character of the same
  8893.     command line argument as option.  If an option takes a mandatory
  8894.     argument, the argument either follows immediately the option or is
  8895.     taken from the next command line argument.  If an option takes an
  8896.     optional argument, the argument must immediately follow the
  8897.     option.
  8898.  
  8899.     When writing portable programs, you should not use optmode,
  8900.     optswchar and options taking optional arguments.  Only letters
  8901.     should be used as options.
  8902.  
  8903.     optmode must not be changed after the first call to getopt().
  8904.     optswchar, however, may be changed at any time.
  8905.  
  8906. ■returnvalue
  8907.  
  8908.     getopt() returns the next option character.  If there are no more
  8909.     command line options, -1 is returned (note that the value of the
  8910.     EOF macro defined in <stdio.h> is -1).  If an invalid option is
  8911.     encountered, ■tt{'?'}  is returned.  If an argument is missing for
  8912.     an option which requires an argument, ■tt{':'} (if the first
  8913.     character of the string pointed to by OPT_STR is a colon) or
  8914.     ■tt{'?'} (if the first character of the string pointed to by
  8915.     OPT_STR is not a colon) is returned.  If optmode is GETOPT_KEEP
  8916.     and the current command line argument is not an option, 0 is
  8917.     returned.
  8918.  
  8919. ■implementation
  8920.  
  8921.     The variables optswchar and optmode are extensions.  Both are
  8922.     declared in <getopt.h> but not in <unistd.h>.  Optional arguments
  8923.     (two colons) are an extension.
  8924.  
  8925.     To reinitialize getopt(), that is, to restart parsing options, set
  8926.     optind to zero.
  8927.  
  8928. ■bugs
  8929.  
  8930.     For POSIX.2, the ARGV argument should be a ■tt{const} pointer;
  8931.     however, GETOPT_ANY reorders the array pointed to by ARGV.
  8932.  
  8933. ■seealso main() _swchar()
  8934.  
  8935.  
  8936. ■function getpagesize()
  8937. ■compat BSD
  8938. ■headers
  8939. #include <stdlib.h>
  8940. ■endheaders
  8941.  
  8942. ■prototype
  8943. int getpagesize (void);
  8944. ■endprototype
  8945.  
  8946.     Return the page size, which is 4096 for the 386.
  8947.  
  8948. ■returnvalue
  8949.  
  8950.     getpagesize() returns the page size.
  8951.  
  8952.  
  8953. ■function getpass()
  8954. ■compat UNIX
  8955. ■headers
  8956. #include <pwd.h>
  8957. #include <unistd.h>
  8958. ■endheaders
  8959.  
  8960. ■param PROMPT
  8961. ■prototype
  8962. char *getpass (const char *PROMPT);
  8963. ■endprototype
  8964.  
  8965.     Print the string pointed to by PROMPT on stderr and read a
  8966.     password from the keyboard device without echoing.  Up to
  8967.     _PASSWORD_LEN (which is 128, defined in <pwd.h>) characters can be
  8968.     entered.
  8969.  
  8970. ■returnvalue
  8971.  
  8972.     getpass() returns a pointer to a statically allocated buffer.  The
  8973.     string will be null-terminated.
  8974.  
  8975. ■seealso _getpass1() _getpass2()
  8976.  
  8977. ■function _getpass1() _getpass2()
  8978. ■compat emx
  8979. ■headers
  8980. #include <pwd.h>
  8981. #include <unistd.h>
  8982. ■endheaders
  8983.  
  8984. ■param PROMPT KBD
  8985. ■prototype
  8986. char *_getpass1 (const char *PROMPT);
  8987. char *_getpass2 (const char *PROMPT, int KBD);
  8988. ■endprototype
  8989.  
  8990.     Print the string pointed to by PROMPT on stderr and read a
  8991.     password from the keyboard device or from standard input without
  8992.     echoing.  Up to _PASSWORD_LEN (which is 128, defined in <pwd.h>)
  8993.     characters can be entered.
  8994.  
  8995.     _getpass1() reads from the keyboard device if standard input is
  8996.     associated with the console.  Otherwise, _getpass1() reads from
  8997.     standard input.
  8998.  
  8999.     _getpass2() reads from the keyboard device if KBD is non-zero.
  9000.     _getpass2() reads from standard input if KBD is zero.
  9001.  
  9002. ■returnvalue
  9003.  
  9004.     _getpass1() and _getpass2() return a pointer to a statically
  9005.     allocated buffer.  The buffer is shared by getpass(), _getpass1(),
  9006.     and _getpass2().  The string will be null-terminated.
  9007.  
  9008. ■hints
  9009.  
  9010.     Use _getpass2() passing zero for KBD if the application should
  9011.     work correctly with pseudo ttys (ptys).
  9012.  
  9013. ■seealso getpass()
  9014.  
  9015.  
  9016. ■function getpid()
  9017. ■compat UNIX
  9018. ■headers
  9019. #include <process.h>
  9020. ■endheaders
  9021.  
  9022. ■prototype
  9023. int getpid (void);
  9024. ■endprototype
  9025.  
  9026.     Get the process identification number of the calling process.
  9027.  
  9028. ■returnvalue
  9029.  
  9030.     getpid() returns the process identification number of the calling
  9031.     process.
  9032.  
  9033. ■seealso getppid() _gettid()
  9034.  
  9035.  
  9036. ■function getppid()
  9037. ■compat UNIX
  9038. ■headers
  9039. #include <process.h>
  9040. ■endheaders
  9041.  
  9042. ■prototype
  9043. int getppid (void);
  9044. ■endprototype
  9045.  
  9046.     Get the process identification number of the parent process of
  9047.     the calling process.
  9048.  
  9049. ■returnvalue
  9050.  
  9051.     getppid() returnes the process identification number of the parent
  9052.     process of the calling process.
  9053.  
  9054. ■seealso getpid()
  9055.  
  9056.  
  9057. ■function getpwent() getpwuid() getpwnam() setpwent() endpwent()
  9058. ■compat UNIX
  9059. ■headers
  9060. #include <pwd.h>
  9061. ■endheaders
  9062.  
  9063. ■param UID NAME
  9064. ■prototype
  9065. struct passwd *getpwent (void);
  9066. struct passwd *getpwuid (int UID);
  9067. struct passwd *getpwnam (char *NAME);
  9068. void setpwent (void);
  9069. void endpwent (void);
  9070. ■endprototype
  9071.  
  9072.     Dummy functions.
  9073.  
  9074. ■seealso cuserid()
  9075.  
  9076.  
  9077. ■function gets()
  9078. ■compat C90
  9079. ■headers
  9080. #include <stdio.h>
  9081. ■endheaders
  9082.  
  9083. ■param BUFFER
  9084. ■prototype
  9085. char *gets (char *BUFFER);
  9086. ■endprototype
  9087.  
  9088.     Read a string from stdin to the array pointed to by BUFFER.  Stop
  9089.     after a newline (LF) character has been read.  The newline
  9090.     character is replaced with a null character.  Use fgets() instead
  9091.     as gets() doesn't know how big the array pointed to by BUFFER is.
  9092.  
  9093. ■returnvalue
  9094.  
  9095.     gets() returns BUFFER.  If an error occurs or the end of the file
  9096.     is reached, gets() returns NULL.
  9097.  
  9098. ■seealso fgets() scanf()
  9099.  
  9100.  
  9101. ■function _getsockhandle()
  9102. ■compat emx *
  9103. ■headers
  9104. #include <stdlib.h>
  9105. ■endheaders
  9106.  
  9107. ■param HANDLE
  9108. ■prototype
  9109. int _getsockhandle (int HANDLE);
  9110. ■endprototype
  9111.  
  9112.     Return the internal socket handle associated with socket handle
  9113.     HANDLE.  As emx.dll maps socket handles internally, you cannot
  9114.     pass handles directly to IBM TCP/IP for OS/2 functions.  Use
  9115.     _getsockhandle() to retrieve the internal socket handle (for IBM
  9116.     TCP/IP for OS/2) of a socket handle.  Internal socket handles can
  9117.     be used with IBM TCP/IP for OS/2 functions, only.  Note that you
  9118.     cannot use socket handles and internal socket handles with OS/2
  9119.     API functions such as DosRead.
  9120.  
  9121.     You have to link with the ■tt{socket} library (use the -lsocket
  9122.     option).
  9123.  
  9124. ■returnvalue
  9125.  
  9126.     _getsockhandle() returns an internal socket handle.  On error,
  9127.     _getsockhandle() sets errno and returns -1.
  9128.  
  9129. ■restrictions
  9130.  
  9131.     _getsockhandle() is implemented for OS/2 only.
  9132.  
  9133.     _getsockhandle() is not available with the system call library
  9134.     sys.lib (■hpt{-Zsys}).
  9135.  
  9136. ■hints
  9137.  
  9138.     _getsockhandle() can be used with _impsockhandle() to pass socket
  9139.     handles down to child processes.  See ■hpt{_impsockhandle()} for
  9140.     details.
  9141.  
  9142. ■seealso _impsockhandle()
  9143.  
  9144.  
  9145. ■function _gettid()
  9146. ■compat emx
  9147. ■headers
  9148. #include <stdlib.h>
  9149. ■endheaders
  9150.  
  9151. ■prototype
  9152. int _gettid (void);
  9153. ■endprototype
  9154.  
  9155.     Get the thread identification number of the calling thread.
  9156.  
  9157. ■returnvalue
  9158.  
  9159.     _gettid() returns the thread identification number of the calling
  9160.     thread.  Under DOS, _gettid() always returns 1.
  9161.  
  9162. ■seealso _beginthread() getpid() _threadid _threadstore()
  9163.  
  9164.  
  9165. ■function _getvol()
  9166. ■compat emx
  9167. ■headers
  9168. #include <stdlib.h>
  9169. ■endheaders
  9170.  
  9171. ■param DRIVE
  9172. ■prototype
  9173. char *_getvol (char DRIVE);
  9174. ■endprototype
  9175.  
  9176.     Retrieve the volume label of the drive DRIVE.  DRIVE must be zero
  9177.     (for retrieving the volume label of the currently selected drive)
  9178.     or in ■tt{'A'} through ■tt{'Z'} or in ■tt{'a'} through ■tt{'z'}.
  9179.  
  9180. ■returnvalue
  9181.  
  9182.     If successful, _getvol() returns a pointer to a statically
  9183.     allocated string of up to 11 characters containing the volume
  9184.     label.  That string will be overwritten by the next call to
  9185.     _getvol().  On error, _getvol() returns NULL.
  9186.  
  9187.  
  9188. ■function getw()
  9189. ■compat UNIX
  9190. ■headers
  9191. #include <stdio.h>
  9192. ■endheaders
  9193.  
  9194. ■param STREAM
  9195. ■prototype
  9196. int getw (FILE *STREAM);
  9197. ■endprototype
  9198.  
  9199.     Read a word (■tt{int}) from STREAM.  Avoid using this function.
  9200.  
  9201. ■returnvalue
  9202.  
  9203.     getw() returns the word read.  On error, getw() returns -1.  As -1
  9204.     is also a possible word value, you have to use ferror() to
  9205.     recognize an error condition.
  9206.  
  9207. ■seealso putw() fwrite()
  9208.  
  9209.  
  9210. ■function getwd()
  9211. ■headers
  9212. #include <stdlib.h>
  9213. ■endheaders
  9214.  
  9215. ■param BUFFER
  9216. ■prototype
  9217. char *getwd (char *BUFFER);
  9218. ■endprototype
  9219.  
  9220.     getwd() retrieves the name of the current working directory
  9221.     (excluding the drive name) and stores it to the array pointed to
  9222.     by BUFFER.  It is assumed that there are MAXPATHLEN bytes
  9223.     available at BUFFER.  This includes the terminating 0.  MAXPATHLEN
  9224.     is defined in <sys/param.h>.  getwd() translates backslashes into
  9225.     forward slashes.  It does not translate upper-case directory names
  9226.     to lower case.
  9227.  
  9228.     getwd() properly handles DBCS characters.
  9229.  
  9230. ■returnvalue
  9231.  
  9232.     If successful, getwd() returns BUFFER.  On error, getwd() copies
  9233.     an error message to BUFFER and returns NULL.
  9234.  
  9235. ■seealso getcwd() _nls_init()
  9236.  
  9237.  
  9238. ■function gettimeofday()
  9239. ■compat BSD
  9240. ■headers
  9241. #include <sys/time.h>
  9242. ■endheaders
  9243.  
  9244. ■param TP TZP
  9245. ■prototype
  9246. int gettimeofday (struct timeval *TP, struct timezone *TZP);
  9247. ■endprototype
  9248.  
  9249.     Obtain the current time and timezone.  If TP is not NULL, the
  9250.     current Coordinated Universal Time (UTC, GMT), expressed in
  9251.     seconds and microseconds since 00:00 1-Jan-1970, is stored to *TP.
  9252.     If TZP is not NULL, information about the timezone is stored to
  9253.     *TZP.
  9254.  
  9255.     The ■tt{timeval} structure is defined as follows:
  9256.  
  9257. ■example
  9258. struct timeval
  9259. {
  9260.   long tv_sec;
  9261.   long tv_usec;
  9262. };
  9263. ■endexample
  9264.  
  9265.     ■tt{tv_sec} and ■tt{tv_usec} are the number of seconds and
  9266.     microseconds, respectively, elapsed since 00:00:00 1-Jan-1970
  9267.     Coordinated Universal Time (UTC, GMT).
  9268.  
  9269. ■returnvalue
  9270. ■description
  9271. ■item 0
  9272.     success
  9273. ■item -1
  9274.     error
  9275. ■enddescription
  9276.  
  9277. ■seealso ftime() settimeofday() time()
  9278.  
  9279.  
  9280. ■function glob() globfree()
  9281. ■compat POSIX.2
  9282. ■headers
  9283. #include <glob.h>
  9284. ■endheaders
  9285.  
  9286. ■param PATTERN FLAGS ERRFUNC EPATH EERRNO PGLOB
  9287. ■prototype
  9288. int glob (const char *PATTERN, int FLAGS,
  9289.           int (*ERRFUNC)(const char *EPATH, int EERRNO), glob_t *PGLOB);
  9290. void globfree (glob_t *PGLOB);
  9291. ■endprototype
  9292.  
  9293.     The glob() function generates pathnames matching PATTERN.  The
  9294.     value of FLAGS is the bitwise OR of zero or more of the following
  9295.     flags:
  9296.  
  9297. ■description
  9298. ■item GLOB_APPEND
  9299.  
  9300.     Append new pathnames to the ones generated by a previous call of
  9301.     glob().  When calling glob() with GLOB_APPEND, glob() must have
  9302.     been called without GLOB_APPEND for the structure pointed to by
  9303.     PGLOB and the members of that structure must have the same values
  9304.     as after the previous call to glob().  Moreover, the GLOB_DOOFFS
  9305.     bit of FLAGS must have the same value as for the previous call of
  9306.     glob().
  9307.  
  9308. ■item GLOB_DOOFFS
  9309.  
  9310.     Add null pointers at the beginning of PGLOB■tt{->gl_pathv}.  The
  9311.     number of null pointers is specified by PGLOB■tt{->gl_offs}.  If
  9312.     GLOB_APPEND is set, the number of null pointers is not changed.
  9313.  
  9314. ■item GLOB_ERR
  9315.  
  9316.     Return when a non-readable directory is encountered.  If GLOB_ERR
  9317.     is not set, glob() ignores non-readable directories.
  9318.  
  9319. ■item GLOB_MARK
  9320.  
  9321.     Append a slash to pathnames that are directories.
  9322.  
  9323. ■item GLOB_NOESCAPE
  9324.  
  9325.     Do not treat backslash as an escape character.  If GLOB_NOESCAPE
  9326.     is not set, backslash can be used to remove the special meaning
  9327.     from special characters such as` ■tt{*}' and `■tt{[}'.
  9328.  
  9329. ■item GLOB_NOCHECK
  9330.  
  9331.     If PATTERN does not match any pathname, add PATTERN to
  9332.     PGLOB■tt{->gl_pathv}.  If PATTERN does not match any pathname and
  9333.     GLOB_NOCHECK is not set, glob() returns an error.
  9334.  
  9335. ■item GLOB_NOSORT
  9336.  
  9337.     Do not sort the pathnames.  If GLOB_NOSORT is not set, the
  9338.     pathnames added by this call of glob() are sorted according to
  9339.     strcoll().
  9340.  
  9341. ■item GLOB_PERIOD
  9342.  
  9343.     Also include pathnames that have a component starting with a
  9344.     period.  If GLOB_PERIOD is not set, those pathnames are excluded.
  9345.  
  9346. ■enddescription
  9347.  
  9348.     If a non-readable directory is encountered and ERRFUNC is not a
  9349.     null pointer, ERRFUNC will be called with EPATH pointing to the
  9350.     pathname of the non-readable directory and EERRNO set to the errno
  9351.     value.  If ERRFUNC returns a non-zero value, glob() will stop the
  9352.     scan and return GLOB_ABEND.  If ERRFUNC returns zero, the behavior
  9353.     depends on GLOB_ERR.
  9354.  
  9355.     PGLOB points to a structure of type glob_t which is defined as
  9356.     follows:
  9357.  
  9358. ■example
  9359. typedef struct
  9360. {
  9361.   size_t gl_pathc;
  9362.   char **gl_pathv;
  9363.   size_t gl_offs;
  9364.   /* Members used internally are not shown here */
  9365. } glob_t;
  9366. ■endexample
  9367.  
  9368.     The gl_pathc member contains the number of pathnames matched by
  9369.     PATTERN.  If gl_pathc is zero, the value of gl_pathv is undefined.
  9370.     gl_pathv contains a pointer to an array of pointers to pathnames:
  9371.     If GLOB_DOOFFS is set, the array starts with gl_offs null
  9372.     pointers.  If GLOB_DOOFFS is not set, gl_offs is ignored (treated
  9373.     as zero).  Following these null pointers (if any), glob() stores
  9374.     gl_pathc pointers to pathnames.  A null pointer follows the last
  9375.     pathname.
  9376.  
  9377.     The characters `■tt{?}', `■tt{*}', and `■tt{[]}' are interpreted
  9378.     as wildcard characters in the pattern.  `■tt{?}' matches one
  9379.     character, `■tt{*}' matches zero or more characters.  `■tt{[]}'
  9380.     matches the set of characters listed between the brackets, ranges
  9381.     (such as `■tt{[0-9]}') are allowed.  If the first character after
  9382.     `■tt{[}' is `■tt{!}', all characters ■em{not} in the set match the
  9383.     set.
  9384.  
  9385.     globfree() deallocates any memory allocated by glob() for the
  9386.     structure pointed to by PGLOB.  glob() must have been called for
  9387.     the structure pointed to by PGLOB and the members of that
  9388.     structure must have the same values as after the last call to
  9389.     glob().
  9390.  
  9391. ■returnvalue
  9392.  
  9393.     glob() returns one of the following values:
  9394.  
  9395. ■description
  9396. ■item 0
  9397.     Success
  9398. ■item GLOB_ABEND
  9399.     The operation of glob() was stopped for a non-readable directory
  9400.     because GLOB_ERR was set or ERRFUNC returned a non-zero value
  9401. ■item GLOB_NOMATCH
  9402.     No pathname matching PATTERN found
  9403. ■item GLOB_NOSPACE
  9404.     Out of memory
  9405. ■enddescription
  9406.  
  9407.   Even if glob() returns a non-zero value, gl_pathc and gl_pathv of
  9408.   the structure pointed to by PGLOB are set.
  9409.  
  9410. ■implementation
  9411.  
  9412.     If the first character after `■tt{[}' is `■tt{^}', all characters
  9413.     ■em{not} in the set match the set.
  9414.  
  9415. ■seealso _fnexplode() fnmatch() strcoll() _wildcard()
  9416.  
  9417.  
  9418. ■function gmtime()
  9419. ■compat C90
  9420. ■headers
  9421. #include <time.h>
  9422. ■endheaders
  9423.  
  9424. ■param T
  9425. ■prototype
  9426. struct tm *gmtime (const time_t *T);
  9427. ■endprototype
  9428.  
  9429.     Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
  9430.     Coordinated Universal Time (UTC, GMT) in the variable pointed to
  9431.     by T to a time and date structure (UTC) and return a pointer to
  9432.     the structure.  gmtime(), mktime() and localtime() use the same
  9433.     memory location, therefore the values are overwritten if one of
  9434.     these functions is called.
  9435.  
  9436. ■returnvalue
  9437.  
  9438.     gmtime() returns a pointer to a structure.
  9439.  
  9440. ■seealso asctime() ctime() localtime() mktime() time()
  9441.  
  9442.  
  9443. ■function _heapchk()
  9444. ■compat PC
  9445. ■headers
  9446. #include <malloc.h>
  9447. ■endheaders
  9448.  
  9449. ■prototype
  9450. int _heapchk (void);
  9451. ■endprototype
  9452.  
  9453.     _heapchk() checks the default heap and the tiled default heap and
  9454.     all their blocks for consistency.  Note that _heapchk() may crash
  9455.     if the heap is corrupted.  _heapchk() can help debugging programs
  9456.     which experience heap problems.
  9457.  
  9458. ■returnvalue
  9459.  
  9460.     _heapchk() returns one of the following values:
  9461. ■description
  9462. ■item _HEAPBADBEGIN
  9463.     The heap is corrupted.
  9464. ■item _HEAPBADEND
  9465.     The heap is corrupted.
  9466. ■item _HEAPBADNODE
  9467.     A block of the heap is damaged or the heap is corrupted.
  9468. ■item _HEAPEMPTY
  9469.     The heap has not been initialized.
  9470. ■item _HEAPOK
  9471.     The heap seems to be consistent.
  9472. ■enddescription
  9473.  
  9474. ■seealso _udefault() _heapset() _uheapchk() _utdefault()
  9475.  
  9476.  
  9477. ■function _heapmin()
  9478. ■compat VAC++
  9479. ■headers
  9480. #include <malloc.h>
  9481. ■endheaders
  9482.  
  9483. ■prototype
  9484. int _heapmin (void);
  9485. ■endprototype
  9486.  
  9487.     The _heapmin() function returns unused memory of the default
  9488.     regular heap to the operating system.  The heap is never made
  9489.     smaller than its initial size.  Calling _heapmin() is equivalent
  9490.     to calling _uheapmin() for the default heap.
  9491.  
  9492. ■returnvalue
  9493. ■description
  9494. ■item 0
  9495.     success
  9496. ■item -1
  9497.     error
  9498. ■enddescription
  9499.  
  9500. ■seealso brk() _heapchk() sbrk() _theapmin() _udefault() _uheapmin()
  9501.  
  9502.  
  9503. ■function _heapset()
  9504. ■compat PC
  9505. ■headers
  9506. #include <malloc.h>
  9507. ■endheaders
  9508.  
  9509. ■param FILL
  9510. ■prototype
  9511. int _heapset (unsigned FILL);
  9512. ■endprototype
  9513.  
  9514.     _heapset() fills all bytes of all unused blocks of the default
  9515.     heap and the tiled default heap with FILL.  Note that _heapset()
  9516.     may crash if the heap is corrupted.  _heapset() can help debugging
  9517.     programs which erroneously depend on the contents of dynamically
  9518.     allocated blocks.  ■hpt{_heapchk()} checks the heap more
  9519.     thoroughly than _heapset().
  9520.  
  9521. ■returnvalue
  9522.  
  9523.     _heapset() returns one of the following values:
  9524. ■description
  9525. ■item _HEAPBADBEGIN
  9526.     The heap is corrupted.
  9527. ■item _HEAPBADEND
  9528.     The heap is corrupted.
  9529. ■item _HEAPBADNODE
  9530.     A block of the heap is damaged or the heap is corrupted.
  9531. ■item _HEAPEMPTY
  9532.     The heap has not been initialized.
  9533. ■item _HEAPOK
  9534.     The heap seems to be consistent.
  9535. ■enddescription
  9536.  
  9537. ■seealso _udefault() _heapchk() _uheapset() _utdefault()
  9538.  
  9539.  
  9540. ■function _heap_walk() _uheap_walk()
  9541. ■compat VAC++
  9542. ■headers
  9543. #include <malloc.h>     /* for _heap_walk() */
  9544. #include <umalloc.h>    /* for _uheap_walk() */
  9545. ■endheaders
  9546.  
  9547. ■param H CALLBACK
  9548. ■param BLOCK SIZE FLAG STATUS FNAME LINENO
  9549. ■prototype
  9550. int _heap_walk (int (*CALLBACK)(const void *, size_t, int, int,
  9551.                                 const char *, size_t));
  9552. int _uheap_walk (Heap_t H, int (*CALLBACK)(const void *, size_t, int, int,
  9553.                                            const char *, size_t));
  9554. ■endprototype
  9555.  
  9556.     _heap_walk() applies the function pointed to by CALLBACK to all
  9557.     free and used blocks of the default heap and the tiled default
  9558.     heap.
  9559.  
  9560.     _uheap_walk() applies the function pointed to by CALLBACK to all
  9561.     free and used blocks of the heap H.
  9562.  
  9563.     Note that the heap is locked, so using the heap in the callback
  9564.     function will cause a deadlock.
  9565.  
  9566. ■indent
  9567.     ■tt{int my_walker (const void *}BLOCK■tt{, size_t }SIZE■tt{, int }FLAG■tt{,} ■break
  9568.     ■tt{               int }STATUS■tt{, const char *}FNAME■tt{, size_t }LINENO■tt{);}
  9569. ■endindent
  9570.  
  9571.     BLOCK points to a block of SIZE bytes.  FLAG is either _USEDENTRY
  9572.     (for a used block) or _FREEENTRY (for a free block).  STATUS is
  9573.     one of the following values, describing the status of the block:
  9574.  
  9575. ■description
  9576. ■item _HEAPBADBEGIN
  9577.     The heap is corrupted.
  9578. ■item _HEAPBADEND
  9579.     The heap is corrupted.
  9580. ■item _HEAPBADNODE
  9581.     The block is damaged.
  9582. ■item _HEAPEMPTY
  9583.     The heap has not been initialized.
  9584. ■item _HEAPOK
  9585.     The heap seems to be consistent (_HEAPOK is 0).
  9586. ■enddescription
  9587.  
  9588.     FNAME points to the file name of the source file in which the
  9589.     block has been allocated.  LINENO is the line number in which the
  9590.     block has been allocated.  FNAME is NULL if that information is
  9591.     not available, that is, if the object has not been allocated with
  9592.     a debugging heap function.
  9593.  
  9594.  
  9595. ■returnvalue
  9596.  
  9597.     _heap_walk() and _uheap_walk() return the last status (see above
  9598.     for a list of values) unless the callback function returned a
  9599.     non-zero value.  If the callback function returned a non-zero
  9600.     value, _heap_walk() and _uheap_walk() return that value.
  9601.  
  9602. ■restrictions
  9603.  
  9604.     FNAME is current always NULL as there are no debugging heap
  9605.     functions.
  9606.  
  9607. ■hints
  9608.  
  9609.     Use an extra heap if you want to allocate memory in the callback
  9610.     function.
  9611.  
  9612. ■seealso _heapchk() _udefault() _uheapchk() _uheap_walk2()
  9613.  
  9614. ■samplecode
  9615. #include <stdio.h>
  9616. #include <malloc.h>
  9617. #include <umalloc.h>
  9618.  
  9619. static int walk_dump (const void *obj, size_t size, int flag,
  9620.                       int status, const char *fname, size_t lineno)
  9621. {
  9622.   if (status == _HEAPOK)
  9623.     printf ("0x%.8lx 0x%.8lx %s\n",
  9624.             (unsigned long)obj, (unsigned long)size,
  9625.             flag == _FREEENTRY ? "free" : "used");
  9626.   return status;
  9627. }
  9628.  
  9629. int main (void)
  9630. {
  9631.   void *p;
  9632.  
  9633.   /* Avoid deadlock due to buffer allocation in printf()! */
  9634.   setvbuf (stdout, NULL, _IOLBF, BUFSIZ);
  9635.  
  9636.   p = malloc (1000);
  9637.   malloc (2000);
  9638.   free (p);
  9639.   _heap_walk (walk_dump);
  9640.   return 0;
  9641. }
  9642. ■endsamplecode
  9643.  
  9644.  
  9645. ■function hypot() hypotl()
  9646. ■compat C9X
  9647. ■headers
  9648. #include <math.h>
  9649. ■endheaders
  9650.  
  9651. ■param X Y
  9652. ■prototype
  9653. double hypot (double X, double Y);
  9654. long double hypotl (long double X, long double Y);
  9655. ■endprototype
  9656.  
  9657.     Compute and return
  9658.  
  9659. ■typewriter
  9660.   sqrt (■pa{X}*■pa{X} + ■pa{Y}*■pa{Y})
  9661. ■endtypewriter
  9662.  
  9663.     On overflow, +INF is returned and errno is set to ERANGE.
  9664.  
  9665.     hypotl() uses the ■tt{long double} format.
  9666.  
  9667. ■returnvalue
  9668.  
  9669.     See above.
  9670.  
  9671. ■seealso sqrt()
  9672.  
  9673.  
  9674. ■function _imphandle()
  9675. ■compat emx
  9676. ■headers
  9677. #include <io.h>
  9678. ■endheaders
  9679.  
  9680. ■param HANDLE
  9681. ■prototype
  9682. int _imphandle (int HANDLE);
  9683. ■endprototype
  9684.  
  9685.     Register an OS/2 file handle (created by DosOpen, for instance)
  9686.     with the emx run-time system.  Without importing an OS/2 file
  9687.     handle with _imphandle() into the emx run-time system, that handle
  9688.     cannot be used with any C library function.  If necessary,
  9689.     _imphandle() relocates the file handle (this happens when sockets
  9690.     are used).  After calling _imphandle(), you can use the returned
  9691.     file handle both with library functions and OS/2 API functions,
  9692.     and HANDLE can no longer be used (unless identical to the handle
  9693.     returned).  _imphandle() must not be called for file handles not
  9694.     created by an OS/2 API function.  _imphandle() must not be called
  9695.     for socket handles.  Handles inherited from the parent process are
  9696.     already registered with the emx run-time system.
  9697.  
  9698. ■returnvalue
  9699.  
  9700.     _imphandle() returns a file handle.  On error, _imphandle() sets
  9701.     errno and returns -1.
  9702.  
  9703. ■seealso dup() _impsockhandle() open()
  9704.  
  9705.  
  9706. ■function _impsockhandle()
  9707. ■compat emx
  9708. ■headers
  9709. #include <sys/socket.h>
  9710. ■endheaders
  9711.  
  9712. ■param HANDLE RESERVED
  9713. ■prototype
  9714. int _impsockhandle (int HANDLE, int RESERVED);
  9715. ■endprototype
  9716.  
  9717.     Register a socket handle of IBM TCP/IP with the emx run-time
  9718.     system.  HANDLE is the socket handle.  It must not be an emx
  9719.     socket handle.  To obtain the IBM TCP/IP socket handle of an emx
  9720.     socket handle, use ■hpt{_getsockhandle()}.  RESERVED must be zero.
  9721.  
  9722.     You have to link with the ■tt{socket} library (use the -lsocket
  9723.     option).
  9724.  
  9725. ■returnvalue
  9726.  
  9727.     _impsockhandle() returns a file handle.  On error,
  9728.     _impsockhandle() sets errno and returns -1.
  9729.  
  9730. ■restrictions
  9731.  
  9732.     _getsockhandle() is implemented for OS/2 only.
  9733.  
  9734.     _impsockhandle() is not available with the system call library
  9735.     sys.lib (■hpt{-Zsys}).
  9736.  
  9737. ■hints
  9738.  
  9739.     _getsockhandle() and _impsockhandle() can be used to pass down
  9740.     socket handles to child processes.  Call _getsockhandle() in the
  9741.     parent process, pass the value returned by _getsockhandle() to the
  9742.     child process (on the command line, for instance), and call
  9743.     _impsockhandle() on that value in the child process.  Do not close
  9744.     the socket in the parent process until the child process has
  9745.     called _impsockhandle() for that socket (use a semaphore if the
  9746.     child process is run asynchronously)!  Note that socket handles
  9747.     are automatically inherited across fork(), therefore
  9748.     _impsockhandle() must not be used with fork().
  9749.  
  9750. ■seealso _getsockhandle() _imphandle()
  9751.  
  9752.  
  9753. ■function index()
  9754. ■compat BSD
  9755. ■headers
  9756. #include <strings.h>
  9757. ■endheaders
  9758.  
  9759. ■param STRING C
  9760. ■prototype
  9761. char *index (const char *STRING, int C);
  9762. ■endprototype
  9763.  
  9764.     Return a pointer to the first occurrence of the character C in the
  9765.     null-terminated string pointed to by STRING.  If there is no
  9766.     character C in that string, NULL is returned.  If C is the null
  9767.     character (0), a pointer to the terminating null character of that
  9768.     string is returned.
  9769.  
  9770. ■returnvalue
  9771.  
  9772.     See above.
  9773.  
  9774. ■seealso rindex() strchr()
  9775.  
  9776.  
  9777. ■function _inp8() _inp16() _inp32()
  9778. ■compat emx *
  9779. ■headers
  9780. #include <sys/hw.h>
  9781. ■endheaders
  9782.  
  9783. ■param PORT
  9784. ■prototype
  9785. unsigned _inp8 (unsigned PORT);
  9786. unsigned _inp16 (unsigned PORT);
  9787. unsigned _inp32 (unsigned PORT);
  9788. ■endprototype
  9789.  
  9790.     These functions read a single byte or word from a hardware port.
  9791.     _inp8() reads a byte from PORT, _inp16() reads a 16-bit word from
  9792.     PORT, _inp32() reads a 32-bit word from PORT.
  9793.  
  9794.     You have to call _portaccess() first to enable access to a range
  9795.     of ports.  To make your program work under DOS, you have to use
  9796.     emx option -ai, see `■hpt{Using emx options}'.  Under OS/2, your
  9797.     program requires emxio.dll in a directory listed in LIBPATH.
  9798.  
  9799. ■returnvalue
  9800.  
  9801.     _inp8(), _inp16() and _inp32() return the value read from PORT.
  9802.  
  9803. ■seealso _portaccess() _inps8() _outp8() _wait0()
  9804.  
  9805.  
  9806. ■function _inps8() _inps16() _inps32()
  9807. ■compat emx *
  9808. ■headers
  9809. #include <sys/hw.h>
  9810. ■endheaders
  9811.  
  9812. ■param PORT DST COUNT
  9813. ■prototype
  9814. void _inps8 (unsigned PORT, unsigned char *DST, unsigned COUNT);
  9815. void _inps16 (unsigned PORT, unsigned short *DST, unsigned COUNT);
  9816. void _inps32 (unsigned PORT, unsigned long *DST, unsigned COUNT);
  9817. ■endprototype
  9818.  
  9819.     These functions read multiple bytes or words from a hardware port.
  9820.     _inps8() reads COUNT bytes from PORT to the array pointed to by
  9821.     DST.  _inps16() reads COUNT 16-bit words from PORT to the array
  9822.     pointed to by DST.  _inps32() reads COUNT 32-bit words from PORT
  9823.     to the array pointed to by DST.
  9824.  
  9825.     The COUNT argument of _inps8() must not exceed 65535.
  9826.  
  9827.     The array pointed to by DST of _inps16() must be aligned on a
  9828.     16-bit boundary, that is, the address must be even.  COUNT must
  9829.     not exceed 32768.
  9830.  
  9831.     The array pointed to by DST of _inps32() must be aligned on a
  9832.     32-bit boundary, that is, the address must be a multiple of four.
  9833.     COUNT must not exceed 65536.
  9834.  
  9835.     You have to call _portaccess() first to enable access to a range
  9836.     of ports.  To make your program work under DOS, you have to use
  9837.     emx option -ai, see `■hpt{Using emx options}'.  Under OS/2, your
  9838.     program requires emxio.dll in a directory listed in LIBPATH.
  9839.  
  9840. ■seealso _portaccess() _inp8() _outps8()
  9841.  
  9842.  
  9843. ■function _int86()
  9844. ■compat PC
  9845. ■headers
  9846. #include <dos.h>
  9847. ■endheaders
  9848.  
  9849. ■param INT_NUM INP_REGS OUT_REGS
  9850. ■prototype
  9851. int _int86 (int INT_NUM, const union REGS *INP_REGS, union REGS *OUT_REGS);
  9852. ■endprototype
  9853.  
  9854.     Issue a software interrupt under DOS.  This function loads the
  9855.     processor registers EAX, EBX, ECX, EDX, ESI and EDI from INP_REGS,
  9856.     calls software interrupt INT_NUM and stores the processor
  9857.     registers EAX, EBX, ECX, EDX, ESI, EDI and the flags register to
  9858.     OUT_REGS.
  9859.  
  9860.     emx option -ac must be used to enable _int86().  If -ac is not
  9861.     used, a protection violation exception occurs when _int86() is
  9862.     called.  See `■hpt{Using emx options}'.
  9863.  
  9864. ■returnvalue
  9865.  
  9866.     _int86() returns the value of the EAX register.
  9867.  
  9868. ■restrictions
  9869.  
  9870.     _int86() is not supported under OS/2 (there are no software
  9871.     interrupts under OS/2).  Calling _int86() under OS/2 results in a
  9872.     protection violation.
  9873.  
  9874.     The emx DOS extender currently supports only interrupts 0x10,
  9875.     0x11, 0x14, 0x16, 0x17, 0x21 and 0x33.  Please note the following
  9876.     difference to DOS C compilers: the REGS union does not contain an
  9877.     ■tt{x.cflag} field.  The complete flags register is stored to the
  9878.     ■tt{e.eflags} field instead.  The carry flag is available in bit 0
  9879.     of the ■tt{e.eflags} and ■tt{x.flags} fields.
  9880.  
  9881.     The following functions of interrupt 0x10 (video) are supported
  9882.     (the AH register contains the function number):
  9883.  
  9884. ■indent
  9885.  
  9886.         0x00-0x0f, 0x10 (only subfunctions which don't involve
  9887.         pointers), 0x13, 0x1a, 0x40-0x4e (Hercules GRAFIX), 0x4f
  9888.         (VESA, subfunction AL=0x06 not supported), 0x6f, 0xf0, 0xf1,
  9889.         0xf6
  9890.  
  9891. ■endindent
  9892.  
  9893.     The following functions of interrupt 0x21 (DOS call) are supported
  9894.     (the AH register contains the function number):
  9895.  
  9896. ■indent
  9897.  
  9898.         0x01-0x0c, 0x0e, 0x19, 0x2a-0x2e, 0x30, 0x33, 0x36-0x37,
  9899.         0x39-0x47, 0x4b-0x4f, 0x54, 0x56, 0x57, 0x5a, 0x5b
  9900.  
  9901. ■endindent
  9902.  
  9903.     The following functions of interrupt 0x33 (mouse) are supported
  9904.     (the AX register contains the function number):
  9905.  
  9906. ■indent
  9907.  
  9908.         0x00-0x0b, 0x0d-0x13, 0x15, 0x1a-0x28, 0x2a, 0x2f-0x32, 0x35
  9909.  
  9910. ■endindent
  9911.  
  9912.     No pointer conversion is done for interrupts 0x11, 0x14, 0x16 and
  9913.     0x17.  That is, you cannot use functions which involve pointers to
  9914.     buffers in memory.
  9915.  
  9916. ■samplefile /emx/test/int10.c
  9917.  
  9918.  
  9919. ■function ioctl()
  9920. ■compat SysV *
  9921. ■headers
  9922. #include <sys/ioctl.h>
  9923. #include <sys/termio.h>   /* for System V terminal interface */
  9924. #include <sys/kbdscan.h>  /* optional, for extended scan codes */
  9925. ■endheaders
  9926.  
  9927. ■param HANDLE REQUEST INT_ARG PTR_ARG TIO
  9928. ■prototype
  9929. int ioctl (int HANDLE, int REQUEST, int INT_ARG);
  9930. int ioctl (int HANDLE, int REQUEST, void *PTR_ARG);
  9931. int ioctl (int HANDLE, int REQUEST, struct termio *TIO);
  9932. ■endprototype
  9933.  
  9934.     Device control for HANDLE.  REQUEST codes are:
  9935.  
  9936. ■description
  9937. ■item TCGETA
  9938.  
  9939.     Get the parameters associated with the terminal HANDLE and store
  9940.     them in the object pointed to by TIO.  See also `■hpt{General
  9941.     terminal interface}'.
  9942.  
  9943. ■item TCSETA
  9944.  
  9945.     Immediately set the parameters associated with the terminal HANDLE
  9946.     from the object pointed to by TIO.  See also `■hpt{General
  9947.     terminal interface}'.
  9948.  
  9949. ■item TCSETAF
  9950.  
  9951.     Set the parameters associated with the terminal HANDLE from the
  9952.     object pointed to by TIO after waiting for the output to drain and
  9953.     after fglusing the input queue.  See also `■hpt{General terminal
  9954.     interface}'.
  9955.  
  9956. ■item TCSETAW
  9957.  
  9958.     Set the parameters associated with the terminal HANDLE from the
  9959.     object pointed to by TIO after waiting for the output to drain.
  9960.     See also `■hpt{General terminal interface}'.
  9961.  
  9962. ■item TCFLSH
  9963.  
  9964.     Flush the terminal queues.  If INT_ARG is 0, the input queue is
  9965.     flushed; if INT_ARG is 1, the output queue is flushed; if INT_ARG
  9966.     is 2, both the input and output queues are flushed.  Works only if
  9967.     HANDLE refers to the keyboard.  Only flushing the keyboard queue
  9968.     is implemented.
  9969.  
  9970. ■item TCSBRK
  9971.  
  9972.     Wait for output to drain and then send a break. The length of the
  9973.     break depends on INT_ARG.  Currently ignored.  It is not yet
  9974.     specified how the length of the break depends on INT_ARG.
  9975.  
  9976. ■item TCXONC
  9977.  
  9978.     flow control, depending on INT_ARG.  Currently ignored
  9979.  
  9980. ■item FIONREAD
  9981.  
  9982.     Get number of available characters.  The number of available
  9983.     characters is stored to the int pointed to by PTR_ARG.  FIONREAD
  9984.     is implemented for the following types of handles:
  9985.  
  9986. ■itemize
  9987. ■item
  9988.  
  9989.     Terminal handles (keyboard) for which the general terminal
  9990.     interface is enabled.  Note that if ICANON is set, the number of
  9991.     characters in the keyboard buffer is returned which is not the
  9992.     number of characters available for read(), as at least one of the
  9993.     buffered characters (carriage return) is used for command line
  9994.     editing
  9995.  
  9996. ■item
  9997.  
  9998.     Pseudo TTYs and console device implemented by xf86sup.sys
  9999.  
  10000. ■item
  10001.  
  10002.     Named pipes
  10003.  
  10004. ■item
  10005.  
  10006.     Pipes created with pipe() by programs using emx.dll
  10007.  
  10008. ■item
  10009.  
  10010.     Sockets
  10011.  
  10012. ■item
  10013.  
  10014.     All file handles under DOS (0 or 1 character available).
  10015.  
  10016. ■enditemize
  10017.  
  10018. ■item FGETHTYPE
  10019.  
  10020.     Get the handle type and store it to the int pointed to by
  10021.     PTR_ARG.  See <sys/ioctl.h> for handle types (HT_FILE, for
  10022.     instance).
  10023.  
  10024. ■enddescription
  10025.  
  10026.     There are additional REQUESTS codes for socket handles.
  10027.  
  10028. ■returnvalue
  10029.  
  10030.     On error, ioctl() sets errno and returns -1.  Otherwise, ioctl()
  10031.     returns 0 unless a different return value is defined above.
  10032.  
  10033. ■restrictions
  10034.  
  10035.     With the system call library sys.lib (■hpt{-Zsys}), only the
  10036.     FGETHTYPE request is available.
  10037.  
  10038.     The TCSBRK and TCXONC requests are currently ignored.
  10039.  
  10040.     Under DOS, for requests TCGETA, TCSETA, TCSETAF, TCSETAW, and
  10041.     TCFLSH, the value of the HANDLE argument must be 0.
  10042.  
  10043.     TCFLSH is implemented for the keyboard, only.
  10044.  
  10045. ■seealso fcntl() open() read()
  10046.  
  10047.  
  10048. ■function isascii()
  10049. ■compat UNIX
  10050. ■headers
  10051. #include <ctype.h>
  10052. ■endheaders
  10053.  
  10054. ■param C
  10055. ■prototype
  10056. int isascii (int C);
  10057. ■endprototype
  10058.  
  10059.     Return a non-zero value iff C is a valid ASCII character (0
  10060.     through 127).  isascii() can be applied to all integer values.
  10061.     isascii() is implemented both as macro and as function.
  10062.  
  10063. ■returnvalue
  10064.  
  10065.     See above.
  10066.  
  10067. ■seealso isalnum()
  10068.  
  10069.  
  10070. ■function isalnum() isalpha() iscntrl() isdigit() isgraph() islower() isprint() ispunct() isspace() isupper() isxdigit()
  10071. ■compat C90
  10072. ■headers
  10073. #include <ctype.h>
  10074. ■endheaders
  10075.  
  10076. ■param C
  10077. ■prototype
  10078. int isalnum (int C);
  10079. int isalpha (int C);
  10080. int iscntrl (int C);
  10081. int isdigit (int C);
  10082. int isgraph (int C);
  10083. int islower (int C);
  10084. int isprint (int C);
  10085. int ispunct (int C);
  10086. int isspace (int C);
  10087. int isupper (int C);
  10088. int isxdigit (int C);
  10089. ■endprototype
  10090.  
  10091.     These functions (or macros) are used for determining the type of a
  10092.     character, depending on the current locale.  C must be an integer
  10093.     which is representable as ■tt{unsigned char} (that is, 0 through
  10094.     255), or equal to EOF; otherwise the behavior is undefined.  These
  10095.     functions are implemented both as macros and as functions.
  10096.  
  10097.     isalnum() tests for alphanumeric characters, that is, any
  10098.     character for which isalpha() or isdigit() is true.
  10099.  
  10100.     isalpha() tests for alphabetic characters, that is, any character
  10101.     for which islower() or isupper() is true.  For locales other than
  10102.     ■tt{"C"}, isalpha() may also return true for characters for which
  10103.     none of iscntrl(), isdigit(), ispunct() or isspace() is true.
  10104.  
  10105.     iscntrl() tests for control characters.  Control characters are
  10106.     not printing characters.
  10107.  
  10108.     isdigit() tests for decimal digits (■tt{'0'} through ■tt{'9'}).
  10109.  
  10110.     isgraph() tests for printing characters except space (■tt{' '}),
  10111.     that is, any character (except space) for which isprint() is true.
  10112.  
  10113.     islower() tests for lower-case characters, that is, ■tt{'a'}
  10114.     trough ■tt{'z'}.  For locales other than ■tt{"C"}, islower() may
  10115.     also return true for characters for which none of iscntrl(),
  10116.     isdigit(), ispunct() or isspace() is true.
  10117.  
  10118.     isprint() tests for printing characters including space (■tt{' '}).
  10119.     Printing characters are characters which occupy one printing
  10120.     position on a display device.
  10121.  
  10122.     ispunct() tests for punctutation characters, that is, printing
  10123.     characters for which isalnum() is false and which are not space
  10124.     (■tt{' '}).
  10125.  
  10126.     isspace() tests for white-space characters.  In locales other than
  10127.     ■tt{"C"}, isspace() may return true for characters for which
  10128.     isalnum() is false.
  10129.  
  10130.     isupper() tests for upper-case characters, that is, ■tt{'A'}
  10131.     trough ■tt{'Z'}.  For locales other than ■tt{"C"}, isupper() may
  10132.     also return true for characters for which none of iscntrl(),
  10133.     isdigit(), ispunct() or isspace() is true.
  10134.  
  10135.     isxdigit() tests for hexadecimal digits (■tt{'0'} through
  10136.     ■tt{'9'}, ■tt{'a'} through ■tt{'f'}, and ■tt{'A'} through
  10137.     ■tt{'F'}).
  10138.  
  10139. ■returnvalue
  10140.  
  10141.     These functions return a non-zero value if the condition is true,
  10142.     or 0 if it is not true.
  10143.  
  10144. ■restrictions
  10145.  
  10146.     Currently, locale is ignored.
  10147.  
  10148. ■seealso isascii() setlocale() tolower() toupper() _tolower() _toupper()
  10149.  
  10150.  
  10151. ■function isatty()
  10152. ■compat UNIX
  10153. ■headers
  10154. #include <io.h>
  10155. ■endheaders
  10156.  
  10157. ■param HANDLE
  10158. ■prototype
  10159. int isatty (int HANDLE);
  10160. ■endprototype
  10161.  
  10162.     Returns a non-zero value if HANDLE refers to a character device.
  10163.     Returns 0 if HANDLE does not refer to a character file (file or
  10164.     pipe).  If there is an error, errno is set and -1 is returned.
  10165.  
  10166. ■returnvalue
  10167.  
  10168.     See above.
  10169.  
  10170. ■seealso _isterm() ioctl()
  10171.  
  10172.  
  10173. ■function isfinite()
  10174. ■compat C9X
  10175. ■headers
  10176. #include <math.h>
  10177. ■endheaders
  10178.  
  10179. ■param X
  10180. ■prototype
  10181. int isfinite (float X);
  10182. int isfinite (double X);
  10183. int isfinite (long double X);
  10184. ■endprototype
  10185.  
  10186.     Determine whether X is finite (zero, subnormal, normal) or not
  10187.     (infinite, NaN).  The argument X must be of a floating-point type.
  10188.     Determination is based on the type of the argument.
  10189.  
  10190. ■returnvalue
  10191.  
  10192.     isfinite() returns a non-zero value if X is has a finite value;
  10193.     isfinite() returns 0 otherwise.
  10194.  
  10195. ■seealso fpclassify() isnan() isnormal() signbit()
  10196.  
  10197.  
  10198. ■function isnan()
  10199. ■compat C9X
  10200. ■headers
  10201. #include <math.h>
  10202. ■endheaders
  10203.  
  10204. ■param X
  10205. ■prototype
  10206. int isnan (float X);
  10207. int isnan (double X);
  10208. int isnan (long double X);
  10209. ■endprototype
  10210.  
  10211.     Determine whether X is a NaN.  The argument X must be of a
  10212.     floating-point type.  Determination is based on the type of the
  10213.     argument.
  10214.  
  10215. ■returnvalue
  10216.  
  10217.     isnan() returns a non-zero value if X has a NaN value; isnan()
  10218.     returns 0 otherwise.  
  10219.  
  10220. ■seealso fpclassify() isfinite() isnormal() signbit()
  10221.  
  10222.  
  10223. ■function isnormal()
  10224. ■compat C9X
  10225. ■headers
  10226. #include <math.h>
  10227. ■endheaders
  10228.  
  10229. ■param X
  10230. ■prototype
  10231. int isnormal (float X);
  10232. int isnormal (double X);
  10233. int isnormal (long double X);
  10234. ■endprototype
  10235.  
  10236.     Determine whether X is normal or not (zero, subnormal, infinite,
  10237.     NaN).  The argument X must be of a floating-point type.
  10238.     Determination is based on the type of the argument.
  10239.  
  10240. ■returnvalue
  10241.  
  10242.     isnormal() returns a non-zero value if X has a normal value;
  10243.     isnormal() returns 0 otherwise.
  10244.  
  10245. ■seealso fpclassify() isfinite() isnan() signbit()
  10246.  
  10247.  
  10248. ■function _isterm()
  10249. ■compat emx
  10250. ■headers
  10251. #include <io.h>
  10252. ■endheaders
  10253.  
  10254. ■param HANDLE
  10255. ■prototype
  10256. int _isterm (int HANDLE);
  10257. ■endprototype
  10258.  
  10259.     Returns a non-zero value if HANDLE refers to the standard input
  10260.     (keyboard) or standard output (screen) device.  Otherwise, returns
  10261.     0.  If there is an error, errno is set and 0 is returned.
  10262.  
  10263.     Consider using ■tt{ioctl (FGETHTYPE)} instead.
  10264.  
  10265. ■returnvalue
  10266.  
  10267.     See above.
  10268.  
  10269. ■seealso isatty() ioctl()
  10270.  
  10271.  
  10272. ■function _itoa() _ltoa() _ultoa()
  10273. ■compat PC
  10274. ■headers
  10275. #include <stdlib.h>
  10276. ■endheaders
  10277.  
  10278. ■param VALUE STRING RADIX
  10279. ■prototype
  10280. char *_itoa (int VALUE, char *STRING, int RADIX);
  10281. char *_ltoa (long VALUE, char *STRING, int RADIX);
  10282. char *_ultoa (unsigned long VALUE, char *STRING, int RADIX);
  10283. ■endprototype
  10284.  
  10285.     Convert the number VALUE to a string using the number base RADIX
  10286.     (between 2 and 36).  The string is stored to the array pointed to
  10287.     by STRING.
  10288.  
  10289. ■returnvalue
  10290.  
  10291.     _itoa(), _ltoa() and _ultoa() return STRING.
  10292.  
  10293. ■seealso atoi() _lltoa() sprintf() strtol()
  10294.  
  10295.  
  10296. ■function kill()
  10297. ■compat UNIX *
  10298. ■headers
  10299. #include <signal.h>
  10300. ■endheaders
  10301.  
  10302. ■param PID SIG
  10303. ■prototype
  10304. int kill (int PID, int SIG);
  10305. ■endprototype
  10306.  
  10307.     Send the signal SIG to process PID.  If PID is smaller than -1,
  10308.     the signal is sent to process -■pa{PID} and its children.
  10309.  
  10310.     If PID is the process ID of the process which is calling kill(),
  10311.     the signal is sent to the main thread (thread 1) of that process
  10312.     (unless the syscam call library is used).  Use raise() to generate
  10313.     a signal in the current thread.
  10314.  
  10315.     If SIG is 0, kill() checks only whether PID is valid or not.
  10316.  
  10317.     See section ■ref{signal processing} for details on
  10318.     ■hpt{signal processing}.
  10319.  
  10320. ■returnvalue
  10321.  
  10322.     If successful, kill() returns 0.  Otherwise kill() sets errno and
  10323.     returns -1.
  10324.  
  10325. ■errors
  10326. ■description
  10327. ■item EINVAL
  10328.     SIG is not a valid signal number
  10329. ■item ESRCH
  10330.     PID is not the process ID of a process or process PID is not a
  10331.     child process
  10332. ■enddescription
  10333.  
  10334. ■restrictions
  10335.  
  10336.     Only SIGKILL can be sent to arbitrary processes.
  10337.     Only SIGINT and SIGBREAK can be sent to arbitrary child processes.
  10338.     A process can send the other signals only to itself, see
  10339.     ■hpt{raise()}, or to other emx programs.
  10340.  
  10341.     Checking PID by passing 0 for SIG works for child processes only.
  10342.  
  10343.     Special treatment of ■pa{PID}=0, ■pa{PID}=1 and ■pa{PID}=-1 is not
  10344.     implemented.  Negative values of PID are implemented for OS/2 only
  10345.     and work only for direct children of the caller.
  10346.  
  10347.     When using the system call library sys.lib (■hpt{-Zsys}), a
  10348.     process can send arbitrary signals to itself, only SIGINT and
  10349.     SIGBREAK can be sent to only child processes, negative values of
  10350.     PID are not allowed.  Moreover, kill() cannot be used to send a
  10351.     signal to thread 1; the signal will be generated in the current
  10352.     thread.
  10353.  
  10354. ■seealso pause() raise() sigaction() signal()
  10355.  
  10356.  
  10357. ■function labs()
  10358. ■compat C90
  10359. ■headers
  10360. #include <stdlib.h>     /* use this */
  10361. #include <math.h>       /* or this */
  10362. ■endheaders
  10363.  
  10364. ■param N
  10365. ■prototype
  10366. long labs (long N);
  10367. ■endprototype
  10368.  
  10369.     Compute the absolute value of N.  In-line code is generated for
  10370.     this function.
  10371.  
  10372. ■returnvalue
  10373.  
  10374.     If N is negative, labs() returns -■pa{N}.  Otherwise, labs()
  10375.     returns N.
  10376.  
  10377. ■seealso abs() fabs()
  10378.  
  10379.  
  10380. ■function ldexp() ldexpl()
  10381. ■compat C90 C9X
  10382. ■headers
  10383. #include <math.h>
  10384. ■endheaders
  10385.  
  10386. ■param X EXP
  10387. ■prototype
  10388. double ldexp (double X, int EXP);
  10389. long double ldexpl (long double X, int EXP);
  10390. ■endprototype
  10391.  
  10392.     Compute and return X * 2 ^ EXP.  On overflow, NaN is returned and
  10393.     errno is set to ERANGE.
  10394.  
  10395.     ldexpl() uses the ■tt{long double} format.
  10396.  
  10397. ■returnvalue
  10398.  
  10399.     See above.
  10400.  
  10401. ■seealso frexp() pow()
  10402.  
  10403.  
  10404. ■function _lldiv() _uldiv() _ulldiv()
  10405. ■compat emx
  10406. ■headers
  10407. #include <stdlib.h>
  10408. ■endheaders
  10409.  
  10410. ■param NUM DEN
  10411. ■prototype
  10412. _lldiv_t _lldiv (long long NUM, long long DEN);
  10413. _uldiv_t _uldiv (unsigned long NUM, unsigned long DEN);
  10414. _ulldiv_t _ulldiv (unsigned long long NUM, unsigned long long DEN);
  10415. ■endprototype
  10416.  
  10417.     Perform an integer division, dividing NUM by DEN.  The quotient
  10418.     and the remainder are returned in the quot and rem fields,
  10419.     respectively.
  10420.  
  10421.     The following table shows the signs of quot and rem depending on
  10422.     the signs of NUM and DEN for _lldiv():
  10423.  
  10424. ■example
  10425. NUM DEN │ quot rem
  10426. ────────┼─────────
  10427.  +   +  │  +    +
  10428.  +   -  │  -    +
  10429.  -   +  │  -    -
  10430.  -   -  │  +    -
  10431. ■endexample
  10432.  
  10433.     ■bf{Note:} Do not use the -fpcc-struct-return option of GCC.
  10434.  
  10435. ■returnvalue
  10436.  
  10437.     _lldiv(), _uldiv() and _ulldiv() return a structure which contains
  10438.     the quotient and the remainder in the quot and rem fields,
  10439.     respectively.
  10440.  
  10441. ■seealso div() ldiv()
  10442.  
  10443.  
  10444. ■function _lltoa() _ulltoa()
  10445. ■compat emx
  10446. ■headers
  10447. #include <stdlib.h>
  10448. ■endheaders
  10449.  
  10450. ■param VALUE STRING RADIX
  10451. ■prototype
  10452. char *_lltoa (long long VALUE, char *STRING, int RADIX);
  10453. char *_ulltoa (unsigned long long VALUE, char *STRING, int RADIX);
  10454. ■endprototype
  10455.  
  10456.     Convert the number VALUE to a string using the number base RADIX
  10457.     (between 2 and 36).  The string is stored to the array pointed to
  10458.     by STRING.
  10459.  
  10460. ■returnvalue
  10461.  
  10462.     _lltoa() and _ulltoa() return STRING.
  10463.  
  10464. ■seealso atoi() _itoa() _strtoll() _strtoull()
  10465.  
  10466.  
  10467. ■function localeconv()
  10468. ■compat C90
  10469. ■headers
  10470. #include <locale.h>
  10471. ■endheaders
  10472.  
  10473. ■prototype
  10474. struct lconv *localeconv (void);
  10475. ■endprototype
  10476.  
  10477.     Return the address of a structure containing values for the
  10478.     formatting of umeric and monetary quantities according to the
  10479.     current locale.
  10480.  
  10481.     The structure is defined as follows:
  10482.  
  10483. ■example
  10484. struct lconv
  10485. {
  10486.   char *decimal_point;
  10487.   char *thousands_sep;
  10488.   char *grouping;
  10489.   char *int_curr_symbol;
  10490.   char *currency_symbol;
  10491.   char *mon_decimal_point;
  10492.   char *mon_thousands_sep;
  10493.   char *mon_grouping;
  10494.   char *positive_sign;
  10495.   char *negative_sign;
  10496.   char int_frac_digits;
  10497.   char frac_digits;
  10498.   char p_cs_precedes;
  10499.   char p_sep_by_space;
  10500.   char n_cs_precedes;
  10501.   char n_sep_by_space;
  10502.   char p_sign_posn;
  10503.   char n_sign_posn;
  10504. };
  10505. ■endexample
  10506.  
  10507.     If a string member points to ■tt{""}, the value is not available
  10508.     in the current locale or is of zero length.  Note that
  10509.     ■tt{decimal_point} never points to ■tt{""}.  The ■tt{char} members
  10510.     are non-negative numbers.  CHAR_MAX indicates that the value is
  10511.     not available in the current locale.
  10512.  
  10513.     The members have the following meaning:
  10514.  
  10515. ■list
  10516. ■item ■tt{decimal_point}
  10517.  
  10518.     The decimal point character used for formatting numbers (which are
  10519.     not monetary quantities).
  10520.  
  10521. ■item ■tt{thousands_sep}
  10522.  
  10523.     The character used for separating groups of digits before the
  10524.     decimal point in numbers (which are not monetary quantities).
  10525.  
  10526. ■item ■tt{grouping}
  10527.  
  10528.     An array containing the sizes of the groups of digits (right to
  10529.     left), terminated by zero (the previous size is to be used
  10530.     repeatedly for the remainder of the digits) or CHAR_MAX (no
  10531.     further grouping is to be performed).  This is used for numbers
  10532.     which are not monetary quantities.
  10533.  
  10534. ■item ■tt{int_curr_symbol}
  10535.  
  10536.     The first three characters contain the international currency
  10537.     symbol, the fourth character (which is the last one) is the
  10538.     character used for separating the international currency symbol
  10539.     from the monetary quantity.
  10540.  
  10541. ■item ■tt{currency_symbol}
  10542.  
  10543.     The local currency symbol.
  10544.  
  10545. ■item ■tt{mon_decimal_point}
  10546.  
  10547.     The decimal point character used for formatting monetary
  10548.     quantities.
  10549.  
  10550. ■item ■tt{mon_thousands_sep}
  10551.  
  10552.     The character used for separating groups of digits before the
  10553.     decimal point in monetary quantities.
  10554.  
  10555. ■item ■tt{mon_grouping}
  10556.  
  10557.     An array containing the sizes of the groups of digits (right to
  10558.     left), terminated by zero (the previous size is to be used
  10559.     repeatedly for the remainder of the digits) or CHAR_MAX (no
  10560.     further grouping is to be performed).  This is used for monetary
  10561.     quantities.
  10562.  
  10563. ■item ■tt{positive_sign}
  10564.  
  10565.     The string used for indicating that a monetary quantity is not
  10566.     negative (zero or positive).
  10567.  
  10568. ■item ■tt{negative_sign}
  10569.  
  10570.     The string used for indicating that a monetary quantity is negative.
  10571.  
  10572. ■item ■tt{int_frac_digits}
  10573.  
  10574.     The number of digits after the decimal point in monetary
  10575.     quantities (international format).
  10576.  
  10577. ■item ■tt{frac_digits}
  10578.  
  10579.     The number of digits after the decimal point in monetary
  10580.     quantities (local format).
  10581.  
  10582. ■item ■tt{p_cs_precedes}
  10583.  
  10584.     1 or 0 if ■tt{currency_symbol} respectively precedes or succeeds
  10585.     the monetary quantity if it is not negative (zero or positive).
  10586.  
  10587. ■item ■tt{p_sep_by_space}
  10588.  
  10589.     1 or 0 if a space respectively does or does not separate
  10590.     ■tt{currency_symbol} from a non-negative (zero or positive)
  10591.     monetary quantity.
  10592.  
  10593. ■item ■tt{n_cs_precedes}
  10594.  
  10595.     1 or 0 if ■tt{currency_symbol} respectively precedes or succeeds
  10596.     the monetary quantity if it is negative.
  10597.  
  10598. ■item ■tt{n_sep_by_space}
  10599.  
  10600.     1 or 0 if a space respectively does or does not separate
  10601.     ■tt{currency_symbol} from a negative monetary quantity.
  10602.  
  10603. ■item ■tt{p_sign_posn}
  10604.  
  10605.     A number indicating the position of ■tt{positive_sign} for a
  10606.     non-negative (zero or positive) monetary quantity:
  10607.  
  10608. ■description
  10609. ■item 0
  10610.     Parentheses surround the monetary quantity and ■tt{currency_symbol}.
  10611. ■item 1
  10612.     The sign string precedes the quantity and ■tt{currency_symbol}.
  10613. ■item 2
  10614.     The sign string succeeds the quantity and ■tt{currency_symbol}.
  10615. ■item 3
  10616.     The sign string immediately precedes ■tt{currency_symbol}.
  10617. ■item 4
  10618.     The sign string immediately succeeds ■tt{currency_symbol}.
  10619. ■enddescription
  10620.  
  10621. ■item ■tt{n_sign_posn}
  10622.  
  10623.     A number indicating the position of ■tt{positive_sign} for a
  10624.     negative monetary quantity.  See ■tt{p_sign_posn} for a
  10625.     description of the values.
  10626.  
  10627. ■endlist
  10628.  
  10629. ■returnvalue
  10630.  
  10631.     localeconv() returns a pointer to a statically allocated
  10632.     structure.  The contents of that structure can be changed by the
  10633.     next call to localeconv() or setlocale().  You must not write to
  10634.     the structure.
  10635.  
  10636. ■restrictions
  10637.  
  10638.     The contents of the structure are adjusted to use CHAR_MAX for the
  10639.     ■tt{char} type of the module calling localeconv().  When mixing
  10640.     modules with different ■tt{char} types, this will break.  When
  10641.     calling localeconv() in a library, CHAR_MAX of the library will be
  10642.     used instead of CHAR_MAX of the program using the library.
  10643.  
  10644.     When calling the function version of localeconv(), for instance by
  10645.     suppressing macro expansion, it is assumed that ■tt{char} is
  10646.     signed.
  10647.  
  10648. ■seealso setlocale()
  10649.  
  10650.  
  10651. ■function localtime()
  10652. ■compat C90
  10653. ■headers
  10654. #include <time.h>
  10655. ■endheaders
  10656.  
  10657. ■param T
  10658. ■prototype
  10659. struct tm *localtime (const time_t *T);
  10660. ■endprototype
  10661.  
  10662.     Convert the number of seconds elapsed since 00:00:00 1-Jan-1970
  10663.     Coordinated Universal Time (UTC, GMT) in the variable pointed to
  10664.     by T to a time and date structure for the local timezone and
  10665.     return a pointer to the structure.  gmtime(), mktime() and
  10666.     localtime() use the same memory location, therefore the values are
  10667.     overwritten if one of these functions is called.
  10668.  
  10669. ■returnvalue
  10670.  
  10671.     localtime() returns a pointer to a statically allocated
  10672.     structure.
  10673.  
  10674. ■seealso asctime() ctime() gmtime() mktime() time()
  10675.  
  10676.  
  10677. ■function log() log10() logl() log10l()
  10678. ■compat C90 C9X
  10679. ■headers
  10680. #include <math.h>
  10681. ■endheaders
  10682.  
  10683. ■param X
  10684. ■prototype
  10685. double log (double X);
  10686. double log10 (double X);
  10687.  
  10688. long double logl (long double X);
  10689. long double log10l (long double X);
  10690. ■endprototype
  10691.  
  10692.     log() returns the natural logarithm of X.  log10() returns the
  10693.     base-10 logarithm of X.
  10694.  
  10695.     If X is zero, -INF is returned and errno set to EDOM.
  10696.     If X is negative, a NaN is returned and errno set to EDOM.
  10697.  
  10698.     logl() and log10l() use the ■tt{long double} format.
  10699.  
  10700. ■returnvalue
  10701.  
  10702.     See above.
  10703.  
  10704. ■seealso exp() pow()
  10705.  
  10706.  
  10707. ■function longjmp()
  10708. ■compat C90
  10709. ■headers
  10710. #include <setjmp.h>
  10711. ■endheaders
  10712.  
  10713. ■param THERE N
  10714. ■prototype
  10715. void longjmp (jmp_buf THERE, int N);
  10716. ■endprototype
  10717.  
  10718.     Restore the context saved in THERE by setjmp().  longjmp() does a
  10719.     non-local ■tt{goto}, causing execution to continue at the setjmp()
  10720.     call which most recently saved a stack context in THERE.  setjmp()
  10721.     will return N.  If N is 0, setjmp() will return 1.  When calling
  10722.     longjmp() in a signal handler or in a function called by a signal
  10723.     handler (that is, while a signal handler is active), the signal
  10724.     handler will be unwound, that is, it is assumed that the signal
  10725.     handler doesn't return.  longjmp() must be called in the same
  10726.     thread as the most recent call to setjmp() for THERE.  Moreover,
  10727.     the function which most recently called setjmp() to save a stack
  10728.     context in THERE must still be active.  Don't expect local
  10729.     variables to be preserved unless declared volatile.
  10730.  
  10731.     As jmp_buf is an array type, the ■tt{&} operator need not be
  10732.     applied.
  10733.  
  10734. ■seealso setjmp() sigaction() siglongjmp() sigsetjmp() signal()
  10735.  
  10736.  
  10737. ■function _lrotl() _lrotr()
  10738. ■compat VAC++
  10739. ■headers
  10740. #include <sys/builtin.h>
  10741. ■endheaders
  10742.  
  10743. ■param VALUE SHIFT
  10744. ■prototype
  10745. unsigned long _lrotl (unsigned long VALUE, int SHIFT);
  10746. unsigned long _lrotr (unsigned long VALUE, int SHIFT);
  10747. ■endprototype
  10748.  
  10749.     _lrotl() returns VALUE (32 bits) rotated left by SHIFT bits.  If
  10750.     SHIFT is 1, bit 30 is returned as bit 31, bit 29 is returned as
  10751.     bit 30, and so on, bit 0 is returned as bit 1, and bit 31 is
  10752.     returned as bit 0.
  10753.  
  10754.     _lrotr() returns VALUE (32 bits) rotated right by SHIFT bits.  If
  10755.     SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
  10756.     1, and so on, bit 31 is returned as bit 30, and bit 0 is returned
  10757.     as bit 31.
  10758.  
  10759.     SHIFT should be 0 through 31.
  10760.  
  10761.     These functions are implemented as inline functions.
  10762.  
  10763. ■seealso _crotl() _crotr() _srotl() _srotr()
  10764.  
  10765.  
  10766. ■function lseek()
  10767. ■compat UNIX
  10768. ■headers
  10769. #include <io.h>
  10770. ■endheaders
  10771.  
  10772. ■param HANDLE OFFSET ORIGIN
  10773. ■prototype
  10774. long lseek (int HANDLE, long OFFSET, int ORIGIN);
  10775. ■endprototype
  10776.  
  10777.     lseek() moves the file pointer of HANDLE.  The new position OFFSET
  10778.     is relative to ORIGIN: If ORIGIN is SEEK_SET, OFFSET is relative
  10779.     to the beginning of the file, if ORIGIN is SEEK_CUR, OFFSET is
  10780.     relative to the current position, if ORIGIN is SEEK_END, OFFSET is
  10781.     relative to the end of the file.  The file pointer cannot be moved
  10782.     before the beginning of the file.  lseek() does not change the
  10783.     size of the file.
  10784.  
  10785. ■returnvalue
  10786.  
  10787.     lseek() returns the new position relative to the beginning of the
  10788.     file.  If there is an error, lseek() returns -1.
  10789.  
  10790. ■restrictions
  10791.  
  10792.     If the file pointer is set beyond the end of file, the data
  10793.     between the end of file and the new position is undefined (it
  10794.     should be read as zeros, but isn't).
  10795.  
  10796.     For text-mode files, OFFSET must be either zero (with ORIGIN equal
  10797.     to SEEK_SET, SEEK_CUR, or SEEK_END) or a value returned by a call
  10798.     to tell() on the same file (with ORIGIN equal to SEEK_SET).  For
  10799.     text-mode files ending with a Ctrl-Z, SEEK_END is not allowed.
  10800.  
  10801. ■seealso chsize() filelength() tell()
  10802.  
  10803.  
  10804. ■function main()
  10805. ■compat C90
  10806.  
  10807. ■param ARGC ARGV ENVP
  10808. ■prototype
  10809. int main (void);
  10810. int main (int ARGC, char *ARGV[]);
  10811. int main (int ARGC, char *ARGV[], char *ENVP[]);
  10812. ■endprototype
  10813.  
  10814.     This is the function called by the startup code to run your
  10815.     program.  It is not a library function.  ARGC is the number of
  10816.     command line arguments, including the program name.  ARGV points
  10817.     to an array of pointers to the command line arguments.  ENVP
  10818.     points to an array of pointers to the environment strings.  The
  10819.     last entry of each array is a NULL pointer.  main() should always
  10820.     return a value.  If main() returns, ■hpt{exit()} is called using
  10821.     the return value of main() as argument.  If main() ends without
  10822.     ■tt{return} statement and without calling exit(), the return code
  10823.     of the program is undefined.  This should be avoided.  After
  10824.     changing the environment with ■hpt{putenv()}, you should use the
  10825.     ■hpt{environ} global variable instead of the ENVP argument of
  10826.     main().
  10827.  
  10828. ■returnvalue
  10829.  
  10830.     The return value of main() will be the return code of the process.
  10831.  
  10832. ■seealso _envargs() environ _execname() exit() putenv() _response() _wildcard()
  10833.  
  10834.  
  10835. ■function _makepath()
  10836. ■compat PC
  10837. ■headers
  10838. #include <stdlib.h>
  10839. ■endheaders
  10840.  
  10841. ■param DST DRIVE DIR FNAME EXT
  10842. ■prototype
  10843. void _makepath (char *DST, const char *DRIVE, const char *DIR,
  10844.                 const char *FNAME, const char *EXT);
  10845. ■endprototype
  10846.  
  10847.     Build a path name from components and store it to the array
  10848.     pointed to by DST.  The array at DST should be of size _MAX_PATH.
  10849.     If DRIVE is not NULL and does not point to the empty string, the
  10850.     first character of the string (a drive name) pointed to by DRIVE
  10851.     followed by a colon is stored to the array pointed to by DST.  If
  10852.     DIR is not NULL and does not point to the empty string, the string
  10853.     (a directory name) pointed to by DIR is copied to DST.  If it does
  10854.     not end with \ or /, _makepath() appends a / character (or a \
  10855.     character if the string pointed to by DIR contains at least one
  10856.     backslash).  If FNAME is not NULL, the string pointed to by FNAME
  10857.     (a filename) is copied to DST.  If EXT is not NULL and does not
  10858.     point to the empty string, the string pointed to by EXT (an
  10859.     extension) is copied to DST.  If the string pointed to by EXT does
  10860.     not start with a ■tt{.}  character, _makepath() inserts a ■tt{.}
  10861.     in front of the string pointed to by EXT.  If the length of the
  10862.     resulting string (including the terminating null character)
  10863.     exceeds _MAX_PATH, the string is truncated to _MAX_PATH characters
  10864.     (including the terminating null character).
  10865.  
  10866.     _makepath() properly handles DBCS characters.
  10867.  
  10868. ■seealso _nls_init() _splitpath()
  10869.  
  10870. ■samplecode
  10871. char drive[_MAX_DRIVE], dir[_MAX_DIR];
  10872. char tmp[_MAX_PATH];
  10873. _splitpath (path, drive, dir, NULL, NULL);
  10874. _makepath (tmp, drive, dir, "tmpfile", "$$$");
  10875. ■endsamplecode
  10876.  
  10877.  
  10878. ■function malloc()
  10879. ■compat C90
  10880. ■headers
  10881. #include <stdlib.h>
  10882. ■endheaders
  10883.  
  10884. ■param SIZE
  10885. ■prototype
  10886. void *malloc (size_t SIZE);
  10887. ■endprototype
  10888.  
  10889.     Allocate a block of memory big enough for holding SIZE bytes.  If
  10890.     there is an error, malloc() returns NULL.  If SIZE is 0, zero
  10891.     bytes of memory are allocated, the return value will be unequal
  10892.     NULL.
  10893.  
  10894. ■returnvalue
  10895.  
  10896.     malloc() returns a pointer to a newly allocated block of memory.
  10897.     On error, malloc() returns NULL.
  10898.  
  10899. ■implementation
  10900.  
  10901.     malloc() allocates from the default heap of the current thread.
  10902.     ■tt{malloc(0)} returns a non-NULL pointer if there's enough space
  10903.     left in the heap for a block of the minimum size.
  10904.  
  10905. ■restrictions
  10906.  
  10907.     It's possible to replace the emx C library's malloc()
  10908.     implementation; for instance, you can use GNU malloc.  However, do
  10909.     not replace malloc() etc. when dynamically linking to the C
  10910.     runtime library as the functions in the DLL won't call your
  10911.     replacements.
  10912.  
  10913. ■seealso calloc() free() _msize() realloc() _tmalloc() _udefault() _umalloc()
  10914.  
  10915.  
  10916. ■function matherr()
  10917. ■compat SysV
  10918. ■headers
  10919. #include <math.h>
  10920. ■endheaders
  10921.  
  10922. ■param X
  10923. ■prototype
  10924. int matherr (struct exception *X);
  10925. ■endprototype
  10926.  
  10927.     Exception handler for floating point math.
  10928.  
  10929. ■returnvalue
  10930. ■description
  10931. ■item 0
  10932.     success
  10933. ■item non-0
  10934.     error
  10935. ■enddescription
  10936.  
  10937. ■restrictions
  10938.  
  10939.     matherr() is not implemented.
  10940.  
  10941. ■seealso sigaction() signal()
  10942.  
  10943.  
  10944. ■function mblen()
  10945. ■compat C90
  10946. ■headers
  10947. #include <stdlib.h>
  10948. ■endheaders
  10949.  
  10950. ■param S N
  10951. ■prototype
  10952. int mblen (const char *S, size_t N);
  10953. ■endprototype
  10954.  
  10955.     Compute the number of bytes comprising the multibyte character
  10956.     pointed to by S.  If S is NULL, the shift state is reset to the
  10957.     initial state.  At most N bytes at S are examined; a multibyte
  10958.     character consisting of more than N bytes is deemed invalid.
  10959.  
  10960.     Except for the different shift states, this is equivalent to
  10961.  
  10962. ■typewriter
  10963.   mbtowc (NULL, ■pa{S}, ■pa{N})
  10964. ■endtypewriter
  10965.  
  10966.     The shift state of mbtowc() is not affected.
  10967.  
  10968.     In programs linked with the multithread libraries, each thread has
  10969.     its own shift state for mblen().
  10970.  
  10971. ■returnvalue
  10972.  
  10973.     If S is NULL, mblen() returns a non-zero value (if state-dependent
  10974.     encoding is used) or a zero value (if state-dependent encoding is
  10975.     not used).  If S is not NULL, mblen() returns 0 (if S points to
  10976.     the null character), the number of bytes comprising the multibyte
  10977.     character pointed to by S (if there is a valid multibyte
  10978.     character), or -1 (if there is not a valid multibyte character).
  10979.  
  10980. ■seealso mbtowc() setlocale()
  10981.  
  10982.  
  10983. ■function mbstowcs()
  10984. ■compat C90
  10985. ■headers
  10986. #include <stdlib.h>
  10987. ■endheaders
  10988.  
  10989. ■param PWCS S N
  10990. ■prototype
  10991. size_t mbstowcs (wchar_t *PWCS, const char *S, size_t N);
  10992. ■endprototype
  10993.  
  10994.     Convert the null-terminated sequence of multibyte character
  10995.     pointed to by S to a sequence of wchar_t codes pointed to by PWCS.
  10996.     The multibyte character sequence starts in the initial shift
  10997.     state.  At most N codes are stored to PWCS.  PWCS will be
  10998.     terminated with a code of value zero if N is big enough.
  10999.  
  11000.     The shift state of mbtowc() and mblen() is not affected.
  11001.  
  11002. ■returnvalue
  11003.  
  11004.     mbstowcs() returns the number of codes stored to PWCS (excluding
  11005.     the terminating zero code) or ■tt{(size_t)-1} if an invalid
  11006.     multibyte character is encountered.
  11007.  
  11008. ■seealso mblen() mbtowc() setlocale() wcstombs()
  11009.  
  11010.  
  11011. ■function mbtowc()
  11012. ■compat C90
  11013. ■headers
  11014. #include <stdlib.h>
  11015. ■endheaders
  11016.  
  11017. ■param PWC S N
  11018. ■prototype
  11019. int mbtowc (wchar_t *PWC, const char *S, size_t N);
  11020. ■endprototype
  11021.  
  11022.     Convert the multibyte character pointed to by S to a wchar_t code
  11023.     and store it to PWC.  If S is NULL, the shift state is reset to
  11024.     the initial state.  At most N bytes at S are examined; a multibyte
  11025.     character consisting of more than N bytes is deemed invalid.
  11026.  
  11027.     The shift state of mblen() is not affected.
  11028.  
  11029.     In programs linked with the multithread libraries, each thread has
  11030.     its own shift state for mbtowc().
  11031.  
  11032. ■returnvalue
  11033.  
  11034.     If S is NULL, mbtowc() returns a non-zero value (if state-dependent
  11035.     encoding is used) or a zero value (if state-dependent encoding is
  11036.     not used).  If S is not NULL, mbtowc() returns 0 (if S points to
  11037.     the null character), the number of bytes comprising the multibyte
  11038.     character pointed to by S (if there is a valid multibyte
  11039.     character), or -1 (if there is not a valid multibyte character).
  11040.  
  11041. ■seealso mblen() mbstowcs() setlocale() wctomb()
  11042.  
  11043.  
  11044. ■function _md_close()
  11045. ■compat emx
  11046. ■headers
  11047. #include <stdio.h>
  11048. #include <sys/moddef.h>
  11049. ■endheaders
  11050.  
  11051. ■param MD
  11052. ■prototype
  11053. int _md_close (struct _md *MD);
  11054. ■endprototype
  11055.  
  11056.   Destroy the descriptor MD.  MD must have been returned by _md_open()
  11057.   or _md_use_file().  If MD has been returned by _md_open(), the file
  11058.   will be closed.  If MD has been returned by _md_use_file(), the file
  11059.   won't be closed.  _md_close() frees the memory associated with MD.
  11060.   Do not use MD after calling _md_close().
  11061.  
  11062.   You have to link with the moddef library (use the -lmoddef option).
  11063.  
  11064. ■returnvalue
  11065. ■description
  11066. ■item 0
  11067.     success
  11068. ■item -1
  11069.     error
  11070. ■enddescription
  11071.  
  11072. ■seealso _md_open() _md_use_file()
  11073.  
  11074.  
  11075. ■function _md_errmsg()
  11076. ■compat emx
  11077. ■headers
  11078. #include <stdio.h>
  11079. #include <sys/moddef.h>
  11080. ■endheaders
  11081.  
  11082. ■param CODE
  11083. ■prototype
  11084. const char *_md_errmsg (_md_error CODE);
  11085. ■endprototype
  11086.  
  11087.   Return a pointer to the default error message for the error code
  11088.   CODE.  This function can be used in the callback function of
  11089.   _md_parse().
  11090.  
  11091.   You have to link with the moddef library (use the -lmoddef option).
  11092.  
  11093. ■seealso _md_parse()
  11094.  
  11095.  
  11096. ■function _md_get_linenumber() _md_get_number() _md_get_string() _md_get_token()
  11097. ■compat emx
  11098. ■headers
  11099. #include <stdio.h>
  11100. #include <sys/moddef.h>
  11101. ■endheaders
  11102.  
  11103. ■param MD
  11104. ■prototype
  11105. _md_token _md_get_token (struct _md *MD);
  11106. long _md_get_number (const struct _md *MD);
  11107. const char *_md_get_string (const struct _md *MD);
  11108. long _md_get_linenumber (const struct _md *MD);
  11109. ■endprototype
  11110.  
  11111.   Retrieve information about the current token of MD (the token most
  11112.   recently read by ■tt{_md_next_token (md)}).
  11113.  
  11114.   _md_get_token() returns the token identifier (see
  11115.   ■hpt{_md_next_token()} for details).  If _md_get_token() has not
  11116.   been called for MD, _MD_eof is returned.
  11117.  
  11118.   If the current token is a number, _md_get_number() returns the value
  11119.   of the number.  Otherwise, _md_get_number() returns 0.
  11120.  
  11121.   _md_get_string() returns the string value of the current token.  The
  11122.   string value consists of all the characters that are part of the
  11123.   token.
  11124.  
  11125.   _md_get_linenumber() returns the number of the line from
  11126.   which the token has been read.  The first line is numbered 1.
  11127.  
  11128.   You have to link with the moddef library (use the -lmoddef option).
  11129.  
  11130. ■seealso _md_next_token()
  11131.  
  11132.  
  11133. ■function _md_next_token()
  11134. ■compat emx
  11135. ■headers
  11136. #include <stdio.h>
  11137. #include <sys/moddef.h>
  11138. ■endheaders
  11139.  
  11140. ■param MD
  11141. ■prototype
  11142. _md_token _md_next_token (struct _md *MD);
  11143. ■endprototype
  11144.  
  11145.   Read the next token from the module definition file MD and return
  11146.   the token identifier.  See <sys/moddef.h> for token identifiers.  Most
  11147.   token identifiers identify a keyword.  For instance, _MD_NAME
  11148.   is returned for the NAME keyword.  The following special token
  11149.   identfiers are defined:
  11150.  
  11151. ■list
  11152. ■item _MD_dot
  11153.  
  11154.   The character `■tt{.}'.
  11155.  
  11156. ■item _MD_at
  11157.  
  11158.   The character `■tt{@}'.
  11159.  
  11160. ■item _MD_equal
  11161.  
  11162.   The character `■tt{=}'.
  11163.  
  11164. ■item _MD_number
  11165.  
  11166.   A number.  Use _md_get_number() to retrieve the value.
  11167.  
  11168. ■item _MD_word
  11169.  
  11170.   A word which isn't a keyword.  Use _md_get_string() to retrieve the
  11171.   value.
  11172.  
  11173. ■item _MD_quote
  11174.  
  11175.   A quoted string. _md_get_string() to retrieve the value.
  11176.  
  11177. ■item _MD_eof
  11178.  
  11179.   The end of the file has been reached.
  11180.  
  11181. ■item _MD_ioerror
  11182.  
  11183.   An I/O error occured while reading from the file (fatal error).
  11184.  
  11185. ■item _MD_missingquote
  11186.  
  11187.   A quote character is missing (fatal error).  Quote characters must
  11188.   come in pairs.
  11189.  
  11190. ■endlist
  11191.  
  11192.   After calling _md_next_token(), you can retrieve the token
  11193.   identifier, numeric value, string value and line number of the
  11194.   current token by calling _md_get_token(), _md_get_number(),
  11195.   _md_get_string() and _md_get_linenumber(), respectively.
  11196.  
  11197.   You have to link with the moddef library (use the -lmoddef option).
  11198.  
  11199. ■seealso _md_get_linenumber() _md_get_number() _md_get_string() _md_get_token() _md_open() _md_parse() _md_use_file()
  11200.  
  11201.  
  11202. ■function _md_open()
  11203. ■compat emx
  11204. ■headers
  11205. #include <stdio.h>
  11206. #include <sys/moddef.h>
  11207. ■endheaders
  11208.  
  11209. ■param FNAME
  11210. ■prototype
  11211. struct _md *_md_open (const char *FNAME);
  11212. ■endprototype
  11213.  
  11214.   Create a descriptor for reading module definition statements from
  11215.   the file whose name is in the string pointed to by FNAME.  The file
  11216.   is opened in SH_DENYWR mode.  On error (file cannot be opened or out
  11217.   of memory), _md_open() sets errno and returns NULL.  Otherwise, a
  11218.   descriptor is returned which can be passed to _md_next_token() or
  11219.   _md_parse() to parse the file.  Call _md_close() to close the file
  11220.   and to destroy the descriptor.
  11221.  
  11222.   You have to link with the moddef library (use the -lmoddef option).
  11223.  
  11224. ■seealso _md_next_token() _md_parse() _md_use_file()
  11225.  
  11226.  
  11227. ■function _md_parse()
  11228. ■compat emx
  11229. ■headers
  11230. #include <stdio.h>
  11231. #include <sys/moddef.h>
  11232. ■endheaders
  11233.  
  11234. ■param MD CALLBACK ARG STMT TOKEN
  11235. ■prototype
  11236. int _md_parse (struct _md *MD,
  11237.                int (*CALLBACK)(struct _md *MD, const _md_stmt *STMT,
  11238.                                _md_token TOKEN, void *ARG),
  11239.                void *ARG);
  11240. ■endprototype
  11241.  
  11242.   Parse the module definition file MD, calling CALLBACK for each
  11243.   statement.  The token identifier of the statement is passed in TOKEN
  11244.   to CALLBACK.  Information about the statement is passed in STMT.
  11245.   Moreover, CALLBACK receives ■tt{_md_parse()}'s MD and ARG arguments.
  11246.   ARG can be used to pass additional user data to CALLBACK.
  11247.  
  11248.   CALLBACK is also called if an error is encountered.  In that case,
  11249.   TOKEN has the special value _MD_parseerror.
  11250.  
  11251.   _md_parse() starts parsing at the current token, that is,
  11252.   _md_next_token() has to be called before invoking _md_parse().
  11253.   _md_parse() stops parsing when reaching the end of the file or when
  11254.   CALLBACK returns a non-zero value.  In the latter case, _md_parse()
  11255.   returns the value returned by CALLBACK.  In all other cases,
  11256.   _md_parse() returns 0.
  11257.  
  11258.   The following values of TOKEN can be passed to CALLBACK:
  11259.  
  11260. ■list
  11261.  
  11262. ■item _MD_BASE
  11263.  
  11264.   BASE statement.  The base address is available in STMT■tt{->base.addr}.
  11265.  
  11266. ■item _MD_CODE
  11267.  
  11268.   CODE statement.  The segment attributes are available in
  11269.   STMT■tt{->segment.attr}, using a combination of constants like
  11270.   _MDS_IOPL.
  11271.  
  11272. ■item _MD_DATA
  11273.  
  11274.   DATA statement.  The segment attributes are available in
  11275.   STMT■tt{->segment.attr}, using a combination of constants like
  11276.   _MDS_MULTIPLE.
  11277.  
  11278. ■item _MD_DESCRIPTION
  11279.  
  11280.   DESCRIPTION statement.  The description string is available in
  11281.   STMT■tt{->descr.string}.
  11282.  
  11283. ■item _MD_EXETYPE
  11284.  
  11285.   EXETYPE statement.  The executable type is available in
  11286.   STMT■tt{->exetype.type} using a constant like _MDX_OS2.  For
  11287.   _MDX_WINDOWS, the minor and major version numbers are available in
  11288.   STMT■tt{->exetype.minor_version} and STMT■tt{->exetype.major_version},
  11289.   respectively.  If the version numbers are not specified or if the
  11290.   executable type is not WINDOWS, these fields are 0.
  11291.  
  11292. ■item _MD_EXPORTS
  11293.  
  11294.   One export entry of an EXPORTS statement.  Information about the
  11295.   export entry is available in STMT■tt{->export}:
  11296.  
  11297. ■list
  11298. ■item ■tt{flags}
  11299.  
  11300.   If an ordinal number is present, _MDEP_ORDINAL is set.  If the
  11301.   NONAME keyword is present, _MDEP_NONAME is set.  If the RESIDENTNAME
  11302.   keyword is present, _MDEP_RESIDENTNAME is set.  If the NODATA
  11303.   keyword is present, _MDEP_NODATA is set.  If the number of parameter
  11304.   words is present, _MDEP_PWORDS is set.
  11305.  
  11306. ■item ■tt{internalname}
  11307.  
  11308.   The internal name of the entry point.  If no internal name is
  11309.   specified, the string is empty.
  11310.  
  11311. ■item ■tt{entryname}
  11312.  
  11313.   The external name of the entry point.
  11314.  
  11315. ■item ■tt{ordinal}
  11316.  
  11317.   The ordinal number, if ■tt{flags} contains _MDEP_ORDINAL.
  11318.   Otherwise, this field is 0.
  11319.  
  11320. ■item ■tt{pwords}
  11321.  
  11322.   The number of parameter words, if ■tt{flags} contains _MDEP_PWORDS.
  11323.   Otherwise, this field is 0.
  11324.  
  11325. ■endlist
  11326.  
  11327. ■item _MD_HEAPSIZE
  11328.  
  11329.   HEAPSIZE statement.  If a heap size is specified, the heap size is
  11330.   available in STMT■tt{->heapsize.size} and STMT■tt{->heapsize.maxval}
  11331.   is 0.  If MAXVAL is specified, STMT■tt{->heapsize.maxval} is
  11332.   non-zero and STMT■tt{->heapsize.size} is 0.
  11333.  
  11334. ■item _MD_IMPORTS
  11335.  
  11336.   One import entry of an IMPORTS statement.  Information about the
  11337.   import entry is available in STMT■tt{->import}:
  11338.  
  11339. ■list
  11340.  
  11341. ■item ■tt{flags}
  11342.  
  11343.   If an ordinal number is present, _MDIP_ORDINAL is set.
  11344.  
  11345. ■item ■tt{internalname}
  11346.  
  11347.   The internal name of the entry point.  If no internal name is
  11348.   specified, the string is empty.
  11349.  
  11350. ■item ■tt{entryname}
  11351.  
  11352.   The external name of the entry point.  If no external name is
  11353.   specified (that is, if _MDIP_ORDINAL is set), the string is empty.
  11354.  
  11355. ■item ■tt{modulename}
  11356.  
  11357.   The name of the dynamic link library.
  11358.  
  11359. ■item ■tt{ordinal}
  11360.  
  11361.   The ordinal number, if ■tt{flags} contains _MDIP_ORDINAL.
  11362.   Otherwise, this field is 0.
  11363.  
  11364. ■endlist
  11365.  
  11366. ■item _MD_LIBRARY
  11367.  
  11368.   LIBRARY statement.  The name is available in
  11369.   STMT■tt{->library.name}.  The library initialization and termination
  11370.   modes are available in STMT■tt{->library.init} and
  11371.   STMT■tt{->library.term}, respectively.  These fields are set to
  11372.   _MDIT_DEFAULT if no modes are specified.  Otherwise, _MDIT_INSTANCE
  11373.   or _MDIT_GLOBAL is used.
  11374.  
  11375. ■item _MD_NAME
  11376.  
  11377.   NAME statement.  The name is available in STMT■tt{->name.name}.  The
  11378.   application type is available in STMT■tt{->name.pmtype}.  That field
  11379.   is set to _MDT_DEFAULT (if no type is specified), _MDT_WINDOWAPI,
  11380.   _MDT_WINDOWCOMPAT or _MDT_NOTWINDOWCOMPAT.  If NEWFILES is
  11381.   specified, the STMT■tt{->name.newfiles} field is non-zero.
  11382.  
  11383. ■item _MD_OLD
  11384.  
  11385.   OLD statement.  The file name is available in
  11386.   STMT■tt{->old.name}.
  11387.   
  11388. ■item _MD_PHYSICAL
  11389.  
  11390.   PHYSICAL DEVICE statement.  The name is available in
  11391.   STMT■tt{->device.name}.
  11392.  
  11393. ■item _MD_PROTMODE
  11394.  
  11395.   PROTMODE statement.  No additional information is available.
  11396.  
  11397. ■item _MD_REALMODE
  11398.  
  11399.   REALMODE statement.  No additional information is available.
  11400.  
  11401. ■item _MD_SEGMENTS
  11402.  
  11403.   One segment definition of a SEGMENTS statement.  The segment
  11404.   attributes are available in STMT■tt{->segment.attr}, using a
  11405.   combination of constants like _MDS_SHARED.  The segment name is
  11406.   available in STMT■tt{->segment.segname}.  The class name is
  11407.   available in STMT■tt{->segment.classname}.  If no class name is
  11408.   specified, that string is empty.
  11409.  
  11410. ■item _MD_STACKSIZE
  11411.  
  11412.   STACKSIZE statement.  The stack size is available in
  11413.   STMT■tt{->stacksize.size}.
  11414.  
  11415. ■item _MD_STUB
  11416.  
  11417.   STUB statement.  The file name is available in STMT■tt{->stub.name}.
  11418.   If the NONE keyword is used, STMT■tt{->stub.none} is none-zero and
  11419.   the string is empty.
  11420.  
  11421. ■item _MD_VIRTUAL
  11422.  
  11423.   VIRTUAL DEVICE statement.  The name is available in
  11424.   STMT■tt{->device.name}.
  11425.  
  11426. ■item _MD_parseerror
  11427.  
  11428.   _md_parse() has detected an error.  The token identifier of the
  11429.   current statement is available in STMT■tt{->error.stmt}.  An error
  11430.   code is available in STMT■tt{->error.code}.  The following error
  11431.   codes are defined:
  11432.  
  11433. ■list
  11434. ■item _MDE_IO_ERROR
  11435.  
  11436.   _md_next_token() returned _MD_ioerror because an I/O error
  11437.   occured while reading from the file.
  11438.  
  11439. ■item _MDE_MISSING_QUOTE
  11440.  
  11441.   _md_next_token() returned _MD_missingquote because a quote
  11442.   character is missing.  Quote characters must come in pairs.
  11443.  
  11444. ■item _MDE_EMPTY
  11445.  
  11446.   The module definition file is empty, there are no statements.  This
  11447.   error also occurs if _md_next_token() wasn't called before
  11448.   calling _md_parse().
  11449.  
  11450. ■item _MDE_NAME_EXPECTED
  11451.  
  11452.   A name (segment name, class name, entry name) was expected, but a
  11453.   different token was read.
  11454.  
  11455. ■item _MDE_STRING_EXPECTED
  11456.  
  11457.   A quoted string was expected, but a different token was read.
  11458.  
  11459. ■item _MDE_NUMBER_EXPECTED
  11460.  
  11461.   A number was expected, but a different token was read.
  11462.  
  11463. ■item _MDE_DEVICE_EXPECTED
  11464.  
  11465.   The VIRTUAL or PHYSICAL keyword isn't followed by the DEVICE
  11466.   keyword.
  11467.  
  11468. ■item _MDE_EQUAL_EXPECTED
  11469.  
  11470.   An `■tt{=}' character was expected, but a different token was read.
  11471.  
  11472. ■item _MDE_DOT_EXPECTED
  11473.  
  11474.   A `■tt{.}' character was expected, but a different token was read.
  11475.  
  11476. ■item _MDE_STRING_TOO_LONG
  11477.  
  11478.   A string is too long.
  11479.  
  11480. ■item _MDE_INVALID_ORDINAL
  11481.  
  11482.   An ordinal number is invalid.  Valid ordinal numbers are in 1
  11483.   through 65535.
  11484.  
  11485. ■item _MDE_INVALID_STMT
  11486.  
  11487.   An invalid keyword (which doesn't start a statement) was read.
  11488.  
  11489. ■endlist
  11490.  
  11491.   You can use ■hpt{_md_errmsg()} to get a default error message for
  11492.   the error code.
  11493.  
  11494.   If CALLBACK returns 0, _md_parse() skips tokens until finding a
  11495.   keyword which starts a statement or until hitting end of file.  If
  11496.   CALLBACK returns a non-zero number, that number will be immediately
  11497.   returned by _md_parse().
  11498.  
  11499. ■endlist
  11500.  
  11501.   You have to link with the moddef library (use the -lmoddef option).
  11502.  
  11503. ■seealso _md_errmsg() _md_next_token() _md_open() _md_use_file()
  11504.  
  11505. ■samplefile /emx/test/mdecho.c
  11506.  
  11507.  
  11508. ■function _md_use_file()
  11509. ■compat emx
  11510. ■headers
  11511. #include <stdio.h>
  11512. #include <sys/moddef.h>
  11513. ■endheaders
  11514.  
  11515. ■param F
  11516. ■prototype
  11517. struct _md *_md_use_file (FILE *F);
  11518. ■endprototype
  11519.  
  11520.   Create a descriptor for reading module definition statements from
  11521.   the file F.  On error (out of memory), _md_use_file() sets errno and
  11522.   returns NULL.  Otherwise, a descriptor is returned which can be
  11523.   passed to _md_next_token() or _md_parse() to parse the file.  Don't
  11524.   close F before calling _md_close().  Call _md_close() to destroy the
  11525.   descriptor.
  11526.  
  11527.   You have to link with the moddef library (use the -lmoddef option).
  11528.  
  11529. ■seealso _md_close() _md_next_token() _md_open()
  11530.  
  11531.  
  11532. ■function _memaccess()
  11533. ■compat emx
  11534. ■headers
  11535. #include <sys/hw.h>
  11536. ■endheaders
  11537.  
  11538. ■param FIRST LAST FLAG
  11539. ■prototype
  11540. void *_memaccess (unsigned FIRST, unsigned LAST, int FLAG);
  11541. ■endprototype
  11542.  
  11543.     Gain access to physical memory under DOS.  To access memory which
  11544.     is outside the memory space of the current process, you have to
  11545.     call _memaccess().  emx option -am must be used to enable
  11546.     _memaccess(), see `■hpt{Using emx options}'.
  11547.  
  11548.     FIRST is the address of the first byte of the physical memory
  11549.     area, LAST is the address of the last byte of the physical memory
  11550.     area to be accessed.  Both addresses are physical addresses.
  11551.     FIRST and ■pa{LAST}+1 must be page aligned: FIRST and ■pa{LAST}+1
  11552.     must be integral multiples of 4096.  That is, with using
  11553.     hexadecimal notation, FIRST must end with 000, LAST must end with
  11554.     fff.  If FLAG is 0, read access is granted.  If FLAG is 1, read
  11555.     and write access is granted.  Write access can be granted if the
  11556.     address range of the physical memory area is entirely in the range
  11557.     0xa0000 to 0xbffff.  If bytes outside this range are included in
  11558.     FIRST to LAST, emx option -aw must be used to enable write access,
  11559.     see `■hpt{Using emx options}'.
  11560.  
  11561. ■returnvalue
  11562.  
  11563.     _memaccess() returns a pointer to virtual memory mapped to the
  11564.     physical memory area.  On failure, _memaccess() sets errno and
  11565.     returns NULL.
  11566.  
  11567. ■errors
  11568.  
  11569. ■description
  11570. ■item EACCES
  11571.  
  11572.     FIRST not page aligned; ■pa{LAST}+1 not page aligned; LAST not
  11573.     greater than FIRST; write access not allowed
  11574.  
  11575. ■item EINVAL
  11576.  
  11577.     FLAG is not 0 or 1
  11578.  
  11579. ■item ENOMEM
  11580.  
  11581.     not enough virtual memory for storing the paging tables; linear
  11582.     address space of process not big enough for the request
  11583.  
  11584. ■enddescription
  11585.  
  11586. ■restrictions
  11587.  
  11588.     _memaccess() is not available under OS/2.  Obtaining access to
  11589.     memory by linear address is not yet supported.
  11590.  
  11591. ■seealso _portaccess()
  11592.  
  11593. ■samplefile /emx/test/hw_mem.c
  11594.  
  11595.  
  11596. ■function memccpy()
  11597. ■compat PC
  11598. ■headers
  11599. #include <string.h>     /* use this */
  11600. #include <memory.h>     /* or this */
  11601. ■endheaders
  11602.  
  11603. ■param S1 S2 C N
  11604. ■prototype
  11605. void *memccpy (void *S1, const void *S2, int C, size_t N);
  11606. ■endprototype
  11607.  
  11608.     Copy at most the first N bytes from S2 to S1, stopping after
  11609.     copying a byte equal to the lower 8 bits C.  If memccpy() stops
  11610.     because a byte equal to C has been found, a pointer to the byte
  11611.     after the last destination byte (which is equal to C) is returned.
  11612.     If N bytes have been copied without finding a byte equal to C,
  11613.     NULL is returned.
  11614.  
  11615. ■returnvalue
  11616.  
  11617.     See above.
  11618.  
  11619. ■seealso memchr() memcpy() memmove() strcpy() strncpy()
  11620.  
  11621.  
  11622. ■function memchr()
  11623. ■compat C90
  11624. ■headers
  11625. #include <string.h>     /* use this */
  11626. #include <memory.h>     /* or this */
  11627. ■endheaders
  11628.  
  11629. ■param S C N
  11630. ■prototype
  11631. void *memchr (const void *S, int C, size_t N);
  11632. ■endprototype
  11633.  
  11634.     Search the first N bytes at S for a byte equal to the lower 8 bits
  11635.     of C.  If a byte equal to C is found, a pointer to the first
  11636.     occurrence of C is returned.  If there is no such byte, NULL is
  11637.     returned.
  11638.  
  11639. ■returnvalue
  11640.  
  11641.     See above.
  11642.  
  11643. ■seealso _memrchr() strchr()
  11644.  
  11645.  
  11646. ■function memcmp()
  11647. ■compat C90
  11648.  
  11649. ■headers
  11650. #include <string.h>     /* use this */
  11651. #include <memory.h>     /* or this */
  11652. ■endheaders
  11653.  
  11654. ■param S1 S2 N
  11655. ■prototype
  11656. int memcmp (const void *S1, const void *S2, size_t N);
  11657. ■endprototype
  11658.  
  11659.     Compare the first N bytes at S1 to the first N bytes at S2.  If
  11660.     the two buffers are identical (or if N is zero), 0 is returned.
  11661.     Otherwise, a value is returned which indicates the relationship of
  11662.     the first differing byte: a negative value means buffer S1 is
  11663.     lexically less than buffer S2, a positive value means buffer S1 is
  11664.     lexically greater than buffer S2.
  11665.  
  11666. ■returnvalue
  11667. ■description
  11668. ■item <0
  11669.    S1 < S2
  11670. ■item =0
  11671.    S1 = S2
  11672. ■item >0
  11673.    S1 > S2
  11674. ■enddescription
  11675.  
  11676. ■seealso bcmp() _memdif() memicmp()
  11677.  
  11678.  
  11679. ■function _memcount()
  11680. ■compat emx
  11681.  
  11682. ■headers
  11683. #include <string.h>     /* use this */
  11684. #include <memory.h>     /* or this */
  11685. ■endheaders
  11686.  
  11687. ■param MEM C N
  11688. ■prototype
  11689. size_t _memcount (const void *MEM, int C, size_t N);
  11690. ■endprototype
  11691.  
  11692.     Count and return the number of occurrences of character C in the
  11693.     memory area of size N bytes pointed to by MEM.
  11694.  
  11695. ■returnvalue
  11696.  
  11697.     See above.
  11698.  
  11699.  
  11700. ■function memcpy()
  11701. ■compat C90
  11702.  
  11703. ■headers
  11704. #include <string.h>     /* use this */
  11705. #include <memory.h>     /* or this */
  11706. ■endheaders
  11707.  
  11708. ■param S1 S2 N
  11709. ■prototype
  11710. void *memcpy (void *S1, const void *S2, size_t N);
  11711. ■endprototype
  11712.  
  11713.     Copy memory.  Copy N bytes from S2 to S1.  The two regions must
  11714.     not overlap.  GCC generates in-line code for special applications
  11715.     of memcpy().  Use memmove() instead of memcpy() to copy
  11716.     overlapping regions of memory.
  11717.  
  11718. ■returnvalue
  11719.  
  11720.     memcpy() returns S1.
  11721.  
  11722. ■seealso bcopy() memmove()
  11723.  
  11724.  
  11725. ■function _memdif()
  11726. ■compat emx
  11727.  
  11728. ■headers
  11729. #include <string.h>     /* use this */
  11730. #include <memory.h>     /* or this */
  11731. ■endheaders
  11732.  
  11733. ■param MEM1 MEM2 N
  11734. ■prototype
  11735. size_t _memdif (const void *MEM1, const void *MEM2, size_t N);
  11736. ■endprototype
  11737.  
  11738.     Compare the first N bytes pointed to by MEM1 to the first N bytes
  11739.     pointed to by MEM2.  If the two buffers are identical (or if N is
  11740.     zero), _MEMDIF_EQ is returned.  Otherwise, the byte offset of the
  11741.     first difference is returned.
  11742.  
  11743. ■returnvalue
  11744.  
  11745.     See above.
  11746.  
  11747. ■seealso memcmp()
  11748.  
  11749.  
  11750. ■function memicmp()
  11751. ■compat PC
  11752.  
  11753. ■headers
  11754. #include <string.h>     /* use this */
  11755. #include <memory.h>     /* or this */
  11756. ■endheaders
  11757.  
  11758. ■param S1 S2 N
  11759. ■prototype
  11760. int memicmp (const void *S1, const void *S2, size_t N);
  11761. ■endprototype
  11762.  
  11763.     Compare the first N bytes at S1 to the first N bytes at S2,
  11764.     ignoring letter case.  If the two buffers are identical (or if N
  11765.     is zero), 0 is returned.  Otherwise, a value is returned which
  11766.     indicates the relationship of the first differing byte: a negative
  11767.     value means buffer S1 is lexically less than buffer S2 (after
  11768.     conversion to lower case), a positive value means buffer S1 is
  11769.     lexically greater than buffer S2 (after conversion to lower case).
  11770.  
  11771. ■returnvalue
  11772. ■description
  11773. ■item <0
  11774.    S1 < S2
  11775. ■item =0
  11776.    S1 = S2
  11777. ■item >0
  11778.    S1 > S2
  11779. ■enddescription
  11780.  
  11781. ■seealso memcmp() tolower()
  11782.  
  11783.  
  11784. ■function memmove()
  11785. ■compat C90
  11786.  
  11787. ■headers
  11788. #include <string.h>     /* use this */
  11789. #include <memory.h>     /* or this */
  11790. ■endheaders
  11791.  
  11792. ■param S1 S2 N
  11793. ■prototype
  11794. void *memmove (void *S1, const void *S2, size_t N);
  11795. ■endprototype
  11796.  
  11797.     Copy memory.  Copy N bytes from S2 to S1.  The two regions may
  11798.     overlap.
  11799.  
  11800. ■returnvalue
  11801.  
  11802.     memmove() returns S1.
  11803.  
  11804. ■seealso bcopy() memcpy()
  11805.  
  11806.  
  11807. ■function _memrchr()
  11808. ■compat emx
  11809. ■headers
  11810. #include <string.h>     /* use this */
  11811. #include <memory.h>     /* or this */
  11812. ■endheaders
  11813.  
  11814. ■param S C N
  11815. ■prototype
  11816. void *_memrchr (const void *S, int C, size_t N);
  11817. ■endprototype
  11818.  
  11819.     Search the first N bytes at S for a byte equal to the lower 8 bits
  11820.     of C.  If a byte equal to C is found, a pointer to the last
  11821.     occurrence of C is returned.  If there is no such byte, NULL is
  11822.     returned.
  11823.  
  11824. ■returnvalue
  11825.  
  11826.     See above.
  11827.  
  11828. ■seealso memchr() strrchr()
  11829.  
  11830.  
  11831. ■function memset()
  11832. ■compat C90
  11833.  
  11834. ■headers
  11835. #include <string.h>     /* use this */
  11836. #include <memory.h>     /* or this */
  11837. ■endheaders
  11838.  
  11839. ■param S C N
  11840. ■prototype
  11841. void *memset (void *S, int C, size_t N);
  11842. ■endprototype
  11843.  
  11844.     Fill memory.  Set N bytes at S to C.
  11845.  
  11846. ■returnvalue
  11847.  
  11848.     memset() returns S.
  11849.  
  11850. ■seealso bzero()
  11851.  
  11852.  
  11853. ■function _memswap()
  11854. ■compat emx
  11855.  
  11856. ■headers
  11857. #include <string.h>     /* use this */
  11858. #include <memory.h>     /* or this */
  11859. ■endheaders
  11860.  
  11861. ■param S1 S2 N
  11862. ■prototype
  11863. void _memswap (void *S1, void *S2, size_t N);
  11864. ■endprototype
  11865.  
  11866.     Swap two areas of memory of N bytes each, pointed to by S1 and S2.
  11867.     The two areas must not overlap.
  11868.  
  11869.  
  11870. ■function _mfclose()
  11871. ■compat emx
  11872. ■headers
  11873. #include <stdio.h>
  11874. ■endheaders
  11875.  
  11876. ■param STREAM
  11877. ■prototype
  11878. char *_mfclose (FILE *STREAM);
  11879. ■endprototype
  11880.  
  11881.     Close a memory file.  A pointer to the buffer is returned.  On
  11882.     error, NULL is returned.  Use ftell() before calling _mfclose() to
  11883.     get the number of characters in the buffer.  If the ■pa{BUF}
  11884.     argument of _mfopen() was NULL, use free() to deallocate the
  11885.     buffer.
  11886.  
  11887. ■returnvalue
  11888.  
  11889.     See above.
  11890.  
  11891. ■seealso _mfopen()
  11892.  
  11893.  
  11894. ■function _mfopen()
  11895. ■compat emx
  11896. ■headers
  11897. #include <stdio.h>
  11898. ■endheaders
  11899.  
  11900. ■param BUF MODE SIZE INC
  11901. ■prototype
  11902. FILE *_mfopen (char *BUF, const char *MODE, size_t SIZE, int INC);
  11903. ■endprototype
  11904.  
  11905.     Open a memory file.  All output to a memory file goes to a buffer
  11906.     in memory.  The stream returned by _mfopen() can be used with
  11907.     fprintf(), fputc(), ftell() and fwrite().  If BUF is
  11908.     non-■tt{NULL}, output goes to the array of SIZE bytes pointed to
  11909.     by BUF.  INC must be zero.  If BUF is NULL, output goes to a
  11910.     buffer allocated with malloc() and resized with realloc().  The
  11911.     initial size of the buffer is SIZE bytes (which can be zero).  INC
  11912.     must be non-zero.  If INC is positive, the buffer size is
  11913.     increased by INC bytes whenever it is full.  If INC is -2, the
  11914.     buffer size is doubled whenever the buffer is full.  If SIZE
  11915.     is 0 and INC is -2, the initial buffer size is 512 bytes, the
  11916.     buffer will be allocated on the first output to the stream.
  11917.     Currently, MODE must point to ■tt{"wb"}.  On error, _mfopen()
  11918.     returns NULL.  Do not use fclose() on a stream created by
  11919.     _mfopen(), use _mfclose() instead.  Do not read from a stream
  11920.     created by _mfopen().
  11921.  
  11922. ■returnvalue
  11923.  
  11924.     _mfopen() returns a new stream.  On error, _mfopen() returns NULL.
  11925.  
  11926. ■restrictions
  11927.  
  11928.     _fsetmode() doesn't work, newline characters written to the
  11929.     stream are not expanded to CR/LF.
  11930.  
  11931. ■seealso _fassign() fopen() _mfclose() sprintf()
  11932.  
  11933. ■samplefile /emx/test/mftest.c
  11934.  
  11935.  
  11936. ■function _mheap()
  11937. ■compat VAC++
  11938. ■headers
  11939. #include <umalloc.h>
  11940. ■endheaders
  11941.  
  11942. ■param MEM
  11943. ■prototype
  11944. Heap_t _mheap (const void *MEM);
  11945. ■endprototype
  11946.  
  11947.     Return a pointer to the heap in which the memory block MEM has
  11948.     been allocated.  MEM must be the pointer obtained by calling
  11949.     calloc(), malloc(), realloc(), _tcalloc(), _tmalloc(),
  11950.     _trealloc(), _ucalloc(), _umalloc(), _utcalloc(), or _utmalloc().
  11951.     _mheap() returns NULL if MEM is NULL.  The return value of
  11952.     _mheap() is undefined if MEM points to a memory block which has
  11953.     been freed.  _mheap() may crash if MEM does not point to a memory
  11954.     block allocated by one of the functions listed above.
  11955.  
  11956. ■returnvalue
  11957.  
  11958.     _mheap() returns a pointer to the heap in which the memory block
  11959.     MEM has been allocated. _mheap() returns NULL if MEM is NULL.
  11960.  
  11961. ■seealso malloc() _msize() _ucreate() _ucreate2() _udefault() _umalloc()
  11962.  
  11963.  
  11964. ■function mkdir()
  11965. ■compat BSD
  11966. ■headers
  11967. #include <stdlib.h>
  11968. ■endheaders
  11969.  
  11970. ■param NAME MODE
  11971. ■prototype
  11972. int mkdir (const char *NAME, long MODE);
  11973. ■endprototype
  11974.  
  11975.     Create a directory whose name is in the string pointed to by NAME.
  11976.     Only one directory can be created in one step, therefore all but
  11977.     the last component of the string pointed to by NAME must exist.
  11978.     MODE (containing the permission bits) is ignored.
  11979.  
  11980. ■returnvalue
  11981. ■description
  11982. ■item 0
  11983.     success
  11984. ■item -1
  11985.     error
  11986. ■enddescription
  11987.  
  11988. ■seealso chdir() rmdir()
  11989.  
  11990.  
  11991. ■function mkstemp()
  11992. ■compat BSD
  11993. ■headers
  11994. #include <unistd.h>
  11995. ■endheaders
  11996.  
  11997. ■param STRING
  11998. ■prototype
  11999. int mkstemp (char *STRING);
  12000. ■endprototype
  12001.  
  12002.     Create a unique file name by modifying the string pointed to by
  12003.     STRING and open a file descriptor for that file using O_RDWR mode.
  12004.     Trailing ■tt{X} characters of the string pointed to by STRING are
  12005.     replaced by a letter followed by digits (the process ID).  There
  12006.     should be 6 trailing ■tt{X} characters.  Only 26 different file
  12007.     names per process can be created.
  12008.  
  12009. ■returnvalue
  12010.  
  12011.     On success, mkstemp() returns a file descriptor.  On failure,
  12012.     mkstemp() sets errno and returns -1.
  12013.  
  12014. ■hints
  12015.  
  12016.     Note that the string pointed to by STRING will be modified; do not
  12017.     use a string constant!
  12018.  
  12019.     mkstemp() opens the file in text mode; use setmode() to switch the
  12020.     file descriptor to binary mode.
  12021.  
  12022.     mkstemp() avoids the race condition of mktemp(), however it is
  12023.     less portable than mktemp().
  12024.  
  12025. ■seealso mktemp() setmode() tmpfile()
  12026.  
  12027.  
  12028. ■function mktemp()
  12029. ■compat UNIX
  12030. ■headers
  12031. #include <unistd.h>
  12032. ■endheaders
  12033.  
  12034. ■param STRING
  12035. ■prototype
  12036. char *mktemp (char *STRING);
  12037. ■endprototype
  12038.  
  12039.     Create a unique file name by modifying the string pointed to by
  12040.     STRING.  Trailing ■tt{X} characters of the string pointed to by
  12041.     STRING are replaced by a letter followed by digits (the process
  12042.     ID).  There should be 6 trailing ■tt{X} characters.  Only 26
  12043.     different file names per process can be created.
  12044.  
  12045. ■returnvalue
  12046.  
  12047.     On success, mktemp() returns STRING.  On failure, mktemp() returns
  12048.     NULL.
  12049.  
  12050. ■hints
  12051.  
  12052.     Note that the string pointed to by STRING will be modified; do not
  12053.     use a string constant!
  12054.  
  12055.     Note that mktemp() is subject to a race condition: other threads
  12056.     of the same process may use the same temporary file name before
  12057.     you have a chance to create the temporary file.
  12058.  
  12059. ■seealso mkstemp() tempnam() tmpfile() tmpnam()
  12060.  
  12061. ■samplecode
  12062. char tmp[20];
  12063.  
  12064. strcpy (tmp, "exXXXXXX");
  12065. if (mktemp (tmp) != NULL)
  12066.   {
  12067.     /* ... */
  12068.   }
  12069. ■endsamplecode
  12070.  
  12071.  
  12072. ■function mktime()
  12073. ■compat C90
  12074. ■headers
  12075. #include <time.h>
  12076. ■endheaders
  12077.  
  12078. ■param T
  12079. ■prototype
  12080. time_t mktime (struct tm *T);
  12081. ■endprototype
  12082.  
  12083.     Compute the number of seconds elapsed between 00:00:00 1-Jan-1970
  12084.     Coordinated Universal Time (UTC, GMT) and the time in the
  12085.     structure pointed to by T, interpreted as local time.  The tm_wday
  12086.     and tm_yday members of the structure are ignored.  The members of
  12087.     the structure are allowed to be out of range; mktime() modifies
  12088.     the structure to force the values to the usual ranges.  The
  12089.     tm_mday member is not set until the tm_mon and tm_year members
  12090.     have been adjusted.  The time in the structure is assumed to
  12091.     initially represent standard time if tm_isdst is zero.  The time
  12092.     in the structure is assumed to initially represent daylight saving
  12093.     time if tm_isdst is positive.  If tm_isdst is negative, mktime()
  12094.     determines whether daylight saving time is in effect for the
  12095.     specified time.  mktime() sets the tm_wday, tm_yday, and tm_isdst
  12096.     members of the structure as appropriate.
  12097.  
  12098.     See ■hpt{tzset()} for a description of the TZ environment
  12099.     variable.
  12100.  
  12101. ■returnvalue
  12102.  
  12103.     mktime() returns the number of seconds elapsed between 00:00:00
  12104.     1-Jan-1970 UTC and the time in the structure pointed to by T.  If
  12105.     the time cannot be represented, mktime() returns -1 cast as
  12106.     time_t.
  12107.  
  12108. ■implementation
  12109.  
  12110.     If tm_isdst is negative and the specified time is in the time gap
  12111.     between standard time and daylight saving time, mktime() assumes
  12112.     that daylight saving time is not in effect for the specified time.
  12113.  
  12114. ■seealso gmtime() localtime() tzset()
  12115.  
  12116.  
  12117. ■function modf() modfl()
  12118. ■compat C90 C9X
  12119. ■headers
  12120. #include <math.h>
  12121. ■endheaders
  12122.  
  12123. ■param X INT_PTR
  12124. ■prototype
  12125. double modf (double X, double *INT_PTR);
  12126. long double modfl (long double X, long double *INT_PTR);
  12127. ■endprototype
  12128.  
  12129.     Split X into fractional part (which is returned) and integer part
  12130.     (which is stored to ■tt{*}■pa{INT_PTR}).  Both the fractional and
  12131.     the integer part have the same sign as X.
  12132.  
  12133.     modfl() uses the ■tt{long double} format.
  12134.  
  12135. ■returnvalue
  12136.  
  12137.     modf() returns the fractional part of X.
  12138.  
  12139. ■seealso ceil() floor() frexp() rint() trunc()
  12140.  
  12141.  
  12142. ■function _msize()
  12143. ■compat PC
  12144. ■headers
  12145. #include <stdlib.h>
  12146. ■endheaders
  12147.  
  12148. ■param MEM
  12149. ■prototype
  12150. size_t _msize (const void *MEM);
  12151. ■endprototype
  12152.  
  12153.     Return the size of the memory block MEM which has been allocated
  12154.     by one of the C library's memory allocation functions.  MEM must
  12155.     be the pointer obtained by calling calloc(), malloc(), realloc(),
  12156.     _tcalloc(), _tmalloc(), _trealloc(), _ucalloc(), _umalloc(),
  12157.     _utcalloc(), or _utmalloc().  _msize() returns zero if MEM is
  12158.     NULL.  The return value of _msize() is undefined if MEM points to
  12159.     a memory block which has been freed.
  12160.  
  12161. ■returnvalue
  12162.  
  12163.     _msize() returns the number of bytes allocated to MEM or zero if
  12164.     MEM is NULL.
  12165.  
  12166. ■seealso _expand() malloc() _mheap() _umalloc()
  12167.  
  12168.  
  12169. ■function nextafter() nextafterf() nextafterl()
  12170. ■compat C9X
  12171. ■headers
  12172. #include <math.h>
  12173. ■endheaders
  12174.  
  12175. ■param X Y
  12176. ■prototype
  12177. double nextafter (double X, double Y);
  12178. float nextafterf (float X, float Y);
  12179. long double nextafterl (long double X, long double Y);
  12180. ■endprototype
  12181.  
  12182.     Return the next representable value after X, in the type of the
  12183.     function, in the direction of Y.
  12184.  
  12185. ■returnvalue
  12186.  
  12187.     Return Y if X■tt{==}Y is true.  If both X and Y are NaNs, return
  12188.     one of them.  If X or Y is a NaN, return that NaN.  If Y is
  12189.     greater than X, return the smallest value in the type of the
  12190.     function that is greater than X.  If Y is smaller than X, return
  12191.     the greatest value in the type of the function that is smaller
  12192.     than X.
  12193.  
  12194. ■seealso copysign() fpclassify()
  12195.  
  12196.  
  12197. ■function _nls_init()
  12198. ■compat emx
  12199. ■headers
  12200. #include <sys/nls.h>
  12201. ■endheaders
  12202.  
  12203. ■prototype
  12204. void _nls_init (void);
  12205. ■endprototype
  12206.  
  12207.     Initialize the global variables _nls_tolower_tab,
  12208.     _nls_toupper_tab, and _nls_ctype_tab, which are used by
  12209.     _nls_tolower(), _nls_toupper(), _nls_strlwr(), _nls_strupr(), and
  12210.     _nls_is_dbcs_lead().  The tables are initialized appropriately for
  12211.     the current country code and code page.  _nls_init() is
  12212.     automatically called by the startup code, therefore you don't have
  12213.     to call _nls_init() unless you change the country code or the code
  12214.     page: _nls_init() should be called after changing the country code
  12215.     or code page.
  12216.  
  12217. ■seealso _defext() _fncmp() _getext() _getname() _nls_is_dbcs_lead() _nls_strlwr() _nls_tolower() _remext() _splitpath()
  12218.  
  12219.  
  12220. ■function _nls_is_dbcs_lead()
  12221. ■compat emx
  12222. ■headers
  12223. #include <sys/nls.h>
  12224. ■endheaders
  12225.  
  12226. ■param C
  12227. ■prototype
  12228. int _nls_is_dbcs_lead (int C);
  12229. ■endprototype
  12230.  
  12231.     This macro evaluates to a non-zero value if C is the lead byte of
  12232.     a DBCS character.  C must be an integer which is representable as
  12233.     ■tt{unsigned char} (that is, 0 through 255).  Note that C must not
  12234.     be EOF.
  12235.  
  12236. ■returnvalue
  12237.  
  12238.     _nls_is_dbcs_lead() returns zero if its argument is not a DBCS
  12239.     lead byte.  _nls_is_dbcs_lead() returns a non-zero value if its
  12240.     argument is a DBCS lead byte.
  12241.  
  12242. ■seealso _nls_init() _nls_strlwr() _nls_strupr()
  12243.  
  12244.  
  12245. ■function _nls_strlwr() _nls_strupr()
  12246. ■compat emx
  12247. ■headers
  12248. #include <sys/nls.h>
  12249. ■endheaders
  12250.  
  12251. ■param STRING
  12252. ■prototype
  12253. unsigned char *_nls_strlwr (unsigned char *STRING);
  12254. unsigned char *_nls_strupr (unsigned char *STRING);
  12255. ■endprototype
  12256.  
  12257.     These functions convert all the characters of the string pointed
  12258.     to by STRING to lower case or upper case, respectively.  Accented
  12259.     characters etc.  are converted as well, DBCS characters are not
  12260.     changed.
  12261.  
  12262. ■returnvalue
  12263.  
  12264.     _nls_strlwr() and _nls_strupr() return STRING.
  12265.  
  12266. ■seealso _nls_init() _nls_is_dbcs_lead() _nls_tolower() _nls_toupper()
  12267.  
  12268.  
  12269. ■function _nls_tolower() _nls_toupper()
  12270. ■compat emx
  12271. ■headers
  12272. #include <sys/nls.h>
  12273. ■endheaders
  12274.  
  12275. ■param C
  12276. ■prototype
  12277. unsigned char _nls_tolower (unsigned char C);
  12278. unsigned char _nls_toupper (unsigned char C);
  12279. ■endprototype
  12280.  
  12281.     These macros convert the character C to lower case or upper
  12282.     case, respectively.  Accented characters etc. are converted as
  12283.     well.  The result is undefined if C is a DBCS lead byte.
  12284.  
  12285. ■returnvalue
  12286.  
  12287.     _nls_tolower() returns its argument converted to lower case.
  12288.     _nls_toupper() returns its argument converted to upper case.
  12289.  
  12290. ■seealso _nls_init() _nls_strlwr() _nls_strupr()
  12291.  
  12292.  
  12293. ■function offsetof()
  12294. ■compat C90
  12295. ■headers
  12296. #include <stddef.h>
  12297. ■endheaders
  12298.  
  12299. ■param TYPE MEMBER
  12300. ■prototype
  12301. size_t offsetof (TYPE, MEMBER);
  12302. ■endprototype
  12303.  
  12304.     The offsetof() macro expands to an integral constant expression of
  12305.     type ■tt{size_t}.  The value of that expression is the offset in
  12306.     bytes from the beginning of the structure designated by TYPE to
  12307.     the structure member designated by MEMBER.
  12308.  
  12309.     The structure member must not be a bit-field.  Given the declaration
  12310. ■typewriter
  12311. static TYPE s;
  12312. ■endtypewriter
  12313.     the expression
  12314. ■typewriter
  12315. &(s.■pa{MEMBER})
  12316. ■endtypewriter
  12317.     must evaluate to an address constant.
  12318.  
  12319. ■returnvalue
  12320.  
  12321.     See above.
  12322.  
  12323. ■samplecode
  12324. #include <stddef.h>
  12325.  
  12326. struct sample
  12327. {
  12328.   int a;
  12329.   struct
  12330.     {
  12331.       int b[2];
  12332.     } inner;
  12333. };
  12334.  
  12335. size_t offset_a  = offsetof (struct sample, a);
  12336. size_t offset_b0 = offsetof (struct sample, inner.b[0]);
  12337. size_t offset_b1 = offsetof (struct sample, inner.b[1]);
  12338. ■endsamplecode
  12339.  
  12340.  
  12341. ■function open()
  12342. ■compat UNIX
  12343. ■headers
  12344. #include <io.h>
  12345. #include <fcntl.h>
  12346. #include <sys/types.h>
  12347. #include <sys/stat.h>
  12348. ■endheaders
  12349.  
  12350. ■param NAME OFLAG PMODE ISIZE
  12351. ■prototype
  12352. int open (const char *NAME, int OFLAG);
  12353. int open (const char *NAME, int OFLAG, int PMODE);
  12354.  
  12355. int open (const char *NAME, int OFLAG, unsigned long ISIZE);
  12356. int open (const char *NAME, int OFLAG, int PMODE, unsigned long ISIZE);
  12357. ■endprototype
  12358.  
  12359.     Open a file or device.  NAME points to the name of the file or
  12360.     device.  OFLAG contains one or more of the following values,
  12361.     combined by the ■tt{|} operator:
  12362.  
  12363. ■description
  12364.  
  12365. ■item O_RDONLY
  12366.  
  12367.     Open for reading.  Writing is not allowed
  12368.  
  12369. ■item O_WRONLY
  12370.  
  12371.     Open for writing.  Reading is not allowed
  12372.  
  12373. ■item O_RDWR
  12374.  
  12375.     Open for reading and writing
  12376.  
  12377. ■item O_APPEND
  12378.  
  12379.     Move the file pointer to the end of file before any write
  12380.     operation takes place.  This is used for appending to a file
  12381.  
  12382. ■item O_CREAT
  12383.  
  12384.     Create the file if it does not exist.  If this flag is set, the
  12385.     PMODE argument is required
  12386.  
  12387. ■item O_TRUNC
  12388.  
  12389.     Truncate the size of the file to 0
  12390.  
  12391. ■item O_EXCL
  12392.  
  12393.     Fail if the O_CREAT flag is used and the file already exists
  12394.  
  12395. ■item O_NONBLOCK and O_NDELAY
  12396.  
  12397.     Currently ignored
  12398.  
  12399. ■item O_BINARY
  12400.  
  12401.     Binary mode, no translation.  See below
  12402.  
  12403. ■item O_TEXT
  12404.  
  12405.     Text mode, translate CR/LF to the newline character.  See below
  12406.  
  12407. ■item O_NOINHERIT
  12408.  
  12409.     Child processes won't inherit the file handle
  12410.  
  12411. ■item O_SYNC
  12412.  
  12413.     Write operations are synchronous, that is, write() waits until
  12414.     file data has been physically written
  12415.  
  12416. ■item O_SIZE
  12417.  
  12418.     Set the initial size of the file to ISIZE if the file is a new
  12419.     file (O_CREAT) or an existing file truncated (O_TRUNC).  If this
  12420.     flag is set, the ISIZE argument is required.  O_SIZE is ignored
  12421.     under DOS
  12422.  
  12423. ■enddescription
  12424.  
  12425.     If a new file is created, PMODE (modified by the umask value), is
  12426.     used to set the file permissions.  S_IREAD grants read access,
  12427.     S_IWRITE grants write access.  S_IREAD is ignored (DOS and OS/2
  12428.     limitation).  To grant both read and write access, use
  12429.     ■tt{S_IREAD|S_IWRITE}.
  12430.  
  12431.     There are two additional OFLAG flags: O_TEXT for text mode,
  12432.     O_BINARY for binary mode.  Text mode, which is the default,
  12433.     translates each CR/LF pair to a newline character on input and
  12434.     translates newline characters to CR/LF pairs on output.  If the last
  12435.     character of a file is Ctrl-Z, it is discarded on input.  Binary
  12436.     mode disables these transformations.
  12437.  
  12438.     If the file or device cannot be opened, open() sets errno and
  12439.     returns -1.  If open() succeeds, the file handle is returned.  The
  12440.     file handle is always greater than -1.
  12441.  
  12442.     The mode ■tt{O_TRUNC|O_RDONLY} is not implemented.  A Ctrl-Z at
  12443.     the end of the file is removed only when opening a file for
  12444.     appending in text mode.  Ctrl-Z at the end of the file is
  12445.     obsolete, anyway.
  12446.  
  12447.     The file is opened in the sharing mode SH_DENYNO, see
  12448.     ■hpt{sopen()}.
  12449.  
  12450. ■returnvalue
  12451.  
  12452.     open() returns a file handle for the file.  On error, open() sets
  12453.     errno and returns -1.
  12454.  
  12455. ■implementation
  12456.  
  12457.     O_SIZE is an emx extension.  It's the caller's responsibility to
  12458.     truncate the file if its size should be less than ISIZE bytes.
  12459.     O_SIZE is ignored under DOS.
  12460.  
  12461. ■restrictions
  12462.  
  12463.     Under DOS, the O_NOINHERIT flag is currently ignored for child
  12464.     processes which are DOS programs (vs. emx programs).  Under DOS,
  12465.     the O_SYNC and O_SIZE flags are ignored.
  12466.  
  12467. ■seealso close() fcntl() fdopen() ftruncate() sopen()
  12468.  
  12469.  
  12470. ■function opendir() closedir() readdir() seekdir() telldir() rewinddir()
  12471. ■compat POSIX.1
  12472. ■headers
  12473. #include <sys/types.h>
  12474. #include <dirent.h>             /* this is recommended */
  12475. #include <sys/dir.h>            /* this also works (for now) */
  12476. ■endheaders
  12477.  
  12478. ■param NAME DIRP OFF
  12479. ■prototype
  12480. DIR *opendir (const char *NAME);
  12481. int closedir (DIR *DIRP);
  12482. struct dirent *readdir (DIR *DIRP);
  12483. void seekdir (DIR *DIRP, long OFF);
  12484. long telldir (DIR *DIRP);
  12485. void rewinddir (DIR *DIRP);
  12486. ■endprototype
  12487.  
  12488.     Scan directories.  opendir() opens the directory whose name is in
  12489.     the string pointed to by NAME for scanning.  If there is an error,
  12490.     NULL is returned.  Otherwise a value is returned which is used
  12491.     with the other functions to continue the scanning.
  12492.  
  12493.     closedir() ends the directory scan of DIRP.  After closing DIRP,
  12494.     you must not use DIRP.  You should close all handles created by
  12495.     opendir().
  12496.  
  12497.     readdir() retrieves the next directory entry for DIRP.  If there
  12498.     are no more directory entries, NULL is returned.
  12499.  
  12500.     seekdir() moves to the specified directory entry of DIRP.  If OFF
  12501.     is 0, the first directory entry will be read next.  If OFF is 1,
  12502.     the second directory entry will be read next.  And so on.
  12503.     seekdir() is not a POSIX.1 function.
  12504.  
  12505.     telldir() returns the current position in DIRP.  0 is returned for
  12506.     the first directory entry.  telldir() is not a POSIX.1 function.
  12507.  
  12508.     rewinddir() is equivalent to ■tt{seekdir (0)}.
  12509.  
  12510.     These functions use _fnlwr() to convert the file names to lower
  12511.     case on upper-case-only file systems.
  12512.  
  12513. ■returnvalue
  12514.  
  12515.     opendir() returns a descriptor to be used with the other
  12516.     functions.  On error, opendir() returns NULL.
  12517.  
  12518.     closedir() returns 0 if successful, -1 on error.
  12519.  
  12520.     readdir() returns a pointer to a directory entry.  If there are no
  12521.     more directory entries, readdir() returns NULL.
  12522.  
  12523.     telldir() returns the current position in DIRP.
  12524.  
  12525. ■seealso _fnlwr() _wildcard()
  12526.  
  12527.  
  12528. ■function _outp8() _outp16() _outp32()
  12529. ■compat emx *
  12530. ■headers
  12531. #include <sys/hw.h>
  12532. ■endheaders
  12533.  
  12534. ■param PORT VALUE
  12535. ■prototype
  12536. void _outp8 (unsigned PORT, unsigned VALUE);
  12537. void _outp16 (unsigned PORT, unsigned VALUE);
  12538. void _outp32 (unsigned PORT, unsigned VALUE);
  12539. ■endprototype
  12540.  
  12541.     These functions write a single byte or word to a hardware port.
  12542.     _outp8() writes the byte VALUE to PORT, _outp16() writes the
  12543.     16-bit word VALUE to PORT, _outp32() writes the 32-bit word VALUE
  12544.     to PORT.
  12545.  
  12546.     You have to call _portaccess() first to enable access to a range
  12547.     of ports.  To make your program work under DOS, you have to use
  12548.     emx option -ai, see `■hpt{Using emx options}'.  Under OS/2, your
  12549.     program requires emxio.dll in a directory listed in LIBPATH.
  12550.  
  12551. ■seealso _portaccess() _inp8() _outps8()
  12552.  
  12553.  
  12554. ■function _outps8() _outps16() _outps32() _outps8dac()
  12555. ■compat emx *
  12556. ■headers
  12557. #include <sys/hw.h>
  12558. ■endheaders
  12559.  
  12560. ■param PORT SRC COUNT
  12561. ■prototype
  12562. void _outps8 (unsigned PORT, const unsigned char *SRC, unsigned COUNT);
  12563. void _outps16 (unsigned PORT, const unsigned short *SRC, unsigned COUNT);
  12564. void _outps32 (unsigned PORT, const unsigned short *SRC, unsigned COUNT);
  12565. void _outps8dac (unsigned PORT, const unsigned char *SRC, unsigned COUNT);
  12566. ■endprototype
  12567.  
  12568.     These functions write multiple bytes or words to a hardware port.
  12569.     _outps8() writes COUNT bytes from the array pointed to by SRC to
  12570.     PORT.  _outps16() writes COUNT 16-bit words from the array pointed
  12571.     to by SRC to PORT.  _outps32() writes COUNT 32-bit words from the
  12572.     array pointed to by SRC to PORT.
  12573.  
  12574.     The COUNT argument of _outps8() must not exceed 65535.
  12575.  
  12576.     The array pointed to by SRC of _outps16() must be aligned on a
  12577.     16-bit boundary, that is, the address must be even.  COUNT must
  12578.     not exceed 32768.
  12579.  
  12580.     The array pointed to by SRC of _outps32() must be aligned on a
  12581.     32-bit boundary, that is, the address must be a multiple of four.
  12582.     COUNT must not exceed 65536.
  12583.  
  12584.     _outps8dac() is a slowed-down version of _outps8() suitable for
  12585.     writing to the VGA palette registers.
  12586.  
  12587.     You have to call _portaccess() first to enable access to a range
  12588.     of ports.  To make your program work under DOS, you have to use
  12589.     emx option -ai, see `■hpt{Using emx options}'.  Under OS/2, your
  12590.     program requires emxio.dll in a directory listed in LIBPATH.
  12591.  
  12592. ■seealso _portaccess() _inps8() _outp8()
  12593.  
  12594.  
  12595. ■function _path()
  12596. ■compat emx
  12597. ■headers
  12598. #include <stdlib.h>
  12599. ■endheaders
  12600.  
  12601. ■param DST NAME
  12602. ■prototype
  12603. int _path (char *DST, const char *NAME);
  12604. ■endprototype
  12605.  
  12606.     Find an executable file.  If the string pointed to by NAME
  12607.     contains a colon, a slash or a backslash, only that name will be
  12608.     tried.  If the string pointed to by NAME does not contain colons,
  12609.     slashes or backslashes, the file will be sought in the directories
  12610.     listed in the EMXPATH and PATH environment variables.  If the file
  12611.     is not found, the empty string will be stored to the array pointed
  12612.     to by DST, errno will be ENOENT and -1 will be returned.  If the
  12613.     file is found, the path name will be copied to the array pointed
  12614.     to by DST and 0 will be returned.  No default extension is used.
  12615.  
  12616. ■returnvalue
  12617.  
  12618.     See above.
  12619.  
  12620. ■seealso getenv() _searchenv()
  12621.  
  12622.  
  12623. ■function pathconf() fpathconf()
  12624. ■compat POSIX.1
  12625. ■headers
  12626. #include <unistd.h>
  12627. ■endheaders
  12628.  
  12629. ■param PATH HANDLE NAME
  12630. ■prototype
  12631. long pathconf (const char *PATH, int NAME);
  12632. long fpathconf (int HANDLE, int NAME);
  12633. ■endprototype
  12634.  
  12635.     Return the current value of the configurable limit or option NAME
  12636.     associated with the file or directory associated with HANDLE or
  12637.     whose name is in the string pointed to by PATH.  NAME is one of
  12638.     the following constants:
  12639.  
  12640. ■description
  12641. ■item _PC_LINK_MAX
  12642.  
  12643.     corresponds to LINK_MAX (maximum value of a file's link count)
  12644.  
  12645. ■item _PC_MAX_CANON
  12646.  
  12647.     corresponds to MAX_CANON (maximum number of bytes in a terminal
  12648.     canonical input line)
  12649.  
  12650. ■item _PC_MAX_INPUT
  12651.  
  12652.     corresponds to MAX_INPUT (maximum number of bytes for which space
  12653.     will be available in a terminal input queue)
  12654.  
  12655. ■item _PC_NAME_MAX
  12656.  
  12657.     corresponds to NAME_MAX (maximum number of bytes in a file name)
  12658.  
  12659. ■item _PC_PATH_MAX
  12660.  
  12661.     corresponds to PATH_MAX (maximum number of bytes in a path name)
  12662.  
  12663. ■item _PC_PIPE_BUF
  12664.  
  12665.     corresponds to PIPE_BUF (maximum number of bytes that can be
  12666.     written atomically to a pipe)
  12667.  
  12668. ■item _PC_CHOWN_RESTRICTED
  12669.  
  12670.     corresponds to _POSIX_CHOWN_RESTRICTED (see POSIX.1 for details)
  12671.  
  12672. ■item _PC_NO_TRUNC
  12673.  
  12674.     corresponds to _POSIX_NO_TRUNC (path name components longer than
  12675.     NAME_MAX generate an error)
  12676.  
  12677. ■item _PC_VDISABLE
  12678.  
  12679.     corresponds to _POSIX_VDISABLE (terminal special characters can be
  12680.     disabled using this character value, if it is defined)
  12681.  
  12682. ■enddescription
  12683.  
  12684.     See POSIX.1 for more details.
  12685.  
  12686. ■returnvalue
  12687.  
  12688.     If NAME is invalid, pathconf() and fpathconf() set errno to EINVAL
  12689.     and return -1.  If the value associated with NAME has no limit for
  12690.     the path or handle, pathconf() and fpathconf() return -1 without
  12691.     changing errno.  If the implementation needs to use PATH or HANDLE
  12692.     to determine the value of NAME and the implementation does not
  12693.     support the association of NAME with the file specified by PATH or
  12694.     HANDLE, respectively, or if HANDLE is an invalid file descriptor,
  12695.     pathconf() and fpathconf() set errno and return -1.  Otherwise,
  12696.     pathconf() and fpathconf() return the current value of the
  12697.     variable.
  12698.  
  12699. ■restrictions
  12700.  
  12701.     pathconf() and fpathconf() currently return just the POSIX.1
  12702.     minimum values.
  12703.  
  12704. ■seealso sysconf()
  12705.  
  12706.  
  12707. ■function pause()
  12708. ■compat UNIX
  12709. ■headers
  12710. #include <signal.h>
  12711. ■endheaders
  12712.  
  12713. ■prototype
  12714. int pause (void);
  12715. ■endprototype
  12716.  
  12717.     Wait until a signal is received.  The process is suspended until
  12718.     delivery of a signal for which a signal handler is installed.
  12719.     pause() returns after the signal handler returns.
  12720.  
  12721.     The process will be terminated (and pause() won't return) if
  12722.     an uncaught signal is delivered which terminates the process.
  12723.  
  12724. ■returnvalue
  12725.  
  12726.     pause() returns -1 and sets errno to EINTR (if it returns at
  12727.     all).
  12728.  
  12729. ■restrictions
  12730.  
  12731.     pause() is not implemented under DOS.
  12732.  
  12733. ■seealso alarm() kill() raise() sigaction() signal() sigsuspend()
  12734.  
  12735.  
  12736. ■function pclose()
  12737. ■compat UNIX
  12738. ■headers
  12739. #include <stdio.h>
  12740. ■endheaders
  12741.  
  12742. ■param STREAM
  12743. ■prototype
  12744. int pclose (FILE *STREAM);
  12745. ■endprototype
  12746.  
  12747.     Close a pipe created by popen().  pclose() waits until the child
  12748.     process started by popen() ends and then closes STREAM.  The
  12749.     termination status of the child process is returned.  See
  12750.     ■hpt{wait()} for details about the return value.
  12751.  
  12752. ■returnvalue
  12753. ■description
  12754. ■item 0
  12755.     success
  12756. ■item -1
  12757.     error
  12758. ■enddescription
  12759.  
  12760. ■restrictions
  12761.  
  12762.     pclose() is not implemented under DOS.
  12763.  
  12764. ■seealso popen() wait()
  12765.  
  12766.  
  12767. ■function perror()
  12768. ■compat C90
  12769. ■headers
  12770. #include <stdio.h>
  12771. ■endheaders
  12772.  
  12773. ■param STRING
  12774. ■prototype
  12775. void perror (const char *STRING);
  12776. ■endprototype
  12777.  
  12778.     Print an appropriate error message for the current errno value to
  12779.     stderr.  If STRING is NULL or points to the empty string ■tt{""},
  12780.     just the error message is printed.  Otherwise, the string pointed
  12781.     to by STRING and a colon precede the error message.
  12782.  
  12783. ■seealso errno strerror() sys_errlist sys_nerr
  12784.  
  12785.  
  12786. ■function pipe()
  12787. ■compat UNIX
  12788. ■headers
  12789. #include <io.h>
  12790. ■endheaders
  12791.  
  12792. ■param TWO_HANDLES
  12793. ■prototype
  12794. int pipe (int *TWO_HANDLES);
  12795. ■endprototype
  12796.  
  12797.     Create an unnamed pipe.  The handle used for reading from the pipe
  12798.     is stored to ■pa{TWO_HANDLES}■tt{[0]}, the handle used for writing
  12799.     to the pipe is stored to ■pa{TWO_HANDLES}■tt{[1]}.  Both handles
  12800.     are in text mode; use ■tt{setmode()} if you want to switch to
  12801.     binary mode.
  12802.  
  12803. ■returnvalue
  12804. ■description
  12805. ■item 0
  12806.     success
  12807. ■item -1
  12808.     error
  12809. ■enddescription
  12810.  
  12811. ■restrictions
  12812.  
  12813.     pipe() is implemented for OS/2 only.
  12814.  
  12815. ■seealso close() dup() popen() setmode()
  12816.  
  12817.  
  12818. ■function popen()
  12819. ■compat UNIX
  12820. ■headers
  12821. #include <stdio.h>
  12822. ■endheaders
  12823.  
  12824. ■param COMMAND MODE
  12825. ■prototype
  12826. FILE *popen (const char *COMMAND, const char *MODE);
  12827. ■endprototype
  12828.  
  12829.     Start a child process and connect one end of a pipe to it.
  12830.     popen() runs the command whose name is in the string pointed to by
  12831.     COMMAND by starting a command processor.  See ■hpt{system()} for
  12832.     details on locating and running the command processor.  MODE must
  12833.     point to a string starting with ■tt{r} or ■tt{w}.  If the string
  12834.     starts with ■tt{r}, standard output of the command will be
  12835.     redirected, you can get the output by reading from the stream
  12836.     returned by popen().  If the mode string starts with ■tt{w},
  12837.     standard input of the command will be redirected, you can send
  12838.     data to the command by writing to the stream returned by popen().
  12839.     Append ■tt{b} for binary mode or ■tt{t} for text mode to the mode
  12840.     string.  The default is text mode, see also ■hpt{fopen()}.  If an
  12841.     error occurs, popen() returns NULL.  Otherwise, popen() returns a
  12842.     stream which is connected to the local end of the pipe.  Use
  12843.     pclose() to close the stream.
  12844.  
  12845. ■returnvalue
  12846.  
  12847.     popen() returns a new stream.  On error, popen() returns NULL.
  12848.  
  12849. ■restrictions
  12850.  
  12851.     popen() is not implemented under DOS.
  12852.  
  12853. ■seealso pclose() pipe() system()
  12854.  
  12855.  
  12856. ■function _portaccess()
  12857. ■compat emx
  12858. ■headers
  12859. #include <sys/hw.h>
  12860. ■endheaders
  12861.  
  12862. ■param FIRST LAST
  12863. ■prototype
  12864. int _portaccess (unsigned FIRST, unsigned LAST);
  12865. ■endprototype
  12866.  
  12867.     Gain access to hardware ports.  To access hardware ports, you have
  12868.     to call _portaccess().  FIRST is the address of the first port,
  12869.     LAST is the address of the last port.  emx option -ai must be used
  12870.     to enable _portaccess() under DOS, see `■hpt{Using emx options}'.
  12871.  
  12872.     _portaccess() always succeeds under OS/2.
  12873.  
  12874. ■returnvalue
  12875. ■description
  12876. ■item 0
  12877.     success
  12878. ■item -1
  12879.     error
  12880. ■enddescription
  12881.  
  12882. ■seealso _memaccess() _inp8() _outp8() _wait0()
  12883.  
  12884. ■samplefile /emx/test/hw_io.c
  12885.  
  12886.  
  12887. ■function pow() powl()
  12888. ■compat C90 C9X
  12889. ■headers
  12890. #include <math.h>
  12891. ■endheaders
  12892.  
  12893. ■param X Y
  12894. ■prototype
  12895. double pow (double X, double Y);
  12896. long double powl (long double X, long double Y);
  12897. ■endprototype
  12898.  
  12899.     Raise X to the power of Y and return the result.  If pow() is
  12900.     undefined for a given pair of X and Y, pow() returns an
  12901.     implementation-defined value and sets errno to EDOM.  On overflow,
  12902.     pow() returns HUGE_VAL and sets errno to ERANGE.
  12903.  
  12904.     pow() returns 1.0 for all values of X if Y is zero.
  12905.  
  12906.     powl() uses the ■tt{long double} format.
  12907.  
  12908. ■returnvalue
  12909.  
  12910.     pow() returns ■pa{X}^■pa{Y}.
  12911.  
  12912. ■seealso cbrt() exp() ldexp() log() sqrt()
  12913.  
  12914.  
  12915. ■function printf()
  12916. ■compat C90
  12917. ■headers
  12918. #include <stdio.h>
  12919. ■endheaders
  12920.  
  12921. ■param FORMAT <flags> <width> <precision> <size> <type>
  12922. ■prototype
  12923. int printf (const char *FORMAT, ...);
  12924. ■endprototype
  12925.  
  12926.     printf() performs formatted output to the stdout stream.  On
  12927.     success, the number of characters written to stdout is returned.
  12928.     Otherwise, EOF is returned.
  12929.  
  12930.     Characters in the string pointed to by FORMAT are copied
  12931.     unmodified to the destination unless a format specification is
  12932.     hit.  A format specification has the following format:
  12933.  
  12934. ■indent
  12935.   ■sy{%[<flags>][<width>][.<precision>][<size>]<type>}
  12936. ■endindent
  12937.  
  12938.     where items in brackets are optional.  For each format
  12939.     specification an argument of the specified type is taken from the
  12940.     argument list, is formatted according to the format specification
  12941.     and written to the destination.  To include one percent sign in
  12942.     the output, put two percent signs (■tt{%%}) into the FORMAT string.
  12943.  
  12944.     A <flag> character can be specified to modify the formatting. The
  12945.     following <flags> characters are available:
  12946.  
  12947. ■list
  12948. ■item ■tt{-}
  12949.  
  12950.     Left-justify the converted value in the field.  Without this flag,
  12951.     the value is right-justified.  The value will be padded with
  12952.     blanks on the right (note that ■tt{-} overrides ■tt{0}).  If
  12953.     ■tt{-} is not given, the value is padded on the left with blanks
  12954.     or zeros, according to the ■tt{0} flag and the <type>.
  12955.  
  12956. ■item ■tt{+}
  12957.  
  12958.     Always insert sign (■tt{+} or ■tt{-}) for the conversion of a
  12959.     signed number (that is, <type> being ■tt{d}, ■tt{e}, ■tt{E},
  12960.     ■tt{f}, ■tt{g}, ■tt{G} or ■tt{i}).  ■tt{+} is ignored for all
  12961.     other conversions.  ■tt{+} overrides space.  If ■tt{+} is not
  12962.     specified, the sign is printed only for negative numbers and for
  12963.     -0.0.
  12964.  
  12965. ■item space
  12966.  
  12967.     Insert a space if the conversion of a signed number (that is,
  12968.     <type> being ■tt{d}, ■tt{e}, ■tt{E}, ■tt{f}, ■tt{g}, ■tt{G} or
  12969.     ■tt{i}) doesn't start with a sign (■tt{+} or ■tt{-}).  For all
  12970.     other conversions, space is ignored.  If both ■tt{+} and space are
  12971.     given, space is ignored.
  12972.  
  12973. ■item ■tt{0}
  12974.  
  12975.     Pad numbers with ■tt{'0'} characters instead of blanks.  This flag
  12976.     is ignored for non-numeric conversions, if ■tt{-} is used, or if
  12977.     <precision> is given.
  12978.  
  12979. ■item ■tt{#}
  12980.  
  12981.     Use alternate conversion.  For the ■tt{o} conversion, the
  12982.     precision will be increased to force the first digit of the result
  12983.     to be a zero.  For the ■tt{x} and ■tt{X} conversions, the number
  12984.     will be prefixed with ■tt{0x} unless it is zero.  For the ■tt{e},
  12985.     ■tt{E}, ■tt{f}, ■tt{g} and ■tt{G} conversions, a decimal point
  12986.     will always be printed, even if no digits follow it.  For the
  12987.     ■tt{g} and ■tt{G} conversions, trailing zeros are not removed.
  12988.  
  12989. ■endlist
  12990.  
  12991.     If the length of the converted value is less than <width>, it is
  12992.     padded with blanks or ■tt{'0'} characters.  Unless the ■tt{-} flag
  12993.     is used, the field is padded on the left.  Padding is done with
  12994.     zeros for numeric conversions if the ■tt{0} flag is given, the
  12995.     ■tt{-} flag is not given and <precision> is not given.  Otherwise,
  12996.     blanks are used for padding.  If the length of the converted value
  12997.     is greater than <width>, the field is not truncated.  <width> is
  12998.     either a decimal number or a ■tt{*} character.  In the latter
  12999.     case, the width is taken from the argument list.
  13000.  
  13001.     <precision> specifies the number of decimal digits after the
  13002.     decimal point of a floating point number when using the ■tt{e},
  13003.     ■tt{E} or ■tt{f} conversions.  For the ■tt{g} and ■tt{G}
  13004.     conversions, <precision> specifies the maximum number of
  13005.     significant digits.  The number will be rounded according to
  13006.     <precision> for the floating point conversions.  For the ■tt{d},
  13007.     ■tt{i}, ■tt{o}, ■tt{u}, ■tt{x} and ■tt{X} conversions, <precision>
  13008.     specifies the minimum number of digits to print.  If the number
  13009.     has less digits, it will be padded with zeros on the left.  If the
  13010.     precision is 0 and the integer is 0, no output will be produced
  13011.     for this field (except for the ■tt{o} conversion if the ■tt{#}
  13012.     flag is given).  For the ■tt{s} conversion, <precision> specifies
  13013.     the maximum string length.  For all other conversions, <precision>
  13014.     is ignored.  <precision> is either a decimal number or a ■tt{*}
  13015.     character.  In the latter case, the precision is taken from the
  13016.     argument list.  If a decimal point without <precision> is given,
  13017.     the precision will be 0.
  13018.  
  13019.     <size> is either ■tt{h} for a ■tt{short} type (■tt{h} is available
  13020.     for the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, ■tt{x}, and ■tt{X}
  13021.     conversions and for ■tt{n}) or ■tt{l} for a ■tt{long} type (■tt{l}
  13022.     is available for the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, ■tt{x}, and
  13023.     ■tt{X} conversions and for ■tt{n}) or ■tt{L} for the ■tt{long
  13024.     double} type (■tt{L} is available for the ■tt{e}, ■tt{E}, ■tt{f},
  13025.     ■tt{g}, and ■tt{G} conversions).  If <size> is not specified, the
  13026.     default size is used.
  13027.  
  13028.     <type> (the conversion type) is one of the following characters:
  13029.  
  13030. ■list
  13031. ■item ■tt{c}
  13032.  
  13033.     Character.  The argument (■tt{char}, ■tt{signed char},
  13034.     ■tt{unsigned char} or ■tt{int}) is converted to an ■tt{unsigned
  13035.     char} and that character code will be printed.  <size> is ignored.
  13036.  
  13037. ■item ■tt{d}
  13038.  
  13039.     Signed decimal number.  The argument is converted to a signed
  13040.     integer and printed in decimal notation.  Use ■tt{%hd} to print a
  13041.     ■tt{short int}, ■tt{%ld} to print a ■tt{long int} and ■tt{%Ld} to
  13042.     print a ■tt{long long int}.
  13043.  
  13044. ■item ■tt{e}
  13045.  
  13046.     Floating-point number (■tt{double}), using ■tt{e} as exponent
  13047.     sign: ■tt{-#.###e+##}.  There's exactly one digit before the
  13048.     decimal point.  The number of digits after the decimal point is
  13049.     specified by <precision>.  If <precision> is missing, 6 digits are
  13050.     printed after the decimal point.  If <precision> is zero, no
  13051.     decimal point is printed unless the ■tt{#} flag is given.  The
  13052.     exponent has at least 2 digits.  If the number is zero, the
  13053.     exponent is ■tt{00}.  The decimal point character of the current
  13054.     locale is used.  A NaN is printed as `■tt{nan}', infinity as
  13055.     `■tt{inf}'.
  13056.  
  13057. ■item ■tt{E}
  13058.  
  13059.     Floating-point number (■tt{double}); same as ■tt{e}, except for
  13060.     ■tt{E} being used instead of ■tt{e} to introduce the exponent, and
  13061.     `■tt{NAN}' and `■tt{INF}' being printed instead of `■tt{nan}' and
  13062.     `■tt{inf}', respectively.
  13063.  
  13064. ■item ■tt{f}
  13065.  
  13066.     Floating-point number (■tt{double}) printed in fixed-point format.
  13067.     The number of digits after the decimal point is specified by
  13068.     <precision>.  If <precision> is missing, 6 digits are printed.  If
  13069.     <precision> is specified as zero, no decimal point is printed
  13070.     unless the ■tt{#} flag is given.  There's always at least one
  13071.     digit before the decimal point.  The decimal point character of
  13072.     the current locale is used.  A NaN is printed as `■tt{nan}',
  13073.     infinity as `■tt{inf}'.
  13074.  
  13075. ■item ■tt{F}
  13076.  
  13077.     Floating-point number (■tt{double}); same as ■tt{f}, except for
  13078.     `■tt{NAN}' and `■tt{INF}' being printed instead of `■tt{nan}' and
  13079.     `■tt{inf}', respectively.
  13080.  
  13081. ■item ■tt{g}
  13082.  
  13083.     Floating-point number (■tt{double}).  The number is printed in
  13084.     exponential or fixed-point format, depending on the magnitude.  If
  13085.     the number is an integer, it is printed as integer, without
  13086.     decimal point (unless the ■tt{#} flag is used).  If the exponent
  13087.     (of ■tt{e} format output) is less than -4 or greater than
  13088.     <precision> (the default is 6), type ■tt{e} is used.  Otherwise,
  13089.     type ■tt{f} is used.  In both cases, trailing zeros (and the
  13090.     decimal point, if it isn't followed by any digits) will be removed
  13091.     unless the ■tt{#} flag is used.  <precision> specifies the number
  13092.     of significant digits to print.  If <precision> is missing, 6
  13093.     significant digits are printed.  If <precision> is zero, a
  13094.     precision of 1 will be used instead.  The decimal point character
  13095.     of the current locale is used.  A NaN is printed as `■tt{nan}',
  13096.     infinity as `■tt{inf}'.
  13097.  
  13098. ■item ■tt{G}
  13099.  
  13100.     Floating-point number (■tt{double}); same as ■tt{g}, except for
  13101.     ■tt{E} being used instead of ■tt{e} to introduce the exponent, and
  13102.     `■tt{NAN}' and `■tt{INF}' being printed instead of `■tt{nan}' and
  13103.     `■tt{inf}', respectively.
  13104.  
  13105. ■item ■tt{i}
  13106.  
  13107.     Signed decimal number.  Same as ■tt{d}.
  13108.  
  13109. ■item ■tt{n}
  13110.  
  13111.     Store the number of characters formatted up to this point in the
  13112.     FORMAT string (■tt{int *}).  This `conversion' does not create any
  13113.     output.  Use ■tt{%hn} when passing a pointer to a ■tt{short int},
  13114.     ■tt{%ln} when passing a pointer to a ■tt{long int} and ■tt{%Ln}
  13115.     when passing a pointer to a ■tt{long long int}.
  13116.  
  13117. ■item ■tt{o}
  13118.  
  13119.     Unsigned octal number.  The argument is converted to an unsigned
  13120.     integer and printed in octal notation.  Use ■tt{%ho} to print an
  13121.     ■tt{unsigned short int}, ■tt{%lo} to print an ■tt{unsigned long
  13122.     int} and ■tt{%Lo} to print an ■tt{unsigned long long int}.  If the
  13123.     ■tt{#} flag is given, the precision will be increased to force the
  13124.     first digit of the result to be a zero.  If the number is zero and
  13125.     the precision is zero (after taking the ■tt{#} flag into account),
  13126.     the result will be empty.
  13127.  
  13128. ■item ■tt{p}
  13129.  
  13130.     Pointer (■tt{void *}).  The output format of a pointer is
  13131.     implementation-dependent.  In this implementation, ■tt{p} is
  13132.     equivalent to ■tt{x}.
  13133.  
  13134. ■item ■tt{s}
  13135.  
  13136.     String (■tt{char *}).  Print characters of the string until a null
  13137.     character is reached or <precision> (if specified) is exhausted.
  13138.     If <precision> is not specified, the string must have a
  13139.     terminating null character.  If <precision> is specified, the
  13140.     string length is limited by <precision>.
  13141.  
  13142. ■item ■tt{u}
  13143.  
  13144.     Unsigned decimal number.  The argument is converted to an unsigned
  13145.     integer and printed in decimal notation.  Use ■tt{%hu} to print an
  13146.     ■tt{unsigned short int}, ■tt{%lu} to print an ■tt{unsigned long
  13147.     int} and ■tt{%Lu} to print an ■tt{unsigned long long int}.
  13148.  
  13149. ■item ■tt{x}
  13150.  
  13151.     Unsigned hexadecimal number.  The argument is converted to an
  13152.     unsigned integer and printed in hexadecimal notation, using
  13153.     lower-case letters.  Use ■tt{%hx} to print an ■tt{unsigned short
  13154.     int}, ■tt{%lx} to print an ■tt{unsigned long int} and ■tt{%Lx} to
  13155.     print an ■tt{unsigned long long int}.  If the ■tt{#} flag is given
  13156.     and the number is non-zero, ■tt{0x} is prepended.
  13157.  
  13158. ■item ■tt{X}
  13159.  
  13160.     Hexadecimal number (■tt{unsigned int}); same as ■tt{x}, except for
  13161.     upper-case letters being used instead of lower-case letters.
  13162.  
  13163. ■endlist
  13164.  
  13165.     The behavior for other <type> characters is undefined, except for
  13166.     ■tt{%} immediately following ■tt{%}.
  13167.  
  13168. ■returnvalue
  13169.  
  13170.     printf() returns the number of characters written to stdout.  On
  13171.     error, printf() returns EOF.
  13172.  
  13173. ■implementation
  13174.  
  13175.     The ■tt{#} flag is ignored for the ■tt{c}, ■tt{d}, ■tt{i},
  13176.     ■tt{n}, ■tt{p}, ■tt{s} and ■tt{u} conversions.
  13177.  
  13178.     <size> can be ■tt{L} for the ■tt{long long} type (■tt{L} is
  13179.     available for the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, ■tt{x}, and
  13180.     ■tt{X} conversions and for ■tt{n}).  ■tt{ll} is an alternate
  13181.     spelling for ■tt{L}.
  13182.  
  13183. ■restrictions
  13184.  
  13185.     The output could be more accurate for floating point values.
  13186.  
  13187. ■hints
  13188.  
  13189.     Note that ■tt{%lf} is not a valid conversion specifier, use
  13190.     ■tt{%f} instead.  Contrast with scanf().
  13191.  
  13192. ■seealso fopen() fwrite() _itoa() scanf() setlocale() strftime()
  13193.  
  13194. ■samplecode
  13195. int year, month, day;
  13196. ...
  13197. printf ("%d/%.2d/%.2d\n", year, month, day);
  13198. ■endsamplecode
  13199.  
  13200.  
  13201. ■function profil()
  13202. ■compat UNIX *
  13203. ■headers
  13204. #include <unistd.h>
  13205. ■endheaders
  13206.  
  13207. ■param BUFF BUFSIZ OFFSET SCALE
  13208. ■prototype
  13209. int profil (void *BUFF, unsigned BUFSIZ, unsigned OFFSET, unsigned SCALE);
  13210. ■endprototype
  13211.  
  13212.     Sampling profiler.  This function is very experimental, therefore
  13213.     no documentation is provided.  profil() might disappear in the future.
  13214.  
  13215. ■returnvalue
  13216. ■description
  13217. ■item 0
  13218.     success
  13219. ■item -1
  13220.     error
  13221. ■enddescription
  13222.  
  13223. ■implementation
  13224.  
  13225.   The sampling frequency is 1024Hz under DOS, 1000Hz under OS/2.
  13226.   Counters are 32-bit words (under Unix, counters usually are 16-bit
  13227.   words).
  13228.  
  13229. ■restrictions
  13230.  
  13231.   When an attempt to update a counter causes an exception, the program
  13232.   will be terminated (under OS/2) or the system will be stopped (under
  13233.   DOS).
  13234.  
  13235.   Under OS/2, SCALE must be ■tt{0x4000}, ■tt{0x8000}, or ■tt{0x10000}.
  13236.  
  13237.   Under OS/2, profil() uses an unsupported and undocumented OS/2 API
  13238.   which has several bugs and may be dropped in future versions.  It
  13239.   has been tested on OS/2 3.0 only.
  13240.  
  13241.   profil() is not available with the system call library sys.lib
  13242.   (■hpt{-Zsys}).
  13243.  
  13244.  
  13245. ■function ptrace()
  13246. ■compat SysV *
  13247. ■headers
  13248. #include <sys/ptrace.h>
  13249. ■endheaders
  13250.  
  13251. ■param REQUEST PID ADDR DATA
  13252. ■prototype
  13253. int ptrace (int REQUEST, int PID, int ADDR, int DATA);
  13254. ■endprototype
  13255.  
  13256.     Debug a child process.  The child process is identified by PID.
  13257.     The following REQUEST codes are defined:
  13258.  
  13259. ■description
  13260.  
  13261. ■item PTRACE_TRACEME
  13262.  
  13263.     Not implemented -- use ■tt{spawn (P_DEBUG)} instead
  13264.  
  13265.  
  13266. ■item PTRACE_PEEKTEXT
  13267.  
  13268.     Read a 32-bit word from the text space of the child process.
  13269.     ADDR is the address of the word.  The word at ADDR is returned.
  13270.  
  13271. ■item PTRACE_PEEKDATA
  13272.  
  13273.     See PTRACE_PEEKTEXT.  On machines with separate data and text
  13274.     space, this request will read from the data space.
  13275.  
  13276. ■item PTRACE_PEEKUSER
  13277.  
  13278.     Read a 32-bit word from the process table of the child process.
  13279.     This can be used to read the registers of the child process.  See
  13280.     <sys/user.h> for details.
  13281.  
  13282. ■item PTRACE_POKETEXT
  13283.  
  13284.     Write the 32-bit word DATA to address ADDR of the text space of
  13285.     the child process.
  13286.  
  13287. ■item PTRACE_POKEDATA
  13288.  
  13289.     See PTRACE_POKETEXT.  On machines with separate data and text
  13290.     space, this request will write to the data space.
  13291.  
  13292. ■item PTRACE_POKEUSER
  13293.  
  13294.     Write a 32-bit word to the process table of the child process.
  13295.     This can be used to alter the registers of the child process.  See
  13296.     <sys/user.h> for details.  Not all registers can be modified.
  13297.  
  13298. ■item PTRACE_RESUME
  13299.  
  13300.     Resume the child process.  All pending signals will be canceled.
  13301.     If DATA is non-zero, the child process will continue as if it had
  13302.     received that signal.  The child process will run until another
  13303.     signal occurs.
  13304.  
  13305. ■item PTRACE_EXIT
  13306.  
  13307.     Kill the child process.
  13308.  
  13309. ■item PTRACE_STEP
  13310.  
  13311.     Execute the next instruction of the child process.  All pending
  13312.     signals will be canceled.  If DATA is non-zero, the child process
  13313.     will continue as if it had received that signal.  If
  13314.     _UF_PTRACE_MULTITHREAD is selected and PID includes a thread ID, one
  13315.     instruction of that thread only will be executed.  Otherwise, one
  13316.     instruction of any of the ready threads will be executed.
  13317.  
  13318. ■item PTRACE_SESSION
  13319.  
  13320.     If DATA is 0, select the session of the calling process.  If DATA
  13321.     is 1, select the child session.  If DATA is 2, the child session
  13322.     is automatically selected by the next PTRACE_STEP (on ■tt{CALL}
  13323.     instructions only) or PTRACE_RESUME command.  This request is emx
  13324.     specific and is ignored under DOS.
  13325.  
  13326. ■item PTRACE_NOTIFICATION
  13327.  
  13328.     Return the last notification and store data associated with that
  13329.     notification to the buffer pointed to by ADDR.  DATA is the size
  13330.     of the buffer.  If ADDR is NULL or if the size is too small, data
  13331.     won't be stored.  See below for notification codes and data
  13332.     structures.  This request is emx specific and is ignored under
  13333.     DOS.
  13334.  
  13335. ■item PTRACE_CONT
  13336.  
  13337.     Continue after a notification has been reported.  The previous
  13338.     PTRACE_RESUME or PTRACE_STEP request will be continued.  This
  13339.     request is emx specific and is ignored under DOS.
  13340.  
  13341. ■item PTRACE_THAW
  13342.  
  13343.     Thaw (enable) the thread identified by PID (which contains both a
  13344.     process ID and a thread ID).  This request is emx specific and is
  13345.     ignored under DOS.
  13346.  
  13347. ■item PTRACE_FREEZE
  13348.  
  13349.     Freeze (disable) the thread identified by PID (which contains both
  13350.     a process ID and a thread ID).  Note that an attempt to apply
  13351.     PTRACE_STEP to a frozen thread will result in an error.  This
  13352.     request is emx specific and is ignored under DOS.
  13353.  
  13354. ■item PTRACE_ATTACH
  13355.  
  13356.     Attach a debugger to the process identified by PID.  That process
  13357.     must be a direct or indirect child process of a process started
  13358.     with the P_DEBUGDESC flag set (see ■hpt{spawn*()}) and the
  13359.     debugger process debugging the direct parent process of the
  13360.     process identified by PID must still exist (and must continue to
  13361.     exist while the process identified by PID is being debugged).  For
  13362.     each process of this kind, at most one process (debugger) can
  13363.     attach to that process.
  13364.  
  13365. ■item PTRACE_DETACH
  13366.  
  13367.     Detach a debugger from the process identified by PID.  That
  13368.     process must have been attached to with PTRACE_ATTACH by the same
  13369.     process.  ADDR must be either 0 or 1.  If ADDR is 0, the process
  13370.     identified by PID will remain stopped (allowing another process to
  13371.     attach).  If ADDR is 1, the process identified by PID will resume
  13372.     execution.  The debugger process debugging the direct parent
  13373.     process of the process identified by PID must continue to exist
  13374.     during the entire lifetime of the process identified by PID,
  13375.     otherwise that process will be terminated prematurely or may
  13376.     block.
  13377.  
  13378. ■enddescription
  13379.  
  13380.     If _UF_PTRACE_NOTIFY or _UF_PTRACE_MULTITHREAD has been set with
  13381.     _uflags(), ptrace() will report creation and termination of
  13382.     threads and loading and freeing of modules (DLLs).  If a
  13383.     notification is pending, wait() and waitpid() report the child
  13384.     process as having been stopped by SIGPTRACENOTIFY.  In that case,
  13385.     use the PTRACE_NOTIFICATION request of ptrace() to get more
  13386.     information.  If successful, the PTRACE_NOTIFICATION request of
  13387.     ptrace() will report one of the following values:
  13388.  
  13389. ■description
  13390.  
  13391. ■item PTN_THREAD_NEW
  13392.  
  13393.     Creation of a new thread.  To obtain the thread ID, pass a pointer
  13394.     to an object of type ■tt{struct ptn_thread} in ADDR.  That
  13395.     structure is defined as follows:
  13396.  
  13397. ■example
  13398. struct ptn_thread
  13399. {
  13400.   unsigned tid;
  13401.   unsigned long reserved[31];
  13402. };
  13403. ■endexample
  13404.  
  13405.     The ■tt{tid} member will be set to the thread ID.  Creation of the
  13406.     initial thread (thread 1) is also reported.
  13407.  
  13408. ■item PTN_THREAD_END
  13409.  
  13410.     Termination of a thread.  To obtain the thread ID, pass a pointer
  13411.     to an object of type ■tt{struct ptn_thread} in ADDR.  The ■tt{tid}
  13412.     member of that structure will be set to the thread ID.
  13413.     Termination of the initial thread (thread 1) is also reported.
  13414.  
  13415. ■item PTN_MODULE_LOAD
  13416.  
  13417.     Loading of a module.  To obtain the module handle and the full
  13418.     path name of the module, pass a pointer to an object of type
  13419.     ■tt{struct ptn_module} in ADDR.  That structure is defined as
  13420.     follows:
  13421.  
  13422. ■example
  13423. struct ptn_module
  13424. {
  13425.   unsigned long hmte;
  13426.   unsigned long text_start;
  13427.   unsigned long text_size;
  13428.   unsigned long data_start;
  13429.   unsigned long data_size;
  13430.   unsigned long bss_start;
  13431.   unsigned long bss_size;
  13432.   unsigned long flags;
  13433.   unsigned long reserved[24];
  13434.   char name[260];
  13435. };
  13436. ■endexample
  13437.  
  13438.     The ■tt{hmte} member will be set to the module handle.  The
  13439.     ■tt{text_start} member will be set to the start address of the
  13440.     text segment, the ■tt{text_size} member will be set to the size of
  13441.     the text segment.  The ■tt{data_start} member will be set to the
  13442.     start address of the initialized data segment, the ■tt{data_size}
  13443.     member will be set to the size of the initialized data segment.
  13444.     The ■tt{bss_start} member will be set to the start address of the
  13445.     uninitialized data segment, the ■tt{bss_size} member will be set
  13446.     to the size of the uninitialized data segment.  The ■tt{flags}
  13447.     member will have zero or more of the following flags set:
  13448.     PTNMOD_DLL means that the module is a DLL (otherwise, it's the
  13449.     executable file of the program being debugged), PTNMOD_AOUT means
  13450.     that the module has been created with ld and emxbind (otherwise,
  13451.     it has been created with LINK386).  The ■tt{name} member will be
  13452.     set to the full path name of the module.
  13453.  
  13454. ■item PTN_MODULE_FREE
  13455.  
  13456.     Free a module (DLL).  To obtain the module handle and the full
  13457.     path name of the DLL, pass a pointer to an object of type
  13458.     ■tt{struct ptn_module} in ADDR.  The ■tt{hmte} member of that
  13459.     structure will be set to the module handle, the ■tt{name} member
  13460.     will be set to the full path name of the DLL.
  13461.  
  13462. ■item PTN_PROC_NEW
  13463.  
  13464.     Descendant process started.  This notification occurs only for
  13465.     processes started with the P_DEBUGDESC flag of ■hpt{spawn*()} and
  13466.     for child processes of such processes.  The notification is
  13467.     reported to the debugger process debugging the parent process of
  13468.     the new process.  To obtain the process ID and the full path name
  13469.     of the executable file of the descendant process, pass a pointer
  13470.     to an object of type ■tt{struct ptn_proc} in ADDR.  That structure
  13471.     is defined as follows:
  13472.  
  13473. ■example
  13474. struct ptn_proc
  13475. {
  13476.   unsigned pid;
  13477.   unsigned long flags;
  13478.   unsigned long fork_addr;
  13479.   unsigned long reserved[29];
  13480.   char name[260];
  13481. };
  13482. ■endexample
  13483.  
  13484.     The ■tt{pid} member of that structure will be set to the process
  13485.     ID of the descendant.  The ■tt{flags} member will have zero or
  13486.     more of the following flags set: PTNPROC_FORK means that the
  13487.     descendant has been created with fork(), PTNPROC_AOUT means that
  13488.     the executable file has been created with ld and emxbind
  13489.     (otherwise, it has been created with LINK386).  If PTNPROC_FORK is
  13490.     set, ■tt{fork_addr} will contain the return address of the
  13491.     ■tt{__fork()} system call, that is, the address at which the
  13492.     parent and child processes will continue.  If that address cannot
  13493.     be determined (should not happen), ■tt{fork_addr} will be zero.
  13494.     The ■tt{name} member will be set to the full path name of the
  13495.     executable file.
  13496.  
  13497.     The descendant process will block until a debugger process
  13498.     attaches to the descendant process with PTRACE_ATTACH.  To let the
  13499.     descendant process continue without being debugged, apply
  13500.     PTRACE_ATTACH and then PTRACE_DETACH to the descendant process.
  13501.     If the descendant process has been created with fork(), the parent
  13502.     process also blocks until the startup code of the descendant
  13503.     process has been executed.
  13504.  
  13505. ■enddescription
  13506.  
  13507.     If _UF_PTRACE_MULTITHREAD has been selected with _uflags(),
  13508.     ptrace() supports debugging of multithread procdesses.  In that
  13509.     case, the PID argument of ptrace() contains both a process ID and
  13510.     a thread ID.  The PTRACE_PEEKUSER, PTRACE_POKEUSER, and
  13511.     PTRACE_STEP requests apply to the specified thread only.
  13512.     Moreover, wait() and waitpid() will return both a process ID and a
  13513.     thread ID.  The following macros are used to deal with combined
  13514.     process IDs and thread IDs:
  13515.  
  13516. ■description
  13517.  
  13518. ■item PTRACE_GETPID
  13519.  
  13520.     Extract the process ID from the value passed as argument.
  13521.  
  13522. ■item PTRACE_GETTID
  13523.  
  13524.     Extract the thread ID from the value passed as argument.
  13525.  
  13526. ■item PTRACE_PIDTID
  13527.  
  13528.     Build the PID argument for ptrace(): the first argument is the
  13529.     process ID, the second argument is the thread ID.
  13530.  
  13531. ■enddescription
  13532.  
  13533. ■returnvalue
  13534.  
  13535.     See above.  As -1 is a legal return value for the ■tt{PTRACE_PEEK}
  13536.     requests, you should set errno to 0 before calling ptrace() and
  13537.     check errno after the call.
  13538.  
  13539. ■restrictions
  13540.  
  13541.     Under DOS, a process can debug only one child process.  ptrace()
  13542.     is not available with the system call library sys.lib
  13543.     (■hpt{-Zsys}).  Under OS/2, the only signal number which can be
  13544.     passed in DATA for PTRACE_RESUME and PTRACE_STEP is the one of the
  13545.     signal by which the child process has been stopped.
  13546.     Notifications, multithread processes, and debugging of descendants
  13547.     are not supported under DOS.  PTRACE_ATTACH works only under
  13548.     certain circumstances defined above.
  13549.  
  13550. ■seealso spawn*() _uflags() wait() waitpid()
  13551.  
  13552.  
  13553. ■function putc()
  13554. ■compat C90
  13555. ■headers
  13556. #include <stdio.h>
  13557. ■endheaders
  13558.  
  13559. ■param C STREAM
  13560. ■prototype
  13561. int putc (int C, FILE *STREAM);
  13562. ■endprototype
  13563.  
  13564.     Write the character C (converted to an ■tt{unsigned char}) to the
  13565.     output stream STREAM and advance the file position indicator of
  13566.     the stream (if defined).
  13567.  
  13568.     putc() may be implemented as macro, in contrast to fputc().  In
  13569.     consequence, putc() may evaluate its arguments more than once.
  13570.  
  13571. ■returnvalue
  13572.  
  13573.     putc() returns the character written.  On error, putc() sets the
  13574.     error indicator of the stream and returns EOF.
  13575.  
  13576. ■implementation
  13577.  
  13578.     putc() is implemented as in-line function for single-thread
  13579.     programs.
  13580.  
  13581. ■hints
  13582.  
  13583.     Use putc() instead of fputc() if you want to write a lot of
  13584.     characters.
  13585.  
  13586.     The arguments of putc() should not be expressions with side
  13587.     effects.
  13588.  
  13589. ■seealso fputc() putchar()
  13590.  
  13591.  
  13592. ■function putchar()
  13593. ■compat C90
  13594. ■headers
  13595. #include <stdio.h>
  13596. ■endheaders
  13597.  
  13598. ■param C
  13599. ■prototype
  13600. int putchar (int C);
  13601. ■endprototype
  13602.  
  13603.     ■tt{putchar (c)} is equivalent to ■tt{putc (c, stdout)}.
  13604.  
  13605. ■returnvalue
  13606.  
  13607.     putchar() returns the character written.  On error, putchar() sets
  13608.     the error indicator of stdout and returns EOF.
  13609.  
  13610. ■implementation
  13611.  
  13612.     putchar() is implemented as in-line function for single-thread
  13613.     programs.
  13614.  
  13615. ■hints
  13616.  
  13617.     Use putchar() instead of fputc() if you want to write a lot of
  13618.     characters to stdout.
  13619.  
  13620.     The argument of putchar() should not be an expression with side
  13621.     effects.
  13622.  
  13623. ■seealso fputc() putc()
  13624.  
  13625.  
  13626. ■function putenv()
  13627. ■compat BSD
  13628. ■headers
  13629. #include <stdlib.h>
  13630. ■endheaders
  13631.  
  13632. ■param STRING NAME VALUE
  13633. ■param STRING
  13634. ■prototype
  13635. int putenv (const char *STRING);
  13636. ■endprototype
  13637.  
  13638.     Put a value into the environment of the calling process.  STRING
  13639.     is a pointer to a string of the form
  13640.  
  13641. ■typewriter
  13642.   "■pa{NAME}=■pa{VALUE}"
  13643. ■endtypewriter
  13644.  
  13645.     where NAME is the name of the environment variable and VALUE is
  13646.     the value of the environment variable.  If the environment
  13647.     variable NAME already exists, the current value is replaced by the
  13648.     new value, VALUE.  If NAME is not already in the environment,
  13649.     STRING is put into the environment.  Do not free or reuse the
  13650.     string pointed to by STRING after calling putenv().  Using an auto
  13651.     variable is also a bad idea.  After calling putenv(), do not use
  13652.     the ■pa{ENVP} argument of main().  Use environ instead.
  13653.  
  13654. ■returnvalue
  13655. ■description
  13656. ■item 0
  13657.     success
  13658. ■item -1
  13659.     error
  13660. ■enddescription
  13661.  
  13662. ■seealso getenv()
  13663.  
  13664.  
  13665. ■function puts()
  13666. ■compat C90
  13667. ■headers
  13668. #include <stdio.h>
  13669. ■endheaders
  13670.  
  13671. ■param STRING
  13672. ■prototype
  13673. int puts (const char *STRING);
  13674. ■endprototype
  13675.  
  13676.     Write the string pointed to by STRING followed by a newline (LF)
  13677.     character (which is translated to CR/LF if stdout is in text mode)
  13678.     to the stdout stream.
  13679.  
  13680. ■returnvalue
  13681.  
  13682.     On failure, puts() returns EOF.  Otherwise, puts() returns a
  13683.     non-negative value.
  13684.  
  13685. ■seealso fputs() fgets()
  13686.  
  13687.  
  13688. ■function putw()
  13689. ■compat UNIX
  13690. ■headers
  13691. #include <stdio.h>
  13692. ■endheaders
  13693.  
  13694. ■param X STREAM
  13695. ■prototype
  13696. int putw (int X, FILE *STREAM);
  13697. ■endprototype
  13698.  
  13699.     Write the word (■tt{int}) X to STREAM and return it.  Avoid using
  13700.     this function.
  13701.  
  13702. ■returnvalue
  13703.  
  13704.     putw() returns X.  On error, getw() returns -1.  As -1 is also a
  13705.     possible word value, you have to use ferror() to recognize an
  13706.     error condition.
  13707.  
  13708. ■seealso getw() fwrite()
  13709.  
  13710.  
  13711. ■function qsort()
  13712. ■compat C90
  13713.  
  13714. ■headers
  13715. #include <stdlib.h> /* use this */
  13716. #include <search.h> /* or this */
  13717. ■endheaders
  13718.  
  13719. ■param BASE NUM WIDTH COMPARE X1 X2
  13720. ■prototype
  13721. void qsort (void *BASE, size_t NUM, size_t WIDTH,
  13722.             int (*COMPARE)(const void *X1, const void *X2));
  13723. ■endprototype
  13724.  
  13725.    Sort an array.  BASE is a pointer to the beginning of the array.
  13726.    The array contains NUM elements of WIDTH bytes each.  COMPARE is
  13727.    called to compare the two elements pointed to by X1 and X2.
  13728.    COMPARE should return a negative value, if element X1 is less than
  13729.    element X2, zero, if element X1 equals element X2, and a positive
  13730.    value if element X1 is greater than element X2.
  13731.  
  13732.    ■bf{Note:} qsort() is not stable: the order of equal elements is
  13733.    undefined.  To make qsort() stable, add a field to the sort key
  13734.    which holds the index of the element.
  13735.  
  13736.  
  13737. ■function raise()
  13738. ■compat C90
  13739. ■headers
  13740. #include <signal.h>
  13741. ■endheaders
  13742.  
  13743. ■param SIG
  13744. ■prototype
  13745. int raise (int SIG);
  13746. ■endprototype
  13747.  
  13748.     Generate the signal SIG.  If the signal SIG is blocked, the signal
  13749.     will be made pending, to be delivered when it is unblocked.
  13750.  
  13751.     Each thread has its own set of signal handlers.  raise() generates
  13752.     the signal in the thread in which it is called.  Use kill() to
  13753.     send the signal to the main thread (thread 1).
  13754.  
  13755.     See section ■ref{signal processing} for details on
  13756.     ■hpt{signal processing}.
  13757.  
  13758. ■returnvalue
  13759.  
  13760.     If successful, raise() returns 0.  Otherwise -1 is returned and
  13761.     errno is set.
  13762.  
  13763. ■errors
  13764. ■description
  13765. ■item EINVAL
  13766.     SIG is not a valid signal number
  13767. ■enddescription
  13768.  
  13769. ■seealso abort() kill() sigaction() signal()
  13770.  
  13771.  
  13772. ■function rand() srand()
  13773. ■compat C90
  13774. ■headers
  13775. #include <stdlib.h>
  13776. ■endheaders
  13777.  
  13778. ■param SEED
  13779. ■prototype
  13780. int rand (void);
  13781. void srand (unsigned int SEED);
  13782. ■endprototype
  13783.  
  13784.     rand() returns a pseudo-random number in the range 0 through
  13785.     RAND_MAX (32767).  RAND_MAX is defined in <stdlib.h>.  srand()
  13786.     initializes the sequence of random numbers.  The initial SEED
  13787.     value (if srand() is not called) is 1.
  13788.  
  13789.     The quality of the random numbers generated by rand() is poor,
  13790.     though it is not as poor as in other implementations of rand().
  13791.     If you need good random numbers, you should use random(), which is
  13792.     in the BSD library.
  13793.  
  13794.     In programs linked with the multithread libraries (-Zmt, -Zmts, or
  13795.     -Zmtd), rand() will generate identical sequences of random numbers
  13796.     in all the threads and srand() will affect only the thread in
  13797.     which it is called.  The behavior of rand() is undefined in
  13798.     multithread programs linked with single-thread libraries.
  13799.  
  13800.     You must not call rand() or srand() in a thread created by
  13801.     DosCreateThread.
  13802.  
  13803. ■returnvalue
  13804.  
  13805.     See above.
  13806.  
  13807. ■if text
  13808. ■c ■seealso _beginthread() emxbsd.doc
  13809. ■else
  13810. ■c ■seealso _beginthread() random()
  13811. ■endif
  13812.  
  13813.  
  13814. ■function read()
  13815. ■compat UNIX
  13816. ■headers
  13817. #include <io.h>
  13818. ■endheaders
  13819.  
  13820. ■param HANDLE BUF NBYTE
  13821. ■prototype
  13822. int read (int HANDLE, void *BUF, size_t NBYTE);
  13823. ■endprototype
  13824.  
  13825.     Read up to NBYTE characters from file HANDLE to the buffer BUF.
  13826.     The number of characters read is returned.  If there is an error,
  13827.     -1 is returned.  The return value may be less than NBYTE.  For
  13828.     instance, this happens if the end of the file is reached.  See
  13829.     also `■hpt{General terminal interface}'.  If HANDLE is 0 and
  13830.     HANDLE refers to the keyboard and O_NONBLOCK (alias O_NDELAY) has
  13831.     been set with fcntl() for HANDLE and the IDEFAULT and ICANON bits
  13832.     have been reset with ioctl() for HANDLE, -1 is returned and errno
  13833.     is set to EAGAIN if the call to read() would block.  Even if there
  13834.     is some data available, but not enough with respect to VMIN, -1 is
  13835.     returned.
  13836.  
  13837.     If HANDLE has been opened in text mode, CR/LF pairs are translated
  13838.     to newline characters and a Ctrl-Z character is discarded if it is
  13839.     the last character of the file.
  13840.  
  13841. ■returnvalue
  13842.  
  13843.     See above.
  13844.  
  13845. ■seealso open() setmode() write()
  13846.  
  13847.  
  13848. ■function _read_kbd()
  13849. ■compat emx *
  13850. ■headers
  13851. #include <stdlib.h>
  13852. #include <sys/kbdscan.h>  /* optional, for extended scan codes */
  13853. ■endheaders
  13854.  
  13855. ■param ECHO WAIT SIG
  13856. ■prototype
  13857. int _read_kbd (int ECHO, int WAIT, int SIG);
  13858. ■endprototype
  13859.  
  13860.     Get a character from the keyboard.  Extended codes are preceded by
  13861.     a null character (call _read_kbd() again!), the scan codes are
  13862.     defined in <sys/kbdscan.h>.  If ECHO is non-zero, input will be
  13863.     echoed, if WAIT is non-zero, _read_kbd() will wait until a
  13864.     character is available, if WAIT is zero and no character is
  13865.     available, _read_kbd() will return -1, if SIG is zero, Ctrl-C will
  13866.     be ignored.  Examples (taken from <conio.h>):
  13867.  
  13868. ■example
  13869. #define getch()  _read_kbd (0, 1, 0)
  13870. #define getche() _read_kbd (1, 1, 0)
  13871. ■endexample
  13872.  
  13873.     Please use the ■hpt{general terminal interface} instead.
  13874.  
  13875.     It's important to call _read_kbd() again if _read_kbd() returns 0.
  13876.     To see what happens if you don't, type Ctrl-S F10 under DOS.
  13877.  
  13878. ■returnvalue
  13879.  
  13880.     See above.
  13881.  
  13882. ■c ■seealso ioctl() read() <conio.h>
  13883. ■seealso ioctl() read()
  13884.  
  13885.  
  13886. ■function realloc()
  13887. ■compat C90
  13888. ■headers
  13889. #include <stdlib.h>
  13890. ■endheaders
  13891.  
  13892. ■param MEM SIZE
  13893. ■prototype
  13894. void *realloc (void *MEM, size_t SIZE);
  13895. ■endprototype
  13896.  
  13897.     Reallocate the block of memory pointed to by MEM, making it big
  13898.     enough to hold SIZE bytes.  If MEM is NULL, a new block of memory
  13899.     is allocated by calling malloc().  Otherwise, MEM must be a
  13900.     pointer returned by calloc(), malloc(), realloc(), _ucalloc(),
  13901.     _umalloc(), or _utcalloc().  In this case, the size
  13902.     of the block pointer to by MEM is changed to SIZE.  If the block
  13903.     pointed to by MEM cannot be expanded in-place, it is moved.  If
  13904.     MEM is non-■tt{NULL} and SIZE is zero, the block is freed and NULL
  13905.     is returned.  A pointer to the new, resized block of memory is
  13906.     returned.  If there is not enough memory available, NULL is
  13907.     returned.
  13908.  
  13909. ■returnvalue
  13910.  
  13911.     realloc() returns MEM (if the block could be resized without
  13912.     moving), a pointer to a newly allocated block of memory, or NULL
  13913.     (if there wasn't enough memory, or if MEM is non-■tt{NULL} and
  13914.     SIZE is zero).
  13915.  
  13916. ■implementation
  13917.  
  13918.     Some implementations of realloc() can be applied to blocks freed
  13919.     by free() as long as calloc(), malloc(), and realloc() have not
  13920.     been called since freeing the block.  This implementation of
  13921.     realloc() cannot be applied to freed blocks.
  13922.  
  13923.     If MEM is not NULL and the block cannot be moved, realloc() will
  13924.     allocate the new block in MEM's heap.  If MEM is NULL, realloc()
  13925.     will allocate memory from the default heap of the current thread.
  13926.  
  13927. ■seealso malloc() _mheap() _trealloc() _udefault()
  13928.  
  13929.  
  13930. ■function _remext()
  13931. ■compat emx
  13932. ■headers
  13933. #include <stdlib.h>
  13934. ■endheaders
  13935.  
  13936. ■param PATH
  13937. ■prototype
  13938. void _remext (char *PATH);
  13939. ■endprototype
  13940.  
  13941.     Remove the extension from the file name pointed to by PATH.  If
  13942.     the last member of the string starts with a dot
  13943.     (■tt{"/usr/mattes/.profile"}, for instance) the string isn't
  13944.     modified.
  13945.  
  13946.     _remext() properly handles DBCS characters.
  13947.  
  13948. ■seealso _defext() _getext() _nls_init() _splitpath()
  13949.  
  13950.  
  13951. ■function remove()
  13952. ■compat C90
  13953.  
  13954. ■headers
  13955. #include <stdio.h>      /* use this */
  13956. #include <io.h>         /* or this */
  13957. ■endheaders
  13958.  
  13959. ■param NAME
  13960. ■prototype
  13961. int remove (const char *NAME);
  13962. ■endprototype
  13963.  
  13964.     Delete a file.  NAME is a pointer to a string containing the name
  13965.     of the file to be deleted.  Under OS/2 and DOS, remove() and
  13966.     unlink() are equivalent.
  13967.  
  13968. ■returnvalue
  13969. ■description
  13970. ■item 0
  13971.     success
  13972. ■item -1
  13973.     error
  13974. ■enddescription
  13975.  
  13976. ■implementation
  13977.  
  13978.     If the read-only attribute of the file is set, remove() sets errno
  13979.     to EPERM and returns -1.
  13980.  
  13981.     If the file is open in any process, remove() sets errno to EACCES
  13982.     and returns -1.
  13983.  
  13984. ■seealso unlink()
  13985.  
  13986.  
  13987. ■function rename()
  13988. ■compat C90
  13989.  
  13990. ■headers
  13991. #include <stdio.h>      /* use this */
  13992. #include <io.h>         /* or this */
  13993. ■endheaders
  13994.  
  13995. ■param OLD_NAME NEW_NAME
  13996. ■prototype
  13997. int rename (const char *OLD_NAME, const char *NEW_NAME);
  13998. ■endprototype
  13999.  
  14000.     Rename the file or directory whose name is in the string pointed
  14001.     to by OLD_NAME to the name pointed to by NEW_NAME.  Moving a file
  14002.     to a different directory on the same drive is possible.  If a file
  14003.     or directory with the name pointed to by NEW_NAME already exists,
  14004.     rename() fails.
  14005.  
  14006. ■returnvalue
  14007. ■description
  14008. ■item 0
  14009.     success
  14010. ■item -1
  14011.     error
  14012. ■enddescription
  14013.  
  14014. ■implementation
  14015.  
  14016.     If the file is open in any process, rename() sets errno to EACCES
  14017.     and returns -1.
  14018.  
  14019. ■restrictions
  14020.  
  14021.     rename() may set errno to EACCES instead of EEXIST if a file or
  14022.     directory with the name pointed to by NEW_NAME already exists.
  14023.     (Why does OS/2 return ERROR_ACCESS_DENIED instead of
  14024.     ERROR_FILE_EXISTS?)
  14025.  
  14026. ■function _response()
  14027. ■compat emx
  14028. ■headers
  14029. #include <stdlib.h>
  14030. ■endheaders
  14031.  
  14032. ■param ARGCP ARGVP
  14033. ■prototype
  14034. void _response (int *ARGCP, char ***ARGVP);
  14035. ■endprototype
  14036.  
  14037.     Expand response files.  If you want response files
  14038.     (■tt{@filename}, the file ■tt{filename} contains a list of
  14039.     arguments, one per line) to be expanded, call
  14040.  
  14041. ■example
  14042. _response (&argc, &argv);
  14043. ■endexample
  14044.  
  14045.     at the beginning of main().  Response file arguments enclosed in
  14046.     double quotes won't be expanded.  If a response file cannot be
  14047.     opened, the argument is kept unchanged.
  14048.  
  14049. ■seealso _envargs() main() _wildcard()
  14050.  
  14051.  
  14052. ■function rewind()
  14053. ■compat C90
  14054. ■headers
  14055. #include <stdio.h>
  14056. ■endheaders
  14057.  
  14058. ■param STREAM
  14059. ■prototype
  14060. void rewind (FILE *STREAM);
  14061. ■endprototype
  14062.  
  14063.     Move the file pointer of STREAM to the beginning of the file and
  14064.     clear the error and end-of-file indicators.
  14065.  
  14066. ■seealso fseek()
  14067.  
  14068.  
  14069. ■function rindex()
  14070. ■compat BSD
  14071. ■headers
  14072. #include <strings.h>
  14073. ■endheaders
  14074.  
  14075. ■param STRING C
  14076. ■prototype
  14077. char *rindex (const char *STRING, int C);
  14078. ■endprototype
  14079.  
  14080.     Return a pointer to the last occurrence of the character C in the
  14081.     null-terminated string pointed to by STRING.  If there is no
  14082.     character C in the string pointed to by STRING, NULL is returned.
  14083.     If C is 0, a pointer to the terminating null character of the
  14084.     string pointed to by STRING is returned.
  14085.  
  14086. ■returnvalue
  14087.  
  14088.     See above.
  14089.  
  14090. ■seealso index() strrchr()
  14091.  
  14092.  
  14093. ■function rint() rintl()
  14094. ■compat C9X
  14095. ■headers
  14096. #include <math.h>
  14097. ■endheaders
  14098.  
  14099. ■param X
  14100. ■prototype
  14101. double rint (double X);
  14102. long double rintl (long double X);
  14103. ■endprototype
  14104.  
  14105.     Return as floating-point number the integer that is nearest to X.
  14106.     ■tt{rint (}■pa{X}■tt{)} is even if there's a tie, that is if
  14107.  
  14108.     rintl() uses the ■tt{long double} format.
  14109.  
  14110. ■typewriter
  14111.   fabs (rint (■pa{X}) - ■pa{X}) == 0.5
  14112. ■endtypewriter
  14113.  
  14114. ■returnvalue
  14115.  
  14116.     See above.
  14117.  
  14118. ■seealso ceil() floor() trunc()
  14119.  
  14120.  
  14121. ■function rmdir()
  14122. ■compat BSD
  14123. ■headers
  14124. #include <stdlib.h>
  14125. ■endheaders
  14126.  
  14127. ■param NAME
  14128. ■prototype
  14129. int rmdir (const char *NAME);
  14130. ■endprototype
  14131.  
  14132.     Remove the directory whose name is in the string pointed to by
  14133.     NAME.  Only one directory is removed in one step.  If the
  14134.     directory (or a subdirectory thereof) is the current working
  14135.     directory of a process, it cannot be removed.
  14136.  
  14137. ■returnvalue
  14138. ■description
  14139. ■item 0
  14140.     success
  14141. ■item -1
  14142.     error
  14143. ■enddescription
  14144.  
  14145. ■seealso mkdir()
  14146.  
  14147.  
  14148. ■function _rmtmp()
  14149. ■compat UNIX
  14150. ■headers
  14151. #include <stdio.h>
  14152. ■endheaders
  14153.  
  14154. ■prototype
  14155. int _rmtmp (void);
  14156. ■endprototype
  14157.  
  14158.     Close and delete the files created by tmpfile() in the current
  14159.     working directory.  It must be used only in the directory in which
  14160.     tmpfile() created the temporary files.
  14161.  
  14162. ■returnvalue
  14163.  
  14164.     _rmtmp() returns the number of closed (and deleted) files.
  14165.  
  14166. ■seealso tmpfile()
  14167.  
  14168.  
  14169. ■function _rmutex_available()
  14170. ■compat emx
  14171. ■headers
  14172. #include <sys/builtin.h>
  14173. #include <sys/fmutex.h>
  14174. #include <sys/rmutex.h>
  14175. ■endheaders
  14176.  
  14177. ■param SEM
  14178. ■prototype
  14179. int _rmutex_available (_rmutex *SEM);
  14180. ■endprototype
  14181.  
  14182.     Check if the _rmutex semaphore pointed to by SEM is available or
  14183.     owned, without changing the state of the semaphore and without
  14184.     blocking.  Return zero if the semaphore is owned, return a
  14185.     non-zero value if the semaphore is available.  Note that
  14186.     _rmutex_available() just returns a snapshot of the state of the
  14187.     semaphore; in presence of other threads or, in case of a shared
  14188.     semaphore, other processes, the state may change at any time, even
  14189.     before _rmutex_available() returns. This function can be used to
  14190.     avoid deadlock.
  14191.  
  14192. ■returnvalue
  14193.  
  14194.     _rmutex_available() returns a non-zero value if the semaphore is
  14195.     available.  _rmutex_available() returns 0 if the semaphore is
  14196.     owned.  The return value is undefined if the object pointed to by
  14197.     SEM has not been initialized by _rmutex_create().
  14198.  
  14199. ■seealso _fmutex_available() _rmutex_close() _rmutex_create() _rmutex_open() _rmutex_release() _rmutex_request()
  14200.  
  14201.  
  14202. ■function _rmutex_close() _rmutex_checked_close()
  14203. ■compat emx
  14204. ■headers
  14205. #include <sys/builtin.h>
  14206. #include <sys/fmutex.h>
  14207. #include <sys/rmutex.h>
  14208. ■endheaders
  14209.  
  14210. ■param SEM
  14211. ■prototype
  14212. unsigned _rmutex_close (_rmutex *SEM);
  14213. void _rmutex_checked_close (_rmutex *SEM);
  14214. ■endprototype
  14215.  
  14216.     Close an _rmutex semaphore.  SEM should point to an _rmutex object
  14217.     initialized by _rmutex_create().  If there have been ■pa{N} calls
  14218.     to ■hpt{_rmutex_open()} for this semaphore, ■pa{N}+1 calls to
  14219.     _rmutex_close() are required to destroy the semaphore, one call
  14220.     for ■hpt{_rmutex_create()} and one call per _rmutex_open().  The
  14221.     semaphore can no longer be used after it has been destroyed.
  14222.  
  14223.     _rmutex_checked_close() does not return an error code; it calls
  14224.     abort() on failure.
  14225.  
  14226. ■returnvalue
  14227.  
  14228.     _rmutex_close() returns 0 if successful.  Otherwise,
  14229.     _rmutex_close() returns an OS/2 error code defined in <os2.h> such
  14230.     as ERROR_INVALID_HANDLE.  Under DOS, _rmutex_close() always
  14231.     returns 0.
  14232.  
  14233. ■seealso abort() atexit() _fmutex_close() _rmutex_available() _rmutex_create() _rmutex_open() _rmutex_release() _rmutex_request()
  14234.  
  14235.  
  14236. ■function _rmutex_create() _rmutex_checked_create()
  14237. ■compat emx
  14238. ■headers
  14239. #include <sys/builtin.h>
  14240. #include <sys/fmutex.h>
  14241. #include <sys/rmutex.h>
  14242. ■endheaders
  14243.  
  14244. ■param SEM FLAGS
  14245. ■prototype
  14246. unsigned _rmutex_create (_rmutex *SEM, unsigned FLAGS);
  14247. void _rmutex_checked_create (_rmutex *SEM, unsigned FLAGS);
  14248. ■endprototype
  14249.  
  14250.     Create an _rmutex semaphore.  SEM points to the _rmutex object to
  14251.     be initialized.  The semaphore is local to the process if FLAGS is
  14252.     0.  The semaphore can be shared by multiple processes if FLAGS is
  14253.     _FMC_SHARED.  A shared _rmutex semaphore must be located in shared
  14254.     memory (that is, SEM must point to an object in shared memory).
  14255.  
  14256.     _rmutex_checked_create() does not return an error code; it calls
  14257.     abort() on failure.
  14258.  
  14259. ■returnvalue
  14260.  
  14261.     _rmutex_create() returns 0 if successful.  Otherwise,
  14262.     _rmutex_create() returns an OS/2 error code defined in <os2.h>
  14263.     such as ERROR_TOO_MANY_HANDLES.  Under DOS, _rmutex_create()
  14264.     always returns 0.
  14265.  
  14266. ■seealso abort() _fmutex_create() _rmutex_available() _rmutex_close() _rmutex_dummy() _rmutex_open() _rmutex_release() _rmutex_request()
  14267.  
  14268.  
  14269. ■function _rmutex_dummy()
  14270. ■compat emx
  14271. ■headers
  14272. #include <sys/builtin.h>
  14273. #include <sys/fmutex.h>
  14274. #include <sys/rmutex.h>
  14275. ■endheaders
  14276.  
  14277. ■param SEM
  14278. ■prototype
  14279. void _rmutex_dummy (_rmutex *SEM);
  14280. ■endprototype
  14281.  
  14282.     Create a dummy _rmutex semaphore.  SEM points to the _rmutex
  14283.     object to be initialized.  Behavior is undefined if ownership of a
  14284.     dummy _rmutex semaphore is requested when the semaphore is owned.
  14285.     _rmutex_close() must not be called on a dummy _rmutex semaphore.
  14286.  
  14287. ■seealso _fmutex_dummy() _rmutex_create()
  14288.  
  14289.  
  14290. ■function _rmutex_open() _rmutex_checked_open()
  14291. ■compat emx
  14292. ■headers
  14293. #include <sys/builtin.h>
  14294. #include <sys/fmutex.h>
  14295. #include <sys/rmutex.h>
  14296. ■endheaders
  14297.  
  14298. ■param SEM
  14299. ■prototype
  14300. unsigned _rmutex_open (_rmutex *SEM);
  14301. void _rmutex_checked_open (_rmutex *SEM);
  14302. ■endprototype
  14303.  
  14304.     Open an _rmutex semaphore.  SEM should point to an _rmutex object
  14305.     initialized by ■hpt{_rmutex_create()}.  _rmutex_open() is used to
  14306.     obtain access to a shared _rmutex semaphore created by another
  14307.     process.  All threads of the process which called _rmutex_create()
  14308.     have access to the semaphore without calling _rmutex_open().  Call
  14309.     ■hpt{_rmutex_close()} when you no longer need access to the
  14310.     semaphore.
  14311.  
  14312.     _rmutex_checked_open() does not return an error code; it calls
  14313.     abort() on failure.
  14314.  
  14315. ■returnvalue
  14316.  
  14317.     _rmutex_open() returns 0 if successful.  Otherwise, _rmutex_open()
  14318.     returns an OS/2 error code defined in <os2.h> such as
  14319.     ERROR_INVALID_HANDLE.  Under DOS, _rmutex_open() always returns 0.
  14320.  
  14321. ■seealso abort() atexit() _fmutex_open() _rmutex_available() _rmutex_close() _rmutex_create() _rmutex_release() _rmutex_request()
  14322.  
  14323.  
  14324. ■function _rmutex_release() _rmutex_checked_release()
  14325. ■compat emx
  14326. ■headers
  14327. #include <sys/builtin.h>
  14328. #include <sys/fmutex.h>
  14329. #include <sys/rmutex.h>
  14330. ■endheaders
  14331.  
  14332. ■param SEM
  14333. ■prototype
  14334. unsigned _rmutex_release (_rmutex *SEM);
  14335. void _rmutex_checked_release (_rmutex *SEM);
  14336. ■endprototype
  14337.  
  14338.     Relinquish ownership of the _rmutex semaphore pointed to by SEM.
  14339.     If another thread blocks in ■hpt{_rmutex_request()} for this
  14340.     semaphore, _rmutex_release() will unblock one of the blocking
  14341.     threads.  The semaphore should be owned when _rmutex_release() is
  14342.     called.  Though not strictly necessary, ownership of the semaphore
  14343.     should have been requested by the same thread.
  14344.  
  14345.     _rmutex_checked_release() does not return an error code; it calls
  14346.     abort() on failure.  Note that _rmutex_checked_release() is slower
  14347.     than _rmutex_release() because it is not inlined.
  14348.  
  14349. ■returnvalue
  14350.  
  14351.     _rmutex_release() returns 0 if successful.  Otherwise,
  14352.     _rmutex_release() returns an OS/2 error code defined in <os2.h>
  14353.     such as ERROR_TOO_MANY_HANDLES.
  14354.  
  14355. ■seealso abort() __cxchg() _fmutex_release() _rmutex_available() _rmutex_close() _rmutex_create() _rmutex_open() _rmutex_request()
  14356.  
  14357.  
  14358. ■function _rmutex_request() _rmutex_checked_request()
  14359. ■compat emx
  14360. ■headers
  14361. #include <sys/builtin.h>
  14362. #include <sys/fmutex.h>
  14363. #include <sys/rmutex.h>
  14364. ■endheaders
  14365.  
  14366. ■param SEM FLAGS
  14367. ■prototype
  14368. unsigned _rmutex_request (_rmutex *SEM, unsigned FLAGS);
  14369. void _rmutex_checked_request (_rmutex *SEM, unsigned FLAGS);
  14370. ■endprototype
  14371.  
  14372.     Request ownership of the _rmutex semaphore pointed to by SEM.  If
  14373.     FLAGS is 0, _rmutex_request() returns ERROR_INTERRUPT if
  14374.     interrupted by a signal while blocking.  FLAGS is zero or a set of
  14375.     flags combined with the ■tt{|} operator.  If FLAGS includes
  14376.     _FMR_IGNINT, _rmutex_request() does not return if a signal occurs
  14377.     while blocking.  If FLAGS includes _FMR_NOWAIT and the semaphore
  14378.     is owned, _rmutex_request() returns immediately ERROR_MUTEX_OWNED.
  14379.  
  14380.     _rmutex_checked_request() does not return an error code; it calls
  14381.     abort() on failure.  Note that _rmutex_checked_request() is slower
  14382.     than _rmutex_request() because it is not inlined.
  14383.  
  14384.     If the semaphore is available, it will be set to owned and
  14385.     _rmutex_request() will return immediately.  If the semaphore is
  14386.     owned, _rmutex_request() will block while the semaphore is owned.
  14387.     When ■hpt{_rmutex_release()} is called for the semaphore, one of
  14388.     the threads blocking in _rmutex_request() for this semaphore will
  14389.     wake up and gain ownership of the semaphore.
  14390.  
  14391.     Note that ownership of an _rmutex semaphore is not tied to a
  14392.     thread, that is, it's not a thread which owns the semaphore.  This
  14393.     is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
  14394.     occur if _rmutex_request() is called twice for the same semaphore
  14395.     by the same thread without an intervening call to
  14396.     _rmutex_release().  This fact is important to keep in mind in
  14397.     presence of signals.  Signal handlers must not request semaphores
  14398.     which can be owned by the interrupted code.  You might want to
  14399.     block signals before requesting ownership of an _rmutex semaphore.
  14400.  
  14401. ■returnvalue
  14402.  
  14403.     _rmutex_request() returns 0 if successful.  Otherwise,
  14404.     _rmutex_request() returns an OS/2 error code defined in <os2.h>
  14405.     such as ERROR_INTERRUPT.
  14406.  
  14407. ■restrictions
  14408.  
  14409.     Under DOS, _rmutex_request() and _rmutex_checked_request() crash
  14410.     if the semaphore is already owned.
  14411.  
  14412. ■seealso abort() __cxchg() _fmutex_request() _rmutex_available() _rmutex_close() _rmutex_create() _rmutex_open() _rmutex_release()
  14413.  
  14414.  
  14415. ■function sbrk()
  14416. ■compat UNIX
  14417. ■headers
  14418. #include <stdlib.h>
  14419. ■endheaders
  14420.  
  14421. ■param INCR
  14422. ■prototype
  14423. void *sbrk (int INCR);
  14424. ■endprototype
  14425.  
  14426.     Change memory allocation by INCR bytes.  If INCR is positive, the
  14427.     memory limit is increased.  If INCR is negative, the memory limit
  14428.     is decreased.  On success, sbrk() returns the previous memory
  14429.     limit.  Otherwise, -1 cast as pointer is returned and errno set to
  14430.     ENOMEM.  Please don't use sbrk() -- use malloc() instead for
  14431.     memory allocation.
  14432.  
  14433.     If non-contiguous memory allocation with monotonous addresses
  14434.     (_UF_SBRK_MONOTONOUS) has been enabled with _uflags(), sbrk() may
  14435.     allocate non-contiguous memory.  In that case, sbrk() with
  14436.     non-negative argument returns the base address of the newly added
  14437.     memory area.  Any memory in the gap between the previous memory
  14438.     limit and the base address returned by sbrk() is not accessible.
  14439.     Setting back the memory limit into a gap is not possible.  If
  14440.     non-contiguous memory allocation with arbitrary addresses
  14441.     (_UF_SBRK_ARBITRARY) has been enabled with _uflags(), sbrk() may
  14442.     allocate non-contiguous memory; the memory object may even be at a
  14443.     lower address than the previous one.  In both cases, at most one
  14444.     memory object can be deallocated with sbrk() at a time, that is,
  14445.     you cannot reset the break address with sbrk() to an address
  14446.     outside the most recently allocated memory object.  However, you
  14447.     can deallocate the most recently allcoated memory object by
  14448.     resetting the break address to the start of the that memory
  14449.     object; after doing so, sbrk(0) will return the break address of
  14450.     the memory object which became the top one.
  14451.  
  14452.     Currently, there are some restrictions when using a non-contiguous
  14453.     memory: emxbind cannot create a preloaded executable with more
  14454.     than one heap object.  fork() fails if there is more than one heap
  14455.     object.
  14456.  
  14457. ■returnvalue
  14458.  
  14459.     See above.
  14460.  
  14461. ■seealso brk() fork() malloc() _uflags() ulimit()
  14462.  
  14463. ■samplecode
  14464. /* Allocate memory with sbrk().  This function fails if sbrk()
  14465.    does not return contiguous memory.  Return a pointer to the
  14466.    new memory area.  Return NULL on error.  This function assumes
  14467.    that no other thread calls sbrk(). */
  14468.  
  14469. void *more_memory (size_t n)
  14470. {
  14471.   oid *prev, *base;
  14472.  
  14473.   if ((int)n < 0)               /* Check for overflow */
  14474.     return NULL;
  14475.   prev = sbrk (0);              /* Get current memory limit */
  14476.   if (prev == (void *)-1)
  14477.     return NULL;                /* Error */
  14478.   base = sbrk ((int)n);         /* Allocate memory */
  14479.   if (base == (void *)-1)
  14480.     return NULL;                /* Error */
  14481.   if (prev != base)             /* Non-contiguous? */
  14482.     {
  14483.       sbrk (-(int)n);           /* Free non-contiguous memory */
  14484.       return NULL;              /* Failure */
  14485.     }
  14486.   return base;                  /* Success */
  14487. }
  14488. ■endsamplecode
  14489.  
  14490.  
  14491. ■function scanf()
  14492. ■compat C90
  14493. ■headers
  14494. #include <stdio.h>
  14495. ■endheaders
  14496.  
  14497. ■param FORMAT <width> <size> <type>
  14498. ■prototype
  14499. int scanf (const char *FORMAT, ...);
  14500. ■endprototype
  14501.  
  14502.     The stdin stream is read and input is parsed according to the
  14503.     format string pointed to by FORMAT.  For each field in the format
  14504.     string there must be a pointer to the location receiving the
  14505.     value.  The pointers are passed after the FORMAT argument.
  14506.  
  14507.     Whitespace (any number of spaces) in the format string matches
  14508.     whitespace (any number of spaces, including zero) in the input.
  14509.     All other characters except for ■tt{%} are compared to the input.
  14510.     Parsing ends when a mismatch is encountered.  ■tt{%%} in the
  14511.     format string matches ■tt{%} in the input.  A ■tt{%} which is not
  14512.     followed by another ■tt{%} or the end of the string starts a field
  14513.     specification.  The field in the input is interpreted according to
  14514.     the field specification.  For most field types, whitespace is
  14515.     ignored at the start of a field.  Field specifications have the
  14516.     format
  14517.  
  14518. ■indent
  14519.   ■sy{%[*][<width>][<size>]<type>}
  14520. ■endindent
  14521.  
  14522.     where items in brackets are optional.  If the ■tt{*} is present, the
  14523.     value is not assigned.  No pointer will be fetched from the
  14524.     argument list and the value is ignored.
  14525.  
  14526.     <width> is a positive integral decimal number specifying the maximum
  14527.     field width.  At most this many characters are read for this
  14528.     field.
  14529.  
  14530.     <size> is either ■tt{h} for a ■tt{short} type (■tt{h} is available
  14531.     for the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, and ■tt{x} conversions and
  14532.     for ■tt{n}), ■tt{l} for a ■tt{long} type (■tt{l} is available for
  14533.     the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, and ■tt{x} conversions and for
  14534.     ■tt{n}) or the ■tt{double} type (■tt{l} is also available for the
  14535.     ■tt{e}, ■tt{f}, and ■tt{g} conversions) or ■tt{L} for the ■tt{long
  14536.     double} type (■tt{L} is available for the ■tt{e}, ■tt{f}, and
  14537.     ■tt{g} conversions).  If <size> is omitted, the default size is
  14538.     used.
  14539.  
  14540.     <type> is one of the following characters:
  14541.  
  14542. ■list
  14543. ■item ■tt{c}
  14544.  
  14545.     Character (■tt{char}).  Whitespace is not skipped.  If a field
  14546.     width is specified, that many characters are read and assigned,
  14547.     without a terminating null character (■tt{char[]}).  If no field
  14548.     width is specified, one character will be read and assigned.
  14549.  
  14550. ■item ■tt{d}
  14551.  
  14552.     Signed decimal integer (■tt{int}).  ■tt{%hd} is used for ■tt{short
  14553.     int}, ■tt{%ld} is used for ■tt{long int} and ■tt{%Ld} is used for
  14554.     ■tt{long long int}.
  14555.  
  14556. ■item ■tt{e f g E F G}
  14557.  
  14558.     Floating-point number (■tt{float}).  ■tt{%le} etc. is used for
  14559.     ■tt{double}, ■tt{%Le} etc. is used for ■tt{long double}.  scanf()
  14560.     accepts the same format of float-point numbers as ■hpt{strtod()}.
  14561.     The decimal point character of the current locale is used.
  14562.  
  14563. ■item ■tt{i}
  14564.  
  14565.     Decimal, octal or hexadecimal signed integer (■tt{int}).  ■tt{%hi}
  14566.     is used for ■tt{short int}, ■tt{%li} is used for ■tt{long int} and
  14567.     ■tt{%Li} is used for ■tt{long long}.  The base is 16 if the number
  14568.     begins with ■tt{0x} or ■tt{0X}.  The base is 8 if the number
  14569.     begins with ■tt{0} (not followed by an ■tt{x} or ■tt{X}).
  14570.     Otherwise, the base is 10.
  14571.  
  14572. ■item ■tt{n}
  14573.  
  14574.     Number of characters read so far (■tt{int}).  No input is taken.
  14575.     The number of characters read so far is assigned to the integer
  14576.     (unless assignment is suppressed with the ■tt{*} flag).  Use
  14577.     ■tt{%hn} to assign to a ■tt{short int}, ■tt{%ln} to assign to a
  14578.     ■tt{long int} or ■tt{%Ln} to assign to a ■tt{long long int}.
  14579.  
  14580. ■item ■tt{o}
  14581.  
  14582.     Octal unsigned integer (■tt{unsigned}).  ■tt{%ho} is used for
  14583.     ■tt{unsigned short}, ■tt{%lo} is used for ■tt{unsigned long int}
  14584.     and ■tt{%Lo} is used for ■tt{unsigned long long int}.
  14585.     The input may contain a sign character.
  14586.  
  14587. ■item ■tt{p}
  14588.  
  14589.     Pointer (■tt{void *}).  The input format of a pointer is
  14590.     implementation-dependent.  In this implementation, ■tt{p} is equivalent
  14591.     to ■tt{x}.
  14592.  
  14593. ■item ■tt{s}
  14594.  
  14595.     Read and assign characters until the field width is exhausted or
  14596.     hitting whitespace (■tt{char[]}).  The destination array must be
  14597.     big enough to hold all the characters.  Note that initial
  14598.     whitespace is skipped.  Perhaps you want to use ■tt{%[...]}
  14599.     instead of ■tt{%s}.
  14600.  
  14601. ■item ■tt{u}
  14602.  
  14603.     Unsigned decimal integer (■tt{unsigned int}).  ■tt{%hu} is used
  14604.     for ■tt{unsigned short int}, ■tt{%lu} is used for ■tt{unsigned
  14605.     long int} and ■tt{%Lu} is used for ■tt{unsigned long long int}.
  14606.     The input may contain a sign character.
  14607.  
  14608. ■item ■tt{x}
  14609.  
  14610.     hexadecimal integer (■tt{unsigned int}).  ■tt{%hx} is used for
  14611.     ■tt{unsigned short int}, ■tt{%lx} is used for ■tt{unsigned long
  14612.     int} and ■tt{%Lx} is used for ■tt{unsigned long long int}. The
  14613.     input may contain a sign character.
  14614.  
  14615. ■item ■tt{[}
  14616.  
  14617.     Null-terminated string (■tt{char[]}).  White space is not skipped.
  14618.     ■tt{[} is followed by a set of characters which is delimited by
  14619.     ■tt{]}.  The field ends at the first character not in the
  14620.     character set ■tt{[...]}.  If ■tt{[^...]} is used, the field ends
  14621.     at the first character in that set.  The field also ends when the
  14622.     field width is exhausted.  The set contains all characters listed
  14623.     in the brackets.  To include a ■tt{]} in the set, make it the
  14624.     first character of the set.  You can specify a range of characters
  14625.     by listing the first and the last character, separated by a
  14626.     ■tt{-}.  To include a ■tt{-} in the set, make it the last
  14627.     character of the set.  The destination array must be big enough to
  14628.     hold all the characters.
  14629.  
  14630. ■endlist
  14631.  
  14632.     scanf() puts back into the stream at most one conflicting
  14633.     character.  In consequence, some character sequences acceptable to
  14634.     strtod(), strtof(), strtol(), strtold(), and strtoul() are not
  14635.     acceptable to scanf().
  14636.  
  14637. ■returnvalue
  14638.  
  14639.     If successful, scanf() returns the number of fields converted.  On
  14640.     error, scanf() returns EOF.
  14641.  
  14642. ■implementation
  14643.  
  14644.     <size> can be ■tt{L} for ■tt{long long} types (■tt{L} is available
  14645.     for the ■tt{d}, ■tt{i}, ■tt{o}, ■tt{u}, and ■tt{x} conversions and
  14646.     for ■tt{n})).
  14647.  
  14648. ■hints
  14649.  
  14650.     To read user input, you should use fgets() and sscanf() instead of
  14651.     scanf() because scanf() doesn't stop reading at the end of the
  14652.     line.
  14653.  
  14654.     Use ■tt{%lf} for variables of type ■tt{double}.  Contrast with
  14655.     printf().
  14656.  
  14657. ■seealso fgets() fread() fscanf() printf() setlocale() sscanf() strptime() strtod() strtol() vscanf()
  14658.  
  14659. ■samplecode
  14660. int year, month, day;
  14661. ...
  14662. if (scanf ("%d/%d/%d", &year, &month, &day) == 3)
  14663.   {
  14664.     ...
  14665.   }
  14666. ■endsamplecode
  14667.  
  14668.  
  14669. ■function _scrsize()
  14670. ■compat emx
  14671. ■headers
  14672. #include <stdlib.h>
  14673. ■endheaders
  14674.  
  14675. ■param DST
  14676. ■prototype
  14677. void _scrsize (int *DST);
  14678. ■endprototype
  14679.  
  14680.     Retrieve the screen (window) size.  The number of text columns
  14681.     (width) is stored to ■pa{DST}■tt{[0]}, the number of text rows
  14682.     (height) is stored to ■pa{DST}■tt{[1]}.
  14683.  
  14684. ■seealso v_dimen()
  14685.  
  14686.  
  14687. ■function _searchenv()
  14688. ■compat PC
  14689. ■headers
  14690. #include <stdlib.h>
  14691. ■endheaders
  14692.  
  14693. ■param NAME VAR PATH
  14694. ■prototype
  14695. void _searchenv (const char *NAME, const char *VAR, char *PATH);
  14696. ■endprototype
  14697.  
  14698.     Search a file in the directories listed in an environment
  14699.     variable.  First, the file name pointed to by NAME is tried as is.
  14700.     If that file does not exist, the directories listed in the
  14701.     environment variable whose name is in the string pointed to by VAR
  14702.     are searched.  If the file is found, the constructed path name
  14703.     (either the string pointed to by NAME or a directory plus the
  14704.     string pointed to by NAME) will be copied to the array pointed to
  14705.     by PATH.  If the file is not found, the empty string will be
  14706.     stored to the array pointed to by PATH.
  14707.  
  14708.     _searchenv() properly handles DBCS characters.
  14709.  
  14710. ■seealso getenv() _nls_init() _path()
  14711.  
  14712.  
  14713. ■function _seek_hdr()
  14714. ■compat emx
  14715. ■headers
  14716. #include <io.h>
  14717. ■endheaders
  14718.  
  14719. ■param HANDLE
  14720. ■prototype
  14721. int _seek_hdr (int HANDLE);
  14722. ■endprototype
  14723.  
  14724.     Move the file pointer of HANDLE to the a.out header of an
  14725.     executable file (a.out or bound .exe).  _seek_hdr() assumes that
  14726.     the file pointer points to the beginning of the header (ie, the
  14727.     beginning of the file).  If no header is found, the file pointer
  14728.     will be repositioned to the original position.
  14729.  
  14730. ■returnvalue
  14731. ■description
  14732. ■item 0
  14733.     success
  14734. ■item -1
  14735.     error (errno is set)
  14736. ■enddescription
  14737.  
  14738. ■seealso _fseek_hdr()
  14739.  
  14740.  
  14741. ■function select()
  14742. ■compat UNIX *
  14743. ■headers
  14744. #include <sys/select.h>
  14745. ■endheaders
  14746.  
  14747. ■param NFDS READFDS WRITEFDS EXCEPTFDS TIMEOUT
  14748. ■prototype
  14749. int select (int NFDS, fd_set *READFDS, fd_set *WRITEFDS, fd_set *EXCEPTFDS,
  14750.             struct timeval *TIMEOUT);
  14751. ■endprototype
  14752.  
  14753.     Wait for a file handle to become ready for reading, writing, or
  14754.     until an exceptional situation exists for a file handle, or until
  14755.     a time-out expires.  `Ready for reading' means that a call to
  14756.     read() in blocking mode (O_NONBLOCK not being set) will return
  14757.     immediately, that is, will transfer data and return a positive
  14758.     number, will transfer no data and return zero, or will report an
  14759.     error (except EAGAIN alias EWOULDBLOCK) by returning -1.  `Ready
  14760.     for writing' means that a call to write() in blocking mode will
  14761.     return immediately, that is, will transfer data and return a
  14762.     positive number, will transfer no data and return zero, or will
  14763.     report an error (except EAGAIN alias EWOULDBLOCK) by returning -1.
  14764.     `Exceptional situations' means pending errors for sockets.  No
  14765.     other exceptional situations are currently defined.
  14766.  
  14767.     select() returns as soon as any handle in the set pointed to by
  14768.     READFDS is ready for reading, or a handle in the set pointed to by
  14769.     WRITEFDS is ready for writing, or an exceptional situation exists
  14770.     for a handle in the set pointed to by EXCEPTFDS.  READFDS,
  14771.     WRITEFDS, and EXCEPTFDS can each be NULL.  If TIMEOUT is NULL,
  14772.     select() waits indefinitely.  Otherwise, waiting terminates after
  14773.     the time-out pointed to by TIMEOUT expired.  NFDS is the number of
  14774.     handles to be checked.
  14775.  
  14776.     select() updates the objects pointed to by READFDS, WRITEFDS, and
  14777.     EXCEPTFDS to include only the handles which are ready for reading,
  14778.     writing, or for which an exceptional situation exists,
  14779.     respectively, and returns the number of those handles.
  14780.  
  14781.     Some implementations of select() update the object pointed to by
  14782.     TIMEOUT to reflect the amount of time remaining.  The emx
  14783.     implementation of select() currently doesn't do this and probably
  14784.     won't do this.
  14785.  
  14786.     The following macros are available for handling the bitstrings
  14787.     used by select():
  14788.  
  14789. ■list
  14790.  
  14791. ■item ■tt{FD_ZERO(}■pa{S}■tt{)}
  14792.  
  14793.     clear all bits of ■pa{S}
  14794.  
  14795. ■item ■tt{FD_SET(}■pa{N}■tt{,}■pa{S)}
  14796.  
  14797.     set bit ■pa{N} in ■pa{S}
  14798.  
  14799. ■item ■tt{FD_CLR(}■pa{N}■tt{,}■pa{S}■tt{)}
  14800.  
  14801.     clear bit ■pa{N} in ■pa{S}
  14802.  
  14803. ■item ■tt{FD_ISSET(}■pa{N}■tt{,}■pa{S)}
  14804.  
  14805.     return a non-zero value iff bit ■pa{N} is set in ■pa{S}
  14806.  
  14807. ■endlist
  14808.  
  14809.     The FD_SETSIZE macro specifies the number of file handles in an
  14810.     fd_set object.  The default value is 256.  To increase the number
  14811.     of file descriptors in fd_set, define FD_SETSIZE before including
  14812.     <sys/types.h> and <sys/select.h>.  The FD_ZERO macro and
  14813.     assignment of fd_set objects use the size of the object; in
  14814.     consequence, you must be careful when passing pointers to fd_set
  14815.     objects between modules which have been compiled with different
  14816.     values for FD_SETSIZE (libraries!).
  14817.  
  14818.     select() is implemented for the following types of handles:
  14819.  
  14820. ■itemize
  14821.  
  14822. ■item
  14823.  
  14824.     Standard input handles (keyboard) with IDEFAULT not set (DOS:
  14825.     handle 0 only).  Note that if ICANON is set, read() has to wait
  14826.     until the line is completed.  If IDEFAULT is set (that's the
  14827.     initial setting), standard input handles are reported as being
  14828.     ready
  14829.  
  14830. ■item
  14831.  
  14832.     Pseudo TTYs of xf86sup.sys
  14833.  
  14834. ■item
  14835.  
  14836.     Named pipes.  Named pipes are always reported to be ready for
  14837.     writing
  14838.  
  14839. ■item
  14840.  
  14841.     Pipes created with pipe() by programs using emx.dll; such pipes
  14842.     are always reported to be ready for writing
  14843.  
  14844. ■item
  14845.  
  14846.     Sockets under OS/2
  14847.  
  14848. ■item
  14849.     ASYNC devices (such as ■tt{COM1}) under OS/2
  14850.  
  14851. ■item
  14852.  
  14853.     All file handles under DOS; regular files are reported to be ready
  14854.     for reading if the file pointer is not at the end of the file --
  14855.     this behavior may change in the future: regular files should be
  14856.     reported to be always ready for reading
  14857.  
  14858. ■enditemize
  14859.  
  14860.     All handle types not supported by select() are reported to be
  14861.     ready for reading and ready for writing and having no exceptional
  14862.     situation pending.
  14863.  
  14864.     The ■tt{timeval} structure is defined as follows:
  14865.  
  14866. ■example
  14867. struct timeval
  14868. {
  14869.   long tv_sec;
  14870.   long tv_usec;
  14871. };
  14872. ■endexample
  14873.  
  14874.     ■tt{tv_sec} and ■tt{tv_usec} are the number of seconds and
  14875.     microseconds, respectively.
  14876.  
  14877. ■returnvalue
  14878. ■description
  14879. ■item >0
  14880.     number of ready handles
  14881. ■item 0
  14882.     time out
  14883. ■item -1
  14884.     error
  14885. ■enddescription
  14886.  
  14887. ■restrictions
  14888.  
  14889.     select() is not available with the system call library sys.lib
  14890.     (■hpt{-Zsys}).
  14891.  
  14892. ■seealso ioctl() pipe()
  14893.  
  14894.  
  14895. ■function setbuf()
  14896. ■compat C90
  14897. ■headers
  14898. #include <stdio.h>
  14899. ■endheaders
  14900.  
  14901. ■param STREAM BUFFER
  14902. ■prototype
  14903. int setbuf (FILE *STREAM, char *BUFFER);
  14904. ■endprototype
  14905.  
  14906.     Associate the buffer of size BUFSIZ pointed to by BUFFER with
  14907.     STREAM.  This must be done before the file has been read or
  14908.     written.  If BUFFER is NULL, the file is unbuffered.  You should
  14909.     use setvbuf() instead.
  14910.  
  14911. ■returnvalue
  14912.  
  14913. ■description
  14914. ■item 0
  14915.     success
  14916. ■item EOF
  14917.     error
  14918. ■enddescription
  14919.  
  14920.     BSD setbuf() seems to have an ■tt{int} return value, therefore emx
  14921.     setbuf() has an ■tt{int} return value.  This should not break
  14922.     programs which expect ■tt{void setbuf()}.
  14923.  
  14924. ■seealso setbuffer() setvbuf()
  14925.  
  14926.  
  14927. ■function setbuffer()
  14928. ■compat UNIX
  14929. ■headers
  14930. #include <stdio.h>
  14931. ■endheaders
  14932.  
  14933. ■param STREAM BUFFER SIZE
  14934. ■prototype
  14935. int setbuffer (FILE *STREAM, char *BUFFER, size_t SIZE);
  14936. ■endprototype
  14937.  
  14938.     Associate the buffer of size SIZE pointed to by BUFFER with
  14939.     STREAM.  This must be done before the file has been read or
  14940.     written.  If BUFFER is NULL, the file is unbuffered.  You should
  14941.     use setvbuf() instead.
  14942.  
  14943. ■returnvalue
  14944.  
  14945. ■description
  14946. ■item 0
  14947.     success
  14948. ■item EOF
  14949.     error
  14950. ■enddescription
  14951.  
  14952.     BSD setbuffer() seems to have an ■tt{int} return value, therefore
  14953.     emx setbuffer() has an ■tt{int} return value.  This should not
  14954.     break programs which expect ■tt{void setbuffer()}.
  14955.  
  14956. ■seealso setvbuf()
  14957.  
  14958.  
  14959. ■function setjmp()
  14960. ■compat C90
  14961. ■headers
  14962. #include <setjmp.h>
  14963. ■endheaders
  14964.  
  14965. ■param HERE
  14966. ■prototype
  14967. int setjmp (jmp_buf HERE);
  14968. ■endprototype
  14969.  
  14970.     Save the current stack context in HERE and return 0.  Later, you
  14971.     can continue at this point by calling longjmp().  When execution
  14972.     continues at setjmp() after calling longjmp(), the second argument
  14973.     of longjmp() is returned, which is always non-zero (if zero is
  14974.     used as second argument of longjmp(), it will be turned into 1).
  14975.  
  14976.     setjmp() may be implemented as macro.  setjmp() can be used only
  14977.     in the following contexts:
  14978.  
  14979. ■itemize
  14980. ■item
  14981.   the entire controlling expression of a ■tt{do}, ■tt{if},
  14982.   ■tt{switch}, or ■tt{while} statement
  14983. ■item
  14984.   the operand to the ■tt{!} operator if the resulting expression is
  14985.   the entire controlling expression of one of the statements listed
  14986.   above
  14987. ■item
  14988.   the operand of a relational or equality operator if the resulting
  14989.   expression is the entire controlling expression of one of the
  14990.   statements listed above and the other operand is an integral
  14991.   constant expression
  14992. ■item
  14993.   the entire expression of an expression statement.
  14994. ■enditemize
  14995.  
  14996. ■returnvalue
  14997.  
  14998.     setjmp() returns 0 when directly called.  When returning from a
  14999.     call to longjmp(), setjmp() returns a non-zero value (supplied by
  15000.     the call to longjmp()).
  15001.  
  15002. ■implementation
  15003.  
  15004.     The restrictions on the contexts in which setjmp() can be used do
  15005.     not apply.
  15006.  
  15007. ■hints
  15008.  
  15009.     As jmp_buf is an array type, the ■tt{&} operator need not be
  15010.     applied.
  15011.  
  15012. ■seealso longjmp() siglongjmp() sigsetjmp()
  15013.  
  15014.  
  15015. ■function setlocale()
  15016. ■compat C90
  15017. ■headers
  15018. #include <locale.h>
  15019. ■endheaders
  15020.  
  15021. ■param CATEGORY LOCALE
  15022. ■prototype
  15023. char *setlocale (int CATEGORY, const char *LOCALE);
  15024. ■endprototype
  15025.  
  15026.     Select a locale.  Either the entire locale or a portion of the
  15027.     locale is set, depending on CATEGORY:
  15028.  
  15029. ■list
  15030. ■item LC_ALL
  15031.  
  15032.     Set the entire locale, including categories LC_COLLATE, LC_CTYPE,
  15033.     LC_MONETARY, LC_NUMERIC and LC_TIME.
  15034.  
  15035. ■item LC_COLLATE
  15036.  
  15037.     Control the behavior of strcoll() and strxfrm().
  15038.  
  15039. ■item LC_CTYPE
  15040.  
  15041.     Control the behavior of isalnum(), isalpha(), iscntrl(),
  15042.     isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(),
  15043.     tolower(), toupper(), mblen(), mbstowcs(), mbtowc(), wcstombs()
  15044.     and wctomb().  This also affects the interpretation of multibyte
  15045.     character format strings by printf(), scanf() and strftime().
  15046.     Note that isdigit() and isxdigit() are not affected.
  15047.  
  15048. ■item LC_MONETARY
  15049.  
  15050.     Set the information related to formatting of monetary quantities.
  15051.     This affects the contents of the structure returned by
  15052.     localeconv().
  15053.  
  15054. ■item LC_NUMERIC
  15055.  
  15056.     Select the decimal point character for atof(), _atofl(), gcvt(),
  15057.     printf(), scanf(), strtod(), strtof(), and strtold().  Set the
  15058.     information related to formatting of numeric quantities.  This
  15059.     affects the contents of the structure returned by localeconv().
  15060.  
  15061. ■item LC_TIME
  15062.  
  15063.     Control the behavior of strftime().
  15064.  
  15065. ■endlist
  15066.  
  15067.     If LOCALE points to the empty string ■tt{""}, the value of the
  15068.     environment variable LANG is taken instead.  If LANG is not set,
  15069.     ■tt{"C"} is used for LOCALE.  ■tt{"C"} is the initial locale at
  15070.     program startup.  It provides the usual C conversions.
  15071.  
  15072.     Other possible values of LOCALE are ■tt{LC_C_FRANCE},
  15073.     ■tt{LC_C_GERMANY}, ■tt{LC_C_ITALY}, ■tt{LC_C_SPAIN}, ■tt{LC_C_UK},
  15074.     ■tt{LC_C_USA}, ■tt{"de_de"}, ■tt{"en_us"}, and ■tt{"en_gb"}.
  15075.  
  15076.     If LOCALE is a null pointer, a pointer to the string associated
  15077.     with CATEGORY for the currently selected locale is returned.  That
  15078.     string can be used as LOCALE with CATEGORY for restoring that
  15079.     locale.  If CATEGORY is LC_ALL and different locale strings are
  15080.     associated with the categories, a pointer to a string is returned
  15081.     which selects those locales when used with LC_ALL.
  15082.  
  15083.     All threads of a process share the same locale.
  15084.  
  15085. ■returnvalue
  15086.  
  15087.     setlocale() returns NULL on error.  Otherwise, it returns a
  15088.     pointer to the string associated with CATEGORY for the new locale
  15089.     (or the current one if LOCALE is NULL).  The string must not be
  15090.     modified by the program; it may be overwritten by a subsequent
  15091.     call to setlocale().
  15092.  
  15093. ■restrictions
  15094.  
  15095.     Currently, information associated with LC_COLLATE and LC_CTYPE is
  15096.     ignored.  Moreover, strftime() always assumes that code page 850
  15097.     is in effect.
  15098.  
  15099. ■seealso isupper() localeconv() mbtowc() strcoll() strftime() strxfrm()
  15100.  
  15101.  
  15102. ■function setmode()
  15103. ■compat PC
  15104. ■headers
  15105. #include <io.h>
  15106. #include <fcntl.h>
  15107. ■endheaders
  15108.  
  15109. ■param HANDLE MODE
  15110. ■prototype
  15111. int setmode (int HANDLE, int MODE);
  15112. ■endprototype
  15113.  
  15114.     Change the text/binary mode of a file handle.  MODE must be either
  15115.     O_BINARY or O_TEXT.
  15116.  
  15117.     ■bf{Note:} Use _fsetmode() to change the mode of a stream.
  15118.  
  15119. ■returnvalue
  15120.  
  15121.   If there's an error, setmode() returns -1 and sets errno to EBADF or
  15122.   EINVAL otherwise setmode() returns the previous mode, that is,
  15123.   O_BINARY or O_TEXT.
  15124.  
  15125. ■seealso _fsetmode() open()
  15126.  
  15127.  
  15128. ■function _setsyserrno()
  15129. ■compat emx *
  15130. ■headers
  15131. #include <stdlib.h>
  15132. ■endheaders
  15133.  
  15134. ■param CODE
  15135. ■prototype
  15136. int _setsyserrno (int CODE);
  15137. ■endprototype
  15138.  
  15139.     Make the next _syserrno() call return CODE.  This function returns
  15140.     the OS/2 or DOS error code for the last system call of the current
  15141.     thread, like _syserrno().
  15142.  
  15143. ■returnvalue
  15144.  
  15145.     See above.  If _setsyserrno() is not implemented, -1 will returned
  15146.     without setting errno.
  15147.  
  15148. ■restrictions
  15149.  
  15150.     _setsyserrno() is not implemented under DOS.  _setsyserrno() is
  15151.     not supported with the system call library sys.lib (■hpt{-Zsys}).
  15152.  
  15153. ■seealso errno _syserrno()
  15154.  
  15155. ■function settimeofday()
  15156. ■compat BSD
  15157. ■headers
  15158. #include <sys/time.h>
  15159. ■endheaders
  15160.  
  15161. ■param TP TZP
  15162. ■prototype
  15163. int settimeofday (const struct timeval *TP, const struct timezone *TZP);
  15164. ■endprototype
  15165.  
  15166.     Set the system time and timezone.  If TP is not NULL, the system
  15167.     time is set to the time (Coordinated Universal Time) specified by
  15168.     the structure pointed to by TP.  If TZP is not NULL, the timezone
  15169.     is set according to the structure pointed to by TZP.
  15170.  
  15171.     The ■tt{timeval} structure is defined as follows:
  15172.  
  15173. ■example
  15174. struct timeval
  15175. {
  15176.   long tv_sec;
  15177.   long tv_usec;
  15178. };
  15179. ■endexample
  15180.  
  15181.     ■tt{tv_sec} and ■tt{tv_usec} are the number of seconds and
  15182.     microseconds, respectively, elapsed since 00:00:00 1-Jan-1970 UTC.
  15183.  
  15184. ■returnvalue
  15185. ■description
  15186. ■item 0
  15187.     success
  15188. ■item -1
  15189.     error
  15190. ■enddescription
  15191.  
  15192. ■restrictions
  15193.  
  15194.     Setting the timezone is not implemented, TZP must be a null
  15195.     pointer.  The real time clock is not set under DOS versions
  15196.     earlier than 3.3.
  15197.  
  15198. ■seealso gettimeofday() ftime() time()
  15199.  
  15200.  
  15201. ■function setvbuf()
  15202. ■compat C90
  15203. ■headers
  15204. #include <stdio.h>
  15205. ■endheaders
  15206.  
  15207. ■param STREAM BUFFER MODE SIZE
  15208. ■prototype
  15209. int setvbuf (FILE *STREAM, char *BUFFER, int MODE, size_t SIZE);
  15210. ■endprototype
  15211.  
  15212.     Set the buffering mode of STREAM to MODE.  The array of SIZE bytes
  15213.     pointed to by BUFFER may be used instead of a buffer allocated by
  15214.     setvbuf() if BUFFER is not NULL.  Available modes are:
  15215.  
  15216. ■description
  15217.  
  15218. ■item _IONBF
  15219.  
  15220.     the file is unbuffered, BUFFER and SIZE are always ignored
  15221.  
  15222. ■item _IOFBF
  15223.  
  15224.     the file is full buffered
  15225.  
  15226. ■item _IOLBF
  15227.  
  15228.     the file is line buffered
  15229.  
  15230. ■enddescription
  15231.  
  15232.     The file must not have been read or written since it was opened.
  15233.  
  15234. ■returnvalue
  15235.  
  15236.     On success, setvbuf() returns 0.  On failure, setvbuf() returns a
  15237.     non-zero value.
  15238.  
  15239. ■implementation
  15240.  
  15241.     This implementation of setvbuf() uses BUFFER unless MODE is _IONBF
  15242.     or SIZE is invalid.  If SIZE is invalid, a buffer of BUFSIZ bytes
  15243.     is used.
  15244.  
  15245.     For reading a file, _IOFBF and _IOLBF are equivalent.  Each time a
  15246.     newline character is written to a line-buffered file, the buffer
  15247.     is flushed.  The buffer is also flushed if it becomes full while
  15248.     writing.  The buffer is filled by reading from the disk file (or
  15249.     device) if the buffer becomes empty while reading.
  15250.  
  15251. ■seealso fflush() fputs() fwrite()
  15252.  
  15253.  
  15254. ■function sigaction()
  15255. ■compat POSIX.1 *
  15256. ■headers
  15257. #include <signal.h>
  15258. ■endheaders
  15259.  
  15260. ■param SIG IACT OACT
  15261. ■prototype
  15262. int sigaction (int SIG, const struct sigaction *IACT,
  15263.                struct sigaction *OACT);
  15264. ■endprototype
  15265.  
  15266.     Examine and/or specify the action associated with the signal SIG.
  15267.     If IACT is not NULL, it points to a structure specifying the
  15268.     action to be associated with the signal SIG.  If IACT is NULL, the
  15269.     action for signal SIG won't be changed.  If OACT is not NULL, the
  15270.     previous action for signal SIG will be stored to the object
  15271.     pointed to by OACT.
  15272.  
  15273.     The ■tt{sigaction} structure is defined as follows:
  15274.  
  15275. ■example
  15276. struct sigaction
  15277. {
  15278.   void (*sa_handler)(int sig);
  15279.   sigset_t sa_mask;
  15280.   int sa_flags;
  15281. };
  15282. ■endexample
  15283.  
  15284.     sa_handler can be SIG_DFL (to get the default action), SIG_IGN (to
  15285.     ignore the signal), or the address of a signal-catching function
  15286.     (signal handler).
  15287.  
  15288.     sa_mask is a set of signals to be blocked prior to calling the
  15289.     signal-catching function.  sa_mask is ignored for the `emx' and
  15290.     `System V' signal models.
  15291.  
  15292.     Every object of type sigset_t should be initialized at least once
  15293.     with either sigemptyset() or sigfillset() before any use.  When
  15294.     using an uninitialized object of type sigset_t, the results are
  15295.     undefined.
  15296.  
  15297.     sa_flags is a set of flag bits used to modify the behavior of the
  15298.     signal SIG.  The following flag bits are available:
  15299.  
  15300. ■description
  15301. ■item SA_NOCLDSTOP
  15302.  
  15303.     Do not generate SIGCHLD when a child process stops.
  15304.  
  15305. ■item SA_SYSV
  15306.  
  15307.     Use the `System V' signal model for the signal SIG: before calling
  15308.     a signal-catching function, reset the signal action to SIG_DFL,
  15309.     don't block the signal, and ignore sa_mask.
  15310.  
  15311. ■item SA_ACK
  15312.  
  15313.     Use the `emx' signal model for the signal SIG: ignore sa_mask, use
  15314.     SIG_ACK for unblocking the signal.
  15315.  
  15316. ■enddescription
  15317.  
  15318.     In a multithread program, sigaction() examines and sets the
  15319.     signal action for the thread in which it is called.  Signal action
  15320.     settings are private to each thread.
  15321.  
  15322.     If the previous signal action for signal SIG has been set by
  15323.     signal(), the value of the object pointed to by OACT is
  15324.     unspecified; however, if that object is subsequently used for
  15325.     setting the signal action with sigaction(), handling of the signal
  15326.     is as if the original call to signal() were repeated.
  15327.  
  15328.     See section ■ref{signal processing} for details on
  15329.     ■hpt{signal processing}.
  15330.  
  15331. ■returnvalue
  15332.  
  15333.     If successful, sigaction() returns 0.  Otherwise sigaction()
  15334.     sets errno and returns -1.
  15335.  
  15336. ■errors
  15337.  
  15338. ■description
  15339. ■item EINVAL
  15340.  
  15341.     SIG is not a valid signal number or an attempt was made to catch a
  15342.     signal that cannot be caught or to ignore a signal that cannot be
  15343.     ignored.
  15344.  
  15345. ■enddescription
  15346.  
  15347. ■implementation
  15348.  
  15349.     The SA_ACK and SA_SYSV flag bits of sa_flags are emx extensions.
  15350.  
  15351. ■restrictions
  15352.  
  15353.     The SA_NOCLDSTOP flag bit of sa_flags is ignored as stopped
  15354.     processes are not supported (except for ptrace()).
  15355.  
  15356. ■seealso raise() kill() sigemptyset() signal() sigpending() sigprocmask()
  15357.  
  15358. ■samplecode
  15359. void sig_cleanup (int signo)
  15360. {
  15361.   cleanup ();
  15362.   printf ("Process terminated by signal %d\n", signo);
  15363.   exit (99);
  15364. }
  15365.  
  15366. void sig_init (void)
  15367. {
  15368.   struct sigaction sa;
  15369.  
  15370.   sa.sa_handler = sig_cleanup;
  15371.   sa.sa_flags = 0;
  15372.   sigemptyset (&sa.sa_mask);
  15373.   sigaction (SIGINT, &sa, NULL);
  15374. }
  15375. ■endsamplecode
  15376.  
  15377.  
  15378. ■function sigaddset() sigdelset()
  15379. ■compat POSIX.1 *
  15380. ■headers
  15381. #include <signal.h>
  15382. ■endheaders
  15383.  
  15384. ■param SET SIG
  15385. ■prototype
  15386. int sigaddset (sigset_t *SET, int SIG);
  15387. int sigdelset (sigset_t *SET, int SIG);
  15388. ■endprototype
  15389.  
  15390.     sigaddset() adds the signal SIG to the set of signals pointed to
  15391.     by SET.
  15392.  
  15393.     sigdelset() deletes the signal SIG from the set of signals pointed
  15394.     to by SET.
  15395.  
  15396.     Every object of type sigset_t should be initialized at least once
  15397.     with either sigemptyset() or sigfillset() before any use.  When
  15398.     using an uninitialized object of type sigset_t, the results are
  15399.     undefined.
  15400.  
  15401. ■returnvalue
  15402.  
  15403.     If successful, sigaddset() and sigdelset() return 0.  Otherwise,
  15404.     these functions set errno and return -1.
  15405.  
  15406. ■errors
  15407.  
  15408. ■description
  15409. ■item EINVAL
  15410.  
  15411.     SIG is not a valid signal number.
  15412.  
  15413. ■enddescription
  15414.  
  15415. ■seealso sigemptyset() sigfillset() sigismember()
  15416.  
  15417.  
  15418. ■function sigemptyset() sigfillset()
  15419. ■compat POSIX.1 *
  15420. ■headers
  15421. #include <signal.h>
  15422. ■endheaders
  15423.  
  15424. ■param SET
  15425. ■prototype
  15426. int sigemptyset (sigset_t *SET);
  15427. int sigfillset (sigset_t *SET);
  15428. ■endprototype
  15429.  
  15430.     sigemptyset() initializes the object pointed to by SET to an empty
  15431.     set of signals.
  15432.  
  15433.     sigfillset() initializes the object pointed to by SET to a signal
  15434.     set which includes all signals.
  15435.  
  15436.     Every object of type sigset_t should be initialized at least once
  15437.     with either sigemptyset() or sigfillset() before any use.  When
  15438.     using an uninitialized object of type sigset_t, the results are
  15439.     undefined.
  15440.  
  15441. ■returnvalue
  15442.  
  15443.     If successful, sigemptyset() and sigfillset() return 0.  Otherwise,
  15444.     these functions set errno and return -1.
  15445.  
  15446. ■seealso sigaction() sigaddset() sigdelset() sigprocmask() sigismember()
  15447.  
  15448.  
  15449. ■function sigismember()
  15450. ■compat POSIX.1 *
  15451. ■headers
  15452. #include <signal.h>
  15453. ■endheaders
  15454.  
  15455. ■param SET SIG
  15456. ■prototype
  15457. int sigismember (const sigset_t *SET, int SIG);
  15458. ■endprototype
  15459.  
  15460.     sigismember() tests whether the signal SIG is a member of the set
  15461.     of signals pointed to by SET.
  15462.  
  15463.     Every object of type sigset_t should be initialized at least once
  15464.     with either sigemptyset() or sigfillset() before any use.  When
  15465.     using an uninitialized object of type sigset_t, the results are
  15466.     undefined.
  15467.  
  15468. ■returnvalue
  15469.  
  15470.     sigismember() returns 1 if the signal SIG is a member of the set
  15471.     of signals pointed to by SET, or 0 if the signal SIG is not a
  15472.     member of the set of signals pointed to by SET.  On error,
  15473.     sigismember() sets errno and returns -1.
  15474.  
  15475. ■errors
  15476.  
  15477. ■description
  15478. ■item EINVAL
  15479.  
  15480.     SIG is not a valid signal number.
  15481.  
  15482. ■enddescription
  15483.  
  15484. ■seealso sigaddset() sigdelset() sigemptyset() sigfillset()
  15485.  
  15486.  
  15487. ■function siglongjmp()
  15488. ■compat POSIX.1
  15489. ■headers
  15490. #include <setjmp.h>
  15491. ■endheaders
  15492.  
  15493. ■param THERE N SAVEMASK
  15494. ■prototype
  15495. void siglongjmp (sigjmp_buf THERE, int N);
  15496. ■endprototype
  15497.  
  15498.     Restore the context saved in THERE by sigsetjmp() and -- if the
  15499.     SAVEMASK argument of sigsetjmp() was non-zero -- restore the
  15500.     signal mask saved by sigsetjmp() .  siglongjmp() does a non-local
  15501.     ■tt{goto}, causing execution to continue at the sigsetjmp() call
  15502.     which most recently saved a stack context in THERE.  sigsetjmp()
  15503.     will return N.  If N is 0, sigsetjmp() will return 1.  When
  15504.     calling siglongjmp() in a signal handler or in a function called
  15505.     by a signal handler (that is, while a signal handler is active),
  15506.     the signal handler will be unwound, that is, it is assumed that
  15507.     the signal handler doesn't return.  siglongjmp() must be called in
  15508.     the same thread as the most recent call to sigsetjmp() for THERE.
  15509.     Moreover, the function which most recently called sigsetjmp() to
  15510.     save a stack context in THERE must still be active.  Don't expect
  15511.     local variables to be preserved unless declared volatile.
  15512.  
  15513.     As sigjmp_buf is an array type, the ■tt{&} operator need not be
  15514.     applied.
  15515.  
  15516. ■seealso longjmp() setjmp() sigaction() sigprocmask() sigsetjmp() signal()
  15517.  
  15518.  
  15519. ■function signal()
  15520. ■compat C90
  15521. ■headers
  15522. #include <signal.h>
  15523. ■endheaders
  15524.  
  15525. ■param SIG HANDLER
  15526. ■prototype
  15527. void (*signal (int SIG, void (*HANDLER)()))(int SIG);
  15528. ■endprototype
  15529.  
  15530.     Set the signal action associated with signal SIG.  HANDLER can be
  15531.     SIG_DFL (to get the default action), SIG_IGN (to ignore the
  15532.     signal), or the address of a signal-catching function (signal
  15533.     handler).
  15534.  
  15535.     On delivery of the signal, the signal number is passed as the only
  15536.     argument to the signal-catching function.  Before the
  15537.     signal-catching funcion is called, the signal is blocked or the
  15538.     signal action is reset to SIG_DFL, depending on the signal
  15539.     processing model.
  15540.  
  15541.     The action associated with SIGKILL cannot be changed.
  15542.  
  15543.     In a multithread program, signal() sets a signal handler for
  15544.     the thread in which it is called.  The set of signal handlers is
  15545.     private to each thread.
  15546.  
  15547.     On delivery, the signal is blocked before calling the signal
  15548.     handler, if the `emx' signal model is used and the signal is
  15549.     caught (that is, a signal handler is installed).  To unblock the
  15550.     signal SIG, call
  15551.  
  15552. ■example
  15553. signal (sig, SIG_ACK)
  15554. ■endexample
  15555.  
  15556.     See section ■ref{signal processing} for details on
  15557.     ■hpt{signal processing}.
  15558.  
  15559. ■returnvalue
  15560.  
  15561.     If successful, signal() returns the previous signal action
  15562.     (SIG_IGN or SIG_DFL or the address of a signal handler) associated
  15563.     with signal SIG.  On failure, signal() returns SIG_ERR.  If
  15564.     HANDLER is SIG_ACK, signal() returns the current signal action
  15565.     associated with the signal SIG.
  15566.  
  15567. ■seealso abort() kill() raise() sigaction() sigprocmask()
  15568.  
  15569.  
  15570. ■function signbit()
  15571. ■compat C9X
  15572. ■headers
  15573. #include <math.h>
  15574. ■endheaders
  15575.  
  15576. ■param X
  15577. ■prototype
  15578. int signbit (float X);
  15579. int signbit (double X);
  15580. int signbit (long double X);
  15581. ■endprototype
  15582.  
  15583.     Determine the sign of X.  The argument X must be of a
  15584.     floating-point type.
  15585.  
  15586. ■returnvalue
  15587.  
  15588.     signbit() returns a non-zero value if the sign of X is negative;
  15589.     signbit() returns 0 otherwise.
  15590.  
  15591. ■seealso copysign() fpclassify() isfinite() isnan() isnormal()
  15592.  
  15593.  
  15594. ■function sigpending()
  15595. ■compat POSIX.1 *
  15596. ■headers
  15597. #include <signal.h>
  15598. ■endheaders
  15599.  
  15600. ■param SET
  15601. ■prototype
  15602. int sigpending (sigset_t *SET);
  15603. ■endprototype
  15604.  
  15605.     Store in the object pointed to by SET the set of signals that
  15606.     are blocked and pending.
  15607.  
  15608.     Every object of type sigset_t should be initialized at least once
  15609.     with either sigemptyset() or sigfillset() before any use.  When
  15610.     using an uninitialized object of type sigset_t, the results are
  15611.     undefined.
  15612.  
  15613. ■returnvalue
  15614.  
  15615.     If successful, sigpending() returns 0.  Otherwise sigpending()
  15616.     returns -1 and sets errno.
  15617.  
  15618. ■seealso kill() raise() sigaction() sigprocmask() sigismember()
  15619.  
  15620. ■samplecode
  15621. int poll_sigint (void)
  15622. {
  15623.   sigset_t s;
  15624.  
  15625.   sigemptyset (&s);
  15626.   return (sigprocmask (&s) == 0
  15627.           && sigismember (&s, SIGINT) == 1);
  15628. }
  15629. ■endsamplecode
  15630.  
  15631.  
  15632. ■function sigprocmask()
  15633. ■compat POSIX.1 *
  15634. ■headers
  15635. #include <signal.h>
  15636. ■endheaders
  15637.  
  15638. ■param HOW ISET OSET
  15639. ■prototype
  15640. int sigprocmask (int HOW, const sigset_t *ISET, sigset_t *OSET);
  15641. ■endprototype
  15642.  
  15643.     Examine and/or change the signal mask (set of blocked signals) of
  15644.     the calling process.  If ISET is not NULL, it points to a set of
  15645.     signals used to change the signal mask.  The following values are
  15646.     available for HOW to indicate how to modify the signal mask:
  15647.  
  15648. ■description
  15649. ■item SIG_BLOCK
  15650.  
  15651.     Add the signals of the set pointed to by ISET to the set of
  15652.     blocked signals.  The resulting signal mask will be the union of
  15653.     the current signal mask and the signal set pointed to by ISET.
  15654.  
  15655. ■item SIG_UNBLOCK
  15656.  
  15657.     Remove the signals of the set pointed to by ISET from the set of
  15658.     blocked signals.  The resulting signal mask will be the
  15659.     intersection of the current signal mask and the complement of the
  15660.     signal set pointed to by ISET.
  15661.  
  15662. ■item SIG_SETMASK
  15663.  
  15664.     Replace the current signal mask with the signal set pointed to by
  15665.     ISET.
  15666.  
  15667. ■enddescription
  15668.  
  15669.     SIGKILL cannot be blocked; any attempt to block SIGKILL is ignored
  15670.     by sigprocmask() without indication of an error.
  15671.  
  15672.     If ISET is NULL, the signal mask won't be changed.
  15673.  
  15674.     If OSET is not NULL, the previous signal mask will be stored in
  15675.     the object pointed to by OSET.
  15676.  
  15677.     If any unblocked signal is pending, at least one unblocked pending
  15678.     signal will be delivered before sigprocmask() returns.
  15679.  
  15680.     Every object of type sigset_t should be initialized at least once
  15681.     with either sigemptyset() or sigfillset() before any use.  When
  15682.     using an uninitialized object of type sigset_t, the results are
  15683.     undefined.
  15684.  
  15685. ■returnvalue
  15686.  
  15687.     If successful, sigprocmask() returns 0.  Otherwise sigprocmask()
  15688.     returns -1 and sets errno.
  15689.  
  15690. ■errors
  15691. ■description
  15692. ■item EINVAL
  15693.     HOW is not SIG_BLOCK, SIG_UNBLOCK, or SIG_SETMASK
  15694. ■enddescription
  15695.  
  15696. ■seealso kill() raise() sigaction() sigemptyset() sigismember() siglongjmp() sigpending() sigsetjmp()
  15697.  
  15698. ■samplecode
  15699. void block_sigint (void)
  15700. {
  15701.   sigset_t s;
  15702.  
  15703.   sigemptyset (&s);
  15704.   sigaddset (&s, SIGINT);
  15705.   sigprocmask (SIG_BLOCK, &s, NULL);
  15706. }
  15707. ■endsamplecode
  15708.  
  15709.  
  15710. ■function sigsetjmp()
  15711. ■compat POSIX.1
  15712. ■headers
  15713. #include <setjmp.h>
  15714. ■endheaders
  15715.  
  15716. ■param HERE SAVEMASK
  15717. ■prototype
  15718. int sigsetjmp (sigjmp_buf HERE, int SAVEMASK);
  15719. ■endprototype
  15720.  
  15721.     Save the current stack context in HERE and return 0.  If SAVEMASK
  15722.     is non-zero, also save the current signal mask (set of blocked
  15723.     signals) to HERE.  Later, you can continue at this point by
  15724.     calling siglongjmp().  When execution continues at sigsetjmp()
  15725.     after calling siglongjmp(), the second argument of siglongjmp() is
  15726.     returned, which is always non-zero (if zero is used as second
  15727.     argument of siglongjmp(), it will be turned into 1).
  15728.  
  15729.     sigsetjmp() must not be used in compliated expressions.
  15730.  
  15731.     As sigjmp_buf is an array type, the ■tt{&} operator need not be
  15732.     applied.
  15733.  
  15734. ■returnvalue
  15735.  
  15736.     sigsetjmp() returns 0 when directly called.  When returning from a
  15737.     call to siglongjmp(), sigsetjmp() returns a non-zero value
  15738.     (supplied by the call to siglongjmp()).
  15739.  
  15740. ■seealso longjmp() setjmp() siglongjmp() sigprocmask()
  15741.  
  15742.  
  15743. ■function sigsuspend()
  15744. ■compat POSIX.1 *
  15745. ■headers
  15746. #include <signal.h>
  15747. ■endheaders
  15748.  
  15749. ■param MASK
  15750. ■prototype
  15751. int sigsuspend (const sigset_t *MASK);
  15752. ■endprototype
  15753.  
  15754.     Replace the signal mask with the set of signals pointed to by MASK
  15755.     and then suspend the process until delivery of a signal for which
  15756.     a signal handler is installed.  sigsuspend() returns after the
  15757.     signal handler returns.  Before returning, sigsuspends() restores
  15758.     the signal mask to the set that existed prior to the sigsuspend()
  15759.     call.
  15760.  
  15761.     The process will be terminated (and sigsuspend() won't return) if
  15762.     an uncaught signal is delivered which terminates the process.
  15763.  
  15764.     SIGKILL cannot be blocked; any attempt to block SIGKILL is ignored
  15765.     by sigsuspend() without indication of an error.
  15766.  
  15767.     Every object of type sigset_t should be initialized at least once
  15768.     with either sigemptyset() or sigfillset() before any use.  When
  15769.     using an uninitialized object of type sigset_t, the results are
  15770.     undefined.
  15771.  
  15772. ■returnvalue
  15773.  
  15774.     sigsuspend() sets errno to EINTR and returns -1.
  15775.  
  15776. ■restrictions
  15777.  
  15778.     sigsuspend() is not implemented under DOS.
  15779.  
  15780. ■seealso alarm() kill() pause() sigaction() sigemptyset() sigprocmask()
  15781.  
  15782.  
  15783. ■function sleep()
  15784. ■compat POSIX.1
  15785. ■headers
  15786. #include <stdlib.h>
  15787. ■endheaders
  15788.  
  15789. ■param SEC
  15790. ■prototype
  15791. unsigned sleep (unsigned SEC);
  15792. ■endprototype
  15793.  
  15794.     Suspend the calling process for SEC seconds or until an unblocked
  15795.     signal is caught.  SEC should not exceed 4294967.
  15796.  
  15797. ■returnvalue
  15798.  
  15799.     If interrupted by a caught signal, sleep() returns the number of
  15800.     remaining seconds.  Otherwise, sleep() returns 0.
  15801.  
  15802. ■implementation
  15803.  
  15804.     alarm() and SIGALRM don't interfer with the operation of sleep().
  15805.  
  15806. ■restrictions
  15807.  
  15808.     sleep() is also interrupted by ignored signals and, under OS/2, by
  15809.     blocked signals.
  15810.  
  15811. ■seealso alarm() sigaction() signal() sigprocmask() _sleep2()
  15812.  
  15813.  
  15814. ■function _sleep2()
  15815. ■compat emx
  15816. ■headers
  15817. #include <stdlib.h>
  15818. ■endheaders
  15819.  
  15820. ■param MILLISEC
  15821. ■prototype
  15822. unsigned _sleep2 (unsigned MILLISEC);
  15823. ■endprototype
  15824.  
  15825.     Suspend the calling process for MILLISEC milliseconds.  As the
  15826.     system clock is used for timing, the actual duration of the time
  15827.     interval depends on the granularity of the system clock.  The time
  15828.     interval is rounded up to the next clock tick.  Also note that
  15829.     calling _sleep2() involves an overhead.
  15830.  
  15831.     Delivery of a signal which is caught interrupts _sleep2().
  15832.  
  15833. ■returnvalue
  15834.  
  15835.     _sleep2() returns 0.
  15836.  
  15837. ■restrictions
  15838.  
  15839.     Under OS/2, sleep() is also interrupted by ignored signals and by
  15840.     blocked signals.  Under DOS, sleep() is not interrupted by
  15841.     signals.
  15842.  
  15843. ■seealso alarm() sigaction() signal() sigprocmask() sleep()
  15844.  
  15845.  
  15846. ■function _smutex_available()
  15847. ■compat emx
  15848. ■headers
  15849. #include <sys/builtin.h>
  15850. #include <sys/smutex.h>
  15851. ■endheaders
  15852.  
  15853. ■param SEM
  15854. ■prototype
  15855. int _smutex_available (volatile _smutex *SEM);
  15856. ■endprototype
  15857.  
  15858.     Check if the _smutex semaphore pointed to by SEM is available or
  15859.     owned, without changing the state of the semaphore and without
  15860.     blocking.  Return zero if the semaphore is owned, return a
  15861.     non-zero value if the semaphore is available.  Note that
  15862.     _smutex_available() just returns a snapshot of the state of the
  15863.     semaphore; in presence of other threads or other processes having
  15864.     access to the semaphore, the state may change at any time, even
  15865.     before _smutex_available() returns. This function can be used to
  15866.     avoid deadlock.
  15867.  
  15868. ■returnvalue
  15869.  
  15870.     _smutex_available() returns a non-zero value if the semaphore is
  15871.     available.  _smutex_available() returns 0 if the semaphore is
  15872.     owned.
  15873.  
  15874. ■seealso _smutex_release() _smutex_request()
  15875.  
  15876.  
  15877. ■function _smutex_release()
  15878. ■compat emx
  15879. ■headers
  15880. #include <sys/builtin.h>
  15881. #include <sys/smutex.h>
  15882. ■endheaders
  15883.  
  15884. ■param SEM
  15885. ■prototype
  15886. void _smutex_release (volatile _smutex *SEM);
  15887. ■endprototype
  15888.  
  15889.     Relinquish ownership of the _smutex semaphore pointed to by SEM.
  15890.     Unblocking any process blocking in ■hpt{_smutex_request()} for
  15891.     this semaphore won't occur before the current time slice ends.
  15892.  
  15893. ■seealso __cxchg() _smutex_available() _smutex_request()
  15894.  
  15895.  
  15896. ■function _smutex_request()
  15897. ■compat emx
  15898. ■headers
  15899. #include <sys/builtin.h>
  15900. #include <sys/smutex.h>
  15901. ■endheaders
  15902.  
  15903. ■param SEM FLAGS
  15904. ■prototype
  15905. void _smutex_request (volatile _smutex *SEM);
  15906. ■endprototype
  15907.  
  15908.     Request ownership of the _smutex semaphore pointed to by SEM.  If
  15909.     the semaphore is available, it will be set to owned and
  15910.     _smutex_request() will return immediately.
  15911.  
  15912.     If the semaphore is owned, _smutex_request() will suspend the
  15913.     current thread, periodically checking whether the semaphore is
  15914.     available or still owned.  If the semaphore is available, it will
  15915.     be set atomically to owned and _smutex_request() will return.
  15916.     Otherwise, _smutex_request() will continue polling.
  15917.     _smutex_request() does not return if a signal occurs while
  15918.     blocking.
  15919.  
  15920.     Note that ownership of an _smutex semaphore is not tied to a
  15921.     thread, that is, it's not a thread which owns the semaphore.  This
  15922.     is in contrast to OS/2's mutex semaphores (HMTX).  Deadlock will
  15923.     occur if _smutex_request() is called twice for the same semaphore
  15924.     by the same thread without an intervening call to
  15925.     _smutex_release().  This fact is important to keep in mind in
  15926.     presence of signals.  Signal handlers must not request semaphores
  15927.     which can be owned by the interrupted code.  You might want to
  15928.     block signals before requesting ownership of an _smutex semaphore.
  15929.  
  15930. ■restrictions
  15931.  
  15932.     Under DOS, _smutex_request() crashes if the semaphore is already
  15933.     owned.
  15934.  
  15935. ■seealso __cxchg() _fmutex_create() _rmutex_create() _smutex_available() _smutex_release()
  15936.  
  15937.  
  15938. ■function snprintf()
  15939. ■compat BSD
  15940. ■headers
  15941. #include <stdio.h>
  15942. ■endheaders
  15943.  
  15944. ■param BUFFER N FORMAT
  15945. ■prototype
  15946. int snprintf (char *BUFFER, size_t N, const char *FORMAT, ...);
  15947. ■endprototype
  15948.  
  15949.     Formatted output to the string pointed to by BUFFER.  If N is
  15950.     zero, BUFFER may be NULL and nothing is written.  Otherwise, up to
  15951.     ■pa{N}-1 characters and a terminating null character will be
  15952.     written to BUFFER.  If formatting yields more than ■pa{N}-1
  15953.     characters, output will be truncated.  The terminating null
  15954.     character will be put into BUFFER even if output is truncated.
  15955.  
  15956. ■returnvalue
  15957.  
  15958.     On success, snprintf() returns the number of characters (excluding
  15959.     the terminating null character) that would have been written to
  15960.     BUFFER if N had been sufficiently large.  That is, output is
  15961.     truncated iff the returned value is greater than or equal to N.
  15962.     On error, snprintf() returns EOF.
  15963.  
  15964. ■seealso sprintf() vsnprintf()
  15965.  
  15966.  
  15967. ■function sopen()
  15968. ■compat PC
  15969. ■headers
  15970. #include <io.h>
  15971. #include <share.h>
  15972. ■endheaders
  15973.  
  15974. ■param NAME OFLAG SHFLAG PMODE ISIZE
  15975. ■prototype
  15976. int sopen (const char *NAME, int OFLAG, int SHFLAG);
  15977. int sopen (const char *NAME, int OFLAG, int SHFLAG, int PMODE);
  15978.  
  15979. int sopen (const char *NAME, int OFLAG, int SHFLAG,
  15980.            unsigned long ISIZE);
  15981. int sopen (const char *NAME, int OFLAG, int SHFLAG, int PMODE,
  15982.            unsigned long ISIZE);
  15983. ■endprototype
  15984.  
  15985.     Open a file or device with an explicit sharing mode.  NAME points
  15986.     to the name of the file or device.  OFLAG contains one or more of
  15987.     the following values, combined by the ■tt{|} operator:
  15988.  
  15989. ■description
  15990.  
  15991. ■item O_RDONLY
  15992.  
  15993.     Open for reading.  Writing is not allowed
  15994.  
  15995. ■item O_WRONLY
  15996.  
  15997.     Open for writing.  Reading is not allowed
  15998.  
  15999. ■item O_RDWR
  16000.  
  16001.     Open for reading and writing
  16002.  
  16003. ■item O_APPEND
  16004.  
  16005.     Move the file pointer to the end of file before any write
  16006.     operation takes place.  This is used for appending to a file
  16007.  
  16008. ■item O_CREAT
  16009.  
  16010.     Create the file if it does not exist.  If this flag is set, the
  16011.     PMODE argument is required
  16012.  
  16013. ■item O_TRUNC
  16014.  
  16015.     Truncate the size of the file to 0
  16016.  
  16017. ■item O_EXCL
  16018.  
  16019.     Fail if the O_CREAT is used and the file already exists
  16020.  
  16021. ■item O_NONBLOCK alias O_NDELAY
  16022.  
  16023.     Currently ignored
  16024.  
  16025. ■item O_BINARY
  16026.  
  16027.     Binary mode, no translation.  See below
  16028.  
  16029. ■item O_TEXT
  16030.  
  16031.     Text mode, translate CR/LF to newline.  See below
  16032.  
  16033. ■item O_NOINHERIT
  16034.  
  16035.     Child processes won't inherit the file handle
  16036.  
  16037. ■item O_SYNC
  16038.  
  16039.     Write operations are synchronous, that is, write() waits until
  16040.     file data has been physically written
  16041.  
  16042. ■item O_SIZE
  16043.  
  16044.     Set the initial size of the file to ISIZE if the file is a new
  16045.     file (O_CREAT) or an existing file truncated (O_TRUNC).  If this
  16046.     flag is set, the ISIZE argument is required.  O_SIZE is ignored
  16047.     under DOS
  16048.  
  16049. ■enddescription
  16050.  
  16051.     If a new file is created, PMODE (modified by the umask value), is
  16052.     used to set the file permissions.  S_IREAD grants read access,
  16053.     S_IWRITE grants write access.  S_IREAD is ignored (DOS and OS/2
  16054.     limitation).
  16055.  
  16056.     There are two additional OFLAG flags: O_TEXT for text mode,
  16057.     O_BINARY for binary mode.  Text mode, which is the default,
  16058.     translates each CR/LF pair to a newline character on input and
  16059.     translates newline characters to CR/LF pairs on output.  If the last
  16060.     character of a file is Ctrl-Z, it is discarded on input.  Binary
  16061.     mode disables these transformations.
  16062.  
  16063.     If the file or device cannot be opened, open() sets errno and
  16064.     returns -1.  If open() succeeds, the file handle is returned.  The
  16065.     file handle is always greater than -1.
  16066.  
  16067.     The mode ■tt{O_TRUNC|O_RDONLY} is not implemented.  A Ctrl-Z at
  16068.     the end of the file is removed only when opening a file for
  16069.     appending in text mode.  Ctrl-Z at the end of the file is
  16070.     obsolete, anyway.
  16071.  
  16072.     The sharing mode of the file is given by SHFLAG.  The following
  16073.     sharing modes are available:
  16074.  
  16075. ■description
  16076.  
  16077. ■item SH_DENYRW
  16078.  
  16079.     Deny read and write access
  16080.  
  16081. ■item SH_DENYRD
  16082.  
  16083.     Deny read access (permit write access)
  16084.  
  16085. ■item SH_DENYWR
  16086.  
  16087.     Deny write access (permit read access)
  16088.  
  16089. ■item SH_DENYNO
  16090.  
  16091.     Deny nothing (permit read and write access)
  16092.  
  16093. ■enddescription
  16094.  
  16095. ■returnvalue
  16096.  
  16097.     sopen() returns a file handle for the file.  On error, sopen()
  16098.     sets errno and returns -1.
  16099.  
  16100. ■implementation
  16101.  
  16102.     O_SIZE is an emx extension.  It's the caller's responsibility to
  16103.     truncate the file if its size should be less than ISIZE bytes.
  16104.     O_SIZE is ignored under DOS.
  16105.  
  16106. ■restrictions
  16107.  
  16108.     Under DOS, the O_NOINHERIT flag is currently ignored for child
  16109.     processes which are DOS programs (vs. emx programs).  Under DOS,
  16110.     the O_SYNC and O_SIZE flags are ignored.
  16111.  
  16112. ■seealso close() fcntl() fdopen() ftruncate() open()
  16113.  
  16114.  
  16115. ■function spawn*() spawnl() spawnle() spawnlp() spawnlpe() spawnv() spawnve() spawnvp() spawnvpe()
  16116. ■compat PC *
  16117. ■headers
  16118. #include <process.h>
  16119. ■endheaders
  16120.  
  16121. ■param MODE NAME ARG0 ARGV ENVP
  16122. ■prototype
  16123. int spawnl (int MODE, const char *NAME, const char *ARG0, ...);
  16124. int spawnle (int MODE, const char *NAME, const char *ARG0, ...);
  16125. int spawnlp (int MODE, const char *NAME, const char *ARG0, ...);
  16126. int spawnlpe (int MODE, const char *NAME, const char *ARG0, ...);
  16127. int spawnv (int MODE, const char *NAME, char * const ARGV[]);
  16128. int spawnve (int MODE, const char *NAME,char * const ARGV[],
  16129.              char * const ENVP[]);
  16130. int spawnvp (int MODE, const char *NAME, char * const ARGV[]);
  16131. int spawnvpe (int MODE, const char *NAME, char * const ARGV[],
  16132.               char * const ENVP[]);
  16133. ■endprototype
  16134.  
  16135.     Run a program.  NAME points to the name of the executable file to
  16136.     run.
  16137.  
  16138.     Use spawnl(), spawnle(), spawnlp() or spawnlpe() for passing a
  16139.     fixed number of arguments.  ARG0 points to a string containing the
  16140.     0th argument which is the program name, by convention.  Following
  16141.     ARG0, pointers to the arguments are passed.  After the last
  16142.     argument pointer, a null pointer cast to `■tt{char *}' must be
  16143.     following.  At least ARG0 must be specified.
  16144.  
  16145.     Use spawnv(), spawnve(), spawnvp() or spawnvpe() for passing a
  16146.     variable number of arguments.  ARGV points to an array of pointers
  16147.     to strings.  The first entry is the program name, by convention.
  16148.     The last argument pointer must be followed by a null pointer.
  16149.  
  16150.     spawnl(), spawnlp(), spawnv() and spawnvp() pass the environment
  16151.     of the current process to the child process.  To pass a different
  16152.     environment to the child process pass a pointer to an array of
  16153.     strings after the null argument pointer of spawnle() and
  16154.     spawnlpe() or pass the pointer in the ENVP argument of spawnve()
  16155.     and spawnvpe().  The last string pointer in the array must be
  16156.     followed by a null pointer.
  16157.  
  16158.     If both the child process and the parent process use emx.exe or
  16159.     emx.dll, the child process will inherit the signal actions of the
  16160.     parent process: Signals set to SIG_IGN in the parent process will
  16161.     be set to SIG_IGN in the child process, signals set to SIG_DFL in
  16162.     the parent process will be set to SIG_DFL in the child process,
  16163.     signals caught in the parent process will be set to SIG_DFL in the
  16164.     child process.
  16165.  
  16166.     The MODE argument specifies how to run the child process.  You
  16167.     have to include exactly one of the following values:
  16168.  
  16169. ■description
  16170.  
  16171. ■item P_WAIT
  16172.  
  16173.     run the process synchronously, that is, control returns to the
  16174.     parent process after the child process finishes
  16175.  
  16176. ■item P_NOWAIT
  16177.  
  16178.     run the process asynchronously, that is in parallel with the
  16179.     parent process.  Use wait() to wait for completion of the child
  16180.     process and to get its termination status.  Under DOS, the process
  16181.     is run synchronously
  16182.  
  16183. ■item P_OVERLAY
  16184.  
  16185.     replace the parent process, that is, run the child process and
  16186.     terminate the parent process
  16187.  
  16188. ■item P_DEBUG
  16189.  
  16190.     run the process in debugging mode, that is, under control of the
  16191.     parent process.  Use ptrace() to control the child process
  16192.  
  16193. ■item P_DETACH
  16194.  
  16195.     run the process detached, that is, without input and output.
  16196.     P_DETACH is not available under DOS
  16197.  
  16198. ■item P_SESSION
  16199.  
  16200.     run the process in a separate session.  P_SESSION is not available
  16201.     under DOS.
  16202.  
  16203. ■item P_PM
  16204.  
  16205.     the process is a Presentation Manager program.  P_PM is not
  16206.     available under DOS.
  16207.  
  16208. ■enddescription
  16209.  
  16210.     Additional flags are available for P_SESSION, which can be added
  16211.     by using the ■tt{|} operator:
  16212.  
  16213. ■description
  16214.  
  16215. ■item P_QUOTE
  16216.  
  16217.     Quote all the arguments, that is, suppress expansion of command
  16218.     line arguments by ■hpt{_wildcard()} and ■hpt{_response()} in the
  16219.     child process.  Without P_QUOTE, arguments are not quoted
  16220.  
  16221. ■item P_TILDE
  16222.  
  16223.     Use the `MKS Korn shell' method for passing command line arguments
  16224.     (OS/2, only; this was the default in emx 0.8h and earlier).  That
  16225.     method passes the arguments in the third and following strings of
  16226.     DosExecPgm.  The tilde character is used as flag at the start of
  16227.     the third string
  16228.  
  16229. ■enddescription
  16230.  
  16231.     Use one of the following flags for selecting the session type:
  16232.  
  16233. ■description
  16234.  
  16235. ■item P_DEFAULT
  16236.  
  16237.     let the operating system choose the session type
  16238.  
  16239. ■item P_FULLSCREEN
  16240.  
  16241.     start a full-screen session
  16242.  
  16243. ■item P_WINDOWED
  16244.  
  16245.     start a windowed session
  16246.  
  16247. ■enddescription
  16248.  
  16249.     These flags (which can be used with P_SESSION and P_PM) control
  16250.     the initial appearance of the window:
  16251.  
  16252. ■description
  16253.  
  16254. ■item P_MINIMIZE
  16255.  
  16256.     minimize the window
  16257.  
  16258. ■item P_MAXIMIZE
  16259.  
  16260.     maximize the window
  16261.  
  16262. ■enddescription
  16263.  
  16264.     Additionally, you can use the following flags with P_SESSION and
  16265.     P_PM:
  16266.  
  16267. ■description
  16268.  
  16269. ■item P_BACKGROUND
  16270.  
  16271.     start the session in the background
  16272.  
  16273. ■item P_FOREGROUND
  16274.  
  16275.     start the session in the foreground.  This works only if the
  16276.     calling session is in the foreground.  P_FOREGROUND is the default
  16277.  
  16278. ■item P_NOCLOSE
  16279.  
  16280.     don't close the window automatically when the process ends
  16281.     (ignored for P_PM)
  16282.  
  16283. ■item P_UNRELATED
  16284.  
  16285.     create an independent session.  SIGCHLD won't be raised when the
  16286.     session terminates.  wait() and waitpid() cannot be used on that
  16287.     session.  spawn*() returns zero (instead of a process ID) on
  16288.     success.
  16289.  
  16290. ■enddescription
  16291.  
  16292.     Additional flags are available for P_DEBUG, which can be added
  16293.     by using the ■tt{|} operator:
  16294.  
  16295. ■description
  16296.  
  16297. ■item P_NOSESSION
  16298.  
  16299.     don't run debuggee in a separate session.  The same effect can be
  16300.     achieved with the -E emx option.
  16301.  
  16302. ■item P_DEBUGDESC
  16303.  
  16304.     enable debugging of descendant processes of the debuggee; see
  16305.     ■hpt{ptrace()} for details.  P_DEBUGDESC cannot be used if
  16306.     _UF_PTRACE_STANDARD is in effect, see ■hpt{_uflags()} for details.
  16307.  
  16308. ■enddescription
  16309.  
  16310.     When the new process terminates, SIGCHLD is sent to the process
  16311.     which started that process.  You should use wait() or waitpid() to
  16312.     get the return code of the process.  If you don't retrieve the
  16313.     return code for asynchronous child processes, the return codes
  16314.     fill up memory.  All this does not apply to P_WAIT, P_OVERLAY and
  16315.     P_DETACH.
  16316.  
  16317. ■returnvalue
  16318.  
  16319.     These functions return the return value of the child process
  16320.     (P_WAIT), or the process ID of the child process (P_NOWAIT,
  16321.     P_DEBUG, P_SESSION and P_PM), or zero (P_UNRELATED) if successful.
  16322.     On error they return -1.
  16323.  
  16324. ■restrictions
  16325.  
  16326.     The command line length is restricted to 126 characters when
  16327.     running DOS programs.  DOS programs can only be run in P_WAIT or
  16328.     P_NOWAIT mode.  P_NOWAIT runs processes synchronously under DOS.
  16329.     The termination status of only one process will be kept for wait()
  16330.     under DOS.  The default extension is .exe; if you want to run a
  16331.     .com file, explicitly add .com.  Currently, DOS seems to crash if
  16332.     you try to spawn a .com file without using emx option -p, see
  16333.     `■hpt{Using emx options}'.  (The machine crashes on the second
  16334.     attempt.)  With the system call library sys.lib (■hpt{-Zsys}),
  16335.     only modes P_WAIT, P_NOWAIT and P_OVERLAY are currently available.
  16336.  
  16337. ■seealso exit() ptrace() system() wait()
  16338.  
  16339.  
  16340. ■function _splitargs()
  16341. ■compat emx
  16342. ■headers
  16343. #include <stdlib.h>
  16344. ■endheaders
  16345.  
  16346. ■param STRING COUNT
  16347. ■prototype
  16348. char **_splitargs (char *STRING, int *COUNT);
  16349. ■endprototype
  16350.  
  16351.     Parse the string pointed to by STRING like a command line and
  16352.     build a vector of pointers to the arguments.  The vector is
  16353.     terminated by a NULL pointer.  The number of arguments is stored
  16354.     to the variable pointed to by COUNT unless COUNT is NULL.  The
  16355.     string pointed to by STRING is modified by _splitargs(), the
  16356.     pointers in the resulting vector point into the string pointed to
  16357.     by STRING.  _splitargs() allocates the vector using malloc().  If
  16358.     you no longer need the vector, use free() to deallocate it.  On
  16359.     error, _splitargs() sets errno and returns NULL.
  16360.  
  16361.     Arguments in the string pointed to by STRING are separated by
  16362.     whitespace (one or more blanks, tabs and linefeeds).  Whitespace
  16363.     at the start of the string is skipped.  To include blanks, tabs or
  16364.     linefeeds in an argument, the argument must be quoted using double
  16365.     quotation marks.  To remove the special meaning of a double quote,
  16366.     precede it with a backslash.  To remove the special meaning of a
  16367.     backslash in front of a double quote, precede the backslash with a
  16368.     backslash.  The backslash character doesn't have a special meaning
  16369.     unless it precedes a double quote or any number of backslashes
  16370.     followed by a double quote.
  16371.  
  16372.     In other words: If there are n backslashes (\) immediately
  16373.     preceding a double quote character ("), floor(n/2) backslashes are
  16374.     put into the argument.  If n is odd, the double quote character is
  16375.     put into the argument.  If n is even (including zero), the double
  16376.     quote character is used for quoting, that is, spaces are not
  16377.     treated as argument delimiters until the next `quoting' double
  16378.     quote character (ie, a double quote character immediately preceded
  16379.     by an even number (including zero) of backslashes) is found.
  16380.     Backslashes not preceding a quote character are always read as
  16381.     backslashes.
  16382.  
  16383. ■returnvalue
  16384.  
  16385.     See above.
  16386.  
  16387.  
  16388. ■function _splitpath()
  16389. ■compat PC
  16390. ■headers
  16391. #include <stdlib.h>
  16392. ■endheaders
  16393.  
  16394. ■param SRC DRIVE DIR FNAME EXT
  16395. ■prototype
  16396. void _splitpath (const char *SRC, char *DRIVE, char *DIR, char *FNAME,
  16397.                  char *EXT);
  16398. ■endprototype
  16399.  
  16400.     Split the path name pointed to by SRC into its components.  The
  16401.     drive name (including the colon) is stored to the array pointed to
  16402.     by DRIVE.  The directory (including the final slash or backslash)
  16403.     is copied to the array pointed to by DIR, the file name without
  16404.     extension is copied to the array pointed to by FNAME, the
  16405.     extension (including the dot) is copied to the array pointed to by
  16406.     EXT.  The arrays should be of size _MAX_DRIVE, _MAX_DIR,
  16407.     _MAX_FNAME and _MAX_EXT, respectively.  These constants include
  16408.     the terminating null characters.  If one of the pointers (except
  16409.     for SRC) is NULL, that component is not stored.
  16410.  
  16411.     _splitpath() properly handles DBCS characters.
  16412.  
  16413. ■seealso _fngetdrive() _getext() _getname() _makepath() _nls_init()
  16414.  
  16415. ■samplecode
  16416. char drive[_MAX_DRIVE], dir[_MAX_DIR];
  16417. char fname[_MAX_FNAME], ext[_MAX_EXT];
  16418. char *path = "c:/files/more/test.file.c";
  16419.  
  16420. _splitpath (path, drive, dir, fname, ext);
  16421. ■endsamplecode
  16422.  
  16423.     Results of the example:
  16424.  
  16425. ■example
  16426. drive = "c:"
  16427. dir   = "/files/more/"
  16428. fname = "test.file"
  16429. ext   = ".c"
  16430. ■endexample
  16431.  
  16432.  
  16433. ■function sprintf()
  16434. ■compat C90
  16435. ■headers
  16436. #include <stdio.h>
  16437. ■endheaders
  16438.  
  16439. ■param BUFFER FORMAT
  16440. ■prototype
  16441. int sprintf (char *BUFFER, const char *FORMAT, ...);
  16442. ■endprototype
  16443.  
  16444.     Formatted output to the string pointed to by BUFFER.  The string
  16445.     must be big enough to hold the output.  See ■hpt{printf()} for details.
  16446.  
  16447. ■returnvalue
  16448.  
  16449.     On success, sprintf() returns the number of characters copied to
  16450.     BUFFER (excluding the terminating null character).  On error,
  16451.     sprintf() returns EOF.
  16452.  
  16453. ■seealso gcvt() _itoa() _mfopen() printf() sscanf() snprintf()
  16454.  
  16455.  
  16456. ■function sqrt() sqrtl()
  16457. ■compat C90 C9X
  16458. ■headers
  16459. #include <math.h>
  16460. ■endheaders
  16461.  
  16462. ■param X
  16463. ■prototype
  16464. double sqrt (double X);
  16465. long double sqrtl (long double X);
  16466. ■endprototype
  16467.  
  16468.     Compute the square root of X.
  16469.  
  16470.     sqrtl() uses the ■tt{long double} format.
  16471.  
  16472. ■returnvalue
  16473.  
  16474.     sqrt() returns the square root of X.  If X is negative, a NaN is
  16475.     returned and errno set to EDOM.
  16476.  
  16477. ■seealso cbrt() pow()
  16478.  
  16479.  
  16480. ■function _srotl() _srotr()
  16481. ■compat VAC++
  16482. ■headers
  16483. #include <sys/builtin.h>
  16484. ■endheaders
  16485.  
  16486. ■param VALUE SHIFT
  16487. ■prototype
  16488. unsigned short _srotl (unsigned short VALUE, int SHIFT);
  16489. unsigned short _srotr (unsigned short VALUE, int SHIFT);
  16490. ■endprototype
  16491.  
  16492.     _srotl() returns VALUE (16 bits) rotated left by SHIFT bits.  If
  16493.     SHIFT is 1, bit 14 is returned as bit 15, bit 13 is returned as bit
  16494.     14, and so on, bit 0 is returned as bit 1, and bit 15 is
  16495.     returned as bit 0.
  16496.  
  16497.     _srotr() returns VALUE (16 bits) rotated right by SHIFT bits.  If
  16498.     SHIFT is 1, bit 1 is returned as bit 0, bit 2 is returned as bit
  16499.     1, and so on, bit 7 is returned as bit 6, and bit 0 is returned as
  16500.     bit 7.
  16501.  
  16502.     SHIFT should be 0 through 15.
  16503.  
  16504.     These functions are implemented as inline functions.
  16505.  
  16506. ■seealso _crotl() _crotr() _lrotl() _lrotr()
  16507.  
  16508.  
  16509. ■function sscanf()
  16510. ■compat C90
  16511. ■headers
  16512. #include <stdio.h>
  16513. ■endheaders
  16514.  
  16515. ■param BUFFER FORMAT
  16516. ■prototype
  16517. int sscanf (const char *BUFFER, const char *FORMAT, ...);
  16518. ■endprototype
  16519.  
  16520.     Parse the string pointed to by BUFFER according to the format
  16521.     string pointed to by FORMAT.  For each field in the format string
  16522.     there must be a pointer to the location receiving the value.  The
  16523.     pointers are passed after the FORMAT argument.
  16524.  
  16525. ■returnvalue
  16526.  
  16527.     If successful, sscanf() returns the number of fields converted.
  16528.     On error, sscanf() returns EOF.
  16529.  
  16530. ■seealso scanf() sprintf() strptime()
  16531.  
  16532. ■samplecode
  16533. char inp[512];
  16534. int year, month, day;
  16535. ...
  16536. if (fgets (inp, sizeof (inp), stdin) != NULL
  16537.     && sscanf (inp, "%d/%d/%d", &year, &month, &day) == 3)
  16538.   {
  16539.     ...
  16540.   }
  16541. ■endsamplecode
  16542.  
  16543.  
  16544. ■function stat()
  16545. ■compat UNIX
  16546. ■headers
  16547. #include <io.h>
  16548. #include <sys/types.h>
  16549. #include <sys/stat.h>
  16550. ■endheaders
  16551.  
  16552. ■param NAME BUFFER
  16553. ■prototype
  16554. int stat (const char *NAME, struct stat *BUFFER);
  16555. ■endprototype
  16556.  
  16557.     Retrieve information about a file or directory.  NAME is a pointer
  16558.     to the name of the file or directory.  stat() will put the data
  16559.     into the structure pointed to by BUFFER:
  16560.  
  16561. ■example
  16562. struct stat
  16563. {
  16564.   dev_t   st_dev;       /* Device number */
  16565.   ino_t   st_ino;       /* Inode number */
  16566.   mode_t  st_mode;      /* Protection mode, S_IREAD etc. */
  16567.   nlink_t st_nlink;     /* Number of links -- always 1 */
  16568.   uid_t   st_uid;       /* User ID of owner -- always 0 (root) */
  16569.   gid_t   st_gid;       /* Group ID of owner -- always 0 (root) */
  16570.   dev_t   st_rdev;      /* Always 0 */
  16571.   off_t   st_size;      /* Size of file */
  16572.   time_t  st_atime;     /* Time of last access */
  16573.   time_t  st_mtime;     /* Time of last modification */
  16574.   time_t  st_ctime;     /* Time of creation */
  16575.   long    st_attr;      /* File attributes (OS/2 and DOS style) */
  16576.   long    st_reserved;  /* Currently not used */
  16577. };
  16578. ■endexample
  16579.  
  16580. ■returnvalue
  16581. ■description
  16582. ■item 0
  16583.     success
  16584. ■item -1
  16585.     error (errno is set)
  16586. ■enddescription
  16587.  
  16588. ■restrictions
  16589.  
  16590.     st_dev and st_rdev are set to zero.  Each call to stat() returns a
  16591.     different value for st_ino.
  16592.  
  16593. ■seealso fstat()
  16594.  
  16595.  
  16596. ■function _status87()
  16597. ■compat PC
  16598. ■headers
  16599. #include <float.h>
  16600. ■endheaders
  16601.  
  16602. ■prototype
  16603. unsigned _status87 (void);
  16604. ■endprototype
  16605.  
  16606.     Return the coprocessor status word.
  16607.  
  16608. ■returnvalue
  16609.  
  16610.     See above.
  16611.  
  16612. ■seealso _clear87() _control87()
  16613.  
  16614.  
  16615. ■function strcat()
  16616. ■compat C90
  16617. ■headers
  16618. #include <string.h>
  16619. ■endheaders
  16620.  
  16621. ■param STRING1 STRING2
  16622. ■prototype
  16623. char *strcat (char *STRING1, const char *STRING2);
  16624. ■endprototype
  16625.  
  16626.     Append the null-terminated string pointed to by STRING2 to the
  16627.     null-terminated array pointed to by STRING1.  The objects must
  16628.     not overlap.
  16629.  
  16630. ■returnvalue
  16631.  
  16632.     strcat() returns STRING1.
  16633.  
  16634. ■seealso strcpy()
  16635.  
  16636.  
  16637. ■function strchr()
  16638. ■compat C90
  16639. ■headers
  16640. #include <string.h>
  16641. ■endheaders
  16642.  
  16643. ■param STRING C
  16644. ■prototype
  16645. char *strchr (const char *STRING, int C);
  16646. ■endprototype
  16647.  
  16648.     Return a pointer to the first occurrence of the character C in the
  16649.     null-terminated string pointed to by STRING.  If there is no
  16650.     character C in that string, NULL is returned.  If C is the null
  16651.     character (0), a pointer to the terminating null character of that
  16652.     string is returned.
  16653.  
  16654. ■returnvalue
  16655.  
  16656.     See above.
  16657.  
  16658. ■seealso index() memchr() strrchr() strstr()
  16659.  
  16660.  
  16661. ■function strcmp()
  16662. ■compat C90
  16663. ■headers
  16664. #include <string.h>
  16665. ■endheaders
  16666.  
  16667. ■param STRING1 STRING2
  16668. ■prototype
  16669. int strcmp (const char *STRING1, const char *STRING2);
  16670. ■endprototype
  16671.  
  16672.     Compare the null-terminated strings pointed to by STRING1 and
  16673.     STRING2.  If the string pointed to by STRING1 is less than the
  16674.     string pointed to by STRING2, a negative value is returned.  If
  16675.     the string pointed to by STRING1 is equal to the string pointed to
  16676.     by STRING2, zero is returned.  If the string pointed to by STRING1
  16677.     is greater than the string pointed to by STRING2, a positive value
  16678.     is returned.
  16679.  
  16680. ■returnvalue
  16681. ■description
  16682. ■item <0
  16683.    1st string < 2nd string
  16684. ■item =0
  16685.    1st string = 2nd string
  16686. ■item >0
  16687.    1st string > 2nd string
  16688. ■enddescription
  16689.  
  16690. ■seealso memcmp() stricmp() strncmp()
  16691.  
  16692.  
  16693. ■function strcoll()
  16694. ■compat C90
  16695. ■headers
  16696. #include <string.h>
  16697. ■endheaders
  16698.  
  16699. ■param STRING1 STRING2
  16700. ■prototype
  16701. int strcoll (const char *STRING1, const char *STRING2);
  16702. ■endprototype
  16703.  
  16704.     Compare the null-terminated strings pointed to by STRING1 and
  16705.     STRING2 according to the LC_COLLATE category of the current
  16706.     locale.  If the string pointed to by STRING1 is less than the
  16707.     string pointed to by STRING2, a negative value is returned.  If
  16708.     the string pointed to by STRING1 is equal to the string pointed to
  16709.     by STRING2, zero is returned.  If the string pointed to by STRING1
  16710.     is greater than the string pointed to by STRING2, a positive value
  16711.     is returned.
  16712.  
  16713. ■returnvalue
  16714. ■description
  16715. ■item <0
  16716.    1st string < 2nd string
  16717. ■item =0
  16718.    1st string = 2nd string
  16719. ■item >0
  16720.    1st string > 2nd string
  16721. ■enddescription
  16722.  
  16723. ■restrictions
  16724.  
  16725.     Currently, locale is ignored: strcoll() is equivalent to strcmp().
  16726.  
  16727. ■seealso setlocale() strcmp()
  16728.  
  16729.  
  16730. ■function strcpy()
  16731. ■compat C90
  16732. ■headers
  16733. #include <string.h>
  16734. ■endheaders
  16735.  
  16736. ■param STRING1 STRING2
  16737. ■prototype
  16738. char *strcpy (char *STRING1, const char *STRING2);
  16739. ■endprototype
  16740.  
  16741.     Copy the null-terminated string pointed to by STRING2 to the array
  16742.     pointed to by STRING1.  The objects must not overlap.
  16743.  
  16744. ■returnvalue
  16745.  
  16746.     strcpy() returns STRING1.
  16747.  
  16748. ■seealso memccpy() memcpy() strcat() strncpy()
  16749.  
  16750.  
  16751. ■function strcspn()
  16752. ■compat C90
  16753. ■headers
  16754. #include <string.h>
  16755. ■endheaders
  16756.  
  16757. ■param STRING1 STRING2
  16758. ■prototype
  16759. size_t strcspn (const char *STRING1, const char *STRING2);
  16760. ■endprototype
  16761.  
  16762.     Return the length of the initial substring of the string pointed
  16763.     to by STRING1 which consists of characters not in the string
  16764.     pointed to by STRING2.  That is, the index of the first character
  16765.     in the string pointed to by STRING1 which also occurs in the
  16766.     string pointed to by STRING2 is returned.  If all characters of
  16767.     the string pointed to by STRING1 are not in the string pointed to
  16768.     by STRING2, the length of the string pointed to by STRING1 is
  16769.     returned.
  16770.  
  16771. ■returnvalue
  16772.  
  16773.     See above.
  16774.  
  16775. ■seealso strpbrk() strspn()
  16776.  
  16777.  
  16778. ■function strdup()
  16779. ■compat UNIX
  16780. ■headers
  16781. #include <string.h>
  16782. ■endheaders
  16783.  
  16784. ■param STRING
  16785. ■prototype
  16786. char *strdup (const char *STRING);
  16787. ■endprototype
  16788.  
  16789.     Creates a duplicate of the string pointed to by STRING by using
  16790.     malloc() to allocate storage and copying the string pointed to by
  16791.     STRING.
  16792.  
  16793. ■returnvalue
  16794.  
  16795.     strdup() returns a pointer to the new string.  If there is not
  16796.     enough memory, strdup() returns NULL.
  16797.  
  16798. ■seealso malloc() strcpy()
  16799.  
  16800.  
  16801. ■function strerror()
  16802. ■compat C90
  16803. ■headers
  16804. #include <string.h>
  16805. ■endheaders
  16806.  
  16807. ■param ERRNUM
  16808. ■prototype
  16809. char *strerror (int ERRNUM);
  16810. ■endprototype
  16811.  
  16812.     Return a pointer to a an error message according to the error
  16813.     number ERRNUM.  You must not write to the string returned by
  16814.     strerror().  The string may get changed by the next call to
  16815.     strerror().
  16816.  
  16817. ■returnvalue
  16818.  
  16819.     See above.
  16820.  
  16821. ■seealso errno perror() sys_errlist
  16822.  
  16823.  
  16824. ■function strftime()
  16825. ■compat C90
  16826. ■headers
  16827. #include <time.h>
  16828. ■endheaders
  16829.  
  16830. ■param STRING SIZE FORMAT T
  16831. ■prototype
  16832. size_t strftime (char *STRING, size_t SIZE, const char *FORMAT,
  16833.                  const struct tm *T);
  16834. ■endprototype
  16835.  
  16836.     Format time.  The output string is written to the array of SIZE
  16837.     characters pointed to by STRING, including the terminating null
  16838.     character.  Like sprintf(), strftime() copies the string pointed
  16839.     to by FORMAT to the array pointed to by STRING, replacing format
  16840.     specifications with formatted data from T.  Ordinary characters
  16841.     are copied unmodified.  The following format specifications are
  16842.     available:
  16843.  
  16844. ■description
  16845. ■item %%
  16846.  
  16847.     percent sign
  16848.  
  16849. ■item %a
  16850.  
  16851.     locale's abbreviated weekday name
  16852.  
  16853. ■item %A
  16854.  
  16855.     locale's full weekday name
  16856.  
  16857. ■item %b
  16858.  
  16859.     locale's abbreviated month name
  16860.  
  16861. ■item %B
  16862.  
  16863.     locale's full month name
  16864.  
  16865. ■item %c
  16866.  
  16867.     locale's date and time
  16868.  
  16869. ■item %d
  16870.  
  16871.     day of month (01-31)
  16872.  
  16873. ■item %D
  16874.  
  16875.     date, this is equivalent to %m/%d/%y
  16876.  
  16877. ■item %e
  16878.  
  16879.     day of month ( 1-31), blank padded
  16880.  
  16881. ■item %h
  16882.  
  16883.     locale's abbreviated month name
  16884.  
  16885. ■item %H
  16886.  
  16887.     hour (00-23)
  16888.  
  16889. ■item %I
  16890.  
  16891.     hour (01-12)
  16892.  
  16893. ■item %j
  16894.  
  16895.     day of year (001-366)
  16896.  
  16897. ■item %m
  16898.  
  16899.     month (01-12)
  16900.  
  16901. ■item %M
  16902.  
  16903.     minute (00-59)
  16904.  
  16905. ■item %n
  16906.  
  16907.     newline character
  16908.  
  16909. ■item %p
  16910.  
  16911.     locale's equivalent to AM or PM, as appropriate
  16912.  
  16913. ■item %r
  16914.  
  16915.     time in AM/PM notation, this is equivalent to %I:%M:%S %p
  16916.  
  16917. ■item %S
  16918.  
  16919.     second (00-59)
  16920.  
  16921. ■item %t
  16922.  
  16923.     TAB character
  16924.  
  16925. ■item %T
  16926.  
  16927.     time, this is equivalent to %H:%M:%S
  16928.  
  16929. ■item %U
  16930.  
  16931.     week number of the year, the first day of the week is Sunday
  16932.     (00-53)
  16933.  
  16934. ■item %w
  16935.  
  16936.     weekday, the first day of the week is Sunday (0-6)
  16937.  
  16938. ■item %W
  16939.  
  16940.     week number of the year, the first day of the week is Monday
  16941.     (00-53)
  16942.  
  16943. ■item %x
  16944.  
  16945.     locale's date representation
  16946.  
  16947. ■item %X
  16948.  
  16949.     locale's time representation
  16950.  
  16951. ■item %y
  16952.  
  16953.     year without century (00-99)
  16954.  
  16955. ■item %Y
  16956.  
  16957.     year with century (1970-2106)
  16958.  
  16959. ■item %Z
  16960.  
  16961.     timezone name or no characters if no time zone is determinable
  16962.  
  16963. ■enddescription
  16964.  
  16965.     If % is followed by a character not listed above, the results are
  16966.     undefined.
  16967.  
  16968. ■returnvalue
  16969.  
  16970.     On success, strftime() returns the number of characters copied to
  16971.     the array pointed to by STRING, excluding the terminating null
  16972.     character.  On failure (SIZE exceeded), strftime() returns 0.
  16973.  
  16974. ■seealso asctime() setlocale() sprintf() strptime() tzset()
  16975.  
  16976.  
  16977. ■function stricmp()
  16978. ■compat PC
  16979. ■headers
  16980. #include <string.h>
  16981. ■endheaders
  16982.  
  16983. ■param STRING1 STRING2
  16984. ■prototype
  16985. int stricmp (const char *STRING1, const char *STRING2);
  16986. ■endprototype
  16987.  
  16988.     Compare the strings pointed to by STRING1 and STRING2, ignoring
  16989.     letter case.  If the strings are equal, 0 is returned.  Otherwise,
  16990.     a positive value is returned if the string pointed to by STRING1
  16991.     is greater than the string pointed to by STRING2 (after conversion
  16992.     to lower case).  A negative value is returned if the string
  16993.     pointed to by STRING1 is less than the string pointed to by
  16994.     STRING2 (after conversion to lower case).  The strings are not
  16995.     modified.
  16996.  
  16997. ■returnvalue
  16998. ■description
  16999. ■item <0
  17000.    1st string < 2nd string
  17001. ■item =0
  17002.    1st string = 2nd string
  17003. ■item >0
  17004.    1st string > 2nd string
  17005. ■enddescription
  17006.  
  17007. ■seealso strcmp() tolower()
  17008.  
  17009.  
  17010. ■function strlen()
  17011. ■compat C90
  17012. ■headers
  17013. #include <string.h>
  17014. ■endheaders
  17015.  
  17016. ■param STRING
  17017. ■prototype
  17018. size_t strlen (const char *STRING);
  17019. ■endprototype
  17020.  
  17021.     Compute the length (number of characters) of the string pointed to
  17022.     by STRING.  The length does not include the terminating null
  17023.     character.
  17024.  
  17025. ■returnvalue
  17026.  
  17027.     strlen() returns the length of the string pointed to by STRING,
  17028.     that is, the number of characters preceding the terminating null
  17029.     character.
  17030.  
  17031. ■seealso strchr()
  17032.  
  17033.  
  17034. ■function strlwr()
  17035. ■compat PC
  17036. ■headers
  17037. #include <string.h>
  17038. ■endheaders
  17039.  
  17040. ■param STRING
  17041. ■prototype
  17042. char *strlwr (char *STRING);
  17043. ■endprototype
  17044.  
  17045.     Convert the string pointed to by STRING to lower case.  The
  17046.     characters ■tt{'A'} through ■tt{'Z'} are mapped to the characters
  17047.     ■tt{'a'} through ■tt{'z'}.  All other characters are not changed.
  17048.  
  17049. ■returnvalue
  17050.  
  17051.     strlwr() returns STRING.
  17052.  
  17053. ■seealso _fnlwr() strupr()
  17054.  
  17055.  
  17056. ■function strncat()
  17057. ■compat C90
  17058. ■headers
  17059. #include <string.h>
  17060. ■endheaders
  17061.  
  17062. ■param STRING1 STRING2 COUNT
  17063. ■prototype
  17064. char *strncat (char *STRING1, const char *STRING2, size_t COUNT);
  17065. ■endprototype
  17066.  
  17067.     Append the null-terminated string pointed to by STRING2 to the
  17068.     null-terminated string pointed to by STRING1.  At most COUNT
  17069.     characters of the string pointed to by STRING2 are appended to the
  17070.     string pointed to by STRING1.  strncat() terminates the new string
  17071.     pointed to by STRING1 with a null character.
  17072.  
  17073. ■returnvalue
  17074.  
  17075.     strncat() returns STRING1.
  17076.  
  17077. ■seealso strcat() strncpy()
  17078.  
  17079.  
  17080. ■function strncmp()
  17081. ■compat C90
  17082. ■headers
  17083. #include <string.h>
  17084. ■endheaders
  17085.  
  17086. ■param STRING1 STRING2 COUNT
  17087. ■prototype
  17088. int strncmp (const char *STRING1, const char *STRING2, size_t COUNT);
  17089. ■endprototype
  17090.  
  17091.     Compare the null-terminated strings pointed to by STRING1 and
  17092.     STRING2.  At most the first COUNT characters are compared.  If the
  17093.     string pointed to by STRING1 is less than the string pointed to by
  17094.     STRING2, a negative value is returned.  If the string pointed to
  17095.     by STRING1 is equal to the string pointed to by STRING2, zero is
  17096.     returned.  If the string pointed to by STRING1 is greater than the
  17097.     string pointed to by STRING2, a positive value is returned.
  17098.  
  17099. ■returnvalue
  17100. ■description
  17101. ■item <0
  17102.    1st string < 2nd string
  17103. ■item =0
  17104.    1st string = 2nd string
  17105. ■item >0
  17106.    1st string > 2nd string
  17107. ■enddescription
  17108.  
  17109. ■seealso memcmp() strcmp() strnicmp()
  17110.  
  17111.  
  17112. ■function strncpy()
  17113. ■compat C90
  17114. ■headers
  17115. #include <string.h>
  17116. ■endheaders
  17117.  
  17118. ■param STRING1 STRING2 COUNT
  17119. ■prototype
  17120. char *strncpy (char *STRING1, const char *STRING2, size_t COUNT);
  17121. ■endprototype
  17122.  
  17123.     Copy the null-terminated string pointed to by STRING2 to the array
  17124.     pointed to by STRING1.  The objects must not overlap.  At most the
  17125.     first COUNT characters of the string pointed to by STRING2 are
  17126.     copied.  If the string pointed to by STRING2 is shorter than COUNT
  17127.     characters, the string pointed to by STRING1 will be padded with
  17128.     null characters to COUNT characters.  If the length of the string
  17129.     pointed to by STRING2 is equal to or greater than COUNT, a
  17130.     terminating null character will not be appended.
  17131.  
  17132. ■returnvalue
  17133.  
  17134.     strncpy() returns STRING1.
  17135.  
  17136. ■seealso strcpy() strncat()
  17137.  
  17138.  
  17139. ■function _strncpy()
  17140. ■compat emx
  17141. ■headers
  17142. #include <string.h>
  17143. ■endheaders
  17144.  
  17145. ■param STRING1 STRING2 SIZE
  17146. ■prototype
  17147. char *_strncpy (char *STRING1, const char *STRING2, size_t SIZE);
  17148. ■endprototype
  17149.  
  17150.     Copy the null-terminated string pointed to by STRING2 to the array
  17151.     pointed to by STRING1.  The objects must not overlap.  At most
  17152.     SIZE characters, including the terminating null character, are
  17153.     copied to the array pointed to by STRING1.  A terminating null
  17154.     character is always appended, even if the string pointed to by
  17155.     STRING2 is too long.
  17156.  
  17157. ■returnvalue
  17158.  
  17159.     _strncpy() returns STRING1.
  17160.  
  17161. ■seealso strcpy() strncpy()
  17162.  
  17163.  
  17164. ■function strnicmp()
  17165. ■compat PC
  17166. ■headers
  17167. #include <string.h>
  17168. ■endheaders
  17169.  
  17170. ■param STRING1 STRING2 COUNT
  17171. ■prototype
  17172. int strnicmp (const char *STRING1, const char *STRING2, size_t COUNT);
  17173. ■endprototype
  17174.  
  17175.     Compare the null-terminated strings pointed to by STRING1 and
  17176.     STRING2 ignoring letter case.  At most the first COUNT characters
  17177.     are compared.  If the string pointed to by STRING1 is equal to the
  17178.     string pointed to by STRING2, zero is returned.  If the string
  17179.     pointed to by STRING1 is less than the string pointed to by
  17180.     STRING2 (after conversion to lower case), a negative value is
  17181.     returned.  If the string pointed to by STRING1 is greater than the
  17182.     string pointed to by STRING2 (after conversion to lower case), a
  17183.     positive value is returned.  The strings are not modified.
  17184.  
  17185. ■returnvalue
  17186. ■description
  17187. ■item <0
  17188.    1st string < 2nd string
  17189. ■item =0
  17190.    1st string = 2nd string
  17191. ■item >0
  17192.    1st string > 2nd string
  17193. ■enddescription
  17194.  
  17195. ■seealso memicmp() strcmp() strncmp() tolower()
  17196.  
  17197.  
  17198. ■function strnset()
  17199. ■compat PC
  17200. ■headers
  17201. #include <string.h>
  17202. ■endheaders
  17203.  
  17204. ■param STRING C COUNT
  17205. ■prototype
  17206. char *strnset (char *STRING, int C, size_t COUNT);
  17207. ■endprototype
  17208.  
  17209.     Set, at most, the first COUNT characters of the string pointed to
  17210.     by STRING to the character C.  If the length of the string pointed
  17211.     to by STRING is less than COUNT, strnset() stops at the
  17212.     terminating null character.
  17213.  
  17214. ■returnvalue
  17215.  
  17216.     strnset() returns STRING.
  17217.  
  17218. ■seealso memset() strset()
  17219.  
  17220.  
  17221. ■function strpbrk()
  17222. ■compat C90
  17223. ■headers
  17224. #include <string.h>
  17225. ■endheaders
  17226.  
  17227. ■param STRING1 STRING2
  17228. ■prototype
  17229. char *strpbrk (const char *STRING1, const char *STRING2);
  17230. ■endprototype
  17231.  
  17232.     Return a pointer to the first occurrence in the string pointed to
  17233.     by STRING1 of a character of the string pointed to by STRING2.
  17234.     The terminating null character is not included in the search.  If
  17235.     no character of the string pointed to by STRING2 can be found in
  17236.     the string pointed to by STRING1, NULL is returned.
  17237.  
  17238. ■returnvalue
  17239.  
  17240.     See above.
  17241.  
  17242. ■seealso strchr() strcspn()
  17243.  
  17244.  
  17245. ■function strptime()
  17246. ■compat UNIX
  17247. ■headers
  17248. #include <time.h>
  17249. ■endheaders
  17250.  
  17251. ■param BUFFER FORMAT T
  17252. ■prototype
  17253. char *strptime (const char *BUFFER, const char *FORMAT, struct tm *T);
  17254. ■endprototype
  17255.  
  17256.     Parse a time specification in the input string pointed to by
  17257.     BUFFER according to the format string pointed to by FORMAT,
  17258.     updating the structure pointed to by T.
  17259.  
  17260.     Whitespace (any number of spaces) in the format string matches
  17261.     whitespace (any number of spaces, including zero) in the input
  17262.     string.  All other characters except for ■tt{%} are compared to
  17263.     the input.  Parsing ends (with an error being indicated) when a
  17264.     mismatch is encountered.  ■tt{%%} in the format string matches
  17265.     ■tt{%} in the input string.  A ■tt{%} which is not followed by
  17266.     another ■tt{%} or the end of the string starts a field
  17267.     specification.  The field in the input is interpreted according to
  17268.     the field specification.  For all field types, whitespace is
  17269.     ignored at the start of a field.  Field specifications matching
  17270.     numbers skip leading zeros.  Case is ignored when comparing
  17271.     strings.  The field width is not restricted, that is, as many
  17272.     characters as possible are matched.  The following field
  17273.     specifications are available:
  17274.  
  17275. ■description
  17276. ■item %%
  17277.  
  17278.     percent sign (see above)
  17279.  
  17280. ■item %a
  17281.  
  17282.     locale's abbreviated weekday name, tm_wday
  17283.  
  17284. ■item %A
  17285.  
  17286.     locale's full weekday name, update tm_wday
  17287.  
  17288. ■item %b
  17289.  
  17290.     locale's abbreviated month name, update tm_mon.  %h is a synonym
  17291.     for %b
  17292.  
  17293. ■item %B
  17294.  
  17295.     locale's full month name, update tm_mon
  17296.  
  17297. ■item %c
  17298.  
  17299.     locale's date and time, update tm_year, tm_mon, tm_mday, tm_hour,
  17300.     tm_min, and tm_sec
  17301.  
  17302. ■item %C
  17303.  
  17304.     date and time, equivalent to %x %X, update tm_year, tm_mon,
  17305.     tm_mday, tm_hour, tm_min, and tm_sec
  17306.  
  17307. ■item %d
  17308.  
  17309.     day of month (1-31), update tm_mday
  17310.  
  17311. ■item %D
  17312.  
  17313.     date, this is equivalent to %m/%d/%y, update tm_year, tm_mon, and
  17314.     tm_mday
  17315.  
  17316. ■item %e
  17317.  
  17318.     day of month (1-31), update tm_mday
  17319.  
  17320. ■item %H
  17321.  
  17322.     hour (0-23), update tm_hour (%k is a synonym for %H)
  17323.  
  17324. ■item %I
  17325.  
  17326.     hour (1-12), update tm_hour (%l is a synonym for %I)
  17327.  
  17328. ■item %j
  17329.  
  17330.     day of year (1-366), update tm_yday
  17331.  
  17332. ■item %m
  17333.  
  17334.     month (1-12), update tm_mon
  17335.  
  17336. ■item %M
  17337.  
  17338.     minute (0-59), update tm_min
  17339.  
  17340. ■item %n
  17341.  
  17342.     newline character
  17343.  
  17344. ■item %p
  17345.  
  17346.     locale's equivalent to AM or PM, as appropriate (for use with %I),
  17347.     update tm_hour
  17348.  
  17349. ■item %r
  17350.  
  17351.     time in AM/PM notation, this is equivalent to %I:%M:%S %p, update
  17352.     tm_hour, tm_min, and tm_sec
  17353.  
  17354. ■item %R
  17355.  
  17356.     hour and minutes, equivalent to %H:%M, update tm_hour and tm_min
  17357.  
  17358. ■item %S
  17359.  
  17360.     second (0-59), update tm_sec
  17361.  
  17362. ■item %t
  17363.  
  17364.     TAB character
  17365.  
  17366. ■item %T
  17367.  
  17368.     time, equivalent to %H:%M:%S, update tm_hour, tm_min, tm_sec
  17369.  
  17370. ■item %U
  17371.  
  17372.     week number of the year, the first day of the week is Sunday
  17373.     (0-53), currently ignored
  17374.  
  17375. ■item %w
  17376.  
  17377.     weekday, the first day of the week is Sunday (0-6), update tm_wday
  17378.  
  17379. ■item %W
  17380.  
  17381.     week number of the year, the first day of the week is Monday
  17382.     (0-53), currently ignored
  17383.  
  17384. ■item %x
  17385.  
  17386.     locale's date representation, update tm_year, tm_mon, and tm_mday
  17387.  
  17388. ■item %X
  17389.  
  17390.     locale's time representation, update tm_hour, tm_min, and tm_sec
  17391.  
  17392. ■item %y
  17393.  
  17394.     year without century (0-99, mapping 0-68 to 2000-2068 and 69-99 to
  17395.     1969-1999), update tm_year
  17396.  
  17397. ■item %Y
  17398.  
  17399.     year with century (1970-2106), update tm_year
  17400.  
  17401. ■enddescription
  17402.  
  17403.     If % is followed by a character not listed above, the results are
  17404.     undefined.
  17405.  
  17406. ■restrictions
  17407.  
  17408.     Case is currently not ignored for non-ASCII characters.  %p must
  17409.     currently come after %I in the format string.
  17410.  
  17411.     As behavior of other implementations of strptime() is quite
  17412.     varying, this implementation of strptime() does not behave like
  17413.     most other implementations of strptime().  strptime() is not
  17414.     portable.
  17415.  
  17416. ■returnvalue
  17417.  
  17418.     If successful, strptime() returns a pointer to the character
  17419.     following the last character parsed.  On error, strptime() returns
  17420.     NULL.
  17421.  
  17422. ■seealso setlocale() sscanf() strftime()
  17423.  
  17424.  
  17425. ■function strrchr()
  17426. ■compat C90
  17427. ■headers
  17428. #include <string.h>
  17429. ■endheaders
  17430.  
  17431. ■param STRING C
  17432. ■prototype
  17433. char *strrchr (const char *STRING, int C);
  17434. ■endprototype
  17435.  
  17436.     Return a pointer to the last occurrence of the character C in the
  17437.     null-terminated string pointed to by STRING.  If there is no
  17438.     character C in that string, NULL is returned.  If C is the null
  17439.     character (0), a pointer to the terminating null character of that
  17440.     string is returned.
  17441.  
  17442. ■returnvalue
  17443.  
  17444.     See above.
  17445.  
  17446. ■seealso _memrchr() rindex() strchr()
  17447.  
  17448.  
  17449. ■function strrev()
  17450. ■compat PC
  17451. ■headers
  17452. #include <string.h>
  17453. ■endheaders
  17454.  
  17455. ■param STRING
  17456. ■prototype
  17457. char *strrev (char *STRING);
  17458. ■endprototype
  17459.  
  17460.     Reverse the order of the characters in the string pointed to by
  17461.     STRING.  The terminating null character remains in place.
  17462.  
  17463. ■returnvalue
  17464.  
  17465.     strrev() returns STRING.
  17466.  
  17467.  
  17468. ■function strset()
  17469. ■compat PC
  17470. ■headers
  17471. #include <string.h>
  17472. ■endheaders
  17473.  
  17474. ■param STRING C
  17475. ■prototype
  17476. char *strset (char *STRING, int C);
  17477. ■endprototype
  17478.  
  17479.     Replace all the characters of the string pointed to by STRING with
  17480.     the character C.  The terminating null character is not changed.
  17481.  
  17482. ■returnvalue
  17483.  
  17484.     strset() returns STRING.
  17485.  
  17486. ■seealso memset() strnset()
  17487.  
  17488.  
  17489. ■function strspn()
  17490. ■compat C90
  17491. ■headers
  17492. #include <string.h>
  17493. ■endheaders
  17494.  
  17495. ■param STRING1 STRING2
  17496. ■prototype
  17497. size_t strspn (const char *STRING1, const char *STRING2);
  17498. ■endprototype
  17499.  
  17500.     Return the length of the initial substring of the string pointed
  17501.     to by STRING1 which consists entirely of characters in the string
  17502.     pointed to by STRING2.  That is, the index of the first character
  17503.     in the string pointed to by STRING1 which does not occur in the
  17504.     string pointed to by STRING2 is returned.  If all characters in
  17505.     the string pointed to by STRING1 also occur in the string pointed
  17506.     to by STRING2, the length of the string pointed to by STRING1 is
  17507.     returned.
  17508.  
  17509. ■returnvalue
  17510.  
  17511.     See above.
  17512.  
  17513. ■seealso strcspn() strpbrk()
  17514.  
  17515.  
  17516. ■function strstr()
  17517. ■compat C90
  17518. ■headers
  17519. #include <string.h>
  17520. ■endheaders
  17521.  
  17522. ■param STRING1 STRING2
  17523. ■prototype
  17524. char *strstr (const char *STRING1, const char *STRING2);
  17525. ■endprototype
  17526.  
  17527.     Return a pointer to the first occurrence of the string pointed to
  17528.     by STRING2 in the string pointed to by STRING1.  If the length of
  17529.     the string pointed to by STRING2 is zero, STRING1 is returned.  If
  17530.     the string pointed to by STRING2 is not a substring of the string
  17531.     pointed to by STRING1, NULL is returned.
  17532.  
  17533. ■returnvalue
  17534.  
  17535.     See above.
  17536.  
  17537. ■seealso strchr()
  17538.  
  17539.  
  17540. ■function strtod() strtof() strtold()
  17541. ■compat C90 C9X
  17542. ■headers
  17543. #include <stdlib.h>
  17544. ■endheaders
  17545.  
  17546. ■param STRING END_PTR
  17547. ■prototype
  17548. double strtod (const char *STRING, char **END_PTR);
  17549. float strtof (const char *STRING, char **END_PTR);
  17550. long double strtold (const char *STRING, char **END_PTR);
  17551. ■endprototype
  17552.  
  17553.     strtod() converts a character string to a ■tt{double}.  Leading
  17554.     white space is skipped.  strtod() stops at the first character
  17555.     that cannot be converted.  The string pointed to by STRING is
  17556.     expected to have one of the following forms:
  17557.  
  17558. ■indent
  17559.   ■sy{[<whitespace>] [+|-] [<digits>] [.<digits>] [[d|D|e|E] [+|-] <digits>]} ■break
  17560.   ■sy{[<whitespace>] [+|-] INF} ■break
  17561.   ■sy{[<whitespace>] [+|-] INFINITY} ■break
  17562.   ■sy{[<whitespace>] [+|-] NAN} ■break
  17563.   ■sy{[<whitespace>] [+|-] NAN(...)}
  17564. ■endindent
  17565.  
  17566.     The decimal point character of the current locale is used.  Letter
  17567.     case is ignored for INF, INFINITY, and NAN.  Digits, letters, and
  17568.     the underscore character can occur in the parentheses following
  17569.     `NAN'.
  17570.  
  17571.     If END_PTR is not NULL and the conversion has been performed, a
  17572.     pointer to the first character which cannot be converted is stored
  17573.     to the object pointed to by END_PTR.  If END_PTR is not NULL and
  17574.     no conversion has been performed, STRING is stored to the object
  17575.     pointed to by END_PTR.
  17576.  
  17577.     If no conversion could be performed, strtod() doesn't change errno
  17578.     and returns 0.0 (you can examine the pointer stored to the object
  17579.     pointed to by END_PTR to recognize this case).  On overflow,
  17580.     strtod() sets errno to ERANGE and returns HUGE_VAL or
  17581.     -■tt{HUGE_VAL}, depending on the sign of the number.  On
  17582.     underflow, strtod() sets errno to ERANGE and returns 0.0.
  17583.  
  17584.     The strtold() function proposed for C9X uses the ■tt{long double}
  17585.     format.  On overflow, strtold() returns HUGE_VALL or
  17586.     -■tt{HUGE_VALL}, depending on the sign of the number.
  17587.  
  17588.     The strtof() function proposed for C9X uses the ■tt{float}
  17589.     format.  On overflow, strtof() returns HUGE_VALF or
  17590.     -■tt{HUGE_VALF}, depending on the sign of the number.
  17591.  
  17592. ■returnvalue
  17593.  
  17594.     strtod(), strtof(), and strtold() return the converted value.  If
  17595.     no number is recognized, strtod(), strtof(), and strtold() return
  17596.     0.0.  On overflow, strtod() returns HUGE_VAL or -■tt{HUGE_VAL}.
  17597.     On overflow, strtof() returns HUGE_VALF or -■tt{HUGE_VALF}.  On
  17598.     overflow, strtold() returns HUGE_VALL or -■tt{HUGE_VALL}.  On
  17599.     underflow, strtod(), strtof(), and strtold() return 0.0.
  17600.  
  17601. ■seealso atof() setlocale() sscanf() strtol()
  17602.  
  17603.  
  17604. ■function strtok()
  17605. ■compat C90
  17606. ■headers
  17607. #include <string.h>
  17608. ■endheaders
  17609.  
  17610. ■param STRING1 STRING2
  17611. ■prototype
  17612. char *strtok (char *STRING1, const char *STRING2);
  17613. ■endprototype
  17614.  
  17615.     Return a pointer to the next token in the string pointed to by
  17616.     STRING1.  The characters of the string pointed to by STRING2 are
  17617.     the set of delimiting characters.  Tokens in the string pointed to
  17618.     by STRING1 are separated by one or more characters from the string
  17619.     pointed to by STRING2.
  17620.  
  17621.     The first call to strtok() for STRING1 skips leading delimiters
  17622.     and returns a pointer to the first token.  To get the next token
  17623.     of the string pointed to by STRING1, call strtok() with a NULL
  17624.     argument for STRING1.  The set of delimiters pointed to by STRING2
  17625.     as well as the pointer STRING2 may be different on subsequent calls.
  17626.  
  17627.     strtok() modifies the string pointed to by STRING1 by inserting
  17628.     null characters for terminating tokens.  Thus, the pointer
  17629.     returned by strtok() points to a null-terminated token.
  17630.  
  17631.     If there are no more tokens, NULL is returned.
  17632.  
  17633. ■returnvalue
  17634.  
  17635.     See above.
  17636.  
  17637. ■seealso strpbrk()
  17638.  
  17639.  
  17640. ■function strtol()
  17641. ■compat C90
  17642. ■headers
  17643. #include <stdlib.h>
  17644. ■endheaders
  17645.  
  17646. ■param STRING END_PTR RADIX
  17647. ■prototype
  17648. long strtol (const char *STRING, char **END_PTR, int RADIX);
  17649. ■endprototype
  17650.  
  17651.     Convert a character string to a signed long integer.  The string
  17652.     pointed to by STRING should have the following format:
  17653.  
  17654. ■indent
  17655.   ■sy{[<whitespace>] [+|-] [|0|0x|0X] <digits>}
  17656. ■endindent
  17657.  
  17658.     Leading white space (as defined by isspace()) is skipped.  RADIX
  17659.     is the number base used for conversion.  It must either be between
  17660.     2 and 36 or be zero.
  17661.  
  17662.     If RADIX is 0, the number base is derived from the format of the
  17663.     number: If the number starts with ■tt{0x}, base 16 is used.  If
  17664.     the number starts with ■tt{0} (not followed by ■tt{x}), base 8 is
  17665.     used.  If the number does not start with ■tt{0}, base 10 is used.
  17666.  
  17667.     strtol() stops at the first character that cannot be converted.
  17668.     If END_PTR is not NULL and the conversion has been performed, a
  17669.     pointer to the first character which cannot be converted is stored
  17670.     to the object pointed to by END_PTR.  If END_PTR is not NULL and
  17671.     no conversion has been performed, STRING is stored to the object
  17672.     pointed to by END_PTR.
  17673.  
  17674.     strtol() doesn't change errno and returns 0 if no conversion could
  17675.     be performed (you can examine the pointer stored to the object
  17676.     pointed to by END_PTR to recognize this case).  On overflow,
  17677.     strtol() sets errno to ERANGE and returns LONG_MIN or LONG_MAX
  17678.     (depending on the sign character).  If RADIX is out of range,
  17679.     strtol() sets errno to EDOM and returns 0.
  17680.  
  17681. ■returnvalue
  17682.  
  17683.     strtol() returns the converted value.  If no number is recognized
  17684.     or if RADIX is invalid, strtol() returns 0.  On overflow, strtol()
  17685.     returns LONG_MIN or LONG_MAX.
  17686.  
  17687. ■seealso atol() isspace() _ltoa() _strtoll() strtoul() sscanf()
  17688.  
  17689. ■samplecode
  17690. int read_long (char **ptr, long *dst)
  17691. {
  17692.   char *p;
  17693.   long n;
  17694.  
  17695.   errno = 0;
  17696.   n = strtol (*ptr, &p, 0);
  17697.   if (errno != 0 || p == *ptr)
  17698.     return 0;                   /* Failure */
  17699.   *dst = n; *ptr = p;
  17700.   return 1;                     /* Success */
  17701. }
  17702. ■endsamplecode
  17703.  
  17704.  
  17705. ■function _strtoll()
  17706. ■compat emx
  17707. ■headers
  17708. #include <stdlib.h>
  17709. ■endheaders
  17710.  
  17711. ■param STRING END_PTR RADIX
  17712. ■prototype
  17713. long long _strtoll (const char *STRING, char **END_PTR, int RADIX);
  17714. ■endprototype
  17715.  
  17716.     Convert a character string to a signed long long integer.  The
  17717.     string pointed to by STRING should have the following format:
  17718.  
  17719. ■indent
  17720.   ■sy{[<whitespace>] [+|-] [|0|0x|0X] <digits>}
  17721. ■endindent
  17722.  
  17723.     Leading white space (as defined by isspace()) is skipped.  RADIX
  17724.     is the number base used for conversion.  It must either be between
  17725.     2 and 36 or be zero.
  17726.  
  17727.     If RADIX is 0, the number base is derived from the format of the
  17728.     number: If the number starts with ■tt{0x}, base 16 is used.  If
  17729.     the number starts with ■tt{0} (not followed by ■tt{x}), base 8 is
  17730.     used.  If the number does not start with ■tt{0}, base 10 is used.
  17731.  
  17732.     _strtoll() stops at the first character that cannot be converted.
  17733.     If END_PTR is not NULL and the conversion has been performed, a
  17734.     pointer to the first character which cannot be converted is stored
  17735.     to the object pointed to by END_PTR.  If END_PTR is not NULL and
  17736.     no conversion has been performed, STRING is stored to the object
  17737.     pointed to by END_PTR.
  17738.  
  17739.     _strtoll() doesn't change errno and returns 0 if no conversion
  17740.     could be performed (you can examine the pointer stored to the
  17741.     object pointed to by END_PTR to recognize this case).  On
  17742.     overflow, _strtoll() sets errno to ERANGE and returns
  17743.     LONG_LONG_MIN or LONG_LONG_MAX (depending on the sign character).
  17744.     If RADIX is out of range, _strtoll() sets errno to EDOM and
  17745.     returns 0.
  17746.  
  17747. ■returnvalue
  17748.  
  17749.     _strtoll() returns the converted value.  If no number is
  17750.     recognized or if RADIX is invalid, strtol() returns 0.  On
  17751.     overflow, _strtoll() returns LONG_LONG_MIN or LONG_LONG_MAX.
  17752.  
  17753. ■seealso _atoll() isspace() _lltoa() strtol() _strtoull() sscanf()
  17754.  
  17755.  
  17756. ■function strtoul()
  17757. ■compat C90
  17758. ■headers
  17759. #include <stdlib.h>
  17760. ■endheaders
  17761.  
  17762. ■param STRING END_PTR RADIX
  17763. ■prototype
  17764. unsigned long strtoul (const char *STRING, char **END_PTR, int RADIX);
  17765. ■endprototype
  17766.  
  17767.     Convert a character string to an unsigned long integer.  The
  17768.     string pointed to by STRING should have the following format:
  17769.  
  17770. ■indent
  17771.   ■sy{[<whitespace>] [+|-] [|0|0x|0X] <digits>}
  17772. ■endindent
  17773.  
  17774.     Leading white space (as defined by isspace()) is skipped.  RADIX
  17775.     is the number base used for conversion.  It must either be between
  17776.     2 and 36 or be zero.
  17777.  
  17778.     If RADIX is 0, the number base is derived from the format of the
  17779.     number: If the number starts with ■tt{0x}, base 16 is used.  If
  17780.     the number starts with ■tt{0} (not followed by ■tt{x}), base 8 is
  17781.     used.  If the number does not start with ■tt{0}, base 10 is used.
  17782.  
  17783.     strtoul() stops at the first character that cannot be converted.
  17784.     If END_PTR is not NULL and the conversion has been performed, a
  17785.     pointer to the first character which cannot be converted is stored
  17786.     to the object pointed to by END_PTR.  If END_PTR is not NULL and
  17787.     no conversion has been performed, STRING is stored to the object
  17788.     pointed to by END_PTR.
  17789.  
  17790.     strtoul() returns 0 if no conversion could be performed (errno will
  17791.     not be changed).  On overflow, strtoul() sets errno to ERANGE and
  17792.     returns ULONG_MAX.  If RADIX is out of range, strtoul() sets errno
  17793.     to EDOM and returns 0.
  17794.  
  17795.  
  17796. ■returnvalue
  17797.  
  17798.     strtoul() returns the converted value.  If no number is recognized
  17799.     or if RADIX is invalid, strtoul() returns 0.  On overflow, strtoul()
  17800.     returns ULONG_MAX.
  17801.  
  17802. ■seealso isspace() strtol() _strtoull() sscanf() _ultoa()
  17803.  
  17804.  
  17805. ■function _strtoull()
  17806. ■compat emx
  17807. ■headers
  17808. #include <stdlib.h>
  17809. ■endheaders
  17810.  
  17811. ■param STRING END_PTR RADIX
  17812. ■prototype
  17813. unsigned long long _strtoull (const char *STRING, char **END_PTR, int RADIX);
  17814. ■endprototype
  17815.  
  17816.     Convert a character string to an unsigned long long integer.  The
  17817.     string pointed to by STRING should have the following format:
  17818.  
  17819. ■indent
  17820.   ■sy{[<whitespace>] [+|-] [|0|0x|0X] <digits>}
  17821. ■endindent
  17822.  
  17823.     Leading white space (as defined by isspace()) is skipped.  RADIX
  17824.     is the number base used for conversion.  It must either be between
  17825.     2 and 36 or be zero.
  17826.  
  17827.     If RADIX is 0, the number base is derived from the format of the
  17828.     number: If the number starts with ■tt{0x}, base 16 is used.  If
  17829.     the number starts with ■tt{0} (not followed by ■tt{x}), base 8 is
  17830.     used.  If the number does not start with ■tt{0}, base 10 is used.
  17831.  
  17832.     _strtoull() stops at the first character that cannot be converted.
  17833.     If END_PTR is not NULL and the conversion has been performed, a
  17834.     pointer to the first character which cannot be converted is stored
  17835.     to the object pointed to by END_PTR.  If END_PTR is not NULL and
  17836.     no conversion has been performed, STRING is stored to the object
  17837.     pointed to by END_PTR.
  17838.  
  17839.     _strtoull() returns 0 if no conversion could be performed (errno
  17840.     will not be changed).  On overflow, _strtoull() sets errno to
  17841.     ERANGE and returns ULONG_LONG_MAX.  If RADIX is out of range,
  17842.     _strtoull() sets errno to EDOM and returns 0.
  17843.  
  17844. ■returnvalue
  17845.  
  17846.     _strtoull() returns the converted value.  If no number is recognized
  17847.     or if RADIX is invalid, _strtoull() returns 0.  On overflow, _strtoull()
  17848.     returns ULONG_LONG_MAX.
  17849.  
  17850. ■seealso isspace() _strtoll() strtoul() sscanf() _ulltoa()
  17851.  
  17852.  
  17853. ■function strupr()
  17854. ■compat PC
  17855. ■headers
  17856. #include <string.h>
  17857. ■endheaders
  17858.  
  17859. ■param STRING
  17860. ■prototype
  17861. char *strupr (char *STRING);
  17862. ■endprototype
  17863.  
  17864.     Convert the string pointed to by STRING to upper case.  The
  17865.     characters ■tt{'a'} through ■tt{'z'} are mapped to the characters
  17866.     ■tt{'A'} through ■tt{'Z'}.  All other characters are not changed.
  17867.  
  17868. ■returnvalue
  17869.  
  17870.     strupr() returns STRING.
  17871.  
  17872. ■seealso strlwr()
  17873.  
  17874.  
  17875. ■function strxfrm()
  17876. ■compat C90
  17877. ■headers
  17878. #include <string.h>
  17879. ■endheaders
  17880.  
  17881. ■param STRING1 STRING2 N
  17882. ■prototype
  17883. size_t strxfrm (char *STRING1, const char *STRING2, size_t N);
  17884. ■endprototype
  17885.  
  17886.     Transform the string pointed to by STRING2 according to the
  17887.     LC_COLLATE category of the current locale and copy the result to
  17888.     the array pointed to by STRING1.  After applying strxfrm(), you
  17889.     can use strcmp() for comparing the strings; applying strcmp() to
  17890.     strings transformed by strxfrm() is equivalent to calling
  17891.     strcoll() on the original strings.  At most N characters
  17892.     (including the terminating null character) are stored to the array
  17893.     pointed to by STRING1.  STRING1 can be NULL if N is zero.
  17894.  
  17895. ■returnvalue
  17896.  
  17897.     strxfrm() returns the number of characters in the transformed
  17898.     string (excluding the terminating null character), even if that
  17899.     number exceeds N.  If the return value is equal to or greater than
  17900.     N, the contents of the string pointed to by STRING1 are
  17901.     indeterminate.
  17902.  
  17903. ■restrictions
  17904.  
  17905.     Currently, locale is ignored: strxfrm() copies the characters
  17906.     without modifications.
  17907.  
  17908. ■seealso setlocale() strcoll()
  17909.  
  17910. ■samplecode
  17911. /* Transform a string, allocating memory with malloc(). */
  17912. char *xfrm (const char *s)
  17913. {
  17914.   size_t len = strxfrm (NULL, s, 0);
  17915.   char *t = malloc (len + 1);
  17916.   if (t != NULL)
  17917.     strxfrm (t, s, len + 1);
  17918.   return t;
  17919. }
  17920. ■endsamplecode
  17921.  
  17922.  
  17923. ■function swab()
  17924. ■compat UNIX
  17925. ■headers
  17926. #include <stdlib.h>
  17927. ■endheaders
  17928.  
  17929. ■param SRC DST N
  17930. ■prototype
  17931. void swab (const void *SRC, void *DST, size_t N);
  17932. ■endprototype
  17933.  
  17934.     Copy N bytes from SRC to DST, swapping each pair of adjacent
  17935.     bytes.  N must be even.
  17936.  
  17937.  
  17938. ■function _swchar()
  17939. ■compat emx
  17940. ■headers
  17941. #include <stdlib.h>
  17942. ■endheaders
  17943.  
  17944. ■prototype
  17945. char _swchar (void);
  17946. ■endprototype
  17947.  
  17948.     Retrieve the current switch character.  If the switch character
  17949.     has been changed to ■tt{'-'}, _swchar() returns ■tt{'-'}.
  17950.     Otherwise, _swchar() returns 0.  In this case, you should use the
  17951.     standard switch character ■tt{'/'}.
  17952.  
  17953. ■returnvalue
  17954.  
  17955.     See above.
  17956.  
  17957. ■seealso getopt()
  17958.  
  17959.  
  17960. ■function sysconf()
  17961. ■compat POSIX.1
  17962. ■headers
  17963. #include <unistd.h>
  17964. ■endheaders
  17965.  
  17966. ■param NAME
  17967. ■prototype
  17968. long sysconf (int NAME);
  17969. ■endprototype
  17970.  
  17971.     Return the current value of the configurable system limit or
  17972.     option NAME.  NAME is one of the following constants:
  17973.  
  17974. ■description
  17975. ■item _SC_ARG_MAX
  17976.  
  17977.     corresponds to ARG_MAX (length of arguments and environment for
  17978.     ■tt{exec*()}, in bytes)
  17979.  
  17980. ■item _SC_CHILD_MAX
  17981.  
  17982.     corresponds to CHILD_MAX (number of simultaneous processes per
  17983.     real user ID)
  17984.  
  17985. ■item _SC_CLK_TCK
  17986.  
  17987.     number of clock ticks per second, for times()
  17988.  
  17989. ■item _SC_NGROUPS_MAX
  17990.  
  17991.     corresponds to NGROUPS_MAX (maximum number of simultaneous
  17992.     supplementary group IDs per process)
  17993.  
  17994. ■item _SC_OPEN_MAX
  17995.  
  17996.     corresponds to OPEN_MAX (number of files that one process can have
  17997.     open at one time)
  17998.  
  17999. ■item _SC_STREAM_MAX
  18000.  
  18001.     corresponds to STREAM_MAX (number of streams that one process can
  18002.     have open at one time)
  18003.  
  18004. ■item _SC_TZNAME_MAX
  18005.  
  18006.     corresponds to TZNAME_MAX (number of bytes supported for the name
  18007.     of a time zone)
  18008.  
  18009. ■item _SC_JOB_CONTROL
  18010.  
  18011.     corresponds to _POSIX_JOB_CONTROL (defined if the implementation
  18012.     supports job control -- emx doesn't)
  18013.  
  18014. ■item _SC_SAVED_IDS
  18015.  
  18016.     corresponds to _POSIX_SAVED_IDS (defined if each process has a
  18017.     saved set-user-ID and a saved set-group-ID -- not true for emx)
  18018.  
  18019. ■item _SC_VERSION
  18020.  
  18021.     corresponds to _POSIX_VERSION (the integer 199009L)
  18022.  
  18023. ■enddescription
  18024.  
  18025.     See POSIX.1 for more details.
  18026.  
  18027. ■returnvalue
  18028.  
  18029.     If NAME is invalid, sysconf() sets errno to EINVAL and returns -1.
  18030.     If NAME is associated with functionality that is not supported by
  18031.     the system, sysconf() returns -1 and does not change errno.
  18032.     Otherwise, sysconf() returns the current value of the variable.
  18033.  
  18034. ■restrictions
  18035.  
  18036.     sysconf() currently returns just the POSIX.1 minimum values.
  18037.  
  18038. ■seealso fpathconf() pathconf()
  18039.  
  18040.  
  18041. ■function _syserrno()
  18042. ■compat emx *
  18043. ■headers
  18044. #include <stdlib.h>
  18045. ■endheaders
  18046.  
  18047. ■prototype
  18048. int _syserrno (void);
  18049. ■endprototype
  18050.  
  18051.     Return the OS/2 or DOS error code for the last system call of the
  18052.     current thread.  If there was no error, 0 is returned.  If the
  18053.     last system call hasn't called an OS/2 or DOS function, 0 is
  18054.     returned.
  18055.  
  18056. ■returnvalue
  18057.  
  18058.     See above.
  18059.  
  18060. ■restrictions
  18061.  
  18062.     _syserrno() is not implemented under DOS.  _syserrno() is not
  18063.     supported with the system call library sys.lib (■hpt{-Zsys}).
  18064.  
  18065. ■seealso errno _setsyserrno()
  18066.  
  18067. ■function system()
  18068. ■compat C90
  18069. ■headers
  18070. #include <process.h>
  18071. ■endheaders
  18072.  
  18073. ■param NAME
  18074. ■prototype
  18075. int system (const char *NAME);
  18076. ■endprototype
  18077.  
  18078.     Execute a command by passing it to the command interpreter.  NAME
  18079.     is a pointer to a string containing the command name.  system()
  18080.     uses the COMSPEC environment variable for locating cmd.exe or
  18081.     command.com, respectively.  The COMSPEC environment variable can
  18082.     be overriden by setting the EMXSHELL environment variable.  The
  18083.     PATH environment variable is not used for locating cmd.exe.  If
  18084.     the argument is ■tt{""}, an interactive shell will be started.  If
  18085.     the argument is NULL, system() only checks whether cmd.exe or
  18086.     command.com, respectively, can be found.
  18087.  
  18088.     As command.com is used under DOS, the command line is restricted
  18089.     to about 123 characters.  If you don't need a command shell, use
  18090.     spawn*() instead of system().  It's a bad idea to run emx programs
  18091.     using system() -- not tested.  You must use the -p emx option when
  18092.     using system() under DOS, see `■hpt{Using emx options}'.
  18093.  
  18094.     The system() function passes the ■tt{/c} option to the command
  18095.     processor if COMSPEC (or EMXSHELL) points to cmd.exe,
  18096.     ■tt{4os2.exe}, command.com or ■tt{4dos.com}.  Otherwise,
  18097.     system() assumes that a Unix-like shell is to be used and passes
  18098.     the ■tt{-c} option.
  18099.  
  18100. ■returnvalue
  18101.  
  18102.     If system() fails, errno is set and -1 is returned.  If the
  18103.     argument is NULL and the command processor can be found, 0 is
  18104.     returned.  In all other cases, the return code of the command
  18105.     processor is returned.  The return code of the program run by the
  18106.     command processor is returned by cmd.exe but not by command.com.
  18107.     command.com always returns 0.
  18108.  
  18109. ■seealso popen() spawn*()
  18110.  
  18111.  
  18112. ■function _tcalloc()
  18113. ■compat OS/2
  18114. ■headers
  18115. #include <stdlib.h>
  18116. ■endheaders
  18117.  
  18118. ■param ELEMENTS SIZE
  18119. ■prototype
  18120. void *_tcalloc (size_t ELEMENTS, size_t SIZE);
  18121. ■endprototype
  18122.  
  18123.     Allocate a block of memory big enough for holding ELEMENTS
  18124.     elements of SIZE bytes each.  The block will not cross a 64 KByte
  18125.     boundary unless SIZE is greater than 65536.  If SIZE is greater
  18126.     than 65536, the block will be aligned on a 64 KByte boundary.
  18127.     _tcalloc() fills the block with zeros.  If there is an error,
  18128.     _tcalloc() returns NULL.
  18129.  
  18130. ■returnvalue
  18131.  
  18132.     _tcalloc() returns a pointer to a newly allocated block of
  18133.     memory.  On error, _tcalloc() returns NULL.
  18134.  
  18135. ■restrictions
  18136.  
  18137.     If you replace the emx malloc() implementation with a malloc()
  18138.     implementation (GNU malloc, for instance) that has not _tmalloc()
  18139.     etc. built in, you have to link with the ■tt{tmalloc} library
  18140.     (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
  18141.     etc.
  18142.  
  18143. ■seealso calloc() _tfree() _tmalloc() _utcalloc() _utdefault()
  18144.  
  18145.  
  18146. ■function tcdrain()
  18147. ■compat POSIX.1 *
  18148. ■headers
  18149. #include <termios.h>
  18150. ■endheaders
  18151.  
  18152. ■param HANDLE
  18153. ■prototype
  18154. int tcdrain (int HANDLE);
  18155. ■endprototype
  18156.  
  18157.     tcdrain() waits until all output written to the terminal
  18158.     associated with the file descriptor HANDLE has been transmitted.
  18159.  
  18160. ■returnvalue
  18161.  
  18162.     tcdrain() returns 0 if successful.  Otherwise, tcdrain()
  18163.     sets errno and returns -1.
  18164.  
  18165. ■errors
  18166. ■description
  18167. ■item EBADF
  18168.   HANDLE is not a valid open file descriptor.
  18169. ■item ENOTTY
  18170.   HANDLE is not associated with a terminal.
  18171. ■enddescription
  18172.  
  18173. ■implementation
  18174.  
  18175.     tcdrain() currently does nothing and always succeeds.
  18176.  
  18177. ■restrictions
  18178.  
  18179.     tcdrain() is not available with the system call library sys.lib
  18180.     (■hpt{-Zsys}).
  18181.  
  18182. ■seealso tcflow() tcflush() tcsendbreak() tcsetattr()
  18183.  
  18184.  
  18185. ■function tcflow()
  18186. ■compat POSIX.1 *
  18187. ■headers
  18188. #include <termios.h>
  18189. ■endheaders
  18190.  
  18191. ■param HANDLE ACTION
  18192. ■prototype
  18193. int tcflow (int HANDLE, int ACTION);
  18194. ■endprototype
  18195.  
  18196.     tcflow() suspends or resumes transmission or reception of data on
  18197.     the terminal associated with the file descriptor HANDLE, depending
  18198.     on ACTION:
  18199.  
  18200. ■description
  18201. ■item TCIOFF
  18202.   Transmit a VSTOP character to suspend input.
  18203. ■item TCION
  18204.   Transmit a VSTART character to resume suspended input.
  18205. ■item TCOOFF
  18206.   Suspend output.
  18207. ■item TCOON
  18208.   Resume suspended output.
  18209. ■enddescription
  18210.  
  18211.     See `■hpt{General terminal interface}' for details.
  18212.  
  18213. ■returnvalue
  18214.  
  18215.     tcflow() returns 0 if successful.  Otherwise, tcflow()
  18216.     sets errno and returns -1.
  18217.  
  18218. ■errors
  18219. ■description
  18220. ■item EBADF
  18221.   HANDLE is not a valid open file descriptor.
  18222. ■item ENOTTY
  18223.   HANDLE is not associated with a terminal.
  18224. ■enddescription
  18225.  
  18226. ■implementation
  18227.  
  18228.     tcflow() currently does nothing and always succeeds.
  18229.  
  18230. ■restrictions
  18231.  
  18232.     tcflow() is not available with the system call library sys.lib
  18233.     (■hpt{-Zsys}).
  18234.  
  18235. ■seealso tcdrain() tcflush() tcsendbreak() tcsetattr()
  18236.  
  18237.  
  18238. ■function tcflush()
  18239. ■compat POSIX.1 *
  18240. ■headers
  18241. #include <termios.h>
  18242. ■endheaders
  18243.  
  18244. ■param HANDLE QUEUE
  18245. ■prototype
  18246. int tcflush (int HANDLE, int QUEUE);
  18247. ■endprototype
  18248.  
  18249.     tcflush() flushes the input and/or output queues of the terminal
  18250.     associated with the file descriptor HANDLE, depending on QUEUE:
  18251.  
  18252. ■description
  18253. ■item TCIFLUSH
  18254.   Flush the input queue.
  18255. ■item TCOFLUSH
  18256.   Flush the output queue.
  18257. ■item TCIOFLUSH
  18258.   Flush the both the input and output queues.
  18259. ■enddescription
  18260.  
  18261. ■returnvalue
  18262.  
  18263.     tcflush() returns 0 if successful.  Otherwise, tcflush()
  18264.     sets errno and returns -1.
  18265.  
  18266. ■errors
  18267. ■description
  18268. ■item EBADF
  18269.   HANDLE is not a valid open file descriptor.
  18270. ■item EINVAL
  18271.   QUEUE is not valid.
  18272. ■item ENOTTY
  18273.   HANDLE is not associated with a terminal.
  18274. ■enddescription
  18275.  
  18276. ■implementation
  18277.  
  18278.     tcflush() currently works on the keyboard, only.
  18279.  
  18280. ■restrictions
  18281.  
  18282.     tcflush() is not available with the system call library sys.lib
  18283.     (■hpt{-Zsys}).
  18284.  
  18285.     Under DOS, the value of the HANDLE argument must be 0.
  18286.  
  18287. ■seealso tcdrain() tcflow() tcsendbreak() tcsetattr()
  18288.  
  18289.  
  18290. ■function tcgetattr()
  18291. ■compat POSIX.1 *
  18292. ■headers
  18293. #include <termios.h>
  18294. ■endheaders
  18295.  
  18296. ■param HANDLE PTERMIOS
  18297. ■prototype
  18298. int tcgetattr (int HANDLE, struct termios *PTERMIOS);
  18299. ■endprototype
  18300.  
  18301.     Store the parameters of the terminal associated with the file
  18302.     descriptor HANDLE to the object pointed to by PTERMIOS.
  18303.  
  18304.     See `■hpt{General terminal interface}' for details.
  18305.  
  18306. ■returnvalue
  18307.  
  18308.     tcgetattr() returns 0 if successful.  Otherwise, tcgetattr() sets
  18309.     errno and returns -1.
  18310.  
  18311. ■errors
  18312. ■description
  18313. ■item EBADF
  18314.   HANDLE is not a valid open file descriptor.
  18315. ■item ENOTTY
  18316.   HANDLE is not associated with a terminal.
  18317. ■enddescription
  18318.  
  18319. ■implementation
  18320.  
  18321.     Currently, errno is set to ENOTTY instead of EBADF if HANDLE is
  18322.     out of range.
  18323.  
  18324. ■restrictions
  18325.  
  18326.     tcgetattr() is not available with the system call library sys.lib
  18327.     (■hpt{-Zsys}).
  18328.  
  18329.     Under DOS, the value of the HANDLE argument must be 0.
  18330.  
  18331. ■seealso cfgetispeed() cfgetospeed() tcsetattr()
  18332.  
  18333.  
  18334. ■function tcsendbreak()
  18335. ■compat POSIX.1 *
  18336. ■headers
  18337. #include <termios.h>
  18338. ■endheaders
  18339.  
  18340. ■param HANDLE DURATION
  18341. ■prototype
  18342. int tcsendbreak (int HANDLE, int DURATION);
  18343. ■endprototype
  18344.  
  18345.     tcsendbreak() sends a `break' on an asynchronous line.  The
  18346.     duration of the `break' is controlled by DURATION in a
  18347.     not-yet-specified way.  If applied to a handle which is not
  18348.     associated with an asynchronous line, tcsendbreak() does nothing.
  18349.  
  18350. ■returnvalue
  18351.  
  18352.     tcsendbreak() returns 0 if successful.  Otherwise, tcsendbreak()
  18353.     sets errno and returns -1.
  18354.  
  18355. ■errors
  18356. ■description
  18357. ■item EBADF
  18358.   HANDLE is not a valid open file descriptor.
  18359. ■item ENOTTY
  18360.   HANDLE is not associated with a terminal.
  18361. ■enddescription
  18362.  
  18363. ■implementation
  18364.  
  18365.     tcsendbreak() currently does nothing and always succeeds.
  18366.  
  18367. ■restrictions
  18368.  
  18369.     tcsendbreak() is not available with the system call library
  18370.     sys.lib (■hpt{-Zsys}).
  18371.  
  18372. ■seealso tcdrain() tcflow() tcflush() tcsetattr()
  18373.  
  18374.  
  18375. ■function tcsetattr()
  18376. ■compat POSIX.1 *
  18377. ■headers
  18378. #include <termios.h>
  18379. ■endheaders
  18380.  
  18381. ■param HANDLE OPTIONS PTERMIOS
  18382. ■prototype
  18383. int tcsetattr (int HANDLE, int OPTIONS, const struct termios *PTERMIOS);
  18384. ■endprototype
  18385.  
  18386.     Set the parameters of the terminal associated with the file
  18387.     descriptor HANDLE from the object pointed to by PTERMIOS.  OPTIONS
  18388.     must be one of the following symbols:
  18389.  
  18390. ■description
  18391. ■item TCSANOW
  18392.   The change is performed immediately.
  18393. ■item TCSADRAIN
  18394.   The change is performed after all output has been transmitted.
  18395. ■item TCSAFLUSH
  18396.   The change is performed after all output has been transmitted.
  18397.   The input queue is flushed before performing the change.
  18398. ■enddescription
  18399.  
  18400.     See `■hpt{General terminal interface}' for details.
  18401.  
  18402. ■returnvalue
  18403.  
  18404.     tcsetattr() returns 0 if successful.  Otherwise, tcsetattr() sets
  18405.     errno and returns -1.
  18406.  
  18407. ■errors
  18408. ■description
  18409. ■item EBADF
  18410.   HANDLE is not a valid open file descriptor.
  18411. ■item EINVAL
  18412.   OPTIONS is not valid or an attempt was made to change an attribute
  18413.   to an unsupported value.
  18414. ■item ENOTTY
  18415.   HANDLE is not associated with a terminal.
  18416. ■enddescription
  18417.  
  18418. ■implementation
  18419.  
  18420.     Currently, errno is set to ENOTTY instead of EBADF if HANDLE is
  18421.     out of range.
  18422.  
  18423. ■restrictions
  18424.  
  18425.     tcsetattr() is not available with the system call library sys.lib
  18426.     (■hpt{-Zsys}).
  18427.  
  18428.     Under DOS, the value of the HANDLE argument must be 0.
  18429.  
  18430. ■seealso cfsetispeed() cfsetospeed() tcdrain() tcflush() tcgetattr()
  18431.  
  18432.  
  18433. ■function tell()
  18434. ■compat PC
  18435. ■headers
  18436. #include <io.h>
  18437. ■endheaders
  18438.  
  18439. ■param HANDLE
  18440. ■prototype
  18441. long tell (int HANDLE);
  18442. ■endprototype
  18443.  
  18444.     tell() returns the current position of the file pointer of HANDLE.
  18445.     If there is an error, tell() returns -1.
  18446.  
  18447. ■returnvalue
  18448.  
  18449.     See above.
  18450.  
  18451. ■seealso lseek()
  18452.  
  18453.  
  18454. ■function tempnam()
  18455. ■compat UNIX
  18456. ■headers
  18457. #include <stdio.h>
  18458. ■endheaders
  18459.  
  18460. ■param DIR PREFIX
  18461. ■prototype
  18462. char *tempnam (const char *DIR, const char *PREFIX);
  18463. ■endprototype
  18464.  
  18465.     Generate a file name suitable for a temporary file without
  18466.     overwriting an existing file.  tempnam() returns a pointer to a
  18467.     string allocated by malloc().  If the TMP environment variable is
  18468.     set and the directory specified by TMP exists, that directory is
  18469.     used.  Otherwise, the DIR argument is used.  If DIR is NULL or the
  18470.     directory whose name is in the string pointed to by DIR does not
  18471.     exist, P_tmpdir as defined in <stdio.h> is used.  If even this
  18472.     fails, NULL is returned.  The name of the file will start with the
  18473.     string pointed to by PREFIX.  The string pointed to by PREFIX must
  18474.     not be longer than 5 characters.
  18475.  
  18476. ■returnvalue
  18477.  
  18478.     See above.
  18479.  
  18480. ■seealso tmpnam()
  18481.  
  18482.  
  18483. ■function _tfree()
  18484. ■compat OS/2
  18485. ■headers
  18486. #include <stdlib.h>
  18487. ■endheaders
  18488.  
  18489. ■param MEM
  18490. ■prototype
  18491. void _tfree (void *MEM);
  18492. ■endprototype
  18493.  
  18494.     Deallocate a block of memory allocated by _tmalloc(), _tcalloc()
  18495.     or _trealloc().  MEM points to the block of memory.  MEM must have
  18496.     been returned by _tmalloc(), _tcalloc() or _trealloc().  Do not
  18497.     use MEM after calling _tfree().  If MEM is NULL, _tfree() does
  18498.     nothing.
  18499.  
  18500. ■restrictions
  18501.  
  18502.     If you replace the emx malloc() implementation with a malloc()
  18503.     implementation (GNU malloc), for instance) that has not _tmalloc()
  18504.     etc. built in, you have to link with the ■tt{tmalloc} library
  18505.     (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
  18506.     etc.
  18507.  
  18508. ■seealso free() _tcalloc() _tmalloc() _trealloc()
  18509.  
  18510.  
  18511. ■function _theapmin()
  18512. ■compat VAC++
  18513. ■headers
  18514. #include <malloc.h>
  18515. ■endheaders
  18516.  
  18517. ■prototype
  18518. int _theapmin (void);
  18519. ■endprototype
  18520.  
  18521.     The _theapmin() function returns unused memory of the tiled
  18522.     default heap to the operating system.  The heap is never made
  18523.     smaller than its initial size.  Calling _theapmin() is equivalent
  18524.     to calling _uheapmin() for the tiled default heap.
  18525.  
  18526. ■returnvalue
  18527. ■description
  18528. ■item 0
  18529.     success
  18530. ■item -1
  18531.     error
  18532. ■enddescription
  18533.  
  18534. ■seealso brk() _heapchk() sbrk() _heapmin() _uheapmin() _utdefault()
  18535.  
  18536.  
  18537. ■function _threadstore()
  18538. ■compat OS/2
  18539. ■headers
  18540. #include <stdlib.h>
  18541. ■endheaders
  18542.  
  18543. ■param PTR
  18544. ■prototype
  18545. void **_threadstore (void);
  18546. ■endprototype
  18547.  
  18548.     The _threadstore() function returns the address of a pointer to
  18549.     thread-specific user-defined data.  Initially, that pointer is
  18550.     NULL.  To create thread-specific data, allocate a memory object
  18551.     (using malloc(), for instance) and assign the address of that
  18552.     memory object to the location returned by _threadstore():
  18553.  
  18554. ■example
  18555. p = malloc (sizeof (struct user_data));
  18556. *_threadstore() = p;
  18557. ■endexample
  18558.  
  18559.     To access a thread-specific variable, use _threadstore() to get
  18560.     the pointer to the memory object:
  18561.  
  18562. ■example
  18563. x = (*_threadstore)->myvar;
  18564. ■endexample
  18565.  
  18566. ■returnvalue
  18567.  
  18568.     _threadstore() returns the address of a pointer located in the
  18569.     thread-specific data block of the emx C library.
  18570.  
  18571. ■restrictions
  18572.  
  18573.     _threadstore() is available only in the multithread libraries
  18574.     (-Zmt, -Zmts, or -Zmtd).
  18575.  
  18576. ■seealso _beginthread() _gettid() _threadid
  18577.  
  18578.  
  18579. ■function time()
  18580. ■compat C90
  18581. ■headers
  18582. #include <time.h>
  18583. ■endheaders
  18584.  
  18585. ■param PTR
  18586. ■prototype
  18587. time_t time (time_t *PTR);
  18588. ■endprototype
  18589.  
  18590.     Return the number of seconds elapsed since 00:00:00 1-Jan-1970
  18591.     Coordinated Universal Time (UTC, GMT).  The system time is
  18592.     converted according to the local timezone.  If PTR is not NULL,
  18593.     the result is also stored to the variable pointed to by PTR.
  18594.  
  18595. ■returnvalue
  18596.  
  18597.     See above.
  18598.  
  18599. ■seealso ftime() gettimeofday() gmtime() localtime() settimeofday()
  18600.  
  18601.  
  18602. ■function times()
  18603. ■compat UNIX
  18604. ■headers
  18605. #include <time.h>
  18606. #include <sys/times.h>
  18607. #include <sys/param.h>  /* for HZ */
  18608. ■endheaders
  18609.  
  18610. ■param BUFFER
  18611. ■prototype
  18612. long times (struct tms *BUFFER);
  18613. ■endprototype
  18614.  
  18615.     Return the current time in CLK_TCK fractions of a second since
  18616.     00:00:00 1-Jan-1970 Coordinated Universal Time (UTC, GMT).  Also
  18617.     sets the tms_utime field of BUFFER to the number of HZ fractions
  18618.     of a second the process has been running.  The other fields are
  18619.     set to 0.
  18620.  
  18621. ■returnvalue
  18622.  
  18623.     times() returns the current time in CLK_TCK fractions of a second
  18624.     since 00:00 1-Jan-1970 UTC.
  18625.  
  18626. ■restrictions
  18627.  
  18628.     The return value is unusable due to overflow.
  18629.  
  18630. ■seealso clock() time()
  18631.  
  18632.  
  18633. ■function _tmalloc()
  18634. ■compat OS/2
  18635. ■headers
  18636. #include <stdlib.h>
  18637. ■endheaders
  18638.  
  18639. ■param SIZE
  18640. ■prototype
  18641. void *_tmalloc (size_t SIZE);
  18642. ■endprototype
  18643.  
  18644.     Allocate a block of memory big enough for holding SIZE bytes.  The
  18645.     block will not cross a 64 KByte boundary unless SIZE is greater
  18646.     than 65536.  If SIZE is greater than 65536, the block will be
  18647.     aligned on a 64 KByte boundary.  Therefore, blocks allocated with
  18648.     _tmalloc() can be used with 16-bit functions.  If there is an
  18649.     error, _tmalloc() returns NULL.  If SIZE is 0, zero bytes of
  18650.     memory are allocated, the return value will be unequal NULL.  Use
  18651.     _tfree() to deallocate a block of memory allocated by _tmalloc().
  18652.  
  18653.     As _tmalloc() causes additional heap fragmentation, you should not
  18654.     use _tmalloc() unless you need an aligned block.
  18655.  
  18656. ■returnvalue
  18657.  
  18658.     _tmalloc() returns a pointer to a newly allocated block of memory.
  18659.     On error, _tmalloc() returns NULL.
  18660.  
  18661. ■restrictions
  18662.  
  18663.     If you replace the emx malloc() implementation with a malloc()
  18664.     implementation (GNU malloc, for instance) that has not _tmalloc()
  18665.     etc. built in, you have to link with the ■tt{tmalloc} library
  18666.     (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
  18667.     etc.
  18668.  
  18669. ■seealso malloc() _tcalloc() _tfree() _trealloc() _utdefault() _utmalloc()
  18670.  
  18671.  
  18672. ■function tmpfile()
  18673. ■compat C90
  18674. ■headers
  18675. #include <stdio.h>
  18676. ■endheaders
  18677.  
  18678. ■prototype
  18679. FILE *tmpfile (void);
  18680. ■endprototype
  18681.  
  18682.     Create and open a temporary file.  The file is opened in
  18683.     ■tt{"w+b"} mode.  The file will automatically be deleted when the
  18684.     stream is closed with fclose() or at program termination.
  18685.  
  18686. ■returnvalue
  18687.  
  18688.     On success, tmpfile() returns a pointer to the stream associated
  18689.     with the temporary file.  If the file cannot be created, tmpfile()
  18690.     returns NULL.
  18691.  
  18692. ■implementation
  18693.  
  18694.     The name of the file is created as if tmpnam() were called.
  18695.  
  18696.     The temporary file will not be deleted if the program terminates
  18697.     abnormally.
  18698.  
  18699. ■seealso fclose() _rmtmp() tmpnam()
  18700.  
  18701.  
  18702. ■function tmpnam()
  18703. ■compat C90
  18704. ■headers
  18705. #include <stdio.h>
  18706. ■endheaders
  18707.  
  18708. ■param STRING
  18709. ■prototype
  18710. char *tmpnam (char *STRING);
  18711. ■endprototype
  18712.  
  18713.     Create a unique file name and store it to the array pointed to by
  18714.     STRING.  tmpnam() generates a different file name each time it is
  18715.     called, up to TMP_MAX times.  If STRING is NULL, a static buffer
  18716.     is used which will be overwritten by subsequent calls.  If STRING
  18717.     is not NULL, it must point to an array of at least L_tmpnam
  18718.     characters.
  18719.  
  18720. ■returnvalue
  18721.  
  18722.     On success, tmpnam() returns a pointer to the new name.  On
  18723.     failure, tmpnam() returns NULL.
  18724.  
  18725. ■implementation
  18726.  
  18727.     The file name is the concatenation of P_tmpdir and a sequence of
  18728.     digits.
  18729.  
  18730. ■hints
  18731.  
  18732.     Use tmpfile() if you need a temporary file but don't need the name
  18733.     of that file.  Note that tmpnam() is subject to a race condition:
  18734.     other processes may use the same temporary file name before you
  18735.     have a chance to create the temporary file.
  18736.  
  18737. ■seealso tempnam() tmpfile() mktemp()
  18738.  
  18739.  
  18740. ■function tolower() toupper()
  18741. ■compat C90
  18742. ■headers
  18743. #include <ctype.h>
  18744. ■endheaders
  18745.  
  18746. ■param C
  18747. ■prototype
  18748. int tolower (int C);
  18749. int toupper (int C);
  18750. ■endprototype
  18751.  
  18752.     tolower() converts the character C to lower case, if it is an
  18753.     upper-case letter.  toupper() converts the character C to upper
  18754.     case, if it is a lower-case letter.
  18755.  
  18756. ■returnvalue
  18757.  
  18758.     If the argument of tolower() is a character for which isupper() is
  18759.     true and there is a corresponding character for which islower() is
  18760.     true, tolower() returns the corresponding character; otherwise
  18761.     tolower() returns the argument unchanged.
  18762.  
  18763.     If the argument of toupper() is a character for which islower() is
  18764.     true and there is a corresponding character for which isupper() is
  18765.     true, toupper() returns the corresponding character; otherwise
  18766.     toupper() returns the argument unchanged.
  18767.  
  18768. ■restrictions
  18769.  
  18770.     Currently, locale is ignored.
  18771.  
  18772. ■seealso setlocale() stricmp() strlwr() strupr() _tolower() _toupper()
  18773.  
  18774.  
  18775. ■function _tolower() _toupper()
  18776. ■compat UNIX
  18777. ■headers
  18778. #include <ctype.h>
  18779. ■endheaders
  18780.  
  18781. ■param C
  18782. ■prototype
  18783. int _tolower (int C);
  18784. int _toupper (int C);
  18785. ■endprototype
  18786.  
  18787.     _tolower() converts the upper-case character C to lower case; C
  18788.     must be in the range ■tt{'A'} through ■tt{'Z'}.  _toupper()
  18789.     converts the lower-case character C to upper case; C must be in
  18790.     the range ■tt{'a'} through ■tt{'z'}.
  18791.  
  18792. ■returnvalue
  18793.  
  18794.     See above.
  18795.  
  18796. ■seealso tolower() toupper()
  18797.  
  18798.  
  18799. ■function _trealloc()
  18800. ■compat OS/2
  18801. ■headers
  18802. #include <stdlib.h>
  18803. ■endheaders
  18804.  
  18805. ■param MEM SIZE
  18806. ■prototype
  18807. void *_trealloc (void *MEM, size_t SIZE);
  18808. ■endprototype
  18809.  
  18810.     Reallocate the block of memory pointed to by MEM, making it big
  18811.     enough to hold SIZE bytes.  The block will not cross a 64 KByte
  18812.     boundary unless SIZE is greater than 65536.  If SIZE is greater
  18813.     than 65536, the block will be aligned on a 64 KByte boundary.  If
  18814.     MEM is NULL, a new block of memory is allocated.  Otherwise, MEM
  18815.     must be a pointer returned by _tcalloc(), _tmalloc() or
  18816.     _trealloc(); the size of MEM is adjusted.  If MEM is non-■tt{NULL}
  18817.     and SIZE is zero, the block is freed and NULL is returned.  If MEM
  18818.     cannot be expanded in-place, it is moved.  A pointer to the new,
  18819.     resized block of memory is returned.  If there is not enough
  18820.     memory available, NULL is returned.
  18821.  
  18822.     MEM can also be a pointer to a block of memory freed by _tfree()
  18823.     as long as calloc(), malloc(), realloc(), _tcalloc(), _tmalloc()
  18824.     and _trealloc() have not been called since freeing the block.
  18825.     Using this feature is not recommended, it may get removed in
  18826.     future implementations of _trealloc().
  18827.  
  18828. ■returnvalue
  18829.  
  18830.     _trealloc() returns MEM (if the block could be resized without
  18831.     moving), a pointer to a newly allocated block of memory, or NULL
  18832.     (if there wasn't enough memory).
  18833.  
  18834. ■restrictions
  18835.  
  18836.     If you replace the emx malloc() implementation with a malloc()
  18837.     implementation (GNU malloc, for instance) that has not _tmalloc()
  18838.     etc. built in, you have to link with the ■tt{tmalloc} library
  18839.     (-ltmalloc), which implements _tmalloc() etc. on top of malloc()
  18840.     etc.
  18841.  
  18842. ■seealso realloc() _tmalloc() _utdefault()
  18843.  
  18844.  
  18845. ■function trunc() truncl()
  18846. ■compat C9X
  18847. ■headers
  18848. #include <math.h>
  18849. ■endheaders
  18850.  
  18851. ■param X
  18852. ■prototype
  18853. double trunc (double X);
  18854. long double truncl (long double X);
  18855. ■endprototype
  18856.  
  18857.     Return as floating-point number X chopped to an integer by
  18858.     truncating the fractional digits (rounding toward 0).
  18859.  
  18860.     truncl() uses the ■tt{long double} format.
  18861.  
  18862. ■returnvalue
  18863.  
  18864.     See above.
  18865.  
  18866. ■seealso ceil() floor() modf() rint()
  18867.  
  18868.  
  18869. ■function truncate()
  18870. ■compat BSD
  18871. ■headers
  18872. #include <io.h>
  18873. ■endheaders
  18874.  
  18875. ■param NAME LENGTH
  18876. ■prototype
  18877. int truncate (char *NAME, long LENGTH);
  18878. ■endprototype
  18879.  
  18880.     Truncate a file to at most LENGTH bytes.  NAME is a pointer to a
  18881.     string containing the name of the file.  If LENGTH is greater than
  18882.     the current length of the file, the length is not changed.
  18883.  
  18884. ■returnvalue
  18885. ■description
  18886. ■item 0
  18887.     success
  18888. ■item -1
  18889.     error
  18890. ■enddescription
  18891.  
  18892. ■seealso chsize() ftruncate()
  18893.  
  18894.  
  18895. ■function ttyname()
  18896. ■compat POSIX.1
  18897. ■headers
  18898. #include <unistd.h>
  18899. ■endheaders
  18900.  
  18901. ■param HANDLE
  18902. ■prototype
  18903. char *ttyname (int HANDLE);
  18904. ■endprototype
  18905.  
  18906.     Return a pointer to a string containing the pathname of the device
  18907.     associated with file descriptor HANDLE.
  18908.  
  18909.     The pointer returned by ttyname() may point to a static buffer
  18910.     which is overwritten by each call of ttyname().
  18911.  
  18912. ■returnvalue
  18913.  
  18914.     If successful, ttyname() returns a pointer to a null-terminated
  18915.     string.  On error, ttyname() returns NULL.
  18916.  
  18917. ■restrictions
  18918.  
  18919.     ttyname() is not implemented for DOS.  ttyname() is not available
  18920.     with the system call library sys.lib (■hpt{-Zsys}).
  18921.  
  18922.     ttyname() is implemented for the following devices only:
  18923.     ■tt{/dev/con}, ■tt{/dev/nul}, ■tt{/dev/clock$}, and the devices of
  18924.     Holger Veit's ■tt{xf86sup.sys} device driver.
  18925.  
  18926. ■seealso fstat() isatty()
  18927.  
  18928.  
  18929. ■function tzset()
  18930. ■compat C90 VAC++
  18931. ■headers
  18932. #include <time.h>
  18933. ■endheaders
  18934.  
  18935. ■prototype
  18936. void tzset (void);
  18937. ■endprototype
  18938.  
  18939.     Set timezone according to the TZ environment variable.  The
  18940.     following global variables are set by tzset(): ■tt{daylight},
  18941.     ■tt{timezone}, tzname.  The value of TZ has the following format:
  18942.  
  18943. ■indent
  18944.     ■sy{<TZ1>[<OFF>,[<TZ2>[,<SM>,<SW>,<SD>,<ST>,<EM>,<EW>,<ED>,<ET>,<SHIFT>]]]}
  18945. ■endindent
  18946.  
  18947.     ■sy{<TZ1>} is the three-letter name of the standard timezone.
  18948.  
  18949.     ■sy{<OFF>} is the offset to Coordinated Universal Time; positive
  18950.     values are to the west of the Prime Meridian, negative values are
  18951.     to the east of the Prime Meridian.  The offset can be specified as
  18952.     hours, hours and minutes, or hours, minutes, and seconds.  Hours,
  18953.     minutes, and seconds are separated by colons.  If ■sy{<OFF>} is
  18954.     not specified, an offset of 0 will be used (this may change in the
  18955.     future).
  18956.  
  18957.     ■sy{<TZ2>} is the three-letter name of the summer timezone
  18958.     (daylight saving time).  If ■sy{<TZ2>} is not specified, daylight
  18959.     saving time does not apply.  If ■sy{<TZ2>} is specified, daylight
  18960.     saving time does apply; the remainder of the TZ's value specifies
  18961.     when and how to change to and back from daylight saving time.
  18962.     ■sy{<SM>} through ■sy{<ST>} define, in current local time, when to
  18963.     switch from standard time to daylight saving time, ■sy{<EM>}
  18964.     through ■sy{<ET>} define, in current local time, when to switch
  18965.     from daylight saving time to standard time.  (On the southern
  18966.     hemisphere, the end date precedes the start date.)  ■sy{<SHIFT>} is
  18967.     the amount of change in seconds.
  18968.  
  18969.     ■sy{<SM>} specifies the month (1 through 12) of the change.
  18970.     ■sy{<SW>} specifies the week of the change; if this value is zero,
  18971.     ■sy{<SD>} specifies the day of month (1 through 31).  If ■sy{<SW>}
  18972.     is positive (1 through 4), the change occurs on weekday ■sy{<SD>}
  18973.     (0=Sunday through 6=Saturday) of the ■sy{<SW>}th week of the
  18974.     specified month.  The first week of a month starts on the first
  18975.     Sunday of the month.  If ■sy{<SW>} is negative (-1 through -4),
  18976.     the change occurs on weekday ■sy{<SD>} (0=Sunday through
  18977.     6=Saturday) of the -■sy{<SW>}th week of the specified month,
  18978.     counted from the end of the month (that is, -1 specifies the last
  18979.     week of the month).  The last week of a month starts on the last
  18980.     Sunday of the month.  ■sy{<ST>} specifies the time of the change,
  18981.     in seconds.  Note that ■sy{<ST>} is specified in local standard
  18982.     time and ■sy{<ET>} is specified in local daylight saving time.
  18983.     Example:
  18984.  
  18985. ■example
  18986. CET-1CED,3,-1,0,7200,10,-1,0,10800,3600
  18987. ■endexample
  18988.  
  18989.     In this example, the name of the standard time zone is ■tt{CET},
  18990.     the name of the summer time zone is CED.  Daylight saving time
  18991.     starts at 2:00 on the last Sunday of March and ends at 3:00 on the
  18992.     last Sunday of October.  Time changes by one hour in daylight
  18993.     saving time.
  18994.  
  18995.     If no characters follow ■sy{<TZ2>}, the rule
  18996.     `■tt{,4,1,0,3600,10,-1,0,7200,3600}' will be used: Daylight saving
  18997.     time starts at 1:00 on the first Sunday of April and ends at 2:00
  18998.     on the last Sunday of October.  Time changes by one hour in
  18999.     daylight saving time.
  19000.  
  19001.     If the value of TZ is invalid, tzset() does not have any effect.
  19002.  
  19003. ■implementation
  19004.  
  19005.     If TZ is not set, Coordinated Universal Time will be used.
  19006.  
  19007.     The three-character limit for timezone names and the weird and
  19008.     US-based definition of `first week' and `last week' are required
  19009.     for compatibility with applications compiled with VAC++.
  19010.  
  19011. ■restrictions
  19012.  
  19013.     After changing the value of TZ by modifying environ, you should
  19014.     call tzset().  That is not required when changing TZ with putenv().
  19015.  
  19016. ■seealso environ putenv()
  19017.  
  19018.  
  19019. ■function _uaddmem()
  19020. ■compat VAC++
  19021. ■headers
  19022. #include <umalloc.h>
  19023. ■endheaders
  19024.  
  19025. ■param H MEMORY SIZE CLEAN
  19026. ■prototype
  19027. Heap_t _uaddmem (Heap_t H, void *MEMORY, size_t SIZE, int CLEAN);
  19028. ■endprototype
  19029.  
  19030.     _uaddmem() adds memory to the heap H.  MEMORY points to the memory
  19031.     area to be added, SIZE is the size of the memory area in bytes.
  19032.     CLEAN should be _BLOCK_CLEAN if the memory area has been
  19033.     initialized to zeros; CLEAN should be ■tt{!_BLOCK_CLEAN} if the
  19034.     memory area contains or may contain non-zero bytes.  If the heap
  19035.     is shared, MEMORY should point to shared memory.
  19036.  
  19037.     If the memory area added by _uaddmem() is adjacent to (the end of)
  19038.     one of the segments of the heap, that segment will be expanded.
  19039.     Otherwise, a new segment will be created and a number of bytes of
  19040.     the memory area will be used for storing control information.
  19041.  
  19042. ■hints
  19043.  
  19044.     Add few large memory areas instead of many small memory areas to
  19045.     minimize the total overhead of the control information added to
  19046.     the segments.  Moreover, the size of the segments limits the size
  19047.     of the blocks which can be allocated from the heap.
  19048.  
  19049.     Memory allocated with DosAllocMem is initialized to zeros.
  19050.  
  19051. ■returnvalue
  19052.  
  19053.     _uaddmem() returns H if successful.  _uaddmem() returns NULL on
  19054.     error.
  19055.  
  19056. ■seealso sbrk() _ucreate() _ucreate2() _udestroy()
  19057.  
  19058.  
  19059. ■function _ucalloc()
  19060. ■compat VAC++
  19061. ■headers
  19062. #include <umalloc.h>
  19063. ■endheaders
  19064.  
  19065. ■param H ELEMENTS SIZE
  19066. ■prototype
  19067. void *_ucalloc (Heap_t H, size_t ELEMENTS, size_t SIZE);
  19068. ■endprototype
  19069.  
  19070.     Allocate from the heap H a block of memory big enough for holding
  19071.     ELEMENTS elements of SIZE bytes each.  _ucalloc() fills the block
  19072.     with zeros.  If there is an error, _ucalloc() returns NULL.
  19073.  
  19074. ■implementation
  19075.  
  19076.     If at least one argument is zero, _ucalloc() returns a non-NULL
  19077.     pointer if there's enough space left in the heap for a block of
  19078.     the minimum size.
  19079.  
  19080. ■returnvalue
  19081.  
  19082.     _ucalloc() returns a pointer to a newly allocated block of memory.
  19083.     On error, _ucalloc() returns NULL.
  19084.  
  19085. ■seealso calloc() free() _msize() _udefault() _umalloc() _utcalloc()
  19086.  
  19087.  
  19088. ■function _ucreate()
  19089. ■compat VAC++
  19090. ■headers
  19091. #include <umalloc.h>
  19092. ■endheaders
  19093.  
  19094. ■param MEMORY SIZE CLEAN TYPE ALLOC_FUN RELEASE_FUN
  19095. ■prototype
  19096. Heap_t _ucreate (void *MEMORY, size_t SIZE, int CLEAN, unsigned TYPE,
  19097.                  void *(*ALLOC_FUN)(Heap_t, size_t *, int *),
  19098.                  void (*RELEASE_FUN)(Heap_t, void *, size_t));
  19099. ■endprototype
  19100.  
  19101.     _ucreate() creates a heap in the memory area pointed to by MEMORY
  19102.     of size SIZE bytes.  SIZE must be at least _HEAP_MIN_SIZE.  CLEAN
  19103.     should be _BLOCK_CLEAN if the memory area has been initialized to
  19104.     zeros; CLEAN should be ■tt{!_BLOCK_CLEAN} if the memory area
  19105.     contains or may contain non-zero bytes.  TYPE specifies the type
  19106.     of the heap: _HEAP_REGULAR (regular, not tiled) or _HEAP_TILED.
  19107.     All memory allocated from a tiled heap will be appropriately
  19108.     aligned (tiled) for 16-bit functions.  In addition to
  19109.     _HEAP_REGULAR or _HEAP_TILED, TYPE may include _HEAP_SHARED (using
  19110.     the ■tt{|} operator) if MEMORY points to shared memory.  If
  19111.     _HEAP_SHARED is set, the heap can be shared between processes.
  19112.     The remaining two arguments are pointers to callback functions for
  19113.     allocating and releasing additional memory objects (segments) for
  19114.     the heap.  Any or all of these arguments may be NULL to indicate
  19115.     that no callback function is provided.  _ucreate() returns a
  19116.     pointer to the new heap or, on error, NULL.
  19117.  
  19118.     Before the new heap can be used, _uopen() must be called.  To
  19119.     destroy the heap, call _uclose() and _udestroy(), then deallocate
  19120.     the memory area pointed to by MEMORY if appropriate.  You can use
  19121.     the new heap as default heap by calling _udefault() or as tiled
  19122.     default heap by calling _utdefault().
  19123.  
  19124.     The function pointed to by ALLOC_FUN is called to allocate more
  19125.     memory for the heap.  See ■hpt{_ucreate2()} for details.  If
  19126.     ALLOC_FUN is NULL, the size of the heap is fixed; if the initial
  19127.     size is exhausted, allocation will fail.
  19128.  
  19129.     The function pointed to by RELEASE_FUN is called to deallocate
  19130.     memory memory allocated by the function pointed to by ALLOC_FUN.
  19131.     See ■hpt{_ucreate2()} for details.  If RELEASE_FUN is NULL,
  19132.     _udestroy() and _uheapmin() won't release memory.
  19133.  
  19134.     _ucreate2() is equivalent to _ucreate() with NULL passed for
  19135.     ■pa{EXPAND_FUN} and ■pa{SHRINK_FUN}.
  19136.  
  19137. ■returnvalue
  19138.  
  19139.     _ucreate() returns a pointer to the new heap if successful.
  19140.     _ucreate() returns NULL on error.
  19141.  
  19142. ■seealso sbrk() _ucreate2() _udefault() _udestroy() _uheapchk() _umalloc() _uopen() _utdefault()
  19143.  
  19144. ■samplecode
  19145. #define INCL_DOSMEMMGR
  19146. #include <os2.h>
  19147. #include <umalloc.h>
  19148.  
  19149. Heap_t create_shared_heap (const char *name, size_t size)
  19150. {
  19151.   ULONG rc;
  19152.   void *mem;
  19153.   Heap_t h;
  19154.  
  19155.   rc = DosAllocSharedMem (&mem, name, size,
  19156.                           PAG_COMMIT | PAG_READ | PAG_WRITE);
  19157.   if (rc != 0)
  19158.     return NULL;
  19159.   h = _ucreate (mem, size, !_BLOCK_CLEAN, _HEAP_REGULAR | _HEAP_SHARED,
  19160.                 NULL, NULL);
  19161.   if (h == NULL)
  19162.     DosFreeMem (mem);
  19163.   return h;
  19164. }
  19165. ■endsamplecode
  19166.  
  19167.  
  19168. ■function _ucreate2()
  19169. ■compat emx
  19170. ■headers
  19171. #include <umalloc.h>
  19172. ■endheaders
  19173.  
  19174. ■param MEMORY SIZE CLEAN TYPE ALLOC_FUN RELEASE_FUN EXPAND_FUN SHRINK_FUN
  19175. ■param H PSIZE PCLEAN BASE OLD_SIZE PNEW_SIZE
  19176. ■prototype
  19177. Heap_t _ucreate2 (void *MEMORY, size_t SIZE, int CLEAN, unsigned TYPE,
  19178.                   void *(*ALLOC_FUN)(Heap_t, size_t *, int *),
  19179.                   void (*RELEASE_FUN)(Heap_t, void *, size_t),
  19180.                   int (*EXPAND_FUN)(Heap_t, void *, size_t, size_t *, int *),
  19181.                   void (*SHRINK_FUN)(Heap_t, void *, size_t, size_t *));
  19182. ■endprototype
  19183.  
  19184.     _ucreate2() creates a heap in the memory area pointed to by MEMORY
  19185.     of size SIZE bytes.  SIZE must be at least _HEAP_MIN_SIZE.  CLEAN
  19186.     should be _BLOCK_CLEAN if the memory area has been initialized to
  19187.     zeros; CLEAN should be ■tt{!_BLOCK_CLEAN} if the memory area
  19188.     contains or may contain non-zero bytes.  TYPE specifies the type
  19189.     of the heap: _HEAP_REGULAR (regular, not tiled) or _HEAP_TILED.
  19190.     All memory allocated from a tiled heap will be appropriately
  19191.     aligned (tiled) for 16-bit functions.  In addition to
  19192.     _HEAP_REGULAR or _HEAP_TILED, TYPE may include _HEAP_SHARED (using
  19193.     the ■tt{|} operator) if MEMORY points to shared memory.  If
  19194.     _HEAP_SHARED is set, the heap can be shared between processes.
  19195.     The remaining four arguments are pointers to callback functions
  19196.     for allocating, releasing, expanding, or shrinking additional
  19197.     memory objects (segments) for the heap.  Any or all of these
  19198.     arguments may be NULL to indicate that no callback function is
  19199.     provided.  _ucreate2() returns a pointer to the new heap or, on
  19200.     error, NULL.
  19201.  
  19202.     Before the new heap can be used, _uopen() must be called.  To
  19203.     destroy the heap, call _uclose() and _udestroy(), then deallocate
  19204.     the memory area pointed to by MEMORY if appropriate.  You can use
  19205.     the new heap as default heap by calling _udefault() or as tiled
  19206.     default heap by calling _utdefault().  You can add more memory to a
  19207.     heap with _uaddmem().
  19208.  
  19209.     The function pointed to by ALLOC_FUN is called to allocate more
  19210.     memory for the heap:
  19211.  
  19212. ■indent
  19213.     ■tt{void *my_alloc (Heap_t }H■tt{, size_t *}PSIZE■tt{, int *}PCLEAN■tt{);}
  19214. ■endindent
  19215.  
  19216.     H points to the heap to be expanded.  Note that the heap is
  19217.     locked, so passing H to a heap-specific library function (except
  19218.     for _uheap_type()) will cause a deadlock.  If the heap is shared,
  19219.     the function shall allocate shared memory. The function can call
  19220.     _uheap_type() to query the type of memory required.  PSIZE points
  19221.     to an object containing the desired size of the memory area to be
  19222.     allocated.  The function may allocate more memory than requested;
  19223.     it's recommended to allocate a multiple of 65536 bytes.  The
  19224.     function may also allocate less memory than requested; however, it
  19225.     must not do so twice in a row.  This can be used to fill gaps
  19226.     caused by non-contiguous memory allocation.  The function shall
  19227.     store to the object pointed to by PSIZE the actual number of bytes
  19228.     allocated.  Moreover, the function shall store _BLOCK_CLEAN or
  19229.     ■tt{!}_BLOCK_CLEAN to the object pointed to by PCLEAN depending on
  19230.     whether the memory area has been initialized to zeros or not,
  19231.     respectively.  The function shall return a pointer to the memory
  19232.     area it has allocated or NULL if the allocation request could not
  19233.     be satisfied.  If the function returns a pointer to a memory area
  19234.     adjacent to (the end of) another memory area of the heap, that
  19235.     memory area will be expanded, so that blocks spanning both memory
  19236.     areas can be allocated.
  19237.  
  19238.     If ALLOC_FUN is NULL, the size of the heap is fixed; if the
  19239.     initial size is exhausted, allocation will fail.  However, you can
  19240.     add more memory to a heap with ■hpt{_uaddmem()}.
  19241.  
  19242.     The function pointed to by RELEASE_FUN is called to deallocate
  19243.     memory memory allocated by the function pointed to by ALLOC_FUN:
  19244.  
  19245. ■indent
  19246.     ■tt{void my_release (Heap_t }H■tt{, void *}MEMORY■tt{, size_t }SIZE■tt{);}
  19247. ■endindent
  19248.  
  19249.     H points to the heap for which the memory area has been allocated.
  19250.     Note that the heap is locked, so passing H to a heap-specific
  19251.     library function will cause a deadlock.  MEMORY points to the
  19252.     memory area to be deallocated; the memory area has been allocated
  19253.     by the function pointed to by ALLOC_FUN.  SIZE is the size of the
  19254.     memory area, as reported by the function pointed to by ALLOC_FUN.
  19255.  
  19256.     If RELEASE_FUN is NULL, _udestroy() and _uheapmin() won't release
  19257.     memory.
  19258.  
  19259.     The function pointed to by EXPAND_FUN is called to expand a memory
  19260.     area of the heap:
  19261.  
  19262. ■indent
  19263.     ■tt{int my_expand (Heap_t }H■tt{, void *}BASE■tt{, size_t }OLD_SIZE■tt{,} ■break
  19264.     ■tt{               size_t *}PNEW_SIZE■tt{, int *}PCLEAN■tt{);}
  19265. ■endindent
  19266.  
  19267.     H points to the heap to be expanded.  Note that the heap is
  19268.     locked, so passing H to a heap-specific library function will
  19269.     cause a deadlock.  BASE points to the memory area to expand; it
  19270.     points either to the initial memory area for the heap (passed as
  19271.     MEMORY to _ucreate() or _ucreate2()) or to a memory area allocated
  19272.     by the function pointed to by ALLOC_FUN.  The memory area
  19273.     currently has a size of OLD_SIZE bytes (as passed as SIZE to
  19274.     _ucreate() or _ucreate2() or as reported by the function pointed
  19275.     to by ALLOC_FUN or EXPAND_FUN).  PNEW_SIZE points to an object
  19276.     containing the size to which the memory area should be expanded.
  19277.     The function may expand the memory area more than requested; it's
  19278.     recommended to expand to a multiple of 65536 bytes.  Expanding the
  19279.     memory area less than requested is also possible, but not
  19280.     recommended.  The function shall store the actual new size of the
  19281.     memory area to the object pointed to by PNEW_SIZE.  Moreover, the
  19282.     function shall store _BLOCK_CLEAN or ■tt{!}_BLOCK_CLEAN to the
  19283.     object pointed to by PCLEAN depending on whether the additional
  19284.     memory has been initialized to zeros or not, respectively.  The
  19285.     function shall return a non-zero value if expansion succeeded, or
  19286.     0 if if the expansion request could not be satisfied.
  19287.  
  19288.     If EXPAND_FUN is NULL, _expand() and realloc() won't attempt to
  19289.     expand the heap to expand in place the last block of a heap
  19290.     segment.  Instead, the function pointed to by ALLOC_FUN might be
  19291.     called to expand the heap non-contiguously.
  19292.  
  19293.     The function pointed to by SHRINK_FUN is called to shrink a memory
  19294.     area of the heap:
  19295.  
  19296. ■indent
  19297.     ■tt{void my_shrink (Heap_t }H■tt{, void *}MEMORY■tt{, size_t }OLD_SIZE■tt{,} ■break
  19298.     ■tt{                size_t *}PNEW_SIZE■tt{);}
  19299. ■endindent
  19300.  
  19301.     H points to the heap to be shrunk.  Note that the heap is locked,
  19302.     so passing H to a heap-specific library function will cause a
  19303.     deadlock.  MEMORY points to the memory area to shrunk; it points
  19304.     to a memory area allocated by the function pointed to by
  19305.     ALLOC_FUN.  Note that the initial memory area is never shrunk
  19306.     below its initial size.  The memory area currently has a size of
  19307.     OLD_SIZE bytes (as reported by the function pointed to by
  19308.     ALLOC_FUN or EXPAND_FUN).  PNEW_SIZE points to an object
  19309.     containing the size to which the memory area should be shrunk;
  19310.     that size might be 0.  The function may shrink the memory area
  19311.     less than requested; it's recommended to shrink to a multiple of
  19312.     65536 bytes.  The function shall store the actual new size of the
  19313.     memory area to the object pointed to by PNEW_SIZE.  If the memory
  19314.     area cannot be shrunk, the function shall store OLD_SIZE to the
  19315.     object pointed to by PNEW_SIZE.
  19316.  
  19317.     If SHRINK_FUN is NULL, _uheapmin() won't attempt to shrink memory
  19318.     areas; however, it will still try to deallocate memory areas if
  19319.     RELEASE_FUN is not NULL.
  19320.  
  19321. ■returnvalue
  19322.  
  19323.     _ucreate2() returns a pointer to the new heap if successful.
  19324.     _ucreate2() returns NULL on error.
  19325.  
  19326. ■implementation
  19327.  
  19328.     If you need compatibility with VAC++, use _ucreate() instead of
  19329.     _ucreate2().  Note that VAC++ does not allow ALLOC_FUN to allocate
  19330.     less memory than requested.
  19331.  
  19332. ■hints
  19333.  
  19334.     Memory allocated with DosAllocMem is initialized to zeros.
  19335.  
  19336. ■seealso sbrk() _ucreate() _udefault() _udestroy() _uheapchk() _uheap_type() _umalloc() _uopen() _utdefault()
  19337.  
  19338.  
  19339. ■function _uclose()
  19340. ■compat VAC++
  19341. ■headers
  19342. #include <umalloc.h>
  19343. ■endheaders
  19344.  
  19345. ■param H
  19346. ■prototype
  19347. int _uclose (Heap_t H);
  19348. ■endprototype
  19349.  
  19350.     Close the heap H.  Heaps should be closed before destruction with
  19351.     _udestroy().  Shared heaps should be closed when they are no
  19352.     longer used; they should be closed by all processes before
  19353.     destruction with _udestroy().  After closing a heap, all attempts
  19354.     to access the heap will invoke undefined behavior.  _uclose()
  19355.     fails if H is the runtime heap (_RUNTIME_HEAP) or the tiled
  19356.     runtime heap.
  19357.  
  19358. ■returnvalue
  19359. ■description
  19360. ■item 0
  19361.     success
  19362. ■item -1
  19363.     error
  19364. ■enddescription
  19365.  
  19366. ■seealso _ucreate() _ucreate2() _udestroy() _uopen()
  19367.  
  19368.  
  19369. ■function _udefault()
  19370. ■compat VAC++
  19371. ■headers
  19372. #include <umalloc.h>
  19373. ■endheaders
  19374.  
  19375. ■param H
  19376. ■prototype
  19377. Heap_t _udefault (Heap_t H);
  19378. ■endprototype
  19379.  
  19380.     The _udefault() function selects the heap pointed to by H as the
  19381.     default heap of the current thread unless H is NULL.  All
  19382.     non-tiled memory allocation functions such as malloc() which don't
  19383.     take a pointer to a heap will use the heap pointed to by H if
  19384.     called in the same thread.  If H is NULL, _udefault() won't set
  19385.     the default heap.
  19386.  
  19387.     Initially, the runtime heap, _RUNTIME_HEAP, is used as default
  19388.     heap for all threads.  You can make _RUNTIME_HEAP again the
  19389.     default heap of the current thread by calling
  19390.     ■tt{_udefault(_RUNTIME_HEAP)}.
  19391.  
  19392. ■returnvalue
  19393.  
  19394.     _udefault() returns a pointer to the previous default heap of the
  19395.     current thread.  If the default heap has not yet been created,
  19396.     _udefault() will return NULL.
  19397.  
  19398. ■hints
  19399.  
  19400.     You can use _udefault() to assign a unique heap to each thread or
  19401.     to share the default heap between multiple processes.
  19402.  
  19403.     To obtain a pointer to the default heap of the current thread
  19404.     without selecting a new heap, call ■tt{_udefault(NULL)}.
  19405.  
  19406. ■seealso _mheap() _ucreate() _ucreate2() _utdefault()
  19407.  
  19408. ■samplecode
  19409. Heap_t *my_heap, old_heap;
  19410.  
  19411. old_heap = _udefault (my_heap);
  19412. /*...*/
  19413. _udefault (old_heap);   /* Restore previous default heap */
  19414. ■endsamplecode
  19415.  
  19416.  
  19417. ■function _udestroy()
  19418. ■compat VAC++
  19419. ■headers
  19420. #include <umalloc.h>
  19421. ■endheaders
  19422.  
  19423. ■param H FORCE
  19424. ■prototype
  19425. int _udestroy (Heap_t H, int FORCE);
  19426. ■endprototype
  19427.  
  19428.     Destroy the heap H.  If there are any blocks of the heap in use
  19429.     (not freed) and FORCE is ■tt{!_FORCE}, _udestroy() fails.  If
  19430.     FORCE is _FORCE, the heap will be destroyed even if there are
  19431.     blocks in use.
  19432.  
  19433.     The function passed to the ■pa{RELEASE_FUN} argument (if not NULL)
  19434.     of ■hpt{_ucreate()} and ■hpt{_ucreate2()} is called to deallocate
  19435.     all segments added to the heap, that is, all memory assigned to
  19436.     the heap except for the initial memory area passed to _ucreate()
  19437.     or _ucreate2().
  19438.  
  19439.     _udestroy() fails if H is the runtime heap (_RUNTIME_HEAP) or the
  19440.     tiled runtime heap.  ■hpt{_uclose()} should be called before
  19441.     _udestroy().  After destroying a heap, all attempts to access the
  19442.     heap will invoke undefined behavior.
  19443.  
  19444. ■returnvalue
  19445. ■description
  19446. ■item 0
  19447.     success
  19448. ■item -1
  19449.     error
  19450. ■enddescription
  19451.  
  19452. ■seealso _uaddmem() _uclose() _ucreate() _ucreate2() _udefault() _uheapmin()
  19453.  
  19454.  
  19455. ■function _uflags()
  19456. ■compat emx
  19457. ■headers
  19458. #include <sys/uflags.h>
  19459. ■endheaders
  19460.  
  19461. ■param MASK NEW_BITS
  19462. ■prototype
  19463. int _uflags (int MASK, int NEW_BITS);
  19464. ■endprototype
  19465.  
  19466.     Set bits which control the behavior of the emx runtime library
  19467.     (emx.dll, emx.exe, or sys.lib).  Bits set in MASK are replaced
  19468.     with the matching bits of NEW_BITS:
  19469.  
  19470. ■example
  19471. bits = ((bits & ~mask) | (new_bits & mask));
  19472. ■endexample
  19473.  
  19474.     If MASK is 0, the bits are not changed.  MASK should be one of the
  19475.     following symbols:
  19476. ■description
  19477. ■item _UF_SIG_MODEL
  19478.     Signal processing model
  19479. ■item _UF_SBRK_MODEL
  19480.     Memory allocation model for sbrk()
  19481. ■item _UF_PTRACE_MODEL
  19482.     Debugging model for ptrace()
  19483. ■enddescription
  19484.     If MASK includes _UF_SIG_MODEL, exactly one of the following
  19485.     symbols should be used in NEW_BITS:
  19486. ■description
  19487. ■item _UF_SIG_EMX
  19488.     Select the emx signal processing model for signal() -- this is the
  19489.     default setting
  19490. ■item _UF_SIG_SYSV
  19491.     Select the System V signal processing model for signal().  The
  19492.     -Zsysv-signals option selects _UF_SIG_SYSV
  19493. ■item _UF_SIG_BSD
  19494.     Select the BSD and POSIX.1 signal processing model for signal().
  19495.     The -Zbsd-signals option selects _UF_SIG_BSD
  19496. ■enddescription
  19497.     If MASK includes _UF_SBRK_MODEL, exactly one of the following
  19498.     symbols should be used in NEW_BITS:
  19499. ■description
  19500. ■item _UF_SBRK_CONTIGUOUS
  19501.     sbrk() always allocates contiguous memory; the size of the heap is
  19502.     limited to the initial heap size.  This is the initial setting;
  19503.     however, the malloc() implementation of emx selects
  19504.     _UF_SBRK_ARBITRARY
  19505. ■item _UF_SBRK_MONOTONOUS
  19506.     sbrk() may allocate non-contiguous memory with increasing
  19507.     addresses; up to 16 memory objects can be used for the heap
  19508. ■item _UF_SBRK_ARBITRARY
  19509.     sbrk() may allocate non-contiguous memory with arbitrary
  19510.     addresses; up to 16 memory objects can be used for the heap.  The
  19511.     malloc() implementation of emx selects _UF_SBRK_ARBITRARY
  19512. ■enddescription
  19513.     If MASK includes _UF_PTRACE_MODEL, exactly one of the following
  19514.     symbols should be used in NEW_BITS:
  19515. ■description
  19516. ■item _UF_PTRACE_STANDARD
  19517.     ptrace() doesn't report creation and termination of threads and
  19518.     loading and freeing of modules (DLLs); moreover, ptrace() doesn't
  19519.     support multiple threads.  This is the initial setting.
  19520. ■item _UF_PTRACE_NOTIFY
  19521.     ptrace() may report creation and termination of threads and
  19522.     loading and freeing of modules (DLLs); ptrace() does not support
  19523.     multiple threads.
  19524. ■item _UF_PTRACE_MULTITHREAD
  19525.     ptrace() may report creation and termination of threads and
  19526.     loading and freeing of modules (DLLs); moreover, ptrace() does
  19527.     support multiple threads; this model also modifies the return
  19528.     values of wait() and waitpid() for processes being under control
  19529.     of ptrace().
  19530. ■enddescription
  19531.     To pass multiple values, use the ■tt{|} operator to combine the
  19532.     symbols.
  19533.  
  19534.     _uflags() should not be called by application programs.
  19535.     _UF_SBRK_MONOTONOUS and _UF_SBRK_ARBITRARY should not be selected
  19536.     unless all callers of sbrk() know how to cope with non-contiguous
  19537.     memory.
  19538.  
  19539.     The -Zsysv-signals and -Zbsd-signals options of GCC add startup
  19540.     code which calls _uflags().
  19541.  
  19542. ■returnvalue
  19543.  
  19544.     _uflags() returns the previous set of bits (ie, the set of bits
  19545.     which was in effect when _uflags() was called).
  19546.  
  19547. ■restrictions
  19548.  
  19549.     Under DOS, memory is always contiguous, _UF_SBRK_MONOTONOUS and
  19550.     _UF_SBRK_ARBITRARY are ignored.  _UF_SIG_SYSV and _UF_SIG_BSD are
  19551.     not supported with the system call library sys.lib (■hpt{-Zsys}).
  19552.     Under DOS, the _UF_PTRACE_MODEL settings are ignored.
  19553.  
  19554. ■seealso brk() sbrk() sigaction() signal() ptrace() ulimit() wait()
  19555.  
  19556.  
  19557. ■function _uheapchk()
  19558. ■compat VAC++
  19559. ■headers
  19560. #include <umalloc.h>
  19561. ■endheaders
  19562.  
  19563. ■param H
  19564. ■prototype
  19565. int _uheapchk (Heap_t H);
  19566. ■endprototype
  19567.  
  19568.     _uheapchk() checks the heap pointed to by H and all its blocks for
  19569.     consistency.  Note that _uheapchk() may crash if the heap is
  19570.     corrupted.  _uheapchk() can help debugging programs which
  19571.     experience heap problems.
  19572.  
  19573.     Use _heapchk() to check the default heap and the tiled default
  19574.     heap.
  19575.  
  19576. ■returnvalue
  19577.  
  19578.     _uheapchk() returns one of the following values:
  19579. ■description
  19580. ■item _HEAPBADBEGIN
  19581.     The heap is corrupted.
  19582. ■item _HEAPBADEND
  19583.     The heap is corrupted.
  19584. ■item _HEAPBADNODE
  19585.     A block of the heap is damaged or the heap is corrupted.
  19586. ■item _HEAPEMPTY
  19587.     The heap has not been initialized.
  19588. ■item _HEAPOK
  19589.     The heap seems to be consistent.
  19590. ■enddescription
  19591.  
  19592. ■seealso _heapchk() _uheapset() _uheap_walk()
  19593.  
  19594.  
  19595. ■function _uheapmin()
  19596. ■compat VAC++
  19597. ■headers
  19598. #include <umalloc.h>
  19599. ■endheaders
  19600.  
  19601. ■param H
  19602. ■prototype
  19603. int _uheapmin (Heap_t H);
  19604. ■endprototype
  19605.  
  19606.     The _uheapmin() function returns unused memory of the heap H to
  19607.     the operating system.  The heap is never made smaller than its
  19608.     initial size.  The function passed to the ■pa{RELEASE_FUN} argument
  19609.     (if not NULL) of ■hpt{_ucreate()} and ■hpt{_ucreate2()} is called
  19610.     to deallocate segments of the heap which don't contain any
  19611.     allocated blocks.  The function pased to the ■pa{SHRINK_FUN}
  19612.     argument (if not NULL) of _ucreate2() is called to shrink segments
  19613.     which have free space at the end (except for the initial memory
  19614.     area passed to _ucreate2()).
  19615.  
  19616.     You can use _heapmin() and _theapmin() to minimize the default
  19617.     regular heap and tiled default heap, respectively.
  19618.  
  19619. ■returnvalue
  19620. ■description
  19621. ■item 0
  19622.     success
  19623. ■item -1
  19624.     error
  19625. ■enddescription
  19626.  
  19627. ■seealso brk() _heapmin() _uheapchk() sbrk() _theapmin() _ucreate() _ucreate2() _ustats()
  19628.  
  19629.  
  19630. ■function _uheapset()
  19631. ■compat VAC++
  19632. ■headers
  19633. #include <umalloc.h>
  19634. ■endheaders
  19635.  
  19636. ■param H FILL
  19637. ■prototype
  19638. int _uheapset (Heap_t H, unsigned FILL);
  19639. ■endprototype
  19640.  
  19641.     _uheapset() fills all bytes of all unused blocks of the heap
  19642.     pointed to by H with FILL.  Note that _uheapset() may crash if the
  19643.     heap is corrupted.  _uheapset() can help debugging programs which
  19644.     erroneously depend on the contents of dynamically allocated
  19645.     blocks.  ■hpt{_uheapchk()} checks the heap more thoroughly than
  19646.     _heapset().
  19647.  
  19648.     Use _heapset() to fill the default heap and the tiled default
  19649.     heap.
  19650.  
  19651. ■returnvalue
  19652.  
  19653.     _uheapset() returns one of the following values:
  19654. ■description
  19655. ■item _HEAPBADBEGIN
  19656.     The heap is corrupted.
  19657. ■item _HEAPBADEND
  19658.     The heap is corrupted.
  19659. ■item _HEAPBADNODE
  19660.     A block of the heap is damaged or the heap is corrupted.
  19661. ■item _HEAPEMPTY
  19662.     The heap has not been initialized.
  19663. ■item _HEAPOK
  19664.     The heap seems to be consistent.
  19665. ■enddescription
  19666.  
  19667. ■seealso _heapset() _uheapchk() _uheap_walk()
  19668.  
  19669.  
  19670. ■function _uheap_type()
  19671. ■compat emx
  19672. ■headers
  19673. #include <umalloc.h>
  19674. ■endheaders
  19675.  
  19676. ■param H
  19677. ■prototype
  19678. unsigned _uheap_type (Heap_t H);
  19679. ■endprototype
  19680.  
  19681.     The _uheap_type() function returns the type of the heap H, as
  19682.     specified by the ■pa{TYPE} argument of ■hpt{_ucreate()} and
  19683.     ■hpt{_ucreate2()}.
  19684.  
  19685. ■returnvalue
  19686.  
  19687.     The _uheap_type() function returns a combination of the
  19688.     _HEAP_REGULAR, _HEAP_TILED, and _HEAP_SHARED values.
  19689.  
  19690. ■hints
  19691.  
  19692.     This function can be useful in allocation functions which are used
  19693.     for different heaps.
  19694.  
  19695. ■seealso _uaddmem() _ucreate() _ucreate2()
  19696.  
  19697.  
  19698. ■function _uheap_walk2()
  19699. ■compat emx
  19700. ■headers
  19701. #include <umalloc.h>
  19702. ■endheaders
  19703.  
  19704. ■param H CALLBACK ARG
  19705. ■param BLOCK SIZE FLAG STATUS FNAME LINENO
  19706. ■prototype
  19707. int _uheap_walk2 (Heap_t H,
  19708.                   int (*CALLBACK)(Heap_t, const void *, size_t, int, int,
  19709.                                   const char *, size_t, void *),
  19710.                   void *ARG);
  19711. ■endprototype
  19712.  
  19713.     Apply the function pointed to by CALLBACK to all free and used
  19714.     blocks of the heap H.  Note that the heap is locked, so using the
  19715.     heap in the callback function will cause a deadlock.  ARG will be
  19716.     passed on to the callback function.
  19717.  
  19718. ■indent
  19719.     ■tt{int my_walker (Heap_t }H■tt{, const void *}BLOCK■tt{, size_t }SIZE■tt{, int }FLAG■tt{,} ■break
  19720.     ■tt{               int }STATUS■tt{, const char *}FNAME■tt{, size_t }LINENO■tt{,} ■break
  19721.     ■tt{               void *}ARG■tt{);}
  19722. ■endindent
  19723.  
  19724.     H points to the heap being examined, it's the same value as passed
  19725.     to _uheap_walk2().  BLOCK points to a block of SIZE bytes.  FLAG
  19726.     is either _USEDENTRY (for a used block) or _FREEENTRY (for a free
  19727.     block).  STATUS is one of the following values, describing the
  19728.     status of the block:
  19729.  
  19730. ■description
  19731. ■item _HEAPBADBEGIN
  19732.     The heap is corrupted.
  19733. ■item _HEAPBADEND
  19734.     The heap is corrupted.
  19735. ■item _HEAPBADNODE
  19736.     The block is damaged.
  19737. ■item _HEAPEMPTY
  19738.     The heap has not been initialized.
  19739. ■item _HEAPOK
  19740.     The heap seems to be consistent (_HEAPOK is 0).
  19741. ■enddescription
  19742.  
  19743.     FNAME points to the file name of the source file in which the
  19744.     block has been allocated.  LINENO is the line number in which the
  19745.     block has been allocated.  FNAME is NULL if that information is
  19746.     not available, that is, if the object has not been allocated with
  19747.     a debugging heap function.  ARG is the same value as passed to
  19748.     _uheap_walk2().
  19749.  
  19750.  
  19751. ■returnvalue
  19752.  
  19753.     _uheap_walk2() returns the last status (see above for a list of
  19754.     values) unless the callback function returned a non-zero value.
  19755.     If the callback function returned a non-zero value, _uheap_walk2()
  19756.     returns that value.
  19757.  
  19758. ■restrictions
  19759.  
  19760.     FNAME is current always NULL as there are no debugging heap
  19761.     functions.
  19762.  
  19763. ■implementation
  19764.  
  19765.     If you need compatibility with VAC++, use _uheap_walk() instead of
  19766.     _uheap_walk2().
  19767.  
  19768. ■hints
  19769.  
  19770.     Use an extra heap if you want to allocate memory in the callback
  19771.     function.
  19772.  
  19773. ■seealso _heap_walk() _uheap_walk()
  19774.  
  19775.  
  19776. ■function ulimit()
  19777. ■compat UNIX
  19778. ■headers
  19779. #include <ulimit.h>
  19780. ■endheaders
  19781.  
  19782. ■param REQUEST
  19783. ■prototype
  19784. long ulimit (int REQUEST, ...);
  19785. ■endprototype
  19786.  
  19787.     Get or set process limits.  The following REQUEST codes are
  19788.     implemented:
  19789.  
  19790. ■description
  19791. ■item UL_GFILLIM
  19792.  
  19793.     Return the maximum file size.  Always returns ■tt{1 << 21}.
  19794.  
  19795. ■item UL_SFILLIM
  19796.  
  19797.     Set the maximum file size according to the second argument which
  19798.     is of type ■tt{int}.  Ignored.  Returns the second argument.
  19799.  
  19800. ■item UL_GMEMLIM
  19801.  
  19802.     Return the greatest possible break value.
  19803.  
  19804. ■item UL_NOFILES
  19805.  
  19806.     Return the number of files that can be open simultaneously per
  19807.     process.  Always returns 40.
  19808.  
  19809. ■item UL_OBJREST
  19810.  
  19811.     Return the number of bytes remaining in the current heap object.
  19812.     Let ■pa{N} be the return value of ■tt{ulimit(UL_OBJREST)}.  If
  19813.     allocation of non-contiguous memory is disabled, up to ■pa{N}
  19814.     bytes can be allocated with brk() or sbrk().  Attempts to allocate
  19815.     more than ■pa{N} bytes will fail.  If allocation of
  19816.     non-contiguous memory has been enabled with _uflags(), requests
  19817.     for up to ■pa{N} bytes will yield contiguous memory; calling
  19818.     sbrk() with an argument greater than ■pa{N} will create a new heap
  19819.     object, leaving a gap between the previous heap object and the new
  19820.     one.
  19821.  
  19822. ■enddescription
  19823.  
  19824. ■returnvalue
  19825.  
  19826.     See above.
  19827.  
  19828. ■implementation
  19829.  
  19830.     UL_GFILLIM and UL_NOFILES return dummy values.  UL_SFILLIM is
  19831.     ignored.  UL_OBJREST is an emx extension.
  19832.  
  19833. ■seealso brk() sbrk() _uflags()
  19834.  
  19835.  
  19836. ■function _umalloc()
  19837. ■compat VAC++
  19838. ■headers
  19839. #include <umalloc.h>
  19840. ■endheaders
  19841.  
  19842. ■param H SIZE
  19843. ■prototype
  19844. void *_umalloc (Heap_t H, size_t SIZE);
  19845. ■endprototype
  19846.  
  19847.     Allocate from the heap H a block of memory big enough for holding
  19848.     SIZE bytes.  If there is an error, _umalloc() returns NULL.  If
  19849.     SIZE is 0, zero bytes of memory are allocated, the return value
  19850.     will be unequal NULL.
  19851.  
  19852. ■returnvalue
  19853.  
  19854.     _umalloc() returns a pointer to a newly allocated block of memory.
  19855.     On error, _umalloc() returns NULL.
  19856.  
  19857. ■implementation
  19858.  
  19859.     ■tt{_umalloc(0)} returns a non-NULL pointer if there's enough
  19860.     space left in the heap for a block of the minimum size.
  19861.  
  19862. ■seealso free() malloc() _msize() realloc() _ucalloc() _utmalloc()
  19863.  
  19864.  
  19865. ■function umask()
  19866. ■compat UNIX
  19867. ■headers
  19868. #include <io.h>
  19869. ■endheaders
  19870.  
  19871. ■param PMODE
  19872. ■prototype
  19873. int umask (int PMODE);
  19874. ■endprototype
  19875.  
  19876.     Set the file-permission mask of the current process to PMODE.
  19877.     Only the S_IWRITE bit is used.  Either specify
  19878.     ■tt{S_IREAD|S_IWRITE} or ■tt{S_IREAD} for PMODE.
  19879.  
  19880. ■returnvalue
  19881.  
  19882.     umask() returns the previous file-permission mask.
  19883.  
  19884. ■restrictions
  19885.  
  19886.     The current file-permission mask is inherited by emx programs
  19887.     spawned under DOS.  Under OS/2, the file-permission mask is not
  19888.     yet inherited.  When spawning a non-emx program (such as
  19889.     command.com, see ■hpt{system()}) which spawns an emx program, that
  19890.     program won't inherit the file-permission mask.
  19891.  
  19892. ■seealso fopen() open()
  19893.  
  19894.  
  19895. ■function uname()
  19896. ■compat UNIX
  19897. ■headers
  19898. #include <sys/utsname.h>
  19899. ■endheaders
  19900.  
  19901. ■param NAME
  19902. ■prototype
  19903. int uname (struct utsname *NAME);
  19904. ■endprototype
  19905.  
  19906.     Store information identifying the current system to the structure
  19907.     pointed to by NAME.
  19908.  
  19909. ■returnvalue
  19910.  
  19911.     uname() always returns 0 (always successful).
  19912.  
  19913. ■function ungetc()
  19914. ■compat C90
  19915. ■headers
  19916. #include <stdio.h>
  19917. ■endheaders
  19918.  
  19919. ■param C STREAM
  19920. ■prototype
  19921. int ungetc (int C, FILE *STREAM);
  19922. ■endprototype
  19923.  
  19924.     Push back the character C onto STREAM and clear the end-of-file
  19925.     indicator.  STREAM must be open for reading.  The next read
  19926.     operation on STREAM starts with C.  If C is EOF, nothing is done.
  19927.     Only one character can be pushed onto a stream.  fflush(),
  19928.     fseek(), fsetpos() and rewind() undo ungetc().  After a successful
  19929.     ungetc(), the value of the file pointer is undefined until the
  19930.     character has been read.
  19931.  
  19932. ■returnvalue
  19933.  
  19934.     On success, ungetc() returns the character C.  On failure,
  19935.     ungetc() returns EOF.
  19936.  
  19937. ■seealso fgetc() fflush()
  19938.  
  19939.  
  19940. ■function unlink()
  19941. ■compat UNIX
  19942.  
  19943. ■headers
  19944. #include <unistd.h>     /* use this */
  19945. #include <io.h>         /* or this */
  19946. ■endheaders
  19947.  
  19948. ■param NAME
  19949. ■prototype
  19950. int unlink (const char *NAME);
  19951. ■endprototype
  19952.  
  19953.     Delete a file.  NAME is a pointer to a string containing the name
  19954.     of the file to be deleted.  Under OS/2 and DOS, unlink() and
  19955.     remove() are equivalent.
  19956.  
  19957. ■returnvalue
  19958. ■description
  19959. ■item 0
  19960.     success
  19961. ■item -1
  19962.     error
  19963. ■enddescription
  19964.  
  19965. ■implementation
  19966.  
  19967.     If the read-only attribute of the file is set, unlink() sets errno
  19968.     to EPERM and returns -1.
  19969.  
  19970.     If the file is open in any process, unlink() sets errno to EACCES
  19971.     and returns -1.
  19972.  
  19973. ■seealso remove()
  19974.  
  19975.  
  19976. ■function _uopen()
  19977. ■compat VAC++
  19978. ■headers
  19979. #include <umalloc.h>
  19980. ■endheaders
  19981.  
  19982. ■param H
  19983. ■prototype
  19984. int _uopen (Heap_t H);
  19985. ■endprototype
  19986.  
  19987.     Open the heap H.  Before a heap created with _ucreate() or
  19988.     _ucreate2() can be used, it must be opened.  A shared heap must be
  19989.     opened by all processes which want to access the heap.  All
  19990.     attempts to access a heap before it has been opened will invoke
  19991.     undefined behavior.
  19992.  
  19993.     _uopen() fails if H is the runtime heap (_RUNTIME_HEAP) or the
  19994.     tiled runtime heap.
  19995.  
  19996. ■returnvalue
  19997. ■description
  19998. ■item 0
  19999.     success
  20000. ■item -1
  20001.     error
  20002. ■enddescription
  20003.  
  20004. ■seealso _uclose() _ucreate() _ucreate2()
  20005.  
  20006.  
  20007. ■function _ustats()
  20008. ■compat VAC++
  20009. ■headers
  20010. #include <umalloc.h>
  20011. ■endheaders
  20012.  
  20013. ■param H PSTATS
  20014. ■prototype
  20015. int _ustats (Heap_t H, _HEAPSTATS *PSTATS);
  20016. ■endprototype
  20017.  
  20018.     _ustats() computes statistics on the heap pointed to by H and fills
  20019.     in the structure pointed to by PSTATS.  The structure has the
  20020.     following members:
  20021.  
  20022. ■description
  20023. ■item ■tt{_provided}
  20024.     Total number of bytes provided by the heap, including used and
  20025.     free blocks, excluding overhead for control structures
  20026. ■item ■tt{_used}
  20027.     Total number of bytes in used blocks
  20028. ■item ■tt{_tiled}
  20029.     1 if the heap is tiled (_HEAP_TILED), 0 if the heap is not tiled
  20030. ■item ■tt{_shared}
  20031.     1 if the heap is shared (_HEAP_SHARED), 0 if the heap is not shared
  20032. ■item ■tt{_max_free}
  20033.     Number of bytes in the biggest free block
  20034. ■item ■tt{_segments}
  20035.     Number of segments
  20036. ■item ■tt{_crates}
  20037.     Number of blocks allocated internally for allocation of small user
  20038.     blocks
  20039. ■enddescription
  20040.  
  20041. ■returnvalue
  20042.  
  20043.     _ustats() returns 0 if successful.  _ustats() returns a non-zero
  20044.     value on error.
  20045.  
  20046. ■implementation
  20047.  
  20048.     The ■tt{_segments} and ■tt{_crates} members are an emx extension.
  20049.  
  20050. ■hints
  20051.  
  20052.     Use ■hpt{_udefault()} to obtain a pointer to the default heap if
  20053.     you want to apply _ustats() to the default heap.
  20054.  
  20055. ■seealso _uaddmem() _udefault() _uheapmin() _uheap_walk()
  20056.  
  20057.  
  20058. ■function _utcalloc()
  20059. ■compat emx
  20060. ■headers
  20061. #include <umalloc.h>
  20062. ■endheaders
  20063.  
  20064. ■param H ELEMENTS SIZE
  20065. ■prototype
  20066. void *_utcalloc (Heap_t H, size_t ELEMENTS, size_t SIZE);
  20067. ■endprototype
  20068.  
  20069.     Allocate from the heap pointed to by H a block of memory big
  20070.     enough for holding ELEMENTS elements of SIZE bytes each.  The
  20071.     block will not cross a 64 KByte boundary unless SIZE is greater
  20072.     than 65536.  If SIZE is greater than 65536, the block will be
  20073.     aligned on a 64 KByte boundary.  _utcalloc() fills the block with
  20074.     zeros.  If there is an error, _utcalloc() returns NULL.
  20075.  
  20076. ■returnvalue
  20077.  
  20078.     _utcalloc() returns a pointer to a newly allocated block of
  20079.     memory.  On error, _utcalloc() returns NULL.
  20080.  
  20081. ■seealso calloc() free() realloc() _tcalloc() _utmalloc()
  20082.  
  20083.  
  20084. ■function _utdefault()
  20085. ■compat emx
  20086. ■headers
  20087. #include <umalloc.h>
  20088. ■endheaders
  20089.  
  20090. ■param H
  20091. ■prototype
  20092. Heap_t _utdefault (Heap_t H);
  20093. ■endprototype
  20094.  
  20095.     The _utdefault() function selects the heap pointed to by H as the
  20096.     tiled default heap of the current thread unless H is NULL.  All
  20097.     tiled memory allocation functions such as _tmalloc() which don't
  20098.     take a pointer to a heap will use the heap pointed to by H if
  20099.     called in the same thread.  If H is NULL, _utdefault() won't set
  20100.     the tiled default heap.
  20101.  
  20102.     Initially, the tiled runtime heap is used as tiled default heap
  20103.     for all threads.
  20104.  
  20105. ■returnvalue
  20106.  
  20107.     _utdefault() returns a pointer to the previous tiled default heap
  20108.     of the current thread.  If the tiled default heap has not yet been
  20109.     created, _utdefault() will return NULL.
  20110.  
  20111. ■hints
  20112.  
  20113.     To obtain a pointer to the tiled default heap of the current
  20114.     thread without selecting a new heap, call ■tt{_utdefault(NULL)}.
  20115.  
  20116. ■seealso _mheap() _ucreate() _ucreate2() _udefault()
  20117.  
  20118.  
  20119. ■function utime()
  20120. ■compat SysV
  20121. ■headers
  20122. #include <utime.h>
  20123. ■endheaders
  20124.  
  20125. ■param NAME TIMES
  20126. ■prototype
  20127. int utime (const char *NAME, const struct utimbuf *TIMES);
  20128. ■endprototype
  20129.  
  20130.     Set the time stamp of a file to the access time and modification
  20131.     time in the structure pointed to by TIMES.  NAME points to a
  20132.     string containing the name of the file.  If TIMES is NULL, both
  20133.     the access time and the modification time are set to the current
  20134.     time.
  20135.  
  20136.     The ■tt{utimbuf} structure is defined as follows:
  20137.  
  20138. ■example
  20139. struct utimbuf
  20140. {
  20141.   time_t actime;
  20142.   time_t modtime;
  20143. };
  20144. ■endexample
  20145.  
  20146.     ■tt{actime} is the time of the last access, ■tt{modtime} is the
  20147.     time of the last modification.
  20148.  
  20149. ■returnvalue
  20150. ■description
  20151. ■item 0
  20152.     success
  20153. ■item -1
  20154.     error
  20155. ■enddescription
  20156.  
  20157. ■seealso stat() utimes()
  20158.  
  20159.  
  20160. ■function utimes()
  20161. ■compat BSD
  20162. ■headers
  20163. #include <sys/time.h>
  20164. ■endheaders
  20165.  
  20166. ■param NAME TVP
  20167. ■prototype
  20168. int utimes (const char *NAME, const struct timeval *TVP);
  20169. ■endprototype
  20170.  
  20171.     Set the time stamp of a file to the access time in
  20172.     ■pa{TVP}■tt{[0]} and the modification time in ■pa{TVP}■tt{[1]}.
  20173.     NAME points to a string containing the file name.  If TVP is NULL,
  20174.     both the access time and the modification time are set to the
  20175.     current time.
  20176.  
  20177.     The ■tt{timeval} structure is defined as follows:
  20178.  
  20179. ■example
  20180. struct timeval
  20181. {
  20182.   long tv_sec;
  20183.   long tv_usec;
  20184. };
  20185. ■endexample
  20186.  
  20187.     ■tt{tv_sec} and ■tt{tv_usec} are the number of seconds and
  20188.     microseconds, respectively, elapsed since 00:00:00 1-Jan-1970 UTC.
  20189.  
  20190. ■returnvalue
  20191. ■description
  20192. ■item 0
  20193.     success
  20194. ■item -1
  20195.     error
  20196. ■enddescription
  20197. ■seealso stat() utime()
  20198.  
  20199.  
  20200. ■function _utmalloc()
  20201. ■compat emx
  20202. ■headers
  20203. #include <umalloc.h>
  20204. ■endheaders
  20205.  
  20206. ■param H SIZE
  20207. ■prototype
  20208. void *_utmalloc (Heap_t H, size_t SIZE);
  20209. ■endprototype
  20210.  
  20211.     Allocate from the heap pointed to by H a block of memory big
  20212.     enough for holding SIZE bytes.  The block will not cross a 64
  20213.     KByte boundary unless SIZE is greater than 65536.  If SIZE is
  20214.     greater than 65536, the block will be aligned on a 64 KByte
  20215.     boundary.  Therefore, blocks allocated with _utmalloc() can be
  20216.     used with 16-bit functions.  If there is an error, _utmalloc()
  20217.     returns NULL.  If SIZE is 0, zero bytes of memory are allocated,
  20218.     the return value will be unequal NULL.  Use free() to deallocate a
  20219.     block of memory allocated by _utmalloc().
  20220.  
  20221.     As _utmalloc() causes additional heap fragmentation, you should
  20222.     not use _utmalloc() unless you need an aligned block.
  20223.  
  20224. ■returnvalue
  20225.  
  20226.     _utmalloc() returns a pointer to a newly allocated block of
  20227.     memory.  On error, _utmalloc() returns NULL.
  20228.  
  20229. ■seealso free() realloc() _tmalloc() _umalloc() _utcalloc()
  20230.  
  20231.  
  20232. ■function v_attrib()
  20233. ■compat emx
  20234. ■headers
  20235. #include <sys/video.h>
  20236. ■endheaders
  20237.  
  20238. ■param A
  20239. ■prototype
  20240. void v_attrib (int A);
  20241. ■endprototype
  20242.  
  20243.     Set the attributes (colors etc.) used by video library functions
  20244.     to A.  You can make A by using the binary OR operator and the
  20245.     ■tt{F_}■sl{whatever}, ■tt{B_}■sl{whatever}, INTENSITY and BLINK
  20246.     constants.
  20247.  
  20248. ■seealso v_init() v_putc()
  20249.  
  20250.  
  20251. ■function v_backsp()
  20252. ■compat emx
  20253. ■headers
  20254. #include <sys/video.h>
  20255. ■endheaders
  20256.  
  20257. ■param COUNT
  20258. ■prototype
  20259. void v_backsp (int COUNT);
  20260. ■endprototype
  20261.  
  20262.     Backspace the cursor.  The cursor is moved left by COUNT
  20263.     characters.  If the cursor leaves the screen at the left edge, it
  20264.     is moved to the end of the previous line.  The cursor cannot leave
  20265.     the screen at the top edge.
  20266.  
  20267. ■seealso v_putc()
  20268.  
  20269.  
  20270. ■function v_clear()
  20271. ■compat emx
  20272. ■headers
  20273. #include <sys/video.h>
  20274. ■endheaders
  20275.  
  20276. ■prototype
  20277. void v_clear (void);
  20278. ■endprototype
  20279.  
  20280.     Clear the screen using the current attributes.
  20281.  
  20282. ■seealso v_attrib() v_clreol()
  20283.  
  20284.  
  20285. ■function v_clreol()
  20286. ■compat emx
  20287. ■headers
  20288. #include <sys/video.h>
  20289. ■endheaders
  20290.  
  20291. ■prototype
  20292. void v_clreol (void);
  20293. ■endprototype
  20294.  
  20295.     Clear the line from the current cursor position to the end of the
  20296.     current line using the current attributes.
  20297.  
  20298. ■seealso v_attrib() v_clear()
  20299.  
  20300.  
  20301. ■function v_ctype()
  20302. ■compat emx
  20303. ■headers
  20304. #include <sys/video.h>
  20305. ■endheaders
  20306.  
  20307. ■param START END
  20308. ■prototype
  20309. void v_ctype (int START, int END);
  20310. ■endprototype
  20311.  
  20312.     Set the cursor type.  START is the first row of the cursor, END is
  20313.     the last row of the cursor.  Both values are zero-based. Use
  20314.     v_hardware() to determine the size of the character box.
  20315.  
  20316.     Note that cmd.exe resets the cursor type.
  20317.  
  20318. ■seealso v_getctype() v_hardware() v_hidecursor()
  20319.  
  20320.  
  20321. ■function v_delline()
  20322. ■compat emx
  20323. ■headers
  20324. #include <sys/video.h>
  20325. ■endheaders
  20326.  
  20327. ■param COUNT
  20328. ■prototype
  20329. void v_delline (int COUNT);
  20330. ■endprototype
  20331.  
  20332.     Delete COUNT lines at the current cursor position by moving up the
  20333.     lines below the current line.  The current attributes are used for
  20334.     filling lines becoming empty at the bottom of the screen.
  20335.  
  20336. ■seealso v_attrib() v_insline() v_scroll()
  20337.  
  20338.  
  20339. ■function v_dimen()
  20340. ■compat emx
  20341. ■headers
  20342. #include <sys/video.h>
  20343. ■endheaders
  20344.  
  20345. ■param WIDTH HEIGHT
  20346. ■prototype
  20347. void v_dimen (int *WIDTH, int *HEIGHT);
  20348. ■endprototype
  20349.  
  20350.     Store the screen width (columns) to WIDTH, the screen height
  20351.     (lines) to HEIGHT.
  20352.  
  20353. ■seealso _scrsize()
  20354.  
  20355.  
  20356. ■function v_fclose()
  20357. ■compat emx
  20358. ■headers
  20359. #include <stdio.h>
  20360. #include <sys/video.h>
  20361. ■endheaders
  20362.  
  20363. ■param STREAM
  20364. ■prototype
  20365. int v_fclose (FILE *STREAM);
  20366. ■endprototype
  20367.  
  20368.     Close a video file created by v_fopen().
  20369.  
  20370. ■returnvalue
  20371. ■description
  20372. ■item 0
  20373.     success
  20374. ■item -1
  20375.     error
  20376. ■enddescription
  20377.  
  20378. ■seealso v_fopen()
  20379.  
  20380.  
  20381. ■function v_fopen()
  20382. ■compat emx
  20383. ■headers
  20384. #include <stdio.h>
  20385. #include <sys/video.h>
  20386. ■endheaders
  20387.  
  20388. ■prototype
  20389. FILE *v_fopen (void);
  20390. ■endprototype
  20391.  
  20392.     Open a video file.  All output to a video file goes to the screen,
  20393.     using video library functions such as v_puts().  The stream
  20394.     returned by v_fopen() can be used with fprintf(), fputc() and
  20395.     fwrite().  On error, v_fopen() returns NULL.  Do not use fclose()
  20396.     on a stream created by v_fopen(), use v_fclose() instead.  Do not
  20397.     read from a stream created by v_fopen().
  20398.  
  20399. ■returnvalue
  20400.  
  20401.     See above.
  20402.  
  20403. ■seealso _fassign() fopen() v_fclose() v_printf()
  20404.  
  20405. ■samplefile /emx/test/vftest.c
  20406.  
  20407.  
  20408. ■function v_getattr()
  20409. ■compat emx
  20410. ■headers
  20411. #include <sys/video.h>
  20412. ■endheaders
  20413.  
  20414. ■prototype
  20415. int v_getattr (void);
  20416. ■endprototype
  20417.  
  20418.     Return the current attributes.
  20419.  
  20420. ■returnvalue
  20421.  
  20422.     See above.
  20423.  
  20424. ■seealso v_attrib()
  20425.  
  20426.  
  20427. ■function v_getctype()
  20428. ■compat emx
  20429. ■headers
  20430. #include <sys/video.h>
  20431. ■endheaders
  20432.  
  20433. ■param START END
  20434. ■prototype
  20435. void v_getctype (int *START, int *END);
  20436. ■endprototype
  20437.  
  20438.     Store the current cursor start and end rows to START and END.
  20439.  
  20440. ■seealso v_ctype()
  20441.  
  20442.  
  20443. ■function v_getline()
  20444. ■compat emx
  20445. ■headers
  20446. #include <sys/video.h>
  20447. ■endheaders
  20448.  
  20449. ■param DST X Y COUNT
  20450. ■prototype
  20451. void v_getline (char *DST, int X, int Y, int COUNT);
  20452. ■endprototype
  20453.  
  20454.     Copy COUNT character/attributes pairs from the screen at position
  20455.     (X,Y) to the array pointed to by DST.  2*■pa{COUNT} bytes are
  20456.     copied.  The cursor is not moved.
  20457.  
  20458. ■seealso v_putline()
  20459.  
  20460.  
  20461. ■function v_getxy()
  20462. ■compat emx
  20463. ■headers
  20464. #include <sys/video.h>
  20465. ■endheaders
  20466.  
  20467. ■param X Y
  20468. ■prototype
  20469. void v_getxy (int *X, int *Y);
  20470. ■endprototype
  20471.  
  20472.     Store the current cursor position to X (column) and Y (line).
  20473.  
  20474. ■seealso v_gotoxy()
  20475.  
  20476.  
  20477. ■function v_gotoxy()
  20478. ■compat emx
  20479. ■headers
  20480. #include <sys/video.h>
  20481. ■endheaders
  20482.  
  20483. ■param X Y
  20484. ■prototype
  20485. void v_gotoxy (int X, int Y);
  20486. ■endprototype
  20487.  
  20488.     Move the cursor to line Y, column X.  Both values are zero-based.
  20489.     Line 0 is the top line, column 0 is the left-most column.
  20490.  
  20491. ■seealso v_getxy()
  20492.  
  20493.  
  20494. ■function v_hardware()
  20495. ■compat emx
  20496. ■headers
  20497. #include <sys/video.h>
  20498. ■endheaders
  20499.  
  20500. ■prototype
  20501. int v_hardware (void);
  20502. ■endprototype
  20503.  
  20504.     Get the display adapter type.
  20505.  
  20506. ■returnvalue
  20507.  
  20508. ■description
  20509.  
  20510. ■item V_MONOCHROME
  20511.  
  20512.     Monochrome display adapter
  20513.  
  20514. ■item V_COLOR_8
  20515.  
  20516.     Color display adapter, the character box height is 8 scan lines
  20517.  
  20518. ■item V_COLOR_12
  20519.  
  20520.     Color display adapter, the character box height is 12 scan lines
  20521.  
  20522. ■enddescription
  20523.  
  20524. ■seealso v_ctype()
  20525.  
  20526.  
  20527. ■function v_hidecursor()
  20528. ■compat emx
  20529. ■headers
  20530. #include <sys/video.h>
  20531. ■endheaders
  20532.  
  20533. ■prototype
  20534. void v_hidecursor (void);
  20535. ■endprototype
  20536.  
  20537.     Turn off the cursor.  Use v_ctype() to turn the cursor on.
  20538.  
  20539. ■seealso v_ctype()
  20540.  
  20541.  
  20542. ■function v_init()
  20543. ■compat emx
  20544. ■headers
  20545. #include <sys/video.h>
  20546. ■endheaders
  20547.  
  20548. ■prototype
  20549. int v_init (void);
  20550. ■endprototype
  20551.  
  20552.     Initialize video library.  You must call this function before
  20553.     calling any other video library function.  The attributes are set
  20554.     to ■tt{F_WHITE|B_BLACK}.
  20555.  
  20556.     General information about the video library: The video library
  20557.     implements text-mode output to the screen.  You have to link with
  20558.     -lvideo.  Under DOS, emx option -acm is required, see `■hpt{Using
  20559.     emx options}'.  See ■hpt{wm_init()} for a higher-level interface.
  20560.  
  20561. ■returnvalue
  20562.  
  20563.     v_init() always returns 1.
  20564.  
  20565. ■seealso v_attrib()
  20566.  
  20567. ■samplefile /emx/test/video.c
  20568.  
  20569.  
  20570. ■function v_insline()
  20571. ■compat emx
  20572. ■headers
  20573. #include <sys/video.h>
  20574. ■endheaders
  20575.  
  20576. ■param COUNT
  20577. ■prototype
  20578. void v_insline (int COUNT);
  20579. ■endprototype
  20580.  
  20581.     Insert COUNT empty lines at the current cursor position by moving
  20582.     down the line at the current cursor position and all lines below
  20583.     that line.  The current attributes are used for filling the empty
  20584.     lines.
  20585.  
  20586. ■seealso v_attrib() v_delline() v_scroll()
  20587.  
  20588.  
  20589. ■function v_printf()
  20590. ■compat emx
  20591. ■headers
  20592. #include <sys/video.h>
  20593. ■endheaders
  20594.  
  20595. ■param FMT
  20596. ■prototype
  20597. int v_printf (const char *FMT, ...);
  20598. ■endprototype
  20599.  
  20600.     Formatted output to the screen at the current cursor position.
  20601.     The cursor is moved.  See ■hpt{printf()} for details on the format
  20602.     string pointed to by FMT.
  20603.  
  20604. ■returnvalue
  20605.  
  20606.     v_printf() returns the number of output characters.
  20607.  
  20608. ■seealso v_attrib() v_fopen() v_putc() v_puts() v_vprintf()
  20609.  
  20610.  
  20611. ■function v_putc()
  20612. ■compat emx
  20613. ■headers
  20614. #include <sys/video.h>
  20615. ■endheaders
  20616.  
  20617. ■param C
  20618. ■prototype
  20619. void v_putc (char C);
  20620. ■endprototype
  20621.  
  20622.     Display character C on the screen at the current cursor position,
  20623.     using the current attributes.  The cursor is moved.  If the cursor
  20624.     leaves the screen at the right edge, it will be moved to the start
  20625.     of the next line.  If C is ■tt{'\n'}, the cursor is moved to the
  20626.     start of the next line.  If the cursor leaves the screen at the
  20627.     bottom edge, the screen is scrolled up.
  20628.  
  20629. ■seealso v_attrib() v_puts() v_scrollup()
  20630.  
  20631.  
  20632. ■function v_putline()
  20633. ■compat emx
  20634. ■headers
  20635. #include <sys/video.h>
  20636. ■endheaders
  20637.  
  20638. ■param SRC X Y COUNT
  20639. ■prototype
  20640. void v_putline (const char *SRC, int X, int Y, int COUNT);
  20641. ■endprototype
  20642.  
  20643.     Copy COUNT character/attributes pairs from the array pointed to by
  20644.     SRC to the screen at position (X,Y).  2*■pa{COUNT} bytes are
  20645.     copied.  The cursor is not moved.
  20646.  
  20647. ■seealso v_getline() v_putmask() v_putn()
  20648.  
  20649.  
  20650. ■function v_putm()
  20651. ■compat emx
  20652. ■headers
  20653. #include <sys/video.h>
  20654. ■endheaders
  20655.  
  20656. ■param STR LEN
  20657. ■prototype
  20658. void v_putm (const char *STR, int LEN);
  20659. ■endprototype
  20660.  
  20661.     Display LEN characters of the string pointed to by STR at the
  20662.     current cursor position using the current attributes.  The cursor
  20663.     is not moved.
  20664.  
  20665. ■seealso v_putline() v_putn() v_puts()
  20666.  
  20667.  
  20668. ■function v_putmask()
  20669. ■compat emx
  20670. ■headers
  20671. #include <sys/video.h>
  20672. ■endheaders
  20673.  
  20674. ■param SRC MASK X Y COUNT
  20675. ■prototype
  20676. void v_putmask (const char *SRC, const char *MASK, int X, int Y, int COUNT);
  20677. ■endprototype
  20678.  
  20679.     Copy COUNT character/attributes pairs from the array pointed to by
  20680.     SRC to the screen.  A character/attributes pair at
  20681.     ■pa{SRC}■tt{[2*i]} and ■pa{SRC}■tt{[2*i+1]}, is copied only if
  20682.     ■pa{MASK}■tt{[i]} is non-zero.  The cursor is not moved.
  20683.  
  20684. ■seealso v_putline()
  20685.  
  20686.  
  20687. ■function v_putn()
  20688. ■compat emx
  20689. ■headers
  20690. #include <sys/video.h>
  20691. ■endheaders
  20692.  
  20693. ■param C COUNT
  20694. ■prototype
  20695. void v_putn (char C, int COUNT);
  20696. ■endprototype
  20697.  
  20698.     Display character C at the current cursor position using the
  20699.     current attributes.  COUNT is the number of times to display the
  20700.     character.  The cursor is not moved.
  20701.  
  20702. ■seealso v_attrib() v_putc()
  20703.  
  20704.  
  20705. ■function v_puts()
  20706. ■compat emx
  20707. ■headers
  20708. #include <sys/video.h>
  20709. ■endheaders
  20710.  
  20711. ■param STR
  20712. ■prototype
  20713. void v_puts (const char *STR);
  20714. ■endprototype
  20715.  
  20716.     Display the string pointed to by STR at the current cursor
  20717.     position using the current attributes.  The ■tt{'\n'} character
  20718.     moves the cursor to the start of the next line.  Scrolling is
  20719.     performed when the cursor leaves the screen at the bottom edge.
  20720.  
  20721. ■seealso v_attrib() v_printf() v_putc() v_putm()
  20722.  
  20723.  
  20724. ■function v_scroll()
  20725. ■compat emx
  20726. ■headers
  20727. #include <sys/video.h>
  20728. ■endheaders
  20729.  
  20730. ■param TL_X TL_Y BR_X BR_Y COUNT FLAG
  20731. ■prototype
  20732. void v_scroll (int TL_X, int TL_Y, int BR_X, int BR_Y, int COUNT, int FLAG);
  20733. ■endprototype
  20734.  
  20735.     Scroll a rectangle of the screen by COUNT lines.  The top left
  20736.     character cell is at (TL_X,TL_Y), the bottom right character cell
  20737.     is at (BR_X,BR_Y).  If FLAG is V_SCROLL_UP, the rectangle is
  20738.     scrolled up, if FLAG is V_SCROLL_DOWN, the rectangle is scrolled
  20739.     down.  If FLAG is V_SCROLL_CLEAR, the rectangle is filled with
  20740.     blanks.  Lines becoming empty are filled with blanks using the
  20741.     current attributes.
  20742.  
  20743. ■seealso v_attrib() v_scrollup()
  20744.  
  20745.  
  20746. ■function v_scrollup()
  20747. ■compat emx
  20748. ■headers
  20749. #include <sys/video.h>
  20750. ■endheaders
  20751.  
  20752. ■prototype
  20753. void v_scrollup (void);
  20754. ■endprototype
  20755.  
  20756.     Scroll screen up by one line.  The bottom line is filled with
  20757.     blanks, using the current attributes.
  20758.  
  20759. ■seealso v_attrib() v_putc()
  20760.  
  20761.  
  20762. ■function v_vprintf()
  20763. ■compat emx
  20764. ■headers
  20765. #include <sys/video.h>
  20766. ■endheaders
  20767.  
  20768. ■param FMT ARG_PTR
  20769. ■prototype
  20770. int v_vprintf (const char *FMT, va_list ARG_PTR);
  20771. ■endprototype
  20772.  
  20773.     Formatted output to the screen.  Instead of a list of arguments,
  20774.     this function takes a pointer to the list of arguments.  See
  20775.     v_printf() for details.
  20776.  
  20777. ■returnvalue
  20778.  
  20779.     v_vprintf() returns the number of output characters.
  20780.  
  20781. ■seealso v_printf() va_arg()
  20782.  
  20783.  
  20784. ■function va_arg() va_end() va_start()
  20785. ■compat C90
  20786. ■headers
  20787. #include <stdarg.h>
  20788. ■endheaders
  20789.  
  20790. ■param ARG_PTR TYPE PREV_ARG
  20791. ■prototype
  20792. type va_arg (va_list ARG_PTR, TYPE);
  20793. void va_end (va_list ARG_PTR);
  20794. void va_start (va_list ARG_PTR, TYPE PREV_ARG);
  20795. ■endprototype
  20796.  
  20797.     Access arguments of a function with variable number of arguments.
  20798.     You have to declare a variable of type va_list, for instance
  20799.     ARG_PTR.  Use
  20800.  
  20801. ■typewriter
  20802.   va_start (ARG_PTR, PREV_ARG)
  20803. ■endtypewriter
  20804.  
  20805.     where PREV_ARG is the argument preceding the variable arguments,
  20806.     to initialize ARG_PTR.  Use
  20807.  
  20808. ■typewriter
  20809.   va_arg (ARG_PTR, TYPE)
  20810. ■endtypewriter
  20811.  
  20812.     to get the next argument, which is of type TYPE.  Use
  20813.  
  20814. ■typewriter
  20815.   va_end (ARG_PTR)
  20816. ■endtypewriter
  20817.  
  20818.     when you no longer need ARG_PTR.
  20819.  
  20820. ■returnvalue
  20821.  
  20822.     See above.
  20823.  
  20824. ■restrictions
  20825.  
  20826.     PREV_ARG must not be declared ■tt{register}, must not be of
  20827.     function or array type, and the type must be compatible to the
  20828.     type that results from promotion.  For instance, PREV_ARG must not
  20829.     be of type ■tt{char} or ■tt{float}.
  20830.  
  20831.     TYPE must be compatible to the type that results from promotion.
  20832.     For instance, TYPE must not be ■tt{unsigned char} or ■tt{float}
  20833.     (instead, use ■tt{unsigned int} and ■tt{double}, respectively).
  20834.  
  20835. ■seealso vprintf()
  20836.  
  20837. ■samplefile /emx/samples/stdarg.c
  20838.  
  20839.  
  20840. ■function vprintf() vfprintf() vsprintf()
  20841. ■compat C90
  20842. ■headers
  20843. #include <stdio.h>
  20844. ■endheaders
  20845.  
  20846. ■param FORMAT ARG_PTR STREAM BUFFER
  20847. ■prototype
  20848. int vprintf (const char *FORMAT, va_list ARG_PTR);
  20849. int vfprintf (FILE *STREAM, const char *FORMAT, va_list ARG_PTR);
  20850. int vsprintf (char *BUFFER, const char *FORMAT, va_list ARG_PTR);
  20851. ■endprototype
  20852.  
  20853.     Formatted output to stdout, to the stream STREAM or to the string
  20854.     pointed to by BUFFER, respectively.  Instead of a list of
  20855.     arguments, these functions take a pointer to the list of
  20856.     arguments.  See ■hpt{printf()} for details.
  20857.  
  20858. ■returnvalue
  20859.  
  20860.     vprintf(), vfprintf() and vsprintf() return the number of
  20861.     output characters.  On error, these functions return EOF.
  20862.  
  20863. ■seealso printf() va_arg() vsnprintf()
  20864.  
  20865.  
  20866. ■function vscanf() vfscanf() vsscanf()
  20867. ■compat emx
  20868. ■headers
  20869. #include <stdio.h>
  20870. ■endheaders
  20871.  
  20872. ■param FORMAT ARG_PTR STREAM BUFFER
  20873. ■prototype
  20874. int vscanf (const char *FORMAT, va_list ARG_PTR);
  20875. int vfscanf (FILE *STREAM, const char *FORMAT, va_list ARG_PTR);
  20876. int vsscanf (const char *BUFFER, const char *FORMAT, va_list ARG_PTR);
  20877. ■endprototype
  20878.  
  20879.     Parse input from stdin, STREAM or the string pointed to by BUFFER,
  20880.     respectively.  Instead of a list of arguments, these functions
  20881.     take a pointer to the list of arguments.  See ■hpt{scanf()} for
  20882.     details.
  20883.  
  20884. ■returnvalue
  20885.  
  20886.     If successful, vscanf(), vfscanf() and vsscanf() return the number
  20887.     of fields converted.  On error, these functions return EOF.
  20888.  
  20889. ■seealso scanf() va_arg()
  20890.  
  20891.  
  20892. ■function vsnprintf()
  20893. ■compat BSD
  20894. ■headers
  20895. #include <stdio.h>
  20896. ■endheaders
  20897.  
  20898. ■param BUFFER N FORMAT ARG_PTR
  20899. ■prototype
  20900. int vsnprintf (char *BUFFER, size_t N, const char *FORMAT, va_list ARG_PTR);
  20901. ■endprototype
  20902.  
  20903.     Formatted output to the string pointed to by BUFFER.  If N is
  20904.     zero, BUFFER may be NULL and nothing is written.  Otherwise, up to
  20905.     ■pa{N}-1 characters and a terminating null character will be
  20906.     written to BUFFER.  If formatting yields more than ■pa{N}-1
  20907.     characters, output will be truncated.  The terminating null
  20908.     character will be put into BUFFER even if output is truncated.
  20909.  
  20910.     Instead of a list of arguments, this function takes a pointer to
  20911.     the list of arguments.  See ■hpt{printf()} for details.
  20912.  
  20913. ■returnvalue
  20914.  
  20915.     On success, vsnprintf() returns the number of characters
  20916.     (excluding the terminating null character) that would have been
  20917.     written to BUFFER if N had been sufficiently large.  That is,
  20918.     output is truncated iff the returned value is greater than or
  20919.     equal to N.  On error, vsnprintf() returns EOF.
  20920.  
  20921. ■seealso printf() snprintf() va_arg() vsprintf()
  20922.  
  20923.  
  20924. ■function wait()
  20925. ■compat POSIX.1
  20926.  
  20927. ■headers
  20928. #include <sys/types.h>
  20929. #include <sys/wait.h>
  20930. ■endheaders
  20931.  
  20932. ■param STAT_LOC STAT_VAL
  20933. ■prototype
  20934. int wait (int *STAT_LOC);
  20935. ■endprototype
  20936.  
  20937.     Obtain status information about a child process.  wait() suspends
  20938.     the process until status information for a child process is
  20939.     available or until a signal occurs.
  20940.  
  20941.     If status information is available, wait() returns immediately.
  20942.     This happens if a child process terminated before wait() is
  20943.     called, or if status information about a debuggee is available,
  20944.     that is, after calling ptrace() with requests PTRACE_RESUME or
  20945.     PTRACE_STEP.
  20946.  
  20947.     If there are no child processes, wait() returns immediately,
  20948.     setting errno to ECHILD and returning -1.  If STAT_LOC is not
  20949.     NULL, the return code and the termination status are stored to the
  20950.     location pointed to by STAT_LOC.
  20951.  
  20952.     You can use the following macros for determining the type of
  20953.     status (STAT_VAL is the value pointed to by STAT_LOC):
  20954.  
  20955. ■list
  20956. ■item ■tt{WIFEXITED (}STAT_VAL■tt{)}
  20957.  
  20958.     This macro returns a non-zero value if the process for which
  20959.     STAT_VAL was returned terminated normally.
  20960.  
  20961. ■item ■tt{WIFSIGNALED (}STAT_VAL■tt{)}
  20962.  
  20963.     This macro returns a non-zero value if the process for which
  20964.     STAT_VAL was returned terminated due to a signal which was not
  20965.     caught.
  20966.  
  20967. ■item ■tt{WIFSTOPPED (}STAT_VAL■tt{)}
  20968.  
  20969.     This macro returns a non-zero value if the process for which
  20970.     STAT_VAL was returned is stopped.  This occurs only if the child
  20971.     process is being debugged.
  20972.  
  20973. ■endlist
  20974.  
  20975.     Depending on the type of status indicated by the above macros, you
  20976.     can use exactly one of the following macro to obtain additional
  20977.     information:
  20978.  
  20979. ■list
  20980. ■item ■tt{WEXITSTATUS (}STAT_VAL■tt{)}
  20981.  
  20982.     If ■tt{WIFEXITED(}STAT_VAL■tt{)} is non-zero, this macro returns
  20983.     the return code of the child process (passed to exit(), _exit(),
  20984.     or returned from main()).
  20985.  
  20986. ■item ■tt{WTERMSIG (}STAT_VAL■tt{)}
  20987.  
  20988.     If ■tt{WIFSIGNALED(}STAT_VAL■tt{)} is non-zero, this macro returns
  20989.     the number of the signal by which the child process was terminated.
  20990.  
  20991. ■item ■tt{WSTOPSIG (}STAT_VAL■tt{)}
  20992.  
  20993.     If ■tt{WIFSTOPPED(}STAT_VAL■tt{)} is non-zero, this macro returns
  20994.     the number of the signal by which the child process was stopped.
  20995.  
  20996. ■endlist
  20997.  
  20998.  
  20999. ■returnvalue
  21000.  
  21001.     wait() returns the process ID of the child process.  If
  21002.     _UF_PTRACE_MULTITHREAD has been set with _uflags(), the return value
  21003.     of wait() contains both the thread ID and the process ID; use the
  21004.     PTRACE_GETPID and PTRACE_GETTID macros of <sys/ptrace.h> to
  21005.     extract the process ID and the thread ID.  If an error occurs,
  21006.     wait() sets errno and returns -1.
  21007.  
  21008. ■restrictions
  21009.  
  21010.     Under DOS, wait() is currently implemented only for processes
  21011.     being debugged and for synchronous processes started with
  21012.     P_NOWAIT; see ■hpt{ptrace()} and ■hpt{spawn*()}.  Under DOS, the
  21013.     termination status of only one process is kept for wait().  If you
  21014.     run another process before calling wait(), the termination status
  21015.     will be overwritten.
  21016.  
  21017.     Under OS/2, wait() works only for processes started with spawn*()
  21018.     or ■hpt{exec*()}.  It does not work for processes started with
  21019.     DosExecPgm or DosStartSession.  If the processes found by wait()
  21020.     has been started as a session, only the return code is available,
  21021.     not the signal number.
  21022.  
  21023.     wait() is interrupted by signals which are ignored (SIG_IGN) and
  21024.     by signals which are blocked.
  21025.  
  21026. ■seealso exit() fork() main() ptrace() sigaction() signal() sigprocmask() spawn*() _uflags() waitpid()
  21027.  
  21028. ■samplecode
  21029. int tc, pid;
  21030.  
  21031. pid = wait (&tc);
  21032. if (pid >= 0)
  21033.   {
  21034.     if (WIFEXITED (tc))
  21035.       printf ("Normal process termination, rc=%d\n", WEXITSTATUS (tc));
  21036.     else if (WIFSIGNALED (tc))
  21037.       printf ("Process terminated by signal %d\n", WTERMSIG (tc));
  21038.     else
  21039.       printf ("Process stopped by signal %d\n", WSTOPSIG (tc));
  21040.   }
  21041. ■endsamplecode
  21042.  
  21043.  
  21044. ■function _wait0() _wait1() _wait01() _wait10()
  21045. ■compat emx *
  21046. ■headers
  21047. #include <sys/hw.h>
  21048. ■endheaders
  21049.  
  21050. ■param PORT MASK
  21051. ■prototype
  21052. void _wait0 (unsigned PORT, unsigned MASK);
  21053. void _wait1 (unsigned PORT, unsigned MASK);
  21054. void _wait01 (unsigned PORT, unsigned MASK);
  21055. void _wait10 (unsigned PORT, unsigned MASK);
  21056. ■endprototype
  21057.  
  21058.     The _wait0() and _wait1() functions wait for the bit indicated by
  21059.     MASK of the 8-bit hardware port PORT being 0 or 1, respectively.
  21060.  
  21061.     The _wait01() and _wait10() functions wait for a 0->1 or 1->0
  21062.     transition, respectively, of the bit indicated by MASK of the
  21063.     8-bit hardware port PORT.
  21064.  
  21065.     If there are multiple bits set in MASK, 0 means all bits
  21066.     cleared, 1 means at least one bit set.
  21067.  
  21068.     You have to call _portaccess() first to enable access to a range
  21069.     of ports.  To make your program work under DOS, you have to use
  21070.     emx option -ai, see `■hpt{Using emx options}'.  Under OS/2, your
  21071.     program requires emxio.dll in a directory listed in LIBPATH.
  21072.  
  21073.     Note that these functions eat a lot of CPU time.
  21074.  
  21075. ■seealso _portaccess() _inp8()
  21076.  
  21077.  
  21078. ■function waitpid()
  21079. ■compat POSIX.1
  21080. ■headers
  21081. #include <sys/types.h>
  21082. #include <sys/wait.h>
  21083. ■endheaders
  21084.  
  21085. ■param PID STAT_LOC OPTIONS
  21086. ■prototype
  21087. int waitpid (int PID, int *STAT_LOC, int OPTIONS);
  21088. ■endprototype
  21089.  
  21090.     Wait until status information for the child process PID is
  21091.     available or until a signal occurs.  If PID is -1, waitpid() waits
  21092.     for any child process, as does wait().  If there is no child
  21093.     process with process ID PID (or if PID is -1 and there is no child
  21094.     process), errno is set to ESRCH and -1 is returned.  On success,
  21095.     the process ID is returned.  If STAT_LOC is not NULL, the return
  21096.     code and the termination status are stored to the location pointed
  21097.     to by STAT_LOC, see ■hpt{wait()} for details.
  21098.  
  21099.     OPTIONS is the bitwise OR of zero or more of the following flags:
  21100.  
  21101. ■description
  21102.  
  21103. ■item WNOHANG
  21104.  
  21105.     Don't wait if no status information is currently available.  If
  21106.     WNOHANG is set, and there are any child processes matching PID,
  21107.     and no status available for any child process matching PID, 0 is
  21108.     returned.
  21109.  
  21110. ■item WUNTRACED
  21111.  
  21112.     Not implemented.
  21113.  
  21114. ■enddescription
  21115.  
  21116. ■returnvalue
  21117. ■description
  21118. ■item -1
  21119.     error or interrupted (errno set to ECHILD, EINVAL, or EINTR)
  21120. ■item >0
  21121.     process ID.  If _UF_PTRACE_MULTITHREAD has been set with _uflags(),
  21122.     the return value of waitpid() contains both the thread ID and the
  21123.     process ID; use the PTRACE_GETPID and PTRACE_GETTID macros of
  21124.     <sys/ptrace.h> to extract the process ID and the thread ID
  21125. ■item 0
  21126.     WNOHANG is set in OPTIONS, and there are child processes matching
  21127.     PID, and no status available for any child process matching PID
  21128. ■enddescription
  21129.  
  21130. ■restrictions
  21131.  
  21132.     waitpid() is not implemented for negative values of PID.
  21133.     WUNTRACED in OPTIONS is ignored.  waitpid() is not implemented
  21134.     under DOS.  waitpid() is interrupted by signals which are ignored
  21135.     (SIG_IGN) and by signals which are blocked.
  21136.  
  21137. ■seealso fork() ptrace() sigaction() signal() sigprocmask() spawn*() _uflags() wait()
  21138.  
  21139.  
  21140. ■function _wildcard()
  21141. ■compat emx
  21142. ■headers
  21143. #include <stdlib.h>
  21144. ■endheaders
  21145.  
  21146. ■param ARGCP ARGVP
  21147. ■prototype
  21148. void _wildcard (int *ARGCP, char ***ARGVP);
  21149. ■endprototype
  21150.  
  21151.     Expand wildcards.  If you want wildcards on the command line to be
  21152.     expanded, call
  21153.  
  21154. ■example
  21155. _wildcard (&argc, &argv);
  21156. ■endexample
  21157.  
  21158.     at the beginning of main().  Wildcard arguments enclosed in double
  21159.     quotes won't be expanded.  If the expansion of a wildcard argument
  21160.     is empty, the wildcard argument is kept unchanged.  Directories
  21161.     are included in the expansion.  Hidden and system files are
  21162.     omitted.
  21163.  
  21164.     _fnlwr() is used to convert file names to lower case on
  21165.     upper-case-only file systems.
  21166.  
  21167.     _wildcard() properly handles DBCS characters.
  21168.  
  21169. ■seealso _envargs() _fnexplode() main() _nls_init() _response()
  21170.  
  21171.  
  21172. ■function wcstombs()
  21173. ■compat C90
  21174. ■headers
  21175. #include <stdlib.h>
  21176. ■endheaders
  21177.  
  21178. ■param S PWCS N
  21179. ■prototype
  21180. size_t wcstombs (char *S, const wchar_t *PWCS, size_t N);
  21181. ■endprototype
  21182.  
  21183.     Convert the zero-terminated sequence of wchar_t codes at PWCS to a
  21184.     multibyte character sequence beginning at S.  The multibyte
  21185.     character sequence starts in the initial shift state.  At most N
  21186.     bytes are stored.  S will be terminated with a null character if N
  21187.     is big enough.
  21188.  
  21189.     The shift state of wctomb() is not affected.
  21190.  
  21191. ■returnvalue
  21192.  
  21193.     wcstombs() returns the number of bytes stored to S (excluding the
  21194.     terminating null character) or ■tt{(size_t_t)-1} if a code could
  21195.     not be counverted.
  21196.  
  21197. ■seealso mbstowcs() setlocale() wctomb()
  21198.  
  21199.  
  21200. ■function wctomb()
  21201. ■compat C90
  21202. ■headers
  21203. #include <stdlib.h>
  21204. ■endheaders
  21205.  
  21206. ■param S WCHAR
  21207. ■prototype
  21208. int wctomb (char *S, wchar_t WCHAR);
  21209. ■endprototype
  21210.  
  21211.     Convert the wchar_t code WCHAR to a multibyte character sequence
  21212.     pointed to by S.  At most MB_CUR_MAX bytes are stored.  If S is
  21213.     NULL, the shift state is reset to the initial state.  If WCHAR is
  21214.     zero, the shift state is the initial state after return from
  21215.     wctomb().
  21216.  
  21217.     In programs linked with the multithread libraries, each thread has
  21218.     its own shift state for wctomb().
  21219.  
  21220. ■returnvalue
  21221.  
  21222.     If S is NULL, wctomb() returns a non-zero value (if
  21223.     state-dependent encoding is used) or a zero value (if
  21224.     state-dependent encoding is not used).  If S is not NULL, wctomb()
  21225.     returns 0 (if WCHAR is zero), the number of bytes comprising the
  21226.     multibyte character stored to S (if conversion is successful), or
  21227.     -1 (if WCHAR could not be converted).
  21228.  
  21229. ■seealso mbtowc() setlocale() wcstombs()
  21230.  
  21231.  
  21232. ■function wm_attrib()
  21233. ■compat emx
  21234. ■headers
  21235. #include <sys/winmgr.h>
  21236. ■endheaders
  21237.  
  21238. ■param WH A
  21239. ■prototype
  21240. void wm_attrib (wm_handle WH, int A);
  21241. ■endprototype
  21242.  
  21243.     Set the default attributes of window WH to A.
  21244.  
  21245. ■seealso wm_create() wm_get_attrib() wm_putc()
  21246.  
  21247.  
  21248. ■function wm_attrib_all()
  21249. ■compat emx
  21250. ■headers
  21251. #include <sys/winmgr.h>
  21252. ■endheaders
  21253.  
  21254. ■param WH A
  21255. ■prototype
  21256. void wm_attrib_all (wm_handle WH, int A);
  21257. ■endprototype
  21258.  
  21259.     Change the attributes of all characters of window WH (except of
  21260.     the border) to A.  The character codes are not changed.
  21261.  
  21262. ■seealso wm_attrib() wm_clear() wm_create()
  21263.  
  21264.  
  21265. ■function wm_backsp()
  21266. ■compat emx
  21267. ■headers
  21268. #include <sys/winmgr.h>
  21269. ■endheaders
  21270.  
  21271. ■param WH COUNT
  21272. ■prototype
  21273. void wm_backsp (wm_handle WH, int COUNT);
  21274. ■endprototype
  21275.  
  21276.     Backspace the cursor of window WH.  The cursor is moved left by
  21277.     COUNT characters.  If the cursor leaves the window at the left
  21278.     edge, it is moved to the end of the previous line.  The cursor
  21279.     cannot leave the window at the top edge.
  21280.  
  21281. ■seealso wm_putc()
  21282.  
  21283.  
  21284. ■function wm_border()
  21285. ■compat emx
  21286. ■headers
  21287. #include <sys/winmgr.h>
  21288. ■endheaders
  21289.  
  21290. ■param WH BFLAG BATTR TITLE TFLAG TATTR
  21291. ■prototype
  21292. void wm_border (wm_handle WH, int BFLAG, int BATTR, const char *TITLE,
  21293.                 int TFLAG, int TATTR);
  21294. ■endprototype
  21295.  
  21296.     Change the border of window WH.  The border type is set to BFLAG:
  21297.     0 turns the border off, 1 uses a single line, 2 uses a double
  21298.     line, 3 and 4 use both single and double lines -- which is not
  21299.     recommended as most code pages do not contain the necessary
  21300.     symbols.  All other values are used as characters for drawing the
  21301.     border.  The attributes BATTR are used for drawing the border.
  21302.     The string pointed to by TITLE is displayed centered in the top
  21303.     line of the border.  If TFLAG is non-zero, vertical bars are used
  21304.     to separate the title text from the border.  The attributes TATTR
  21305.     are used for displaying the title text.
  21306.  
  21307. ■seealso wm_create()
  21308.  
  21309.  
  21310. ■function wm_bottom()
  21311. ■compat emx
  21312. ■headers
  21313. #include <sys/winmgr.h>
  21314. ■endheaders
  21315.  
  21316. ■param WH
  21317. ■prototype
  21318. void wm_bottom (wm_handle WH);
  21319. ■endprototype
  21320.  
  21321.     Move window WH to the bottom of the window stack, that is, it will
  21322.     be moved below all other windows.
  21323.  
  21324. ■seealso wm_top() wm_up()
  21325.  
  21326.  
  21327. ■function wm_chide()
  21328. ■compat emx
  21329. ■headers
  21330. #include <sys/winmgr.h>
  21331. ■endheaders
  21332.  
  21333. ■param FLAG
  21334. ■prototype
  21335. void wm_chide (int FLAG);
  21336. ■endprototype
  21337.  
  21338.     Set the cursor hide mode.  If FLAG is non-zero, the cursor is
  21339.     hidden if the current cursor position is hidden by another window.
  21340.     If FLAG is zero, the cursor is visible even if the cursor position
  21341.     is hidden by another window.  The initial value is non-zero.
  21342.  
  21343. ■seealso wm_ctype() wm_cursor()
  21344.  
  21345.  
  21346. ■function wm_clear()
  21347. ■compat emx
  21348. ■headers
  21349. #include <sys/winmgr.h>
  21350. ■endheaders
  21351.  
  21352. ■param WH
  21353. ■prototype
  21354. void wm_clear (wm_handle WH);
  21355. ■endprototype
  21356.  
  21357.     Clear window WH by filling WH with blanks using the current
  21358.     attributes.
  21359.  
  21360. ■seealso wm_attrib() wm_attrib_all()
  21361.  
  21362.  
  21363. ■function wm_close()
  21364. ■compat emx
  21365. ■headers
  21366. #include <sys/winmgr.h>
  21367. ■endheaders
  21368.  
  21369. ■param WH
  21370. ■prototype
  21371. void wm_close (wm_handle WH);
  21372. ■endprototype
  21373.  
  21374.     Close the window WH.  After closing the window, it still exists
  21375.     but is not visible.
  21376.  
  21377. ■seealso wm_open()
  21378.  
  21379.  
  21380. ■function wm_close_all()
  21381. ■compat emx
  21382. ■headers
  21383. #include <sys/winmgr.h>
  21384. ■endheaders
  21385.  
  21386. ■prototype
  21387. void wm_close_all (void);
  21388. ■endprototype
  21389.  
  21390.    Close all the windows.  wm_close_all() restores the original screen
  21391.    contents.
  21392.  
  21393. ■seealso wm_close() wm_open()
  21394.  
  21395.  
  21396. ■function wm_clr_eol()
  21397. ■compat emx
  21398. ■headers
  21399. #include <sys/winmgr.h>
  21400. ■endheaders
  21401.  
  21402. ■param WH X Y
  21403. ■prototype
  21404. void wm_clr_eol (wm_handle WH, int X, int Y);
  21405. ■endprototype
  21406.  
  21407.     Clear from position (X,Y) of window WH to the end of that line of
  21408.     that window by displaying blanks.  The current attributes are
  21409.     used.
  21410.  
  21411. ■seealso wm_clear()
  21412.  
  21413.  
  21414. ■function wm_create()
  21415. ■compat emx
  21416. ■headers
  21417. #include <sys/winmgr.h>
  21418. ■endheaders
  21419.  
  21420. ■param X0 Y0 X1 Y1 BORDER BATTR WATTR
  21421. ■prototype
  21422. wm_handle wm_create (int X0, int Y0, int X1, int Y1, int BORDER, int BATTR,
  21423.                      int WATTR);
  21424. ■endprototype
  21425.  
  21426.     Create a window.  The upper left character of the window interior
  21427.     is at (X0,Y0), the bottom right character of the window interior
  21428.     is at (X1,Y1).  A window may be larger than the screen or
  21429.     partially or completely outside the screen.  BORDER specifies the
  21430.     border type: 0 doesn't draw a border, 1 uses a single line, 2 uses
  21431.     a double line, 3 and 4 use both single and double lines -- which
  21432.     is not recommended as most code pages do not contain the necessary
  21433.     symbols.  All other values are used as characters for drawing the
  21434.     border.  The attributes BATTR are used for drawing the border.
  21435.     The attributes for displaying text in the window are set to WATTR.
  21436.     After creating a window, it is invisible.  Use wm_open() to show
  21437.     the window.
  21438.  
  21439. ■returnvalue
  21440.  
  21441.     wm_create() returns the handle of the window if successful.
  21442.     Otherwise, NULL is returned.
  21443.  
  21444. ■seealso wm_attrib() wm_border() wm_delete() wm_open()
  21445.  
  21446.  
  21447. ■function wm_ctype()
  21448. ■compat emx
  21449. ■headers
  21450. #include <sys/winmgr.h>
  21451. ■endheaders
  21452.  
  21453. ■param WH START END
  21454. ■prototype
  21455. void wm_ctype (wm_handle WH, int START, int END);
  21456. ■endprototype
  21457.  
  21458.     Set the cursor type of window WH.  START is the first row of the
  21459.     cursor, END is the last row of the cursor.  Both values are
  21460.     zero-based.  The cursor type set by wm_ctype() is used for
  21461.     displaying the cursor if it is connected to window WH.  Use
  21462.     v_hardware() to determine the size of the character box.
  21463.  
  21464. ■seealso v_hardware() wm_chide() wm_cursor()
  21465.  
  21466.  
  21467. ■function wm_cursor()
  21468. ■compat emx
  21469. ■headers
  21470. #include <sys/winmgr.h>
  21471. ■endheaders
  21472.  
  21473. ■param WH
  21474. ■prototype
  21475. void wm_cursor (wm_handle WH);
  21476. ■endprototype
  21477.  
  21478.     Connect the screen cursor with the cursor of window WH.  The
  21479.     cursor is displayed at the cursor position of window WH, using the
  21480.     cursor type of window WH.  If WH is NULL, the screen cursor is not
  21481.     connected to any window and is invisible.  Initially, the screen
  21482.     cursor is not connected to any window.
  21483.  
  21484. ■seealso wm_chide() wm_ctype() wm_cvis()
  21485.  
  21486.  
  21487. ■function wm_cvis()
  21488. ■compat emx
  21489. ■headers
  21490. #include <sys/winmgr.h>
  21491. ■endheaders
  21492.  
  21493. ■param WH FLAG
  21494. ■prototype
  21495. void wm_cvis (wm_handle WH, int FLAG);
  21496. ■endprototype
  21497.  
  21498.     Set the cursor status of window WH.  If FLAG is non-zero, the
  21499.     cursor is enabled, if FLAG is zero, the cursor is disabled.
  21500.  
  21501. ■seealso wm_chide() wm_cursor()
  21502.  
  21503.  
  21504. ■function wm_del_char()
  21505. ■compat emx
  21506. ■headers
  21507. #include <sys/winmgr.h>
  21508. ■endheaders
  21509.  
  21510. ■param WH X Y COUNT
  21511. ■prototype
  21512. void wm_del_char (wm_handle WH, int X, int Y, int COUNT);
  21513. ■endprototype
  21514.  
  21515.     Delete COUNT characters at position (X,Y) of window WH.
  21516.     Characters to the right of that position are moved left, the
  21517.     positions becoming vacant at the right edge of the window are
  21518.     filled with blanks using the current attributes.
  21519.  
  21520. ■seealso wm_attrib() wm_del_line() wm_ins_char()
  21521.  
  21522.  
  21523. ■function wm_del_line()
  21524. ■compat emx
  21525. ■headers
  21526. #include <sys/winmgr.h>
  21527. ■endheaders
  21528.  
  21529. ■param WH Y COUNT
  21530. ■prototype
  21531. void wm_del_line (wm_handle WH, int Y, int COUNT);
  21532. ■endprototype
  21533.  
  21534.     Delete COUNT lines at line Y of window WH by moving up the
  21535.     lines below that line.  The current attributes are used for
  21536.     filling lines becoming empty at the bottom of the window.
  21537.  
  21538. ■seealso wm_attrib() wm_del_char() wm_ins_line() wm_scroll()
  21539.  
  21540.  
  21541. ■function wm_delete()
  21542. ■compat emx
  21543. ■headers
  21544. #include <sys/winmgr.h>
  21545. ■endheaders
  21546.  
  21547. ■param WH
  21548. ■prototype
  21549. void wm_delete (wm_handle WH);
  21550. ■endprototype
  21551.  
  21552.     Destroy the window WH.  After calling wm_delete(), the window
  21553.     handle WH must no longer be used.  The window is not closed.
  21554.  
  21555. ■seealso wm_close() wm_create()
  21556.  
  21557.  
  21558. ■function wm_dimen()
  21559. ■compat emx
  21560. ■headers
  21561. #include <sys/winmgr.h>
  21562. ■endheaders
  21563.  
  21564. ■param WH WIDTH HEIGHT
  21565. ■prototype
  21566. void wm_dimen (wm_handle WH, int *WIDTH, int *HEIGHT);
  21567. ■endprototype
  21568.  
  21569.     Store the width of the window WH (columns) to WIDTH, the height
  21570.     (lines) to HEIGHT.
  21571.  
  21572. ■seealso wm_create()
  21573.  
  21574.  
  21575. ■function wm_down()
  21576. ■compat emx
  21577. ■headers
  21578. #include <sys/winmgr.h>
  21579. ■endheaders
  21580.  
  21581. ■param WH
  21582. ■prototype
  21583. void wm_down (wm_handle WH);
  21584. ■endprototype
  21585.  
  21586.     Move window WH down the window stack, that is, it will be covered
  21587.     by an additional window unless WH is already the bottom window.
  21588.  
  21589. ■seealso wm_bottom() wm_top() wm_up()
  21590.  
  21591.  
  21592. ■function wm_exit()
  21593. ■compat emx
  21594. ■headers
  21595. #include <sys/winmgr.h>
  21596. ■endheaders
  21597.  
  21598. ■prototype
  21599. void wm_exit (void);
  21600. ■endprototype
  21601.  
  21602.     Quit the window manager and release all memory allocated by the
  21603.     window manager.  All window handles become invalid.  The windows
  21604.     are not closed.
  21605.  
  21606. ■seealso wm_close() wm_delete()
  21607.  
  21608.  
  21609. ■function wm_fclose()
  21610. ■compat emx
  21611. ■headers
  21612. #include <stdio.h>
  21613. #include <sys/winmgr.h>
  21614. ■endheaders
  21615.  
  21616. ■param STREAM
  21617. ■prototype
  21618. int wm_fclose (FILE *STREAM);
  21619. ■endprototype
  21620.  
  21621.     Close a window manager file.
  21622.  
  21623. ■returnvalue
  21624. ■description
  21625. ■item 0
  21626.     success
  21627. ■item -1
  21628.     error
  21629. ■enddescription
  21630.  
  21631.  
  21632. ■seealso wm_fopen()
  21633.  
  21634.  
  21635. ■function wm_find()
  21636. ■compat emx
  21637. ■headers
  21638. #include <sys/winmgr.h>
  21639. ■endheaders
  21640.  
  21641. ■param X Y
  21642. ■prototype
  21643. wm_handle wm_find (int X, int Y);
  21644. ■endprototype
  21645.  
  21646.     Find the window which is visible at position (X,Y) of the screen.
  21647.  
  21648. ■returnvalue
  21649.  
  21650.     wm_find() returns the window handle if such a window exists.
  21651.     Otherwise, wm_find() returns NULL.
  21652.  
  21653.  
  21654. ■function wm_fopen()
  21655. ■compat emx
  21656. ■headers
  21657. #include <stdio.h>
  21658. #include <sys/winmgr.h>
  21659. ■endheaders
  21660.  
  21661. ■param WH
  21662. ■prototype
  21663. FILE *wm_fopen (wm_handle WH);
  21664. ■endprototype
  21665.  
  21666.     Open a window manager file.  All output to a video file goes to
  21667.     the window WH, using window manager library functions such as
  21668.     wm_puts().  The stream returned by wm_fopen() can be used with
  21669.     fprintf(), fputc() and fwrite().  On error, wm_fopen() returns
  21670.     NULL.  Do not use fclose() on a stream created by v_fopen(), use
  21671.     wm_fclose() instead.  Do not read from a stream created by
  21672.     wm_fopen().
  21673.  
  21674. ■returnvalue
  21675.  
  21676.     See above.
  21677.  
  21678. ■seealso _fassign() fopen() wm_printf()
  21679.  
  21680.  
  21681. ■function wm_get_attrib()
  21682. ■compat emx
  21683. ■headers
  21684. #include <sys/winmgr.h>
  21685. ■endheaders
  21686.  
  21687. ■param WH
  21688. ■prototype
  21689. int wm_get_attrib (wm_handle WH);
  21690. ■endprototype
  21691.  
  21692.     Return the current attributes of window WH.
  21693.  
  21694. ■returnvalue
  21695.  
  21696.     See above.
  21697.  
  21698. ■seealso wm_attrib()
  21699.  
  21700.  
  21701. ■function wm_get_cursor()
  21702. ■compat emx
  21703. ■headers
  21704. #include <sys/winmgr.h>
  21705. ■endheaders
  21706.  
  21707. ■prototype
  21708. wm_handle wm_get_cursor (void);
  21709. ■endprototype
  21710.  
  21711.     Get the window to which the screen cursor is connected.
  21712.  
  21713. ■returnvalue
  21714.  
  21715.     wm_get_cursor() returns the window handle of the window to which
  21716.     the screen cursor is connected.  If the cursor is not connected to
  21717.     any window, wm_get_cursor() returns NULL.
  21718.  
  21719. ■seealso wm_cursor()
  21720.  
  21721.  
  21722. ■function wm_get_pos()
  21723. ■compat emx
  21724. ■headers
  21725. #include <sys/winmgr.h>
  21726. ■endheaders
  21727.  
  21728. ■param WH X Y
  21729. ■prototype
  21730. void wm_get_pos (wm_handle WH, int *X, int *Y);
  21731. ■endprototype
  21732.  
  21733.     Store the screen coordinates of the upper left character of the
  21734.     interior of window WH to X and Y.
  21735.  
  21736. ■seealso wm_create() wm_move()
  21737.  
  21738.  
  21739. ■function wm_getxy() wm_getx() wm_gety()
  21740. ■compat emx
  21741. ■headers
  21742. #include <sys/winmgr.h>
  21743. ■endheaders
  21744.  
  21745. ■param WH X Y
  21746. ■prototype
  21747. void wm_getxy (wm_handle WH, int *X, int *Y);
  21748. int wm_getx (wm_handle WH);
  21749. int wm_gety (wm_handle WH);
  21750. ■endprototype
  21751.  
  21752.     wm_getxy() stores the cursor coordinates of window WH to X and Y.
  21753.     wm_getx() returns the horizontal position (column) of the cursor
  21754.     of window WH.  wm_gety() returns the vertical position (line) of
  21755.     the cursor of window WH.  The coordinates are zero-based and are
  21756.     relative to the upper left character of the interior of window WH.
  21757.  
  21758. ■returnvalue
  21759.  
  21760.     See above.
  21761.  
  21762. ■seealso wm_gotoxy()
  21763.  
  21764.  
  21765. ■function wm_gotoxy()
  21766. ■compat emx
  21767. ■headers
  21768. #include <sys/winmgr.h>
  21769. ■endheaders
  21770.  
  21771. ■param WH X Y
  21772. ■prototype
  21773. void wm_gotoxy (wm_handle WH, int X, int Y);
  21774. ■endprototype
  21775.  
  21776.     Move the cursor of window WH to (X,Y).  The coordinates are
  21777.     zero-based and are relative to the upper left character of the
  21778.     interior of window WH.  If the screen cursor is connected to the
  21779.     cursor of window WH, the screen cursor is moved.
  21780.  
  21781. ■seealso wm_cursor() wm_getxy()
  21782.  
  21783.  
  21784. ■function wm_ins_char()
  21785. ■compat emx
  21786. ■headers
  21787. #include <sys/winmgr.h>
  21788. ■endheaders
  21789.  
  21790. ■param WH X Y COUNT
  21791. ■prototype
  21792. void wm_ins_char (wm_handle WH, int X, int Y, int COUNT);
  21793. ■endprototype
  21794.  
  21795.     Insert COUNT blank characters at position (X,Y) of window WH.
  21796.     Characters to the right of that position are moved right.  The
  21797.     current attributes are used for displaying the blank characters.
  21798.  
  21799. ■seealso wm_attrib() wm_del_char() wm_ins_line()
  21800.  
  21801.  
  21802. ■function wm_ins_line()
  21803. ■compat emx
  21804. ■headers
  21805. #include <sys/winmgr.h>
  21806. ■endheaders
  21807.  
  21808. ■param WH Y COUNT
  21809. ■prototype
  21810. void wm_ins_line (wm_handle WH, int Y, int COUNT);
  21811. ■endprototype
  21812.  
  21813.     Insert COUNT empty lines at line Y of window WH by moving down
  21814.     that line and all lines below that line.  The current attributes
  21815.     are used for filling the empty lines.
  21816.  
  21817. ■seealso wm_attrib() wm_del_line() wm_scroll()
  21818.  
  21819.  
  21820. ■function wm_init()
  21821. ■compat emx
  21822. ■headers
  21823. #include <sys/winmgr.h>
  21824. ■endheaders
  21825.  
  21826. ■param N
  21827. ■prototype
  21828. int wm_init (int N);
  21829. ■endprototype
  21830.  
  21831.     Initialize the window manager and allocate memory for N windows.
  21832.     You must call this function before calling any other window
  21833.     manager function.
  21834.  
  21835.     General information about window manager functions: The window
  21836.     manager functions implement text-mode output to windows on the
  21837.     screen.  You have to link with -lvideo.  Under DOS, emx option
  21838.     -acm is required, see `■hpt{Using emx options}'.
  21839.  
  21840. ■returnvalue
  21841. ■description
  21842. ■item 1
  21843.     success
  21844. ■item 0
  21845.     error
  21846. ■enddescription
  21847.  
  21848. ■seealso wm_exit()
  21849.  
  21850. ■samplefile /emx/samples/wm_demo.c, /emx/samples/wm_hello.c
  21851.  
  21852.  
  21853. ■function wm_move()
  21854. ■compat emx
  21855. ■headers
  21856. #include <sys/winmgr.h>
  21857. ■endheaders
  21858.  
  21859. ■param WH X Y
  21860. ■prototype
  21861. void wm_move (wm_handle WH, int X, int Y);
  21862. ■endprototype
  21863.  
  21864.     Move the window WH.  The upper left character of the interior of
  21865.     the window will be at screen coordinates (X,Y).
  21866.  
  21867. ■seealso wm_get_pos()
  21868.  
  21869.  
  21870. ■function wm_open()
  21871. ■compat emx
  21872. ■headers
  21873. #include <sys/winmgr.h>
  21874. ■endheaders
  21875.  
  21876. ■param WH
  21877. ■prototype
  21878. void wm_open (wm_handle WH);
  21879. ■endprototype
  21880.  
  21881.     Open the window WH.  The window will be showed on the screen
  21882.     unless it is covered by other windows or outside the screen.
  21883.  
  21884. ■seealso wm_close()
  21885.  
  21886.  
  21887. ■function wm_printf()
  21888. ■compat emx
  21889. ■headers
  21890. #include <sys/winmgr.h>
  21891. ■endheaders
  21892.  
  21893. ■param WH FMT
  21894. ■prototype
  21895. int wm_printf (wm_handle WH, const char *FMT, ...);
  21896. ■endprototype
  21897.  
  21898.     Formatted output to window WH at the current cursor position of
  21899.     that window.  The cursor is moved.  See ■hpt{printf()} for details
  21900.     on the format string pointed to by FMT.
  21901.  
  21902. ■returnvalue
  21903.  
  21904.     wm_printf() returns the number of output characters.
  21905.  
  21906. ■seealso wm_attrib() wm_fopen() wm_putc() wm_puts() wm_vprintf()
  21907.  
  21908.  
  21909. ■function wm_puta_at()
  21910. ■compat emx
  21911. ■headers
  21912. #include <sys/winmgr.h>
  21913. ■endheaders
  21914.  
  21915. ■param WH X Y A COUNT
  21916. ■prototype
  21917. void wm_puta_at (wm_handle WH, int X, int Y, int A, int COUNT);
  21918. ■endprototype
  21919.  
  21920.     Change to A the attributes of COUNT characters at position (X,Y)
  21921.     of window WH.  All COUNT characters must be in one line of the
  21922.     window.
  21923.  
  21924. ■seealso wm_attrib() wm_putsa_at()
  21925.  
  21926.  
  21927. ■function wm_putc()
  21928. ■compat emx
  21929. ■headers
  21930. #include <sys/winmgr.h>
  21931. ■endheaders
  21932.  
  21933. ■param WH C
  21934. ■prototype
  21935. void wm_putc (wm_handle WH, char C);
  21936. ■endprototype
  21937.  
  21938.     Display character C in window WH at the current cursor position of
  21939.     that window, using the current attributes of that window.  The
  21940.     cursor of that window is moved.  If the cursor leaves the window
  21941.     at the right edge, it will be moved to the start of the next
  21942.     line.  If C is ■tt{'\n'}, the cursor is moved to the start of the
  21943.     next line.  If the cursor leaves the window at the bottom edge,
  21944.     the window is scrolled up.
  21945.  
  21946. ■seealso wm_attrib() wm_putc_at() wm_putca() wm_scroll() wm_wrap()
  21947.  
  21948.  
  21949. ■function wm_putc_at()
  21950. ■compat emx
  21951. ■headers
  21952. #include <sys/winmgr.h>
  21953. ■endheaders
  21954.  
  21955. ■param WH X Y C
  21956. ■prototype
  21957. void wm_putc_at (wm_handle WH, int X, int Y, char C);
  21958. ■endprototype
  21959.  
  21960.     Display character C at position (X,Y) of window WH using the
  21961.     current attributes of that window.  The cursor is not moved.
  21962.  
  21963. ■seealso wm_attrib() wm_gotoxy()
  21964.  
  21965.  
  21966. ■function wm_putca()
  21967. ■compat emx
  21968. ■headers
  21969. #include <sys/winmgr.h>
  21970. ■endheaders
  21971.  
  21972. ■param WH C A
  21973. ■prototype
  21974. void wm_putca (wm_handle WH, char C, int A);
  21975. ■endprototype
  21976.  
  21977.     Display character C in window WH at the current cursor position of
  21978.     that window, using the attributes A.  The cursor of that window is
  21979.     moved.  If the cursor leaves the window at the right edge, it will
  21980.     be moved to the start of the next line.  If C is ■tt{'\n'}, the
  21981.     cursor is moved to the start of the next line.  If the cursor
  21982.     leaves the window at the bottom edge, the window is scrolled up.
  21983.  
  21984. ■seealso wm_putc() wm_putca_at() wm_scroll() wm_wrap()
  21985.  
  21986.  
  21987. ■function wm_putca_at()
  21988. ■compat emx
  21989. ■headers
  21990. #include <sys/winmgr.h>
  21991. ■endheaders
  21992.  
  21993. ■param WH X Y C A
  21994. ■prototype
  21995. void wm_putca_at (wm_handle WH, int X, int Y, char C, int A);
  21996. ■endprototype
  21997.  
  21998.     Display character C at position (X,Y) of window WH using the
  21999.     attributes A.  The cursor is not moved.
  22000.  
  22001.  
  22002. ■function wm_puts()
  22003. ■compat emx
  22004. ■headers
  22005. #include <sys/winmgr.h>
  22006. ■endheaders
  22007.  
  22008. ■param WH STR
  22009. ■prototype
  22010. void wm_puts (wm_handle WH, const char *STR);
  22011. ■endprototype
  22012.  
  22013.     Display the string pointed to by STR in window WH at the current
  22014.     cursor position of that window using the current attributes of
  22015.     that window.  The ■tt{'\n'} character moves the cursor to the
  22016.     start of the next line.  Scrolling is performed when the cursor
  22017.     leaves the window at the bottom edge.
  22018.  
  22019. ■seealso wm_attrib() wm_putc() wm_putsa() wm_scroll() wm_wrap()
  22020.  
  22021.  
  22022. ■function wm_puts_at()
  22023. ■compat emx
  22024. ■headers
  22025. #include <sys/winmgr.h>
  22026. ■endheaders
  22027.  
  22028. ■param WH X Y STR
  22029. ■prototype
  22030. void wm_puts_at (wm_handle WH, int X, int Y, const char *STR);
  22031. ■endprototype
  22032.  
  22033.     Display the string pointed to by STR in window WH at position
  22034.     (X,Y) using the current attributes of that window.  The ■tt{'\n'}
  22035.     character is not interpreted, the cursor is not moved.
  22036.  
  22037. ■seealso wm_attrib() wm_puts()
  22038.  
  22039.  
  22040. ■function wm_putsa()
  22041. ■compat emx
  22042. ■headers
  22043. #include <sys/winmgr.h>
  22044. ■endheaders
  22045.  
  22046. ■param WH STR LEN
  22047. ■prototype
  22048. void wm_putsa (wm_handle WH, const char *STR, int LEN);
  22049. ■endprototype
  22050.  
  22051.     Display LEN characters with attributes in window WH at the current
  22052.     cursor position of that window.  STR points to an array of
  22053.     character and attributes pairs.  There are 2*■pa{LEN} bytes at
  22054.     STR.
  22055.  
  22056. ■seealso wm_putca() wm_puts() wm_scroll() wm_wrap()
  22057.  
  22058.  
  22059. ■function wm_putsa_at()
  22060. ■compat emx
  22061. ■headers
  22062. #include <sys/winmgr.h>
  22063. ■endheaders
  22064.  
  22065. ■param WH X Y STR LEN
  22066. ■prototype
  22067. void wm_putsa_at (wm_handle WH, int X, int Y, const char *STR, int LEN);
  22068. ■endprototype
  22069.  
  22070.     Display LEN characters with attributes in window WH at position
  22071.     (X,Y).  STR points to an array of character and attributes pairs.
  22072.     There are 2*■pa{LEN} bytes at STR.
  22073.  
  22074. ■seealso wm_putsa()
  22075.  
  22076.  
  22077. ■function wm_scroll()
  22078. ■compat emx
  22079. ■headers
  22080. #include <sys/winmgr.h>
  22081. ■endheaders
  22082.  
  22083. ■param WH COUNT
  22084. ■prototype
  22085. void wm_scroll (wm_handle WH, int COUNT);
  22086. ■endprototype
  22087.  
  22088.     Scroll the interior of window WH up by one line.  The bottom line
  22089.     is filled with blanks, using the current attributes.
  22090.  
  22091. ■seealso wm_attrib() wm_del_line() wm_ins_line() wm_putc()
  22092.  
  22093.  
  22094. ■function wm_top()
  22095. ■compat emx
  22096. ■headers
  22097. #include <sys/winmgr.h>
  22098. ■endheaders
  22099.  
  22100. ■param WH
  22101. ■prototype
  22102. void wm_top (wm_handle WH);
  22103. ■endprototype
  22104.  
  22105.     Move window WH to the top of the window stack, that is, it will
  22106.     cover all other windows.
  22107.  
  22108. ■seealso wm_bottom() wm_down()
  22109.  
  22110.  
  22111. ■function wm_up()
  22112. ■compat emx
  22113. ■headers
  22114. #include <sys/winmgr.h>
  22115. ■endheaders
  22116.  
  22117. ■param WH
  22118. ■prototype
  22119. void wm_up (wm_handle WH);
  22120. ■endprototype
  22121.  
  22122.     Move window WH up the window stack, that is, it will cover an
  22123.     additional window unless WH is already the top window.
  22124.  
  22125. ■seealso wm_bottom() wm_down() wm_top()
  22126.  
  22127.  
  22128. ■function wm_update()
  22129. ■compat emx
  22130. ■headers
  22131. #include <sys/winmgr.h>
  22132. ■endheaders
  22133.  
  22134. ■param WH FLAG
  22135. ■prototype
  22136. void wm_update (wm_handle WH, int FLAG);
  22137. ■endprototype
  22138.  
  22139.     Set the update mode of window WH.  If FLAG is non-zero (which is
  22140.     the default), the screen is updated immediately if window WH is
  22141.     changed.  If FLAG is zero, changes to window WH are done in memory
  22142.     only.  This can be done to improve speed.  Each call to
  22143.     wm_update() copies the window to the screen, regardless of the
  22144.     FLAG argument.
  22145.  
  22146.  
  22147. ■function wm_vprintf()
  22148. ■compat emx
  22149. ■headers
  22150. #include <sys/winmgr.h>
  22151. ■endheaders
  22152.  
  22153. ■param WH FMT ARG_PTR
  22154. ■prototype
  22155. int wm_vprintf (wm_handle WH, const char *FMT, va_list ARG_PTR);
  22156. ■endprototype
  22157.  
  22158.     Formatted output to window WH.  Instead of a list of arguments,
  22159.     this function takes a pointer to the list of arguments.  See
  22160.     wm_printf() for details.
  22161.  
  22162. ■returnvalue
  22163.  
  22164.     wm_vprintf() returns the number of output characters.
  22165.  
  22166. ■seealso wm_printf() va_arg()
  22167.  
  22168.  
  22169. ■function wm_wrap()
  22170. ■compat emx
  22171. ■headers
  22172. #include <sys/winmgr.h>
  22173. ■endheaders
  22174.  
  22175. ■param WH WRAP_FLAG
  22176. ■prototype
  22177. void wm_wrap (wm_handle WH, int WRAP_FLAG);
  22178. ■endprototype
  22179.  
  22180.     Set the end-of-line wrap mode of window WH.  If WRAP_FLAG is
  22181.     non-zero (which is the default), the cursor is moved to the next
  22182.     line if it reaches the end of a line.  If WRAP_FLAG is zero, the
  22183.     cursor stays at the end of the line.  wm_wrap() applies to
  22184.     wm_putc(), wm_puts(), wm_printf(), etc■.
  22185.  
  22186. ■seealso wm_putc()
  22187.  
  22188.  
  22189. ■function write()
  22190. ■compat POSIX.1
  22191. ■headers
  22192. #include <io.h>
  22193. ■endheaders
  22194.  
  22195. ■param HANDLE BUF NBYTE
  22196. ■prototype
  22197. int write (int HANDLE, const void *BUF, size_t NBYTE);
  22198. ■endprototype
  22199.  
  22200.     Write NBYTE characters from the buffer BUF to the file HANDLE.
  22201.     Writing 0 characters is allowed -- the request will be ignored.
  22202.     In text mode, newline characters are translated to CR/LF pairs.
  22203.  
  22204. ■returnvalue
  22205.  
  22206.     write() returns the number of characters written.  If there is an
  22207.     error, write() returns -1.  Text mode translation does not affect
  22208.     the return value.
  22209.  
  22210. ■errors
  22211. ■description
  22212. ■item EAGAIN
  22213.  
  22214.     The O_NONBLOCK (alias O_NDELAY) flag is set for HANDLE and the
  22215.     process would be suspended in the write operation.
  22216.  
  22217. ■item EBADF
  22218.  
  22219.     The HANDLE argument is not a valid file descriptor.
  22220.  
  22221. ■item EINTR
  22222.  
  22223.     The write operation was interrupted by a caught signal.
  22224.  
  22225. ■item EIO
  22226.  
  22227.     An I/O error occured.  Use _syserrno() for getting the system
  22228.     error code.
  22229.  
  22230. ■item ENOSPC
  22231.  
  22232.     There is no free space remaining on the device containing the file.
  22233.  
  22234. ■item EPIPE
  22235.  
  22236.     An attempt is made to write to a pipe or named pipe that is not
  22237.     open for reading by any process.  A SIGPIPE signal is sent to the
  22238.     process.  This error is returned if the signal does not terminate
  22239.     the process.
  22240.  
  22241. ■enddescription
  22242.  
  22243. ■restrictions
  22244.  
  22245.     In binary mode, partial transfers to disk files (due to lack of
  22246.     disk space) do not occur.  In text mode, partial transfers may
  22247.     occur if the actual number of bytes (with newline translated to
  22248.     CR/LF) written exceeds 1024.
  22249.  
  22250.     PIPE_BUF is ignored: Write operations are atomic for any value of
  22251.     NBYTE in blocking mode; write operations may be non-atomic for any
  22252.     value of NBYTE in non-blocking mode.
  22253.  
  22254.     O_APPEND is subject to race conditions.
  22255.  
  22256. ■seealso open() setmode() read() sigaction() signal()
  22257.  
  22258.  
  22259. ■h1 Variable reference
  22260. ■i1 Variables
  22261.  
  22262.   The variables are listed almost alphabetically.
  22263.  
  22264.  
  22265. ■function daylight
  22266. ■headers
  22267. #include <time.h>
  22268. ■endheaders
  22269.  
  22270. ■prototype
  22271. int daylight;
  22272. ■endprototype
  22273.  
  22274.     This variable is zero if standard time is in effect.  It is
  22275.     non-zero if daylight saving time is in effect.
  22276.  
  22277. ■seealso timezone tzname tzset()
  22278.  
  22279.  
  22280. ■function _emx_env
  22281. ■compat emx
  22282. ■headers
  22283. #include <stdlib.h>
  22284. ■endheaders
  22285.  
  22286. ■prototype
  22287. const unsigned int _emx_env;
  22288. ■endprototype
  22289.  
  22290.     This variable contains bits describing the environment your
  22291.     program is running in:
  22292.  
  22293. ■description
  22294.  
  22295. ■item 0x0001
  22296.  
  22297.     Running under VCPI
  22298.  
  22299. ■item 0x0002
  22300.  
  22301.     Running under XMS
  22302.  
  22303. ■item 0x0004
  22304.  
  22305.     VDISK 3.3 detected
  22306.  
  22307. ■item 0x0008
  22308.  
  22309.     Running under DESQview
  22310.  
  22311. ■item 0x0010
  22312.  
  22313.     287 coprocessor present
  22314.  
  22315. ■item 0x0020
  22316.  
  22317.     387 coprocessor present
  22318.  
  22319. ■item 0x0200
  22320.  
  22321.     Running under OS/2 2.x
  22322.  
  22323. ■item 0x0400
  22324.  
  22325.     File names are truncated (-t option)
  22326.  
  22327. ■item 0x0800
  22328.  
  22329.     Data and stack executable (-ac option under DOS)
  22330.  
  22331. ■item 0x1000
  22332.  
  22333.     Running under RSX
  22334.  
  22335. ■enddescription
  22336.  
  22337.     You should check the 0x0200 bit before calling an OS/2 API
  22338.     function.  You should check the 0x0400 bit when comparing file
  22339.     names.
  22340.  
  22341. ■seealso _osmode
  22342.  
  22343.  
  22344. ■function _emx_rev
  22345. ■compat emx
  22346. ■headers
  22347. #include <stdlib.h>
  22348. ■endheaders
  22349.  
  22350. ■prototype
  22351. const unsigned int _emx_rev;
  22352. ■endprototype
  22353.  
  22354.     This variable contains the emx revision index.  The revision index
  22355.     is a number that is incremented everytime a new emx revision is
  22356.     released.  When the emx version number changes, the revision index
  22357.     is not reset to zero.  If _emx_rev is zero, the revision index is
  22358.     not available because the emx version being in use is too old or
  22359.     the system call library is used.
  22360.  
  22361. ■seealso _emx_vcmp _emx_vprt
  22362.  
  22363.  
  22364. ■function _emx_vcmp
  22365. ■compat emx
  22366. ■headers
  22367. #include <stdlib.h>
  22368. ■endheaders
  22369.  
  22370. ■prototype
  22371. const unsigned int _emx_vcmp;
  22372. ■endprototype
  22373.  
  22374.     This variable contains the emx version number, suitable for
  22375.     comparing.
  22376.  
  22377. ■seealso _emx_rev _emx_vprt
  22378.  
  22379. ■samplecode
  22380. if (_emx_vcmp > 0x302e3861)             /* > 0.8a */
  22381.   {
  22382.     ...
  22383.   }
  22384. ■endsamplecode
  22385.  
  22386.  
  22387. ■function _emx_vprt
  22388. ■compat emx
  22389. ■headers
  22390. #include <stdlib.h>
  22391. ■endheaders
  22392.  
  22393. ■prototype
  22394. const char _emx_vprt[5];
  22395. ■endprototype
  22396.  
  22397.     This variable contains the emx version number, suitable for
  22398.     printing.
  22399.  
  22400. ■seealso _emx_rev _emx_vcmp
  22401.  
  22402. ■samplecode
  22403. printf ("emx version: %s\n", _emx_vprt);
  22404. ■endsamplecode
  22405.  
  22406.  
  22407. ■function environ
  22408. ■compat POSIX.1
  22409.  
  22410. ■prototype
  22411. char **environ;
  22412. ■endprototype
  22413.  
  22414.     A pointer to the current environment of the process.  environ
  22415.     points to an array of pointers to strings.  The array is
  22416.     terminated by a NULL pointer.  After changing the environment with
  22417.     putenv(), you should use this variable instead of the ■pa{ENVP}
  22418.     parameter of main().
  22419.  
  22420. ■implementation
  22421.  
  22422.     environ is declared in <stdlib.h>.
  22423.  
  22424. ■restrictions
  22425.  
  22426.     After changing the value of TZ, you should call tzset().
  22427.  
  22428. ■seealso main() putenv() tzset()
  22429.  
  22430.  
  22431. ■function errno
  22432. ■compat C90
  22433. ■headers
  22434. #include <errno.h>
  22435. ■endheaders
  22436.  
  22437. ■prototype
  22438. int errno;
  22439. ■endprototype
  22440.  
  22441.     When a library function call fails, errno is usually set to a
  22442.     positive value indicating the type of error.  On success, errno is
  22443.     usually not changed.  Note that no library function sets errno to
  22444.     zero.
  22445.  
  22446. ■implementation
  22447.  
  22448.     The following errno values are supported:
  22449.  
  22450. ■example
  22451. Name            │ Value │ Description
  22452. ────────────────┼───────┼──────────────────────────────────
  22453. EPERM           │  1    │ Operation not permitted
  22454. ENOENT          │  2    │ No such file or directory
  22455. ESRCH           │  3    │ No such process
  22456. EINTR           │  4    │ Interrupted system call
  22457. EIO             │  5    │ I/O error
  22458. ENXIO           │  6    │ No such device or address
  22459. E2BIG           │  7    │ Arguments or environment too big
  22460. ENOEXEC         │  8    │ Invalid executable file format
  22461. EBADF           │  9    │ Bad file number
  22462. ECHILD          │  10   │ No children
  22463. EAGAIN          │  11   │ Resource temporarily unavailable
  22464. ENOMEM          │  12   │ Not enough memory
  22465. EACCES          │  13   │ Permission denied
  22466. EFAULT          │  14   │ Bad address
  22467. ENOLCK          │  15   │ No locks available
  22468. EBUSY           │  16   │ Resource busy
  22469. EEXIST          │  17   │ File exists
  22470. EXDEV           │  18   │ Cross-device link
  22471. ENODEV          │  19   │ No such device
  22472. ENOTDIR         │  20   │ Not a directory
  22473. EISDIR          │  21   │ Is a directory
  22474. EINVAL          │  22   │ Invalid argument
  22475. ENFILE          │  23   │ Too many open files in system
  22476. EMFILE          │  24   │ Too many open files
  22477. ENOTTY          │  25   │ Inappropriate ioctl
  22478. EDEADLK         │  26   │ Resource deadlock avoided
  22479. EFBIG           │  27   │ File too large
  22480. ENOSPC          │  28   │ Disk full
  22481. ESPIPE          │  29   │ Illegal seek
  22482. EROFS           │  30   │ Read-only file system
  22483. EMLINK          │  31   │ Too many links
  22484. EPIPE           │  32   │ Broken pipe
  22485. EDOM            │  33   │ Domain error
  22486. ERANGE          │  34   │ Result too large
  22487. ENOTEMPTY       │  35   │ Directory not empty
  22488. EINPROGRESS     │  36   │ Operation now in progress
  22489. ENOSYS          │  37   │ Function not implemented
  22490. ENAMETOOLONG    │  38   │ File name too long
  22491. EDESTADDRREQ    │  39   │ Destination address required
  22492. EMSGSIZE        │  40   │ Message too long
  22493. EPROTOTYPE      │  41   │ Protocol wrong type for socket
  22494. ENOPROTOOPT     │  42   │ Option not supported by protocol
  22495. EPROTONOSUPPORT │  43   │ tocol not supported
  22496. ESOCKTNOSUPPORT │  44   │ ket type not supported
  22497. EOPNOTSUPP      │  45   │ Operation not supported on socket
  22498. EPFNOSUPPORT    │  46   │ Protocol family not supported
  22499. EAFNOSUPPORT    │  47   │ Address family not supported by
  22500.                 │       │ protocol family
  22501. EADDRINUSE      │  48   │ Address already in use
  22502. EADDRNOTAVAIL   │  49   │ an't assigned requested address
  22503. ENETDOWN        │  50   │ Network is down
  22504. ENETUNREACH     │  51   │ Network is unreachable
  22505. ENETRESET       │  52   │ Network dropped connection on reset
  22506. ECONNABORTED    │  53   │ Software caused connection abort
  22507. ECONNRESET      │  54   │ Connection reset by peer
  22508. ENOBUFS         │  55   │ No buffer space available
  22509. EISCONN         │  56   │ Socket is already connected
  22510. ENOTCONN        │  57   │ Socket is not connected
  22511. ESHUTDOWN       │  58   │ Can't send after socket shutdown
  22512. ETOOMANYREFS    │  59   │ Too many references: can't splice
  22513. ETIMEDOUT       │  60   │ Connection timed out
  22514. ECONNREFUSED    │  61   │ Connection refused
  22515. ELOOP           │  62   │ Too many levels of symbolic links
  22516. ENOTSOCK        │  63   │ Socket operation on non-socket
  22517. EHOSTDOWN       │  64   │ Host is down
  22518. EHOSTUNREACH    │  65   │ No route to host
  22519. EALREADY        │  66   │ Operation already in progress
  22520. ■endexample
  22521.  
  22522.     In multithread programs (-Zmt, -Zmts, or -Zmtd), errno is not a
  22523.     global variable; it is an lvalue that depends on the thread
  22524.     number; each thread has its own errno object.
  22525.  
  22526.     To create a library which can be linked to both single-thread and
  22527.     multithread programs, use the option
  22528.  
  22529. ■example
  22530. -D__ST_MT_ERRNO__
  22531. ■endexample
  22532.  
  22533.     on the GCC command line to define errno to call _errno().
  22534.  
  22535. ■seealso _beginthread() _errno() _gettid() perror() strerror() _syserrno() sys_errlist _threadid _threadstore()
  22536.  
  22537.  
  22538. ■function g_xsize g_ysize g_colors
  22539. ■compat emx
  22540. ■headers
  22541. #include <graph.h>
  22542. ■endheaders
  22543.  
  22544. ■prototype
  22545. int g_xsize;
  22546. int g_ysize;
  22547. int g_colors;
  22548. ■endprototype
  22549.  
  22550.     These variables describe the graphics mode selected by g_mode() or
  22551.     g_modeset().  g_xsize is the horizontal resolution (width),
  22552.     g_ysize is the vertical resolution (height), g_colors is the
  22553.     number of distinct colors that can be displayed at a time.
  22554.  
  22555. ■seealso g_mode() g_modeset()
  22556.  
  22557.  
  22558. ■function _osminor _osmajor
  22559. ■compat PC
  22560. ■headers
  22561. #include <stdlib.h>
  22562. ■endheaders
  22563.  
  22564. ■prototype
  22565. const unsigned char _osminor;
  22566. const unsigned char _osmajor;
  22567. ■endprototype
  22568.  
  22569.     These variables contain the minor and major version numbers of the
  22570.     operating system.  For DOS 3.30, _osmajor is 3 and _osminor is
  22571.     30.  For OS/2 2.0, _osmajor is 20, _osminor is 0.  For OS/2 2.1,
  22572.     _osmajor is 20, _osminor is 10.
  22573.  
  22574. ■seealso _emx_env _osmode
  22575.  
  22576. ■samplecode
  22577. printf ("OS version: %d.%d\n", _osmajor, _osminor);
  22578. ■endsamplecode
  22579.  
  22580.  
  22581. ■function _osmode
  22582. ■compat PC
  22583. ■headers
  22584. #include <stdlib.h>
  22585. ■endheaders
  22586.  
  22587. ■prototype
  22588. const unsigned char _osmode;
  22589. ■endprototype
  22590.  
  22591.     This variable contains DOS_MODE if your program is running under
  22592.     DOS or OS2_MODE if your program is running under OS/2.
  22593.  
  22594. ■seealso _emx_env
  22595.  
  22596.  
  22597. ■function stderr stdin stdout
  22598. ■compat C90
  22599. ■headers
  22600. #include <stdio.h>
  22601. ■endheaders
  22602.  
  22603. ■prototype
  22604. FILE *stderr;
  22605. FILE *stdin;
  22606. FILE *stdout;
  22607. ■endprototype
  22608.  
  22609.     stderr, stdin, and stdout are expressions of type `■tt{FILE *}'
  22610.     pointing to the ■tt{FILE} objects associated with the
  22611.     standard error, standard input, and standard output streams,
  22612.     respectively.
  22613.  
  22614. ■hints
  22615.  
  22616.     Note that stderr, stdin, and stdout need not be variables, that
  22617.     is, you cannot use them in initializers and you cannot assign to
  22618.     them.  Use freopen() to associate another stream with stderr,
  22619.     stdin, or stdout.
  22620.  
  22621. ■seealso freopen()
  22622.  
  22623.  
  22624. ■function sys_errlist sys_nerr
  22625. ■headers
  22626. #include <stdlib.h>
  22627. ■endheaders
  22628.  
  22629. ■prototype
  22630. const char * const sys_errlist[];
  22631. const int sys_nerr;
  22632. ■endprototype
  22633.  
  22634.     sys_errlist is an array of error messages indexed by errno values.
  22635.     sys_nerr is the number of elements in the sys_errlist array.
  22636.  
  22637. ■seealso errno perror() strerror()
  22638.  
  22639.  
  22640. ■function _threadid
  22641. ■compat OS/2
  22642. ■headers
  22643. #include <stddef.h>
  22644. ■endheaders
  22645.  
  22646. ■prototype
  22647. unsigned *_threadid;
  22648. ■endprototype
  22649.  
  22650.     _threadid is an lvalue which points to the thread identification
  22651.     number of the current thread as contained in the ■tt{TIB2}
  22652.     structure.  _threadid must not be used under DOS.
  22653.  
  22654. ■seealso _beginthread() _gettid() _threadstore()
  22655.  
  22656.  
  22657. ■function timezone
  22658. ■headers
  22659. #include <time.h>
  22660. ■endheaders
  22661.  
  22662. ■prototype
  22663. long timezone;
  22664. ■endprototype
  22665.  
  22666.     Seconds west of the Prime Meridian.  This variable is set by tzset().
  22667.  
  22668. ■seealso daylight tzname tzset()
  22669.  
  22670.  
  22671. ■function tzname
  22672. ■headers
  22673. #include <time.h>
  22674. ■endheaders
  22675.  
  22676. ■prototype
  22677. char *tzname[2];
  22678. ■endprototype
  22679.  
  22680.     The first pointer points to the name of the local standard
  22681.     timezone.  The second pointer points to the name of the local
  22682.     summer timezone.  This variable is set by tzset().
  22683.  
  22684. ■seealso daylight timezone tzset()
  22685.  
  22686.  
  22687. ■h1 System calls
  22688.  
  22689.   System calls are documented in ■tt{/emx/doc/system.doc}.
  22690.  
  22691.   All system calls are declared in <emx/syscalls.h>.  Interface
  22692.   routines are in the emx.a and emx.lib libraries.  System call
  22693.   emulation routines are in the sys.lib libraries.  Please do not use
  22694.   system calls from application programs -- always use C library
  22695.   functions.  If you need a system call, put a function into the
  22696.   library which issues the system call.
  22697.  
  22698.   Do not use INT 21H: the function numbers and the parameter passing
  22699.   conventions are subject to change.  Similarities to DOS function
  22700.   numbers are just coincidence and will probably disappear.  Moreover,
  22701.   INT 21H, like any software interrupt, cannot be used under OS/2.
  22702.   The goal is to have Unix-like system calls.
  22703.  
  22704. ■text
  22705.  
  22706. --------------------------- END OF EMXLIB.DOC ------------------------------
  22707. ■endtext
  22708.