Index of Topics

- A -
abort
The abort Function
abort_handler_s
abs
access, _access, _waccess
acos
acosh
alloca
Allocating Zero Memory
Analyze Functions
_arc, _arc_w, _arc_wxy
asctime Functions
asctime_s, _wasctime_s
asin
asinh
assert
atan
atan2
atanh
atexit
The atexit Function
atof, _wtof
atoi, _wtoi
atol, _wtol
atoll, _wtoll
_atouni
Attribute Functions

- B -
basename
bcmp
bcopy
bdos
_beginthread, _beginthreadex
Bessel Functions
_bfreeseg
_bgetcmd
_bheapseg
BIOS Functions
_bios_disk
_bios_equiplist
_bios_keybrd
_bios_memsize
_bios_printer
_bios_serialcom
_bios_timeofday
_bprintf, _bwprintf
break...  Functions
bsearch
bsearch_s
btowc
bzero

- C -
C Library Overview
cabs
calloc Functions
cbrt
ceil
cgets
_chain_intr
Character Manipulation Functions
Character Testing
chdir, _chdir, _wchdir
_chdrive
chmod, _chmod, _wchmod
_chsize, chsize
Classes of Functions
Classes of Graphics Functions
_clear87
clearenv
clearerr
_clearscreen
clock
The clock Function
clock_getres
clock_gettime
clock_nanosleep
clock_settime
clone
close, _close
closedir, _wclosedir
_cmdname
_commit
Console I/O Functions
_control87
_controlfp
Conversion Functions
Coordinate System Functions
copysign
cos
cosh
cprintf
cputs
creat, _creat, _wcreat
cscanf
ctime Functions
ctime_s, _wctime_s
cwait, _cwait

- D -
Default Signals
Default Windowing Functions
delay
Deleting Open Files
Diagnostic Printed by the assert Function
_dieeetomsbin
difftime
Directory Functions
dirname
_disable
Display Functions
_displaycursor
div
_dmsbintoieee
Domain Errors
DOS Commands
DOS Considerations
DOS Devices
DOS Directories
DOS File Names
DOS Files
DOS Interrupts
DOS LFN aware Functions
DOS Processes
DOS-Specific Functions
_dos_allocmem
_dos_close
_dos_commit
_dos_creat
_dos_creatnew
_dos_find...  Functions
_dos_freemem
_dos_getdate
_dos_getdiskfree
_dos_getdrive
_dos_getfileattr
_dos_getftime
_dos_gettime
_dos_getvect
_dos_keep
_dos_open
_dos_read
_dos_setblock
_dos_setdate
_dos_setdrive
_dos_setfileattr
_dos_setftime
_dos_settime
_dos_setvect
_dos_write
dosexterr
Drawing Functions
dup, _dup
dup2, _dup2
_dwDeleteOnClose
_dwSetAboutDlg
_dwSetAppTitle
_dwSetConTitle
_dwShutDown
_dwYield

- E -
ecvt, _ecvt, _wecvt
_ellipse, _ellipse_w, _ellipse_wxy
_enable
endhostent
endnetent
endprotoent
endpwent
endservent
_endthread, _endthreadex
Environment Functions
Environment Names
_eof, eof
erf
erfc
exec...  Functions
exit
_Exit, _exit
exp
exp2
_expand Functions
expm1

- F -
fabs
fclose
fcloseall
fcvt, _fcvt, _wfcvt
fdim
fdopen, _fdopen, _wfdopen
feclearexcept
fedisableexcept, __fedisableexcept
feenableexcept, __feenableexcept
fegetenv
fegetexceptflag
fegetround
feholdexcept
feof
feraiseexcept
ferror
fesetenv
fesetexceptflag
fesetround
fetestexcept
feupdateenv
fflush
ffs
fgetc, fgetwc
fgetchar, _fgetchar, _fgetwchar
fgetpos
fgets, fgetws
_fieeetomsbin
File Access Limits
File Buffering
File Manipulation Functions
File Names
File Position Errors
File Position in Append Mode
_filelength, _filelengthi64, filelength
FILENAME_MAX
fileno
_findclose
_findfirst, _findfirsti64, _wfindfirst, _wfindfirsti64
_findnext, _findnexti64, _wfindnext, _wfindnexti64
_finite
_floodfill, _floodfill_w
floor
_flushall, flushall
fma
fmax
fmin
fmod
The fmod Function
_fmsbintoieee
fnmatch
Font Manipulation Functions
fopen, _wfopen
fopen_s, _wfopen_s
FP_OFF
FP_SEG
fpclassify
_fpreset
fprintf, fwprintf
fprintf_s, fwprintf_s
fputc, fputwc
fputchar, _fputchar, _fputwchar
fputs, fputws
fread
free Functions
_freect
freopen, _wfreopen
freopen_s, _wfreopen_s
frexp
fscanf, fwscanf
fscanf_s, fwscanf_s
fseek
fsetpos
_fsopen, _wfsopen
fstat, _fstat, _fstati64
fsync
ftell
ftime
_fullpath, _wfullpath
fwide
fwrite

- G -
gcvt, _gcvt, _wgcvt
_get_osfhandle
_getactivepage
_getarcinfo
_getbkcolor
getc, getwc
getch
getchar, getwchar
getche
_getcliprgn
getcmd
_getcolor
_getcurrentposition, _getcurrentposition_w
getcwd, _wgetcwd
_getdcwd, _wgetdcwd
getdelim
_getdiskfree
_getdrive
getegid
getenv, _wgetenv
getenv_s
geteuid
_getfillmask
_getfontinfo
getgid
_getgtextextent
_getgtextvector
gethostbyaddr
gethostbyname
gethostent
_getimage, _getimage_w, _getimage_wxy
getline
_getlinestyle
_getmbcp
getnetbyaddr
getnetbyname
getnetent
getopt
getpgrp
_getphyscoord
getpid, _getpid
_getpixel, _getpixel_w
_getplotaction
getppid
getprotobyname
getprotobynumber
getprotoent
getpwent
getpwnam
getpwuid
gets, _getws
gets_s
getservbyname
getservbyport
getservent
_gettextcolor
_gettextcursor
_gettextextent
_gettextposition
_gettextsettings
_gettextwindow
gettid
getuid
_getvideoconfig
_getviewcoord, _getviewcoord_w, _getviewcoord_wxy
_getvisualpage
_getw
_getwindowcoord
Global Data
gmtime Functions
gmtime_s
Graphics Adapters
Graphics Functions
Graphics Header Files
Graphics Library
Graphics Text Functions
_grow_handles
_grstatus
_grtext, _grtext_w

- H -
halloc
_harderr, _hardresume, _hardretn
_hdopen
Header Files
Header Files in /watcom/h
Header Files in /watcom/h/sys
Heap Functions
_heapchk Functions
_heapenable
_heapgrow Functions
_heapmin Functions
_heapset Functions
_heapshrink Functions
_heapwalk Functions
hfree
hypot

- I -
ignore_handler_s
ilogb
Image Manipulation Functions
_imagesize, _imagesize_w, _imagesize_wxy
imaxabs
imaxdiv
Implementation-Defined Behavior of the C Library
inp
inpd
inpw
int386
int386x
int86
int86x
intdos
intdosx
Intel 80x86 Architecture-Specific Functions
Intel Pentium Multimedia Extension Functions
intr
intrf
isalnum, iswalnum
isalpha, iswalpha
isascii, __isascii, iswascii
isatty, _isatty
isblank, iswblank
iscntrl, iswcntrl
iscsym, __iscsym, __iswcsym
iscsymf, __iscsymf, __iswcsymf
isdigit, iswdigit
isfinite
isgraph, iswgraph
isinf
isleadbyte
islower, iswlower
_ismbbalnum
_ismbbalpha
_ismbbgraph
_ismbbkalnum
_ismbbkalpha
_ismbbkana
_ismbbkprint
_ismbbkpunct
_ismbblead
_ismbbprint
_ismbbpunct
_ismbbtrail
_ismbcalnum
_ismbcalpha
_ismbccntrl
_ismbcdigit
_ismbcgraph
_ismbchira
_ismbckata
_ismbcl0
_ismbcl1
_ismbcl2
_ismbclegal
_ismbclower
_ismbcprint
_ismbcpunct
_ismbcspace
_ismbcsymbol
_ismbcupper
_ismbcxdigit
isnan
isnormal
isprint, iswprint
ispunct, iswpunct
isspace, iswspace
isupper, iswupper
iswctype
isxdigit, iswxdigit
itoa, _itoa, _itow

- K -
kbhit, _kbhit

- L -
labs
ldexp
ldiv
lfind
lgamma
lgamma_r
Library Functions and Macros
_lineto, _lineto_w
llabs
lldiv
lltoa, _lltoa, _lltow
localeconv
localtime Functions
localtime_s
lock
locking, _locking
log
log10
log1p
log2
logb
longjmp
_lrotl
_lrotr
lsearch
lseek, _lseek, _lseeki64
ltoa, _ltoa, _ltow

- M -
_m_empty
_m_from_int
_m_packssdw
_m_packsswb
_m_packuswb
_m_paddb
_m_paddd
_m_paddsb
_m_paddsw
_m_paddusb
_m_paddusw
_m_paddw
_m_pand
_m_pandn
_m_pcmpeqb
_m_pcmpeqd
_m_pcmpeqw
_m_pcmpgtb
_m_pcmpgtd
_m_pcmpgtw
_m_pmaddwd
_m_pmulhw
_m_pmullw
_m_por
_m_pslld
_m_pslldi
_m_psllq
_m_psllqi
_m_psllw
_m_psllwi
_m_psrad
_m_psradi
_m_psraw
_m_psrawi
_m_psrld
_m_psrldi
_m_psrlq
_m_psrlqi
_m_psrlw
_m_psrlwi
_m_psubb
_m_psubd
_m_psubsb
_m_psubsw
_m_psubusb
_m_psubusw
_m_psubw
_m_punpckhbw
_m_punpckhdq
_m_punpckhwd
_m_punpcklbw
_m_punpckldq
_m_punpcklwd
_m_pxor
_m_to_int
main, wmain, WinMain, wWinMain
_makepath, _wmakepath
malloc Functions
Math Functions
matherr
max
_mbbtombc
_mbbtype
_mbccmp, _fmbccmp
_mbccpy, _fmbccpy
_mbcicmp, _fmbcicmp
_mbcjistojms
_mbcjmstojis
_mbclen, _fmbclen
_mbctohira
_mbctokata
_mbctolower
_mbctombb
_mbctoupper
_mbgetcode, _fmbgetcode
mblen, _fmblen
_mbputchar, _fmbputchar
mbrlen, _fmbrlen
mbrtowc, _fmbrtowc
_mbsbtype, _fmbsbtype
_mbsdec, _fmbsdec, _strdec, _wcsdec
_mbsinc, _fmbsinc, _strinc, _wcsinc
mbsinit, sisinit
_mbsnbcat, _fmbsnbcat
_mbsnbcmp, _fmbsnbcmp
_mbsnbcnt, _fmbsnbcnt, _mbsnccnt, _fmbsnccnt, _strncnt, _wcsncnt
_mbsnbcpy, _fmbsnbcpy
_mbsnbicmp, _fmbsnbicmp
_mbsnbset, _fmbsnbset
_mbsnextc, _fmbsnextc, _strnextc, _wcsnextc
_mbsninc, _fmbsninc, _strninc, _wcsninc
mbsrtowcs, _fmbsrtowcs
mbsrtowcs_s, _fmbsrtowcs_s
_mbsspnp, _fmbsspnp, _strspnp, _wcsspnp
mbstowcs, _fmbstowcs
mbstowcs_s, _fmbstowcs_s
_mbterm, _fmbterm
mbtowc, _fmbtowc
_mbvtop, _fmbvtop
_memavl
memccpy, _fmemccpy, _memccpy
memchr, _fmemchr, wmemchr
memcmp, _fmemcmp, wmemcmp
memcpy, _fmemcpy, wmemcpy
memcpy_s, wmemcpy_s
_memicmp, _fmemicmp, memicmp
_memmax
memmove, _fmemmove, wmemmove
memmove_s, wmemmove_s
Memory Allocation Functions
Memory Manipulation Functions
memset, _fmemset, wmemset
Messages Generated by the perror Function
min
Miscellaneous Functions
MK_FP
mkdir, _mkdir, _wmkdir
mkstemp
_mktemp, _wmktemp
mktime
mlock
mlockall
mmap
modf
movedata
_moveto, _moveto_w
mprotect
_msize Functions
msync
Multibyte Character Manipulation Functions
Multibyte String Manipulation Functions
munlock
munlockall
munmap

- N -
nan
nearbyint
nextafter
nl_langinfo
nosound
Null Characters
NULL Macro

- O -
offsetof
_onexit, onexit
open, _open, _wopen
_open_osfhandle
opendir, _wopendir
Operating System I/O Functions
The OS/2 TZ Environment Variable
_os_handle
_outgtext
_outmem
outp
outpd
outpw
_outtext

- P -
pclose
_pclose
perror, _wperror
_pg_analyzechart, _pg_analyzechartms
_pg_analyzepie
_pg_analyzescatter, _pg_analyzescatterms
_pg_chart, _pg_chartms
_pg_chartpie
_pg_chartscatter, _pg_chartscatterms
_pg_defaultchart
_pg_getchardef
_pg_getpalette
_pg_getstyleset
_pg_hlabelchart
_pg_initchart
_pg_resetpalette
_pg_resetstyleset
_pg_setchardef
_pg_setpalette
_pg_setstyleset
_pg_vlabelchart
_pie, _pie_w, _pie_wxy
_pipe
_polygon, _polygon_w, _polygon_wxy
popen
_popen, _wpopen
pow
Presentation Graphics Functions
printf, wprintf
printf_s, wprintf_s
Printing Pointer Values
Process Environment
Process Primitive Functions
putc, putwc
putch
putchar, putwchar
putenv, _putenv, _wputenv
_putimage, _putimage_w
puts, _putws
_putw

- Q -
qsort
qsort_s

- R -
raise
rand
Re-entrant Functions
read, _read, readv
readdir, _wreaddir
Reading Pointer Values
Reading Ranges
readlink
realloc Functions
_rectangle, _rectangle_w, _rectangle_wxy
_registerfonts
remainder
_remapallpalette
_remappalette
remove, _wremove
rename, _wrename
Renaming with a Name that Exists
rewind
rewinddir, _wrewinddir
rint
rmdir, _rmdir, _wrmdir
_rotl
_rotr
round

- S -
sbrk
scalbn
scanf, wscanf
scanf_s, wscanf_s
sched_get_priority_max
sched_get_priority_min
sched_getparam
sched_getscheduler
sched_rr_get_interval
sched_setparam
sched_setscheduler
sched_yield
_scrolltextwindow
_searchenv, _wsearchenv
Searching Functions
segread
_selectpalette
sem_destroy
sem_getvalue
sem_init
sem_post
sem_trywait
sem_wait
set_constraint_handler_s
_set_matherr
set_new_handler, _set_new_handler
_setactivepage
_setbkcolor
setbuf
_setcharsize, _setcharsize_w
_setcharspacing, _setcharspacing_w
_setcliprgn
_setcolor
setenv, _setenv, _wsetenv
_setfillmask
_setfont
_setgtextvector
sethostent
setjmp
_setlinestyle
setlocale, _wsetlocale
_setmbcp
_setmode, setmode
setnetent
_setpixel, _setpixel_w
_setplotaction
setprotoent
setpwent
setservent
_settextalign
_settextcolor
_settextcursor
_settextorient
_settextpath
_settextposition
_settextrows
_settextwindow
setvbuf
_setvideomode
_setvideomoderows
_setvieworg
_setviewport
_setvisualpage
_setwindow
The SIGILL Signal
signal
The signal Function
signbit
sin
sinh
sleep
_snprintf, _snwprintf
snprintf, snwprintf
snprintf_s, snwprintf_s
_sopen, _wsopen, sopen
sound
Space Characters
spawn...  Functions
_splitpath, _wsplitpath
_splitpath2, _wsplitpath2
sprintf, swprintf
sprintf_s, swprintf_s
sqrt
srand
sscanf, swscanf
sscanf_s, swscanf_s
stackavail, _stackavail
stat, _stat, _stati64, _wstat, _wstati64, lstat
_status87
strcasecmp
strcat, _fstrcat, wcscat, _mbscat, _fmbscat
strcat_s, wcscat_s
strchr, _fstrchr, wcschr, _mbschr, _fmbschr
strcmp, _fstrcmp, wcscmp, _mbscmp, _fmbscmp
strcmpi, wcscmpi
strcoll, wcscoll, _mbscoll
strcpy, _fstrcpy, wcscpy, _mbscpy, _fmbscpy
strcpy_s, wcscpy_s
strcspn, _fstrcspn, wcscspn, _mbscspn, _fmbscspn
_strdate, _wstrdate
strdup, _strdup, _fstrdup, wcsdup, _wcsdup, _mbsdup, _fmbsdup
Stream I/O Functions
The strerror Function
strerror, _wcserror
strerror_s, _wcserror_s
strerrorlen_s, _wcserrorlen_s
strftime, wcsftime, _wstrftime_ms
_stricmp, _fstricmp, _wcsicmp, _mbsicmp, _fmbsicmp, stricmp
_stricoll, _wcsicoll, _mbsicoll
String Manipulation Functions
strlcat, wcslcat
strlcpy, wcslcpy
strlen, _fstrlen, wcslen, _mbslen, _fmbslen
_strlwr, _fstrlwr, _wcslwr, _mbslwr, _fmbslwr, strlwr
strncasecmp
strncat, _fstrncat, wcsncat, _mbsncat, _fmbsncat
strncat_s, wcsncat_s
strncmp, _fstrncmp, wcsncmp, _mbsncmp, _fmbsncmp
_strncoll, _wcsncoll, _mbsncoll
strncpy, _fstrncpy, wcsncpy, _mbsncpy, _fmbsncpy
strncpy_s, wcsncpy_s
_strnicmp, _fstrnicmp, _wcsnicmp, _mbsnicmp, _fmbsnicmp, strnicmp
_strnicoll, _wcsnicoll, _mbsnicoll
strnlen_s, wcsnlen_s
_strnset, _fstrnset, _wcsnset, _mbsnset, _fmbsnset, strnset, wcsnset
strpbrk, _fstrpbrk, wcspbrk, _mbspbrk, _fmbspbrk
strrchr, _fstrrchr, wcsrchr, _mbsrchr, _fmbsrchr
_strrev, _fstrrev, _wcsrev, _mbsrev, _fmbsrev, strrev
_strset, _fstrset, _wcsset, _mbsset, _fmbsset, strset
strspn, _fstrspn, wcsspn, _mbsspn, _fmbsspn
strspnp, _fstrspnp
strstr, _fstrstr, wcsstr, _mbsstr, _fmbsstr
_strtime, _wstrtime
strtod, wcstod
strtoimax, wcstoimax
strtok, strtok_r, _fstrtok, _fstrtok_r, wcstok, _mbstok, _mbstok_r, _fmbstok, _fmbstok_r
strtok_s, wcstok_s
strtol, wcstol
strtoll, wcstoll
strtoul, wcstoul
strtoull, wcstoull
strtoumax, wcstoumax
_strupr, _fstrupr, _wcsupr, _mbsupr, _fmbsupr, strupr
strxfrm, wcsxfrm
swab
sysconf
sysinfo
The system Function
system, _wsystem

- T -
tan
tanh
_tell, _telli64, tell
_tempnam, _wtempnam
Terminating Newline Characters
Text Functions
tgamma
time
Time Functions
The Time Zone
timer_create
timer_delete
timer_getoverrun
timer_gettime
timer_settime
tmpfile
tmpfile_s
tmpnam, _wtmpnam
tmpnam_s, _wtmpnam_s
tolower, _tolower, towlower
toupper, _toupper, towupper
towctrans
trunc
Truncation of Text Files
ttyname, ttyname_r
The TZ Environment Variable
tzset

- U -
ulltoa, _ulltoa, _ulltow
ultoa, _ultoa, _ultow
umask, _umask
Underflow of Floating-Point Values
ungetc, ungetwc
ungetch
unlink, _unlink, _wunlink
unlock
_unregisterfonts
unsetenv, _wunsetenv
Utility Functions
utime, _utime, _wutime
utoa, _utoa, _utow

- V -
va_arg
va_end
va_start
Variable-length Argument Lists
_vbprintf, _vbwprintf
vcprintf
vcscanf
vfprintf, vfwprintf
vfprintf_s, vfwprintf_s
vfscanf, vfwscanf
vfscanf_s, vfwscanf_s
vprintf, vwprintf
vprintf_s, vwprintf_s
vscanf, vwscanf
vscanf_s, vwscanf_s
_vsnprintf, _vsnwprintf
vsnprintf, vsnwprintf
vsnprintf_s, vsnwprintf_s
vsprintf, vswprintf
vsprintf_s, vswprintf_s
vsscanf, vswscanf
vsscanf_s, vswscanf_s

- W -
wait
wcrtomb, _fwcrtomb
wcrtomb_s, _fwcrtomb_s
wcsrtombs, _fwcsrtombs
wcsrtombs_s, _fwcsrtombs_s
wcstombs, _fwcstombs
wcstombs_s, _fwcstombs_s
wctob
wctomb, _fwctomb
wctomb_s, _fwctomb_s
wctrans
wctype
Wide Character Manipulation Functions
Wide Character Stream I/O Functions
Wide String Manipulation Functions
_wrapon
write, _write, writev

- Z -
Zero-Length Files

C Library Overview


The C library provides much of the power usually associated with the C language.  This chapter introduces the individual functions (and macros) that comprise the Open Watcom C library.  The chapter Library Functions and Macros describes each function and macro in complete detail.

Library functions are called as if they had been defined within the program.  When the program is linked, the code for these routines is incorporated into the program by the linker.

Strictly speaking, it is not necessary to declare most library functions since they return int values for the most part.  It is preferred, however, to declare all functions by including the header files found in the synopsis section with each function.  Not only does this declare the return value, but also the type expected for each of the arguments as well as the number of arguments.  This enables the Open Watcom C and C++ compilers to check the arguments coded with each function call.

Classes of Functions


The functions in the Open Watcom C library can be organized into a number of classes:
Character Manipulation Functions

These functions deal with single characters.

Wide Character Manipulation Functions

These functions deal with wide characters.

Multibyte Character Manipulation Functions

These functions deal with multibyte characters.

Memory Manipulation Functions

These functions manipulate blocks of memory.

String Manipulation Functions

These functions manipulate strings of characters.  A character string is an array of zero or more adjacent characters followed by a null character ('\0') which marks the end of the string.

Wide String Manipulation Functions

These functions manipulate strings of wide characters.  A wide character string is an array of zero or more adjacent wide characters followed by a null wide character (L'\0') which marks the end of the wide string.

Multibyte String Manipulation Functions

These functions manipulate strings of multibyte characters.  A multibyte character is either a single-byte or double-byte character.  The Chinese, Japanese and Korean character sets are examples of character sets containing both single-byte and double-byte characters.
What determines whether a character is a single-byte or double-byte character is the value of the lead byte in the sequence.   For example, in the Japanese DBCS (double-byte character set), double-byte characters are those in which the first byte falls in the range 0x81 - 0x9F or 0xE0 - 0xFC and the second byte falls in the range 0x40 - 0x7E or 0x80 - 0xFC.  A string of multibyte characters must be scanned from the first byte (index 0) to the last byte (index n) in sequence in order to determine if a particular byte is part of a double-byte character.  For example, suppose that a multibyte character string contains the following byte values.

     
     0x31 0x40 0x41 0x81 0x41 // "1@A.." where .. is a DB char

Among other characters, it contains the letter "A" (the first 0x41) and a double-byte character (0x81 0x41).   The second 0x41 is not the letter "A" and that could only be determined by scanning from left to right starting with the first byte (0x31).

Conversion Functions

These functions convert values from one representation to another.  Numeric values, for example, can be converted to strings.

Memory Allocation Functions

These functions are concerned with allocating and deallocating memory.

Heap Functions

These functions provide the ability to shrink and grow the heap, as well as, find heap related problems.

Math Functions

The mathematical functions perform mathematical computations such as the common trigonometric calculations.  These functions operate on double values, also known as floating-point values.

Searching Functions

These functions provide searching and sorting capabilities.

Time Functions

These functions provide facilities to obtain and manipulate times and dates.

Variable-length Argument Lists

These functions provide the capability to process a variable number of arguments to a function.

Stream I/O Functions

These functions provide the "standard" functions to read and write files.  Data can be transmitted as characters, strings, blocks of memory or under format control.

Wide Character Stream I/O Functions

These functions provide the "standard" functions to read and write files of wide characters.  Data can be transmitted as wide characters, wide character strings, blocks of memory or under format control.

Process Primitive Functions

These functions deal with process creation, execution and termination, signal handling, and timer operations.

Process Environment

These functions deal with process identification, user identification, process groups, system identification, system time and process time, environment variables, terminal identification, and configurable system variables.

Directory Functions

These functions provide directory services.

Operating System I/O Functions

These "non-standard" file operations are more primitive than the "standard" functions in that they are directly interfaced to the operating system.  They are included to provide compatibility with other C implementations and to provide the capability to directly use operating-system file operations.

File Manipulation Functions

These functions operate directly on files, providing facilities such as deletion of files.

Console I/O Functions

These functions provide the capability to directly read and write characters from the console.

Default Windowing Functions

These functions provide the capability to manipulate various dialog boxes in Open Watcom's default windowing system.

BIOS Functions

This set of functions allows access to services provided by the BIOS.

DOS-Specific Functions

This set of functions allows access to DOS-specific functions.

Intel 80x86 Architecture-Specific Functions

This set of functions allows access to Intel 80x86 processor-related functions.

Intel Pentium Multimedia Extension Functions

This set of functions allows access to Intel Architecture Multimedia Extensions (MMX).

Miscellaneous Functions

This collection consists of the remaining functions.

DOS LFN aware Functions

These functions are DOS LFN capable.

The following subsections describe these function classes in more detail.  Each function in the class is noted with a brief description of its purpose.  The chapter Library Functions and Macros provides a complete description of each function and macro.

Character Manipulation Functions


These functions operate upon single characters of type char.  The functions test characters in various ways and convert them between upper and lowercase.  The following functions are defined:
isalnum
test for letter or digit

isalpha
test for letter

isascii
test for ASCII character

isblank
test for blank character

iscntrl
test for control character

__iscsym
test for letter, underscore or digit

__iscsymf
test for letter or underscore

isdigit
test for digit

isgraph
test for printable character, except space

islower
test for letter in lowercase

isprint
test for printable character, including space

ispunct
test for punctuation characters

isspace
test for "white space" characters

isupper
test for letter in uppercase

isxdigit
test for hexadecimal digit

tolower
convert character to lowercase

toupper
convert character to uppercase

Wide Character Manipulation Functions


These functions operate upon wide characters of type wchar_t.  The functions test wide characters in various ways and convert them between upper and lowercase.  The following functions are defined:
iswalnum
test for letter or digit

iswalpha
test for letter

iswascii
test for ASCII character

iswblank
test for blank character

iswcntrl
test for control character

__iswcsym
test for letter, underscore or digit

__iswcsymf
test for letter or underscore

iswdigit
test for digit

iswgraph
test for printable character, except space

iswlower
test for letter in lowercase

iswprint
test for printable character, including space

iswpunct
test for punctuation characters

iswspace
test for "white space" characters

iswupper
test for letter in uppercase

iswxdigit
test for hexadecimal digit

wctype
construct a property value for a given "property"

iswctype
test a character for a specific property

towlower
convert character to lowercase

towupper
convert character to uppercase

wctrans
construct mapping value for a given "property"

towctrans
convert a character based on a specific property

Multibyte Character Manipulation Functions


These functions operate upon multibyte characters.  The functions test wide characters in various ways and convert them between upper and lowercase.  The following functions are defined:
_fmbccmp
compare one multibyte character with another

_fmbccpy
copy one multibyte character from one string to another

_fmbcicmp
compare one multibyte character with another (case insensitive)

_fmbclen
return number of bytes comprising multibyte character

_fmblen
determine length of next multibyte character

_fmbgetcode
get next single-byte or double-byte character from far string

_fmbputchar
store single-byte or double-byte character into far string

_fmbrlen
determine length of next multibyte character

_fmbrtowc
convert far multibyte character to wide character

_fmbsbtype
return type of byte in multibyte character string

_fmbtowc
convert far multibyte character to wide character

_ismbbalnum
test for isalnum or _ismbbkalnum

_ismbbalpha
test for isalpha or _ismbbkalpha

_ismbbgraph
test for isgraph or _ismbbkprint

_ismbbkalnum
test for non-ASCII text symbol other than punctuation

_ismbbkana
test for single-byte Katakana character

_ismbbkalpha
test for non-ASCII text symbol other than digits or punctuation

_ismbbkprint
test for non-ASCII text or non-ASCII punctuation symbol

_ismbbkpunct
test for non-ASCII punctuation character

_ismbblead
test for valid first byte of multibyte character

_ismbbprint
test for isprint or _ismbbkprint

_ismbbpunct
test for ispunct or _ismbbkpunct

_ismbbtrail
test for valid second byte of multibyte character

_ismbcalnum
test for _ismbcalpha or _ismbcdigit

_ismbcalpha
test for a multibyte alphabetic character

_ismbccntrl
test for a multibyte control character

_ismbcdigit
test for a multibyte decimal-digit character '0' through '9'

_ismbcgraph
test for a printable multibyte character except space

_ismbchira
test for a double-byte Hiragana character

_ismbckata
test for a double-byte Katakana character

_ismbcl0
test for a double-byte non-Kanji character

_ismbcl1
test for a JIS level 1 double-byte character

_ismbcl2
test for a JIS level 2 double-byte character

_ismbclegal
test for a valid multibyte character

_ismbclower
test for a valid lowercase multibyte character

_ismbcprint
test for a printable multibyte character including space

_ismbcpunct
test for any multibyte punctuation character

_ismbcspace
test for any multibyte space character

_ismbcsymbol
test for valid multibyte symbol (punctuation and other special graphics)

_ismbcupper
test for valid uppercase multibyte character

_ismbcxdigit
test for any multibyte hexadecimal-digit character

_mbbtombc
return double-byte equivalent to single-byte character

_mbbtype
determine type of byte in multibyte character

_mbccmp
compare one multibyte character with another

_mbccpy
copy one multibyte character from one string to another

_mbcicmp
compare one multibyte character with another (case insensitive)

_mbcjistojms
convert JIS code to shift-JIS code

_mbcjmstojis
convert shift-JIS code to JIS code

_mbclen
return number of bytes comprising multibyte character

_mbctolower
convert double-byte uppercase character to double-byte lowercase character

_mbctoupper
convert double-byte lowercase character to double-byte uppercase character

_mbctohira
convert double-byte Katakana character to Hiragana character

_mbctokata
convert double-byte Hiragana character to Katakana character

_mbctombb
return single-byte equivalent to double-byte character

_mbgetcode
get next single-byte or double-byte character from string

mblen
determine length of next multibyte character

_mbputchar
store single-byte or double-byte character into string

mbrlen
determine length of next multibyte character

mbrtowc
convert multibyte character to wide character

_mbsbtype
return type of byte in multibyte character string

mbsinit
determine if mbstate_t object describes an initial conversion state

mbtowc
convert multibyte character to wide character

Memory Manipulation Functions


These functions manipulate blocks of memory.  In each case, the address of the memory block and its size is passed to the function.  The functions that begin with "_f" accept far pointers as their arguments allowing manipulation of any memory location regardless of which memory model your program has been compiled for.  The following functions are defined:
_fmemccpy
copy far memory block up to a certain character

_fmemchr
search far memory block for a character value

_fmemcmp
compare any two memory blocks (near or far)

_fmemcpy
copy far memory block, overlap not allowed

_fmemicmp
compare far memory, case insensitive

_fmemmove
copy far memory block, overlap allowed

_fmemset
set any memory block (near of far) to a character

memccpy
copy memory block up to a certain character

memchr
search memory block for a character value

memcmp
compare memory blocks

memcpy
copy memory block, overlap not allowed

_memicmp
compare memory, case insensitive

memmove
copy memory block, overlap allowed

memset
set memory block to a character

movedata
copy memory block, with segment information

swab
swap bytes of a memory block

wmemchr
search memory block for a wide character value

wmemcmp
compare memory blocks

wmemcpy
copy memory block, overlap not allowed

wmemmove
copy memory block, overlap allowed

wmemset
set memory block to a wide character

See the section "String Manipulation Functions" for descriptions of functions that manipulate strings of data.  See the section "Wide String Manipulation Functions" for descriptions of functions that manipulate wide strings of data.

String Manipulation Functions


A string is an array of characters (with type char) that is terminated with an extra null character ('\0').  Functions are passed only the address of the string since the size can be determined by searching for the terminating null character.  The functions that begin with "_f" accept far pointers as their arguments allowing manipulation of any memory location regardless of which memory model your program has been compiled for.   The following functions are defined:
bcmp
** deprecated ** compare two byte strings

bcopy
** deprecated ** copy a byte string

_bprintf
formatted transmission to fixed-length string

bzero
** deprecated ** zero a byte string

_fstrcat
concatenate two far strings

_fstrchr
locate character in far string

_fstrcmp
compare two far strings

_fstrcpy
copy far string

_fstrcspn
get number of string characters not from a set of characters

_fstricmp
compare two far strings with case insensitivity

_fstrlen
length of a far string

_fstrlwr
convert far string to lowercase

_fstrncat
concatenate two far strings, up to a maximum length

_fstrncmp
compare two far strings up to maximum length

_fstrncpy
copy a far string, up to a maximum length

_fstrnicmp
compare two far strings with case insensitivity up to a maximum length

_fstrnset
fill far string with character to a maximum length

_fstrpbrk
locate occurrence of a string within a second string

_fstrrchr
locate last occurrence of character from a character set

_fstrrev
reverse a far string in place

_fstrset
fill far string with a character

_fstrspn
find number of characters at start of string which are also in a second string

_fstrstr
find first occurrence of string in second string

_fstrtok
get next token from a far string

_fstrupr
convert far string to uppercase

sprintf
formatted transmission to string

sscanf
scan from string under format control

strcat
concatenate string

strchr
locate character in string

strcmp
compare two strings

strcmpi
** deprecated ** compare two strings with case insensitivity

strcoll
compare two strings using "locale" collating sequence

strcpy
copy a string

strcspn
get number of string characters not from a set of characters

_strdec
returns pointer to the previous character in string

strdup
allocate and duplicate a string

strerror
get error message as string

_stricmp
compare two strings with case insensitivity

_strinc
return pointer to next character in string

strlcat
concatenate string into a bounded buffer

strlcpy
copy string into a bounded buffer

strlen
string length

_strlwr
convert string to lowercase

strncat
concatenate two strings, up to a maximum length

strncmp
compare two strings up to maximum length

_strncnt
count the number of characters in the first "n" bytes

strncpy
copy a string, up to a maximum length

_strnextc
return integer value of the next character in string

_strnicmp
compare two strings with case insensitivity up to a maximum length

_strninc
increment character pointer by "n" characters

_strnset
fill string with character to a maximum length

strpbrk
locate occurrence of a string within a second string

strrchr
locate last occurrence of character from a character set

_strrev
reverse a string in place

_strset
fill string with a character

strspn
find number of characters at start of string which are also in a second string

_strspnp
return pointer to first character of string not in set

strstr
find first occurrence of string in second string

strtok
get next token from string

_strupr
convert string to uppercase

strxfrm
transform string to locale's collating sequence

_vbprintf
same as "_bprintf" but with variable arguments

vsscanf
same as "sscanf" but with variable arguments

For related functions see the sections Conversion Functions (conversions to and from strings), Time Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without terminating null character).

Wide String Manipulation Functions


A wide string is an array of wide characters (with type wchar_t) that is terminated with an extra null wide character (L'\0').  Functions are passed only the address of the string since the size can be determined by searching for the terminating null character.  The functions that begin with "_f" accept far pointers as their arguments allowing manipulation of any memory location regardless of which memory model your program has been compiled for.  The following functions are defined:
_bwprintf
formatted wide character transmission to fixed-length wcsing

swprintf
formatted wide character transmission to string

swscanf
scan from wide character string under format control

_vbwprintf
same as "_bwprintf" but with variable arguments

vswscanf
same as "swscanf" but with variable arguments

wcscat
concatenate string

wcschr
locate character in string

wcscmp
compare two strings

wcscmpi
** deprecated ** compare two strings with case insensitivity

wcscoll
compare two strings using "locale" collating sequence

wcscpy
copy a string

wcscspn
get number of string characters not from a set of characters

_wcsdec
returns pointer to the previous character in string

wcsdup
allocate and duplicate a string

_wcserror
get error message as string

_wcsicmp
compare two strings with case insensitivity

_wcsinc
return pointer to next character in string

wcslcat
concatenate string into a bounded buffer

wcslcpy
copy string into a bounded buffer

wcslen
string length

_wcslwr
convert string to lowercase

wcsncat
concatenate two strings, up to a maximum length

wcsncmp
compare two strings up to maximum length

_wcsncnt
count the number of characters in the first "n" bytes

wcsncpy
copy a string, up to a maximum length

_wcsnextc
return integer value of the next multi-byte character in string

_wcsnicmp
compare two strings with case insensitivity up to a maximum length

_wcsninc
increment wide character pointer by "n" characters

_wcsnset
fill string with character to a maximum length

wcspbrk
locate occurrence of a string within a second string

wcsrchr
locate last occurrence of character from a character set

_wcsrev
reverse a string in place

_wcsset
fill string with a character

wcsspn
find number of characters at start of string which are also in a second string

_wcsspnp
return pointer to first character of string not in set

wcsstr
find first occurrence of string in second string

wcstok
get next token from string

_wcsupr
convert string to uppercase

wcsxfrm
transform string to locale's collating sequence

For related functions see the sections Conversion Functions (conversions to and from strings), Time Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without terminating null character).

Multibyte String Manipulation Functions


A wide string is an array of wide characters (with type wchar_t) that is terminated with an extra null wide character (L'\0').  Functions are passed only the address of the wide string since the size can be determined by searching for the terminating null character.  The functions that begin with "_f" accept far pointers as their arguments allowing manipulation of any memory location regardless of which memory model your program has been compiled for.  The following functions are defined:
btowc
return wide character version of single-byte character

_fmbscat
concatenate two far strings

_fmbschr
locate character in far string

_fmbscmp
compare two far strings

_fmbscpy
copy far string

_fmbscspn
get number of string characters not from a set of characters

_fmbsdec
returns far pointer to the previous character in far string

_fmbsdup
allocate and duplicate a far string

_fmbsicmp
compare two far strings with case insensitivity

_fmbsinc
return far pointer to next character in far string

_fmbslen
length of a far string

_fmbslwr
convert far string to lowercase

_fmbsnbcat
append up to "n" bytes of string to another string

_fmbsnbcmp
compare up to "n" bytes in two strings

_fmbsnbcnt
count the number of characters in the first "n" bytes

_fmbsnbcpy
copy up to "n" bytes of a string

_fmbsnbicmp
compare up to "n" bytes in two strings with case insensitivity

_fmbsnbset
fill string with up to "n" bytes

_fmbsncat
concatenate two far strings, up to a maximum length

_fmbsnccnt
count the number of characters in the first "n" bytes

_fmbsncmp
compare two far strings up to maximum length

_fmbsncpy
copy a far string, up to a maximum length

_fmbsnextc
return integer value of the next multi-byte character in far string

_fmbsnicmp
compare two far strings with case insensitivity up to a maximum length

_fmbsninc
increment wide character far pointer by "n" characters

_fmbsnset
fill far string with character to a maximum length

_fmbspbrk
locate occurrence of a string within a second string

_fmbsrchr
locate last occurrence of character from a character set

_fmbsrev
reverse a far string in place

_fmbsrtowcs
convert multibyte character string to wide character string

_fmbsset
fill far string with a character

_fmbsspn
find number of characters at start of string which are also in a second string

_fmbsspnp
return far pointer to first character of far string not in set

_fmbsstr
find first occurrence of string in second string

_fmbstok
get next token from a far string

_fmbstowcs
convert multibyte character string to wide character string

_fmbsupr
convert far string to uppercase

_fmbterm
determine if next multibyte character in string is null

_fmbvtop
store multibyte character into far string

_fwcrtomb
convert wide character to multibyte character and store

_fwcsrtombs
convert far wide character string to far multibyte character string

_fwcstombs
convert far wide character string to far multibyte character string

_fwctomb
convert wide character to multibyte character

_mbscat
concatenate string

_mbschr
locate character in string

_mbscmp
compare two strings

_mbscoll
compare two strings using "locale" collating sequence

_mbscpy
copy a string

_mbscspn
get number of string characters not from a set of characters

_mbsdec
returns pointer to the previous character in string

_mbsdup
allocate and duplicate a string

_mbsicmp
compare two strings with case insensitivity

_mbsinc
return pointer to next character in string

mbsinit
determine if mbstate_t object describes an initial conversion state

_mbslen
string length

_mbslwr
convert string to lowercase

_mbsnbcat
append up to "n" bytes of string to another string

_mbsnbcmp
compare up to "n" bytes in two strings

_mbsnbcnt
count the number of characters in the first "n" bytes

_mbsnbcpy
copy up to "n" bytes of a string

_mbsnbicmp
compare up to "n" bytes in two strings with case insensitivity

_mbsnbset
fill string with up to "n" bytes

_mbsncat
concatenate two strings, up to a maximum length

_mbsnccnt
count the number of characters in the first "n" bytes

_mbsncmp
compare two strings up to maximum length

_mbsncpy
copy a string, up to a maximum length

_mbsnextc
return integer value of the next multi-byte character in string

_mbsnicmp
compare two strings with case insensitivity up to a maximum length

_mbsninc
increment wide character pointer by "n" characters

_mbsnset
fill string with up to "n" multibyte characters

_mbspbrk
locate occurrence of a string within a second string

_mbsrchr
locate last occurrence of character from a character set

_mbsrev
reverse a string in place

mbsrtowcs
convert multibyte character string to wide character string

_mbsset
fill string with a character

_mbsspn
find number of characters at start of string which are also in a second string

_mbsspnp
return pointer to first character of string not in set

_mbsstr
find first occurrence of string in second string

_mbstok
get next token from string

mbstowcs
convert multibyte character string to wide character string

_mbsupr
convert string to uppercase

_mbterm
determine if next multibyte character in string is null

_mbvtop
store multibyte character into string

wcrtomb
convert wide character to multibyte character and store

wcsrtombs
convert wide character string to multibyte character string

wcstombs
convert wide character string to multibyte character string

wctob
return single-byte character version of wide character

wctomb
convert wide character to multibyte character

For related functions see the sections Conversion Functions (conversions to and from strings), Time Functions (formatting of dates and times), and Memory Manipulation Functions (operate on arrays without terminating null character).

Conversion Functions


These functions perform conversions between objects of various types and strings.  The following functions are defined:
atof
string to "double"

atoh
hexadecimal string to "unsigned int"

atoi
string to "int"

atol
string to "long int"

atoll
string to "long long int"

ecvt
"double" to E-format string

fcvt
"double" to F-format string

gcvt
"double" to string

itoa
"int" to string

lltoa
"long long int" to string

ltoa
"long int" to string

strtod
string to "double"

strtol
string to "long int"

strtoll
string to "long long int"

strtoul
string to "unsigned long int"

strtoull
string to "unsigned long long int"

ulltoa
"unsigned long long int" to string

ultoa
"unsigned long int" to string

utoa
"unsigned int" to string

These functions perform conversions between objects of various types and wide character strings.  The following functions are defined:
_itow
"int" to wide character string

_lltow
"long long int" to wide character string

_ltow
"long int" to wide character string

_ulltow
"unsigned long long int" to wide character string

_ultow
"unsigned long int" to wide character string

_utow
"unsigned int" to wide character string

wcstod
wide character string to "double"

wcstol
wide character string to "long int"

wcstoll
wide character string to "long long int"

wcstoul
wide character string to "unsigned long int"

wcstoull
wide character string to "unsigned long long int"

_wtof
wide character string to "double"

_wtoi
wide character string to "int"

_wtol
wide character string to "long int"

_wtoll
wide character string to "long long int"

See also tolower, towlower, _mbctolower, toupper, towupper, _mbctoupper, _strlwr, _wcslwr, _mbslwr, _strupr, _wcsupr and _mbsupr which convert the cases of characters and strings.

Memory Allocation Functions


These functions allocate and de-allocate blocks of memory.

Unless you are running your program in 32-bit protect mode, where segments have a limit of 4 gigabytes, the default data segment has a maximum size of 64K bytes.  It may be less in a machine with insufficient memory or when other programs in the computer already occupy some of the memory.  The _nmalloc function allocates space within this area while the _fmalloc function allocates space outside the area (if it is available).

In a small data model, the malloc, calloc and realloc functions use the _nmalloc function to acquire memory; in a large data model, the _fmalloc function is used.

It is also possible to allocate memory from a based heap using _bmalloc.  Based heaps are similar to far heaps in that they are located outside the normal data segment.  Based pointers only store the offset portion of the full address, so they behave much like near pointers.  The selector portion of the full address specifies which based heap a based pointer belongs to, and must be passed to the various based heap functions.

It is important to use the appropriate memory-deallocation function to free memory blocks.  The _nfree function should be used to free space acquired by the _ncalloc, _nmalloc, or _nrealloc functions.  The _ffree function should be used to free space acquired by the _fcalloc, _fmalloc, or _frealloc functions.  The _bfree function should be used to free space acquired by the _bcalloc, _bmalloc, or _brealloc functions.

The free function will use the _nfree function when the small data memory model is used; it will use the _ffree function when the large data memory model is being used.

It should be noted that the _fmalloc and _nmalloc functions can both be used in either data memory model.  The following functions are defined:
alloca
allocate auto storage from stack

_bcalloc
allocate and zero memory from a based heap

_bexpand
expand a block of memory in a based heap

_bfree
free a block of memory in a based heap

_bfreeseg
free a based heap

_bheapseg
allocate a based heap

_bmalloc
allocate a memory block from a based heap

_bmsize
return the size of a memory block

_brealloc
re-allocate a memory block in a based heap

calloc
allocate and zero memory

_expand
expand a block of memory

_fcalloc
allocate and zero a memory block (outside default data segment)

_fexpand
expand a block of memory (outside default data segment)

_ffree
free a block allocated using "_fmalloc"

_fmalloc
allocate a memory block (outside default data segment)

_fmsize
return the size of a memory block

_frealloc
re-allocate a memory block (outside default data segment)

free
free a block allocated using "malloc", "calloc" or "realloc"

_freect
return number of objects that can be allocated

halloc
allocate huge array

hfree
free huge array

malloc
allocate a memory block (using current memory model)

_memavl
return amount of available memory

_memmax
return largest block of memory available

_msize
return the size of a memory block

_ncalloc
allocate and zero a memory block (inside default data segment)

_nexpand
expand a block of memory (inside default data segment)

_nfree
free a block allocated using "_nmalloc"

_nmalloc
allocate a memory block (inside default data segment)

_nmsize
return the size of a memory block

_nrealloc
re-allocate a memory block (inside default data segment)

realloc
re-allocate a block of memory

sbrk
set allocation "break" position

stackavail
determine available amount of stack space

Heap Functions


These functions provide the ability to shrink and grow the heap, as well as, find heap related problems.  The following functions are defined:
_heapchk
perform consistency check on the heap

_bheapchk
perform consistency check on a based heap

_fheapchk
perform consistency check on the far heap

_nheapchk
perform consistency check on the near heap

_heapgrow
grow the heap

_fheapgrow
grow the far heap

_nheapgrow
grow the near heap up to its limit of 64K

_heapmin
shrink the heap as small as possible

_bheapmin
shrink a based heap as small as possible

_fheapmin
shrink the far heap as small as possible

_nheapmin
shrink the near heap as small as possible

_heapset
fill unallocated sections of heap with pattern

_bheapset
fill unallocated sections of based heap with pattern

_fheapset
fill unallocated sections of far heap with pattern

_nheapset
fill unallocated sections of near heap with pattern

_heapshrink
shrink the heap as small as possible

_fheapshrink
shrink the far heap as small as possible

_bheapshrink
shrink a based heap as small as possible

_nheapshrink
shrink the near heap as small as possible

_heapwalk
walk through each entry in the heap

_bheapwalk
walk through each entry in a based heap

_fheapwalk
walk through each entry in the far heap

_nheapwalk
walk through each entry in the near heap

Math Functions


These functions operate with objects of type double, also known as floating-point numbers.  The Intel 8087 processor (and its successor chips) is commonly used to implement floating-point operations on personal computers.  Functions ending in "87" pertain to this specific hardware and should be isolated in programs when portability is a consideration.  The following functions are defined:
abs
absolute value of an object of type "int"

acos
arccosine

acosh
inverse hyperbolic cosine

asin
arcsine

asinh
inverse hyperbolic sine

atan
arctangent of one argument

atan2
arctangent of two arguments

atanh
inverse hyperbolic tangent

Bessel Functions
bessel functions j0, j1, jn, y0, y1, and yn

cabs
absolute value of complex number

cbrt
cubed root of a number

ceil
ceiling function

_clear87
clears floating-point status

_control87
sets new floating-point control word

copysign
copies the sign of one number to another

cos
cosine

cosh
hyperbolic cosine

div
compute quotient, remainder from division of an "int" object

erf
computes the error function

erfc
computes the complementary error function

exp
exponential function

exp2
two raised to a value

expm1
exponential of a number minus one

fabs
absolute value of "double"

fdim
positive difference of two numbers

_finite
determines whether floating-point value is valid

floor
floor function

fma
fused multiply-add

fmax
returns larger of two numbers

fmin
returns smaller of two numbers

fmod
modulus function

_fpreset
initializes for floating-point operations

frexp
fractional exponent

hypot
compute hypotenuse

ilogb
retrieve the exponent of a "double"

imaxabs
get quotient, remainder from division of object of maximum-size integer type

imaxdiv
absolute value of an object of maximum-size integer type

j0
return Bessel functions of the first kind (described under Bessel Functions )

j1
return Bessel functions of the first kind (described under Bessel Functions )

jn
return Bessel functions of the first kind (described under Bessel Functions )

labs
absolute value of an object of type "long int"

ldexp
multiply by a power of two

ldiv
get quotient, remainder from division of object of type "long int"

lgamma
natural logarithm of the absolute value of the Gamma function

lgamma_r
natural logarithm of the absolute value of the Gamma function (thread-safe)

log
natural logarithm

log10
logarithm, base 10

log1p
natural logarithm of one plus the argument

log2
logarithm, base 2

logb
retrieve the exponent of a "double"

matherr
handles error from math functions

max
return maximum of two arguments

min
return minimum of two arguments

modf
get integral, fractional parts of "double"

nearbyint
returns nearest integer based on rounding mode

nextafter
returns next machine-representable floating point value

pow
raise to power

rand
random integer

remainder
retrieves the remainder of a division operation

rint
returns nearest integer based on rounding mode

round
rounds to the nearest integer

scalbn
compute a "double" times two raised to a power

_set_matherr
specify a math error handler

sin
sine

sinh
hyperbolic sine

sqrt
square root

srand
set starting point for generation of random numbers using "rand" function

_status87
gets floating-point status

tan
tangent

tanh
hyperbolic tangent

tgamma
compute the Gamma function

trunc
truncate a floating point value

y0
return Bessel functions of the second kind (described under Bessel Functions )

y1
return Bessel functions of the second kind (described under Bessel Functions )

yn
return Bessel functions of the second kind (described under Bessel Functions )

Searching Functions


These functions provide searching and sorting capabilities.  The following functions are defined:
bsearch
find a data item in an array using binary search

lfind
find a data item in an array using linear search

lsearch
linear search array, add item if not found

qsort
sort an array

Time Functions


These functions are concerned with dates and times.  The following functions are defined:
asctime
makes time string from time structure

_asctime
makes time string from time structure

_wasctime
makes time string from time structure

__wasctime
makes time string from time structure

clock
gets time since program start

ctime
gets calendar time string

_ctime
gets calendar time string

_wctime
gets calendar time string

__wctime
gets calendar time string

difftime
calculate difference between two times

ftime
returns the current time in a "timeb" structure

gmtime
convert calendar time to Coordinated Universal Time (UTC)

_gmtime
convert calendar time to Coordinated Universal Time (UTC)

localtime
convert calendar time to local time

_localtime
convert calendar time to local time

mktime
make calendar time from local time

_strdate
return date in buffer

strftime
format date and time

wcsftime
format date and time

_wstrftime_ms
format date and time

_strtime
return time in buffer

_wstrtime
return time in buffer

time
get current calendar time

tzset
set global variables to reflect the local time zone

_wstrdate
return date in buffer

Variable-length Argument Lists


Variable-length argument lists are used when a function does not have a fixed number of arguments.  These macros provide the capability to access these arguments.  The following functions are defined:
va_arg
get next variable argument

va_end
complete access of variable arguments

va_start
start access of variable arguments

Stream I/O Functions


A stream is the name given to a file or device which has been opened for data transmission.  When a stream is opened, a pointer to a FILE structure is returned.  This pointer is used to reference the stream when other functions are subsequently invoked.

There are two modes by which data can be transmitted:
binary
Data is transmitted unchanged.

text
On input, carriage-return characters are removed before following linefeed characters.  On output, carriage-return characters are inserted before linefeed characters.

These modes are required since text files are stored with the two characters delimiting a line of text, while the C convention is for only the linefeed character to delimit a text line.

When a program begins execution, there are a number of streams already open for use:
stdin
Standard Input:  input from the console

stdout
Standard Output:  output to the console

stderr
Standard Error:  output to the console (used for error messages)

stdaux
Standard Auxiliary:  auxiliary port, available for use by a program (not available in some Windows platforms)

stdprn
Standard Printer:  available for use by a program (not available in some Windows platforms)

These standard streams may be re-directed by use of the freopen function.

See also the section File Manipulation Functions for other functions which operate upon files.

The functions referenced in the section Operating System I/O Functions may also be invoked (use the fileno function to obtain the file handle).  Since the stream functions may buffer input and output, these functions should be used with caution to avoid unexpected results.

The following functions are defined:
clearerr
clear end-of-file and error indicators for stream

fclose
close stream

fcloseall
close all open streams

fdopen
open stream, given handle

feof
test for end of file

ferror
test for file error

fflush
flush output buffer

fgetc
get next character from file

_fgetchar
equivalent to "fgetc" with the argument "stdin"

fgetpos
get current file position

fgets
get a string

_flushall
flush output buffers for all streams

fopen
open a stream

fprintf
format output

fputc
write a character

_fputchar
write a character to the "stdout" stream

fputs
write a string

fread
read a number of objects

freopen
re-opens a stream

fscanf
scan input according to format

fseek
set current file position, relative

fsetpos
set current file position, absolute

_fsopen
open a shared stream

ftell
get current file position

fwrite
write a number of objects

getc
read character

getchar
get next character from "stdin"

gets
get string from "stdin"

_getw
read int from stream file

perror
write error message to "stderr" stream

printf
format output to "stdout"

putc
write character to file

putchar
write character to "stdout"

puts
write string to "stdout"

_putw
write int to stream file

rewind
position to start of file

scanf
scan input from "stdin" under format control

setbuf
set buffer

setvbuf
set buffering

tmpfile
create temporary file

ungetc
push character back on input stream

vfprintf
same as "fprintf" but with variable arguments

vfscanf
same as "fscanf" but with variable arguments

vprintf
same as "printf" but with variable arguments

vscanf
same as "scanf" but with variable arguments

See the section Directory Functions for functions which are related to directories.

Wide Character Stream I/O Functions


The previous section describes some general aspects of stream input/output.  The following describes functions dealing with streams containing multibyte character sequences.

After a stream is associated with an external file, but before any operations are performed on it, the stream is without orientation.  Once a wide character input/output function has been applied to a stream without orientation, the stream becomes wide-oriented.  Similarly, once a byte input/output function has been applied to a stream without orientation, the stream becomes byte-oriented.  Only a successful call to freopen can otherwise alter the orientation of a stream (it removes any orientation).  You cannot mix byte input/output functions and wide character input/output functions on the same stream.

A file positioning function can cause the next wide character output function to overwrite a partial multibyte character.   This can lead to the subsequent reading of a stream of multibyte characters containing an invalid character.

When multibyte characters are read from a stream, they are converted to wide characters.  Similarly, when wide characters are written to a stream, they are converted to multibyte characters.

The following functions are defined:
fgetwc
get next wide character from file

_fgetwchar
equivalent to "fgetwc" with the argument "stdin"

fgetws
get a wide character string

fprintf
"C" and "S" extensions to the format specifier

fputwc
write a wide character

_fputwchar
write a character to the "stdout" stream

fputws
write a wide character string

fscanf
"C" and "S" extensions to the format specifier

fwprintf
formatted wide character output

fwscanf
scan wide character input according to format

getwc
read wide character

getwchar
get next wide character from "stdin"

_getws
get wide character string from "stdin"

putwc
write wide character to file

putwchar
write wide character to "stdout"

_putws
write wide character string to "stdout"

ungetwc
push wide character back on input stream

vfwprintf
same as "fwprintf" but with variable arguments

vfwscanf
same as "fwscanf" but with variable arguments

vswprintf
same as "swprintf" but with variable arguments

vwprintf
same as "wprintf" but with variable arguments

vwscanf
same as "wscanf" but with variable arguments

_wfdopen
open stream, given handle using a wide character "mode"

_wfopen
open a stream using wide character arguments

_wfreopen
re-opens a stream using wide character arguments

_wfsopen
open a shared stream using wide character arguments

_wperror
write error message to "stderr" stream

wprintf
format wide character output to "stdout"

wscanf
scan wide character input from "stdin" under format control

See the section Directory Functions for functions which are related to directories.

Process Primitive Functions


These functions deal with process creation, execution and termination, signal handling, and timer operations.

When a new process is started, it may replace the existing process
or the existing process may be suspended while the new process executes (control continues at the point following the place where the new process was started)
The following functions are defined:
abort
immediate termination of process, return code 3

alarm
send calling process SIGALRM signal after specified time

atexit
register exit routine

_beginthread
start a new thread of execution

cwait
wait for a child process to terminate

_cwait
wait for a child process to terminate

delay
delay for number of milliseconds

_endthread
end the current thread

execl
chain to program

_execl
chain to program

execle
chain to program, pass environment

_execle
chain to program, pass environment

execlp
chain to program

_execlp
chain to program

execlpe
chain to program, pass environment

_execlpe
chain to program, pass environment

execv
chain to program

_execv
chain to program

execve
chain to program, pass environment

_execve
chain to program, pass environment

execvp
chain to program

_execvp
chain to program

execvpe
chain to program, pass environment

_execvpe
chain to program, pass environment

exit
exit process, set return code

_Exit
exit process, set return code

_exit
exit process, set return code

fork
create a new process

kill
send a signal to specified process

_onexit
register exit routine

pause
suspend calling process until signal

raise
signal an exceptional condition

sigaction
examine or specify action for specific signal

sigaddset
add specified signal to set

sigdelset
delete specified signal from set

sigemptyset
initialize signal set to exclude certain signals

sigfillset
initialize signal set to include certain signals

sigismember
test whether signal is a member of a set

signal
set handling for exceptional condition

sigpending
store set of pending signals

sigprocmask
examine or change process's signal mask

sigsuspend
replace process's signal mask and then suspend process

sleep
delay for number of seconds

spawnl
create process

_spawnl
create process

spawnle
create process, set environment

_spawnle
create process, set environment

spawnlp
create process

_spawnlp
create process

spawnlpe
create process, set environment

_spawnlpe
create process, set environment

spawnv
create process

_spawnv
create process

spawnve
create process, set environment

_spawnve
create process, set environment

spawnvp
create process

_spawnvp
create process

spawnvpe
create process, set environment

_spawnvpe
create process, set environment

system
execute system command

wait
wait for any child process to terminate

waitpid
wait for a child process to terminate

_wexecl
chain to program

_wexecle
chain to program, pass environment

_wexeclp
chain to program

_wexeclpe
chain to program, pass environment

_wexecv
chain to program

_wexecve
chain to program, pass environment

_wexecvp
chain to program

_wexecvpe
chain to program, pass environment

_wspawnl
create process

_wspawnle
create process, set environment

_wspawnlp
create process

_wspawnlpe
create process, set environment

_wspawnv
create process

_wspawnve
create process, set environment

_wspawnvp
create process

_wspawnvpe
create process, set environment

_wsystem
execute system command

There are eight spawn... and exec... functions each.  The "..." is one to three letters:

Process Environment


These functions deal with process identification, process groups, system identification, system time, environment variables, and terminal identification.  The following functions are defined:
_bgetcmd
get command line

clearenv
delete environment variables

confstr
get configuration-defined string values

ctermid
return name of controlling terminal

cuserid
generate login name of process owner

getcmd
get command line

getegid
get effective group ID of calling process

getenv
get environment variable value

geteuid
get effective user ID

getgid
get real group ID of calling process

getgroups
get supplementary group IDs

getlogin
get user's login name

getnid
get netword ID

getpgrp
get process group ID of calling process

getpid
get process ID of calling process

_getpid
get process ID of calling process

getppid
get parent process ID of calling process

gettid
get thread ID of current thread

getuid
get real user ID

isatty
determine if file descriptor associated with a terminal

putenv
add, change or delete environment variable

_searchenv
search for a file in list of directories

searchenv
search for a file in list of directories

setegid
set the effective group ID

setenv
add, change or delete environment variable

seteuid
set the effective user ID

setgid
set real group ID, effective group ID

setpgid
set process group ID for job control

setsid
create a new session and set process group ID

setuid
set real user ID, effective user ID

sysconf
determine value of configurable system limit or option

times
return time-accounting information

ttyname
return pointer to string containing pathname of terminal associated with file descriptor argument

uname
return operating system identification

unsetenv
delete environment variable

_wgetenv
get environment variable value

_wputenv
add, change or delete environment variable

_wsearchenv
search for a file in list of directories

_wsetenv
add, change or delete environment variable

_wunsetenv
delete environment variable

Directory Functions


These functions pertain to directory manipulation.  The following functions are defined:
chdir
change current working directory

closedir
close opened directory file

getcwd
get current working directory

_getdcwd
get current directory on drive

mkdir
make a new directory

opendir
open directory file

readdir
read file name from directory

rewinddir
reset position of directory stream

rmdir
remove a directory

_wchdir
change current working directory

_wclosedir
close opened directory file

_wgetcwd
get current working directory

_wgetdcwd
get current directory on drive

_wmkdir
make a new directory

_wopendir
open directory file

_wreaddir
read file name from directory

_wrewinddir
reset position of directory stream

_wrmdir
remove a directory

Operating System I/O Functions


These functions operate at the operating-system level and are included for compatibility with other C implementations.   It is recommended that the functions used in the section File Manipulation Functions be used for new programs, as these functions are defined portably and are part of the ISO/ANSI standard for the C language.

The functions in this section reference opened files and devices using a file handle which is returned when the file is opened.  The file handle is passed to the other functions.

The following functions are defined:
_chsize
change the size of a file

close
close file

_commit
commit changes to disk

creat
create a file

dup
duplicate file handle, get unused handle number

dup2
duplicate file handle, supply new handle number

_eof
test for end of file

fcntl
control over an open file

fdatasync
write queued file data to disk

_filelength
get file size

fileno
get file handle for stream file

fstat
get file status

fsync
write queued file and filesystem data to disk

_hdopen
get POSIX handle from OS handle

link
create new directory entry

lock
lock a section of a file

locking
lock/unlock a section of a file

lseek
set current file position

ltrunc
truncate a file

mkfifo
make a FIFO special file

mknod
make a filesystem entry point

mount
mount a filesystem

open
open a file

_os_handle
get OS handle from POSIX handle

_pclose
close a pipe

pclose
close a pipe

pipe
create an inter-process channel

_popen
open a pipe

popen
open a pipe

read
read a record

readlink
read a symbolic link

readv
read several records placing them into a specified number of buffers

select
synchronous I/O multiplexing

_setmode
set file mode

_sopen
open a file for shared access

symlink
create a symbolic link

sync
sync the filesystem

_tell
get current file position

umask
set file permission mask

umount
unmount a filesystem

unlink
delete a file

unlock
unlock a section of a file

write
write a record

writev
write several records from a specified number of buffers

_wcreat
create a file

_wopen
open a file

_wpopen
open a pipe

_wsopen
open a file for shared access

_wunlink
delete a file

File Manipulation Functions


These functions operate directly with files.  The following functions are defined:
access
test file or directory for mode of access

chmod
change permissions for a file

chown
change owner user ID and group ID of the specified file

fchmod
change the permissions for the file associated with the specified file descriptor to the specified mode

fchown
change the user ID and group ID of the file associated with the specified file descriptor to the specified numeric values

fpathconf
determine value of configurable limit associated with a file or directory

lstat
get file status

pathconf
determine value of configurable limit associated with a file or directory

remove
delete a file

rename
rename a file

stat
get file status

tmpnam
create name for temporary file

utime
set modification time for a file

_waccess
test file or directory for mode of access

_wchmod
change permissions for a file

_wremove
delete a file

_wrename
rename a file

_wstat
get file status

_wtmpnam
create name for temporary file

_wutime
set modification time for a file

Console I/O Functions


These functions provide the capability to read and write data from the console.  Data is read or written without any special initialization (devices are not opened or closed), since the functions operate at the hardware level.

The following functions are defined:
cgets
get a string from the console

cprintf
print formatted string to the console

cputs
write a string to the console

cscanf
scan formatted data from the console

getch
get character from console, no echo

getche
get character from console, echo it

kbhit
test if keystroke available

putch
write a character to the console

ungetch
push back next character from console

Default Windowing Functions


These functions provide the capability to manipulate attributes of various windows created by Open Watcom's default windowing system for Microsoft Windows and IBM OS/2.

The following functions are defined:
_dwDeleteOnClose
delete console window upon close

_dwSetAboutDlg
set about dialogue box title and contents

_dwSetAppTitle
set main window's application title

_dwSetConTitle
set console window's title

_dwShutDown
shut down default windowing system

_dwYield
yield control to other processes

BIOS Functions


This set of functions allows access to services provided by the BIOS.  The following functions are defined:
_bios_disk
provide disk access functions

_bios_equiplist
determine equipment list

_bios_keybrd
provide low-level keyboard access

_bios_memsize
determine amount of system board memory

_bios_printer
provide access to printer services

_bios_serialcom
provide access to serial services

_bios_timeofday
get and set system clock

DOS-Specific Functions


These functions provide the capability to invoke DOS functions directly from a program.  The following functions are defined:
bdos
DOS call (short form)

dosexterr
extract DOS error information

_dos_allocmem
allocate a block of memory

_dos_close
close a file

_dos_commit
flush buffers to disk

_dos_creat
create a file

_dos_creatnew
create a new file

_dos_findclose
close find file matching

_dos_findfirst
find first file matching a specified pattern

_dos_findnext
find the next file matching a specified pattern

_dos_freemem
free a block of memory

_dos_getdate
get current system date

_dos_getdiskfree
get information about disk

_dos_getdrive
get the current drive

_dos_getfileattr
get file attributes

_dos_getftime
get file's last modification time

_dos_gettime
get the current system time

_dos_getvect
get contents of interrupt vector

_dos_keep
install a terminate-and-stay-resident program

_dos_open
open a file

_dos_read
read data from a file

_dos_setblock
change the size of allocated block

_dos_setdate
change current system date

_dos_setdrive
change the current default drive

_dos_setfileattr
set the attributes of a file

_dos_setftime
set a file's last modification time

_dos_settime
set the current system time

_dos_setvect
set an interrupt vector

_dos_write
write data to a file

intdos
cause DOS interrupt

intdosx
cause DOS interrupt, with segment registers

_wdos_findclose
close find file matching

_wdos_findfirst
find first file matching a specified pattern

_wdos_findnext
find the next file matching a specified pattern

Intel 80x86 Architecture-Specific Functions


These functions provide the capability to invoke Intel 80x86 processor-related functions directly from a program.  Functions that apply to the Intel 8086 CPU apply to that family including the 80286, 80386, 80486 and Pentium processors.   The following functions are defined:
_chain_intr
chain to the previous interrupt handler

_disable
disable interrupts

_enable
enable interrupts

FP_OFF
get offset part of far pointer

FP_SEG
get segment part of far pointer

inp
get one byte from hardware port

inpw
get two bytes (one word) from hardware port

int386
cause 386/486/Pentium CPU interrupt

int386x
cause 386/486/Pentium CPU interrupt, with segment registers

int86
cause 8086 CPU interrupt

int86x
cause 8086 CPU interrupt, with segment registers

intr
cause 8086 CPU interrupt, with segment registers

intrf
cause 8086 CPU interrupt, with segment registers and CPU flags

MK_FP
make a far pointer from the segment and offset values

nosound
turn off the speaker

outp
write one byte to hardware port

outpw
write two bytes (one word) to hardware port

segread
read segment registers

sound
turn on the speaker at specified frequency

Intel Pentium Multimedia Extension Functions


This set of functions allows access to Intel Architecture Multimedia Extensions (MMX).  These functions are implemented as in-line intrinsic functions.  The general format for most functions is:

     
     mm_result = mm_function( mm_operand1, mm_operand2 );

These functions provide a simple model for use of Intel Multimedia Extension (MMX).  More advanced use of MMX can be implemented in much the same way that these functions are implemented.  See the <mmintrin.h> header file for examples.  The following functions are defined:
_m_empty
empty multimedia state

_m_from_int
form 64-bit MM value from unsigned 32-bit integer value

_m_packssdw
pack and saturate 32-bit double-words from two MM elements into signed 16-bit words

_m_packsswb
pack and saturate 16-bit words from two MM elements into signed bytes

_m_packuswb
pack and saturate signed 16-bit words from two MM elements into unsigned bytes

_m_paddb
add packed bytes

_m_paddd
add packed 32-bit double-words

_m_paddsb
add packed signed bytes with saturation

_m_paddsw
add packed signed 16-bit words with saturation

_m_paddusb
add packed unsigned bytes with saturation

_m_paddusw
add packed unsigned 16-bit words with saturation

_m_paddw
add packed 16-bit words

_m_pand
AND 64 bits of two MM elements

_m_pandn
invert the 64 bits in MM element, then AND 64 bits from second MM element

_m_pcmpeqb
compare packed bytes for equality

_m_pcmpeqd
compare packed 32-bit double-words for equality

_m_pcmpeqw
compare packed 16-bit words for equality

_m_pcmpgtb
compare packed bytes for greater than relationship

_m_pcmpgtd
compare packed 32-bit double-words for greater than relationship

_m_pcmpgtw
compare packed 16-bit words for greater than relationship

_m_pmaddwd
multiply packed 16-bit words, then add 32-bit results pair-wise

_m_pmulhw
multiply the packed 16-bit words of two MM elements, then store high-order 16 bits of results

_m_pmullw
multiply the packed 16-bit words of two MM elements, then store low-order 16 bits of results

_m_por
OR 64 bits of two MM elements

_m_pslld
shift left each 32-bit double-word by amount specified in second MM element

_m_pslldi
shift left each 32-bit double-word by amount specified in constant value

_m_psllq
shift left each 64-bit quad-word by amount specified in second MM element

_m_psllqi
shift left each 64-bit quad-word by amount specified in constant value

_m_psllw
shift left each 16-bit word by amount specified in second MM element

_m_psllwi
shift left each 16-bit word by amount specified in constant value

_m_psrad
shift right (with sign propagation) each 32-bit double-word by amount specified in second MM element

_m_psradi
shift right (with sign propagation) each 32-bit double-word by amount specified in constant value

_m_psraw
shift right (with sign propagation) each 16-bit word by amount specified in second MM element

_m_psrawi
shift right (with sign propagation) each 16-bit word by amount specified in constant value

_m_psrld
shift right (with zero fill) each 32-bit double-word by an amount specified in second MM element

_m_psrldi
shift right (with zero fill) each 32-bit double-word by an amount specified in constant value

_m_psrlq
shift right (with zero fill) each 64-bit quad-word by an amount specified in second MM element

_m_psrlqi
shift right (with zero fill) each 64-bit quad-word by an amount specified in constant value

_m_psrlw
shift right (with zero fill) each 16-bit word by an amount specified in second MM element

_m_psrlwi
shift right (with zero fill) each 16-bit word by an amount specified in constant value

_m_psubb
subtract packed bytes in MM element from second MM element

_m_psubd
subtract packed 32-bit dwords in MM element from second MM element

_m_psubsb
subtract packed signed bytes in MM element from second MM element with saturation

_m_psubsw
subtract packed signed 16-bit words in MM element from second MM element with saturation

_m_psubusb
subtract packed unsigned bytes in MM element from second MM element with saturation

_m_psubusw
subtract packed unsigned 16-bit words in MM element from second MM element with saturation

_m_psubw
subtract packed 16-bit words in MM element from second MM element

_m_punpckhbw
interleave bytes from the high halves of two MM elements

_m_punpckhdq
interleave 32-bit double-words from the high halves of two MM elements

_m_punpckhwd
interleave 16-bit words from the high halves of two MM elements

_m_punpcklbw
interleave bytes from the low halves of two MM elements

_m_punpckldq
interleave 32-bit double-words from the low halves of two MM elements

_m_punpcklwd
interleave 16-bit words from the low halves of two MM elements

_m_pxor
XOR 64 bits from two MM elements

_m_to_int
retrieve low-order 32 bits from MM value

Miscellaneous Functions


The following functions are defined:
assert
test an assertion and output a string upon failure

_fullpath
return full path specification for file

_getmbcp
get current multibyte code page

getopt
a command-line parser that can be used by applications that follow guidelines outlined in the Single UNIX Specification

_harderr
critical error handler

_hardresume
critical error handler resume

localeconv
obtain locale specific conversion information

longjmp
return and restore environment saved by "setjmp"

_lrotl
rotate an "unsigned long" left

_lrotr
rotate an "unsigned long" right

main
the main program (user written)

offsetof
get offset of field in structure

_rotl
rotate an "unsigned int" left

_rotr
rotate an "unsigned int" right

setjmp
save environment for use with "longjmp" function

_makepath
make a full filename from specified components

setlocale
set locale category

_setmbcp
set current multibyte code page

sigsetjmp
save environment and process's signal mask for use with "siglongjmp" function

siglongjmp
return and restore environment and process's signal mask saved by "sigsetjmp"

_splitpath
split a filename into its components

_splitpath2
split a filename into its components

_wfullpath
return full path specification for file

_wmakepath
make a full filename from specified components

_wsetlocale
set locale category

_wsplitpath
split a filename into its components

_wsplitpath2
split a filename into its components

DOS LFN aware Functions


These functions deal with DOS Long File Name if an application is compiled with -D__WATCOM_LFN__ option and DOS LFN support is available on host system.  The following functions are defined:
access
test file or directory for mode of access

chdir
change current working directory

chmod
change permissions for a file

creat
create a file

_dos_creat
create a file

_dos_creatnew
create a new file

_dos_findfirst
find first file matching a specified pattern

_dos_getfileattr
get file attributes

_dos_open
open a file

_dos_setfileattr
set the attributes of a file

_findfirst
find first file matching a specified pattern

_fullpath
return full path specification for file

getcwd
get current working directory

_getdcwd
get current directory on drive

lstat
get file status

mkdir
make a new directory

open
open a file

opendir
open directory file

remove
delete a file

rename
rename a file

rmdir
remove a directory

_sopen
open a file for shared access

stat
get file status

tmpnam
create name for temporary file

unlink
delete a file

utime
set modification time for a file

_waccess
test file or directory for mode of access

_wchdir
change current working directory

_wchmod
change permissions for a file

_wcreat
create a file

_wdos_findfirst
find first file matching a specified pattern

_wfindfirst
find first file matching a specified pattern

_wfullpath
return full path specification for file

_wgetcwd
get current working directory

_wgetdcwd
get current directory on drive

_wmkdir
make a new directory

_wopen
open a file

_wopendir
open directory file

_wremove
delete a file

_wrename
rename a file

_wrmdir
remove a directory

_wsopen
open a file for shared access

_wstat
get file status

_wtmpnam
create name for temporary file

_wunlink
delete a file

_wutime
set modification time for a file

Header Files


The following header files are supplied with the C library.  As has been previously noted, when a library function is referenced in a source file, the related header files (shown in the synopsis for that function) should be included into that source file.  The header files provide the proper declarations for the functions and for the number and types of arguments used with them.  Constant values used in conjunction with the functions are also declared.  The files can be included multiple times and in any order.

Header Files in /watcom/h


The following header files are provided with the software.  The header files that are located in the \WATCOM\H directory are described first. 
assert.h
This ISO C90 header file is required when an assert macro is used.  These assertions will be ignored when the identifier NDEBUG is defined. 

bios.h
This header file declares all BIOS related functions. 

conio.h
This header file declares console and Intel 80x86 port input/output functions. 

ctype.h
This ISO C90 header file declares functions that perform character classification and case conversion operations.  Similar functions for wide characters are declared in <wctype.h>. 

direct.h
This header file declares functions related to directories and the type DIR which describes an entry in a directory.  

dos.h
This header file declares functions that interact with DOS.  It includes the definitions of the FP_OFF, FP_SEG and MK_FP macros, and for the following structures and unions: 
DOSERROR
describes the DOS error information. 

REGS
describes the CPU registers for Intel 8086 family. 

SREGS
describes the segment registers for the Intel 8086 family. 

REGPACK
describes the CPU registers and segment registers for Intel 8086 family. 

INTPACK
describes the input parameter to an "interrupt" function.

env.h
This POSIX header file declares environment string functions. 

errno.h
This ISO C90 header file provides the extern declaration for error variable errno and provides the symbolic names for error codes that can be placed in the error variable. 

fcntl.h
This POSIX header file defines the flags used by the open and _sopen functions.  The function declarations for these functions are found in the <io.h> header file. 

fenv.h
This ISO C99 header file defines several types and declares several functions that give access to the floating point environment.   These functions can be used to control status flags and control modes in the floating point processor. 

float.h
This ISO C90 header file declares constants related to floating-point numbers, declarations for low-level floating-point functions, and the declaration of the floating-point exception codes. 

fnmatch.h
This header file declares the pattern matching function fnmatch

graph.h
This header file contains structure definitions and function declarations for the Open Watcom C Graphics library functions.  

inttypes.h
This ISO C99 header file includes <stdint.h> and expands on it by definition macros for printing and scanning specific sized integer types.  This header also declares several functions for manipulating maximum sized integers.
Note that the format macros are not visible in C++ programs unless the macro __STDC_FORMAT_MACROS is defined.  

io.h
This header file declares functions that perform input/output operations at the operating system level.  These functions use file handles to reference files or devices.  The function fstat is declared in the <sys/stat.h> header file. 

limits.h
This ISO C90 header file contains constant declarations for limits or boundary values for ranges of integers and characters.  

locale.h
This ISO C90 header file contains declarations for the categories (LC...) of locales which can be selected using the setlocale function which is also declared. 

malloc.h
This header file declares the memory allocation and deallocation functions. 

math.h
This ISO/ANSI header file declares the mathematical functions (which operate with floating-point numbers) and the structures:  
exception
describes the exception structure passed to the matherr function; symbolic constants for the types of exceptions are included

complex
declares a complex number

mmintrin.h
This header file declares functions that interact with the Intel Architecture Multimedia Extensions.  It defines the datatype used to store multimedia values: 
__m64
describes the 64-bit multimedia data element.  Note:  the underlying implementation details of this datatype are subject to change.  Other compilers may implement a similar datatype in a different manner.

It also contains prototypes for multimedia functions and pragmas for the in-line generation of code that operates on multimedia registers. 

process.h
This header file declares the spawn... functions, the exec... functions, and the system function.  The file also contains declarations for the constants P_WAIT, P_NOWAIT, P_NOWAITO, and P_OVERLAY

search.h
This header file declares the functions lfind and lsearch

setjmp.h
This ISO C90 header file declares the setjmp and longjmp functions. 

share.h
This header file defines constants for shared access to files using the _sopen function. 

signal.h
This ISO C90 header file declares the signal and raise functions. 

stdarg.h
This ISO C90 header file defines the macros which handle variable argument lists. 

stdbool.h
This ISO C99 header file defines the macro bool and the macros true and false for use in C programs.   If this header is included in a C++ program there is no effect.  The C++ reserved words will not be redefined.   However the definition of bool, true, and false used in a C program will be compatible with their C++ counterparts.  In particular, a C function declared as taking a bool parameter and a structure containing a bool member can both be shared between C and C++ without error. 

stddef.h
This ISO C90 header file defines a few popular constants and types including NULL (null pointer), size_t (unsigned size of an object), and ptrdiff_t (difference between two pointers).  It also contains a declaration for the offsetof macro. 

stdint.h
This ISO C99 header file defines numerous type names for integers of various sizes.  Such type names provide a reasonably portable way to refer to integers with a specific number of bits.  This header file also defines macros that describe the minimum and maximum values for these types (similar to the macros in limits.h), and macros for writing integer constants with specific sized types.
Note that in C++ programs the limit macros are not visible unless the macro __STDC_LIMIT_MACROS is defined.   Similarly the constant writing macros are not visible unless the macro __STDC_CONSTANT_MACROS is defined.  

stdio.h
This ISO C90 header file declares the standard input/output functions.  Files, devices and directories are referenced using pointers to objects of the type FILE

stdlib.h
This ISO C90 header file declares many standard functions excluding those declared in other header files discussed in this section. 

string.h
This ISO C90 header file declares functions that manipulate strings or blocks of memory. 

time.h
This ISO/ANSI header file declares functions related to times and dates and defines the structure struct tm

varargs.h
This UNIX System V header file provides an alternate way of handling variable argument lists.  The equivalent ISO/ANSI header file is <stdarg.h>. 

wchar.h
This ISO C99 header file defines several data types including wchar_t, size_t, mbstate_t (an object that can hold conversion state information necessary to convert between multibyte characters and wide characters), wctype_t (a scalar type that can hold values which represent locale-specific character classification), and wint_t which is an integral type that can hold any wchar_t value as well as WEOF (a character that is not in the set of "wchar_t" characters and that is used to indicate end-of-file on an input stream).   The functions that are declared in this header file are grouped as follows:

wctype.h
This ISO C99 header file declares functions that perform characater classification and case conversion operations on wide characters.  Similar functions for ordinary characters are declared in <ctype.h>.

Header Files in /watcom/h/sys


The following header files are present in the sys subdirectory.  Their presence in this directory indicates that they are system-dependent header files. 
sys/locking.h
This header file contains the manifest constants used by the locking function. 

sys/stat.h
This POSIX header file contains the declarations pertaining to file status, including definitions for the fstat and stat functions and for the structure: 
stat
describes the information obtained for a directory, file or device

sys/timeb.h
This header file describes the timeb structure used in conjunction with the ftime function.  

sys/types.h
This POSIX header file contains declarations for the types used by system-level calls to obtain file status or time information.  

sys/utime.h
This POSIX header file contains a declaration for the utime function and for the structured type utimbuf used by it.

Global Data


Certain data items are used by the Open Watcom C/C++ run-time library and may be inspected (or changed in some cases) by a program.  The defined items are: 
_amblksiz
Prototype in <stdlib.h>.
This unsigned int data item contains the increment by which the "break" pointer for memory allocation will be advanced when there is no freed block large enough to satisfy a request to allocate a block of memory.  This value may be changed by a program at any time. 

__argc
Prototype in <stdlib.h>.
This int item contains the number of arguments passed to main

__argv
Prototype in <stdlib.h>.
This char ** item contains a pointer to a vector containing the actual arguments passed to main.  

daylight
Prototype in <time.h>.
This unsigned int has a value of one when daylight saving time is supported in this locale and zero otherwise.   Whenever a time function is called, the tzset function is called to set the value of the variable.   The value will be determined from the value of the TZ environment variable. 

_doserrno
Prototype in <stdlib.h>.
This int item contains the actual error code returned when a DOS, Windows or OS/2 function fails. 

environ
Prototype in <stdlib.h>.
This char ** __near data item is a pointer to an array of character pointers to the environment strings.

errno
Prototype in <errno.h>.
This int item contains the number of the last error that was detected.  The run-time library never resets errno to 0.  Symbolic names for these errors are found in the <errno.h> header file.  See the descriptions for the perror and strerror functions for information about the text which describes these errors. 

fltused_
The C compiler places a reference to the fltused_ symbol into any module that uses a floating-point library routine or library routine that requires floating-point support (e.g., the use of a float or double as an argument to the printf function). 

_fmode
Prototype in <stdlib.h>.
This data item contains the default type of file (text or binary) translation for a file.  It will contain a value of either
O_BINARY
indicates that data is transmitted to and from streams unchanged.

O_TEXT
indicates that carriage return characters are added before linefeed characters on output operations and are removed on input operations when they precede linefeed characters.

These values are defined in the <fcntl.h> header file.  The value of _fmode may be changed by a program to change the default behavior of the open, fopen, creat and _sopen functions.  The default setting of _fmode is O_TEXT, for text-mode translation.  O_BINARY is the setting for binary mode.  You can change the value of _fmode in either of two ways: 

__MaxThreads
There is a limit to the number of threads an application can create under 16-bit OS/2 and 32-bit NetWare.  The default limit is 32.  This limit can be adjusted by statically initializing the unsigned global variable __MaxThreads.
Under 32-bit OS/2, there is no limit to the number of threads an application can create.  However, due to the way in which multiple threads are supported in the Open Watcom libraries, there is a small performance penalty once the number of threads exceeds the default limit of 32 (this number includes the initial thread).  If you are creating more than 32 threads and wish to avoid this performance penalty, you can redefine the threshold value of 32.  You can statically initialize the global variable __MaxThreads.

By adding the following line to your multi-threaded application, the new threshold value will be set to 48.

     
     unsigned __MaxThreads = { 48 };

__minreal
Prototype in <stdlib.h>.
This data item contains the minimum amount of real memory (below 640K) to reserve when running a 32-bit DOS extended application.  

optarg
Prototype in <unistd.h>.
This char * variable contains a pointer to an option-argument parsed by the getopt function.  

opterr
Prototype in <unistd.h>.
This int variable controls whether the getopt function will print error messages.  The default value is non-zero and will cause the getopt function to print error messages on the console.  

optind
Prototype in <unistd.h>.
This int variable holds the index of the argument array element currently processed by the getopt function. 

optopt
Prototype in <unistd.h>.
This int variable contains the unrecognized option character in case the getopt function returns an error. 

_osmajor
Prototype in <stdlib.h>.
This unsigned char variable contains the major number for the version of Operating System executing on the computer.   By example, if current running DOS version is 3.20, then the value will be 3. 

_osminor
Prototype in <stdlib.h>.
This unsigned char variable contains the minor number for the version of Operating System executing on the computer.   By example, if current running DOS version is 3.20, then the value will be 20. 

_osbuild
(Win32 only) Prototype in <stdlib.h>.
This unsigned short variable contains the operating system build number for the version of Windows executing on the computer. 

_osver
(Win32 only) Prototype in <stdlib.h>.
This unsigned int variable contains the operating system build number for the version of Windows executing on the computer.
On Win32s or Windows 95/98 platforms, the high bit of the low-order 16-bit word is turned on.  Windows 95/98 do not have build numbers.

     
     unsigned short dwBuild;

     // Get build numbers for Win32 or Win32s

     if( _osver < 0x8000 )       // Windows NT/2000
         dwBuild = _osver;
     else if (_winmajor < 4)     // Win32s
         dwBuild = _osver & 0x8000;
     else                         // Windows 95 or 98
         dwBuild =  0;            // No build numbers provided

Note that the Win32 GetVersionEx function is the preferred method for obtaining operating system version number information. 

_osmode
(16-bit only) Prototype in <stdlib.h>.
This unsigned char variable contains either the value DOS_MODE which indicates the program is running in real address mode, or it contains the value OS2_MODE which indicates the program is running in protected address mode. 

_psp
Prototype in <stdlib.h>.
This data item contains the segment value for the DOS Program Segment Prefix.  Consult the technical documentation for your DOS system for the process information contained in the Program Segment Prefix. 

_stacksize
On 16-bit 80x86 systems, this unsigned int value contains the size of the stack for a TINY memory model program.   Changing the value of this item during the execution of a program will have no effect upon the program, since the value is used when the program starts execution.  To change the size of the stack to be 8K bytes, a statement such as follows can be included with the program.
     
     unsigned int _stacksize = { 8 * 1024 };

stdaux
Prototype in <stdio.h>.
This variable (with type FILE *) indicates the standard auxiliary port (not available in some Windows platforms).  

stderr
Prototype in <stdio.h>.
This variable (with type FILE *) indicates the standard error stream (set to the console by default). 

stdin
Prototype in <stdio.h>.
This variable (with type FILE *) indicates the standard input stream (set to the console by default). 

stdout
Prototype in <stdio.h>.
This variable (with type FILE *) indicates the standard output stream (set to the console by default). 

stdprn
Prototype in <stdio.h>.
This variable (with type FILE *) indicates the standard printer.  (not available in some Windows platforms).  

sys_errlist
Prototype in <stdlib.h>.
This variable is an array of pointers to character strings for each error code defined in the <errno.h> header file. 

sys_nerr
Prototype in <stdlib.h>.
This int variable contains the number of messages declared in sys_errlist

_threadid
Prototype in <stddef.h>.
This variable/function may be used to obtain the id of the current thread which is an int.  In the 32-bit libraries, _threadid is a function that returns a pointer to an int.  In the 16-bit libraries, _threadid is a far pointer to an int.  Note that the value stored where _threadid points does not necessarily change when a thread context switch occurs (so do not make a copy of the pointer ...  it may change).  To obtain the current thread identifier, simply code:
     
     int tid = *_threadid;

timezone
Prototype in <time.h>.
This long int contains the number of seconds of time that the local time zone is earlier than Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).  Whenever a time function is called, the tzset function is called to set the value of the variable.  The value will be determined from the value of the TZ environment variable. 

tzname
Prototype in <time.h>.
This array of two pointers to character strings indicates the name of the standard abbreviation for the time zone and the name of the abbreviation for the time zone when daylight saving time is in effect.  Whenever a time function is called, the tzset function is called to set the values in the array.  These values will be determined from the value of the TZ environment variable. 

__wargc
Prototype in <stdlib.h>.
This int item contains the number of arguments passed to wmain

__wargv
Prototype in <stdlib.h>.
This wchar_t ** item contains a pointer to a vector containing the actual arguments passed to wmain.  

_wenviron
Prototype in <stdlib.h>.
This wchar_t ** __near data item is a pointer to an array of wide character pointers to the wide character equivalents of the environment strings. 

__win_alloc_flags
Prototype in <stdlib.h>.
This unsigned long int variable contains the flags to be used when allocating memory in Windows. 

__win_realloc_flags
Prototype in <stdlib.h>.
This unsigned long int variable contains the flags to be used when reallocating memory in Windows. 

_winmajor
(Win32 only) Prototype in <stdlib.h>.
This unsigned int variable contains the operating system major version number for the version of Windows executing on the computer.  For example, the major version number of the Daytona release of Windows NT is 3.
Note that the Win32 GetVersionEx function is the preferred method for obtaining operating system version number information. 

_winminor
(Win32 only) Prototype in <stdlib.h>.
This unsigned int variable contains the operating system minor version number for the version of Windows executing on the computer.  For example, the minor version number of the Daytona release of Windows NT is 5.
Note that the Win32 GetVersionEx function is the preferred method for obtaining operating system version number information. 

_winver
(Win32 only) Prototype in <stdlib.h>.
This unsigned int variable contains the operating system version number for the version of Windows executing on the computer.  The low-order byte contains the minor version number (see also _winminor).  The next byte contains the major version number (see also _winmajor).  The high-order word contains no useful information.
Note that the Win32 GetVersionEx function is the preferred method for obtaining operating system version number information.

The TZ Environment Variable


The TZ environment variable is used to establish the local time zone.  The value of the variable is used by various time functions to compute times relative to Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).

The time on the computer should be set to the local time.  Use the DOS time command and the DOS date command if the time is not automatically maintained by the computer hardware.

The TZ environment variable can be set (before the program is executed) by using the DOS set command as follows:

     
         SET TZ=PST8PDT

or (during the program execution) by using the setenv or putenv library functions:

     
         setenv( "TZ", "PST8PDT", 1 );
         putenv( "TZ=PST8PDT" );

The value of the variable can be obtained by using the getenv function:

     
         char *tzvalue;
          . . .
         tzvalue = getenv( "TZ" );

The tzset function processes the TZ environment variable and sets the global variables daylight (indicates if daylight saving time is supported in the locale), timezone (contains the number of seconds of time difference between the local time zone and Coordinated Universal Time (UTC)), and tzname (a vector of two pointers to character strings containing the standard and daylight time-zone names).

The value of the TZ environment variable should be set as follows (spaces are for clarity only):
std offset dst offset , rule

On the OS/2 platform, an alternate format is also supported.  Please refer to the following section for details.
The expanded format is as follows:
stdoffset[dst[offset][,start[/time],end[/time]]]
std, dst
three or more letters that are the designation for the standard (std) or summer (dst) time zone.  Only std is required.  If dst is omitted, then summer time does not apply in this locale.  Upper- and lowercase letters are allowed.  Any characters except for a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed.

offset
indicates the value one must add to the local time to arrive at Coordinated Universal Time (UTC).  The offset has the form:
hh[:mm[:ss]]

The minutes (mm) and seconds (ss) are optional.  The hour (hh) is required and may be a single digit.  The offset following std is required.  If no offset follows dst, summer time is assumed to be one hour ahead of standard time.  One or more digits may be used; the value is always interpreted as a decimal number.  The hour may be between 0 and 24, and the minutes (and seconds) - if present - between 0 and 59.   If preceded by a "-", the time zone will be east of the Prime Meridian; otherwise it will be west (which may be indicated by an optional preceding "+").

rule
indicates when to change to and back from summer time.  The rule has the form:
date/time,date/time

where the first date describes when the change from standard to summer time occurs and the second date describes when the change back happens.  Each time field describes when, in current local time, the change to the other time is made.

The format of date may be one of the following:
Jn
The Julian day n (1 <= n <= 365).  Leap days are not counted.  That is, in all years - including leap years - February 28 is day 59 and March 1 is day 60.  It is impossible to explicitly refer to the occasional February 29.

n
The zero-based Julian day (0 <= n <= 365).  Leap years are counted, and it is possible to refer to February 29.

Mm.n.d
The d'th day (0 <= d <= 6) of week n of month m of the year (1 <= n <= 5, 1 <= m <= 12, where week 5 means "the last d day in month m" which may occur in the fourth or fifth week).  Week 1 is the first week in which the d'th day occurs.  Day zero is Sunday.

The time has the same format as offset except that no leading sign ("+" or "-") is allowed.   The default, if time is omitted, is 02:00:00.

Whenever ctime, _ctime, localtime, _localtime or mktime is called, the time zone names contained in the external variable tzname will be set as if the tzset function had been called.  The same is true if the %Z directive of strftime is used.

Some examples are:
TZ=EST5EDT
Eastern Standard Time is 5 hours earlier than Coordinated Universal Time (UTC).  Standard time and daylight saving time both apply to this locale.  By default, Eastern Daylight Time (EDT) is one hour ahead of standard time (i.e., EDT4).   Since it is not specified, daylight saving time starts on the first Sunday of April at 2:00 A.M.  and ends on the last Sunday of October at 2:00 A.M.  This is the default when the TZ variable is not set.

TZ=EST5EDT4,M4.1.0/02:00:00,M10.5.0/02:00:00
This is the full specification for the default when the TZ variable is not set.  Eastern Standard Time is 5 hours earlier than Coordinated Universal Time (UTC).  Standard time and daylight saving time both apply to this locale.   Eastern Daylight Time (EDT) is one hour ahead of standard time.  Daylight saving time starts on the first (1) Sunday (0) of April (4) at 2:00 A.M.  and ends on the last (5) Sunday (0) of October (10) at 2:00 A.M.

TZ=PST8PDT
Pacific Standard Time is 8 hours earlier than Coordinated Universal Time (UTC).  Standard time and daylight saving time both apply to this locale.  By default, Pacific Daylight Time is one hour ahead of standard time (i.e., PDT7).  Since it is not specified, daylight saving time starts on the first Sunday of April at 2:00 A.M.  and ends on the last Sunday of October at 2:00 A.M.

TZ=NST3:30NDT1:30
Newfoundland Standard Time is 3 and 1/2 hours earlier than Coordinated Universal Time (UTC).  Standard time and daylight saving time both apply to this locale.  Newfoundland Daylight Time is 1 and 1/2 hours earlier than Coordinated Universal Time (UTC).

TZ=Central Europe Time-2:00
Central European Time is 2 hours later than Coordinated Universal Time (UTC).  Daylight saving time does not apply in this locale.

The OS/2 TZ Environment Variable


On the OS/2 platform, an alternate format of the TZ environment variable is supported, in addition to the standard format described in the preceding section.  The value of the OS/2 TZ environment variable should be set as follows (spaces are for clarity only):
std offset dst, rule

This format will be used if after scanning the standard format there are additional fields or the format has not been identified as standard.
The standard format is identified if an offset follows dst; characters J, M, /, or :  are found in rule; or some fields are empty.

The alternate expanded format is as follows (fields may not be empty):
stdoffsetdst,sm,sw,sd,st,em,ew,ed,et,shift
std, dst
three or more letters that are the designation for the standard (std) and summer (dst) time zone.  Upper- and lowercase letters are allowed.  Any characters except for a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL (\0) are allowed.

offset
indicates the value one must add to the local time to arrive at Coordinated Universal Time (UTC).  The offset has the form:
hh[:mm[:ss]]

The minutes (mm) and seconds (ss) are optional.  The hour (hh) is required and may be a single digit.  The value is always interpreted as a decimal number.  The hour may be between 0 and 24, and the minutes (and seconds) - if present - between 0 and 59.  If preceded by a "-", the time zone will be east of the Prime Meridian; otherwise it will be west (which may be indicated by an optional preceding "+").

rule
indicates when to change to and back from summer time and the time shift for summer time.  The rule has the form:
sm,sw,sd,st,em,ew,ed,et,shift

where sm,sw,sd,st describe when the change from standard to summer time occurs and em,ew,ed,et describe when the change back happens.

sm and em specify the starting and ending month (1 - 12) of the summer time.

sw and ew specify the starting and ending week of the summer time.  You can specify the last week of the month ( -1 ), or week 1 to 4.  Week 0 has a special meaning for the day field ( sd or ed ).

sd/ed Starting/ending day of dst,

0 - 6 ( weekday Sun to Sat ) if sw/ew is not zero,

1 - 31 ( day of the month ) if sw/ew is zero

st/et Starting/ending time (in seconds after midnight) of the summer time.

shift Amount of time change (in seconds).

An example of the default setting is:
TZ=EST5EDT,4,1,0,7200,10,-1,0,7200,3600
This is the full specification for the default when the TZ variable is not set.  Eastern Standard Time is 5 hours earlier than Coordinated Universal Time (UTC).  Standard time and daylight saving time both apply to this locale.   Eastern Daylight Time (EDT) is one hour ahead of standard time.  Daylight saving time starts on the first (1) Sunday (0) of April (4) at 2:00 A.M.  and ends on the last (-1) Sunday (0) of October (10) at 2:00 A.M.

Graphics Library


The Open Watcom C Graphics Library consists of a large number of functions that provide graphical image support under DOS and QNX.  This chapter provides an overview of this support.  The following topics are discussed.

Graphics Functions


Graphics functions are used to display graphical images such as lines and circles upon the computer screen.  Functions are also provided for displaying text along with the graphics output.

Graphics Adapters


Support is provided for both color and monochrome screens which are connected to the computer using any of the following graphics adapters:

Classes of Graphics Functions


The functions in the Open Watcom C Graphics Library can be organized into a number of classes:
Environment Functions

These functions deal with the hardware environment.

Coordinate System Functions

These functions deal with coordinate systems and mapping coordinates from one system to another.

Attribute Functions

These functions control the display of graphical images.

Drawing Functions

These functions display graphical images such as lines and ellipses.

Text Functions

These functions deal with displaying text in both graphics and text modes.

Graphics Text Functions

These functions deal with displaying graphics text.

Image Manipulation Functions

These functions store and retrieve screen images.

Font Manipulation Functions

These functions deal with displaying font based text.

Presentation Graphics Functions

These functions deal with displaying presentation graphics elements such as bar charts and pie charts.

The following subsections describe these function classes in more detail.  Each function in the class is noted with a brief description of its purpose.

Environment Functions


These functions deal with the hardware environment.  The _getvideoconfig function returns information about the current video mode and the hardware configuration.  The _setvideomode function selects a new video mode.

Some video modes support multiple pages of screen memory.  The visual page (the one displayed on the screen) may be different than the active page (the one to which objects are being written).

The following functions are defined:
_getactivepage
get the number of the current active graphics page

_getvideoconfig
get information about the graphics configuration

_getvisualpage
get the number of the current visual graphics page

_grstatus
get the status of the most recently called graphics library function

_setactivepage
set the active graphics page (the page to which graphics objects are drawn)

_settextrows
set the number of rows of text displayed on the screen

_setvideomode
select the video mode to be used

_setvideomoderows
select the video mode and the number of text rows to be used

_setvisualpage
set the visual graphics page (the page displayed on the screen)

Coordinate System Functions


These functions deal with coordinate systems and mapping coordinates from one system to another.  The Open Watcom C Graphics Library supports three coordinate systems: 
  1. Physical coordinates
  2. View coordinates
  3. Window coordinates

Physical coordinates match the physical dimensions of the screen.  The physical origin, denoted (0,0), is located at the top left corner of the screen.  A pixel to the right of the origin has a positive x-coordinate and a pixel below the origin will have a positive y-coordinate.  The x- and y-coordinates will never be negative values.

The view coordinate system can be defined upon the physical coordinate system by moving the origin from the top left corner of the screen to any physical coordinate (see the _setvieworg function).  In the view coordinate system, negative x- and y-coordinates are allowed.  The scale of the view and physical coordinate systems is identical (both are in terms of pixels)

The window coordinate system is defined in terms of a range of user-specified values (see the _setwindow function).  These values are scaled to map onto the physical coordinates of the screen.  This allows for consistent pictures regardless of the resolution (number of pixels) of the screen.

The following functions are defined:
_getcliprgn
get the boundary of the current clipping region

_getphyscoord
get the physical coordinates of a point in view coordinates

_getviewcoord
get the view coordinates of a point in physical coordinates

_getviewcoord_w
get the view coordinates of a point in window coordinates

_getviewcoord_wxy
get the view coordinates of a point in window coordinates

_getwindowcoord
get the window coordinates of a point in view coordinates

_setcliprgn
set the boundary of the clipping region

_setvieworg
set the position to be used as the origin of the view coordinate system

_setviewport
set the boundary of the clipping region and the origin of the view coordinate system

_setwindow
define the boundary of the window coordinate system

Attribute Functions


These functions control the display of graphical images such as lines and circles.  Lines and figures are drawn using the current color (see the _setcolor function), the current line style (see the _setlinestyle function), the current fill mask (see the _setfillmask function), and the current plotting action (see the _setplotaction function).

The following functions are defined:
_getarcinfo
get the endpoints of the most recently drawn arc

_getbkcolor
get the background color

_getcolor
get the current color

_getfillmask
get the current fill mask

_getlinestyle
get the current line style

_getplotaction
get the current plotting action

_remapallpalette
assign colors for all pixel values

_remappalette
assign color for one pixel value

_selectpalette
select a palette

_setbkcolor
set the background color

_setcolor
set the current color

_setfillmask
set the current fill mask

_setlinestyle
set the current line style

_setplotaction
set the current plotting action

Drawing Functions


These functions display graphical images such as lines and ellipses.  Functions exist to draw straight lines (see the _lineto function), rectangles (see the _rectangle function), polygons (see the _polygon function), ellipses (see the _ellipse function), elliptical arcs (see the _arc function) and pie-shaped wedges from ellipses (see the _pie function).

These figures are drawn using the attributes described in the previous section.  The functions ending with _w or _wxy use the window coordinate system; the others use the view coordinate system.

The following functions are defined:
_arc
draw an arc

_arc_w
draw an arc using window coordinates

_arc_wxy
draw an arc using window coordinates

_clearscreen
clear the screen and fill with the background color

_ellipse
draw an ellipse

_ellipse_w
draw an ellipse using window coordinates

_ellipse_wxy
draw an ellipse using window coordinates

_floodfill
fill an area of the screen with the current color

_floodfill_w
fill an area of the screen in window coordinates with the current color

_getcurrentposition
get the coordinates of the current output position

_getcurrentposition_w
get the window coordinates of the current output position

_getpixel
get the color of the pixel at the specified position

_getpixel_w
get the color of the pixel at the specified position in window coordinates

_lineto
draw a line from the current position to a specified position

_lineto_w
draw a line from the current position to a specified position in window coordinates

_moveto
set the current output position

_moveto_w
set the current output position using window coordinates

_pie
draw a wedge of a "pie"

_pie_w
draw a wedge of a "pie" using window coordinates

_pie_wxy
draw a wedge of a "pie" using window coordinates

_polygon
draw a polygon

_polygon_w
draw a polygon using window coordinates

_polygon_wxy
draw a polygon using window coordinates

_rectangle
draw a rectangle

_rectangle_w
draw a rectangle using window coordinates

_rectangle_wxy
draw a rectangle using window coordinates

_setpixel
set the color of the pixel at the specified position

_setpixel_w
set the color of the pixel at the specified position in window coordinates

Text Functions


These functions deal with displaying text in both graphics and text modes.  This type of text output can be displayed in only one size.

This text is displayed using the _outtext and _outmem functions.  The output position for text follows the last text that was displayed or can be reset (see the _settextposition function).  Text windows can be created (see the _settextwindow function) in which the text will scroll.  Text is displayed with the current text color (see the _settextcolor function).

The following functions are defined:
_clearscreen
clear the screen and fill with the background color

_displaycursor
determine whether the cursor is to be displayed after a graphics function completes execution

_getbkcolor
get the background color

_gettextcolor
get the color used to display text

_gettextcursor
get the shape of the text cursor

_gettextposition
get the current output position for text

_gettextwindow
get the boundary of the current text window

_outmem
display a text string of a specified length

_outtext
display a text string

_scrolltextwindow
scroll the contents of the text window

_setbkcolor
set the background color

_settextcolor
set the color used to display text

_settextcursor
set the shape of the text cursor

_settextposition
set the output position for text

_settextwindow
set the boundary of the region used to display text

_wrapon
permit or disallow wrap-around of text in a text window

Graphics Text Functions


These functions deal with displaying graphics text.  Graphics text is displayed as a sequence of line segments, and can be drawn in different sizes (see the _setcharsize function), with different orientations (see the _settextorient function) and alignments (see the _settextalign function).  The functions ending with _w use the window coordinate system; the others use the view coordinate system.

The following functions are defined:
_gettextextent
get the bounding rectangle for a graphics text string

_gettextsettings
get information about the current settings used to display graphics text

_grtext
display graphics text

_grtext_w
display graphics text using window coordinates

_setcharsize
set the character size used to display graphics text

_setcharsize_w
set the character size in window coordinates used to display graphics text

_setcharspacing
set the character spacing used to display graphics text

_setcharspacing_w
set the character spacing in window coordinates used to display graphics text

_settextalign
set the alignment used to display graphics text

_settextorient
set the orientation used to display graphics text

_settextpath
set the path used to display graphics text

Image Manipulation Functions


These functions are used to transfer screen images.  The _getimage function transfers a rectangular image from the screen into memory.  The _putimage function transfers an image from memory back onto the screen.  The functions ending with _w or _wxy use the window coordinate system; the others use the view coordinate system.

The following functions are defined:
_getimage
store an image of an area of the screen into memory

_getimage_w
store an image of an area of the screen in window coordinates into memory

_getimage_wxy
store an image of an area of the screen in window coordinates into memory

_imagesize
get the size of a screen area

_imagesize_w
get the size of a screen area in window coordinates

_imagesize_wxy
get the size of a screen area in window coordinates

_putimage
display an image from memory on the screen

_putimage_w
display an image from memory on the screen using window coordinates

Font Manipulation Functions


These functions are for the display of fonts compatible with Microsoft Windows.  Fonts are contained in files with an extension of .FON.  Before font based text can be displayed, the fonts must be registered with the _registerfonts function, and a font must be selected with the _setfont function.

The following functions are defined:
_getfontinfo
get information about the currently selected font

_getgtextextent
get the length in pixels of a text string

_getgtextvector
get the current value of the font text orientation vector

_outgtext
display a string of text in the current font

_registerfonts
initialize the font graphics system

_setfont
select a font from among the registered fonts

_setgtextvector
set the font text orientation vector

_unregisterfonts
frees memory allocated by the font graphics system

Presentation Graphics Functions


These functions provide a system for displaying and manipulating presentation graphics elements such as bar charts and pie charts.  The presentation graphics functions can be further divided into three classes:
Display Functions

These functions are for the initialization of the presentation graphics system and the displaying of charts.

Analyze Functions

These functions calculate default values for chart elements without actually displaying the chart.

Utility Functions

These functions provide additional support to control the appearance of presentation graphics elements.

The following subsections describe these function classes in more detail.  Each function in the class is noted with a brief description of its purpose.

Display Functions


These functions are for the initialization of the presentation graphics system and the displaying of charts.  The _pg_initchart function initializes the system and should be the first presentation graphics function called.  The single-series functions display a single set of data on a chart; the multi-series functions (those ending with ms) display several sets of data on the same chart.

The following functions are defined:
_pg_chart
display a bar, column or line chart

_pg_chartms
display a multi-series bar, column or line chart

_pg_chartpie
display a pie chart

_pg_chartscatter
display a scatter chart

_pg_chartscatterms
display a multi-series scatter chart

_pg_defaultchart
initialize the chart environment for a specific chart type

_pg_initchart
initialize the presentation graphics system

Analyze Functions


These functions calculate default values for chart elements without actually displaying the chart.  The functions ending with ms analyze multi-series charts; the others analyze single-series charts.

The following functions are defined:
_pg_analyzechart
analyze a bar, column or line chart

_pg_analyzechartms
analyze a multi-series bar, column or line chart

_pg_analyzepie
analyze a pie chart

_pg_analyzescatter
analyze a scatter chart

_pg_analyzescatterms
analyze a multi-series scatter chart

Utility Functions


These functions provide additional support to control the appearance of presentation graphics elements.

The following functions are defined:
_pg_getchardef
get bit-map definition for a specific character

_pg_getpalette
get presentation graphics palette (colors, line styles, fill patterns and plot characters)

_pg_getstyleset
get presentation graphics style-set (line styles for window borders and grid lines)

_pg_hlabelchart
display text horizontally on a chart

_pg_resetpalette
reset presentation graphics palette to default values

_pg_resetstyleset
reset presentation graphics style-set to default values

_pg_setchardef
set bit-map definition for a specific character

_pg_setpalette
set presentation graphics palette (colors, line styles, fill patterns and plot characters)

_pg_setstyleset
set presentation graphics style-set (line styles for window borders and grid lines)

_pg_vlabelchart
display text vertically on a chart

Graphics Header Files


All program modules which use the Graphics Library should include the header file graph.h.  This file contains prototypes for all the functions in the library as well as the structures and constants used by them.

Modules using the presentation graphics functions should also include the header file pgchart.h.

DOS Considerations


For the most part, DOS (Disk Operating System) for your personal computer can be ignored, unless an application is highly dependent upon the hardware or uses specialized functions from the operating system.  In this section, some of these aspects will be addressed.  For a more detailed explanation, the technical documentation for the DOS that you are using should be consulted.

DOS Devices


Most of the hardware devices attached to your computer have names which are recognized by DOS.  These names cannot be used as the names of files.  Some examples are:
CON
the console (screen)

AUX
the serial (auxiliary) port

COM1
serial port 1

COM2
serial port 2

PRN
the printer on the parallel port

LPT1
the printer on the first parallel port

LPT2
the printer on the second parallel port

LPT3
the printer on the third parallel port

NUL
a non-existent device, which accepts (and discards) output

Disks (such as diskette drives and hard disks) are specified as single letters, starting with the letter A.  A colon character (:) follows the letter for the drive.  Either uppercase or lowercase letters can be used.  Some examples are:
A:
the first disk drive

a:
the first disk drive

e:
the fifth disk drive

DOS Directories


Each disk drive is conceptually divided into directories.  Each directory is capable of containing files and/or other directories.  The initial directory, called the root directory, is not named; all other directories are named and can be accessed with a path specification.  A path is either absolute or relative to the current working directory.  Some examples are:
b:\
the root directory of the second disk drive

\
the root directory of the current disk drive

\outer\middle\inner

directory inner which is contained within directory middle which is contained within directory outer which is contained within the root directory of the current disk drive.

Directory names are separated by backslash characters (\).  The initial backslash character informs DOS that the path starts with the root directory.  When the first character is not a backslash, the path starts with the current working directory on the indicated device.

The DOS CHDIR (CD) command can be used to change the current working directory for a device.  Suppose that the following DOS commands were issued:

     
     chdir a:\apps\payroll
     chdir c:\mydir

Then, the following path specifications are:
Relative Path
Absolute Path

a:xxx\y
a:\apps\payroll\xxx\y

c:zzzzz
c:\mydir\zzzzz

When no drive is specified, DOS uses the current disk drive.

DOS File Names


The name of a file within a directory has the format filename.ext where the required filename portion is up to eight characters in length and the optional ext portion is up to three characters in length.  A period character (.) separates the two names when the ext portion is present.

More than eight characters can be given in the filename.  DOS truncates the name to eight characters when a longer filename is given.  This may lead to erroneous results in some cases, since the files MYBIGDATAFILE and MYBIGDATES both refer to the file MYBIGDAT.

The characters used in file names may be letters, digits as well as some other characters documented in your DOS technical documentation.  Most people restrict their file names to contain only letters and digits.  Uppercase and lowercase letters are treated as being equivalent (file names are case insensitive).  Thus, the files

     
     MYDATA.NEW
     mydata.new
     MyData.New

all refer to the same file.

You cannot use a DOS device name (such as CON or PRN, for example) for a file name.  See the section DOS Devices for a list of these reserved names.

A complete file designation has the following format:

     
     drive:\path\filename.ext

where:
drive:
is an optional disk drive specification.  If omitted, the default drive is used.  Some examples are:
     
     A:  (first disk drive)
     c:  (third disk drive)

\path\
is the path specification for the directory containing the desired file.  Some examples are:
     
     \mylib\
     \apps\payroll\

filename.ext
is the name of the file.

Suppose that the current working directories are as follows:
Drive
Directory

A:
\payroll

B:
\           (root directory)

C:
\source\c

and that the default disk drive is C:.  Then, the following file designations will result in the indicated file references:
Designation
Actual File

pgm.c
C:\SOURCE\C\PGM.C

\basic.dat
C:\BASIC.DAT

paypgm\outsep.c
C:\SOURCE\C\PAYPGM\OUTSEP.C

b:data
B:\DATA

a:employee
A:\PAYROLL\EMPLOYEE

a:\deduct\yr1988
A:\DEDUCT\YR1988

DOS Files


DOS files are stored within directories on disk drives.  Most software, including Open Watcom C/C++, treats files in two representations:
BINARY
These files can contain arbitrary data.  It is the responsibility of the software to recognize records within the file if they exist.

TEXT
These files contain lines of "printable" characters.  Each line is delimited by a carriage return character followed by a linefeed character.

Since the conceptual view of text files in the C and C++ languages is that lines are terminated by only linefeed characters, the Open Watcom C library will remove carriage returns on input and add them on output, provided the mode is set to be text.  This mode is set upon opening the file or with the _setmode function.

DOS Commands


DOS commands are documented in the technical documentation for your DOS system.  These may be invoked from a C or C++ program with the system function.

DOS Interrupts


DOS interrupts and 8086 interrupts are documented in the technical documentation for your DOS system.  These may be generated from a C or C++ program by calling the bdos, intdos, intdosx, intr, intrf, int386, int386x, int86 and int86x functions.

DOS Processes


Currently, DOS has the capability to execute only one process at a time.  Thus, when a process is initiated with the spawn... parameter P_WAIT, the new process will execute to completion before control returns to the initiating program.  Otherwise, the new task replaces the initial task.  Tasks can be started by using the system, exec... and spawn... functions.

Library Functions and Macros


Each of the functions or macros in the C Library is described in this chapter.  Each description consists of a number of subsections:
Synopsis:
This subsection gives the header files that should be included within a source file that references the function or macro.   It also shows an appropriate declaration for the function or for a function that could be substituted for a macro.   This declaration is not included in your program; only the header file(s) should be included.
When a pointer argument is passed to a function and that function does not modify the item indicated by that pointer, the argument is shown with const before the argument.  For example,

     
     const char *string

indicates that the array pointed at by string is not changed.

Constraints:
This subsection describes Runtime-constraints for Safer C Library functions.

Safer C:
This subsection points to the Safer C version of the described "unsafe" function.

Description:
This subsection is a description of the function or macro.

Returns:
This subsection describes the return value (if any) for the function or macro.

Errors:
This subsection describes the possible errno values.

See Also:
This optional subsection provides a list of related functions or macros.

Example:
This optional subsection consists of one or more examples of the use of the function.  The examples are often just fragments of code (not complete programs) for illustration purposes.

Classification:
This subsection provides an indication of where the function or macro is commonly found.  The following notation is used:
ISO C
These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 9899:1989.

ISO C90
These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 9899:1990.

ISO C95
These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 9899:1990/AMD 1:1995.

ISO C99
These functions or macros are defined by the ISO/ANSI C standard ISO/IEC 9899:1999.

POSIX 1003.1
The functions or macros are not defined by the ISO C standard.  These functions are specified in the document IEEE Standard Portable Operating System Interface for Computer Environments (IEEE Draft Standard 1003.1-1990).

POSIX 1003.2
These functions or macros are not defined by the ISO C standard.  These functions are specified in the document Shell and Utility Application Interface for Computer Operating System Environments (IEEE Computer Society Working Group 1003.2).

POSIX 1003.4
These functions or macros are not defined by the ISO C standard.  These functions are specified in the document Realtime Extensions for Computer Operating System Environments (IEEE Computer Society Working Group 1003.4).

Intel
These functions or macros are neither ISO C nor POSIX.  It performs a function related to the Intel x86 architecture.   It may be found in other implementations of C for personal computers using Intel chips.  Use these functions with caution, if portability is a consideration.

BIOS
These functions access a service of the BIOS found in IBM Personal Computers and compatibles.  These functions should not be used if portability is a consideration.

DOS
These functions or macros are neither ISO C nor POSIX.  They perform a function related to DOS.  They may be found in other implementations of C for personal computers with DOS.  Use these functions with caution, if portability is a consideration.

OS/2
These functions are specific to OS/2.

PC Graphics
These functions are part of the PC graphics library.

Windows
These functions are specific to Microsoft Windows.

WATCOM
These functions or macros are neither ISO C nor POSIX.  They may be found in other implementations of the C language, but caution should be used if portability is a consideration.

TR 24731
These functions are "safer" versions of normal C library functions.  They perform more checks on parameters and should be used in preference over their "unsafe" version.

Systems:
This subsection provides an indication of where the function or macro is supported.  The following notation is used:
All
This function is available on all systems (we do not include RDOS, Linux, Netware or DOS/PM in this category).

DOS
This function is available on both 16-bit DOS and 32-bit extended DOS.

DOS/16
This function is available on 16-bit, real-mode DOS.

DOS/32
This function is available on 32-bit, protected-mode extended DOS.

DOS/PM
This 16-bit DOS protected-mode function is supported under Phar Lap's 286|DOS-Extender "RUN286".  The function is found in one of Open Watcom's 16-bit protected-mode DOS libraries (DOSPM*.LIB under the 16-bit OS2 subdirectory).

Linux
This function is available on the Linux operating system for Intel 80386 and upwards compatible systems.

MACRO
This function is implemented as a macro (#define) on all systems.

Math
This function is a math function.  Math functions are available on all systems.

Netware
This function is available on the 32-bit Novell Netware operating system.

OS/2 1.x
This function is available on IBM OS/2 1.x, a 16-bit protected-mode system for Intel 80286 and upwards compatible systems.
When "(MT)" appears after OS/2, it refers to the CLIBMTL library which supports multi-threaded applications.

When "(DL)" appears after OS/2, it refers to the CLIBDLL library which supports creation of Dynamic Link Libraries.

When "(all)" appears after "OS/2 1", it means all versions of the OS/2 1.x libraries.

If a function is missing from the OS/2 library, it may be found in Open Watcom's 16-bit protected-mode DOS libraries (DOSPM*.LIB) for Phar Lap's 286|DOS-Extender (RUN286).

OS/2-32
This function is available on 32-bit IBM OS/2, a protected-mode system for Intel 80386 and upwards compatible systems.

RDOS
This function is available on RDOS operating system.

QNX
This function is available on QNX Software Systems' 16 or 32-bit operating systems.

QNX/16
This function is available on QNX Software Systems' 16-bit operating system.

QNX/32
This function is available on QNX Software Systems' 32-bit operating system.

Windows
This function is available on 16-bit, protected-mode Windows 3.x.

Win386
This function is available on Microsoft Windows 3.x, using Open Watcom's Windows Extender for 32-bit protected-mode applications running on Intel 386 or upward compatible systems.

Win32
This function is available on 32-bit Microsoft Windows platforms (Windows 95, Windows 98, Windows NT, Windows 2000, etc.).   It may also be available for Windows 3.x using Win32s support.

abort

Synopsis:

#include <stdlib.h>
void abort( void );
Description:
The abort function raises the signal SIGABRT.  The default action for SIGABRT is to terminate program execution, returning control to the process that started the calling program (usually the operating system).  The status unsuccessful termination is returned to the invoking process by means of the function call raise(SIGABRT).  The exit code returned to the invoking process is EXIT_FAILURE which is defined in the <stdlib.h> header file.
Returns:
The abort function does not return to its caller.
See Also:
atexit, _bgetcmd, exec..., exit, _Exit, _exit, getcmd, getenv, main, putenv, spawn..., system, _wsystem
Example:

#include <stdlib.h>

void main()
  {
    int major_error = 1;

    if( major_error )
      abort();
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

abort_handler_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void abort_handler_s(
        const char * restrict msg,
        void * restrict ptr,
        errno_t error );
Description:
The abort_handler_s function may be passed as an argument to the set_constraint_handler_s function.  It writes a message on the standard error stream in the following format:
     
     Runtime-constraint violation: <msg>

The abort_handler_s function then calls the abort function.
Returns:
The abort_handler_s function does not return to its caller.
See Also:
ignore_handler_s, set_constraint_handler_s
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
#include <stdio.h>

void main( void )
{
    constraint_handler_t    old_handler;

    old_handler = set_constraint_handler_s( abort_handler_s );
    if( getenv_s( NULL, NULL, 0, NULL ) ) {
        printf( "getenv_s failed\n" );
    }
    set_constraint_handler_s( old_handler );
}

produces the following:

Runtime-constraint violation: getenv_s, name == NULL.
ABNORMAL TERMINATION
Classification:
TR 24731
Systems:
All, Linux, RDOS, Netware

abs

Synopsis:

#include <stdlib.h>
int abs( int j );
Description:
The abs function returns the absolute value of its integer argument j.
Returns:
The abs function returns the absolute value of its argument.
See Also:
labs, llabs, imaxabs, fabs
Example:

#include <stdio.h>
#include <stdlib.h>

void main( void )
{
    printf( "%d %d %d\n", abs( -5 ), abs( 0 ), abs( 5 ) );
}

produces the following:

5 0 5
Classification:
ISO C90
Systems:
All, Linux, RDOS, Netware

access, _access, _waccess

Synopsis:

#include <io.h>
int access( const char *path, int mode );
int _access( const char *path, int mode );
int _waccess( const wchar_t *path, int mode );
Description:
The access function determines if the file or directory specified by path exists and if it can be accessed with the file permission given by mode.
When the value of mode is zero, only the existence of the file is verified.  The read and/or write permission for the file can be determined when mode is a combination of the bits:
Bit     Meaning
R_OK
test for read permission

W_OK
test for write permission

X_OK
test for execute permission

F_OK
test for existence of file

With DOS, all files have read permission; it is a good idea to test for read permission anyway, since a later version of DOS may support write-only files.

The _access function is identical to access.  Use _access for ANSI naming conventions.

The _waccess function is a wide character version of access that operates with wide character strings.
Returns:
The access function returns zero if the file or directory exists and can be accessed with the specified mode.  Otherwise, -1 is returned and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EACCES
Access denied because the file's permission does not allow the specified access.

ENOENT
Path or file not found.
See Also:
chmod, fstat, open, _sopen, stat
Example:

#include <stdio.h>
#include <stdlib.h>
#include <io.h>

void main( int argc, char *argv[] )
  {
    if( argc != 2 ) {
      fprintf( stderr, "Use: check <filename>\n" );
      exit( 1 );
    }

    if( access( argv[1], F_OK ) == 0 ) {
      printf( "%s exists\n", argv[1] );
    } else {
      printf( "%s does not exist\n", argv[1] );
      exit( EXIT_FAILURE );
    }
    if( access( argv[1], R_OK ) == 0 ) {
      printf( "%s is readable\n", argv[1] );
    }
    if( access( argv[1], W_OK ) == 0 ) {
      printf( "%s is writeable\n", argv[1] );
    }
    if( access( argv[1], X_OK ) == 0 ) {
      printf( "%s is executable\n", argv[1] );
    }
    exit( EXIT_SUCCESS );
  }
Classification:
POSIX 1003.1
_access conforms to ANSI naming conventions
_waccess is WATCOM
Systems:
access - All, Linux, RDOS, Netware
_access - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_waccess - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

acos

Synopsis:

#include <math.h>
double acos( double x );
Description:
The acos function computes the principal value of the arccosine of x.  A domain error occurs for arguments not in the range [-1,1].
Returns:
The acos function returns the arccosine in the range [0,P].  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr stream.
See Also:
asin, atan, atan2, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", acos(.5) );
  }

produces the following:

1.047197
Classification:
ISO C
Systems:
Math

acosh

Synopsis:

#include <math.h>
double acosh( double x );
Description:
The acosh function computes the inverse hyperbolic cosine of x.  A domain error occurs if the value of x is less than 1.0.
Returns:
The acosh function returns the inverse hyperbolic cosine value.  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr stream.
See Also:
asinh, atanh, cosh, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", acosh( 1.5 ) );
  }

produces the following:

0.962424
Classification:
WATCOM
Systems:
Math

alloca

Synopsis:

#include <malloc.h>
void *alloca( size_t size );
Description:
The alloca function allocates space for an object of size bytes from the stack.  The allocated space is automatically discarded when the current function exits.  The alloca function should not be used in an expression that is an argument to a function.
Returns:
The alloca function returns a pointer to the start of the allocated memory.  The return value is NULL if there is insufficient stack space available.
See Also:
calloc, malloc, stackavail
Example:

#include <stdio.h>
#include <string.h>
#include <malloc.h>
FILE *open_err_file( char * );

void main()
  {
    FILE *fp;

    fp = open_err_file( "alloca" );
    if( fp == NULL ) {
      printf( "Unable to open error file\n" );
    } else {
      fclose( fp );
    }
  }

FILE *open_err_file( char *name )
  {
     char *buffer;
     /* allocate temp buffer for file name */
     buffer = (char *) alloca( strlen(name) + 5 );
     if( buffer ) {
       sprintf( buffer, "%s.err", name );
       return( fopen( buffer, "w" ) );
     }
     return( (FILE *) NULL );
  }
Classification:
WATCOM
Systems:
MACRO

_arc, _arc_w, _arc_wxy

Synopsis:

#include <graph.h>
short _FAR _arc( short x1, short y1,
                 short x2, short y2,
                 short x3, short y3,
                 short x4, short y4 );

short _FAR _arc_w( double x1, double y1,
                   double x2, double y2,
                   double x3, double y3,
                   double x4, double y4 );

short _FAR _arc_wxy( struct _wxycoord _FAR *p1,
                      struct _wxycoord _FAR *p2,
                      struct _wxycoord _FAR *p3,
                      struct _wxycoord _FAR *p4 );
Description:
The _arc functions draw elliptical arcs.  The _arc function uses the view coordinate system.  The _arc_w and _arc_wxy functions use the window coordinate system.
The center of the arc is the center of the rectangle established by the points (x1,y1) and (x2,y2).   The arc is a segment of the ellipse drawn within this bounding rectangle.  The arc starts at the point on this ellipse that intersects the vector from the centre of the ellipse to the point (x3,y3).  The arc ends at the point on this ellipse that intersects the vector from the centre of the ellipse to the point (x4,y4).  The arc is drawn in a counter-clockwise direction with the current plot action using the current color and the current line style.

The following picture illustrates the way in which the bounding rectangle and the vectors specifying the start and end points are defined.


When the coordinates (x1,y1) and (x2,y2) establish a line or a point (this happens when one or more of the x-coordinates or y-coordinates are equal), nothing is drawn.

The current output position for graphics output is set to be the point at the end of the arc that was drawn.
Returns:
The _arc functions return a non-zero value when the arc was successfully drawn; otherwise, zero is returned.
See Also:
_ellipse, _pie, _rectangle, _getarcinfo, _setcolor, _setlinestyle, _setplotaction
Example:

#include <conio.h>
#include <graph.h>

main()
{
    _setvideomode( _VRES16COLOR );
    _arc( 120, 90, 520, 390, 500, 20, 450, 460 );
    getch();
    _setvideomode( _DEFAULTMODE );
}

produces the following:

Classification:
PC Graphics
Systems:
_arc - DOS
_arc_w - DOS
_arc_wxy - DOS

asctime Functions

Synopsis:

#include <time.h>
char * asctime( const struct tm *timeptr );
char *_asctime( const struct tm *timeptr, char *buf );
wchar_t *_wasctime( const struct tm *timeptr );
wchar_t *__wasctime( const struct tm *timeptr, wchar_t *buf );

struct  tm {
  int tm_sec;   /* seconds after the minute -- [0,61] */
  int tm_min;   /* minutes after the hour   -- [0,59] */
  int tm_hour;  /* hours after midnight     -- [0,23] */
  int tm_mday;  /* day of the month         -- [1,31] */
  int tm_mon;   /* months since January     -- [0,11] */
  int tm_year;  /* years since 1900                    */
  int tm_wday;  /* days since Sunday        -- [0,6]  */
  int tm_yday;  /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag         */
};
Safer C:
The Safer C Library extension provides the asctime_s function which is a safer alternative to asctime.  This newer asctime_s function is recommended to be used instead of the traditional "unsafe" asctime function.
Description:
The asctime functions convert the time information in the structure pointed to by timeptr into a string containing exactly 26 characters.  This string has the form shown in the following example:
     
     Sat Mar 21 15:58:27 1987\n\0

All fields have a constant width.  The new-line character '\n' and the null character '\0' occupy the last two positions of the string.

The ISO C function asctime places the result string in a static buffer that is re-used each time asctime or ctime is called.  The non-ISO C function _asctime places the result string in the buffer pointed to by buf.

The _wasctime and __wasctime functions are identical to their asctime and _asctime counterparts except that they deal with wide character strings.
Returns:
The asctime functions return a pointer to the character string result.
See Also:
asctime_s, clock, ctime Functions, ctime_s, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#include <stdio.h>
#include <time.h>

void main()
  {
    struct tm  time_of_day;
    time_t     ltime;
    auto char  buf[26];

    time( &ltime );
    _localtime( &ltime, &time_of_day );
    printf( "Date and time is: %s\n",
            _asctime( &time_of_day, buf ) );
  }

produces the following:

Date and time is: Sat Mar 21 15:58:27 1987
Classification:
ISO C
_asctime is WATCOM
_wasctime is WATCOM
__wasctime is WATCOM
Systems:
asctime - All, Linux, RDOS, Netware
_asctime - All, RDOS, Netware
_wasctime - All, Linux
__wasctime - All, Linux

asctime_s, _wasctime_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
errno_t asctime_s( char * s,
                   rsize_t maxsize,
                   const struct tm * timeptr);
errno_t _wasctime_s( wchar_t * s,
                      rsize_t maxsize,
                      const struct tm * timeptr);

struct  tm {
  int tm_sec;   /* seconds after the minute -- [0,61] */
  int tm_min;   /* minutes after the hour   -- [0,59] */
  int tm_hour;  /* hours after midnight     -- [0,23] */
  int tm_mday;  /* day of the month         -- [1,31] */
  int tm_mon;   /* months since January     -- [0,11] */
  int tm_year;  /* years since 1900                    */
  int tm_wday;  /* days since Sunday        -- [0,6]  */
  int tm_yday;  /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag         */
};
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and asctime_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither s nor timeptr shall be a null pointer.  maxsize shall not be less than 26 and shall not be greater than RSIZE_MAX.  The broken-down time pointed to by timeptr shall be normalized.  The calendar year represented by the broken-down time pointed to by timeptr shall not be less than calendar year 0 and shall not be greater than calendar year 9999.  If there is a runtime-constraint violation, there is no attempt to convert the time, and s[0] is set to a null character if s is not a null pointer and maxsize is not zero and is not greater than RSIZE_MAX.
Description:
The asctime_s function converts the normalized broken-down time in the structure pointed to by timeptr into a 26 character (including the null character) string in the form
     
     Sun Sep 16 01:03:52 1973\n\0

The fields making up this string are (in order):
  1. The name of the day of the week represented by timeptr->tm_wday using the following three character weekday names:

    Sun, Mon, Tue, Wed, Thu, Fri, and Sat.
  2. The character space.
  3. The name of the month represented by timeptr->tm_mon using the following three character month names:

    Jan, Feb, Mar,Apr,May,Jun, Jul, Aug, Sep, Oct, Nov, and Dec.
  4. The character space.
  5. The value of timeptr->tm_mday as if printed using the fprintf format "%2d".
  6. The character space.
  7. The value of timeptr->tm_hour as if printed using the fprintf format "%.2d".
  8. The character colon.
  9. The value of timeptr->tm_min as if printed using the fprintf format "%.2d".
  10. The character colon.
  11. The value of timeptr->tm_sec as if printed using the fprintf format "%.2d".
  12. The character space.
  13. The value of timeptr->tm_year + 1900 as if printed using the fprintf format "%4d".
  14. The character new line.
  15. The null character.

The _wasctime_s function is a wide character version of asctime_s that operates with wide character strings.
Returns:
The asctime_s function returns zero if there was no runtime-constraint violation.  Otherwise, a non-zero value is returned.
See Also:
asctime Functions, clock, ctime Functions, ctime_s, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <time.h>

void main()
{
    struct tm  time_of_day;
    time_t     ltime;
    auto char  buf[26];

    time( &ltime );
    _localtime( &ltime, &time_of_day );
    asctime_s( buf, sizeof( buf ), &time_of_day );
    printf( "Date and time is: %s\n", buf );
}

produces the following:

Date and time is: Mon Jan 30 11:32:45 2006
Classification:
TR 24731
_wasctime_s is WATCOM
Systems:
asctime_s - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS, Netware
_wasctime_s - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux

asin

Synopsis:

#include <math.h>
double asin( double x );
Description:
The asin function computes the principal value of the arcsine of x.  A domain error occurs for arguments not in the range [-1,1].
Returns:
The asin function returns the arcsine in the range [-P/2,P/2].  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr stream.
See Also:
acos, atan, atan2, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", asin(.5) );
  }

produces the following:

0.523599
Classification:
ISO C
Systems:
Math

asinh

Synopsis:

#include <math.h>
double asinh( double x );
Description:
The asinh function computes the inverse hyperbolic sine of x.
Returns:
The asinh function returns the inverse hyperbolic sine value.
See Also:
acosh, atanh, sinh, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", asinh( 0.5 ) );
  }

produces the following:

0.481212
Classification:
WATCOM
Systems:
Math

assert

Synopsis:

#include <assert.h>
void assert( int expression );
Description:
The assert macro prints a diagnostic message upon the stderr stream and terminates the program if expression is false (0).  The diagnostic message has the form
Assertion failed:  expression, file filename, line linenumber

where filename is the name of the source file and linenumber is the line number of the assertion that failed in the source file.  Filename and linenumber are the values of the preprocessing macros __FILE__ and __LINE__ respectively.  No action is taken if expression is true (non-zero).

The assert macro is typically used during program development to identify program logic errors.  The given expression should be chosen so that it is true when the program is functioning as intended.  After the program has been debugged, the special "no debug" identifier NDEBUG can be used to remove assert calls from the program when it is re-compiled.  If NDEBUG is defined (with any value) with a -d command line option or with a #define directive, the C preprocessor ignores all assert calls in the program source.
Returns:
The assert macro does not return a value.
Example:

#include <stdio.h>
#include <assert.h>

void process_string( char *string )
  {
    /* use assert to check argument */
    assert( string != NULL );
    assert( *string != '\0' );
    /* rest of code follows here */
  }

void main()
  {
    process_string( "hello" );
    process_string( "" );
  }
Classification:
ISO C
Systems:
MACRO

atan

Synopsis:

#include <math.h>
double atan( double x );
Description:
The atan function computes the principal value of the arctangent of x.
Returns:
The atan function returns the arctangent in the range (-P/2,P/2).
See Also:
acos, asin, atan2
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", atan(.5) );
  }

produces the following:

0.463648
Classification:
ISO C
Systems:
Math

atan2

Synopsis:

#include <math.h>
double atan2( double y, double x );
Description:
The atan2 function computes the principal value of the arctangent of y/x, using the signs of both arguments to determine the quadrant of the return value.  A domain error occurs if both arguments are zero.
Returns:
The atan2 function returns the arctangent of y/x, in the range (-P,P).  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr stream.
See Also:
acos, asin, atan, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", atan2( .5, 1. ) );
  }

produces the following:

0.463648
Classification:
ISO C
Systems:
Math

atanh

Synopsis:

#include <math.h>
double atanh( double x );
Description:
The atanh function computes the inverse hyperbolic tangent of x.  A domain error occurs if the value of x is outside the range (-1,1).
Returns:
The atanh function returns the inverse hyperbolic tangent value.  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to EDOM, and print a "DOMAIN error" diagnostic message using the stderr stream.
See Also:
acosh, asinh, matherr, tanh
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", atanh( 0.5 ) );
  }

produces the following:

0.549306
Classification:
WATCOM
Systems:
Math

atexit

Synopsis:

#include <stdlib.h>
int atexit( void (*func)(void) );
Description:
The atexit function is passed the address of function func to be called when the program terminates normally.   Successive calls to atexit create a list of functions that will be executed on a "last-in, first-out" basis.   No more than 32 functions can be registered with the atexit function.
The functions have no parameters and do not return values.
Returns:
The atexit function returns zero if the registration succeeds, non-zero if it fails.
See Also:
abort, _Exit, _exit, exit
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
    extern void func1(void), func2(void), func3(void);

    atexit( func1 );
    atexit( func2 );
    atexit( func3 );
    printf( "Do this first.\n" );
  }

void func1(void) { printf( "last.\n" ); }

void func2(void) { printf( "this " ); }

void func3(void) { printf( "Do " ); }

produces the following:

Do this first.
Do this last.
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

atof, _wtof

Synopsis:

#include <stdlib.h>
double atof( const char *ptr );
double _wtof( const wchar_t *ptr );
Description:
The atof function converts the string pointed to by ptr to double representation.  It is equivalent to
     
     strtod( ptr, (char **)NULL )

The _wtof function is a wide character version of atof that operates with wide character strings.   It is equivalent to

     
     wcstod( ptr, (wchar_t **)NULL )
Returns:
The atof function returns the converted value.  Zero is returned when the input string cannot be converted.   In this case, errno is not set.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
sscanf, strtod
Example:

#include <stdlib.h>

void main()
  {
    double x;

    x = atof( "3.1415926" );
  }
Classification:
ISO C
_wtof is WATCOM
Systems:
atof - Math
_wtof - Math

atoi, _wtoi

Synopsis:

#include <stdlib.h>
int atoi( const char *ptr );
int _wtoi( const wchar_t *ptr );
Description:
The atoi function converts the string pointed to by ptr to int representation.
The _wtoi function is a wide character version of atoi that operates with wide character strings.
Returns:
The atoi function returns the converted value.
See Also:
atol, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, strtoimax, strtoumax, ultoa, ulltoa, utoa
Example:

#include <stdlib.h>

void main()
{
    int x;

    x = atoi( "-289" );
}
Classification:
ISO C
_wtoi is WATCOM
Systems:
atoi - All, Linux, RDOS, Netware
_wtoi - All, Linux, RDOS

atol, _wtol

Synopsis:

#include <stdlib.h>
long int atol( const char *ptr );
long int _wtol( const wchar_t *ptr );
Description:
The atol function converts the string pointed to by ptr to long int representation.
The _wtol function is a wide character version of atol that operates with wide character strings.
Returns:
The atol function returns the converted value.
See Also:
atoi, atoll, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, strtoimax, strtoumax, ultoa, ulltoa, utoa
Example:

#include <stdlib.h>

void main()
{
    long int x;

    x = atol( "-289" );
}
Classification:
ISO C
_wtol is WATCOM
Systems:
atol - All, Linux, RDOS, Netware
_wtol - All, Linux, RDOS

atoll, _wtoll

Synopsis:

#include <stdlib.h>
long long int atoll( const char *ptr );
long long int _wtoll( const wchar_t *ptr );
Description:
The atoll function converts the string pointed to by ptr to long long int representation.
The _wtoll function is a wide character version of atoll that operates with wide character strings.
Returns:
The atoll function returns the converted value.
See Also:
atoi, atol, itoa, ltoa, lltoa, sscanf, strtol, strtoll, strtoul, strtoull, strtoimax, strtoumax, ultoa, ulltoa, utoa
Example:

#include <stdlib.h>

void main()
{
    long int x;

    x = atoll( "-289356768201" );
}
Classification:
ISO C
_wtoll is WATCOM
Systems:
atoll - All, Linux, RDOS, Netware
_wtoll - All, Linux, RDOS

_atouni

Synopsis:

#include <stdlib.h>
wchar_t *_atouni( wchar_t *wcs, const char *sbcs );
Description:
The _atouni function converts the string pointed to by sbcs to a wide character string and places it in the buffer pointed to by wcs.
The conversion ends at the first null character.
Returns:
The _atouni function returns the first argument as a result.
See Also:
atoi, atol, itoa, ltoa, strtod, strtol, strtoul, ultoa, utoa
Example:

#include <stdlib.h>

void main()
  {
    wchar_t wcs[12];

    _atouni( wcs, "Hello world" );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

basename

Synopsis:

#include <libgen.h>
char *basename( char *path );
Description:
The basename function returns a pointer to the final component of a pathname pointed to by the path argument, deleting trailing path separators.
If the string pointed to by path consists entirely of path separators, a string consisting of single path separator is returned.

If path is a null pointer or points to an empty string, a pointer to the string "." is returned.

The basename function may modify the string pointed to by path and may return a pointer to static storage that may be overwritten by a subsequent call to basename

The basename function is not re-entrant or thread-safe.
Returns:
The basename function returns a pointer to the final component of path.
See Also:
dirname
Example:

#include <stdio.h>
#include <libgen.h>

int main( void )
{

    puts( basename( "/usr/lib" ) );
    puts( basename( "//usr//lib//" ) );
    puts( basename( "///" ) );
    puts( basename( "foo" ) );
    puts( basename( NULL ) );
    return( 0 );
}

produces the following:

lib
lib
/
foo
.
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

bdos

Synopsis:

#include <dos.h>
int bdos( int dos_func, unsigned dx, unsigned char al );
Description:
The bdos function causes the computer's central processor (CPU) to be interrupted with an interrupt number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function.  Before the interrupt, the DX register is loaded from dx, the AH register is loaded with the DOS function number from dos_func and the AL register is loaded from al.  The remaining registers are passed unchanged to DOS.
You should consult the technical documentation for the DOS operating system you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The bdos function returns the value of the AX register after the interrupt has completed.
See Also:
int386, int386x, int86, int86x, intdos, intdosx, intr, intrf, segread
Example:

#include <dos.h>

#define DISPLAY_OUTPUT  2

void main()
  {
    int rc;

    rc = bdos( DISPLAY_OUTPUT, 'B', 0 );
    rc = bdos( DISPLAY_OUTPUT, 'D', 0 );
    rc = bdos( DISPLAY_OUTPUT, 'O', 0 );
    rc = bdos( DISPLAY_OUTPUT, 'S', 0 );
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, DOS/PM

_beginthread, _beginthreadex

Synopsis:

#include <process.h>
#if defined(__386__)
#   define FAR
#else
#   define FAR __far
#endif

#if defined(__NT__)
unsigned long _beginthread(
        void (*start_address)(void *),
        unsigned stack_size,
        void     *arglist);
unsigned long _beginthreadex(
        void *security,
        unsigned stack_size,
        unsigned (__stdcall *start_address)(void *),
        void *arglist,
        unsigned initflag,
        unsigned *thrdid );
#else
int FAR _beginthread(
        void (FAR *start_address)(void FAR *),
        void FAR *stack_bottom,
        unsigned stack_size,
        void FAR *arglist );
#endif
Description:
The _beginthread function is used to start a new thread of execution at the function identified by start_address with a single parameter identified by arglist.
For each operating environment under which _beginthread is supported, the _beginthread function uses the appropriate system call to begin a new thread of execution.

The new thread will use the memory identified by stack_bottom and stack_size for its stack.

Note for 16-bit applications:  If the stack is not in DGROUP (i.e., the stack pointer does not point to an area in DGROUP) then you must compile your application with the "zu" option.  For example, the pointer returned by malloc in a large data model may not be in DGROUP.  The "zu" option relaxes the restriction that the SS register contains the base address of the default data segment, "DGROUP".  Normally, all data items are placed into the group DGROUP and the SS register contains the base address of this group.  In a thread, the SS register will likely not contain the base address of this group.  When the "zu" option is selected, the SS register is volatile (assumed to point to another segment) and any global data references require loading a segment register such as DS with the base address of DGROUP.

Note for OS/2 32-bit applications:  Memory for a stack need not be provided by the application.  The stack_bottom may be NULL in which case the run-time system will provide a stack.  You must specify a non-zero stack_size for this stack.

Note for Win32 applications:  Memory for a stack is provided by the run-time system.  The size of the stack is determined by stack_size and must not be zero.

The _beginthreadex function can be used to create a new thread, in a running or suspended state specified by initflag, with security attributes specified by security.

The initial state of the new thread (running or suspended) is specified by the initflag argument.  If the CREATE_SUSPENDED flag (WINBASE.H) is specified, the thread is created in a suspended state, and will not run until the Win32 ResumeThread function is called with the thread handle as an argument.  If this value is zero, the thread runs immediately after creation.

The security descriptor for the new thread is specified by the security argument.  This is a pointer to a Win32 SECURITY_ATTRIBUTES structure (see Microsoft's Win32 Programmer's Reference for more information).   For default behaviour, the security structure pointer can be NULL.

The thread identifier is returned in the location identified by the thrdid argument.

The thread ends when it exits from its main function or calls exit, _Exit, _exit, _endthread or _endthreadex.

The variable/function _threadid which is defined in <stddef.h> may be used by the executing thread to obtain its thread ID.  In the 16-bit libraries, _threadid is a far pointer to an int.  In the 32-bit libraries, it is a function that returns an int.

There is no limit to the number of threads an application can create under Win32 platforms.

There is a limit to the number of threads an application can create under 16-bit OS/2 and 32-bit NetWare.  The default limit is 32.  This limit can be adjusted by statically initializing the unsigned global variable __MaxThreads.

Under 32-bit OS/2, there is no limit to the number of threads an application can create.  However, due to the way in which multiple threads are supported in the Open Watcom libraries, there is a small performance penalty once the number of threads exceeds the default limit of 32 (this number includes the initial thread).  If you are creating more than 32 threads and wish to avoid this performance penalty, you can redefine the threshold value of 32.  You can statically initialize the global variable __MaxThreads.

By adding the following line to your multi-threaded application, the new threshold value will be set to 48.

     
     unsigned __MaxThreads = { 48 };
Returns:
Under Win32, the _beginthread function returns the thread handle for the new thread if successful; otherwise it returns -1 to indicate that the thread could not be started.
Under all other systems that support the _beginthread function (OS/2, Netware and QNX), it returns the thread ID for the new thread if successful; otherwise it returns -1 to indicate that the thread could not be started.

The _beginthreadex function returns the thread handle for the new thread if successful; otherwise it returns 0 to indicate that the thread could not be started.

When the thread could not be started, the value of errno could be set to EAGAIN if there are too many threads, or to EINVAL if the argument is invalid or the stack size is incorrect, or to ENOMEM if there is not enough available memory.
See Also:
_endthread
Example:

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <malloc.h>
#include <process.h>
#include <dos.h>

#if defined(__386__)
  #define FAR
  #define STACK_SIZE    8192
#else
  #define FAR           __far
  #define STACK_SIZE    4096
#endif

static volatile int     WaitForThread;

void FAR child( void FAR *parm )
  {
    char * FAR *argv = (char * FAR *) parm;
    int  i;

    printf( "Child thread ID = %x\n", *_threadid );
    for( i = 0; argv[i]; i++ ) {
      printf( "argv[%d] = %s\n", i, argv[i] );
    }
    WaitForThread = 0;
    _endthread();
  }

void main()
  {
    char           *args[3];
#if defined(__NT__)
    unsigned long   tid;
#else
    char           *stack;
    int             tid;
#endif

    args[0] = "child";
    args[1] = "parm";
    args[2] = NULL;
    WaitForThread = 1;
#if defined(__NT__)
    tid = _beginthread( child, STACK_SIZE, args );
    printf( "Thread handle = %lx\n", tid );
#else
  #if defined(__386__)
    stack = (char *) malloc( STACK_SIZE );
  #else
    stack = (char *) _nmalloc( STACK_SIZE );
  #endif
    tid = _beginthread( child, stack, STACK_SIZE, args );
    printf( "Thread ID = %x\n", tid );
#endif
    while( WaitForThread ) {
        sleep( 0 );
    }
  }
Classification:
WATCOM
Systems:
_beginthread - Win32, OS/2 1.x(MT), OS/2 1.x(DL), OS/2-32, Linux, RDOS, Netware
_beginthreadex - Win32

Bessel Functions

Synopsis:

#include <math.h>
double j0( double x );
double j1( double x );
double jn( int n, double x );
double y0( double x );
double y1( double x );
double yn( int n, double x );
Description:
Functions j0, j1, and jn return Bessel Functions of the first kind.
Functions y0, y1, and yn return Bessel Functions of the second kind.  The argument x must be positive.  If x is negative, will be called to print a DOMAIN error message to stderr, set errno to EDOM, and return the value -HUGE_VAL.  This error handling can be modified by using the matherr routine.
Returns:
These functions return the result of the desired Bessel Function of x.
See Also:
matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
     double x, y, z;

     x = j0( 2.4 );
     y = y1( 1.58 );
     z = jn( 3, 2.4 );
     printf( "j0(2.4) = %f, y1(1.58) = %f\n", x, y );
     printf( "jn(3,2.4) = %f\n", z );
  }
Classification:
WATCOM
Systems:
j0 - Math
j1 - Math
jn - Math
y0 - Math
y1 - Math
yn - Math

bcmp

Synopsis:

** deprecated **
#include <strings.h>
int bcmp(const void *s1, const void *s2, size_t n);
Description:
The bcmp function compares the byte string pointed to by s1 to the string pointed to by s2.  The number of bytes to compare is specified by n.  Null characters may be included in the comparision.
Note that this function is similar to the ISO C memcmp function but just tests for equality (new code should use the ISO C function).
Returns:
The bcmp function returns zero if the byte strings are identical; otherwise it returns 1.
See Also:
bcopy, bzero, memcmp, strcmp
Example:

#include <stdio.h>
#include <strings.h>

void main()
  {
    if( bcmp( "Hello there", "Hello world", 6 ) ) {
      printf( "Not equal\n" );
    } else {
      printf( "Equal\n" );
    }
  }

produces the following:

Equal
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

bcopy

Synopsis:

** deprecated **
#include <strings.h>
void bcopy( const void *src, void *dst, size_t n );
Description:
The bcopy function copies the byte string pointed to by src (including any null characters) into the array pointed to by dst.  The number of bytes to copy is specified by n.  Copying of overlapping objects is guaranteed to work properly.
Note that this function is similar to the ISO C memmove function but the order of arguments is different (new code should use the ISO C function).
Returns:
The bcopy function has no return value.
See Also:
bcmp, bzero, memmove, strcpy
Example:

#include <stdio.h>
#include <strings.h>

void main()
  {
    auto char buffer[80];

    bcopy( "Hello ", buffer,     6 );
    bcopy( "world",  &buffer[6], 6 );
    printf( "%s\n", buffer );
  }

produces the following:

Hello world
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_bfreeseg

Synopsis:

#include <malloc.h>
int _bfreeseg( __segment seg );
Description:
The _bfreeseg function frees a based-heap segment.
The argument seg indicates the segment returned by an earlier call to _bheapseg.
Returns:
The _bfreeseg function returns 0 if successful and -1 if an error occurred.
See Also:
_bheapseg, calloc, _expand, free, malloc, realloc
Example:

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>

struct list {
    struct list __based(__self) *next;
    int                          value;
};

void main()
  {
    int         i;
    __segment   seg;
    struct list __based(seg) *head;
    struct list __based(seg) *p;

    /* allocate based heap */
    seg = _bheapseg( 1024 );
    if( seg == _NULLSEG ) {
      printf( "Unable to allocate based heap\n" );
      exit( 1 );
    }

    /* create a linked list in the based heap */
    head = 0;
    for( i = 1; i < 10; i++ ) {
      p = _bmalloc( seg, sizeof( struct list ) );
      if( p == _NULLOFF ) {
        printf( "_bmalloc failed\n" );
        break;
      }
      p->next = head;
      p->value = i;
      head = p;
    }

    /* traverse the linked list, printing out values */
    for( p = head; p != 0; p = p->next ) {
      printf( "Value = %d\n", p->value );
    }

    /* free all the elements of the linked list */
    for( ; p = head; ) {
      head = p->next;
      _bfree( seg, p );
    }
    /* free the based heap */
    _bfreeseg( seg );
  }
Classification:
WATCOM
Systems:
DOS/16, Windows, OS/2 1.x(all)

_bgetcmd

Synopsis:

#include <process.h>
int _bgetcmd( char *cmd_line, int len );
Description:
The _bgetcmd function causes the command line information, with the program name removed, to be copied to cmd_line.   The argument len specifies the size of cmd_line.  The information is terminated with a null character.   This provides a method of obtaining the original parameters to a program unchanged (with the white space intact).
This information can also be obtained by examining the vector of program parameters passed to the main function in the program.
Returns:
The number of bytes required to store the entire command line, excluding the terminating null character, is returned.
See Also:
abort, atexit, exec..., exit, _Exit, _exit, getcmd, getenv, main, putenv, spawn..., system, _wsystem
Example:

Suppose a program were invoked with the command line
     
     myprog arg-1 ( my   stuff ) here

where that program contains

#include <stdio.h>
#include <stdlib.h>
#include <process.h>

void main( void )
{
    char  *cmdline;
    int   cmdlen;

    cmdlen = _bgetcmd( NULL, 0 ) + 1;
    cmdline = malloc( cmdlen );
    if( cmdline != NULL ) {
        cmdlen = _bgetcmd( cmdline, cmdlen );
        printf( "%s\n", cmdline );
    }
}

produces the following:

  arg-1 ( my   stuff ) here
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_bheapseg

Synopsis:

#include <malloc.h>
__segment _bheapseg( size_t size );
Description:
The _bheapseg function allocates a based-heap segment of at least size bytes.
The argument size indicates the initial size for the heap.  The heap will automatically be enlarged as needed if there is not enough space available within the heap to satisfy an allocation request by _bcalloc, _bexpand, _bmalloc, or _brealloc.

The value returned by _bheapseg is the segment value or selector for the based heap.  This value must be saved and used as an argument to other based heap functions to indicate which based heap to operate upon.

Each call to _bheapseg allocates a new based heap.
Returns:
The value returned by _bheapseg is the segment value or selector for the based heap.  This value must be saved and used as an argument to other based heap functions to indicate which based heap to operate upon.  A special value of _NULLSEG is returned if the segment could not be allocated.
See Also:
_bfreeseg, calloc, _expand, malloc, realloc
Example:

#include <stdio.h>
#include <stdlib.h>
#include <malloc.h>

struct list {
    struct list __based(__self) *next;
    int                          value;
};

void main()
  {
    int         i;
    __segment   seg;
    struct list __based(seg) *head;
    struct list __based(seg) *p;

    /* allocate based heap */
    seg = _bheapseg( 1024 );
    if( seg == _NULLSEG ) {
      printf( "Unable to allocate based heap\n" );
      exit( 1 );
    }

    /* create a linked list in the based heap */
    head = 0;
    for( i = 1; i < 10; i++ ) {
      p = _bmalloc( seg, sizeof( struct list ) );
      if( p == _NULLOFF ) {
        printf( "_bmalloc failed\n" );
        break;
      }
      p->next = head;
      p->value = i;
      head = p;
    }

    /* traverse the linked list, printing out values */
    for( p = head; p != 0; p = p->next ) {
      printf( "Value = %d\n", p->value );
    }

    /* free all the elements of the linked list */
    for( ; p = head; ) {
      head = p->next;
      _bfree( seg, p );
    }
    /* free the based heap */
    _bfreeseg( seg );
  }
Classification:
WATCOM
Systems:
DOS/16, Windows, OS/2 1.x(all)

_bios_disk

Synopsis:

#include <bios.h>
unsigned short _bios_disk( unsigned service,
                            struct diskinfo_t *diskinfo );
struct  diskinfo_t {     /* disk parameters   */
    unsigned   drive;    /* drive number      */
    unsigned   head;     /* head number        */
    unsigned   track;    /* track number      */
    unsigned   sector;   /* sector number     */
    unsigned   nsectors; /* number of sectors */
    void __far *buffer;  /* buffer address    */
};
Description:
The _bios_disk function uses INT 0x13 to provide access to the BIOS disk functions.  Information for the desired service is passed the diskinfo_t structure pointed to by diskinfo.  The value for service can be one of the following values:
Value     Meaning
_DISK_RESET
Forces the disk controller to do a reset on the disk.  This request does not use the diskinfo argument.

_DISK_STATUS
Obtains the status of the last disk operation.

_DISK_READ
Reads the specified number of sectors from the disk.  This request uses all of the information passed in the diskinfo structure.

_DISK_WRITE
Writes the specified amount of data to the disk.  This request uses all of the information passed in the diskinfo structure.

_DISK_VERIFY
Checks the disk to be sure the specified sectors exist and can be read.  A CRC (cyclic redundancy check) test is performed.   This request uses all of the information passed in the diskinfo structure except for the buffer field.

_DISK_FORMAT
Formats the specified track on the disk.  The head and track fields indicate the track to be formatted.   Only one track can be formatted per call.  The buffer field points to a set of sector markers, whose format depends on the type of disk drive.  This service has no return value.

This function is not supported by DOS/4GW (you must use the Simulate Real-Mode Interrupt DPMI call).
Returns:
The _bios_disk function returns status information in the high-order byte when service is _DISK_STATUS, _DISK_READ, _DISK_WRITE, or _DISK_VERIFY.  The possible values are:
Value
Meaning

0x00
Operation successful

0x01
Bad command

0x02
Address mark not found

0x03
Attempt to write to write-protected disk

0x04
Sector not found

0x05
Reset failed

0x06
Disk changed since last operation

0x07
Drive parameter activity failed

0x08
DMA overrun

0x09
Attempt to DMA across 64K boundary

0x0A
Bad sector detected

0x0B
Bad track detected

0x0C
Unsupported track

0x10
Data read (CRC/ECC) error

0x11
CRC/ECC corrected data error

0x20
Controller failure

0x40
Seek operation failed

0x80
Disk timed out or failed to respond

0xAA
Drive not ready

0xBB
Undefined error occurred

0xCC
Write fault occurred

0xE0
Status error

0xFF
Sense operation failed
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    struct diskinfo_t di;
    unsigned short status;

    di.drive = di.head = di.track = di.sector = 0;
    di.nsectors = 1;
    di.buffer = NULL;
    status = _bios_disk( _DISK_VERIFY, &di );
    printf( "Status = 0x%4.4X\n", status );
  }
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_equiplist

Synopsis:

#include <bios.h>
unsigned short _bios_equiplist( void );
Description:
The _bios_equiplist function uses INT 0x11 to determine what hardware and peripherals are installed on the machine.
Returns:
The _bios_equiplist function returns a set of bits indicating what is currently installed on the machine.  Those bits are defined as follows:
Bit
Meaning

bit 0
Set to 1 if system boots from disk

bit 1
Set to 1 if a math coprocessor is installed

bits 2-3
Indicates motherboard RAM size

bits 4-5
Initial video mode

bits 6-7
Number of diskette drives

bit 8
Set to 1 if machine does not have DMA

bits 9-11
Number of serial ports

bit 12
Set to 1 if a game port is attached

bit 13
Set to 1 if a serial printer is attached

bits 14-15
Number of parallel printers installed
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    unsigned short equipment;

    equipment = _bios_equiplist();
    printf( "Equipment flags = 0x%4.4X\n", equipment );
  }
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_keybrd

Synopsis:

#include <bios.h>
unsigned short _bios_keybrd( unsigned service );
Description:
The _bios_keybrd function uses INT 0x16 to access the BIOS keyboard services.  The possible values for service are the following constants:
Constant     Meaning
_KEYBRD_READ
Reads the next character from the keyboard.  The function will wait until a character has been typed.

_KEYBRD_READY
Checks to see if a character has been typed.  If there is one, then its value will be returned, but it is not removed from the input buffer.

_KEYBRD_SHIFTSTATUS
Returns the current state of special keys.

_NKEYBRD_READ
Reads the next character from an enhanced keyboard.  The function will wait until a character has been typed.

_NKEYBRD_READY
Checks to see if a character has been typed on an enhanced keyboard.  If there is one, then its value will be returned, but it is not removed from the input buffer.

_NKEYBRD_SHIFTSTATUS
Returns the current state of special keys on an enhanced keyboard.
Returns:
The return value depends on the service requested.
The _KEYBRD_READ and _NKEYBRD_READ services return the character's ASCII value in the low-order byte and the character's keyboard scan code in the high-order byte.

The _KEYBRD_READY and _NKEYBRD_READY services return zero if there was no character available, otherwise it returns the same value returned by _KEYBRD_READ and _NKEYBRD_READ.

The shift status is returned in the low-order byte with one bit for each special key defined as follows:
Bit
Meaning

bit 0 (0x01)
Right SHIFT key is pressed

bit 1 (0x02)
Left SHIFT key is pressed

bit 2 (0x04)
CTRL key is pressed

bit 3 (0x08)
ALT key is pressed

bit 4 (0x10)
SCROLL LOCK is on

bit 5 (0x20)
NUM LOCK is on

bit 6 (0x40)
CAPS LOCK is on

bit 7 (0x80)
Insert mode is set
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    unsigned short key_state;

    key_state = _bios_keybrd( _KEYBRD_SHIFTSTATUS );
    if( key_state & 0x10 )
        printf( "SCROLL LOCK is on\n" );
    if( key_state & 0x20 )
        printf( "NUM LOCK is on\n" );
    if( key_state & 0x40 )
        printf( "CAPS LOCK is on\n" );
  }

produces the following:

NUM LOCK is on
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_memsize

Synopsis:

#include <bios.h>
unsigned short _bios_memsize( void );
Description:
The _bios_memsize function uses INT 0x12 to determine the total amount of memory available.
Returns:
The _bios_memsize function returns the total amount of 1K blocks of memory installed (maximum 640).
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    unsigned short memsize;

    memsize = _bios_memsize();
    printf( "The total amount of memory is: %dK\n",
               memsize );
  }

produces the following:

The total amount of memory is: 640K
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_printer

Synopsis:

#include <bios.h>
unsigned short _bios_printer( unsigned service,
                               unsigned port,
                               unsigned data );
Description:
The _bios_printer function uses INT 0x17 to perform printer output services to the printer specified by port.   The values for service are:
Value     Meaning
_PRINTER_WRITE
Sends the low-order byte of data to the printer specified by port.

_PRINTER_INIT
Initializes the printer specified by port.

_PRINTER_STATUS
Get the status of the printer specified by port.
Returns:
The _bios_printer function returns a printer status byte defined as follows:
Bit
Meaning

bit 0 (0x01)
Printer timed out

bits 1-2
Unused

bit 3 (0x08)
I/O error

bit 4 (0x10)
Printer selected

bit 5 (0x20)
Out of paper

bit 6 (0x40)
Printer acknowledge

bit 7 (0x80)
Printer not busy
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    unsigned short status;

    status = _bios_printer( _PRINTER_STATUS, 1, 0 );
    printf( "Printer status: 0x%2.2X\n", status );
  }
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_serialcom

Synopsis:

#include <bios.h>
unsigned short _bios_serialcom( unsigned service,
                                 unsigned serial_port,
                                 unsigned data );
Description:
The _bios_serialcom function uses INT 0x14 to provide serial communications services to the serial port specified by serial_port.  0 represents COM1, 1 represents COM2, etc.  The values for service are:
Value     Meaning
_COM_INIT
Initializes the serial port to the parameters specified in data.

_COM_SEND
Transmits the low-order byte of data to the serial port.

_COM_RECEIVE
Reads an input character from the serial port.

_COM_STATUS
Returns the current status of the serial port.

The value passed in data for the _COM_INIT service can be built using the appropriate combination of the following values:
Value
Meaning

_COM_110
110 baud

_COM_150
150 baud

_COM_300
300 baud

_COM_600
600 baud

_COM_1200
1200 baud

_COM_2400
2400 baud

_COM_4800
4800 baud

_COM_9600
9600 baud

_COM_NOPARITY
No parity

_COM_EVENPARITY
Even parity

_COM_ODDPARITY
Odd parity

_COM_CHR7
7 data bits

_COM_CHR8
8 data bits

_COM_STOP1
1 stop bit

_COM_STOP2
2 stop bits
Returns:
The _bios_serialcom function returns a 16-bit value with the high-order byte containing status information defined as follows:
Bit
Meaning

bit 15 (0x8000)
Timed out

bit 14 (0x4000)
Transmit shift register empty

bit 13 (0x2000)
Transmit holding register empty

bit 12 (0x1000)
Break detected

bit 11 (0x0800)
Framing error

bit 10 (0x0400)
Parity error

bit 9 (0x0200)
Overrun error

bit 8 (0x0100)
Data ready

The low-order byte of the return value depends on the value of the service argument.

When service is _COM_SEND, bit 15 will be set if the data could not be sent.  If bit 15 is clear, the return value equals the byte sent.

When service is _COM_RECEIVE, the byte read will be returned in the low-order byte if there was no error.  If there was an error, at least one of the high-order status bits will be set.

When service is _COM_INIT or _COM_STATUS the low-order bits are defined as follows:
Bit
Meaning

bit 0 (0x01)
Clear to send (CTS) changed

bit 1 (0x02)
Data set ready changed

bit 2 (0x04)
Trailing-edge ring detector

bit 3 (0x08)
Receive line signal detector changed

bit 4 (0x10)
Clear to send

bit 5 (0x20)
Data-set ready

bit 6 (0x40)
Ring indicator

bit 7 (0x80)
Receive-line signal detected
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    unsigned short status;

    status = _bios_serialcom( _COM_STATUS, 1, 0 );
    printf( "Serial status: 0x%2.2X\n", status );
  }
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bios_timeofday

Synopsis:

#include <bios.h>
int _bios_timeofday( int service, long *timeval );
Description:
The _bios_timeofday function uses INT 0x1A to get or set the current system clock value.  The values for service are:
Value     Meaning
_TIME_GETCLOCK
Places the current system clock value in the location pointed to by timeval.  The function returns zero if midnight has not passed since the last time the system clock was read or set; otherwise, it returns 1.

_TIME_SETCLOCK
Sets the system clock to the value in the location pointed to by timeval.
Returns:
A value of -1 is returned if neither _TIME_GETCLOCK nor _TIME_SETCLOCK were specified; otherwise 0 is returned.
Example:

#include <stdio.h>
#include <bios.h>

void main()
  {
    long time_of_day;

    _bios_timeofday( _TIME_GETCLOCK, &time_of_day );
    printf( "Ticks since midnight: %lu\n", time_of_day );
  }

produces the following:

Ticks since midnight: 762717
Classification:
BIOS
Systems:
DOS, Windows, Win386

_bprintf, _bwprintf

Synopsis:

#include <stdio.h>
int _bprintf( char *buf, size_t bufsize,
              const char *format, ... );
int _bwprintf( wchar_t *buf, size_t bufsize,
               const wchar_t *format, ... );
Description:
The _bprintf function is equivalent to the sprintf function, except that the argument bufsize specifies the size of the character array buf into which the generated output is placed.  A null character is placed at the end of the generated character string.  The format string is described under the description of the printf function.
The _bwprintf function is a wide character version of _bprintf.  It accepts a wide character string argument for format and produces wide character output.  The argument buf specifies an array of wide characters into which the generated output is to be written, rather than converted to multibyte characters and written to a stream.
Returns:
The _bprintf function returns the number of characters written into the array, not counting the terminating null character.  The _bwprintf function returns the number of wide characters written into the array, not counting the terminating null character.  An error can occur while converting a value for output.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
cprintf, fprintf, printf, sprintf, _vbprintf, vcprintf, vfprintf, vprintf, vsprintf, _bwprintf, fwprintf, swprintf, _vbwprintf, vfwprintf, vwprintf, vswprintf
Example:

#include <stdio.h>

void main( int argc, char *argv[] )
{
    char file_name[9];
    char file_ext[4];

    _bprintf( file_name, 9, "%s", argv[1] );
    _bprintf( file_ext,  4, "%s", argv[2] );
    printf( "%s.%s\n", file_name, file_ext );
}
Classification:
WATCOM
Systems:
_bprintf - All, Linux, RDOS, Netware
_bwprintf - All, Linux

break...  Functions

Synopsis:

#include <stdlib.h>
void break_off( void );
void break_on( void );
Description:
The break_off function can be used with DOS to restrict break checking (Ctrl+C, Ctrl+Break) to screen output and keyboard input.  The break_on function can be used with DOS to add break checking (Ctrl+C, Ctrl+Break) to other activities such as disk file input/output.
Returns:
The break_off and break_on functions to not return anything.
See Also:
signal
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
    long i;
    FILE *tmpf;

    tmpf = tmpfile();
    if( tmpf != NULL ) {
      printf( "Start\n" );
      break_off();
      for( i = 1; i < 100000; i++ )
        fprintf( tmpf, "%ld\n", i );
      break_on();
      printf( "Finish\n" );
    }
  }
Classification:
DOS
Systems:
break_off - DOS, Windows, Win386
break_on - DOS, Windows, Win386

bsearch

Synopsis:

#include <stdlib.h>
void *bsearch( const void *key,
               const void *base,
               size_t num,
               size_t width,
               int (*compar)( const void *pkey,
                               const void *pbase) );
Safer C:
The Safer C Library extension provides the bsearch_s function which is a safer alternative to bsearch.  This newer bsearch_s function is recommended to be used instead of the traditional "unsafe" bsearch function.
Description:
The bsearch function performs a binary search of a sorted array of num elements, which is pointed to by base, for an item which matches the object pointed to by key.  Each element in the array is width bytes in size.  The comparison function pointed to by compar is called with two arguments that point to elements in the array.  The first argument pkey points to the same object pointed to by key.  The second argument pbase points to a element in the array.  The comparison function shall return an integer less than, equal to, or greater than zero if the key object is less than, equal to, or greater than the element in the array.
Returns:
The bsearch function returns a pointer to the matching member of the array, or NULL if a matching object could not be found.  If there are multiple values in the array which are equal to the key, the return value is not necessarily the first occurrence of a matching value when the array is searched linearly.
See Also:
bsearch_s, lfind, lsearch, qsort, qsort_s
Example:

#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static const char *keywords[] = {
        "auto",
        "break",
        "case",
        "char",
        /* . */
        /* . */
        /* . */
        "while"
  };

#define NUM_KW  sizeof(keywords) / sizeof(char *)

int kw_compare( const void *p1, const void *p2 )
{
    const char *p1c = (const char *) p1;
    const char **p2c = (const char **) p2;
    return( strcmp( p1c, *p2c ) );
}

int keyword_lookup( const char *name )
{
    const char **key;
    key = (char const **) bsearch( name, keywords, NUM_KW,
                   sizeof( char * ),  kw_compare );
    if( key == NULL ) return( -1 );
    return key - keywords;
}

void main()
{
    printf( "%d\n", keyword_lookup( "case" ) );
    printf( "%d\n", keyword_lookup( "crigger" ) );
    printf( "%d\n", keyword_lookup( "auto" ) );
}
//************ Sample program output ************
//2
//-1
//0

produces the following:

2
-1
0
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

bsearch_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void *bsearch_s( const void *key,
                 const void *base,
                 rsize_t nmemb,
                 rsize_t size,
    int (*compar)( const void *k, const void *y, void *context ),
                 void *context );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and bsearch_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither nmemb nor size shall be greater than RSIZE_MAX.  If nmemb is not equal to zero, then none of key, base, or compar shall be a null pointer.  If there is a runtime-constraint violation, the bsearch_s function does not search the array.
Description:
The bsearch_s function searches an array of nmemb objects, the initial element of which is pointed to by base, for an element that matches the object pointed to by key.  The size of each element of the array is specified by size.  The comparison function pointed to by compar is called with three arguments.  The first two point to the key object and to an array element, in that order.  The function shall return an integer less than, equal to, or greater than zero if the key object is considered, respectively, to be less than, to match, or to be greater than the array element.  The array shall consist of:  all the elements that compare less than, all the elements that compare equal to, and all the elements that compare greater than the key object, in that order.  The third argument to the comparison function is the context argument passed to bsearch_s The sole use of context by bsearch_s is to pass it to the comparison function.
Returns:
The bsearch_s function returns a pointer to a matching element of the array,or a null pointer if no match is found or there is a runtime-constraint violation.  If two elements compare as equal, which element is matched is unspecified.
See Also:
bsearch, lfind, lsearch, qsort, qsort_s
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static const char *keywords[] = {
        "auto",
        "break",
        "case",
        "char",
        /* . */
        /* . */
        /* . */
        "while"
};
static void * context = NULL;

#define NUM_KW  sizeof(keywords) / sizeof(char *)

int kw_compare( const void *p1, const void *p2, void *context )
{
    const char *p1c = (const char *) p1;
    const char **p2c = (const char **) p2;
    return( strcmp( p1c, *p2c ) );
}

int keyword_lookup( const char *name )
{
    const char **key;
    key = (char const **) bsearch_s( name, keywords, NUM_KW,
                   sizeof( char * ),  kw_compare, context );
    if( key == NULL ) return( -1 );
    return key - keywords;
}

int main()
{
    printf( "%d\n", keyword_lookup( "case" ) );
    printf( "%d\n", keyword_lookup( "crigger" ) );
    printf( "%d\n", keyword_lookup( "auto" ) );
    return 0;
}
//************ Sample program output ************
//2
//-1
//0

produces the following:

2
-1
0
Classification:
TR 24731
Systems:
All, Linux, RDOS, Netware

btowc

Synopsis:

#include <wchar.h>
wint_t btowc( int c );
Description:
The btowc function determines whether c is a valid single-byte character in the initial shift state.
Returns:
The btowc function returns WEOF if c has the value EOF or if (unsigned char)c does not constitute a valid single-byte character in the initial shift state.  Otherwise, btowc returns the wide character representation of that character.
See Also:
_mbccmp, _mbccpy, _mbcicmp, _mbcjistojms, _mbcjmstojis, _mbclen, _mbctohira, _mbctokata, _mbctolower, _mbctombb, _mbctoupper, mblen, mbrlen, mbrtowc, mbsrtowcs, mbsrtowcs_s, mbstowcs, mbstowcs_s, mbtowc, mbsinit, wcrtomb, wcrtomb_s, wcsrtombs, wcsrtombs_s, wcstombs, wcstombs_s, wctob, wctomb, wctomb_s
Example:

#include <stdio.h>
#include <wchar.h>

void main( void )
{
    printf( "EOF is %sa valid single-byte character\n",
        btowc( EOF ) == WEOF ? "not " : "" );
}

produces the following:

EOF is not a valid single-byte character
Classification:
ISO C
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

bzero

Synopsis:

** deprecated **
#include <strings.h>
void bzero( void *dst, size_t n );
Description:
The bzero function fills the first n bytes of the object pointed to by dst with zero (null) bytes.
Note that this function is similar to the ISO C memset function (new code should use the ISO C function).
Returns:
The bzero function has no return value.
See Also:
memcmp, memcpy, memset, _strset
Example:

#include <strings.h>

void main()
  {
    char buffer[80];

    bzero( buffer, 80 );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

cabs

Synopsis:

#include <math.h>
double cabs( struct complex value );

struct _complex {
    double  x;  /* real part      */
    double  y;  /* imaginary part */
};
Description:
The cabs function computes the absolute value of the complex number value by a calculation which is equivalent to
sqrt( (value.x*value.x) + (value.y*value.y) )

In certain cases, overflow errors may occur which will cause the matherr routine to be invoked.
Returns:
The absolute value is returned.
Example:

#include <stdio.h>
#include <math.h>

struct _complex c = { -3.0, 4.0 };

void main()
  {
    printf( "%f\n", cabs( c ) );
  }

produces the following:

5.000000
Classification:
WATCOM
Systems:
Math

calloc Functions

Synopsis:

#include <stdlib.h>  For ISO C compatibility (calloc only)
#include <malloc.h>  Required for other function prototypes
void *calloc( size_t n, size_t size );
void __based(void) *_bcalloc( __segment seg,
                               size_t n,
                               size_t size );
void __far  *_fcalloc( size_t n, size_t size );
void __near *_ncalloc( size_t n, size_t size );
Description:
The calloc functions allocate space for an array of n objects, each of length size bytes.  Each element is initialized to 0.
Each function allocates memory from a particular heap, as listed below:
Function     Heap
calloc
Depends on data model of the program

_bcalloc
Based heap specified by seg value

_fcalloc
Far heap (outside the default data segment)

_ncalloc
Near heap (inside the default data segment)

In a small data memory model, the calloc function is equivalent to the _ncalloc function; in a large data memory model, the calloc function is equivalent to the _fcalloc function.

A block of memory allocated should be freed using the appropriate free function.
Returns:
The calloc functions return a pointer to the start of the allocated memory.  The return value is NULL ( _NULLOFF for _bcalloc) if there is insufficient memory available or if the value of the size argument is zero.
See Also:
_expand Functions, free Functions, halloc, hfree, malloc Functions, _msize Functions, realloc Functions, sbrk
Example:

#include <stdlib.h>

void main()
  {
    char *buffer;

    buffer = (char *)calloc( 80, sizeof(char) );
  }
Classification:
ISO C
_bcalloc is WATCOM
_fcalloc is WATCOM
_ncalloc is WATCOM
Systems:
calloc - All, Linux, RDOS, Netware
_bcalloc - DOS/16, Windows, OS/2 1.x(all)
_fcalloc - DOS/16, Windows, OS/2 1.x(all)
_ncalloc - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

cbrt

Synopsis:

#include <math.h>
double cbrt( double x );
Description:
The cbrt function computes the cubed root of the argument x.
Returns:
The cubed root of the value.
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", cbrt( 8.0 ) );
  }

produces the following:

2.000000
Classification:
ISO C99
Systems:
Math

ceil

Synopsis:

#include <math.h>
double ceil( double x );
Description:
The ceil function (ceiling function) computes the smallest integer not less than x.
Returns:
The ceil function returns the smallest integer not less than x, expressed as a double.
See Also:
floor
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f %f %f %f %f\n", ceil( -2.1 ), ceil( -2. ),
        ceil( 0.0 ), ceil( 2. ), ceil( 2.1 ) );
  }

produces the following:

-2.000000 -2.000000 0.000000 2.000000 3.000000
Classification:
ISO C
Systems:
Math

cgets

Synopsis:

#include <conio.h>
char *cgets( char *buf );
Description:
The cgets function gets a string of characters directly from the console and stores the string and its length in the array pointed to by buf.  The first element of the array buf[0] must contain the maximum length in characters of the string to be read.  The array must be big enough to hold the string, a terminating null character, and two additional bytes.
The cgets function reads characters until a carriage-return line-feed combination is read, or until the specified number of characters is read.  The string is stored in the array starting at buf[2].  The carriage-return line-feed combination, if read, is replaced by a null character.  The actual length of the string read is placed in buf[1].
Returns:
The cgets function returns a pointer to the start of the string which is at buf[2].
See Also:
fgets, getch, getche, gets
Example:

#include <conio.h>

void main()
  {
    char buffer[82];

    buffer[0] = 80;
    cgets( buffer );
    cprintf( "%s\r\n", &buffer[2] );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_chain_intr

Synopsis:

#include <dos.h>
void _chain_intr( void (__interrupt __far *func)() );
Description:
The _chain_intr function is used at the end of an interrupt routine to start executing another interrupt handler (usually the previous handler for that interrupt).  When the interrupt handler designated by func receives control, the stack and registers appear as though the interrupt just occurred.
Returns:
The _chain_intr function does not return to its caller.
See Also:
_dos_getvect, _dos_keep, _dos_setvect
Example:

#include <stdio.h>
#include <dos.h>

volatile int clock_ticks;
void (__interrupt __far *prev_int_1c)();
#define BLIP_COUNT  (5*18)  /* 5 seconds */

void __interrupt __far timer_rtn()
  {
    ++clock_ticks;
    _chain_intr( prev_int_1c );
  }

int delays = 0;

int compile_a_line()
  {
    if( delays > 15 ) return( 0 );
    delay( 1000 );  /* delay for 1 second */
    printf( "Delayed for 1 second\n" );
    delays++;
    return( 1 );
  }

void main()
  {
    prev_int_1c = _dos_getvect( 0x1c );
    _dos_setvect( 0x1c, timer_rtn );
    while( compile_a_line() ) {
        if( clock_ticks >= BLIP_COUNT ) {
            putchar( '.' );
            clock_ticks -= BLIP_COUNT;
        }
    }
    _dos_setvect( 0x1c, prev_int_1c );
  }
Classification:
WATCOM
Systems:
DOS, Windows

chdir, _chdir, _wchdir

Synopsis:

#include <sys/types.h>
#include <direct.h>
int chdir( const char *path );
int _chdir( const char *path );
int _wchdir( const wchar_t *path );
Description:
The chdir function changes the current directory on the specified drive to the specified path.  If no drive is specified in path then the current drive is assumed.  The path can be either relative to the current directory on the specified drive or it can be an absolute path name.
Each drive under DOS, OS/2 or Windows has a current directory.  The current working directory is the current directory of the current drive.  If you wish to change the current drive, you must use the _dos_setdrive function.

The _chdir function is identical to chdir.  Use _chdir for ANSI naming conventions.

The _wchdir function is a wide character version of chdir that operates with wide character strings.
Returns:
The chdir function returns zero if successful.  Otherwise, -1 is returned, errno is set to indicate the error, and the current working directory remains unchanged.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
ENOENT
The specified path does not exist or path is an empty string.
See Also:
chmod, _dos_setdrive, getcwd, mkdir, rmdir, stat, umask
Example:

#include <stdio.h>
#include <stdlib.h>
#include <direct.h>

void main( int argc, char *argv[] )
{
    if( argc != 2 ) {
        fprintf( stderr, "Use: cd <directory>\n" );
        exit( 1 );
    }

    if( chdir( argv[1] ) == 0 ) {
        printf( "Directory changed to %s\n", argv[1] );
        exit( 0 );
    } else {
        perror( argv[1] );
        exit( 1 );
    }
}
Classification:
POSIX 1003.1
_chdir conforms to ANSI naming conventions
_wchdir is WATCOM
Systems:
chdir - All, Linux, RDOS, Netware
_chdir - All, RDOS, Netware
_wchdir - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_chdrive

Synopsis:

#include <direct.h>
int _chdrive( int drive );
Description:
The _chdrive function changes the current working drive to the one specified by drive.  A value of 1 is drive A, 2 is drive B, 3 is drive C, etc.
Returns:
The _chdrive function returns zero if drive is successfully changed.  Otherwise, -1 is returned.
See Also:
_dos_getdrive, _dos_setdrive, _getdrive
Example:

#include <stdio.h>
#include <direct.h>

void main( void )
{
    int drive = 3;

    if( _chdrive( drive  ) == 0 )
        printf( "Changed the current drive to %c\n",
                'A' + drive - 1 );
}

produces the following:

Changed the current drive to C
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS, DOS/PM

chmod, _chmod, _wchmod

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>
int chmod( const char *path, mode_t permission );
int _chmod( const char *path, mode_t permission );
int _wchmod( const wchar_t *path, mode_t permission );
Description:
The chmod function changes the permissions for a file specified by path to be the settings in the mode given by permission.  The access permissions for the file or directory are specified as a combination of bits (defined in the <sys/stat.h> header file).
The following bits define permissions for the owner.
Permission     Meaning
S_IRWXU
Read, write, execute/search

S_IRUSR
Read permission

S_IWUSR
Write permission

S_IXUSR
Execute/search permission

The following bits define permissions for the group.
Permission     Meaning
S_IRWXG
Read, write, execute/search

S_IRGRP
Read permission

S_IWGRP
Write permission

S_IXGRP
Execute/search permission

The following bits define permissions for others.
Permission     Meaning
S_IRWXO
Read, write, execute/search

S_IROTH
Read permission

S_IWOTH
Write permission

S_IXOTH
Execute/search permission

The following bits define miscellaneous permissions used by other implementations.
Permission     Meaning
S_IREAD
is equivalent to S_IRUSR (read permission)

S_IWRITE
is equivalent to S_IWUSR (write permission)

S_IEXEC
is equivalent to S_IXUSR (execute/search permission)

Upon successful completion, the chmod function will mark for update the st_ctime field of the file.

The _chmod function is identical to chmod.  Use _chmod for ANSI naming conventions.

The _wchmod function is a wide character version of chmod that operates with wide character strings.
Returns:
The chmod returns zero if the new settings are successfully made; otherwise, -1 is returned and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EACCES
Search permission is denied for a component of path.

ENOENT
The specified path does not exist or path is an empty string.
See Also:
fstat, open, _sopen, stat
Example:

/*
* change the permissions of a list of files
* to be read/write by the owner only
*/

#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>

void main( int argc, char *argv[] )
  {
    int i;
    int ecode = 0;

    for( i = 1; i < argc; i++ ) {
      if( chmod( argv[i], S_IRUSR | S_IWUSR ) == -1 ) {
        perror( argv[i] );
        ecode++;
      }
    }
    exit( ecode );
  }
Classification:
POSIX 1003.1
_chmod conforms to ANSI naming conventions
_wchmod is WATCOM
Systems:
chmod - All, Linux, RDOS, Netware
_chmod - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_wchmod - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_chsize, chsize

Synopsis:

#include <io.h>
int _chsize( int handle, long size );

** deprecated **
int chsize( int handle, long size );
Description:
The _chsize function changes the size of the file associated with handle by extending or truncating the file to the length specified by size.  If the file needs to be extended, the file is padded with NULL ('\0') characters.
The chsize function is deprecated, use _chsize instead.
Returns:
The _chsize function returns zero if successful.  A return value of -1 indicates an error, and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EACCES
The specified file is locked against access.

EBADF
Invalid file handle.

ENOSPC
Not enough space left on the device to extend the file.
See Also:
close, creat, open
Example:

#include <stdio.h>
#include <io.h>
#include <fcntl.h>
#include <sys/stat.h>

void main()
  {
    int  handle;

    handle = open( "file", O_RDWR | O_CREAT,
                S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( handle != -1 ) {
      if( _chsize( handle, 32 * 1024L ) != 0 ) {
          printf( "Error extending file\n" );
      }
      close( handle );
    }
  }
Classification:
WATCOM
Systems:
_chsize - All, Linux, RDOS, Netware
chsize - All, Linux, RDOS, Netware

_clear87

Synopsis:

#include <float.h>
unsigned int _clear87( void );
Description:
The _clear87 function clears the floating-point status word which is used to record the status of 8087/80287/80387/80486 floating-point operations.
Returns:
The _clear87 function returns the old floating-point status.  The description of this status is found in the <float.h> header file.
See Also:
_control87, _controlfp, _finite, _fpreset, _status87
Example:

#include <stdio.h>
#include <float.h>

void main()
  {
    unsigned int fp_status;

    fp_status = _clear87();

    printf( "80x87 status =" );
    if( fp_status & SW_INVALID )
        printf( " invalid" );
    if( fp_status & SW_DENORMAL )
        printf( " denormal" );
    if( fp_status & SW_ZERODIVIDE )
        printf( " zero_divide" );
    if( fp_status & SW_OVERFLOW )
        printf( " overflow" );
    if( fp_status & SW_UNDERFLOW )
        printf( " underflow" );
    if( fp_status & SW_INEXACT )
        printf( " inexact_result" );
    printf( "\n" );
  }
Classification:
Intel
Systems:
Math

clearenv

Synopsis:

#include <env.h>
int clearenv( void );
Description:
The clearenv function clears the process environment area.  No environment variables are defined immediately after a call to the clearenv function.  Note that this clears the PATH, COMSPEC, and TZ environment variables which may then affect the operation of other library functions.
The clearenv function may manipulate the value of the pointer environ.
Returns:
The clearenv function returns zero upon successful completion.  Otherwise, it will return a non-zero value and set errno to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
ENOMEM
Not enough memory to allocate a control structure.
See Also:
exec..., _wexec..., getenv, getenv_s, putenv, _searchenv, setenv, unsetenv, _wgetenv, _wputenv, _wsearchenv, _wsetenv, _wunsetenv, spawn..., _wspawn..., system, _wsystem
Example:

The following example clears the entire environment area and sets up a new TZ environment variable.

#include <env.h>

void main()
  {
    clearenv();
    setenv( "TZ", "EST5EDT", 0 );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

clearerr

Synopsis:

#include <stdio.h>
void clearerr( FILE *fp );
Description:
The clearerr function clears the end-of-file and error indicators for the stream pointed to by fp.  These indicators are cleared only when the file is opened or by an explicit call to the clearerr or rewind functions.
Returns:
The clearerr function returns no value.
See Also:
feof, ferror, perror, strerror
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    c = 'J';
    fp = fopen( "file", "w" );
    if( fp != NULL ) {
      fputc( c, fp );
      if( ferror( fp ) ) {  /* if error        */
        clearerr( fp );   /* clear the error */
        fputc( c, fp );   /* and retry it    */
      }
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

_clearscreen

Synopsis:

#include <graph.h>
void _FAR _clearscreen( short area );
Description:
The _clearscreen function clears the indicated area and fills it with the background color.  The area argument must be one of the following values:
_GCLEARSCREEN
area is entire screen

_GVIEWPORT
area is current viewport or clip region

_GWINDOW
area is current text window
Returns:
The _clearscreen function does not return a value.
See Also:
_setbkcolor, _setviewport, _setcliprgn, _settextwindow
Example:

#include <conio.h>
#include <graph.h>

main()
{
    _setvideomode( _VRES16COLOR );
    _rectangle( _GFILLINTERIOR, 100, 100, 540, 380 );
    getch();
    _setviewport( 200, 200, 440, 280 );
    _clearscreen( _GVIEWPORT );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

clock

Synopsis:

#include <time.h>
clock_t clock(void);
Description:
The clock function returns the number of clock ticks of processor time used by program since the program started executing.  This can be converted to seconds by dividing by the value of the macro CLOCKS_PER_SEC.
Note that under DOS and OS/2, the clock tick counter will reset to 0 for each subsequent 24 hour interval that elapses.
Returns:
The clock function returns the number of clock ticks that have occurred since the program started executing.
See Also:
asctime Functions, asctime_s, ctime Functions, ctime_s, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#include <stdio.h>
#include <math.h>
#include <time.h>

void compute( void )
  {
    int i, j;
    double x;

    x = 0.0;
    for( i = 1; i <= 100; i++ )
      for( j = 1; j <= 100; j++ )
        x += sqrt( (double) i * j );
    printf( "%16.7f\n", x );
  }

void main()
  {
    clock_t start_time, end_time;

    start_time = clock();
    compute();
    end_time = clock();
    printf( "Execution time was %lu seconds\n",
          (end_time - start_time) / CLOCKS_PER_SEC );
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

clock_getres

Synopsis:

#include <time.h>
int clock_getres(clockid_t clockid, struct timespec *ts);

struct timespec {
    time_t  tv_sec;
    long    tv_nsec;
};
Description:
The clock_getres function retrieves the minimum resolution of the clock specified by clockid in the ts pointer.
Returns:
If successful, the function will return zero.  If the call fails, the return value is the negation of the appropriate errno value as specified below.  This implementation will also set errno appropriately on failures.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EINVAL
The value of clockid is invalid.
See Also:
clock_settime, clock_gettime, clock_nanosleep
Classification:
POSIX 1003.1
Systems:
Linux

clock_gettime

Synopsis:

#include <time.h>
int clock_gettime(clockid_t clockid, struct timespec *ts);

struct timespec {
    time_t  tv_sec;
    long    tv_nsec;
};
Description:
The clock_gettime function retrieves the time for the clock specified by clockid in the ts pointer.
Returns:
If successful, the function will return zero.  If the call fails, the return value is the negation of the appropriate errno value as specified below.  This implementation will also set errno appropriately on failures.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EINVAL
The value of clockid is invalid.
See Also:
clock_settime, clock_getres, clock_nanosleep
Classification:
POSIX 1003.1
Systems:
Linux

clock_nanosleep

Synopsis:

#include <time.h>
int clock_nanosleep(clockid_t clockid, int flags,
                    const struct timespec *request,
                    struct timespec *remains);

struct timespec {
    time_t  tv_sec;
    long    tv_nsec;
};
Description:
The clock_nanosleep function causes the current thread to be suspended until the time period specified by request has elapsed according to the clock specified by clockid if the flags do not contain the value TIMER_ABSTIME.
If flags does contain TIMER_ABSTIME, the clock_nanosleep function causes the current thread to be suspended until the absolute time specified by request has been reached according to the clock specified by clockid if the flags.

If remains is not NULL, the structure will contain the amount of time remaining to be slept if clock_nanosleep is interrupted by a signal.
Returns:
If successful and uninterrupted, the function will return zero.  If the call fails or is interrupted, the return value is the negation of the appropriate errno value as specified below.  This implementation will also set errno appropriately on failures.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EINTR
The sleep was interrupted by a signal.

EINVAL
The value of clockid, request, or flags is invalid.

ENOTSUP
The specified clock does not support this function.
See Also:
clock_gettime, clock_getres, clock_settime
Classification:
POSIX 1003.1
Systems:
Linux

clock_settime

Synopsis:

#include <time.h>
int clock_settime(clockid_t clockid, const struct timespec *ts);

struct timespec {
    time_t  tv_sec;
    long    tv_nsec;
};
Description:
The clock_settime function sets the time for the clock specified by clockid to the time contained in the ts pointer.  Depending on the value of clockid, the function may fail if the user has insufficient privileges.
Values of ts that specify significance beyond the clock's resolution will be truncated.
Returns:
If successful, the function will return zero.  If the call fails, the return value is the negation of the appropriate errno value as specified below.  This implementation will also set errno appropriately on failures.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EINVAL
The value of clockid is invalid, or the value of ts exceeds the range of this clock.

EPERM
The user does not have sufficient privileges to modify the specified clock.
See Also:
clock_gettime, clock_getres, clock_nanosleep
Classification:
POSIX 1003.1
Systems:
Linux

clone

Synopsis:

#include <sched.h>

pid_t  clone( int (*fn)(void *), void *child_stack,
              int flags, void *args, ... );
            /* pid_t *ppid, void *tls, pid_t *ctid */
Description:
The clone function creates a "clone" of the currently running process that shares the address space of the original, parent process, and starts execution within the clone process at the fn function.  The child function is called with args as its argument, and, once complete, with will terminate with the return value of fn as its exit code.  This function provides a wrapper around the Linux kernel's SYS_clone system call.
The child_stack argument points to a user-allocated memory block within the process's heap for use as the cloned process's new stack space.  Because the stack will grow in the direction of descending address, the child_stack argument should refer to the highest address in the allocated memory.

The flags argument may be one of the following values:
Constant     Meaning
CLONE_VM
Virtual memory should be shared across processes

CLONE_FS
File system information should be shared across processes

CLONE_FILES
File handles should be shared across processes

CLONE_SIGHAND
Signal handlers and blocked signals should be shared across processes

CLONE_PTRACE
Allow tracing within the child process (if enabled in the parent)

CLONE_VFORK
The child can wake the parent via mm_release

CLONE_PARENT
The new child should share the same parent as the cloning process

CLONE_THREAD
The new process is to be considered a thread, and should be grouped in the same thread group as the parent

CLONE_NEWNS
The child process is provided a new mount namespace

CLONE_SYSVSEM
The child process shares all System V semaphores

CLONE_SETTLS
The thread-local storage, an optional argument, should be passed and set appropriately.  The user must specify the tls argument if this flag is set.

CLONE_PARENT_SETTID
Store the thread ID of the parent in the ptid argument.  The user must specify the optional ptid argument if this flag is set.

CLONE_CHILD_CLEARTID
Clear the thread ID stored in ctid argument.  The user must specify the optional ctid argument if this flag is set.

CLONE_UNTRACED
The parent process cannot force tracing on the child process

CLONE_CHILD_SETTID
Store the thread ID of the child process in the ctid argument.  The user must specify the optional ctid argument if this flag is set.

CLONE_NEWUTS
The child process has a new UTS namespace

CLONE_NEWIPC
The child process has a new IPC namespace

CLONE_NEWUSER
The child process has a new user namespace

CLONE_NEWPID
The child process has a new PID namespace

CLONE_NEWNET
The child process has a new network namespace

CLONE_IO
The parent and child share io contexts

This function provides a low-level threading interface that is normally meant for designing higher level thread libraries.
Returns:
If successful, the function will return the process ID of the child process.  If the system call fails, the return value will be -1, and errno will be set appropriately.
Classification:
WATCOM
Systems:
Linux

close, _close

Synopsis:

#include <io.h>
int close( int handle );
int _close( int handle );
Description:
The close function closes a file at the operating system level.  The handle value is the file handle returned by a successful execution of one of the creat, dup, dup2, open or _sopen functions.
The _close function is identical to close.  Use _close for ANSI naming conventions.
Returns:
The close function returns zero if successful.  Otherwise, it returns -1 and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The handle argument is not a valid file handle.
See Also:
creat, dup, dup2, open, _sopen
Example:

#include <fcntl.h>
#include <io.h>

void main()
  {
    int handle;

    handle = open( "file", O_RDONLY );
    if( handle != -1 ) {
      /* process file */
      close( handle );
    }
  }
Classification:
POSIX 1003.1
_close conforms to ANSI naming conventions
Systems:
close - All, Linux, RDOS, Netware
_close - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

closedir, _wclosedir

Synopsis:

#include <direct.h>
int closedir( DIR *dirp );
int _wclosedir( WDIR *dirp );
Description:
The closedir function closes the directory specified by dirp and frees the memory allocated by opendir.
The _wclosedir function is identical to closedir except that it closes a directory of wide character filenames opened by _wopendir.
Returns:
The closedir function returns zero if successful, non-zero otherwise.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The argument dirp does not refer to an open directory stream.
See Also:
_dos_find..., opendir, readdir, rewinddir, _wopendir, _wreaddir, _wrewinddir
Example:

To get a list of files contained in the directory \watcom\h on your default disk:

#include <stdio.h>
#include <direct.h>

typedef struct {
    unsigned short  twosecs : 5;    /* seconds / 2 */
    unsigned short  minutes : 6;
    unsigned short  hours   : 5;
} ftime_t;

typedef struct {
    unsigned short  day     : 5;
    unsigned short  month   : 4;
    unsigned short  year    : 7;
} fdate_t;

void main()
  {
    DIR *dirp;
    struct dirent *direntp;
    ftime_t *f_time;
    fdate_t *f_date;

    dirp = opendir( "\\watcom\\h" );
    if( dirp != NULL ) {
      for(;;) {
        direntp = readdir( dirp );
        if( direntp == NULL ) break;
        f_time = (ftime_t *)&direntp->d_time;
        f_date = (fdate_t *)&direntp->d_date;
        printf( "%-12s %d/%2.2d/%2.2d "
                "%2.2d:%2.2d:%2.2d \n",
            direntp->d_name,
            f_date->year + 1980,
            f_date->month,
            f_date->day,
            f_time->hours,
            f_time->minutes,
            f_time->twosecs * 2 );
      }
      closedir( dirp );
    }
  }

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single backslash.
Classification:
POSIX 1003.1
_wclosedir is WATCOM
Systems:
closedir - All, Linux, RDOS, Netware
_wclosedir - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_cmdname

Synopsis:

#include <process.h>
char *_cmdname( char *buffer );
Description:
The _cmdname function obtains a copy of the executing program's pathname and places it in buffer.
Returns:
If the pathname of the executing program cannot be determined then NULL is returned; otherwise the address of buffer is returned.
See Also:
getcmd
Example:

#include <stdio.h>
#include <process.h>

void main()
  {
    char buffer[PATH_MAX];

    printf( "%s\n", _cmdname( buffer ) );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_commit

Synopsis:

#include <io.h>
int _commit( int handle );
Description:
The _commit function commits changes to the file specified by handle to disk immediately.
Returns:
The _commit function returns -1 if the changes have been successfully committed.  Otherwise, 0 is returned and errno is set to indicate the error.
Classification:
WATCOM
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_control87

Synopsis:

#include <float.h>
unsigned int _control87( unsigned int newcw,
                          unsigned int mask );
Description:
The _control87 function updates the control word of the 8087/80287/80387/80486.  If mask is zero, then the control word is not updated.  If mask is non-zero, then the control word is updated with bits from newcw corresponding to every bit that is on in mask.
Returns:
The _control87 function returns the new control word.  The description of bits defined for the control word is found in the <float.h> header file.
See Also:
_clear87, _controlfp, _finite, _fpreset, _status87
Example:

#include <stdio.h>
#include <float.h>

char *status[2] = { "disabled", "enabled" };

void main()
  {
    unsigned int fp_cw = 0;
    unsigned int fp_mask = 0;
    unsigned int bits;

    fp_cw = _control87( fp_cw,
                         fp_mask );

    printf( "Interrupt Exception Masks\n" );
    bits = fp_cw & MCW_EM;
    printf( "  Invalid Operation exception %s\n",
            status[ (bits & EM_INVALID) == 0 ] );
    printf( "  Denormalized exception %s\n",
            status[ (bits & EM_DENORMAL) == 0 ] );
    printf( "  Divide-By-Zero exception %s\n",
            status[ (bits & EM_ZERODIVIDE) == 0 ] );
    printf( "  Overflow exception %s\n",
            status[ (bits & EM_OVERFLOW) == 0 ] );
    printf( "  Underflow exception %s\n",
            status[ (bits & EM_UNDERFLOW) == 0 ] );
    printf( "  Precision exception %s\n",
            status[ (bits & EM_PRECISION) == 0 ] );

    printf( "Infinity Control = " );
    bits = fp_cw & MCW_IC;
    if( bits == IC_AFFINE )     printf( "affine\n" );
    if( bits == IC_PROJECTIVE ) printf( "projective\n" );

    printf( "Rounding Control = " );
    bits = fp_cw & MCW_RC;
    if( bits == RC_NEAR )       printf( "near\n" );
    if( bits == RC_DOWN )       printf( "down\n" );
    if( bits == RC_UP )         printf( "up\n" );
    if( bits == RC_CHOP )       printf( "chop\n" );

    printf( "Precision Control = " );
    bits = fp_cw & MCW_PC;
    if( bits == PC_24 )         printf( "24 bits\n" );
    if( bits == PC_53 )         printf( "53 bits\n" );
    if( bits == PC_64 )         printf( "64 bits\n" );
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

_controlfp

Synopsis:

#include <float.h>
unsigned int _controlfp( unsigned int newcw,
                          unsigned int mask );
Description:
The _controlfp function updates the control word of the 8087/80287/80387/80486.  If mask is zero, then the control word is not updated.  If mask is non-zero, then the control word is updated with bits from newcw corresponding to every bit that is on in mask.
Returns:
The _controlfp function returns the new control word.  The description of bits defined for the control word is found in the <float.h> header file.
See Also:
_clear87, _control87, _finite, _fpreset, _status87
Example:

#include <stdio.h>
#include <float.h>

char *status[2] = { "disabled", "enabled" };

void main()
  {
    unsigned int fp_cw = 0;
    unsigned int fp_mask = 0;
    unsigned int bits;

    fp_cw = _controlfp( fp_cw,
                         fp_mask );

    printf( "Interrupt Exception Masks\n" );
    bits = fp_cw & MCW_EM;
    printf( "  Invalid Operation exception %s\n",
            status[ (bits & EM_INVALID) == 0 ] );
    printf( "  Denormalized exception %s\n",
            status[ (bits & EM_DENORMAL) == 0 ] );
    printf( "  Divide-By-Zero exception %s\n",
            status[ (bits & EM_ZERODIVIDE) == 0 ] );
    printf( "  Overflow exception %s\n",
            status[ (bits & EM_OVERFLOW) == 0 ] );
    printf( "  Underflow exception %s\n",
            status[ (bits & EM_UNDERFLOW) == 0 ] );
    printf( "  Precision exception %s\n",
            status[ (bits & EM_PRECISION) == 0 ] );

    printf( "Infinity Control = " );
    bits = fp_cw & MCW_IC;
    if( bits == IC_AFFINE )     printf( "affine\n" );
    if( bits == IC_PROJECTIVE ) printf( "projective\n" );

    printf( "Rounding Control = " );
    bits = fp_cw & MCW_RC;
    if( bits == RC_NEAR )       printf( "near\n" );
    if( bits == RC_DOWN )       printf( "down\n" );
    if( bits == RC_UP )         printf( "up\n" );
    if( bits == RC_CHOP )       printf( "chop\n" );

    printf( "Precision Control = " );
    bits = fp_cw & MCW_PC;
    if( bits == PC_24 )         printf( "24 bits\n" );
    if( bits == PC_53 )         printf( "53 bits\n" );
    if( bits == PC_64 )         printf( "64 bits\n" );
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

copysign

Synopsis:

#include <math.h>
double copysign( double x, double y );
Description:
The copysign function returns a value whose absolute value is equal to the absolute value of the argument x and whose sign matches argument y.
Returns:
A value of the same magnitude as x and the same sign as y.
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", copysign( -2.0, 3.0 ) );
  }

produces the following:

2.000000
Classification:
ISO C99
Systems:
Math

cos

Synopsis:

#include <math.h>
double cos( double x );
Description:
The cos function computes the cosine of x (measured in radians).  A large magnitude argument may yield a result with little or no significance.
Returns:
The cos function returns the cosine value.
See Also:
acos, sin, tan
Example:

#include <math.h>

void main()
  {
    double value;
    value = cos( 3.1415278 );
  }
Classification:
ISO C
Systems:
Math

cosh

Synopsis:

#include <math.h>
double cosh( double x );
Description:
The cosh function computes the hyperbolic cosine of x.  A range error occurs if the magnitude of x is too large.
Returns:
The cosh function returns the hyperbolic cosine value.  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to ERANGE, and print a "RANGE error" diagnostic message using the stderr stream.
See Also:
sinh, tanh, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", cosh(.5) );
  }

produces the following:

1.127626
Classification:
ISO C
Systems:
Math

cprintf

Synopsis:

#include <conio.h>
int cprintf( const char *format, ... );
Description:
The cprintf function writes output directly to the console under control of the argument format.  The putch function is used to output characters to the console.  The format string is described under the description of the printf function.
Returns:
The cprintf function returns the number of characters written.
See Also:
_bprintf, fprintf, printf, sprintf, _vbprintf, vcprintf, vfprintf, vprintf, vsprintf, _bwprintf, fwprintf, swprintf, _vbwprintf, vfwprintf, vwprintf, vswprintf
Example:

#include <conio.h>

void main()
  {
    char *weekday, *month;
    int day, year;

    weekday = "Saturday";
    month = "April";
    day = 18;
    year = 1987;
    cprintf( "%s, %s %d, %d\n",
          weekday, month, day, year );
  }

produces the following:

Saturday, April 18, 1987
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

cputs

Synopsis:

#include <conio.h>
int cputs( const char *buf );
Description:
The cputs function writes the character string pointed to by buf directly to the console using the putch function.  Unlike the puts function, the carriage-return and line-feed characters are not appended to the string.  The terminating null character is not written.
Returns:
The cputs function returns a non-zero value if an error occurs; otherwise, it returns zero.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fputs, putch, puts
Example:

#include <conio.h>

void main()
  {
    char buffer[82];

    buffer[0] = 80;
    cgets( buffer );
    cputs( &buffer[2] );
    putch( '\r' );
    putch( '\n' );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

creat, _creat, _wcreat

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>
int creat( const char *path, mode_t mode );
int _creat( const char *path, mode_t mode );
int _wcreat( const wchar_t *path, mode_t mode );
Description:
The creat function creates (and opens) a file at the operating system level.  It is equivalent to:
     
       open( path, O_WRONLY | O_CREAT | O_TRUNC, mode );

The _creat function is identical to creat.  Use _creat for ANSI naming conventions.

The _wcreat function is identical to creat except that it accepts a wide character string argument.

The name of the file to be created is given by path.  When the file exists (it must be writeable), it is truncated to contain no data and the preceding mode setting is unchanged.

When the file does not exist, it is created with access permissions given by the mode argument.  The access permissions for the file or directory are specified as a combination of bits (defined in the <sys/stat.h> header file).

The following bits define permissions for the owner.
Permission     Meaning
S_IRWXU
Read, write, execute/search

S_IRUSR
Read permission

S_IWUSR
Write permission

S_IXUSR
Execute/search permission

The following bits define permissions for the group.
Permission     Meaning
S_IRWXG
Read, write, execute/search

S_IRGRP
Read permission

S_IWGRP
Write permission

S_IXGRP
Execute/search permission

The following bits define permissions for others.
Permission     Meaning
S_IRWXO
Read, write, execute/search

S_IROTH
Read permission

S_IWOTH
Write permission

S_IXOTH
Execute/search permission

The following bits define miscellaneous permissions used by other implementations.
Permission     Meaning
S_IREAD
is equivalent to S_IRUSR (read permission)

S_IWRITE
is equivalent to S_IWUSR (write permission)

S_IEXEC
is equivalent to S_IXUSR (execute/search permission)

All files are readable with DOS; however, it is a good idea to set S_IREAD when read permission is intended for the file.
Returns:
If successful, creat returns a handle for the file.  When an error occurs while opening the file, -1 is returned, and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EACCES
Access denied because path specifies a directory or a volume ID, or a read-only file.

EMFILE
No more handles available (too many open files).

ENOENT
The specified path does not exist or path is an empty string.
See Also:
_chsize, close, dup, dup2, _eof, exec..., fdopen, _filelength, fileno, fstat, _grow_handles, isatty, lseek, open, read, _setmode, _sopen, stat, _tell, write, umask
Example:

#include <sys/types.h>
#include <sys/stat.h>
#include <io.h>

void main()
  {
    int handle;

    handle = creat( "file", S_IWRITE | S_IREAD );
    if( handle != -1 ) {

      /* process file */

      close( handle );
    }
  }
Classification:
POSIX 1003.1
_creat conforms to ANSI naming conventions
_wcreat is WATCOM
Systems:
creat - All, Linux, RDOS, Netware
_creat - All, Linux, RDOS, Netware
_wcreat - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

cscanf

Synopsis:

#include <conio.h>
int cscanf( const char *format, ... );
Description:
The cscanf function scans input from the console under control of the argument format.  Following the format string is a list of addresses to receive values.  The cscanf function uses the function getche to read characters from the console.  The format string is described under the description of the scanf function.
Returns:
The cscanf function returns EOF when the scanning is terminated by reaching the end of the input stream.   Otherwise, the number of input arguments for which values were successfully scanned and stored is returned.  When a file input error occurs, the errno global variable may be set.
See Also:
fscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf, fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf
Example:

To scan a date in the form "Saturday April 18 1987":

#include <conio.h>

void main()
  {
    int day, year;
    char weekday[10], month[10];

    cscanf( "%s %s %d %d",
            weekday, month, &day, &year );
    cprintf( "\n%s, %s %d, %d\n",
            weekday, month, day, year );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

ctime Functions

Synopsis:

#include <time.h>
char *ctime( const time_t *timer );
char *_ctime( const time_t *timer, char *buf );
wchar_t *_wctime( const time_t *timer );
wchar_t *__wctime( const time_t *timer, wchar_t *buf );
Safer C:
The Safer C Library extension provides the ctime_s function which is a safer alternative to ctime.   This newer ctime_s function is recommended to be used instead of the traditional "unsafe" ctime function.
Description:
The ctime functions convert the calendar time pointed to by timer to local time in the form of a string.  The ctime function is equivalent to
     
     asctime( localtime( timer ) )

The ctime functions convert the time into a string containing exactly 26 characters.  This string has the form shown in the following example:

     
     Sat Mar 21 15:58:27 1987\n\0

All fields have a constant width.  The new-line character '\n' and the null character '\0' occupy the last two positions of the string.

The ISO C function ctime places the result string in a static buffer that is re-used each time ctime or asctime is called.  The non-ISO C function _ctime places the result string in the buffer pointed to by buf.

The _wctime function is a wide character version of ctime except that it produces a wide character string.

The __wctime function is a wide character version of _ctime except that it produces a wide character string.

Whenever the ctime functions are called, the tzset function is also called.

The calendar time is usually obtained by using the time function.  That time is Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time (GMT)).

The time set on the computer with the DOS time command and the DOS date command reflects the local time.  The environment variable TZ is used to establish the time zone to which this local time applies.  See the section The TZ Environment Variable for a discussion of how to set the time zone.
Returns:
The ctime functions return the pointer to the string containing the local time.
See Also:
asctime Functions, asctime_s, clock, ctime_s, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset, ctime_s
Example:

#include <stdio.h>
#include <time.h>

void main()
{
    time_t time_of_day;
    auto char buf[26];

    time_of_day = time( NULL );
    printf( "It is now: %s", _ctime( &time_of_day, buf ) );
}

produces the following:

It is now: Fri Dec 25 15:58:42 1987
Classification:
ISO C
_ctime is WATCOM
_wctime is WATCOM
__wctime is WATCOM
Systems:
ctime - All, Linux, RDOS, Netware
_ctime - All, Linux, RDOS
_wctime - All, Linux
__wctime - All, Linux

ctime_s, _wctime_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
errno_t ctime_s( char * s,
                 rsize_t maxsize,
                 const time_t * timer);
#include <wchar.h>
errno_t _wctime_s( wchar_t * s,
                   rsize_t maxsize,
                   const time_t * timer);
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and ctime_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither s nor timer shall be a null pointer.  maxsize shall not be less than 26 and shall not be greater than RSIZE_MAX.  If there is a runtime-constraint violation, s[0] is set to a null character if s is not a null pointer and maxsize is not equal zero and is not greater than RSIZE_MAX.
Description:
The ctime_s function converts the calendar time pointed to by timer to local time in the form of a string.   It is equivalent to
     
     asctime_s( s, maxsize, localtime_s( timer ) )
Recommended practice:

The strftime function allows more flexible formatting and supports locale-specific behavior.  If you do not require the exact form of the result string produced by the ctime_s function, consider using the strftime function instead.
Returns:
The ctime_s function returns zero if there was no runtime-constraint violation.  Otherwise, a non-zero value is returned.
See Also:
asctime Functions, asctime_s, clock, ctime Functions, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <time.h>

void main()
{
    time_t time_of_day;
    auto char buf[26];

    time_of_day = time( NULL );
    ctime_s( buf, sizeof( buf ), &time_of_day );
    printf( "It is now: %s", buf );
}

produces the following:

It is now: Mon Jan 30 14:29:55 2006
Classification:
TR 24731
_wctime_s is WATCOM
Systems:
ctime_s - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS, Netware
_wctime_s - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux

cwait, _cwait

Synopsis:

#include <process.h>
int cwait( int *status, int process_id, int action );
int _cwait( int *status, int process_id, int action );
Description:
The cwait function suspends the calling process until the specified process terminates.
If status is not NULL, it points to a word that will be filled in with the termination status word and return code of the terminated child process.

If the child process terminated normally, then the low order byte of the status word will be set to 0, and the high order byte will contain the low order byte of the return code that the child process passed to the DOSEXIT function.   The DOSEXIT function is called whenever main returns, or exit, or _Exit or _exit are explicity called.

If the child process did not terminate normally, then the high order byte of the status word will be set to 0, and the low order byte will contain one of the following values:
Value
Meaning

1
Hard-error abort

2
Trap operation

3
SIGTERM signal not intercepted
Note:
This implementation of the status value follows the OS/2 model and differs from the Microsoft implementation.  Under Microsoft, the return code is returned in the low order byte and it is not possible to determine whether a return code of 1, 2, or 3 imply that the process terminated normally.  For portability to Microsoft compilers, you should ensure that the application that is waited on does not return one of these values.  The following shows how to handle the status value in a portable manner.
     
     cwait( &status, process_id, WAIT_CHILD );

     #if defined(__WATCOMC__)
     switch( status & 0xff ) {
     case 0:
         printf( "Normal termination exit code = %d\n", status >> 8 );
         break;
     case 1:
         printf( "Hard-error abort\n" );
         break;
     case 2:
         printf( "Trap operation\n" );
         break;
     case 3:
         printf( "SIGTERM signal not intercepted\n" );
         break;
     default:
         printf( "Bogus return status\n" );
     }

     #else if defined(_MSC_VER)
     switch( status & 0xff ) {
     case 1:
         printf( "Possible Hard-error abort\n" );
         break;
     case 2:
         printf( "Possible Trap operation\n" );
         break;
     case 3:
         printf( "Possible SIGTERM signal not intercepted\n" );
         break;
     default:
         printf( "Normal termination exit code = %d\n", status );
     }

     #endif

The process_id argument specifies which process to wait for.  Under Win32, any process can wait for any other process for which the process ID is known.  Under OS/2, a process can wait for any of its child processes.  For example, a process ID is returned by certain forms of the spawn... functions that is used to start a child process.

The action argument specifies when the parent process resumes execution.  This argument is ignored in Win32, but is accepted for compatibility with OS/2 (although Microsoft handles the status value differently from OS/2!).   The possible values are:
Value     Meaning
WAIT_CHILD
Wait until the specified child process has ended.

WAIT_GRANDCHILD
Wait until the specified child process and all of the child processes of that child process have ended.

Under Win32, there is no parent-child relationship.
Returns:
The cwait function returns the (child's) process ID if the (child) process terminated normally.  Otherwise, cwait returns -1 and sets errno to one of the following values:
Constant     Meaning
EINVAL
Invalid action code

ECHILD
Invalid process ID, or the child does not exist.

EINTR
The child process terminated abnormally.
See Also:
exit, _Exit, _exit, spawn..., wait
Example:

#include <stdio.h>
#include <process.h>

void main()
  {
     int   process_id;
     int   status;

     process_id = spawnl( P_NOWAIT, "child.exe",
                "child", "parm", NULL );
     cwait( &status, process_id, WAIT_CHILD );
  }
Classification:
WATCOM
Systems:
cwait - Win32, OS/2 1.x(all), OS/2-32
_cwait - Win32, OS/2 1.x(all), OS/2-32

delay

Synopsis:

#include <i86.h>
void delay( unsigned milliseconds );
Description:
The delay function suspends execution by the specified number of milliseconds.
Returns:
The delay function has no return value.
See Also:
sleep
Example:

#include <i86.h>

void main()
  {
    sound( 200 );
    delay( 500 );  /* delay for 1/2 second */
    nosound();
  }
Classification:
WATCOM
Systems:
All, RDOS, Netware

_dieeetomsbin

Synopsis:

#include <math.h>
extern int _dieeetomsbin( double *src, double *dest );
Description:
The _dieeetomsbin function loads the double pointed to by src in IEEE format and converts it to Microsoft binary format, storing the result into the double pointed to by dest.
For _dieeetomsbin IEEE Nan's and Infinities will cause overflow.  IEEE denormals will be converted if within range.  Otherwise, they will be converted to 0 in the Microsoft binary format.

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38.  The range of Microsoft binary format doubles is 2.938735877056e-39 to 1.701411834605e+38.

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors became standard.
Returns:
The _dieeetomsbin function returns 0 if the conversion was successful.  Otherwise, it returns 1 if conversion would cause an overflow.
See Also:
_dmsbintoieee, _fieeetomsbin, _fmsbintoieee
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    float fieee, fmsb;
    double dieee, dmsb;

    fieee = 0.5;
    dieee = -2.0;

    /* Convert IEEE format to Microsoft binary format */
    _fieeetomsbin( &fieee, &fmsb );
    _dieeetomsbin( &dieee, &dmsb );

    /* Convert Microsoft binary format back to IEEE format */
    _fmsbintoieee( &fmsb, &fieee );
    _dmsbintoieee( &dmsb, &dieee );

    /* Display results */
    printf( "fieee = %f, dieee = %f\n", fieee, dieee );
  }

produces the following:

fieee = 0.500000, dieee = -2.000000
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

difftime

Synopsis:

#include <time.h>
double difftime( time_t time1, time_t time0 );
Description:
The difftime function calculates the difference between the two calendar times:
     
         time1 - time0
Returns:
The difftime function returns the difference between the two times in seconds as a double.
See Also:
asctime Functions, asctime_s, clock, ctime Functions, ctime_s, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#include <stdio.h>
#include <time.h>

void compute( void );

void main()
  {
    time_t start_time, end_time;

    start_time = time( NULL );
    compute();
    end_time = time( NULL );
    printf( "Elapsed time: %f seconds\n",
        difftime( end_time, start_time ) );
  }

void compute( void )
  {
    int i, j;

    for( i = 1; i <= 20; i++ ) {
      for( j = 1; j <= 20; j++ )
        printf( "%3d ", i * j );
      printf( "\n" );
    }
  }
Classification:
ISO C
Systems:
Math

dirname

Synopsis:

#include <libgen.h>
char *dirname( char *path );
Description:
The dirname function takes a pointer to a character string that contains a pathname, and returns a pointer to a string that is a pathname of the parent directory of that file.  Trailing path separators are not considered as part of the path.
The dirname function may modify the string pointed to by path and may return a pointer to static storage that may be overwritten by a subsequent call to dirname

The dirname function is not re-entrant or thread-safe.
Returns:
The dirname function returns a pointer to a string that is the parent directory of path.  If path is a null pointer or points to an empty string, a pointer to the string "." is returned.
See Also:
basename
Example:

#include <stdio.h>
#include <libgen.h>

int main( void )
{

    puts( dirname( "/usr/lib" ) );
    puts( dirname( "/usr/" ) );
    puts( dirname( "usr" ) );
    puts( dirname( "/" ) );
    puts( dirname( ".." ) );
    return( 0 );
}

produces the following:

/usr
/
.
/
.
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

_disable

Synopsis:

#include <i86.h>
void _disable( void );
Description:
The _disable function causes interrupts to become disabled.
The _disable function would be used in conjunction with the _enable function to make sure that a sequence of instructions are executed without any intervening interrupts occurring.
Returns:
The _disable function returns no value.
See Also:
_enable
Example:

#include <stdio.h>
#include <stdlib.h>
#include <i86.h>

struct list_entry {
    struct list_entry *next;
    int               data;
};
volatile struct list_entry *ListHead = NULL;
volatile struct list_entry *ListTail = NULL;

void insert( struct list_entry *new_entry )
  {
    /* insert new_entry at end of linked list */
    new_entry->next = NULL;
    _disable();       /* disable interrupts */
    if( ListTail == NULL ) {
      ListHead = new_entry;
    } else {
      ListTail->next = new_entry;
    }
    ListTail = new_entry;
    _enable();        /* enable interrupts now */
  }

void main()
  {
    struct list_entry *p;
    int i;

    for( i = 1; i <= 10; i++ ) {
      p = (struct list_entry *)
          malloc( sizeof( struct list_entry ) );
      if( p == NULL ) break;
      p->data = i;
      insert( p );
    }
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

_displaycursor

Synopsis:

#include <graph.h>
short _FAR _displaycursor( short mode );
Description:
The _displaycursor function is used to establish whether the text cursor is to be displayed when graphics functions complete.  On entry to a graphics function, the text cursor is turned off.  When the function completes, the mode setting determines whether the cursor is turned back on.  The mode argument can have one of the following values:
_GCURSORON
the cursor will be displayed

_GCURSOROFF
the cursor will not be displayed
Returns:
The _displaycursor function returns the previous setting for mode.
See Also:
_gettextcursor, _settextcursor
Example:

#include <stdio.h>
#include <graph.h>

main()
{
    char buf[ 80 ];

    _setvideomode( _TEXTC80 );
    _settextposition( 2, 1 );
    _displaycursor( _GCURSORON );
    _outtext( "Cursor ON\n\nEnter your name >" );
    gets( buf );
    _displaycursor( _GCURSOROFF );
    _settextposition( 6, 1 );
    _outtext( "Cursor OFF\n\nEnter your name >" );
    gets( buf );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

div

Synopsis:

#include <stdlib.h>
div_t div( int numer, int denom );

typedef struct {
    int quot;     /* quotient  */
    int rem;      /* remainder */
} div_t;
Description:
The div function calculates the quotient and remainder of the division of the numerator numer by the denominator denom.
Returns:
The div function returns a structure of type div_t which contains the fields quot and rem.
See Also:
ldiv, lldiv, imaxdiv
Example:

#include <stdio.h>
#include <stdlib.h>

void print_time( int seconds )
{
     div_t  min_sec;

     min_sec = div( seconds, 60 );
     printf( "It took %d minutes and %d seconds\n",
             min_sec.quot, min_sec.rem );
}

void main( void )
{
    print_time( 130 );
}

produces the following:

It took 2 minutes and 10 seconds
Classification:
ISO C90
Systems:
All, Linux, RDOS, Netware

_dmsbintoieee

Synopsis:

#include <math.h>
extern int _dmsbintoieee( double *src, double *dest );
Description:
The _dmsbintoieee function loads the double pointed to by src in Microsoft binary format and converts it to IEEE format, storing the result into the double pointed to by dest.
The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38.  The range of Microsoft binary format doubles is 2.938735877056e-39 to 1.701411834605e+38.

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors became standard.
Returns:
The _dmsbintoieee function returns 0 if the conversion was successful.  Otherwise, it returns 1 if conversion would cause an overflow.
See Also:
_dieeetomsbin, _fieeetomsbin, _fmsbintoieee
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    float fieee, fmsb;
    double dieee, dmsb;

    fieee = 0.5;
    dieee = -2.0;

    /* Convert IEEE format to Microsoft binary format */
    _fieeetomsbin( &fieee, &fmsb );
    _dieeetomsbin( &dieee, &dmsb );

    /* Convert Microsoft binary format back to IEEE format */
    _fmsbintoieee( &fmsb, &fieee );
    _dmsbintoieee( &dmsb, &dieee );

    /* Display results */
    printf( "fieee = %f, dieee = %f\n", fieee, dieee );
  }

produces the following:

fieee = 0.500000, dieee = -2.000000
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_dos_allocmem

Synopsis:

#include <dos.h>
#if defined(__NT__) || \
  ( defined(__OS2__) && \
        (defined(__386__) || defined(__PPC__)) )
unsigned _dos_allocmem( unsigned size,
                         void * *segment);
#else
unsigned _dos_allocmem( unsigned size,
                         unsigned *segment);
#endif
Description:
The _dos_allocmem function uses system call 0x48 to allocate size paragraphs directly from DOS.  The size of a paragraph is 16 bytes.  The allocated memory is always paragraph aligned.  The segment descriptor for the allocated memory is returned in the word pointed to by segment.  If the allocation request fails, the maximum number of paragraphs that can be allocated is returned in this word instead.
For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used.
Returns:
The _dos_allocmem function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
alloca, calloc, _dos_freemem, _dos_setblock, halloc, malloc
Example:

#include <stdio.h>
#include <dos.h>

void main( void )
{
#if defined(__NT__) || \
  ( defined(__OS2__) && \
        (defined(__386__) || defined(__PPC__)) )
    void *segment;
#else
    unsigned segment;
#endif

    /* Try to allocate 100 paragraphs, then free them */
    if( _dos_allocmem( 100, &segment ) != 0 ) {
        printf( "_dos_allocmem failed\n" );
        printf( "Only %u paragraphs available\n",
                 segment );
    } else {
        printf( "_dos_allocmem succeeded\n" );
        if( _dos_freemem( segment ) != 0 ) {
            printf( "_dos_freemem failed\n" );
        } else {
            printf( "_dos_freemem succeeded\n" );
        }
    }
}
Classification:
DOS
Systems:
DOS, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_close

Synopsis:

#include <dos.h>
unsigned _dos_close( int handle );
Description:
The _dos_close function uses system call 0x3E to close the file indicated by handle.  The value for handle is the one returned by a function call that created or last opened the file.
Returns:
The _dos_close function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
creat, _dos_creat, _dos_creatnew, _dos_open, dup, fclose, open
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

void main()
  {
    int handle;

    /* Try to open "stdio.h" and then close it */
    if( _dos_open( "stdio.h", O_RDONLY, &handle ) != 0 ){
      printf( "Unable to open file\n" );
    } else {
      printf( "Open succeeded\n" );
      if( _dos_close( handle ) != 0 ) {
        printf( "Close failed\n" );
      } else {
        printf( "Close succeeded\n" );
      }
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_commit

Synopsis:

#include <dos.h>
unsigned _dos_commit( int handle );
Description:
The _dos_commit function uses system call 0x68 to flush to disk the DOS buffers associated with the file indicated by handle.  It also forces an update on the corresponding disk directory and the file allocation table.
Returns:
The _dos_commit function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_close, _dos_creat, _dos_open, _dos_write, fflush
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

void main()
  {
    int handle;

    if( _dos_open( "file", O_RDONLY, handle ) != 0 ) {
        printf( "Unable to open file\n" );
    } else {
        if( _dos_commit( handle ) == 0 ) {
            printf( "Commit succeeded.\n" );
        }
        _dos_close( handle );
    }
  }

produces the following:

Commit succeeded.
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_creat

Synopsis:

#include <dos.h>
unsigned _dos_creat( const char *path,
                      unsigned attribute,
                      int *handle );
Description:
The _dos_creat function uses system call 0x3C to create a new file named path, with the access attributes specified by attribute.  The handle for the new file is returned in the word pointed to by handle.  If the file already exists, the contents will be erased, and the attributes of the file will remain unchanged.  The possible values for attribute are:
Attribute     Meaning
_A_NORMAL
Indicates a normal file.  File can be read or written without any restrictions.

_A_RDONLY
Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
Indicates a hidden file.  This file will not show up in a normal directory search.

_A_SYSTEM
Indicates a system file.  This file will not show up in a normal directory search.
Returns:
The _dos_creat function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
creat, _dos_creatnew, _dos_open, _dos_close, open, fdopen, fopen, freopen, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    int handle;

    if( _dos_creat( "file", _A_NORMAL, &handle ) != 0 ){
      printf( "Unable to create file\n" );
    } else {
      printf( "Create succeeded\n" );
      _dos_close( handle );
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_creatnew

Synopsis:

#include <dos.h>
unsigned _dos_creatnew( const char *path,
                         unsigned attribute,
                         int *handle );
Description:
The _dos_creatnew function uses system call 0x5B to create a new file named path, with the access attributes specified by attribute.  The handle for the new file is returned in the word pointed to by handle.  If the file already exists, the create will fail.  The possible values for attribute are:
Attribute     Meaning
_A_NORMAL
Indicates a normal file.  File can be read or written without any restrictions.

_A_RDONLY
Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
Indicates a hidden file.  This file will not show up in a normal directory search.

_A_SYSTEM
Indicates a system file.  This file will not show up in a normal directory search.
Returns:
The _dos_creatnew function returns zero if successful.  Otherwise, it returns an OS error code and sets errno.  Possible values and their interpretations:
Constant     Meaning
EACCES
Access denied because the directory is full, or the file exists and cannot be overwritten.

EEXIST
File already exists

EMFILE
No more handles available (i.e., too many open files)

ENOENT
Path or file not found
See Also:
creat, _dos_creat, _dos_open, _dos_close, open, fdopen, fopen, freopen, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    int handle1, handle2;
    if( _dos_creat( "file", _A_NORMAL, &handle1 ) ){
      printf( "Unable to create file\n" );
    } else {
      printf( "Create succeeded\n" );
      if( _dos_creatnew( "file", _A_NORMAL, &handle2 ) ){
        printf( "Unable to create new file\n" );
      }
      _dos_close( handle1 );
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

dosexterr

Synopsis:

#include <dos.h>
int dosexterr( struct DOSERROR *err_info );

struct _DOSERROR {
    int     exterror; /* contents of AX register */
    char    errclass; /* contents of BH register */
    char    action;   /* contents of BL register */
    char    locus;    /* contents of CH register */
};
Description:
The dosexterr function extracts extended error information following a failed DOS function.  This information is placed in the structure located by err_info.  This function is only useful with DOS version 3.0 or later.
You should consult the technical documentation for the DOS system on your computer for an interpretation of the error information.
Returns:
The dosexterr function returns an unpredictable result when the preceding DOS call did not result in an error.  Otherwise, dosexterr returns the number of the extended error.
See Also:
perror
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

struct _DOSERROR dos_err;

void main()
  {
    int handle;

    /* Try to open "stdio.h" and then close it */
    if( _dos_open( "stdio.h", O_RDONLY, &handle ) != 0 ){
      dosexterr( &dos_err );
      printf( "Unable to open file\n" );
      printf( "exterror (AX) = %d\n", dos_err.exterror );
      printf( "errclass (BH) = %d\n", dos_err.errclass );
      printf( "action   (BL) = %d\n", dos_err.action );
      printf( "locus    (CH) = %d\n", dos_err.locus );
    } else {
      printf( "Open succeeded\n" );
      if( _dos_close( handle ) != 0 ) {
        printf( "Close failed\n" );
      } else {
        printf( "Close succeeded\n" );
      }
    }
  }

produces the following:

Unable to open file
exterror (AX) = 2
errclass (BH) = 8
action   (BL) = 3
locus    (CH) = 2
Classification:
DOS
Systems:
DOS, Windows, Win386, DOS/PM

_dos_find...  Functions

Synopsis:

#include <dos.h>
unsigned _dos_findfirst( const char *path,
                          unsigned attributes,
                          struct find_t *buffer );
unsigned _dos_findnext(  struct find_t *buffer );
unsigned _dos_findclose( struct find_t *buffer );

struct find_t {
    char           reserved[21]; /* reserved for use by DOS    */
    char           attrib;        /* attribute byte for file    */
    unsigned short wr_time;      /* time of last write to file */
    unsigned short wr_date;      /* date of last write to file */
    unsigned long  size;         /* length of file in bytes    */
#if defined(__OS2__) || defined(__NT__)
    char           name[256];     /* null-terminated filename   */
#else
    char           name[13];      /* null-terminated filename   */
#endif
};
unsigned _wdos_findfirst( const wchar_t *path,
                           unsigned attributes,
                           struct _wfind_t *buffer );
unsigned _wdos_findnext( struct _wfind_t *buffer );
unsigned _wdos_findclose( struct _wfind_t *buffer );

struct _wfind_t {
    char           reserved[21]; /* reserved for use by DOS    */
    char           attrib;        /* attribute byte for file    */
    unsigned short wr_time;      /* time of last write to file */
    unsigned short wr_date;      /* date of last write to file */
    unsigned long  size;         /* length of file in bytes    */
#if defined(__OS2__) || defined(__NT__)
    wchar_t        name[256];    /* null-terminated filename   */
#else
    wchar_t        name[13];     /* null-terminated filename   */
#endif
};
Description:
The _dos_findfirst function uses system call 0x4E to return information on the first file whose name and attributes match the path and attributes arguments.  The information is returned in a find_t structure pointed to by buffer.  The path argument may contain wildcard characters ('?' and '*').  The attributes argument may be any combination of the following constants:
Attribute     Meaning
_A_NORMAL
Indicates a normal file.  File can be read or written without any restrictions.

_A_RDONLY
Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
Indicates a hidden file.  This file will not show up in a normal directory search.

_A_SYSTEM
Indicates a system file.  This file will not show up in a normal directory search.

_A_VOLID
Indicates a volume-ID.

_A_SUBDIR
Indicates a sub-directory.

_A_ARCH
This is the archive flag.  It is set whenever the file is modified, and is cleared by the MS-DOS BACKUP command and other backup utility programs.

The attributes argument is interpreted by DOS as follows:
  1. If _A_NORMAL is specified, then normal files are included in the search.
  2. If any of _A_HIDDEN, _A_SYSTEM, _A_SUBDIR are specified, then normal files and the specified type of files are included in the search.
  3. If _A_VOLID is specified, then volume-ID's are also included in the search.  Note:  The _A_VOLID attribute is not supported on systems other than DOS (e.g.  Win32, OS/2).
  4. _A_RDONLY and _A_ARCH are ignored by this function.

The format of the wr_time field is described by the following structure (this structure is not defined in any Open Watcom header file).

typedef struct {
    unsigned short  twosecs : 5;    /* seconds / 2    */
    unsigned short  minutes : 6;    /* minutes (0,59) */
    unsigned short  hours   : 5;    /* hours (0,23)   */
} ftime_t;
The format of the wr_date field is described by the following structure (this structure is not defined in any Open Watcom header file).

typedef struct {
    unsigned short  day     : 5;    /* day (1,31)   */
    unsigned short  month   : 4;    /* month (1,12) */
    unsigned short  year    : 7;    /* 0 is 1980    */
} fdate_t;
The _dos_findnext function uses system call 0x4F to return information on the next file whose name and attributes match the pattern supplied to the _dos_findfirst function.

On some systems (e.g.  Win32, OS/2), you must call _dos_findclose to indicate that you are done matching files.  This function deallocates any resources that were allocated by the _dos_findfirst function.

The _wdos_find...  functions are similar to their counterparts but operate on wide character strings.
Returns:
The _dos_find... functions return zero if successful.  Otherwise, the _dos_findfirst and _dos_findnext functions return an OS error code and set errno accordingly.
See Also:
opendir, readdir, closedir
Example:

#include <stdio.h>
#include <dos.h>

void main()
{
    struct find_t   fileinfo;
    unsigned        rc;          /* return code */

    /* Display name and size of "*.c" files */
    rc = _dos_findfirst( "*.c", _A_NORMAL, &fileinfo );
    while( rc == 0 ) {
        printf( "%14s %10ld\n", fileinfo.name,
                                 fileinfo.size );
        rc = _dos_findnext( &fileinfo );
    }
    #if defined(__OS2__)
    _dos_findclose( &fileinfo );
    #endif
}
Classification:
DOS
Systems:
_dos_findclose - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM
_dos_findfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM
_dos_findnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM
_wdos_findclose - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wdos_findfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wdos_findnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_dos_freemem

Synopsis:

#include <dos.h>
#if defined(__NT__) || \
  ( defined(__OS2__) && \
        (defined(__386__) || defined(__PPC__)) )
unsigned _dos_freemem( void *   segment );
#else
unsigned _dos_freemem( unsigned segment );
#endif
Description:
The _dos_freemem function uses system call 0x49 to release memory that was previously allocated by _dos_allocmem.   The value contained in segment is the one returned by a previous call to _dos_allocmem.
For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used.
Returns:
The _dos_freemem function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_allocmem, _dos_setblock, free, hfree
Example:

#include <stdio.h>
#include <dos.h>

void main( void )
{
#if defined(__NT__) || \
  ( defined(__OS2__) && \
        (defined(__386__) || defined(__PPC__)) )
    void *segment;
#else
    unsigned segment;
#endif

    /* Try to allocate 100 paragraphs, then free them */
    if( _dos_allocmem( 100, &segment ) != 0 ) {
        printf( "_dos_allocmem failed\n" );
        printf( "Only %u paragraphs available\n",
                 segment );
    } else {
        printf( "_dos_allocmem succeeded\n" );
        if( _dos_freemem( segment ) != 0 ) {
            printf( "_dos_freemem failed\n" );
        } else {
            printf( "_dos_freemem succeeded\n" );
        }
    }
}
Classification:
DOS
Systems:
DOS, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getdate

Synopsis:

#include <dos.h>
void _dos_getdate( struct dosdate_t *date );

struct dosdate_t {
    unsigned char  day;       /* 1-31            */
    unsigned char  month;     /* 1-12            */
    unsigned short year;      /* 1980-2099      */
    unsigned char  dayofweek; /* 0-6 (0=Sunday) */
};
Description:
The _dos_getdate function uses system call 0x2A to get the current system date.  The date information is returned in a dosdate_t structure pointed to by date.
Returns:
The _dos_getdate function has no return value.
See Also:
_dos_gettime, _dos_setdate, _dos_settime, gmtime, localtime, mktime, time
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    struct dosdate_t date;
    struct dostime_t time;

    /* Get and display the current date and time */
    _dos_getdate( &date );
    _dos_gettime( &time );
    printf( "The date (MM-DD-YYYY) is: %d-%d-%d\n",
                  date.month, date.day, date.year );
    printf( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
                  time.hour, time.minute, time.second );
  }

produces the following:

The date (MM-DD-YYYY) is: 12-25-1989
The time (HH:MM:SS) is: 14:23:57
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getdiskfree

Synopsis:

#include <dos.h>
unsigned _dos_getdiskfree( unsigned drive,
                         struct diskfree_t *diskspace );
struct diskfree_t {
    unsigned short  total_clusters;
    unsigned short  avail_clusters;
    unsigned short  sectors_per_cluster;
    unsigned short  bytes_per_sector;
};
Description:
The _dos_getdiskfree function uses system call 0x36 to obtain useful information on the disk drive specified by drive.  Specify 0 for the default drive, 1 for drive A, 2 for drive B, etc.  The information about the drive is returned in the structure diskfree_t pointed to by diskspace.
Returns:
The _dos_getdiskfree function returns zero if successful.  Otherwise, it returns a non-zero value and sets errno to EINVAL indicating an invalid drive was specified.
See Also:
_dos_getdrive, _dos_setdrive, _getdiskfree, _getdrive
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    struct diskfree_t disk_data;

    /* get information about drive 3 (the C drive) */
    if( _dos_getdiskfree( 3, &disk_data ) == 0 ) {
      printf( "total clusters: %u\n",
                         disk_data.total_clusters );
      printf( "available clusters: %u\n",
                         disk_data.avail_clusters );
      printf( "sectors/cluster: %u\n",
                         disk_data.sectors_per_cluster );
      printf( "bytes per sector: %u\n",
                         disk_data.bytes_per_sector );
    } else {
      printf( "Invalid drive specified\n" );
    }
  }

produces the following:

total clusters: 16335
available clusters: 510
sectors/cluster: 4
bytes per sector: 512
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getdrive

Synopsis:

#include <dos.h>
void _dos_getdrive( unsigned *drive );
Description:
The _dos_getdrive function uses system call 0x19 to get the current disk drive number.  The current disk drive number is returned in the word pointed to by drive.  A value of 1 is drive A, 2 is drive B, 3 is drive C, etc.
Returns:
The _dos_getdrive function has no return value.
See Also:
_dos_getdiskfree, _dos_setdrive, _getdiskfree, _getdrive
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    unsigned drive;

    _dos_getdrive( &drive );
    printf( "The current drive is %c\n",
                'A' + drive - 1 );
  }

produces the following:

The current drive is C
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getfileattr

Synopsis:

#include <dos.h>
unsigned _dos_getfileattr( const char *path,
                            unsigned *attributes );
Description:
The _dos_getfileattr function uses system call 0x43 to get the current attributes of the file or directory that path points to.  The possible attributes are:
Attribute     Meaning
_A_NORMAL
Indicates a normal file.  File can be read or written without any restrictions.

_A_RDONLY
Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
Indicates a hidden file.  This file will not show up in a normal directory search.

_A_SYSTEM
Indicates a system file.  This file will not show up in a normal directory search.

_A_VOLID
Indicates a volume-ID.

_A_SUBDIR
Indicates a sub-directory.

_A_ARCH
This is the archive flag.  It is set whenever the file is modified, and is cleared by the MS-DOS BACKUP command and other backup utility programs.
Returns:
The _dos_getfileattr function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_setfileattr
Example:

#include <stdio.h>
#include <dos.h>

print_attribute()
  {
    unsigned attribute;

    _dos_getfileattr( "file", &attribute );
    printf( "File attribute is %d\n", attribute );
    if( attribute & _A_RDONLY ) {
        printf( "This is a read-only file.\n" );
    } else {
        printf( "This is not a read-only file.\n" );
    }
  }

void main()
  {
    int      handle;

    if( _dos_creat( "file", _A_RDONLY, &handle ) != 0 ) {
      printf( "Error creating file\n" );
    }
    print_attribute();
    _dos_setfileattr( "file", _A_NORMAL );
    print_attribute();
    _dos_close( handle );
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getftime

Synopsis:

#include <dos.h>
unsigned _dos_getftime( int handle,
                         unsigned *date,
                         unsigned *time );
Description:
The _dos_getftime function uses system call 0x57 to get the date and time that the file associated with handle was last modified.  The date consists of the year, month and day packed into 16 bits as follows:
Bits
Meaning

bits 0-4
Day (1-31)

bits 5-8
Month (1-12)

bits 9-15
Year (0-119 representing 1980-2099)

The time consists of the hour, minute and seconds/2 packed into 16 bits as follows:
Bits
Meaning

bits 0-4
Seconds/2 (0-29)

bits 5-10
Minutes (0-59)

bits 11-15
Hours (0-23)
Returns:
The _dos_getftime function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_setftime
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

#define YEAR(t)   (((t & 0xFE00) >> 9) + 1980)
#define MONTH(t)  ((t & 0x01E0) >> 5)
#define DAY(t)    (t & 0x001F)
#define HOUR(t)   ((t & 0xF800) >> 11)
#define MINUTE(t) ((t & 0x07E0) >> 5)
#define SECOND(t) ((t & 0x001F) << 1)

void main( void )
{
    int      handle;
    unsigned date, time;

    if( _dos_open( "file", O_RDONLY, &handle ) != 0 ) {
        printf( "Unable to open file\n" );
    } else {
        printf( "Open succeeded\n" );
        _dos_getftime( handle, &date, &time );
        printf( "The file was last modified on %d/%d/%d",
                MONTH(date), DAY(date), YEAR(date) );
        printf( " at %.2d:%.2d:%.2d\n",
                HOUR(time), MINUTE(time), SECOND(time) );
        _dos_close( handle );
    }
}

produces the following:

Open succeeded
The file was last modified on 12/29/1989 at 14:32:46
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_gettime

Synopsis:

#include <dos.h>
void _dos_gettime( struct dostime_t *time );

struct dostime_t {
    unsigned char   hour;     /* 0-23                */
    unsigned char   minute;   /* 0-59                */
    unsigned char   second;   /* 0-59                */
    unsigned char   hsecond;  /* 1/100 second; 0-99 */
};
Description:
The _dos_gettime function uses system call 0x2C to get the current system time.  The time information is returned in a dostime_t structure pointed to by time.
Returns:
The _dos_gettime function has no return value.
See Also:
_dos_getdate, _dos_setdate, _dos_settime, gmtime, localtime, mktime, time
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    struct dosdate_t date;
    struct dostime_t time;

    /* Get and display the current date and time */
    _dos_getdate( &date );
    _dos_gettime( &time );
    printf( "The date (MM-DD-YYYY) is: %d-%d-%d\n",
        date.month, date.day, date.year );
    printf( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
        time.hour, time.minute, time.second );
  }

produces the following:

The date (MM-DD-YYYY) is: 12-25-1989
The time (HH:MM:SS) is: 14:23:57
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_getvect

Synopsis:

#include <dos.h>
void (__interrupt __far *_dos_getvect(unsigned intnum))();
Description:
The _dos_getvect function gets the current value of interrupt vector number intnum.
Returns:
The _dos_getvect function returns a far pointer to the current interrupt handler for interrupt number intnum.
See Also:
_chain_intr, _dos_keep, _dos_setvect
Example:

#include <stdio.h>
#include <dos.h>

volatile int clock_ticks;
void (__interrupt __far *prev_int_1c)();
#define BLIP_COUNT  (5*18)  /* 5 seconds */

void __interrupt __far timer_rtn()
  {
    ++clock_ticks;
    _chain_intr( prev_int_1c );
  }

int delays = 0;

int compile_a_line()
  {
    if( delays > 15 ) return( 0 );
    delay( 1000 );  /* delay for 1 second */
    printf( "Delayed for 1 second\n" );
    delays++;
    return( 1 );
  }

void main()
  {
    prev_int_1c = _dos_getvect( 0x1c );
    _dos_setvect( 0x1c, timer_rtn );
    while( compile_a_line() ) {
        if( clock_ticks >= BLIP_COUNT ) {
            putchar( '.' );
            clock_ticks -= BLIP_COUNT;
        }
    }
    _dos_setvect( 0x1c, prev_int_1c );
  }
Classification:
WATCOM
Systems:
DOS, Windows, DOS/PM

_dos_keep

Synopsis:

#include <dos.h>
void _dos_keep( unsigned retcode, unsigned memsize );
Description:
The _dos_keep function is used to install terminate-and-stay-resident programs ("TSR's") in memory.  The amount of memory kept for the program is memsize paragraphs (a paragraph is 16 bytes) from the Program Segment Prefix which is stored in the variable _psp.  The value of retcode is returned to the parent process.
Returns:
The _dos_keep function does not return to its caller.
See Also:
_chain_intr, _dos_getvect, _dos_setvect
Example:

#include <dos.h>

void permanent()
  {
    /* . */
    /* . */
    /* . */
  }

void transient()
  {
    /* . */
    /* . */
    /* . */
  }

void main()
  {
    /* initialize our TSR */
    transient();
    /*
        now terminate and keep resident
        the non-transient portion
        Note: following calculation only works in .COM files
    */
    _dos_keep( 0, (FP_OFF( transient ) + 15) >> 4 );
  }
Classification:
DOS
Systems:
DOS

_dos_open

Synopsis:

#include <dos.h>
#include <fcntl.h>
#include <share.h>
unsigned _dos_open( const char *path,
                    unsigned mode,
                    int *handle );
Description:
The _dos_open function uses system call 0x3D to open the file specified by path, which must be an existing file.  The mode argument specifies the file's access, sharing and inheritance permissions.  The access mode must be one of:
Mode     Meaning
O_RDONLY
Read only

O_WRONLY
Write only

O_RDWR
Both read and write

The sharing permissions, if specified, must be one of:
Permission     Meaning
SH_COMPAT
Set compatibility mode.

SH_DENYRW
Prevent read or write access to the file.

SH_DENYWR
Prevent write access of the file.

SH_DENYRD
Prevent read access to the file.

SH_DENYNO
Permit both read and write access to the file.

The inheritance permission, if specified, is:
Permission     Meaning
O_NOINHERIT
File is not inherited by a child process
Returns:
The _dos_open function returns zero if successful.  Otherwise, it returns an MS-DOS error code and sets errno to one of the following values:
Constant     Meaning
EACCES
Access denied because path specifies a directory or a volume ID, or opening a read-only file for write access

EINVAL
A sharing mode was specified when file sharing is not installed, or access-mode value is invalid

EMFILE
No more handles available, (too many open files)

ENOENT
Path or file not found
See Also:
_dos_close, _dos_creat, _dos_creatnew, _dos_read, _dos_write, fdopen, fopen, freopen, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>
#include <share.h>

void main()
  {
    int handle;

    if( _dos_open( "file", O_RDONLY, &handle ) != 0 ) {
        printf( "Unable to open file\n" );
    } else {
        printf( "Open succeeded\n" );
        _dos_close( handle );
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_read

Synopsis:

#include <dos.h>
unsigned _dos_read( int handle, void __far *buffer,
                    unsigned count, unsigned *bytes );
Description:
The _dos_read function uses system call 0x3F to read count bytes of data from the file specified by handle into the buffer pointed to by buffer.  The number of bytes successfully read will be stored in the unsigned integer pointed to by bytes.
Returns:
The _dos_read function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_close, _dos_open, _dos_write
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

void main()
  {
    unsigned len_read;
    int      handle;
    auto char buffer[80];

    if( _dos_open( "file", O_RDONLY, &handle ) != 0 ) {
      printf( "Unable to open file\n" );
    } else {
      printf( "Open succeeded\n" );
      _dos_read( handle, buffer, 80, &len_read );
      _dos_close( handle );
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_setblock

Synopsis:

#include <dos.h>
unsigned _dos_setblock( unsigned size,
                         unsigned segment,
                         unsigned *maxsize );
Description:
The _dos_setblock function uses system call 0x4A to change the size of segment, which was previously allocated by _dos_allocmem, to size paragraphs.  If the request fails, the maximum number of paragraphs that this memory block can be changed to is returned in the word pointed to by maxsize.
For 32-bit DOS applications, it is recommended that the corresponding DPMI services be used.
Returns:
The _dos_setblock function returns zero if successful.  Otherwise, it returns an OS error code and sets errno to ENOMEM indicating a bad segment value, insufficient memory or corrupted memory.
See Also:
_dos_allocmem, _dos_freemem, realloc
Example:

#include <stdio.h>
#include <dos.h>

void main( void )
{
#if defined(__NT__) || \
  ( defined(__OS2__) && \
        (defined(__386__) || defined(__PPC__)) )
    void *segment;
#else
    unsigned segment;
#endif

    /* Try to allocate 100 paragraphs, then free them */
    if( _dos_allocmem( 100, &segment ) != 0 ) {
        printf( "_dos_allocmem failed\n" );
        printf( "Only %u paragraphs available\n", segment);
    } else {
        printf( "_dos_allocmem succeeded\n" );

#if defined(__DOS__)
        { unsigned maxsize = 0;
        /* Try to increase it to 200 paragraphs */
        if( _dos_setblock( 200, segment, &maxsize ) != 0 ) {
            printf( "_dos_setblock failed: max=%u, err=%s\n",
                    maxsize, strerror( errno) );
        } else {
            printf( "_dos_setblock succeeded\n" );
        }
        }
#endif

        if( _dos_freemem( segment ) != 0 ) {
            printf( "_dos_freemem failed\n" );
        } else {
            printf( "_dos_freemem succeeded\n" );
        }
    }
}
Classification:
DOS
Systems:
DOS, DOS/PM

_dos_setdate

Synopsis:

#include <dos.h>
unsigned _dos_setdate( struct dosdate_t *date );

struct dosdate_t {
    unsigned char   day;        /* 1-31            */
    unsigned char   month;      /* 1-12            */
    unsigned short  year;       /* 1980-2099       */
    unsigned char   dayofweek;  /* 0-6 (0=Sunday) */
};
Description:
The _dos_setdate function uses system call 0x2B to set the current system date.  The date information is passed in a dosdate_t structure pointed to by date.
Returns:
The _dos_setdate function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_getdate, _dos_gettime, _dos_settime, gmtime, localtime, mktime, time
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    struct dosdate_t date;
    struct dostime_t time;

    /* Get and display the current date and time */
    _dos_getdate( &date );
    _dos_gettime( &time );
    printf( "The date (MM-DD-YYYY) is: %d-%d-%d\n",
        date.month, date.day, date.year );
    printf( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
        time.hour, time.minute, time.second );

    /* Change it to the turn of the century */
    date.year = 1999;
    date.month = 12;
    date.day = 31;
    time.hour = 23;
    time.minute = 59;
    _dos_setdate( &date );
    _dos_settime( &time );
    printf( "New date (MM-DD-YYYY) is: %d-%d-%d\n",
        date.month, date.day, date.year );
    printf( "New time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
        time.hour, time.minute, time.second );
  }

produces the following:

The date (MM-DD-YYYY) is: 12-25-1989
The time (HH:MM:SS) is: 14:23:15
New date (MM-DD-YYYY) is: 12-31-1999
New time (HH:MM:SS) is: 23:59:16
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_setdrive

Synopsis:

#include <dos.h>
void _dos_setdrive( unsigned drive, unsigned *total );
Description:
The _dos_setdrive function uses system call 0x0E to set the current default disk drive to be the drive specified by drive, where 1 = drive A, 2 = drive B, etc.  The total number of disk drives is returned in the word pointed to by total.  For DOS versions 3.0 or later, the minimum number of drives returned is 5.
Returns:
The _dos_setdrive function has no return value.  If an invalid drive number is specified, the function fails with no error indication.  You must use the _dos_getdrive function to check that the desired drive has been set.
See Also:
_dos_getdiskfree, _dos_getdrive, _getdiskfree, _getdrive
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    unsigned drive1, drive2, total;

    _dos_getdrive( &drive1 );
    printf( "Current drive is %c\n", 'A' + drive1 - 1 );
    /* try to change to drive C */
    _dos_setdrive( 3, &total );
    _dos_getdrive( &drive2 );
    printf( "Current drive is %c\n", 'A' + drive2 - 1 );
    /* go back to original drive */
    _dos_setdrive( drive1, &total );
    _dos_getdrive( &drive1 );
    printf( "Current drive is %c\n", 'A' + drive1 - 1 );
    printf( "Total number of drives is %u\n", total );
  }

produces the following:

Current drive is D
Current drive is C
Total number of drives is 6
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_setfileattr

Synopsis:

#include <dos.h>
unsigned _dos_setfileattr( const char *path,
                            unsigned attributes );
Description:
The _dos_setfileattr function uses system call 0x43 to set the attributes of the file or directory that path points to.  The possible attributes are:
Attribute     Meaning
_A_NORMAL
Indicates a normal file.  File can be read or written without any restrictions.

_A_RDONLY
Indicates a read-only file.  File cannot be opened for "write".

_A_HIDDEN
Indicates a hidden file.  This file will not show up in a normal directory search.

_A_SYSTEM
Indicates a system file.  This file will not show up in a normal directory search.

_A_VOLID
Indicates a volume-ID.

_A_SUBDIR
Indicates a sub-directory.

_A_ARCH
This is the archive flag.  It is set whenever the file is modified, and is cleared by the MS-DOS BACKUP command and other backup utility programs.
Returns:
The _dos_setfileattr function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_getfileattr
Example:

#include <stdio.h>
#include <dos.h>

print_attribute()
  {
    unsigned attribute;

    _dos_getfileattr( "file", &attribute );
    printf( "File attribute is %x\n", attribute );
    if( attribute & _A_RDONLY ) {
        printf( "This is a read-only file\n" );
    } else {
        printf( "This is not a read-only file\n" );
    }
  }

void main()
  {
    int      handle;

    if( _dos_creat( "file", _A_RDONLY, &handle ) != 0 ){
      printf( "Error creating file\n" );
    }
    print_attribute();
    _dos_setfileattr( "file", _A_NORMAL );
    print_attribute();
    _dos_close( handle );
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_setftime

Synopsis:

#include <dos.h>
unsigned _dos_setftime( int handle,
                         unsigned date,
                         unsigned time );
Description:
The _dos_setftime function uses system call 0x57 to set the date and time that the file associated with handle was last modified.  The date consists of the year, month and day packed into 16 bits as follows:
Bits
Meaning

bits 0-4
Day (1-31)

bits 5-8
Month (1-12)

bits 9-15
Year (0-119 representing 1980-2099)

The time consists of the hour, minute and seconds/2 packed into 16 bits as follows:
Bits
Meaning

bits 0-4
Seconds/2 (0-29)

bits 5-10
Minutes (0-59)

bits 11-15
Hours (0-23)
Returns:
The _dos_setftime function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_getftime
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

#define YEAR(t)   (((t & 0xFE00) >> 9) + 1980)
#define MONTH(t)  ((t & 0x01E0) >> 5)
#define DAY(t)    (t & 0x001F)
#define HOUR(t)   ((t & 0xF800) >> 11)
#define MINUTE(t) ((t & 0x07E0) >> 5)
#define SECOND(t) ((t & 0x001F) << 1)

void main( void )
{
    int      handle;
    unsigned short date, time;

    if( _dos_open( "file", O_RDWR, &handle ) != 0 ) {
        printf( "Unable to open file\n" );
    } else {
      printf( "Open succeeded\n" );
        _dos_getftime( handle, &date, &time );
        printf( "The file was last modified on %d/%d/%d",
                MONTH(date), DAY(date), YEAR(date) );
        printf( " at %.2d:%.2d:%.2d\n",
                HOUR(time), MINUTE(time), SECOND(time) );
        /* set the time to 12 noon */
        time = (12 << 11) + (0 << 5) + 0;
        _dos_setftime( handle, date, time );
        _dos_getftime( handle, &date, &time );
        printf( "The file was last modified on %d/%d/%d",
                MONTH(date), DAY(date), YEAR(date) );
        printf( " at %.2d:%.2d:%.2d\n",
                HOUR(time), MINUTE(time), SECOND(time) );
        _dos_close( handle );
    }
}

produces the following:

Open succeeded
The file was last modified on 12/29/1989 at 14:32:46
The file was last modified on 12/29/1989 at 12:00:00
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_settime

Synopsis:

#include <dos.h>
unsigned _dos_settime( struct dostime_t *time );
struct dostime_t {
    unsigned char hour;     /* 0-23                */
    unsigned char minute;   /* 0-59                */
    unsigned char second;   /* 0-59                */
    unsigned char hsecond;  /* 1/100 second; 0-99 */
};
Description:
The _dos_settime function uses system call 0x2D to set the current system time.  The time information is passed in a dostime_t structure pointed to by time.
Returns:
The _dos_settime function returns zero if successful.  Otherwise, it returns a non-zero value and sets errno to EINVAL indicating that an invalid time was given.
See Also:
_dos_getdate, _dos_setdate, _dos_gettime, gmtime, localtime, mktime, time
Example:

#include <stdio.h>
#include <dos.h>

void main()
  {
    struct dosdate_t date;
    struct dostime_t time;

    /* Get and display the current date and time */
    _dos_getdate( &date );
    _dos_gettime( &time );
    printf( "The date (MM-DD-YYYY) is: %d-%d-%d\n",
        date.month, date.day, date.year );
    printf( "The time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
        time.hour, time.minute, time.second );

    /* Change it to the turn of the century */
    date.year = 1999;
    date.month = 12;
    date.day = 31;
    time.hour = 23;
    time.minute = 59;
    _dos_setdate( &date );
    _dos_settime( &time );
    printf( "New date (MM-DD-YYYY) is: %d-%d-%d\n",
                  date.month, date.day, date.year );
    printf( "New time (HH:MM:SS) is: %.2d:%.2d:%.2d\n",
                  time.hour, time.minute, time.second );
  }

produces the following:

The date (MM-DD-YYYY) is: 12-25-1989
The time (HH:MM:SS) is: 14:23:15
New date (MM-DD-YYYY) is: 12-31-1999
New time (HH:MM:SS) is: 23:59:16
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

_dos_setvect

Synopsis:

#include <dos.h>
void _dos_setvect( unsigned intnum,
                   void (__interrupt __far *handler)() );
Description:
The _dos_setvect function sets interrupt vector number intnum to point to the interrupt handling function pointed to by handler.
Returns:
The _dos_setvect function does not return a value.
See Also:
_chain_intr, _dos_getvect, _dos_keep
Example:

#include <stdio.h>
#include <dos.h>

volatile int clock_ticks;
void (__interrupt __far *prev_int_1c)();
#define BLIP_COUNT  (5*18)  /* 5 seconds */

void __interrupt __far timer_rtn()
  {
    ++clock_ticks;
    _chain_intr( prev_int_1c );
  }

int compile_a_line()
  {
    static int delays = 0;
    if( delays > 15 ) return( 0 );
    delay( 1000 );  /* delay for 1 second */
    printf( "Delayed for 1 second\n" );
    delays++;
    return( 1 );
  }

void main()
  {
    prev_int_1c = _dos_getvect( 0x1c );
    _dos_setvect( 0x1c, timer_rtn );
    while( compile_a_line() ) {
        if( clock_ticks >= BLIP_COUNT ) {
            putchar( '.' );
            clock_ticks -= BLIP_COUNT;
        }
    }
    _dos_setvect( 0x1c, prev_int_1c );
  }
Classification:
WATCOM
Systems:
DOS, Windows, DOS/PM

_dos_write

Synopsis:

#include <dos.h>
unsigned _dos_write( int handle, void const __far *buffer,
                      unsigned count, unsigned *bytes );
Description:
The _dos_write function uses system call 0x40 to write count bytes of data from the buffer pointed to by buffer to the file specified by handle.  The number of bytes successfully written will be stored in the unsigned integer pointed to by bytes.
Returns:
The _dos_write function returns zero if successful.  Otherwise, it returns an OS error code and sets errno accordingly.
See Also:
_dos_close, _dos_open, _dos_read
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>

char buffer[] = "This is a test for _dos_write.";

void main()
  {
    unsigned len_written;
    int      handle;

    if( _dos_creat( "file", _A_NORMAL, &handle ) != 0 ) {
      printf( "Unable to create file\n" );
    } else {
      printf( "Create succeeded\n" );
      _dos_write( handle, buffer, sizeof(buffer),
                  &len_written );
      _dos_close( handle );
    }
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, DOS/PM

dup, _dup

Synopsis:

#include <io.h>
int dup( int handle );
int _dup( int handle );
Description:
The dup function duplicates the file handle given by the argument handle.  The new file handle refers to the same open file handle as the original file handle, and shares any locks.  The new file handle is identical to the original in that it references the same file or device, it has the same open mode (read and/or write) and it will have file position identical to the original.  Changing the position with one handle will result in a changed position in the other.
The _dup function is identical to dup.  Use _dup for ANSI naming conventions.
Returns:
If successful, the new file handle is returned to be used with the other functions which operate on the file.  Otherwise, -1 is returned and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The argument handle is not a valid open file handle.

EMFILE
The number of file handles would exceed {OPEN_MAX}.
See Also:
_chsize, close, creat, dup2, _eof, exec..., fdopen, _filelength, fileno, fstat, _grow_handles, isatty, lseek, open, read, _setmode, _sopen, stat, _tell, write, umask
Example:

#include <fcntl.h>
#include <io.h>

void main( void )
{
    int handle, dup_handle;

    handle = open( "file",
                O_WRONLY | O_CREAT | O_TRUNC | O_TEXT,
                S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( handle != -1 ) {
        dup_handle = dup( handle );
        if( dup_handle != -1 ) {

            /* process file */

            close( dup_handle );
        }
        close( handle );
    }
}
Classification:
POSIX 1003.1
_dup conforms to ANSI naming conventions
Systems:
dup - All, Linux, RDOS, Netware
_dup - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

dup2, _dup2

Synopsis:

#include <io.h>
int dup2( int handle, int handle2 );
int _dup2( int handle, int handle2 );
Description:
The dup2 function duplicates the file handle given by the argument handle.  The new file handle is identical to the original in that it references the same file or device, it has the same open mode (read and/or write) and it will have identical file position to the original (changing the position with one handle will result in a changed position in the other).
The number of the new handle is handle2.  If a file already is opened with this handle, the file is closed before the duplication is attempted.

The _dup2 function is identical to dup2.  Use _dup2 for ANSI naming conventions.
Returns:
The dup2 function returns zero if successful.  Otherwise, -1 is returned and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The argument handle is not a valid open file handle or handle2 is out of range.

EMFILE
The number of file handles would exceed {OPEN_MAX}, or no file handles above handle2 are available.
See Also:
_chsize, close, creat, dup, _eof, exec..., fdopen, _filelength, fileno, fstat, _grow_handles, isatty, lseek, open, read, _setmode, _sopen, stat, _tell, write, umask
Example:

#include <fcntl.h>
#include <io.h>

void main()
  {
    int handle, dup_handle;

    handle = open( "file",
                O_WRONLY | O_CREAT | O_TRUNC | O_TEXT,
                S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( handle != -1 ) {
      dup_handle = 4;
      if( dup2( handle, dup_handle ) != -1 ) {

        /* process file */

        close( dup_handle );
      }
      close( handle );
    }
  }
Classification:
POSIX 1003.1
_dup2 conforms to ANSI naming conventions
Systems:
dup2 - All, Linux, RDOS, Netware
_dup2 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

_dwDeleteOnClose

Synopsis:

#include <wdefwin.h>
int _dwDeleteOnClose( int handle );
Description:
The _dwDeleteOnClose function tells the console window that it should close itself when the corresponding file is closed.  The argument handle is the handle associated with the opened console.
The _dwDeleteOnClose function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwDeleteOnClose function returns 1 if it was successful and 0 if not.
See Also:
_dwSetAboutDlg, _dwSetAppTitle, _dwSetConTitle, _dwShutDown, _dwYield
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    FILE *sec;

    _dwSetAboutDlg( "Hello World About Dialog",
                    "About Hello World\n"
                    "Copyright 1994 by WATCOM\n" );
    _dwSetAppTitle( "Hello World Application Title" );
    _dwSetConTitle( 0, "Hello World Console Title" );
    printf( "Hello World\n" );
    sec = fopen( "CON", "r+" );
    _dwSetConTitle( fileno( sec ),
                    "Hello World Second Console Title" );
    _dwDeleteOnClose( fileno( sec ) );
    fprintf( sec, "Hello to second console\n" );
    fprintf( sec, "Press Enter to close this console\n" );
    fflush( sec );
    fgetc( sec );
    fclose( sec );
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

_dwSetAboutDlg

Synopsis:

#include <wdefwin.h>
int _dwSetAboutDlg( const char *title, const char *text );
Description:
The _dwSetAboutDlg function sets the "About" dialog box of the default windowing system.  The argument title points to the string that will replace the current title.  If title is NULL then the title will not be replaced.  The argument text points to a string which will be placed in the "About" box.  To get multiple lines, embed a new line after each logical line in the string.  If text is NULL, then the current text in the "About" box will not be replaced.
The _dwSetAboutDlg function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwSetAboutDlg function returns 1 if it was successful and 0 if not.
See Also:
_dwDeleteOnClose, _dwSetAppTitle, _dwSetConTitle, _dwShutDown, _dwYield
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    FILE *sec;

    _dwSetAboutDlg( "Hello World About Dialog",
                    "About Hello World\n"
                    "Copyright 1994 by WATCOM\n" );
    _dwSetAppTitle( "Hello World Application Title" );
    _dwSetConTitle( 0, "Hello World Console Title" );
    printf( "Hello World\n" );
    sec = fopen( "CON", "r+" );
    _dwSetConTitle( fileno( sec ),
                    "Hello World Second Console Title" );
    _dwDeleteOnClose( fileno( sec ) );
    fprintf( sec, "Hello to second console\n" );
    fprintf( sec, "Press Enter to close this console\n" );
    fflush( sec );
    fgetc( sec );
    fclose( sec );
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

_dwSetAppTitle

Synopsis:

#include <wdefwin.h>
int _dwSetAppTitle( const char *title );
Description:
The _dwSetAppTitle function sets the main window's title.  The argument title points to the string that will replace the current title.
The _dwSetAppTitle function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwSetAppTitle function returns 1 if it was successful and 0 if not.
See Also:
_dwDeleteOnClose, _dwSetAboutDlg, _dwSetConTitle, _dwShutDown, _dwYield
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    FILE *sec;

    _dwSetAboutDlg( "Hello World About Dialog",
                    "About Hello World\n"
                    "Copyright 1994 by WATCOM\n" );
    _dwSetAppTitle( "Hello World Application Title" );
    _dwSetConTitle( 0, "Hello World Console Title" );
    printf( "Hello World\n" );
    sec = fopen( "CON", "r+" );
    _dwSetConTitle( fileno( sec ),
                    "Hello World Second Console Title" );
    _dwDeleteOnClose( fileno( sec ) );
    fprintf( sec, "Hello to second console\n" );
    fprintf( sec, "Press Enter to close this console\n" );
    fflush( sec );
    fgetc( sec );
    fclose( sec );
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

_dwSetConTitle

Synopsis:

#include <wdefwin.h>
int _dwSetConTitle( int handle, const char *title );
Description:
The _dwSetConTitle function sets the console window's title which corresponds to the handle passed to it.  The argument handle is the handle associated with the opened console.  The argument title points to the string that will replace the current title.
The _dwSetConTitle function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwSetConTitle function returns 1 if it was successful and 0 if not.
See Also:
_dwDeleteOnClose, _dwSetAboutDlg, _dwSetAppTitle, _dwShutDown, _dwYield
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    FILE *sec;

    _dwSetAboutDlg( "Hello World About Dialog",
                    "About Hello World\n"
                    "Copyright 1994 by WATCOM\n" );
    _dwSetAppTitle( "Hello World Application Title" );
    _dwSetConTitle( 0, "Hello World Console Title" );
    printf( "Hello World\n" );
    sec = fopen( "CON", "r+" );
    _dwSetConTitle( fileno( sec ),
                    "Hello World Second Console Title" );
    _dwDeleteOnClose( fileno( sec ) );
    fprintf( sec, "Hello to second console\n" );
    fprintf( sec, "Press Enter to close this console\n" );
    fflush( sec );
    fgetc( sec );
    fclose( sec );
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

_dwShutDown

Synopsis:

#include <wdefwin.h>
int _dwShutDown( void );
Description:
The _dwShutDown function shuts down the default windowing I/O system.  The application will continue to execute but no windows will be available for output.  Care should be exercised when using this function since any subsequent output may cause unpredictable results.
When the application terminates, it will not be necessary to manually close the main window.

The _dwShutDown function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwShutDown function returns 1 if it was successful and 0 if not.
See Also:
_dwDeleteOnClose, _dwSetAboutDlg, _dwSetAppTitle, _dwSetConTitle, _dwYield
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    FILE *sec;

    _dwSetAboutDlg( "Hello World About Dialog",
                    "About Hello World\n"
                    "Copyright 1994 by WATCOM\n" );
    _dwSetAppTitle( "Hello World Application Title" );
    _dwSetConTitle( 0, "Hello World Console Title" );
    printf( "Hello World\n" );

    sec = fopen( "CON", "r+" );
    _dwSetConTitle( fileno( sec ),
                    "Hello World Second Console Title" );
    _dwDeleteOnClose( fileno( sec ) );
    fprintf( sec, "Hello to second console\n" );
    fprintf( sec, "Press Enter to close this console\n" );
    fflush( sec );
    fgetc( sec );
    fclose( sec );
    _dwShutDown();
    /*
      do more computing that does not involve
      console input/output
    */
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

_dwYield

Synopsis:

#include <wdefwin.h>
int _dwYield( void );
Description:
The _dwYield function yields control back to the operating system, thereby giving other processes a chance to run.
The _dwYield function is one of the support functions that can be called from an application using Open Watcom's default windowing support.
Returns:
The _dwYield function returns 1 if it was successful and 0 if not.
See Also:
_dwDeleteOnClose, _dwSetAboutDlg, _dwSetAppTitle, _dwSetConTitle, _dwShutDown
Example:

#include <wdefwin.h>
#include <stdio.h>

void main()
  {
    int i;

    for( i = 0; i < 1000; i++ ) {
      /* give other processes a chance to run */
      _dwYield();
      /* do CPU-intensive calculation */
      /*  .  */
      /*  .  */
      /*  .  */
    }
  }
Classification:
WATCOM
Systems:
Windows, Win386, Win32, OS/2-32

ecvt, _ecvt, _wecvt

Synopsis:

#include <stdlib.h>
char *ecvt( double value,
            int ndigits,
            int *dec,
            int *sign );
char *_ecvt( double value,
             int ndigits,
             int *dec,
             int *sign );
wchar_t *_wecvt( double value,
                 int ndigits,
                 int *dec,
                 int *sign );
Description:
The ecvt function converts the floating-point number value into a character string.  The parameter ndigits specifies the number of significant digits desired.  The converted number will be rounded to ndigits of precision.
The character string will contain only digits and is terminated by a null character.  The integer pointed to by dec will be filled in with a value indicating the position of the decimal point relative to the start of the string of digits.  A zero or negative value indicates that the decimal point lies to the left of the first digit.  The integer pointed to by sign will contain 0 if the number is positive, and non-zero if the number is negative.

The _ecvt function is identical to ecvt.  Use _ecvt for ANSI naming conventions.

The _wecvt function is a wide character version of ecvt except that it produces a wide character string.
Returns:
The ecvt function returns a pointer to a static buffer containing the converted string of digits.  Note:   ecvt and fcvt both use the same static buffer.
See Also:
fcvt, gcvt, printf
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
     char *str;
     int  dec, sign;

     str = ecvt( 123.456789, 6, &dec, &sign );
     printf( "str=%s, dec=%d, sign=%d\n", str,dec,sign );
  }

produces the following:

str=123457, dec=3, sign=0
Classification:
WATCOM
_ecvt conforms to ANSI naming conventions
Systems:
ecvt - Math
_ecvt - Math
_wecvt - Math

_ellipse, _ellipse_w, _ellipse_wxy

Synopsis:

#include <graph.h>
short _FAR _ellipse( short fill, short x1, short y1,
                                  short x2, short y2 );

short _FAR _ellipse_w( short fill, double x1, double y1,
                                    double x2, double y2 );

short _FAR _ellipse_wxy( short fill,
                          struct _wxycoord _FAR *p1,
                          struct _wxycoord _FAR *p2 );
Description:
The _ellipse functions draw ellipses.  The _ellipse function uses the view coordinate system.  The _ellipse_w and _ellipse_wxy functions use the window coordinate system.
The center of the ellipse is the center of the rectangle established by the points (x1,y1) and (x2,y2).

The argument fill determines whether the ellipse is filled in or has only its outline drawn.  The argument can have one of two values:
_GFILLINTERIOR
fill the interior by writing pixels with the current plot action using the current color and the current fill mask

_GBORDER
leave the interior unchanged; draw the outline of the figure with the current plot action using the current color and line style

When the coordinates (x1,y1) and (x2,y2) establish a line or a point (this happens when one or more of the x-coordinates or y-coordinates are equal), nothing is drawn.
Returns:
The _ellipse functions return a non-zero value when the ellipse was successfully drawn; otherwise, zero is returned.
See Also:
_arc, _rectangle, _setcolor, _setfillmask, _setlinestyle, _setplotaction
Example:

#include <conio.h>
#include <graph.h>

main()
{
    _setvideomode( _VRES16COLOR );
    _ellipse( _GBORDER, 120, 90, 520, 390 );
    getch();
    _setvideomode( _DEFAULTMODE );
}

produces the following:

Classification:
PC Graphics
Systems:
_ellipse - DOS
_ellipse_w - DOS
_ellipse_wxy - DOS

_enable

Synopsis:

#include <i86.h>
void _enable( void );
Description:
The _enable function causes interrupts to become enabled.
The _enable function would be used in conjunction with the _disable function to make sure that a sequence of instructions are executed without any intervening interrupts occurring.
Returns:
The _enable function returns no value.
See Also:
_disable
Example:

#include <stdio.h>
#include <stdlib.h>
#include <i86.h>

struct list_entry {
    struct list_entry *next;
    int               data;
};
struct list_entry *ListHead = NULL;
struct list_entry *ListTail = NULL;

void insert( struct list_entry *new_entry )
  {
    /* insert new_entry at end of linked list */
    new_entry->next = NULL;
    _disable();       /* disable interrupts */
    if( ListTail == NULL ) {
      ListHead = new_entry;
    } else {
      ListTail->next = new_entry;
    }
    ListTail = new_entry;
    _enable();        /* enable interrupts now */
  }

void main()
  {
    struct list_entry *p;
    int i;

    for( i = 1; i <= 10; i++ ) {
      p = (struct list_entry *)
          malloc( sizeof( struct list_entry ) );
      if( p == NULL ) break;
      p->data = i;
      insert( p );
    }
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

endhostent

Synopsis:

#include <netdb.h>
void endhostent( void );
Description:
The endhostent function closes the network host database at /etc/hosts.  If the network host database is not open, this call results in no actions.
See Also:
gethostent, sethostent
Classification:
POSIX 1003.1
Systems:
Linux

endnetent

Synopsis:

#include <netdb.h>
void endnetent( void );
Description:
The endnetent function closes the network database.
This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
See Also:
getnetent, setnetent, getnetbyname, getnetbyaddr
Classification:
POSIX 1003.1
Systems:
Linux

endprotoent

Synopsis:

#include <netdb.h>
void endprotoent( void );
Description:
The endprotoent function explicitly closes the protocol database.
This function is not thread-safe.  Other calls to this function or to other functions accessing the protocol database may affect the return value from this function.
See Also:
getprotoent, setprotoent, getprotobyname, getprotobynumber
Classification:
POSIX 1003.1
Systems:
Linux

endpwent

Synopsis:

#include <pwd.h>
void endpwent( void );
Description:
The endpwent function closes the system's password database after calls to getpwent are complete.
See Also:
setpwent, getpwent, getpwnam, getpwuid
Example:

The following program will print out each user and their user ID in the system's password database

#include <stdio.h>
#include <pwd.h>

void main()
  {
    struct passwd *pw;

    setpwent();

    while((pw = getpwent()) != NULL) {
        printf("User id %d is %s\n", (int)pw->pw_uid, pw->pw_name);
    }

    endpwent();
  }
Classification:
POSIX 1003.1
Systems:
Linux

endservent

Synopsis:

#include <netdb.h>
void endservent( void );
Description:
The endservent function closes the service database.
This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
See Also:
getservent, setservent, getservbyname, getservbyport
Classification:
POSIX 1003.1
Systems:
Linux

_endthread, _endthreadex

Synopsis:

#include <process.h>
void _endthread(void);
void _endthreadex( unsigned retval );
Description:
The _endthread function is used to terminate a thread created by _beginthread.  For each operating environment under which _endthread is supported, the _endthread function uses the appropriate system call to end the current thread of execution.
The _endthreadex function is used to terminate a thread created by _beginthreadex.   The thread exit code retval must be specified.
Returns:
The _endthread function does not return any value.
See Also:
_beginthread
Example:

#include <stdio.h>
#include <stdlib.h>
#include <stddef.h>
#include <malloc.h>
#include <process.h>
#include <dos.h>

#if defined(__386__)
  #define FAR
  #define STACK_SIZE    8192
#else
  #define FAR           __far
  #define STACK_SIZE    4096
#endif

static volatile int     WaitForThread;

void FAR child( void FAR *parm )
  {
    char * FAR *argv = (char * FAR *) parm;
    int  i;

    printf( "Child thread ID = %x\n", *_threadid );
    for( i = 0; argv[i]; i++ ) {
      printf( "argv[%d] = %s\n", i, argv[i] );
    }
    WaitForThread = 0;
    _endthread();
  }

void main()
  {
    char           *args[3];
#if defined(__NT__)
    unsigned long   tid;
#else
    char           *stack;
    int             tid;
#endif

    args[0] = "child";
    args[1] = "parm";
    args[2] = NULL;
    WaitForThread = 1;
#if defined(__NT__)
    tid = _beginthread( child, STACK_SIZE, args );
    printf( "Thread handle = %lx\n", tid );
#else
  #if defined(__386__)
    stack = (char *) malloc( STACK_SIZE );
  #else
    stack = (char *) _nmalloc( STACK_SIZE );
  #endif
    tid = _beginthread( child, stack, STACK_SIZE, args );
    printf( "Thread ID = %x\n", tid );
#endif
    while( WaitForThread ) {
        sleep( 0 );
    }
  }
Classification:
WATCOM
Systems:
_endthread - Win32, OS/2 1.x(MT), OS/2 1.x(DL), OS/2-32, Linux, RDOS, Netware
_endthreadex - Win32

_eof, eof

Synopsis:

#include <io.h>
int _eof( int handle );

** deprecated **
int eof( int handle );
Description:
The _eof function determines, at the operating system level, if the end of the file has been reached for the file whose file handle is given by handle.  Because the current file position is set following an input operation, the _eof function may be called to detect the end of the file before an input operation beyond the end of the file is attempted.
The eof function is deprecated, use _eof instead.
Returns:
The _eof function returns 1 if the current file position is at the end of the file, 0 if the current file position is not at the end.  A return value of -1 indicates an error, and in this case errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
EBADF
The handle argument is not a valid file handle.
See Also:
read
Example:

#include <stdio.h>
#include <fcntl.h>
#include <io.h>

void main( void )
{
    int handle, len;
    char buffer[100];

    handle = open( "file", O_RDONLY );
    if( handle != -1 ) {
        while( ! _eof( handle ) ) {
            len = read( handle, buffer, sizeof(buffer) - 1 );
            buffer[ len ] = '\0';
            printf( "%s", buffer );
        }
        close( handle );
    }
}
Classification:
WATCOM
Systems:
_eof - All, Linux, RDOS, Netware
eof - All, Linux, RDOS, Netware

erf

Synopsis:

#include <math.h>
double erf( double x );
Description:
The erf function computes the value of the error function, also known as the Gauss error function, for the argument x.
Returns:
For non-infinite values of x the function returns the value of the error function.  For positive infinity or negative infinity the function returns positive or negative one respectively.  For not-a-number the function returns NAN.
See Also:
erfc
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", erf( 0.0 ) );
  }

produces the following:

0.000000
Classification:
ISO C99
Systems:
Math

erfc

Synopsis:

#include <math.h>
double erfc( double x );
Description:
The erfc function computes the value of the complementary error function, also known as the Gauss error function, for the argument x.
Returns:
For non-infinite values of x the function returns the value of the error function.  For positive infinity or negative infinity the function returns negative or positive one respectively.  For not-a-number the function returns NAN.
See Also:
erf
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", erfc( 0.0 ) );
  }

produces the following:

0.000000
Classification:
WATCOM
Systems:
Math

exec...  Functions

Synopsis:

#include <process.h>
int execl(   path, arg0, arg1..., argn, NULL );
int execle(  path, arg0, arg1..., argn, NULL, envp );
int execlp(  file, arg0, arg1..., argn, NULL );
int execlpe( file, arg0, arg1..., argn, NULL, envp );
int execv(   path, argv );
int execve(  path, argv, envp );
int execvp(  file, argv );
int execvpe( file, argv, envp );
int _execl(   path, arg0, arg1..., argn, NULL );
int _execle(  path, arg0, arg1..., argn, NULL, envp );
int _execlp(  file, arg0, arg1..., argn, NULL );
int _execlpe( file, arg0, arg1..., argn, NULL, envp );
int _execv(   path, argv );
int _execve(  path, argv, envp );
int _execvp(  file, argv );
int _execvpe( file, argv, envp );
  const char *path;             /* file name incl. path */
  const char *file;             /* file name             */
  const char *arg0, ..., *argn; /* arguments            */
  const char *const argv[];     /* array of arguments   */
  const char *const envp[];     /* environment strings  */
int _wexecl(   path, arg0, arg1..., argn, NULL );
int _wexecle(  path, arg0, arg1..., argn, NULL, envp );
int _wexeclp(  file, arg0, arg1..., argn, NULL );
int _wexeclpe( file, arg0, arg1..., argn, NULL, envp );
int _wexecv(   path, argv );
int _wexecve(  path, argv, envp );
int _wexecvp(  file, argv );
int _wexecvpe( file, argv, envp );
  const wchar_t *path;            /* file name incl. path */
  const wchar_t *file;            /* file name             */
  const wchar_t *arg0, ..., *argn;/* arguments            */
  const wchar_t *const argv[];    /* array of arguments   */
  const wchar_t *const envp[];    /* environment strings  */
Description:
The exec...  functions load and execute a new child process, named by path or file.  If the child process is successfully loaded, it replaces the current process in memory.  No return is made to the original program.
The program is located by using the following logic in sequence:
  1. An attempt is made to locate the program in the current working directory if no directory specification precedes the program name; otherwise, an attempt is made in the specified directory.
  2. If no file extension is given, an attempt is made to find the program name, in the directory indicated in the first point, with .COM concatenated to the end of the program name.
  3. If no file extension is given, an attempt is made to find the program name, in the directory indicated in the first point, with .EXE concatenated to the end of the program name.
  4. When no directory specification is given as part of the program name, the execlp, execlpe, execvp, and execvpe functions will repeat the preceding three steps for each of the directories specified by the PATH environment variable.  The command

         
         path c:\myapps;d:\lib\applns

    indicates that the two directories

         
         c:\myapps
         d:\lib\applns

    are to be searched.  The DOS PATH command (without any directory specification) will cause the current path definition to be displayed.

An error is detected when the program cannot be found.

Arguments are passed to the child process by supplying one or more pointers to character strings as arguments in the exec...  call.  These character strings are concatenated with spaces inserted to separate the arguments to form one argument string for the child process.  The length of this concatenated string must not exceed 128 bytes for DOS systems.

The arguments may be passed as a list of arguments (execl, execle, execlp, and execlpe) or as a vector of pointers (execv, execve, execvp, and execvpe).  At least one argument, arg0 or argv[0], must be passed to the child process.  By convention, this first argument is a pointer to the name of the program.

If the arguments are passed as a list, there must be a NULL pointer to mark the end of the argument list.   Similarly, if a pointer to an argument vector is passed, the argument vector must be terminated by a NULL pointer.

The environment for the invoked program is inherited from the parent process when you use the execl, execlp, execv, and execvp functions.  The execle, execlpe, execve, and execvpe functions allow a different environment to be passed to the child process through the envp argument.  The argument envp is a pointer to an array of character pointers, each of which points to a string defining an environment variable.  The array is terminated with a NULL pointer.  Each pointer locates a character string of the form

     
         variable=value

that is used to define an environment variable.  If the value of envp is NULL, then the child process inherits the environment of the parent process.

The environment is the collection of environment variables whose values have been defined with the DOS SET command or by the successful execution of the putenv function.  A program may read these values with the getenv function.

The execvpe and execlpe functions are extensions to POSIX 1003.1.

The _wexec...  functions are similar to their counterparts but operate on wide character strings.
Returns:
When the invoked program is successfully initiated, no return occurs.  When an error is detected while invoking the indicated program, exec...  returns -1 and errno is set to indicate the error.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
E2BIG
The argument list exceeds 128 bytes, or the space required for the environment information exceeds 32K.

EACCES
The specified file has a locking or sharing violation.

EMFILE
Too many files open

ENOENT
Path or file not found

ENOMEM
Not enough memory is available to execute the child process.
See Also:
abort, atexit, exit, _Exit, _exit, getcmd, getenv, main, putenv, spawn..., system
Example:

#include <stddef.h>
#include <process.h>

execl( "myprog",
        "myprog", "ARG1", "ARG2", NULL );

The preceding invokes "myprog" as if

    myprog ARG1 ARG2

had been entered as a command to DOS.  The program will be found if one of

    myprog.
    myprog.com
    myprog.exe

is found in the current working directory.

#include <stddef.h>
#include <process.h>

char *env_list[] = { "SOURCE=MYDATA",
                      "TARGET=OUTPUT",
                      "lines=65",
                      NULL
                    };

execle( "myprog",
        "myprog", "ARG1", "ARG2", NULL,
         env_list );

The preceding invokes "myprog" as if

    myprog ARG1 ARG2
had been entered as a command to DOS.  The program will be found if one of

    myprog.
    myprog.com
    myprog.exe

is found in the current working directory.  The DOS environment for the invoked program will consist of the three environment variables SOURCE, TARGET and lines.

#include <stddef.h>
#include <process.h>

char *arg_list[] = { "myprog", "ARG1", "ARG2", NULL };

execv( "myprog", arg_list );

The preceding invokes "myprog" as if

    myprog ARG1 ARG2

had been entered as a command to DOS.  The program will be found if one of

    myprog.
    myprog.com
    myprog.exe

is found in the current working directory.
Classification:
POSIX 1003.1 with extensions
execle is WATCOM
execlp is WATCOM
execlpe is WATCOM
execv is WATCOM
execve is WATCOM
execvp is WATCOM
execvpe is WATCOM
_execl is WATCOM
_execle is WATCOM
_execlp is WATCOM
_execlpe is WATCOM
_execv is WATCOM
_execve is WATCOM
_execvp is WATCOM
_execvpe is WATCOM
_wexecl is WATCOM
_wexecle is WATCOM
_wexeclp is WATCOM
_wexeclpe is WATCOM
_wexecv is WATCOM
_wexecve is WATCOM
_wexecvp is WATCOM
_wexecvpe is WATCOM
Systems:
execl - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execle - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execlp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execlpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execv - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execve - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execvp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
execvpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execl - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execle - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execlp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execlpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execv - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execve - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execvp - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_execvpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS
_wexecl - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexecle - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexeclp - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexeclpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexecv - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexecve - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexecvp - DOS/16, Win32, OS/2 1.x(all), OS/2-32
_wexecvpe - DOS/16, Win32, OS/2 1.x(all), OS/2-32

_Exit, _exit

Synopsis:

#include <stdlib.h>
void _Exit( int status );
void _exit( int status );
Description:
The _Exit function causes normal program termination to occur.
  1. The functions registered by the atexit or _onexit functions are not called.
  2. Any unopened files are not closed and any buffered output is not flushed to the associated files or devices.
  3. Any files created by tmpfile are not removed.
  4. The return status is made available to the parent process.  Only the low order byte of status is available on DOS systems.  The status value is typically set to 0 to indicate successful termination and set to some other value to indicate an error.

The _exit is functionaly equivalent to _Exit.
Returns:
The _Exit function does not return to its caller.
See Also:
abort, atexit, _bgetcmd, exec..., exit, _exit, getcmd, getenv, main, putenv, spawn..., system, _wsystem
Example:

#include <stdio.h>
#include <stdlib.h>

void main( int argc, char *argv[] )
{
    FILE *fp;

    if( argc <= 1 ) {
        fprintf( stderr, "Missing argument\n" );
        exit( EXIT_FAILURE );
    }

    fp = fopen( argv[1], "r" );
    if( fp == NULL ) {
        fprintf( stderr, "Unable to open '%s'\n", argv[1] );
        _Exit( EXIT_FAILURE );
    }
    fclose( fp );
    _Exit( EXIT_SUCCESS );
}
Classification:
ISO C99
_exit is POSIX 1003.1
Systems:
_Exit - All, Linux, RDOS, Netware
_exit - All, Linux, RDOS, Netware

exit

Synopsis:

#include <stdlib.h>
void exit( int status );
Description:
The exit function causes normal program termination to occur.
First, all functions registered by the atexit function are called in the reverse order of their registration.  Next, all open files are flushed and closed, and all files created by the tmpfile function are removed.  Finally, the return status is made available to the parent process.  Only the low order byte of status is available on DOS systems.  The status value is typically set to 0 to indicate successful termination and set to some other value to indicate an error.
Returns:
The exit function does not return to its caller.
See Also:
abort, atexit, _Exit, _exit
Example:

#include <stdio.h>
#include <stdlib.h>

void main( int argc, char *argv[] )
  {
    FILE *fp;

    if( argc <= 1 ) {
      fprintf( stderr, "Missing argument\n" );
      exit( EXIT_FAILURE );
    }

    fp = fopen( argv[1], "r" );
    if( fp == NULL ) {
      fprintf( stderr, "Unable to open '%s'\n", argv[1] );
      exit( EXIT_FAILURE );
    }
    fclose( fp );
    exit( EXIT_SUCCESS );
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

exp

Synopsis:

#include <math.h>
double exp( double x );
Description:
The exp function computes the exponential function of x.  A range error occurs if the magnitude of x is too large.
Returns:
The exp function returns the exponential value.  When the argument is outside the permissible range, the matherr function is called.  Unless the default matherr function is replaced, it will set the global variable errno to ERANGE, and print a "RANGE error" diagnostic message using the stderr stream.
See Also:
log, matherr
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", exp(.5) );
  }

produces the following:

1.648721
Classification:
ISO C
Systems:
Math

exp2

Synopsis:

#include <math.h>
double exp2( double x );
Description:
The exp2 function computes 2.0 raised to the value x.  calculation.
Returns:
The function returns two to the power x.
See Also:
exp, pow
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", exp2( 2.0 ) );
  }

produces the following:

4.000000
Classification:
ISO C99
Systems:
Math

expm1

Synopsis:

#include <math.h>
double expm1( double x );
Description:
The expm1 function computes the value of the exponential of x minus 1.  This routine provides far better accuracy for cases where the exponential of the argument x is significantly less than 1.0.
Returns:
The function returns a the exponential of x minus 1 without loss of accuracy due to subtractive cancelation.
See Also:
exp
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", expm1( -1.0E-3 ) );
  }

produces the following:

-0.000995
Classification:
ISO C99
Systems:
Math

_expand Functions

Synopsis:

#include <malloc.h>
void        *_expand( void *mem_blk, size_t size );
void __based(void) *_bexpand( __segment seg,
                               void __based(void) *mem_blk,
                               size_t size );
void __far  *_fexpand(void __far  *mem_blk,size_t size);
void __near *_nexpand(void __near *mem_blk,size_t size);
Description:
The _expand functions change the size of the previously allocated block pointed to by mem_blk by attempting to expand or contract the memory block without moving its location in the heap.  The argument size specifies the new desired size for the memory block.  The contents of the memory block are unchanged up to the shorter of the new and old sizes.
Each function expands the memory from a particular heap, as listed below:
Function     Heap Expanded
_expand
Depends on data model of the program

_bexpand
Based heap specified by seg value

_fexpand
Far heap (outside the default data segment)

_nexpand
Near heap (inside the default data segment)

In a small data memory model, the _expand function is equivalent to the _nexpand function; in a large data memory model, the _expand function is equivalent to the _fexpand function.
Returns:
The _expand functions return the value mem_blk if it was successful in changing the size of the block.  The return value is NULL (_NULLOFF for _bexpand) if the memory block could not be expanded to the desired size.  It will be expanded as much as possible in this case.
The appropriate _msize function can be used to determine the new size of the expanded block.
See Also:
calloc Functions, free Functions, halloc, hfree, malloc Functions, _msize Functions, realloc Functions, sbrk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    char *buf;
    char __far *buf2;

    buf = (char *) malloc( 80 );
    printf( "Size of buffer is %u\n", _msize(buf) );
    if( _expand( buf, 100 ) == NULL ) {
        printf( "Unable to expand buffer\n" );
    }
    printf( "New size of buffer is %u\n", _msize(buf) );
    buf2 = (char __far *) _fmalloc( 2000 );
    printf( "Size of far buffer is %u\n", _fmsize(buf2) );
    if( _fexpand( buf2, 8000 ) == NULL ) {
        printf( "Unable to expand far buffer\n" );
    }
    printf( "New size of far buffer is %u\n",
             _fmsize(buf2) );
  }

produces the following:

Size of buffer is 80
Unable to expand buffer
New size of buffer is 80
Size of far buffer is 2000
New size of far buffer is 8000
Classification:
WATCOM
Systems:
_expand - All, Linux, RDOS
_bexpand - DOS/16, Windows, OS/2 1.x(all)
_fexpand - DOS/16, Windows, OS/2 1.x(all)
_nexpand - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

fabs

Synopsis:

#include <math.h>
double fabs( double x );
Description:
The fabs function computes the absolute value of the argument x.
Returns:
The fabs function returns the absolute value of x.
See Also:
abs, labs, imaxabs
Example:

#include <stdio.h>
#include <math.h>

void main()
{
    printf( "%f %f\n", fabs(.5), fabs(-.5) );
}

produces the following:

0.500000 0.500000
Classification:
ISO C
Systems:
Math

fclose

Synopsis:

#include <stdio.h>
int fclose( FILE *fp );
Description:
The fclose function closes the file fp.  If there was any unwritten buffered data for the file, it is written out before the file is closed.  Any unread buffered data is discarded.  If the associated buffer was automatically allocated, it is deallocated.
Returns:
The fclose function returns zero if the file was successfully closed, or non-zero if any errors were detected.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fcloseall, fdopen, fopen, freopen, _fsopen
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;

    fp = fopen( "stdio.h", "r" );
    if( fp != NULL ) {
        fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

fcloseall

Synopsis:

#include <stdio.h>
int fcloseall( void );
Description:
The fcloseall function closes all open stream files, except stdin, stdout, stderr, stdaux, and stdprn.  This includes streams created (and not yet closed) by fdopen, fopen and freopen.  The stdaux and stdprn files are not available for some Windows platforms.
Returns:
The fcloseall function returns the number of streams that were closed if no errors were encountered.  When an error occurs, EOF is returned.
See Also:
fclose, fdopen, fopen, freopen, _fsopen
Example:

#include <stdio.h>

void main()
  {
    printf( "The number of files closed is %d\n",
            fcloseall() );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

fcvt, _fcvt, _wfcvt

Synopsis:

#include <stdlib.h>
char *fcvt( double value,
            int ndigits,
            int *dec,
            int *sign );
char *_fcvt( double value,
             int ndigits,
             int *dec,
             int *sign );
wchar_t *_wfcvt( double value,
                 int ndigits,
                 int *dec,
                 int *sign );
Description:
The fcvt function converts the floating-point number value into a character string.  The parameter ndigits specifies the number of digits desired after the decimal point.  The converted number will be rounded to this position.
The character string will contain only digits and is terminated by a null character.  The integer pointed to by dec will be filled in with a value indicating the position of the decimal point relative to the start of the string of digits.  A zero or negative value indicates that the decimal point lies to the left of the first digit.  The integer pointed to by sign will contain 0 if the number is positive, and non-zero if the number is negative.

The _fcvt function is identical to fcvt.  Use _fcvt for ANSI naming conventions.

The _wfcvt function is a wide character version of fcvt except that it produces a wide character string.
Returns:
The fcvt function returns a pointer to a static buffer containing the converted string of digits.  Note:  ecvt and fcvt both use the same static buffer.
See Also:
ecvt, gcvt, printf
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
     char *str;
     int  dec, sign;

     str = fcvt( -123.456789, 5, &dec, &sign );
     printf( "str=%s, dec=%d, sign=%d\n", str,dec,sign );
  }

produces the following:

str=12345679, dec=3, sign=-1
Classification:
WATCOM
_fcvt conforms to ANSI naming conventions
Systems:
fcvt - Math
_fcvt - Math
_wfcvt - Math

fdim

Synopsis:

#include <math.h>
double fdim( double x, double y );
Description:
The fdim function computes the positive difference of x and y.
fmax( x - y, 0.0 );
Returns:
The routine will either return x - y or 0.0, whichever is greater.
See Also:
fmax, fmin
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", fdim( 3.0, 2.0 ) );
  }

produces the following:

1.000000
Classification:
ISO C99
Systems:
Math

fdopen, _fdopen, _wfdopen

Synopsis:

#include <stdio.h>
FILE *fdopen( int handle, const char *mode );
FILE *_fdopen( int handle, const char *mode );
FILE *_wfdopen( int handle, const wchar_t *mode );
Description:
The fdopen function associates a stream with the file handle handle which represents an opened file or device.   The handle was returned by one of creat, dup, dup2, open, or _sopen.  The open mode mode must match the mode with which the file or device was originally opened.
The argument mode is described in the description of the fopen function.

The _fdopen function is identical to fdopen.  Use _fdopen for ANSI naming conventions.

The _wfdopen function is identical to fdopen except that it accepts a wide character string for the second argument.
Returns:
The fdopen function returns a pointer to the object controlling the stream.  This pointer must be passed as a parameter to subsequent functions for performing operations on the file.  If the open operation fails, fdopen returns a NULL pointer.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
creat, _dos_open, dup, dup2, fopen, freopen, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>
#include <fcntl.h>
#include <io.h>

void main()
  {
    int handle;
    FILE *fp;

    handle = open( "file", O_RDONLY | O_TEXT );
    if( handle != -1 ) {
      fp = fdopen( handle, "r" );
      if( fp != NULL ) {
        /*
            process the stream
        */
        fclose( fp );
      } else {
        close( handle );
      }
    }
  }
Classification:
POSIX 1003.1
_fdopen conforms to ANSI naming conventions
_wfdopen is WATCOM
Systems:
fdopen - All, Linux, RDOS, Netware
_fdopen - All, Linux, RDOS, Netware
_wfdopen - All, Linux

feclearexcept

Synopsis:

#include <fenv.h>
int feclearexcept( int excepts );
Description:
The feclearexcept function attempts to clear the floating-point exceptions specified by the excepts argument.
For valid exception values see fegetexceptflag.
Returns:
The feclearexcept function returns zero if the excepts argument is zero or if all the specified exceptions were successfully cleared.  Otherwise, it returns a nonzero value.
See Also:
fegetexceptflag, feraiseexcept, fesetexceptflag, fetestexcept
Example:

#include <fenv.h>

void main( void )
{
    feclearexcept( FE_OVERFLOW|FE_UNDERFLOW );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fedisableexcept, __fedisableexcept

Synopsis:

#include <fenv.h>
void fedisableexcept( int excepts );
void __fedisableexcept( int excepts );
Description:
The fedisableexcept function disables the floating point exceptions specified by the excepts argument.
For valid exception values see fegetexceptflag.
Returns:
No value is returned.
See Also:
feenableexcept
Example:

#include <fenv.h>

void main( void )
{
    fedisableexcept( FE_DIVBYZERO );
}
Classification:
WATCOM
Systems:
fedisableexcept - All, Linux, RDOS, Netware
__fedisableexcept - All, Linux, RDOS, Netware

feenableexcept, __feenableexcept

Synopsis:

#include <fenv.h>
void feenableexcept( int excepts );
void __feenableexcept( int excepts );
Description:
The feenableexcept function enables the floating point exceptions specified by the excepts argument.
For valid exception values see fegetexceptflag.
Returns:
No value is returned.
See Also:
fedisableexcept
Example:

#include <fenv.h>

void main( void )
{
    feenableexcept( FE_DIVBYZERO );
}
Classification:
WATCOM
Systems:
feenableexcept - All, Linux, RDOS, Netware
__feenableexcept - All, Linux, RDOS, Netware

fegetenv

Synopsis:

#include <fenv.h>
int fegetenv( fenv_t *envp );
Description:
The fegetenv function attempts to store the current floating-point environment in the object pointed to by envp argument.
Returns:
The fegetenv function returns zero if the environment was successfully stored.  Otherwise, it returns a nonzero value.
See Also:
feholdexcept, fesetenv, feupdateenv
Example:

#include <stdio.h>
#include <fenv.h>

void main( void )
{
    fenv_t env;
    fegetenv( &env );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fegetexceptflag

Synopsis:

#include <fenv.h>
int fegetexceptflag( fexcept_t *flagp, int excepts );
Description:
The fegetexceptflag function attempts to store a representation of the floating-point exceptions specified by the excepts argument into the fexcept_t object pointed by the flagp argument.
Valid exception bit values are
FE_INVALID
At least one of the arguments is a value for which the function is not defined.

FE_DENORMAL
The result is not normalized.

FE_DIVBYZERO
Division by zero.

FE_OVERFLOW
The result is too large in magnitude to be represented as the return type.

FE_UNDERFLOW
The result is too small in magnitude to be represented as the return type.

FE_INEXACT
The result is not exact.

FE_ALL_EXCEPT
Is the logical OR of all exceptions.
Returns:
The fegetexceptflag function returns zero if the representation was successfully stored.  Otherwise, it returns a nonzero value.
See Also:
feclearexcept, feraiseexcept, fesetexceptflag, fetestexcept
Example:

#include <fenv.h>

void main( void )
{
    fexcept_t flags;
    fegetexceptflag( &flags, FE_DIVBYZERO );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fegetround

Synopsis:

#include <fenv.h>
int fegetround( void );
Description:
The fegetround function returns a value that indicates the rounding direction mode, as specified in the current floating point environment.
Returns:
The fegetround function returns the value of the rounding direction macro representing the current rounding direction or a negative value if there is no such rounding direction macro or the current rounding direction is not determinable.
For valid rounding modes see fesetround.
See Also:
fesetround
Example:

#include <stdio.h>
#include <fenv.h>

void main( void )
{
    int mode;
    mode = fegetround();
    if ( mode == FE_TONEAREST )
        printf( "Nearest\n" );
    else if ( mode == FE_DOWNWARD )
        printf( "Down\n" );
    else if ( mode == FE_TOWARDZERO )
        printf( "To Zero\n" );
    else if ( mode == FE_UPWARD )
        printf( "Up\n" );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

feholdexcept

Synopsis:

#include <fenv.h>
int feholdexcept( fenv_t *envp );
Description:
The feholdexcept function saves the current floating-point environment in the object pointed to by envp argument, clears the floating-point status flags, and then installs a non-stop (continue on floating-point exceptions) mode, if available, for all floating-point exceptions.
Returns:
The feholdexcept function returns zero if and only if non-stop floating-point exception handling was successfully installed.
See Also:
fegetenv, fesetenv, feupdateenv
Example:

#include <fenv.h>

void main( void )
{
    fenv_t env;
    feholdexcept( &env );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

feof

Synopsis:

#include <stdio.h>
int feof( FILE *fp );
Description:
The feof function tests the end-of-file indicator for the stream pointed to by fp.  Because this indicator is set when an input operation attempts to read past the end of the file the feof function will detect the end of the file only after an attempt is made to read beyond the end of the file.  Thus, if a file contains 10 lines, the feof will not detect end of file after the tenth line is read; it will detect end of file once the program attempts to read more data.
Returns:
The feof function returns non-zero if the end-of-file indicator is set for fp.
See Also:
clearerr, ferror, fopen, freopen, perror, read, strerror
Example:

#include <stdio.h>

void process_record( char *buf )
  {
    printf( "%s\n", buf );
  }

void main()
  {
    FILE *fp;
    char buffer[100];

    fp = fopen( "file", "r" );
    fgets( buffer, sizeof( buffer ), fp );
    while( ! feof( fp ) ) {
      process_record( buffer );
      fgets( buffer, sizeof( buffer ), fp );
    }
    fclose( fp );
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

feraiseexcept

Synopsis:

#include <fenv.h>
int feraiseexcept( int excepts );
Description:
The feraiseexcept function attempts to raise the floating-point exceptions specified by the excepts argument.
For valid exception values see fegetexceptflag.
Returns:
The feraiseexcept function returns zero if the excepts argument is zero or if all the specified exceptions were successfully raised.  Otherwise, it returns a nonzero value.
See Also:
feclearexcept, fegetexceptflag, fetestexcept
Example:

#include <fenv.h>

void main( void )
{
    feraiseexcept( FE_DIVBYZERO );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

ferror

Synopsis:

#include <stdio.h>
int ferror( FILE *fp );
Description:
The ferror function tests the error indicator for the stream pointed to by fp.
Returns:
The ferror function returns non-zero if the error indicator is set for fp.
See Also:
clearerr, feof, perror, strerror
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      c = fgetc( fp );
      if( ferror( fp ) ) {
        printf( "Error reading file\n" );
      }
    }
    fclose( fp );
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

fesetenv

Synopsis:

#include <fenv.h>
int fesetenv( const fenv_t *envp );
Description:
The fesetenv function attempts to establish the floating-point environment to environment represented by the object pointed by envp argument.  The envp argument shall point to an object set by a call to fegetenv or feholdexcept, or equal the FE_DFL_ENV macro.  Note that fesetenv merely installs the state of the floating-point status flags represented through its argument, and does not raise these floating-point exceptions.
Returns:
The fesetenv function returns zero if the environment was successfully established.  Otherwise, it returns a nonzero value.
See Also:
fegetenv, feholdexcept, feupdateenv
Example:

#include <fenv.h>

void main( void )
{
    fenv_t env;
    fegetenv( &env );
    fesetenv( FE_DFL_ENV );
    fesetenv( &env );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fesetexceptflag

Synopsis:

#include <fenv.h>
int fesetexceptflag( const fexcept_t *flagp, int excepts );
Description:
The fesetexceptflag function attempts to set the exceptions indicated by excepts argument with the states stored in the object pointed by flagp argument.  The value pointed by the flagp argument shall have been set by a previous call to fegetexceptflag whose second argument represented at least those floating-point exceptions represented by the excepts argument.  This function does not raise floating-point exceptions, but only sets the state of the flags.
For valid exception values see fegetexceptflag.
Returns:
The fesetexceptflag function returns zero if the excepts argument is zero or if all the specified flags were successfully set to the appropriate state.  Otherwise, it returns a nonzero value.
See Also:
feclearexcept, fegetexceptflag, feraiseexcept, fetestexcept
Example:

#include <fenv.h>

void main( void )
{
    fexcept_t flags;
    fgetexceptflag( &flags, FE_DENORMAL|FE_INVALID );
    fsetexceptflag( &flags, FE_INVALID );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fesetround

Synopsis:

#include <fenv.h>
int fesetround( int mode );
Description:
The fesetround function sets the rounding direction mode, specified by mode, for the current floating point environment.
The rounding direction mode can be one of the following values:
FE_TONEAREST
Round to nearest integer, halfway rounding away from zero

FE_DOWNWARD
Round downward to the next lowest integer

FE_TOWARDZERO
Round to the nearest integer in the direction of zero

FE_UPWARD
Round upward to the next highest integer
Returns:
The fesetround function returns a zero value if and only if the requested rounding direction was established.
See Also:
fegetround, nearbyint, rint
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    fesetround(FE_DOWNWARD)
    printf( "%f\n", rint( 1.5 ) );
    fesetround(FE_UPWARD)
    printf( "%f\n", rint( 1.5 ) );
  }

produces the following:

1.00000
2.00000
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fetestexcept

Synopsis:

#include <fenv.h>
int fetestexcept( int excepts );
Description:
The fetestexcept function tests which of the specified floating-point exceptions flags are currently set.  The excepts argument specifies the floating-point exceptions to be queried.
For valid exception values see fegetexceptflag.
Returns:
The fetestexcept function returns the value of the bitwise OR of the floating-point exception macros corresponding to the currently set floating-point exceptions included in the excepts argument.
See Also:
feclearexcept, fegetexceptflag, feraiseexcept, fesetexceptflag
Example:

#include <stdio.h>
#include <fenv.h>

void main( void )
{
    int excepts;
    feclearexcept( FE_DIVBYZERO );

    ...code that may cause a divide by zero exception

    excepts = fetestexcept( FE_DIVBYZERO );
    if ( excepts & FE_DIVBYZERO)
        printf( "Divide by zero occurred\n" );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

feupdateenv

Synopsis:

#include <fenv.h>
int feupdateenv( const fenv_t *envp );
Description:
The feupdateenv function attempts to save the currently raised floating-point exceptions in its automatic storage, installs the floating-point environment represented by the object pointed to by envp argument, and then raises the saved floating-point exceptions.  The argument envp shall point to an object set by a call to feholdexcept or fegetenv, or equal a floating-point environment macro.
Returns:
The feupdateenv function returns zero if all the actions were successfully carried out.  Otherwise, it returns a nonzero value.
See Also:
fegetenv, feholdexcept, fesetenv
Example:

#include <fenv.h>

void main( void )
{
    fenv_t env;
    fegetenv( &env );
    fesetenv( FE_DFL_ENV );
    feupdateenv( &env );
}
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

fflush

Synopsis:

#include <stdio.h>
int fflush( FILE *fp );
Description:
If the file fp is open for output or update, the fflush function causes any unwritten data to be written to the file.   If the file fp is open for input or update, the fflush function undoes the effect of any preceding ungetc operation on the stream.  If the value of fp is NULL, then all files that are open will be flushed.
Returns:
The fflush function returns EOF if a write error occurs and zero otherwise.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgets, _flushall, fopen, getc, gets, setbuf, setvbuf, ungetc
Example:

#include <stdio.h>
#include <conio.h>

void main()
  {
    printf( "Press any key to continue..." );
    fflush( stdout );
    getch();
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

ffs

Synopsis:

#include <strings.h>
int ffs( int i );
Description:
The ffs finds the first bit set, beginning with the least significant bit, in i.  Bits are numbered starting at one (the least significant bit).
Returns:
The ffs function returns the index of the first bit set.  If i is 0, ffs returns zero.
See Also:
_lrotl, _lrotr, _rotl, _rotr
Example:

#include <stdio.h>
#include <strings.h>

int main( void )
{
    printf( "%d\n", ffs( 0 ) );
    printf( "%d\n", ffs( 16 ) );
    printf( "%d\n", ffs( 127 ) );
    printf( "%d\n", ffs( -16 ) );
    return( 0 );
}

produces the following:

0
5
1
5
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

fgetc, fgetwc

Synopsis:

#include <stdio.h>
int fgetc( FILE *fp );
#include <stdio.h>
#include <wchar.h>
wint_t fgetwc( FILE *fp );
Description:
The fgetc function gets the next character from the file designated by fp.  The character is signed.
The fgetwc function is identical to fgetc except that it gets the next multibyte character (if present) from the input stream pointed to by fp and converts it to a wide character.
Returns:
The fgetc function returns the next character from the input stream pointed to by fp.  If the stream is at end-of-file, the end-of-file indicator is set and fgetc returns EOF.  If a read error occurs, the error indicator is set and fgetc returns EOF.
The fgetwc function returns the next wide character from the input stream pointed to by fp.  If the stream is at end-of-file, the end-of-file indicator is set and fgetwc returns WEOF.  If a read error occurs, the error indicator is set and fgetwc returns WEOF.  If an encoding error occurs, errno is set to EILSEQ and fgetwc returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetchar, fgets, fopen, getc, getchar, gets, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( (c = fgetc( fp )) != EOF )
        fputc( c, stdout );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
fgetc - All, Linux, RDOS, Netware
fgetwc - All, Linux

fgetchar, _fgetchar, _fgetwchar

Synopsis:

#include <stdio.h>
int fgetchar( void );
int _fgetchar( void );
wint_t _fgetwchar( void );
Description:
The fgetchar function is equivalent to fgetc with the argument stdin.
The _fgetchar function is identical to fgetchar.  Use _fgetchar for ANSI naming conventions.

The _fgetwchar function is identical to fgetchar except that it gets the next multibyte character (if present) from the input stream pointed to by stdin and converts it to a wide character.
Returns:
The fgetchar function returns the next character from the input stream pointed to by stdin.  If the stream is at end-of-file, the end-of-file indicator is set and fgetchar returns EOF.  If a read error occurs, the error indicator is set and fgetchar returns EOF.
The _fgetwchar function returns the next wide character from the input stream pointed to by stdin.   If the stream is at end-of-file, the end-of-file indicator is set and _fgetwchar returns WEOF.  If a read error occurs, the error indicator is set and _fgetwchar returns WEOF.  If an encoding error occurs, errno is set to EILSEQ and _fgetwchar returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgets, fopen, getc, getchar, gets, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = freopen( "file", "r", stdin );
    if( fp != NULL ) {
      while( (c = fgetchar()) != EOF )
        fputchar(c);
      fclose( fp );
    }
  }
Classification:
WATCOM
_fgetchar conforms to ANSI naming conventions
Systems:
fgetchar - All, Linux, RDOS, Netware
_fgetchar - All, Linux, RDOS, Netware
_fgetwchar - All, Linux

fgetpos

Synopsis:

#include <stdio.h>
int fgetpos( FILE *fp, fpos_t *pos );
Description:
The fgetpos function stores the current position of the file fp in the object pointed to by pos.  The value stored is usable by the fsetpos function for repositioning the file to its position at the time of the call to the fgetpos function.
Returns:
The fgetpos function returns zero if successful, otherwise, the fgetpos function returns a non-zero value.   When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fopen, fseek, fsetpos, ftell
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    fpos_t position;
    auto char buffer[80];

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      fgetpos( fp, &position ); /* get position     */
      fgets( buffer, 80, fp );  /* read record      */
      fsetpos( fp, &position ); /* set position     */
      fgets( buffer, 80, fp );  /* read same record */
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

fgets, fgetws

Synopsis:

#include <stdio.h>
char *fgets( char *buf, int n, FILE *fp );
#include <stdio.h>
#include <wchar.h>
wchar_t *fgetws( wchar_t *buf, int n, FILE *fp );
Description:
The fgets function gets a string of characters from the file designated by fp and stores them in the array pointed to by buf.  The fgets function stops reading characters when end-of-file is reached, or when a newline character is read, or when n-1 characters have been read, whichever comes first.  The new-line character is not discarded.  A null character is placed immediately after the last character read into the array.
The fgetws function is identical to fgets except that it gets a string of multibyte characters (if present) from the input stream pointed to by fp, converts them to wide characters, and stores them in the wide character array pointed to by buf.  In this case, n specifies the number of wide characters, less one, to be read.

A common programming error is to assume the presence of a new-line character in every string that is read into the array.  A new-line character will not be present when more than n-1 characters occur before the new-line.  Also, a new-line character may not appear as the last character in a file, just before end-of-file.

The gets function is similar to fgets except that it operates with stdin, it has no size argument, and it replaces a newline character with the null character.
Returns:
The fgets function returns buf if successful.  NULL is returned if end-of-file is encountered, or a read error occurs.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgetchar, fopen, getc, getchar, gets, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    char buffer[80];

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( fgets( buffer, 80, fp ) != NULL )
        fputs( buffer, stdout );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
fgets - All, Linux, RDOS, Netware
fgetws - All, Linux

_fieeetomsbin

Synopsis:

#include <math.h>
extern int _fieeetomsbin( float *src, float *dest );
Description:
The _fieeetomsbin function loads the float pointed to by src in IEEE format and converts it to Microsoft binary format, storing the result into the float pointed to by dest.
For _fieeetomsbin IEEE Nan's and Infinities will cause overflow.  IEEE denormals will be converted if within range.  Otherwise, they will be converted to 0 in the Microsoft binary format.

The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38.  The range of Microsoft binary format doubles is 2.938735877056e-39 to 1.701411834605e+38.

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors became standard.
Returns:
The _fieeetomsbin function returns 0 if the conversion was successful.  Otherwise, it returns 1 if conversion would cause an overflow.
See Also:
_dieeetomsbin, _dmsbintoieee, _fmsbintoieee
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    float fieee, fmsb;
    double dieee, dmsb;

    fieee = 0.5;
    dieee = -2.0;

    /* Convert IEEE format to Microsoft binary format */
    _fieeetomsbin( &fieee, &fmsb );
    _dieeetomsbin( &dieee, &dmsb );

    /* Convert Microsoft binary format back to IEEE format */
    _fmsbintoieee( &fmsb, &fieee );
    _dmsbintoieee( &dmsb, &dieee );

    /* Display results */
    printf( "fieee = %f, dieee = %f\n", fieee, dieee );
  }

produces the following:

fieee = 0.500000, dieee = -2.000000
Classification:
WATCOM
Systems:
All, Linux, Netware

_filelength, _filelengthi64, filelength

Synopsis:

#include <io.h>
long _filelength( int handle );
__int64 _filelengthi64( int handle );

** deprecated **
long filelength( int handle );
Description:
The _filelength function returns, as a 32-bit long integer, the number of bytes in the opened file indicated by the file handle handle.
The _filelengthi64 function returns, as a 64-bit integer, the number of bytes in the opened file indicated by the file handle handle.

The filelength function is deprecated, use _filelength instead.
Returns:
If an error occurs in _filelength (-1L) is returned.
If an error occurs in _filelengthi64, (-1I64) is returned.

When an error has occurred, errno contains a value indicating the type of error that has been detected.

Otherwise, the number of bytes written to the file is returned.
See Also:
fstat, lseek, _tell
Example:

#include <sys/types.h>
#include <fcntl.h>
#include <stdio.h>
#include <io.h>

void main( void )
{
    int handle;

    /* open a file for input               */
    handle = open( "file", O_RDONLY | O_TEXT );
    if( handle != -1 ) {
        printf( "Size of file is %ld bytes\n",
              _filelength( handle ) );
        close( handle );
    }
}

produces the following:

Size of file is 461 bytes
Classification:
WATCOM
Systems:
_filelength - All, Linux, RDOS, Netware
_filelengthi64 - All, Linux
filelength - All, Linux, RDOS, Netware

FILENAME_MAX

Synopsis:

#include <stdio.h>
#define FILENAME_MAX 123
Description:
The FILENAME_MAX macro is the size of an array of char big enough to hold a string naming any file that the implementation expects to open; If there is no practical file name length limit, FILENAME_MAX is the recommended size of such an array.  As file name string contents must meet other system-specific constraints, some strings of length FILENAME_MAX may not work.
FILENAME_MAX typically sizes an array to hold a file name.
Returns:
The FILENAME_MAX macro returns a positive integer value.
Example:

#include <stdio.h>
#include <string.h>

int main( int argc, char *argv[] )
{
    if( argc ) {
        char fname[FILENAME_MAX];

        strcpy( fname, argv[0] );
        puts( fname );
    }
    return( 0 );
}
Classification:
ISO C
Systems:
MACRO

fileno

Synopsis:

#include <stdio.h>
int fileno( FILE *stream );
Description:
The fileno function returns the number of the file handle for the file designated by stream.  This number can be used in POSIX input/output calls anywhere the value returned by open can be used.  The following symbolic values in <io.h> define the file handles that are associated with the C language stdin, stdout, stderr, stdaux, and stdprn files when the application is started.  The stdaux and stdprn files are not available for Win32.
Value     Meaning
STDIN_FILENO
Standard input file number, stdin (0)

STDOUT_FILENO
Standard output file number, stdout (1)

STDERR_FILENO
Standard error file number, stderr (2)

STDAUX_FILENO
Standard auxiliary file number, stdaux (3)

STDPRN_FILENO
Standard printer file number, stdprn (4)
Returns:
The fileno function returns the number of the file handle for the file designated by stream.  If an error occurs, a value of -1 is returned and errno is set to indicate the error.
See Also:
open
Example:

#include <stdio.h>

void main()
  {
    FILE *stream;

    stream = fopen( "file", "r" );
    printf( "File number is %d\n", fileno( stream ) );
    fclose( stream );
  }

produces the following:

File number is 7
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

_findclose

Synopsis:

#include <io.h>
int _findclose( intptr_t handle );
Description:
The _findclose function closes the directory of filenames established by a call to the _findfirst function.  The handle argument was returned by the _findfirst function.
Returns:
If successful, _findclose returns 0; otherwise, _findclose and returns -1 and sets errno to one of the following values:
Constant     Meaning
ENOENT
No matching files
See Also:
_dos_find..., _findfirst, _findnext, closedir, opendir, readdir
Example:

#include <stdio.h>
#include <io.h>

void main()
  {
    struct _finddata_t  fileinfo;
    intptr_t            handle;
    int                 rc;

    /* Display name and size of "*.c" files */
    handle = _findfirst( "*.c", &fileinfo );
    rc = handle;
    while( rc != -1 ) {
      printf( "%14s %10ld\n", fileinfo.name,
                               fileinfo.size );
      rc = _findnext( handle, &fileinfo );
    }
    _findclose( handle );
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

_findfirst, _findfirsti64, _wfindfirst, _wfindfirsti64

Synopsis:

#include <io.h>
intptr_t _findfirst( const char *filespec,
                 struct _finddata_t *fileinfo );
intptr_t _findfirsti64( const char *filespec,
                    struct _finddatai64_t *fileinfo );
intptr_t _wfindfirst( const wchar_t *filespec,
                  struct _wfinddata_t *fileinfo );
intptr_t _wfindfirsti64( const wchar_t *filespec,
                  struct _wfinddatai64_t *fileinfo );
Description:
The _findfirst function returns information on the first file whose name matches the filespec argument.  The filespec argument may contain wildcard characters ('?' and '*').  The information is returned in a _finddata_t structure pointed to by fileinfo.
     
     struct _finddata_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         _fsize_t    size;
         char        name[_MAX_PATH];
     };

The _findfirsti64 function returns information on the first file whose name matches the filespec argument.   It differs from the _findfirst function in that it returns a 64-bit file size.  The filespec argument may contain wildcard characters ('?' and '*').  The information is returned in a _finddatai64_t structure pointed to by fileinfo.

     
     struct _finddatai64_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         __int64     size;             /* 64-bit size info        */
         char        name[_MAX_PATH];
     };

The _wfindfirst function is a wide character version of _findfirst that operates with wide character strings.

     
     struct _wfinddata_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         _fsize_t    size;
         wchar_t     name[_MAX_PATH];
     };

The wide character _wfindfirsti64 function is similar to the _findfirsti64 function but operates on wide character strings.  It differs from the _wfindfirst function in that it returns a 64-bit file size.

     
     struct _wfinddatai64_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         __int64     size;             /* 64-bit size info        */
         wchar_t     name[_MAX_PATH];
     };
Returns:
If successful, _findfirst returns a unique search handle identifying the file or group of files matching the filespec specification, which can be used in a subsequent call to _findnext or to _findclose.   Otherwise, _findfirst returns -1 and sets errno to one of the following values:
Constant     Meaning
ENOENT
No matching files

EINVAL
Invalid filename specification
See Also:
_dos_find..., _findclose, _findnext, closedir, opendir, readdir
Example:

#include <stdio.h>
#include <io.h>

void main()
  {
    struct _finddata_t  fileinfo;
    intptr_t            handle;
    int                 rc;

    /* Display name and size of "*.c" files */
    handle = _findfirst( "*.c", &fileinfo );
    rc = handle;
    while( rc != -1 ) {
      printf( "%14s %10ld\n", fileinfo.name,
                               fileinfo.size );
      rc = _findnext( handle, &fileinfo );
    }
    _findclose( handle );
  }
Classification:
DOS
Systems:
_findfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_findfirsti64 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wfindfirst - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wfindfirsti64 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_findnext, _findnexti64, _wfindnext, _wfindnexti64

Synopsis:

#include <io.h>
int _findnext( intptr_t handle, struct _finddata_t *fileinfo );
int _findnexti64( intptr_t handle, struct _finddatai64_t *fileinfo );
int _wfindnext( intptr_t handle, struct _wfinddata_t *fileinfo );
int _wfindnexti64( intptr_t handle, struct _wfinddatai64_t *fileinfo );
Description:
The _findnext function returns information on the next file whose name matches the filespec argument that was specified in a call to the _findfirst function.  The handle argument was returned by the _findfirst function.  The information is returned in a _finddata_t structure pointed to by fileinfo.
     
     struct _finddata_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         _fsize_t    size;
         char        name[_MAX_PATH];
     };

The _findnexti64 function returns information on the next file whose name matches the filespec argument that was specified in a call to the _findfirsti64 function.  It differs from the _findnext function in that it returns a 64-bit file size.  The handle argument was returned by the _findfirsti64 function.  The information is returned in a _finddatai64_t structure pointed to by fileinfo.

     
     struct _finddatai64_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         __int64     size;             /* 64-bit size info        */
         char        name[_MAX_PATH];
     };

The _wfindnext function is a wide character version of _findnext that operates with wide character strings.

     
     struct _wfinddata_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         _fsize_t    size;
         wchar_t     name[_MAX_PATH];
     };

The wide character _wfindnexti64 function is similar to the _findnexti64 function but operates on wide character strings.  It differs from the _wfindnext function in that it returns a 64-bit file size.

     
     struct _wfinddatai64_t {
         unsigned    attrib;
         time_t      time_create;      /* -1 for FAT file systems */
         time_t      time_access;      /* -1 for FAT file systems */
         time_t      time_write;
         __int64     size;             /* 64-bit size info        */
         wchar_t     name[_MAX_PATH];
     };
Returns:
If successful, _findnext returns 0; otherwise, _findnext and returns -1 and sets errno to one of the following values:
Constant     Meaning
ENOENT
No matching files
See Also:
_dos_find..., _findclose, _findfirst, closedir, opendir, readdir
Example:

#include <stdio.h>
#include <io.h>

void main()
  {
    struct _finddata_t  fileinfo;
    intptr_t            handle;
    int                 rc;

    /* Display name and size of "*.c" files */
    handle = _findfirst( "*.c", &fileinfo );
    rc = handle;
    while( rc != -1 ) {
      printf( "%14s %10ld\n", fileinfo.name,
                               fileinfo.size );
      rc = _findnext( handle, &fileinfo );
    }
    _findclose( handle );
  }
Classification:
DOS
Systems:
_findnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_findnexti64 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wfindnext - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32
_wfindnexti64 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_finite

Synopsis:

#include <float.h>
int _finite( double x );
Description:
The _finite function determines whether the double precision floating-point argument is a valid number (i.e., not infinite and not a NAN).
Returns:
The _finite function returns 0 if the number is not valid and non-zero otherwise.
See Also:
_clear87, _control87, _controlfp, _fpreset, printf, _status87, isfinite, fpclassify
Example:

#include <stdio.h>
#include <float.h>

void main()
  {
    printf( "%s\n", (_finite( 1.797693134862315e+308 ) )
        ? "Valid" : "Invalid" );
    printf( "%s\n", (_finite( 1.797693134862320e+308 ) )
        ? "Valid" : "Invalid" );
  }

produces the following:

Valid
Invalid
Classification:
WATCOM
Systems:
Math

_floodfill, _floodfill_w

Synopsis:

#include <graph.h>
short _FAR _floodfill( short x, short y,
                        short stop_color );

short _FAR _floodfill_w( double x, double y,
                          short stop_color );
Description:
The _floodfill functions fill an area of the screen.  The _floodfill function uses the view coordinate system.  The _floodfill_w function uses the window coordinate system.
The filling starts at the point (x,y) and continues in all directions:  when a pixel is filled, the neighbouring pixels (horizontally and vertically) are then considered for filling.  Filling is done using the current color and fill mask.  No filling will occur if the point (x,y) lies outside the clipping region.

If the argument stop_color is a valid pixel value, filling will occur in each direction until a pixel is encountered with a pixel value of stop_color.  The filled area will be the area around (x,y), bordered by stop_color.   No filling will occur if the point (x,y) has the pixel value stop_color.

If stop_color has the value (-1), filling occurs until a pixel is encountered with a pixel value different from the pixel value of the starting point (x,y).  No filling will occur if the pixel value of the point (x,y) is the current color.
Returns:
The _floodfill functions return zero when no filling takes place; a non-zero value is returned to indicate that filling has occurred.
See Also:
_setcliprgn, _setcolor, _setfillmask, _setplotaction
Example:

#include <conio.h>
#include <graph.h>

main()
{
    _setvideomode( _VRES16COLOR );
    _setcolor( 1 );
    _ellipse( _GBORDER, 120, 90, 520, 390 );
    _setcolor( 2 );
    _floodfill( 320, 240, 1 );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_floodfill - DOS
_floodfill_w - DOS

floor

Synopsis:

#include <math.h>
double floor( double x );
Description:
The floor function computes the largest integer not greater than x.
Returns:
The floor function computes the largest integer not greater than x, expressed as a double.
See Also:
ceil, fmod
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", floor( -3.14 ) );
    printf( "%f\n", floor( -3. ) );
    printf( "%f\n", floor( 0. ) );
    printf( "%f\n", floor( 3.14 ) );
    printf( "%f\n", floor( 3. ) );
  }

produces the following:

-4.000000
-3.000000
0.000000
3.000000
3.000000
Classification:
ISO C
Systems:
Math

_flushall, flushall

Synopsis:

#include <stdio.h>
int _flushall( void );

** deprecated **
int flushall( void );
Description:
The _flushall function clears all buffers associated with input streams and writes any buffers associated with output streams.  A subsequent read operation on an input file causes new data to be read from the associated file or device.
Calling the _flushall function is equivalent to calling the fflush for all open stream files.  The flushall function is deprecated, use _flushall instead.
Returns:
The _flushall function returns the number of open streams.  When an output error occurs while writing to a file, the errno global variable will be set.
See Also:
fopen, fflush
Example:

#include <stdio.h>

void main()
  {
    printf( "The number of open files is %d\n",
            _flushall() );
  }

produces the following:

The number of open files is 4
Classification:
WATCOM
Systems:
_flushall - All, Linux, RDOS, Netware
flushall - All, Linux, RDOS, Netware

fma

Synopsis:

#include <math.h>
double fma( double x, double y, double z );
Description:
The fma function performs a fused multiply-add operation.  The resultant value is the product of x and y summed with z.
Returns:
The x*y+z
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", fma( 2.0, 3.0, 1.0 ) );
  }

produces the following:

7.00000
Classification:
ISO C99
Systems:
Math

fmax

Synopsis:

#include <math.h>
double fmax( double x, double y );
Description:
The fmax function returns the larger of x and y.
Returns:
The routine will return the larger of x or y.
See Also:
fdim, fmin
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", fmax( 3.0, 2.0 ) );
  }

produces the following:

3.000000
Classification:
ISO C99
Systems:
Math

fmin

Synopsis:

#include <math.h>
double fmin( double x, double y );
Description:
The fmin function returns the smaller of x and y.
Returns:
The routine will return the smaller of x or y.
See Also:
fdim, fmax
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", fmin( 3.0, 2.0 ) );
  }

produces the following:

2.000000
Classification:
ISO C99
Systems:
Math

fmod

Synopsis:

#include <math.h>
double fmod( double x, double y );
Description:
The fmod function computes the floating-point remainder of x/y, even if the quotient x/y is not representable.
Returns:
The fmod function returns the value x - (i * y), for some integer i such that, if y is non-zero, the result has the same sign as x and magnitude less than the magnitude of y.  If the value of y is zero, then the value returned is zero.
See Also:
ceil, fabs, floor
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", fmod(  4.5,  2.0 ) );
    printf( "%f\n", fmod( -4.5,  2.0 ) );
    printf( "%f\n", fmod(  4.5, -2.0 ) );
    printf( "%f\n", fmod( -4.5, -2.0 ) );
  }

produces the following:

0.500000
-0.500000
0.500000
-0.500000
Classification:
ISO C
Systems:
Math

_fmsbintoieee

Synopsis:

#include <math.h>
extern int _fmsbintoieee( float *src, float *dest );
Description:
The _fmsbintoieee function loads the float pointed to by src in Microsoft binary format and converts it to IEEE format, storing the result &into the float pointed to by dest.
The range of Microsoft binary format floats is 2.938736e-39 to 1.701412e+38.  The range of Microsoft binary format doubles is 2.938735877056e-39 to 1.701411834605e+38.

Microsoft Binary Format was used by early versions of Microsoft QuickBASIC before coprocessors became standard.
Returns:
The _fmsbintoieee function returns 0 if the conversion was successful.  Otherwise, it returns 1 if conversion would cause an overflow.
See Also:
_dieeetomsbin, _dmsbintoieee, _fieeetomsbin
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    float fieee, fmsb;
    double dieee, dmsb;

    fieee = 0.5;
    dieee = -2.0;

    /* Convert IEEE format to Microsoft binary format */
    _fieeetomsbin( &fieee, &fmsb );
    _dieeetomsbin( &dieee, &dmsb );

    /* Convert Microsoft binary format back to IEEE format */
    _fmsbintoieee( &fmsb, &fieee );
    _dmsbintoieee( &dmsb, &dieee );

    /* Display results */
    printf( "fieee = %f, dieee = %f\n", fieee, dieee );
  }

produces the following:

fieee = 0.500000, dieee = -2.000000
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

fnmatch

Synopsis:

#include <fnmatch.h>
int fnmatch( const char *pattern,
             const char *s, int flags );
Description:
The fnmatch function checks the string specified by the s argument to see if it matches the pattern specified by the pattern argument.
The flag argument is a bitwise inclusive OR of the bits described below.  It modifies the interpretation of pattern and s.
Flag     Meaning
FNM_PATHNAME
If set, a path separator in s is explicitly matched by a slash in pattern.  It isn't matched by either the asterisk or question mark special characters, or by a bracket expression.

FNM_PERIOD
If set, a leading period in s matches a period in pattern, where the definition of "leading" depends on FNM_PATHNAME:
  • If FNM_PATHNAME is set, a period is leading if it's the first character in s, or if it immediately follows a path separator.
  • If FNM_PATHNAME isn't set, a period is leading only if it's the first character in s.

FNM_NOESCAPE
If set, disables backslash escaping:
  • If FNM_NOESCAPE isn't set in flags, a backslash character (\) in pattern followed by any other character matches that second character in s.  In particular, \\ matches a backslash in s.
  • If FNM_NOESCAPE is set, a backslash character is treated as an ordinary character.

FNM_IGNORECASE
If set, the matching is case-insensitive.

FNM_CASEFOLD
A synonym for FNM_IGNORECASE.

FNM_LEADING_DIR
If set, the final path separator and any following characters in s are ignored during matching.

A pattern-matching special character that is quoted is a pattern that matches the special character itself.  When not quoted, such special characters have special meaning in the specification of patterns.  The pattern-matching special characters and the contexts in which they have their special meaning are as follows:
?
a ?  is a pattern that matches any printable or nonprintable character except <newline>.

*
the * matches any string, including the null string.

[br_exp]
a pattern that matches a single character as per Regular Expression Bracket Expressions (1003.2 2.9.1.2) except that
  • The exclamation point character (!) replaces the circumflex character (^) in its role as a nonmatching list in the regular expression notation.
  • The backslash is used as an escape character within bracket expressions.

The ?, * and [ characters aren't special when used inside a bracket expression.
The concatenation of patterns matching a single character is a valid pattern that matches the concatenation of the single characters matched by each of the concatenated patterns.  For example, the pattern a[bc] matches the strings ab and ac.

The concatenation of one or more patterns matching a single character with one or more asterisks (*) is a valid pattern.   In such patterns, each asterisk matches a string of zero or more characters, up to the first character that matches the character following the asterisk in the pattern.  For example, the pattern a*d matches the strings ad, abd, and abcd, but not the string abc.

When asterisk is the first or last character in a pattern, it matches zero or more characters that precede or follow the characters matched by the remainded of the pattern.  For example, the pattern a*d* matches the strings ad, abcd, abcdef, aaaad and adddd.  The pattern *a*d matches the strings ad, abcd, efabcd, aaaad and adddd.
Returns:
The fnmatch function returns zero when s matches the pattern specified by pattern.  If there is no match, FNM_NOMATCH is returned.  If an error occurs, fnmatch returns another non-zero value.
Example:

#include <stdio.h>
#include <fnmatch.h>
#include <stdlib.h>
#include <limits.h>

int main( int argc, char **argv )
{
    int     i;
    char    buffer[PATH_MAX+1];

    while( gets( buffer ) ) {
        for( i = 1; i < argc; i++ ) {
            if( fnmatch( argv[i], buffer, 0 ) == 0 ) {
                printf( "'%s' matches pattern '%s'\n",
                         buffer, argv[i] );
                break;
            }
        }
    }
    return( EXIT_SUCCESS );
}
Classification:
POSIX 1003.2
Systems:
All, Linux, RDOS, Netware

fopen, _wfopen

Synopsis:

#include <stdio.h>
FILE *fopen( const char *filename, const char *mode );
FILE *_wfopen( const wchar_t *filename,
               const wchar_t *mode );
Safer C:
The Safer C Library extension provides the fopen_s function which is a safer alternative to fopen.   This newer fopen_s function is recommended to be used instead of the traditional "unsafe" fopen function.
Description:
The fopen function opens the file whose name is the string pointed to by filename, and associates a stream with it.  The argument mode points to a string beginning with one of the following sequences:
Mode
Meaning

"r"
open file for reading

"w"
create file for writing, or truncate to zero length

"a"
append:  open file or create for writing at end-of-file

"r+"
open file for update (reading and/or writing)

"w+"
create file for update, or truncate to zero length

"a+"
append:  open file or create for update, writing at end-of-file

In addition to the above characters, you can also include one of the following characters in mode to specify the translation mode for newline characters:
t
The letter "t" may be added to any of the above sequences in the second or later position to indicate that the file is (or must be) a text file.  It also overrides the global translation mode flag if you link your program with BINMODE.OBJ.   The global translation mode flag default is "text" unless you explicitly link your program with BINMODE.OBJ.
When neither "t" nor "b" is specified, the value of the global variable _fmode establishes whether the file is to treated as a binary or a text file.  Unless this value is changed by the program or you have linked your program with BINMODE.OBJ, the default will be text mode.

b
The letter "b" may be added to any of the above sequences in the second or later position to indicate that the file is (or must be) a binary file (an ISO C requirement for portability to systems that make a distinction between text and binary files).

You can also include one of the following characters to enable or disable the "commit" flag for the associated file.
c
The letter "c" may be added to any of the above sequences in the second or later position to indicate that any output is committed by the operating system whenever a flush ( fflush or _flushall) is done.
This option is not supported under Netware.

n
The letter "n" may be added to any of the above sequences in the second or later position to indicate that the operating system need not commit any output whenever a flush is done.  It also overrides the global commit flag if you link your program with COMMODE.OBJ.  The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ.
This option is not supported under Netware.

The "t", "c", and "n" mode options are extensions for fopen and _fdopen and should not be used where ISO C portability is desired.

Opening a file with read mode (r as the first character in the mode argument) fails if the file does not exist or it cannot be read.  Opening a file with append mode (a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of previous calls to the fseek function.  When a file is opened with update mode (+ as the second or later character of the mode argument), both input and output may be performed on the associated stream.

When a stream is opened in update mode, both reading and writing may be performed.  However, writing may not be followed by reading without an intervening call to the fflush function or to a file positioning function (fseek, fsetpos, rewind).  Similarly, reading may not be followed by writing without an intervening call to a file positioning function, unless the read resulted in end-of-file.

The _wfopen function is a wide character version of fopen that operates with wide character strings.
Returns:
The fopen function returns a pointer to the object controlling the stream.  This pointer must be passed as a parameter to subsequent functions for performing operations on the file.  If the open operation fails, fopen returns NULL.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
_dos_open, fclose, fcloseall, fdopen, fopen_s, freopen, freopen_s, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>

void main()
{
    FILE *fp;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      /* rest of code goes here */
      fclose( fp );
    }
}
Classification:
ISO C ('t', 'c', 'n' are Open Watcom extensions)
_wfopen is WATCOM
Systems:
fopen - All, Linux, RDOS, Netware
_wfopen - All, Linux

fopen_s, _wfopen_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
errno_t fopen_s( FILE * restrict * restrict streamptr,
                 const char * restrict filename,
                 const char * restrict mode);
errno_t _wfopen_s( FILE * restrict * restrict streamptr,
                   const wchar_t * restrict filename,
                   const wchar_t * restrict mode);
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and fopen_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
None of streamptr, filename, or mode shall be a null pointer.  If there is a runtime-constraint violation, fopen_s does not attempt to open a file.  Furthermore, if streamptr is not a null pointer, fopen_s sets *streamptr to the null pointer.
Description:
The fopen_s function opens the file whose name is the string pointed to by filename, and associates a stream with it.  The mode string shall be as described for fopen, with the addition that modes starting with the character 'w' or 'a' may be preceded by the character 'u', see below:
Mode
Meaning

"uw"
truncate to zero length or create text file for writing, default permissions

"ua"
append; open or create text file for writing at end-of-file, default permissions

"uwb"
truncate to zero length or create binary file for writing, default permissions

"uab"
append; open or create binary file for writing at end-of-file, default permissions

"uw+"
truncate to zero length or create text file for update, default permissions

"ua+"
append; open or create text file for update, writing at end-of-file, default permissions

"uw+b or uwb+"
truncate to zero length or create binary file for update, default permissions

"ua+b or uab+"
append; open or create binary file for update, writing at end-of-file, default permissions

To the extent that the underlying system supports the concepts, files opened for writing shall be opened with exclusive (also known as non-shared) access.  If the file is being created, and the first character of the mode string is not 'u', to the extent that the underlying system supports it, the file shall have a file permission that prevents other users on the system from accessing the file.  If the file is being created and first character of the mode string is 'u', then by the time the file has been closed, it shall have the system default file access permissions.  If the file was opened successfully, then the pointer to FILE pointed to by streamptr will be set to the pointer to the object controlling the opened file.  Otherwise, the pointer to FILE pointed to by streamptr will be set to a null pointer.

In addition to the above characters, you can also include one of the following characters in mode to specify the translation mode for newline characters:
t
The letter "t" may be added to any of the above sequences in the second or later position to indicate that the file is (or must be) a text file.  It also overrides the global translation mode flag if you link your program with BINMODE.OBJ.   The global translation mode flag default is "text" unless you explicitly link your program with BINMODE.OBJ.
When neither "t" nor "b" is specified, the value of the global variable _fmode establishes whether the file is to treated as a binary or a text file.  Unless this value is changed by the program or you have linked your program with BINMODE.OBJ, the default will be text mode.

b
The letter "b" may be added to any of the above sequences in the second or later position to indicate that the file is (or must be) a binary file (an ISO C requirement for portability to systems that make a distinction between text and binary files).

You can also include one of the following characters to enable or disable the "commit" flag for the associated file.
c
The letter "c" may be added to any of the above sequences in the second or later position to indicate that any output is committed by the operating system whenever a flush ( fflush or _flushall) is done.
This option is not supported under Netware.

n
The letter "n" may be added to any of the above sequences in the second or later position to indicate that the operating system need not commit any output whenever a flush is done.  It also overrides the global commit flag if you link your program with COMMODE.OBJ.  The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ.
This option is not supported under Netware.

The "t", "c", and "n" mode options are extensions for fopen_s and should not be used where ISO C portability is desired.

Opening a file with read mode (r as the first character in the mode argument) fails if the file does not exist or it cannot be read.  Opening a file with append mode (a as the first character in the mode argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of previous calls to the fseek function.  When a file is opened with update mode (+ as the second or later character of the mode argument), both input and output may be performed on the associated stream.

When a stream is opened in update mode, both reading and writing may be performed.  However, writing may not be followed by reading without an intervening call to the fflush function or to a file positioning function (fseek, fsetpos, rewind).  Similarly, reading may not be followed by writing without an intervening call to a file positioning function, unless the read resulted in end-of-file.

The _wfopen_s function is a wide character version of fopen_s that operates with wide character strings.
Returns:
The fopen_s function returns zero if it opened the file.  If it did not open the file or if there was a runtime-constraint violation, fopen_s returns a non-zero value.
See Also:
_dos_open, fclose, fcloseall, fdopen, fopen, freopen, freopen_s, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

void main()
{
    errno_t rc;
    FILE    *fp;

    rc = fopen_s( &fp, "file", "r" );
    if( fp != NULL ) {
      /* rest of code goes here */
      fclose( fp );
    }
}
Classification:
TR 24731
_wfopen_s is WATCOM
Systems:
fopen_s - All, Linux, RDOS, Netware
_wfopen_s - All, Linux

FP_OFF

Synopsis:

#include <i86.h>
unsigned FP_OFF( void __far *far_ptr );
Description:
The FP_OFF macro can be used to obtain the offset portion of the far pointer value given in far_ptr.
Returns:
The macro returns an unsigned integer value which is the offset portion of the pointer value.
See Also:
FP_SEG, MK_FP, segread
Example:

#include <stdio.h>
#include <i86.h>

char ColourTable[256][3];

void main()
  {
    union REGPACK r;
    int i;

    /* read block of colour registers */
    r.h.ah = 0x10;
    r.h.al = 0x17;
#if defined(__386__)
    r.x.ebx = 0;
    r.x.ecx = 256;
    r.x.edx = FP_OFF( ColourTable );
    r.w.ds = r.w.fs = r.w.gs = FP_SEG( &r );
#else
    r.w.bx = 0;
    r.w.cx = 256;
    r.w.dx = FP_OFF( ColourTable );
#endif
    r.w.es = FP_SEG( ColourTable );
    intr( 0x10, &r );

    for( i = 0; i < 256; i++ ) {
      printf( "Colour index = %d "
              "{ Red=%d, Green=%d, Blue=%d }\n",
              i,
              ColourTable[i][0],
              ColourTable[i][1],
              ColourTable[i][2] );
    }
  }
Classification:
Intel
Systems:
MACRO

FP_SEG

Synopsis:

#include <i86.h>
unsigned FP_SEG( void __far *far_ptr );
Description:
The FP_SEG macro can be used to obtain the segment portion of the far pointer value given in far_ptr.
Returns:
The macro returns an unsigned integer value which is the segment portion of the pointer value.
See Also:
FP_OFF, MK_FP, segread
Example:

#include <stdio.h>
#include <i86.h>

char ColourTable[256][3];

void main()
  {
    union REGPACK r;
    int i;

    /* read block of colour registers */
    r.h.ah = 0x10;
    r.h.al = 0x17;
#if defined(__386__)
    r.x.ebx = 0;
    r.x.ecx = 256;
    r.x.edx = FP_OFF( ColourTable );
    r.w.ds = r.w.fs = r.w.gs = FP_SEG( &r );
#else
    r.w.bx = 0;
    r.w.cx = 256;
    r.w.dx = FP_OFF( ColourTable );
#endif
    r.w.es = FP_SEG( ColourTable );
    intr( 0x10, &r );

    for( i = 0; i < 256; i++ ) {
      printf( "Colour index = %d "
              "{ Red=%d, Green=%d, Blue=%d }\n",
              i,
              ColourTable[i][0],
              ColourTable[i][1],
              ColourTable[i][2] );
    }
  }
Classification:
Intel
Systems:
MACRO

fpclassify

Synopsis:

#include <math.h>
int fpclassify( x );
Description:
The fpclassify macro classifies its argument x as NaN, infinite, normal, subnormal, or zero.  First, an argument represented in a format wider than its semantic type is converted to its semantic type.  Then classification is based on the type of the argument.
The argument x must be an expression of real floating type.

The possible return values of fpclassify and their meanings are listed below.
Constant     Meaning
FP_INFINITE
positive or negative infinity

FP_NAN
NaN (not-a-number)

FP_NORMAL
normal number (neither zero, subnormal, NaN, nor infinity)

FP_SUBNORMAL
subnormal number

FP_ZERO
positive or negative zero
Returns:
The fpclassify macro returns the value of the number classification macro appropriate to the value of its argument x.
See Also:
isfinite, isinf, isnan, isnormal, signbit
Example:

#include <math.h>
#include <stdio.h>

void main( void )
{
    printf( "infinity %s a normal number\n",
        fpclassify( INFINITY ) == FP_NORMAL ?
        "is" : "is not" );
}

produces the following:

infinity is not a normal number
Classification:
ISO C
Systems:
MACRO

_fpreset

Synopsis:

#include <float.h>
void _fpreset( void );
Description:
The _fpreset function resets the floating-point unit to the default state that the math library requires for correct function.  After a floating-point exception, it may be necessary to call the _fpreset function before any further floating-point operations are attempted.
In multi-threaded environments, _fpreset only affects the current thread.
Returns:
No value is returned.
See Also:
_clear87, _control87, _controlfp, _finite, _status87
Example:

#include <stdio.h>
#include <float.h>

char *status[2] = { "No", "  " };

void main( void )
{
    unsigned int fp_status;

    fp_status = _status87();

    printf( "80x87 status\n" );
    printf( "%s invalid operation\n",
            status[ (fp_status & SW_INVALID) == 0 ] );
    printf( "%s denormalized operand\n",
            status[ (fp_status & SW_DENORMAL) == 0 ] );
    printf( "%s divide by zero\n",
            status[ (fp_status & SW_ZERODIVIDE) == 0 ] );
    printf( "%s overflow\n",
            status[ (fp_status & SW_OVERFLOW) == 0 ] );
    printf( "%s underflow\n",
            status[ (fp_status & SW_UNDERFLOW) == 0 ] );
    printf( "%s inexact result\n",
            status[ (fp_status & SW_INEXACT) == 0 ] );
    _fpreset();
}
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

fprintf, fwprintf

Synopsis:

#include <stdio.h>
int fprintf( FILE *fp, const char *format, ... );
#include <stdio.h>
#include <wchar.h>
int fwprintf( FILE *fp, const wchar_t *format, ... );
Safer C:
The Safer C Library extension provides the fprintf_s function which is a safer alternative to fprintf.  This newer fprintf_s function is recommended to be used instead of the traditional "unsafe" fprintf function.
Description:
The fprintf function writes output to the file pointed to by fp under control of the argument format.   The format string is described under the description of the printf function.
The fwprintf function is a wide character version of fprintf.  It accepts a wide character string argument for format and produces wide character output.
Returns:
The fprintf function returns the number of characters written, or a negative value if an output error occurred.  The fwprintf function returns the number of wide characters written, or a negative value if an output error occurred.   When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
_bprintf, cprintf, printf, sprintf, _vbprintf, vcprintf, vfprintf, vprintf, vsprintf, _bwprintf, fwprintf, swprintf, _vbwprintf, vfwprintf, vwprintf, vswprintf
Example:

#include <stdio.h>

char *weekday = { "Saturday" };
char *month = { "April" };

void main( void )
{
    fprintf( stdout, "%s, %s %d, %d\n",
          weekday, month, 18, 1987 );
}

produces the following:

Saturday, April 18, 1987
Classification:
ISO C
fwprintf is ISO C95
Systems:
fprintf - All, Linux, RDOS, Netware
fwprintf - All, Linux

fprintf_s, fwprintf_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int fprintf_s( FILE * restrict stream,
         const char * restrict format, ... );
#include <wchar.h>
int fwprintf_s( FILE * restrict stream.
       const wchar_t * restrict format, ... );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and fprintf_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither stream nor format shall be a null pointer.  The %n specifier (modified or not by flags, field width, or precision) shall not appear in the string pointed to by format.  Any argument to fprintf_s corresponding to a %s specifier shall not be a null pointer.

If there is a runtime-constraint violation, the fprintf_s function does not attempt to produce further output, and it is unspecified to what extent fprintf_s produced output before discovering the runtime-constraint violation.
Description:
The fprintf_s function is equivalent to the fprintf function except for the explicit runtime-constraints listed above.
The fwprintf_s function is a wide character version of fprintf_s.  It accepts a wide character string argument for format and produces wide character output.
Returns:
The fprintf_s function returns the number of characters written, or a negative value if an output error or runtime-constraint violation occurred.
The fwprintf_s function returns the number of wide characters written, or a negative value if an output error or runtime-constraint violation occurred.
See Also:
_bprintf, cprintf, fprintf, printf, sprintf, _vbprintf, vcprintf, vfprintf, vprintf, vsprintf, _bwprintf, fwprintf, swprintf, _vbwprintf, vfwprintf, vwprintf, vswprintf
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

char *weekday = { "Friday" };
char *month = { "August" };

void main( void )
{
    fprintf_s( stdout, "%s, %s %d, %d\n",
               weekday, month, 13, 2004 );
}

produces the following:

Friday, August 13, 2004
Classification:
TR 24731
Systems:
fprintf_s - All, Linux, RDOS, Netware
fwprintf_s - All, Linux

fputc, fputwc

Synopsis:

#include <stdio.h>
int fputc( int c, FILE *fp );
#include <stdio.h>
#include <wchar.h>
wint_t fputwc( wint_t c, FILE *fp );
Description:
The fputc function writes the character specified by the argument c to the output stream designated by fp.
The fputwc function is identical to fputc except that it converts the wide character specified by c to a multibyte character and writes it to the output stream.
Returns:
The fputc function returns the character written or, if a write error occurs, the error indicator is set and fputc returns EOF.
The fputwc function returns the wide character written or, if a write error occurs, the error indicator is set and fputwc returns WEOF.  If an encoding error occurs, errno is set to EILSEQ and fputwc returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fopen, fputchar, fputs, putc, putchar, puts, ferror
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( (c = fgetc( fp )) != EOF )
        fputc( c, stdout );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
fputc - All, Linux, RDOS, Netware
fputwc - All, Linux

fputchar, _fputchar, _fputwchar

Synopsis:

#include <stdio.h>
int fputchar( int c );
int _fputchar( int c );
wint_t _fputwchar( wint_t c );
Description:
The fputchar function writes the character specified by the argument c to the output stream stdout.   This function is identical to the putchar function.
The function is equivalent to:

     
         fputc( c, stdout );

The _fputchar function is identical to fputchar.  Use _fputchar for ANSI naming conventions.

The _fputwchar function is identical to fputchar except that it converts the wide character specified by c to a multibyte character and writes it to the output stream.
Returns:
The fputchar function returns the character written or, if a write error occurs, the error indicator is set and fputchar returns EOF.
The _fputwchar function returns the wide character written or, if a write error occurs, the error indicator is set and _fputwchar returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fopen, fputc, fputs, putc, putchar, puts, ferror
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      c = fgetc( fp );
      while( c != EOF ) {
        _fputchar( c );
        c = fgetc( fp );
      }
      fclose( fp );
    }
  }
Classification:
WATCOM
_fputchar conforms to ANSI naming conventions
Systems:
fputchar - All, Linux, RDOS, Netware
_fputchar - All, Linux, RDOS, Netware
_fputwchar - All, Linux

fputs, fputws

Synopsis:

#include <stdio.h>
int fputs( const char *buf, FILE *fp );
#include <stdio.h>
#include <wchar.h>
int fputws( const wchar_t *buf, FILE *fp );
Description:
The fputs function writes the character string pointed to by buf to the output stream designated by fp.   The terminating null character is not written.
The fputws function is identical to fputs except that it converts the wide character string specified by buf to a multibyte character string and writes it to the output stream.
Returns:
The fputs function returns EOF if an error occurs; otherwise, it returns a non-negative value (the number of characters written).  The fputws function returns EOF if a write or encoding error occurs; otherwise, it returns a non-negative value (the number of characters written).  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fopen, fputc, fputchar, putc, putchar, puts, ferror
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    char buffer[80];

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( fgets( buffer, 80, fp ) != NULL )
        fputs( buffer, stdout );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
fputs - All, Linux, RDOS, Netware
fputws - All, Linux

fread

Synopsis:

#include <stdio.h>
size_t fread( void *buf,
              size_t elsize,
              size_t nelem,
              FILE *fp );
Description:
The fread function reads nelem elements of elsize bytes each from the file specified by fp into the buffer specified by buf.
Returns:
The fread function returns the number of complete elements successfully read.  This value may be less than the requested number of elements.
The feof and ferror functions can be used to determine whether the end of the file was encountered or if an input/output error has occurred.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fopen, feof, ferror
Example:

The following example reads a simple student record containing binary data.  The student record is described by the struct student_data declaration.

#include <stdio.h>

struct student_data {
    int             student_id;
    unsigned char   marks[10];
};

size_t read_data( FILE *fp, struct student_data *p )
  {
    return( fread( p, sizeof(*p), 1, fp ) );
  }

void main()
  {
    FILE *fp;
    struct student_data std;
    int i;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( read_data( fp, &std ) != 0 ) {
        printf( "id=%d ", std.student_id );
        for( i = 0; i < 10; i++ )
          printf( "%3d ", std.marks[ i ] );
        printf( "\n" );
      }
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

free Functions

Synopsis:

#include <stdlib.h>  For ISO C compatibility (free only)
#include <malloc.h>  Required for other function prototypes
void free( void *ptr );
void _bfree( __segment seg, void __based(void) *ptr );
void _ffree( void __far  *ptr );
void _nfree( void __near *ptr );
Description:
When the value of the argument ptr is NULL, the free function does nothing; otherwise, the free function deallocates the memory block located by the argument ptr which points to a memory block previously allocated through a call to the appropriate version of calloc, malloc or realloc.   After the call, the freed block is available for allocation.
Each function deallocates memory from a particular heap, as listed below:
Function     Heap
free
Depends on data model of the program

_bfree
Based heap specified by seg value

_ffree
Far heap (outside the default data segment)

_nfree
Near heap (inside the default data segment)

In a large data memory model, the free function is equivalent to the _ffree function; in a small data memory model, the free function is equivalent to the _nfree function.
Returns:
The free functions return no value.
See Also:
calloc Functions, _expand Functions, halloc, hfree, malloc Functions, _msize Functions, realloc Functions, sbrk
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
    char *buffer;

    buffer = (char *)malloc( 80 );
    if( buffer == NULL ) {
      printf( "Unable to allocate memory\n" );
    } else {

      /* rest of code goes here */

      free( buffer );  /* deallocate buffer */
    }
  }
Classification:
ISO C
_bfree is WATCOM
_ffree is WATCOM
_nfree is WATCOM
Systems:
free - All, Linux, RDOS, Netware
_bfree - DOS/16, Windows, OS/2 1.x(all)
_ffree - DOS/16, Windows, OS/2 1.x(all)
_nfree - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_freect

Synopsis:

#include <malloc.h>
unsigned int _freect( size_t size );
Description:
The _freect function returns the number of times that _nmalloc (or malloc in small data models) can be called to allocate a item of size bytes.  In the tiny, small and medium memory models, the default data segment is only extended as needed to satisfy requests for memory allocation.  Therefore, you will need to call _nheapgrow in these memory models before calling _freect in order to get a meaningful result.
Returns:
The _freect function returns the number of calls as an unsigned integer.
See Also:
calloc, _heapgrow Functions, malloc Functions, _memavl, _memmax
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    int  i;

    printf( "Can allocate %u longs before _nheapgrow\n",
            _freect( sizeof(long) ) );
    _nheapgrow();
    printf( "Can allocate %u longs after _nheapgrow\n",
            _freect( sizeof(long) ) );
    for( i = 1; i < 1000; i++ ) {
      _nmalloc( sizeof(long) );
    }
    printf( "After allocating 1000 longs:\n" );
    printf( "Can still allocate %u longs\n",
            _freect( sizeof(long) ) );
  }

produces the following:

Can allocate 0 longs before _nheapgrow
Can allocate 10447 longs after _nheapgrow
After allocating 1000 longs:
Can still allocate 9447 longs
Classification:
WATCOM
Systems:
All, Linux, RDOS

freopen, _wfreopen

Synopsis:

#include <stdio.h>
FILE *freopen( const char *filename,
               const char *mode,
               FILE *fp );
FILE *_wfreopen( const wchar_t *filename,
                 const wchar_t *mode,
                 FILE *fp );
Safer C:
The Safer C Library extension provides the freopen_s function which is a safer alternative to freopen.  This newer freopen_s function is recommended to be used instead of the traditional "unsafe" freopen function.
Description:
The stream located by the fp pointer is closed.  The freopen function opens the file whose name is the string pointed to by filename, and associates a stream with it.  The stream information is placed in the structure located by the fp pointer.
The argument mode is described in the description of the fopen function.

The _wfreopen function is a wide character version of freopen that operates with wide character strings.
Returns:
The freopen function returns a pointer to the object controlling the stream.  This pointer must be passed as a parameter to subsequent functions for performing operations on the file.  If the open operation fails, freopen returns NULL.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
_dos_open, fclose, fcloseall, fdopen, fopen, fopen_s, freopen_s, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>

void main()
{
    FILE *fp;
    int c;

    fp = freopen( "file", "r", stdin );
    if( fp != NULL ) {
      while( (c = fgetchar()) != EOF )
        fputchar(c);
      fclose( fp );
    }
}
Classification:
ISO C
_wfreopen is WATCOM
Systems:
freopen - All, Linux, RDOS, Netware
_wfreopen - All, Linux

freopen_s, _wfreopen_s

Synopsis:

#include <stdio.h>
#define __STDC_WANT_LIB_EXT1__ 1
errno_t  freopen_s( FILE * restrict * restrict newstreamptr,
                    const char * filename,
                    const char * restrict mode,
                    FILE * restrict stream );
errno_t _wfreopen_s( FILE * restrict * restrict newstreamptr,
                      const wchar_t * restrict filename,
                      const wchar_t * restrict mode,
                      FILE * restrict stream );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and freopen_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
None of newstreamptr, mode, and stream shall be a null pointer.  If there is a runtime-constraint violation, freopen_s neither attempts to close any file associated with stream nor attempts to open a file.   Furthermore, if newstreamptr is not a null pointer, freopen_s sets *newstreamptr to the null pointer.
Description:
The freopen_s function opens the file whose name is the string pointed to by filename and associates the stream pointed to by stream with it.  The mode argument has the same meaning as in the fopen_s function (including the mode's effect on exclusive access and file permissions).  If filename is a null pointer,the freopen_s function attempts to change the mode of the stream to that specified by mode, as if the name of the file currently associated with the stream had been used.  It is implementation-defined which changes of mode are permitted (if any), and under what circumstances.  The freopen_s function first attempts to close any file that is associated with stream.  Failure to close the file is ignored.  The error and end-of-file indicators for the stream are cleared.   If the file was opened successfully, then the pointer to FILE pointed to by newstreamptr will be set to the value of stream.  Otherwise, the pointer to FILE pointed to by newstreamptr will be set to a null pointer.
The _wfreopen_s function is a wide character version of freopen_s that operates with wide character strings.
Returns:
The freopen_s function returns zero if it opened the file.  If it did not open the file or there was a runtime-constraint violation, freopen_s returns a non-zero value.
See Also:
_dos_open, fclose, fcloseall, fdopen, fopen, fopen_s, freopen, _fsopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

void main()
{
    errno_t rc;
    FILE    *fp;
    int     c;

    rc = freopen_s( &fp, "file", "r", stdin );
    if( rc == 0 ) {
      while( (c = fgetc( fp )) != EOF )
        fputchar(c);
      fclose( fp );
    }
}
Classification:
TR 24731
_wfreopen_s is WATCOM
Systems:
freopen_s - All, Linux, RDOS, Netware
_wfreopen_s - All, Linux

frexp

Synopsis:

#include <math.h>
double frexp( double value, int *exp );
Description:
The frexp function breaks a floating-point number into a normalized fraction and an integral power of 2.  It stores the integral power of 2 in the int object pointed to by exp.
Returns:
The frexp function returns the value of x, such that x is a double with magnitude in the interval [0.5,1) or zero, and value equals x times 2 raised to the power *exp.  If value is zero, then both parts of the result are zero.
See Also:
ldexp, modf
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    int    expon;
    double value;

    value = frexp(  4.25, &expon );
    printf( "%f %d\n", value, expon );
    value = frexp( -4.25, &expon );
    printf( "%f %d\n", value, expon );
  }

produces the following:

0.531250 3
-0.531250 3
Classification:
ISO C
Systems:
Math

fscanf, fwscanf

Synopsis:

#include <stdio.h>
int fscanf( FILE *fp, const char *format, ... );
#include <stdio.h>
#include <wchar.h>
int fwscanf( FILE *fp, const wchar_t *format, ... );
Safer C:
The Safer C Library extension provides the fscanf_s function which is a safer alternative to fscanf.   This newer fscanf_s function is recommended to be used instead of the traditional "unsafe" fscanf function.
Description:
The fscanf function scans input from the file designated by fp under control of the argument format.   Following the format string is a list of addresses to receive values.  The format string is described under the description of the scanf function.
The fwscanf function is identical to fscanf except that it accepts a wide character string argument for format.
Returns:
The fscanf function returns EOF if an input failure occurred before any conversion.  Otherwise, the number of input arguments for which values were successfully scanned and stored is returned.  When a file input error occurs, the errno global variable may be set.
See Also:
cscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf, fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf
Example:

To scan a date in the form "Saturday April 18 1987":

#include <stdio.h>

void main( void )
{
    int day, year;
    char weekday[10], month[10];
    FILE *in_data;

    in_data = fopen( "file", "r" );
    if( in_data != NULL ) {
        fscanf( in_data, "%s %s %d %d",
                weekday, month, &day, &year );
        printf( "Weekday=%s Month=%s Day=%d Year=%d\n",
                weekday, month, day, year );
        fclose( in_data );
    }
}
Classification:
ISO C90
fwscanf is ISO C95
Systems:
fscanf - All, Linux, RDOS, Netware
fwscanf - All, Linux

fscanf_s, fwscanf_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
int fscanf_s( FILE * restrict stream,
        const char * restrict format, ... );
#include <stdio.h>
#include <wchar.h>
int fwscanf_s( FILE * restrict stream,
      const wchar_t * restrict format, ... );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and fscanf_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither stream nor format shall be a null pointer.  Any argument indirected through in order to store converted input shall not be a null pointer.

If there is a runtime-constraint violation, the fscanf_s function does not attempt to perform further input, and it is unspecified to what extent fscanf_s performed input before discovering the runtime-constraint violation.
Description:
The fscanf_s function is equivalent to fscanf except that the c, s, and [ conversion specifiers apply to a pair of arguments (unless assignment suppression is indicated by a *).  The first of these arguments is the same as for fscanf.  That argument is immediately followed in the argument list by the second argument, which has type size_t and gives the number of elements in the array pointed to by the first argument of the pair.  If the first argument points to a scalar object, it is considered to be an array of one element.
A matching failure occurs if the number of elements in a receiving object is insufficient to hold the converted input (including any trailing null character).

The fwscanf_s function is identical to fscanf_s except that it accepts a wide character string argument for format.
Returns:
The fscanf_s function returns EOF if an input failure occurred before any conversion or if there was a runtime-constraint violation.  Otherwise, the fscanf_s function returns the number of input items successfully assigned, which can be fewer than provided for, or even zero.
When a file input error occurs, the errno global variable may be set.
See Also:
cscanf, fscanf, scanf, sscanf, vcscanf, vfscanf, vscanf, vsscanf, fwscanf, wscanf, swscanf, vfwscanf, vwscanf, vswscanf
Example:

To scan a date in the form "Friday August 13 2004":

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

void main( void )
{
    int day, year;
    char weekday[10], month[10];
    FILE *in_data;

    in_data = fopen( "file", "r" );
    if( in_data != NULL ) {
        fscanf_s( in_data, "%s %s %d %d",
                weekday, sizeof( weekday ),
                month, sizeof( month ),
                &day, &year );
        printf_s( "Weekday=%s Month=%s Day=%d Year=%d\n",
                weekday, month, day, year );
        fclose( in_data );
    }
}
Classification:
TR 24731
Systems:
fscanf_s - All, Linux, RDOS, Netware
fwscanf_s - All, Linux

fseek

Synopsis:

#include <stdio.h>
int fseek( FILE *fp, long int offset, int where );
Description:
The fseek function changes the read/write position of the file specified by fp.  This position defines the character that will be read or written on the next I/O operation on the file.  The argument fp is a file pointer returned by fopen or freopen.  The argument offset is the position to seek to relative to one of three positions specified by the argument where.  Allowable values for where are:
Value     Meaning
SEEK_SET
The new file position is computed relative to the start of the file.  The value of offset must not be negative.

SEEK_CUR
The new file position is computed relative to the current file position.  The value of offset may be positive, negative or zero.

SEEK_END
The new file position is computed relative to the end of the file.

The fseek function clears the end-of-file indicator and undoes any effects of the ungetc function on the same file.

The ftell function can be used to obtain the current position in the file before changing it.   The position can be restored by using the value returned by ftell in a subsequent call to fseek with the where parameter set to SEEK_SET.
Returns:
The fseek function returns zero if successful, non-zero otherwise.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetpos, fopen, fsetpos, ftell
Example:

The size of a file can be determined by the following example which saves and restores the current position of the file.

#include <stdio.h>

long int filesize( FILE *fp )
  {
    long int save_pos, size_of_file;

    save_pos = ftell( fp );
    fseek( fp, 0L, SEEK_END );
    size_of_file = ftell( fp );
    fseek( fp, save_pos, SEEK_SET );
    return( size_of_file );
  }

void main()
  {
    FILE *fp;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      printf( "File size=%ld\n", filesize( fp ) );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

fsetpos

Synopsis:

#include <stdio.h>
int fsetpos( FILE *fp, fpos_t *pos );
Description:
The fsetpos function positions the file fp according to the value of the object pointed to by pos, which shall be a value returned by an earlier call to the fgetpos function on the same file.
Returns:
The fsetpos function returns zero if successful, otherwise, the fsetpos function returns a non-zero value.   When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetpos, fopen, fseek, ftell
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    fpos_t position;
    auto char buffer[80];

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      fgetpos( fp, &position ); /* get position     */
      fgets( buffer, 80, fp );  /* read record      */
      fsetpos( fp, &position ); /* set position     */
      fgets( buffer, 80, fp );  /* read same record */
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

_fsopen, _wfsopen

Synopsis:

#include <stdio.h>
FILE *_fsopen( const char *filename,
               const char *mode, int share );
FILE *_wfsopen( const wchar_t *filename,
                const wchar_t *mode, int share );
Description:
The _fsopen function opens the file whose name is the string pointed to by filename, and associates a stream with it.  The arguments mode and share control shared reading or writing.  The argument mode points to a string beginning with one of the following sequences:
Mode
Meaning

"r"
open file for reading; use default file translation

"w"
create file for writing, or truncate to zero length; use default file translation

"a"
append:  open text file or create for writing at end-of-file; use default file translation

"rb"
open binary file for reading

"rt"
open text file for reading

"wb"
create binary file for writing, or truncate to zero length

"wt"
create text file for writing, or truncate to zero length

"ab"
append; open binary file or create for writing at end-of-file

"at"
append; open text file or create for writing at end-of-file

"r+"
open file for update (reading and/or writing); use default file translation

"w+"
create file for update, or truncate to zero length; use default file translation

"a+"
append; open file or create for update, writing at end-of-file; use default file translation

"r+b", "rb+"
open binary file for update (reading and/or writing)

"r+t", "rt+"
open text file for update (reading and/or writing)

"w+b", "wb+"
create binary file for update, or truncate to zero length

"w+t", "wt+"
create text file for update, or truncate to zero length

"a+b", "ab+"
append; open binary file or create for update, writing at end-of-file

"a+t", "at+"
append; open text file or create for update, writing at end-of-file

When default file translation is specified, the value of the global variable _fmode establishes whether the file is to treated as a binary or a text file.  Unless this value is changed by the program, the default will be text mode.

Opening a file with read mode ('r' as the first character in the mode argument) fails if the file does not exist or it cannot be read.  Opening a file with append mode ('a' as the first character in the mode argument) causes all subsequent writes to the file to be forced to the current end-of-file, regardless of previous calls to the fseek function.  When a file is opened with update mode ('+' as the second or third character of the mode argument), both input and output may be performed on the associated stream.

When a stream is opened in update mode, both reading and writing may be performed.  However, writing may not be followed by reading without an intervening call to the fflush function or to a file positioning function (fseek, fsetpos, rewind).  Similarly, reading may not be followed by writing without an intervening call to a file positioning function, unless the read resulted in end-of-file.

The shared access for the file, share, is established by a combination of bits defined in the <share.h> header file.  The following values may be set:
Value     Meaning
SH_COMPAT
Set compatibility mode.

SH_DENYRW
Prevent read or write access to the file.

SH_DENYWR
Prevent write access of the file.

SH_DENYRD
Prevent read access to the file.

SH_DENYNO
Permit both read and write access to the file.

You should consult the technical documentation for the DOS system that you are using for more detailed information about these sharing modes.

The _wfsopen function is a wide character version of _fsopen that operates with wide character strings.
Returns:
The _fsopen function returns a pointer to the object controlling the stream.  This pointer must be passed as a parameter to subsequent functions for performing operations on the file.  If the open operation fails, _fsopen returns NULL.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
_dos_open, fclose, fcloseall, fdopen, fopen, freopen, _grow_handles, _hdopen, open, _open_osfhandle, _popen, _sopen
Example:

#include <stdio.h>
#include <share.h>

void main()
  {
    FILE *fp;

    /*
      open a file and prevent others from writing to it
    */
    fp = _fsopen( "report.dat", "w", SH_DENYWR );
    if( fp != NULL ) {
      /* rest of code goes here */
      fclose( fp );
    }
  }
Classification:
WATCOM
Systems:
_fsopen - All, Linux, RDOS, Netware
_wfsopen - All, Linux

fstat, _fstat, _fstati64

Synopsis:

#include <sys/types.h>
#include <sys/stat.h>
int fstat( int handle, struct stat *buf );
int _fstat( int handle, struct stat *buf );
int _fstati64( int handle, struct _stati64 *buf );
Description:
The fstat functions obtain information about an open file whose file handle is handle.  This information is placed in the structure located at the address indicated by buf.
The file <sys/stat.h> contains definitions for the structure stat.
Field     Type/Meaning
st_dev
(dev_t) the disk drive the file resides on

st_ino
(ino_t) this inode's number (not used for DOS)

st_mode
(unsigned short) file mode

st_nlink
(short) number of hard links

st_uid
(unsigned long) user-id (always 'root' for DOS)

st_gid
(short) group-id (always 'root' for DOS)

st_rdev
(dev_t) this should be the device type but it is the same as st_dev for the time being

st_size
(off_t) total file size

st_atime
(time_t) this should be the file "last accessed" time if the file system supports it

st_mtime
(time_t) the file "last modified" time

st_ctime
(time_t) this should be the file "last status change" time if the file system supports it
The following fields are Netware only:

st_btime
(time_t) the file "last archived" time

st_attr
(unsigned long) the file's attributes

st_archivedID
(unsigned long) the user/object ID that last archived file

st_updatedID
(unsigned long) the user/object ID that last updated file

st_inheritedRightsMask
(unsigned short) the inherited rights mask

st_originatingNameSpace
(unsigned char) the originating name space

The structure _stati64 differs from stat in the following way:
st_size
(__int64) total file size (as a 64-bit value)

At least the following macros are defined in the <sys/stat.h> header file.
Macro     Meaning
S_ISFIFO(m)
Test for FIFO.

S_ISCHR(m)
Test for character special file.

S_ISDIR(m)
Test for directory file.

S_ISBLK(m)
Test for block special file.

S_ISREG(m)
Test for regular file.

The value m supplied to the macros is the value of the st_mode field of a stat structure.   The macro evaluates to a non-zero value if the test is true and zero if the test is false.

The following bits are encoded within the st_mode field of a stat structure.
Mask     Owner Permissions
S_IRWXU
Read, write, search (if a directory), or execute (otherwise)

S_IRUSR
Read permission bit

S_IWUSR
Write permission bit

S_IXUSR
Search/execute permission bit

S_IREAD
== S_IRUSR (for Microsoft compatibility)

S_IWRITE
== S_IWUSR (for Microsoft compatibility)

S_IEXEC
== S_IXUSR (for Microsoft compatibility)

S_IRWXU is the bitwise inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.
Mask     Group Permissions (same as owner's on DOS, OS/2 or Windows)
S_IRWXG
Read, write, search (if a directory), or execute (otherwise)

S_IRGRP
Read permission bit

S_IWGRP
Write permission bit

S_IXGRP
Search/execute permission bit

S_IRWXG is the bitwise inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.
Mask     Other Permissions (same as owner's on DOS, OS/2 or Windows)
S_IRWXO
Read, write, search (if a directory), or execute (otherwise)

S_IROTH
Read permission bit

S_IWOTH
Write permission bit

S_IXOTH
Search/execute permission bit

S_IRWXO is the bitwise inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.
Mask     Meaning
S_ISUID
(Not supported by DOS, OS/2 or Windows) Set user ID on execution.  The process's effective user ID shall be set to that of the owner of the file when the file is run as a program.  On a regular file, this bit should be cleared on any write.

S_ISGID
(Not supported by DOS, OS/2 or Windows) Set group ID on execution.  Set effective group ID on the process to the file's group when the file is run as a program.  On a regular file, this bit should be cleared on any write.

The _fstat function is identical to fstat.  Use _fstat for ANSI naming conventions.

The _fstati64 function differ from fstat in the type of structure that they are asked to fill in.  The differences in the structures are described above.
Returns:
All forms of the fstat function return zero when the information is successfully obtained.  Otherwise, -1 is returned.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The handle argument is not a valid file handle.
See Also:
creat, dup, dup2, open, _sopen, stat
Example:

#include <stdio.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <io.h>

void main()
{
    int handle, rc;
    struct stat buf;

    handle = open( "file", O_RDONLY );
    if( handle != -1 ) {
        rc = fstat( handle, &buf );
        if( rc != -1 )
            printf( "File size = %d\n", buf.st_size );
        close( handle );
    }
}
Classification:
POSIX 1003.1
_fstat conforms to ANSI naming conventions
_fstati64 is WATCOM
Systems:
fstat - All, Linux, RDOS, Netware
_fstat - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_fstati64 - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

fsync

Synopsis:

#include <io.h>
int fsync( int fd );
Description:
The fsync function writes to disk all the currently queued data for the open file specified by fd.  All necessary file system information required to retrieve the data is also written to disk.  The file access times are also updated.
The fsync function is used when you wish to ensure that both the file data and file system information required to recover the complete file have been written to the disk.

The fsync function does not return until the transfer is completed.
Returns:
The fsync function returns zero if successful.  Otherwise, it returns -1 and errno is set to indicate the error.  If the fsync function fails, outstanding i/o operations are not guaranteed to have been completed.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EBADF
The fd argument is not a valid file handle.

EINVAL
Synchronized i/o is not supported for this file.

EIO
A physical I/O error occurred (e.g., a bad block).  The precise meaning is device dependent.

ENOSYS
The fsync function is not supported.
See Also:
fstat, open, stat, write
Example:

/*
*      Write a file and make sure it is on disk.
*/
#include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <io.h>

char buf[512];

void main()
{
    int handle;
    int i;

    handle = creat( "file", S_IWRITE | S_IREAD );
    if( handle == -1 ) {
      perror( "Error creating file" );
      exit( EXIT_FAILURE );
    }

    for( i = 0; i < 255; ++i ) {
      memset( buf, i, sizeof( buf ) );
      if( write( handle, buf, sizeof(buf) ) != sizeof(buf) ) {
        perror( "Error writing file" );
        exit( EXIT_FAILURE );
      }
    }

    if( fsync( handle ) == -1 ) {
      perror( "Error sync'ing file" );
      exit( EXIT_FAILURE );
    }

    close( handle );
    exit( EXIT_SUCCESS );
}
Classification:
POSIX 1003.4
Systems:
All, Linux, RDOS, Netware

ftell

Synopsis:

#include <stdio.h>
long int ftell( FILE *fp );
Description:
The ftell function returns the current read/write position of the file specified by fp.  This position defines the character that will be read or written by the next I/O operation on the file.  The value returned by ftell can be used in a subsequent call to fseek to set the file to the same position.
Returns:
The ftell function returns the current read/write position of the file specified by fp.  When an error is detected, -1L is returned.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetpos, fopen, fsetpos, fseek
Example:

#include <stdio.h>

long int filesize( FILE *fp )
  {
    long int save_pos, size_of_file;

    save_pos = ftell( fp );
    fseek( fp, 0L, SEEK_END );
    size_of_file = ftell( fp );
    fseek( fp, save_pos, SEEK_SET );
    return( size_of_file );
  }

void main()
  {
    FILE *fp;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      printf( "File size=%ld\n", filesize( fp ) );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

ftime

Synopsis:

#include <sys/timeb.h>
int ftime( struct timeb *timeptr );

struct timeb {
    time_t         time;     /* time in seconds since Jan 1, 1970 UTC */
    unsigned short millitm;  /* milliseconds                           */
    short          timezone; /* difference in minutes from UTC        */
    short          dstflag;  /* nonzero if in daylight savings time   */
};
Description:
The ftime function gets the current time and stores it in the structure pointed to by timeptr.
Returns:
The ftime function fills in the fields of the structure pointed to by timeptr.  The ftime function returns -1 if not successful, and no useful value otherwise.
See Also:
asctime Functions, asctime_s, clock, ctime Functions, ctime_s, difftime, gmtime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#include <stdio.h>
#include <time.h>
#include <sys/timeb.h>

void main()
  {
    struct timeb timebuf;
    char   *tod;

    ftime( &timebuf );
    tod = ctime( &timebuf.time );
    printf( "The time is %.19s.%hu %s",
        tod, timebuf.millitm, &tod[20] );
  }

produces the following:

The time is Tue Dec 25 15:58:42.870 1990
Classification:
WATCOM
Systems:
All, Linux, RDOS

_fullpath, _wfullpath

Synopsis:

#include <stdlib.h>
char *_fullpath( char *buffer,
                 const char *path,
                 size_t size );
wchar_t *_wfullpath( wchar_t *buffer ,
                      const wchar_t *path,
                      size_t size );
Description:
The _fullpath function returns the full pathname of the file specification in path in the specified buffer buffer of length size.
The maximum size that might be required for buffer is _MAX_PATH.  If the buffer provided is too small, NULL is returned and errno is set.

If buffer is NULL then a buffer of size _MAX_PATH is allocated using malloc.   This buffer may be freed using the free function.

If path is NULL or points to a null string ("") then the current working directory is returned in buffer.

The _wfullpath function is a wide character version of _fullpath that operates with wide character strings.
Returns:
The _fullpath function returns a pointer to the full path specification if no error occurred.  Otherwise, NULL is returned.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
ENOENT
The current working directory could not be obtained.

ENOMEM
The buffer could not be allocated.

ERANGE
The buffer passed was too small.
See Also:
_makepath, _splitpath
Example:

#include <stdio.h>
#include <stdlib.h>

void main( int argc, char *argv[] )
  {
    int i;
    char buff[ PATH_MAX ];

    for( i = 1; i < argc; ++i ) {
      puts( argv[i] );
      if( _fullpath( buff, argv[i], PATH_MAX ) ) {
        puts( buff );
      } else {
        puts( "FAIL!" );
      }
    }
  }
Classification:
WATCOM
Systems:
_fullpath - All, Linux, RDOS, Netware
_wfullpath - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

fwide

Synopsis:

#include <stdio.h>
#include <wchar.h>
int fwide( FILE *fp, int mode );
Description:
The fwide function determines the orientation of the stream pointed to by fp.  If mode is greater than zero, the function first attempts to make the stream wide oriented.  If mode is less than zero, the function first attempts to make the stream byte oriented.  Otherwise, mode is zero and the fwide function does not alter the orientation of the stream.
Returns:
The fwide function returns a value greater than zero if, after the call, the stream has wide orientation, a value less than zero if the stream has byte orientation, or zero if the stream has no orientation.
See Also:
fopen, freopen
Example:

#include <stdio.h>
#include <wchar.h>

void main( void )
{
    FILE    *fp;
    int     mode;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
        mode = fwide( fp, -33 );
        printf( "orientation: %s\n",
            mode > 0 ? "wide" :
            mode < 0 ? "byte" : "none" );
    }
}

produces the following:

orientation: byte
Classification:
ISO C95
Systems:
All, Linux, RDOS

fwrite

Synopsis:

#include <stdio.h>
size_t fwrite( const void *buf,
               size_t elsize,
               size_t nelem,
               FILE *fp );
Description:
The fwrite function writes nelem elements of elsize bytes each to the file specified by fp.
Returns:
The fwrite function returns the number of complete elements successfully written.  This value will be less than the requested number of elements only if a write error occurs.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
ferror, fopen
Example:

#include <stdio.h>

struct student_data {
    int             student_id;
    unsigned char   marks[10];
};

void main()
  {
    FILE *fp;
    struct student_data std;
    int i;

    fp = fopen( "file", "w" );
    if( fp != NULL ) {
      std.student_id = 1001;
      for( i = 0; i < 10; i++ )
        std.marks[ i ] = (unsigned char) (85 + i);

      /* write student record with marks */
      i = fwrite( &std, sizeof(std), 1, fp );
      printf( "%d record written\n", i );
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
All, Linux, RDOS, Netware

gcvt, _gcvt, _wgcvt

Synopsis:

#include <stdlib.h>
char *gcvt( double value,
            int ndigits,
            char *buffer );
char *_gcvt( double value,
            int ndigits,
            char *buffer );
wchar_t *_wgcvt( double value,
                 int ndigits,
                 wchar_t *buffer );
Description:
The gcvt function converts the floating-point number value into a character string and stores the result in buffer.  The parameter ndigits specifies the number of significant digits desired.  The converted number will be rounded to this position.
If the exponent of the number is less than -4 or is greater than or equal to the number of significant digits wanted, then the number is converted into E-format, otherwise the number is formatted using F-format.

The _gcvt function is identical to gcvt.  Use _gcvt for ANSI naming conventions.

The _wgcvt function is a wide character version of gcvt except that it produces a wide character string.
Returns:
The gcvt function returns a pointer to the string of digits.
See Also:
ecvt, fcvt, printf
Example:

#include <stdio.h>
#include <stdlib.h>

void main()
  {
    char buffer[80];

    printf( "%s\n", gcvt( -123.456789, 5, buffer ) );
    printf( "%s\n", gcvt( 123.456789E+12, 5, buffer ) );
  }

produces the following:

-123.46
1.2346E+014
Classification:
WATCOM
_gcvt conforms to ANSI naming conventions
Systems:
gcvt - Math
_gcvt - Math
_wgcvt - Math

_getactivepage

Synopsis:

#include <graph.h>
short _FAR _getactivepage( void );
Description:
The _getactivepage function returns the number of the currently selected active graphics page.
Only some combinations of video modes and hardware allow multiple pages of graphics to exist.  When multiple pages are supported, the active page may differ from the visual page.  The graphics information in the visual page determines what is displayed upon the screen.  Animation may be accomplished by alternating the visual page.  A graphics page can be constructed without affecting the screen by setting the active page to be different than the visual page.

The number of available video pages can be determined by using the _getvideoconfig function.  The default video page is 0.
Returns:
The _getactivepage function returns the number of the currently selected active graphics page.
See Also:
_setactivepage, _setvisualpage, _getvisualpage, _getvideoconfig
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int old_apage;
    int old_vpage;

    _setvideomode( _HRES16COLOR );
    old_apage = _getactivepage();
    old_vpage = _getvisualpage();
    /* draw an ellipse on page 0 */
    _setactivepage( 0 );
    _setvisualpage( 0 );
    _ellipse( _GFILLINTERIOR, 100, 50, 540, 150 );
    /* draw a rectangle on page 1 */
    _setactivepage( 1 );
    _rectangle( _GFILLINTERIOR, 100, 50, 540, 150 );
    getch();
    /* display page 1 */
    _setvisualpage( 1 );
    getch();
    _setactivepage( old_apage );
    _setvisualpage( old_vpage );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getarcinfo

Synopsis:

#include <graph.h>
short _FAR _getarcinfo( struct xycoord _FAR *start_pt,
                         struct xycoord _FAR *end_pt,
                         struct xycoord _FAR *inside_pt );
Description:
The _getarcinfo function returns information about the arc most recently drawn by the _arc or _pie functions.  The arguments start_pt and end_pt are set to contain the endpoints of the arc.  The argument inside_pt will contain the coordinates of a point within the pie.  The points are all specified in the view coordinate system.
The endpoints of the arc can be used to connect other lines to the arc.  The interior point can be used to fill the pie.
Returns:
The _getarcinfo function returns a non-zero value when successful.  If the previous arc or pie was not successfully drawn, zero is returned.
See Also:
_arc, _pie
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct xycoord start_pt, end_pt, inside_pt;

    _setvideomode( _VRES16COLOR );
    _arc( 120, 90, 520, 390, 520, 90, 120, 390 );
    _getarcinfo( &start_pt, &end_pt, &inside_pt );
    _moveto( start_pt.xcoord, start_pt.ycoord );
    _lineto( end_pt.xcoord, end_pt.ycoord );
    getch();
    _setvideomode( _DEFAULTMODE );
}

produces the following:

Classification:
PC Graphics
Systems:
DOS

_getbkcolor

Synopsis:

#include <graph.h>
long _FAR _getbkcolor( void );
Description:
The _getbkcolor function returns the current background color.  In text modes, the background color controls the area behind each individual character.  In graphics modes, the background refers to the entire screen.  The default background color is 0.
Returns:
The _getbkcolor function returns the current background color.
See Also:
_setbkcolor, _remappalette
Example:

#include <conio.h>
#include <graph.h>

long colors[ 16 ] = {
   _BLACK, _BLUE, _GREEN, _CYAN,
   _RED, _MAGENTA, _BROWN, _WHITE,
   _GRAY, _LIGHTBLUE, _LIGHTGREEN, _LIGHTCYAN,
   _LIGHTRED, _LIGHTMAGENTA, _YELLOW, _BRIGHTWHITE
};

main()
{
    long old_bk;
    int bk;

    _setvideomode( _VRES16COLOR );
    old_bk = _getbkcolor();
    for( bk = 0; bk < 16; ++bk ) {
        _setbkcolor( colors[ bk ] );
        getch();
    }
    _setbkcolor( old_bk );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

getc, getwc

Synopsis:

#include <stdio.h>
int getc( FILE *fp );
#include <stdio.h>
#include <wchar.h>
wint_t getwc( FILE *fp );
Description:
The getc function gets the next character from the file designated by fp.  The character is returned as an int value.  The getc function is equivalent to fgetc, except that it may be implemented as a macro.
The getwc function is identical to getc except that it gets the next multibyte character (if present) from the input stream pointed to by fp and converts it to a wide character.
Returns:
The getc function returns the next character from the input stream pointed to by fp.  If the stream is at end-of-file, the end-of-file indicator is set and getc returns EOF.  If a read error occurs, the error indicator is set and getc returns EOF.
The getwc function returns the next wide character from the input stream pointed to by fp.  If the stream is at end-of-file, the end-of-file indicator is set and getwc returns WEOF.  If a read error occurs, the error indicator is set and getwc returns WEOF.  If an encoding error occurs, errno is set to EILSEQ and getwc returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgetchar, fgets, fopen, getchar, gets, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( (c = getc( fp )) != EOF )
        putchar(c);
      fclose( fp );
    }
  }
Classification:
ISO C
Systems:
getc - All, Linux, RDOS, Netware
getwc - All, Linux

getch

Synopsis:

#include <conio.h>
int getch( void );
Description:
The getch function obtains the next available keystroke from the console.  Nothing is echoed on the screen (the function getche will echo the keystroke, if possible).  When no keystroke is available, the function waits until a key is depressed.
The kbhit function can be used to determine if a keystroke is available.
Returns:
A value of EOF is returned when an error is detected; otherwise the getch function returns the value of the keystroke (or character).
When the keystroke represents an extended function key (for example, a function key, a cursor-movement key or the ALT key with a letter or a digit), zero is returned and the next call to getch returns a value for the extended function.
See Also:
getche, kbhit, putch, ungetch
Example:

#include <stdio.h>
#include <conio.h>

void main()
  {
    int c;

    printf( "Press any key\n" );
    c = getch();
    printf( "You pressed %c(%d)\n", c, c );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

getchar, getwchar

Synopsis:

#include <stdio.h>
int getchar( void );
#include <wchar.h>
wint_t getwchar( void );
Description:
The getchar function is equivalent to getc with the argument stdin.
The getwchar function is similar to getchar except that it is equivalent to getwc with the argument stdin.
Returns:
The getchar function returns the next character from the input stream pointed to by stdin.  If the stream is at end-of-file, the end-of-file indicator is set and getchar returns EOF.  If a read error occurs, the error indicator is set and getchar returns EOF.
The getwchar function returns the next wide character from the input stream pointed to by stdin.  If the stream is at end-of-file, the end-of-file indicator is set and getwchar returns WEOF.  If a read error occurs, the error indicator is set and getwchar returns WEOF.  If an encoding error occurs, errno is set to EILSEQ and getwchar returns WEOF.

When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgetchar, fgets, fopen, getc, gets, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = freopen( "file", "r", stdin );
    while( (c = getchar()) != EOF )
      putchar(c);
    fclose( fp );
  }
Classification:
ISO C
Systems:
getchar - All, Linux, RDOS, Netware
getwchar - All, Linux

getche

Synopsis:

#include <conio.h>
int getche( void );
Description:
The getche function obtains the next available keystroke from the console.  The function will wait until a keystroke is available.  That character is echoed on the screen at the position of the cursor (use getch when it is not desired to echo the keystroke).
The kbhit function can be used to determine if a keystroke is available.
Returns:
A value of EOF is returned when an error is detected; otherwise, the getche function returns the value of the keystroke (or character).
When the keystroke represents an extended function key (for example, a function key, a cursor-movement key or the ALT key with a letter or a digit), zero is returned and the next call to getche returns a value for the extended function.
See Also:
getch, kbhit, putch, ungetch
Example:

#include <stdio.h>
#include <conio.h>

void main()
  {
    int c;

    printf( "Press any key\n" );
    c = getche();
    printf( "You pressed %c(%d)\n", c, c );
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_getcliprgn

Synopsis:

#include <graph.h>
void _FAR _getcliprgn( short _FAR *x1, short _FAR *y1,
                        short _FAR *x2, short _FAR *y2 );
Description:
The _getcliprgn function returns the location of the current clipping region.  A clipping region is defined with the _setcliprgn or _setviewport functions.  By default, the clipping region is the entire screen.
The current clipping region is a rectangular area of the screen to which graphics output is restricted.  The top left corner of the clipping region is placed in the arguments (x1,y1).  The bottom right corner of the clipping region is placed in (x2,y2).
Returns:
The _getcliprgn function returns the location of the current clipping region.
See Also:
_setcliprgn, _setviewport
Example:

#include <conio.h>
#include <graph.h>

main()
{
    short x1, y1, x2, y2;

    _setvideomode( _VRES16COLOR );
    _getcliprgn( &x1, &y1, &x2, &y2 );
    _setcliprgn( 130, 100, 510, 380 );
    _ellipse( _GBORDER, 120, 90, 520, 390 );
    getch();
    _setcliprgn( x1, y1, x2, y2 );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

getcmd

Synopsis:

#include <process.h>
char *getcmd( char *cmd_line );
Description:
The getcmd function causes the command line information, with the program name removed, to be copied to cmd_line.   The information is terminated with a null character.  This provides a method of obtaining the original parameters to a program unchanged (with the white space intact).
This information can also be obtained by examining the vector of program parameters passed to the main function in the program.
Returns:
The address of the target cmd_line is returned.
See Also:
abort, atexit, _bgetcmd, exec..., exit, _Exit, _exit, getenv, main, putenv, spawn..., system, _wsystem
Example:

Suppose a program were invoked with the command line
     
     myprog arg-1 ( my   stuff ) here

where that program contains

#include <stdio.h>
#include <process.h>

void main()
  {
    char cmds[128];

    printf( "%s\n", getcmd( cmds ) );
  }

produces the following:

  arg-1 ( my   stuff ) here
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_getcolor

Synopsis:

#include <graph.h>
short _FAR _getcolor( void );
Description:
The _getcolor function returns the pixel value for the current color.  This is the color used for displaying graphics output.  The default color value is one less than the maximum number of colors in the current video mode.
Returns:
The _getcolor function returns the pixel value for the current color.
See Also:
_setcolor
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int col, old_col;

    _setvideomode( _VRES16COLOR );
    old_col = _getcolor();
    for( col = 0; col < 16; ++col ) {
        _setcolor( col );
        _rectangle( _GFILLINTERIOR, 100, 100, 540, 380 );
        getch();
    }
    _setcolor( old_col );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getcurrentposition, _getcurrentposition_w

Synopsis:

#include <graph.h>
struct xycoord _FAR _getcurrentposition( void );

struct _wxycoord _FAR _getcurrentposition_w( void );
Description:
The _getcurrentposition functions return the current output position for graphics.  The _getcurrentposition function returns the point in view coordinates.  The _getcurrentposition_w function returns the point in window coordinates.
The current position defaults to the origin, (0,0), when a new video mode is selected.  It is changed by successful calls to the _arc, _moveto and _lineto functions as well as the _setviewport function.

Note that the output position for graphics output differs from that for text output.  The output position for text output can be set by use of the _settextposition function.
Returns:
The _getcurrentposition functions return the current output position for graphics.
See Also:
_moveto, _settextposition
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct xycoord old_pos;

    _setvideomode( _VRES16COLOR );
    old_pos = _getcurrentposition();
    _moveto( 100, 100 );
    _lineto( 540, 100 );
    _lineto( 320, 380 );
    _lineto( 100, 100 );
    _moveto( old_pos.xcoord, old_pos.ycoord );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_getcurrentposition - DOS
_getcurrentposition_w - DOS

getcwd, _wgetcwd

Synopsis:

#include <direct.h>
char *getcwd( char *buffer, size_t maxlen );
wchar_t *_wgetcwd( wchar_t *buffer, size_t maxlen );
Description:
The getcwd function returns the name of the current working directory.  The buffer address is either NULL or is the location at which a string containing the name of the current working directory is placed.  In the latter case, the value of maxlen is the length in characters (including the terminating null character) which can be be used to store this name.  An error occurs if the length of the path (including the terminating null character) exceeds maxlen.
The maximum size that might be required for buffer is PATH_MAX + 1 bytes.

Extension:  When buffer has a value of NULL, a string is allocated using malloc to contain the name of the current working directory.  This string may be freed using the free function.

The _wgetcwd function is a wide character version of getcwd that operates with wide character strings.   The maxlen is the length in wide characters (wchar_t).
Returns:
The getcwd function returns the address of the string containing the name of the current working directory, unless an error occurs, in which case NULL is returned.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
EINVAL
The argument maxlen is negative.

ENOMEM
Not enough memory to allocate a buffer.

ERANGE
The buffer is too small (specified by maxlen) to contain the name of the current working directory.
See Also:
chdir, chmod, _getdcwd, mkdir, rmdir
Example:

#include <stdio.h>
#include <stdlib.h>
#include <direct.h>

void main()
  {
    char *cwd;

    cwd = getcwd( NULL, 0 );
    if( cwd != NULL ) {
      printf( "My working directory is %s\n", cwd );
      free( cwd );
    }
  }

produces the following:

My working directory is C:\PROJECT\C
Classification:
POSIX 1003.1 with extensions
_wgetcwd is WATCOM
Systems:
getcwd - All, Linux, RDOS, Netware
_wgetcwd - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

_getdcwd, _wgetdcwd

Synopsis:

#include <direct.h>
char *_getdcwd( int drive, char *buffer, size_t maxlen );
wchar_t *_wgetdcwd( int drive, wchar_t *buffer, size_t maxlen );
Description:
The _getdcwd function gets the full path of the current working directory on the specified drive.  The drive argument specifies the drive (0 = default drive, 1 = A, 2 = B, etc.).  The buffer address is either NULL or is the location at which a string containing the name of the current working directory is placed.  In the latter case, the value of maxlen is the length in characters (including the terminating null character) which can be be used to store this name.  An error occurs if the length of the path (including the terminating null character) exceeds maxlen.
The maximum size that might be required for buffer is PATH_MAX + 1 bytes.

When buffer has a value of NULL, a string is allocated using malloc to contain the name of the current working directory.  This string may be freed using the free function.

The _wgetdcwd function is a wide character version of _getdcwd that operates with wide character strings.  The maxlen is the length in wide characters (wchar_t).
Returns:
The _getdcwd function returns the address of the string containing the name of the current working directory on the specified drive, unless an error occurs, in which case NULL is returned.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
Constant     Meaning
ENODEV
The drive cannot be accessed.

ENOMEM
Not enough memory to allocate a buffer.

ERANGE
The buffer is too small (specified by size) to contain the name of the current working directory.
See Also:
chdir, chmod, getcwd, mkdir, rmdir
Example:

#include <stdio.h>
#include <stdlib.h>
#include <direct.h>

void main()
  {
    char *cwd;

    cwd = _getdcwd( 3, NULL, 0 );
    if( cwd != NULL ) {
      printf( "The current directory on drive C is %s\n",
              cwd );
      free( cwd );
    }
  }

produces the following:

The current directory on drive C is C:\PROJECT\C
Classification:
WATCOM
Systems:
_getdcwd - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS
_wgetdcwd - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

getdelim

Synopsis:

#include <stdio.h>
ssize_t getdelim( char **line, size_t *n, int delim, FILE *fp );
Description:
The getdelim function reads in text from a stream fp up to and including a delimiter delim and returns the resulting text in a buffer pointed to by line when complete.  The buffer pointed to by line should be of the size pointed to by n initially.
The buffer pointed to by line can initially be null and n should reflect the size of line and be set to null.  When getdelim is invoked, it will check if the buffer pointed to by line is allocated and large enough.  If not, it will first call realloc to resize the buffer appropriately and adjust the value pointed to by n to reflect the new size of line after reallocation.  If allocation fails, errno will be set to ENOMEM.
Returns:
The function returns the number of characters read into the buffer or -1 on either error or if no further data is available.
Example:

The following program would print out each line in a text file "test.txt" .

#include <stdio.h>

int main( void )
  {
    char *line = NULL;
    size_t n = 0;
    FILE *fp;

    fp = fopen("test.txt", "r");
    while(getdelim(&line, &n, '\n', fp) >= 0) {
        printf("> %s", line);
    }
    fclose(fp);
    return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

_getdiskfree

Synopsis:

#include <direct.h>
unsigned _getdiskfree( unsigned drive,
                         struct diskfree_t *diskspace );
struct diskfree_t {
    unsigned short  total_clusters;
    unsigned short  avail_clusters;
    unsigned short  sectors_per_cluster;
    unsigned short  bytes_per_sector;
};
Description:
The _getdiskfree function uses system call 0x36 to obtain useful information on the disk drive specified by drive.   Specify 0 for the default drive, 1 for drive A, 2 for drive B, etc.  The information about the drive is returned in the structure diskfree_t pointed to by diskspace.
Returns:
The _getdiskfree function returns zero if successful.  Otherwise, it returns a non-zero value and sets errno to EINVAL indicating an invalid drive was specified.
See Also:
_dos_getdiskfree, _dos_getdrive, _dos_setdrive, _getdrive
Example:

#include <stdio.h>
#include <direct.h>

void main()
  {
    struct diskfree_t disk_data;

    /* get information about drive 3 (the C drive) */
    if( _getdiskfree( 3, &disk_data ) == 0 ) {
      printf( "total clusters: %u\n",
                         disk_data.total_clusters );
      printf( "available clusters: %u\n",
                         disk_data.avail_clusters );
      printf( "sectors/cluster: %u\n",
                         disk_data.sectors_per_cluster );
      printf( "bytes per sector: %u\n",
                         disk_data.bytes_per_sector );
    } else {
      printf( "Invalid drive specified\n" );
    }
  }

produces the following:

total clusters: 16335
available clusters: 510
sectors/cluster: 4
bytes per sector: 512
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

_getdrive

Synopsis:

#include <direct.h>
int _getdrive( void );
Description:
The _getdrive function returns the current (default) drive number.
Returns:
A value of 1 is drive A, 2 is drive B, 3 is drive C, etc.
See Also:
_dos_getdiskfree, _dos_getdrive, _dos_setdrive, _getdiskfree
Example:

#include <stdio.h>
#include <direct.h>

void main( void )
{
    printf( "The current drive is %c\n",
                'A' + _getdrive() - 1 );
}

produces the following:

The current drive is C
Classification:
DOS
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

getegid

Synopsis:

#include <unistd.h>
gid_t getegid( void );
Description:
The getegid function returns the efective group ID for the current process.
Returns:
The efective group ID for the current process.
See Also:
getgid, getuid, geteuid
Example:

/*
* Print the effective group ID of the process.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
     printf( "My effective group ID is %d\n", getegid() );
     return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

getenv, _wgetenv

Synopsis:

#include <stdlib.h>
char *getenv( const char *name );
wchar_t *_wgetenv( const wchar_t *name );
Safer C:
The Safer C Library extension provides the getenv_s function which is a safer alternative to getenv.   This newer getenv_s function is recommended to be used instead of the traditional "unsafe" getenv function.
Description:
The getenv function searches the environment list for an entry matching the string pointed to by name.  The matching is case-insensitive; all lowercase letters are treated as if they were in upper case.
Entries can be added to the environment list with the DOS set command or with the putenv or setenv functions.  All entries in the environment list can be displayed by using the DOS set command with no arguments.

To assign a string to a variable and place it in the environment list:

     
         C>SET INCLUDE=C:\WATCOM\H

To see what variables are in the environment list, and their current assignments:

     
         C>SET
         COMSPEC=C:\COMMAND.COM
         PATH=C:\;C:\WATCOM
         INCLUDE=C:\WATCOM\H

The _wgetenv function is a wide character version of getenv that operates with wide character strings.
Returns:
The getenv function returns a pointer to the string assigned to the environment variable if found, and NULL if no match was found.  Note:  the value returned should be duplicated if you intend to modify the contents of the string.
See Also:
exec..., _wexec..., clearenv, getenv_s, putenv, _searchenv, setenv, unsetenv, _wgetenv, _wputenv, _wsearchenv, _wsetenv, _wunsetenv, spawn..., _wspawn..., system, _wsystem
Example:

#include <stdio.h>
#include <stdlib.h>

void main( void )
{
    char *path;

    path = getenv( "INCLUDE" );
    if( path != NULL )
        printf( "INCLUDE=%s\n", path );
}
Classification:
ISO C
_wgetenv is WATCOM
Systems:
getenv - All, Linux, RDOS, Netware
_wgetenv - All, Linux

getenv_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
errno_t getenv_s( size_t * restrict len,
                  char * restrict value,
                  rsize_t maxsize,
                  const char * restrict name );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and getenv_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
name shall not be a null pointer.  maxsize shall neither be equal to zero nor be greater than RSIZE_MAX.  If maxsize is not equal to zero, then value shall not be a null pointer.

If there is a runtime-constraint violation, the integer pointed to by len (if len is not null) is set to zero, and the environment list is not searched.
Description:
The getenv_s function searches the environment list for an entry matching the string pointed to by name.
If that entry is found, getenv_s performs the following actions.  If len is not a null pointer, the length of the string associated with the matched entry is stored in the integer pointed to by len.  If the length of the associated string is less than maxsize, then the associated string is copied to the array pointed to by value.

If that entry is not found, getenv_s performs the following actions.  If len is not a null pointer, zero is stored in the integer pointed to by len.  If maxsize is greater than zero, then value[0] is set to the null character.

The matching is case-insensitive; all lowercase letters are treated as if they were in upper case.

Entries can be added to the environment list with the DOS set command or with the putenv or setenv functions.  All entries in the environment list can be displayed by using the DOS set command with no arguments.

To assign a string to a variable and place it in the environment list:

     
         C>SET INCLUDE=C:\WATCOM\H

To see what variables are in the environment list, and their current assignments:

     
         C>SET
         COMSPEC=C:\COMMAND.COM
         PATH=C:\;C:\WATCOM
         INCLUDE=C:\WATCOM\H
Returns:
The getenv_s function returns zero if the environment string specified by name was found and successfully stored in the buffer pointed to by value.  Otherwise, a non-zero value is returned.
See Also:
exec..., _wexec..., clearenv, getenv, putenv, _searchenv, setenv, unsetenv, _wgetenv, _wputenv, _wsearchenv, _wsetenv, _wunsetenv, spawn..., _wspawn..., system, _wsystem
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
#include <stdio.h>

void main( void )
{
    char    buffer[128];
    size_t  len;

    if( getenv_s( &len, buffer, sizeof( buffer ), "INCLUDE" ) == 0 )
        printf( "INCLUDE=%s\n", buffer );
}
Classification:
TR 24731
Systems:
All, Linux, RDOS, Netware

geteuid

Synopsis:

#include <unistd.h>
uid_t geteuid( void );
Description:
The geteuid function returns the efective user ID for the calling process.
Returns:
The efective user ID for the calling process
See Also:
getuid, getgid, getegid
Example:

/*
* Print the effective user ID of the process.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
    printf( "My effective user ID is %d\n", geteuid() );
    return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

_getfillmask

Synopsis:

#include <graph.h>
unsigned char _FAR * _FAR
    _getfillmask( unsigned char _FAR *mask );
Description:
The _getfillmask function copies the current fill mask into the area located by the argument mask.  The fill mask is used by the _ellipse, _floodfill, _pie, _polygon and _rectangle functions that fill an area of the screen.
The fill mask is an eight-byte array which is interpreted as a square pattern (8 by 8) of 64 bits.  Each bit in the mask corresponds to a pixel.  When a region is filled, each point in the region is mapped onto the fill mask.  When a bit from the mask is one, the pixel value of the corresponding point is set using the current plotting action with the current color; when the bit is zero, the pixel value of that point is not affected.

When the fill mask is not set, a fill operation will set all points in the fill region to have a pixel value of the current color.
Returns:
If no fill mask has been set, NULL is returned; otherwise, the _getfillmask function returns mask.
See Also:
_floodfill, _setfillmask, _setplotaction
Example:

#include <conio.h>
#include <graph.h>

char old_mask[ 8 ];
char new_mask[ 8 ] = { 0x81, 0x42, 0x24, 0x18,
                        0x18, 0x24, 0x42, 0x81 };

main()
{
    _setvideomode( _VRES16COLOR );
    _getfillmask( old_mask );
    _setfillmask( new_mask );
    _rectangle( _GFILLINTERIOR, 100, 100, 540, 380 );
    _setfillmask( old_mask );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getfontinfo

Synopsis:

#include <graph.h>
short _FAR _getfontinfo( struct _fontinfo _FAR *info );
Description:
The _getfontinfo function returns information about the currently selected font.  Fonts are selected with the _setfont function.  The font information is returned in the _fontinfo structure indicated by the argument info.  The structure contains the following fields:
type
1 for a vector font, 0 for a bit-mapped font

ascent
distance from top of character to baseline in pixels

pixwidth
character width in pixels (0 for a proportional font)

pixheight
character height in pixels

avgwidth
average character width in pixels

filename
name of the file containing the current font

facename
name of the current font
Returns:
The _getfontinfo function returns zero if the font information is returned successfully; otherwise a negative value is returned.
See Also:
_registerfonts, _unregisterfonts, _setfont, _outgtext, _getgtextextent, _setgtextvector, _getgtextvector
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int width;
    struct _fontinfo info;

    _setvideomode( _VRES16COLOR );
    _getfontinfo( &info );
    _moveto( 100, 100 );
    _outgtext( "WATCOM Graphics" );
    width = _getgtextextent( "WATCOM Graphics" );
    _rectangle( _GBORDER, 100, 100,
                100 + width, 100 + info.pixheight );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

getgid

Synopsis:

#include <unistd.h>
gid_t getgid( void );
Description:
The getgid function returns the group ID for the current process.
Returns:
The group ID for the current process.
See Also:
getuid, geteuid, getegid
Example:

/*
* Print the group ID of the process.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
     printf( "I belong to group ID %d\n", getgid() );
     return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

_getgtextextent

Synopsis:

#include <graph.h>
short _FAR _getgtextextent( char _FAR *text );
Description:
The _getgtextextent function returns the length in pixels of the argument text as it would be displayed in the current font by the function _outgtext.  Note that the text is not displayed on the screen, only its length is determined.
Returns:
The _getgtextextent function returns the length in pixels of a string.
See Also:
_registerfonts, _unregisterfonts, _setfont, _getfontinfo, _outgtext, _setgtextvector, _getgtextvector
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int width;
    struct _fontinfo info;

    _setvideomode( _VRES16COLOR );
    _getfontinfo( &info );
    _moveto( 100, 100 );
    _outgtext( "WATCOM Graphics" );
    width = _getgtextextent( "WATCOM Graphics" );
    _rectangle( _GBORDER, 100, 100,
                100 + width, 100 + info.pixheight );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getgtextvector

Synopsis:

#include <graph.h>
struct xycoord _FAR _getgtextvector( void );
Description:
The _getgtextvector function returns the current value of the text orientation vector.  This is the direction used when text is displayed by the _outgtext function.
Returns:
The _getgtextvector function returns, as an xycoord structure, the current value of the text orientation vector.
See Also:
_registerfonts, _unregisterfonts, _setfont, _getfontinfo, _outgtext, _getgtextextent, _setgtextvector
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct xycoord old_vec;

    _setvideomode( _VRES16COLOR );
    old_vec = _getgtextvector();
    _setgtextvector( 0, -1 );
    _moveto( 100, 100 );
    _outgtext( "WATCOM Graphics" );
    _setgtextvector( old_vec.xcoord, old_vec.ycoord );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

gethostbyaddr

Synopsis:

#include <netdb.h>
struct hostent *gethostbyaddr( const void *addr,
                                socklen_t len,
                                int type );
Description:
The gethostbyaddr function searches the system's network host database for a host matching the addr argument.   The address should be specified in network byte order.  The len argument specifies the length in bytes of the addr argument, and type specifies the address type.  Accepted types, such as AF_INET or AF_INET6, are expected.  The routine will query only the local network hosts database.
The structure returned is defined as:

struct hostent {
    char    *h_name;       /* host official name                */
    char    **h_aliases;   /* host alternate names, up to 16,
                               terminated by a NULL pointer     */
    int     h_length;      /* address length in bytes           */
    char    **h_addr_list; /* array of pointers to network
                               addresses in network byte order,
                               terminated by a NULL pointer     */
};

The pointer returned by gethostbyaddr points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a matching host is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
If the host is found, the h_name member will be the defintive name of the host, and h_aliases will contain a NULL-terminated list of aliases.  The addresses are contained in the h_addr_list member as a NULL-terminated list, and this structure entry will never be NULL.

If no matching host is found or an error occurs, the return value will be NULL.
See Also:
gethostent, gethostbyname
Classification:
POSIX 1003.1
Systems:
Linux

gethostbyname

Synopsis:

#include <netdb.h>
struct hostent *gethostbyname( const char *name );
Description:
The gethostbyname function determines the address or addresses of a host specified by the name argument.  The routine will query the local database initially.  If not found, the routine will perform a DNS query, returning all "A" records for the given host name.
The structure returned is defined as:

struct hostent {
    char    *h_name;       /* host official name                */
    char    **h_aliases;   /* host alternate names, up to 16,
                               terminated by a NULL pointer     */
    int     h_length;      /* address length in bytes           */
    char    **h_addr_list; /* array of pointers to network
                               addresses in network byte order,
                               terminated by a NULL pointer     */
};

In the current Open Watcom implementation, this routine will only ever return IPv4 addresses, and all addresses will be of AF_INET address type.

The pointer returned by gethostbyname points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a matching host is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
If the host is found, the h_name member will be a copy of the name argument.  The addresses are contained in the h_addr_list member as a NULL-terminated list, and this structure entry will never be NULL.

If no matching host is found or an error occurs, the return value will be NULL.
See Also:
gethostent, gethostbyaddr
Example:

The following program will attempt to determine the address of a hostname passed as an argument.

#include <stdio.h>
#include <netdb.h>
#include <arpa/inet.h>

int main(int argc, char *argv[])
  {
    int i;
    struct hostent *he;
    struct in_addr **addr_list;

    if (argc != 2) {
        fprintf(stderr,"usage: %s <hostname>\n", argv[0]);
        return 1;
    }

    if ((he = gethostbyname(argv[1])) == NULL) {  // get the host info
        printf("Failed to find %s\n", argv[1]);
        return 2;
    }

    printf("IP addresses for %s:\n", argv[1]);
    addr_list = (struct in_addr **)he->h_addr_list;
    for(i = 0; addr_list[i] != NULL; i++) {
        printf("    %s\n", inet_ntoa(*addr_list[i]));
    }

    return 0;
  }
Classification:
POSIX 1003.1
Systems:
Linux

gethostent

Synopsis:

#include <netdb.h>
struct hostent *gethostent( void );
Description:
The gethostent function reads, parses, and returns entries from the network host database at /etc/hosts.  The first call will return the first entry, and subsequent calls return subsequent entries.  A null pointer is returned if either an error is encountered or no further entries exist.
If a call to sethostent was not first made, the gethostent function will open the database if necessary initially.  By default, this will always return the first entry in the database.

The structure returned is defined as:

struct hostent {
    char    *h_name;       /* host official name                */
    char    **h_aliases;   /* host alternate names, up to 16,
                               terminated by a NULL pointer     */
    int     h_length;      /* address length in bytes           */
    char    **h_addr_list; /* array of pointers to network
                               addresses in network byte order,
                               terminated by a NULL pointer     */
};

In the current Open Watcom implementation, this routine will only ever return IPv4 addresses, and all addresses will be of AF_INET address type.

The pointer returned by gethostent points to a static location, and the user should free neither the pointer itself nor any of its consituent structure members.

This function is not thread-safe.  Other calls to functions accessing the hostname database may affect the return value from this function.
Returns:
A parsed host database entry, or NULL if no further entries exist or an error occurred.
See Also:
sethostent, endhostent
Example:

The following program will print out each user and their user ID in the system's password database

#include <stdio.h>
#include <netdb.h>
#include <arpa/inet.h>

int main(int argc, char *argv[])
  {
  struct hostent *e;

    sethostent(1);
    e = gethostent();
    while(e != NULL) {
        char *ia = e->h_addr_list[0];
        printf("%s - %d.%d.%d.%d\n",
               e->h_name,
               ia[0],ia[1],ia[2],ia[3]

        );
        e = gethostent();
    }

    endhostent();
    return 0;
  }
Classification:
POSIX 1003.1
Systems:
Linux

_getimage, _getimage_w, _getimage_wxy

Synopsis:

#include <graph.h>
void _FAR _getimage( short x1, short y1,
                      short x2, short y2,
                      char _HUGE *image );

void _FAR _getimage_w( double x1, double y1,
                        double x2, double y2,
                        char _HUGE *image );

void _FAR _getimage_wxy( struct _wxycoord _FAR *p1,
                          struct _wxycoord _FAR *p2,
                          char _HUGE *image );
Description:
The _getimage functions store a copy of an area of the screen into the buffer indicated by the image argument.   The _getimage function uses the view coordinate system.  The _getimage_w and _getimage_wxy functions use the window coordinate system.
The screen image is the rectangular area defined by the points (x1,y1) and (x2,y2).  The buffer image must be large enough to contain the image (the size of the image can be determined by using the _imagesize function).  The image may be displayed upon the screen at some later time by using the _putimage functions.
Returns:
The _getimage functions do not return a value.
See Also:
_imagesize, _putimage
Example:

#include <conio.h>
#include <graph.h>
#include <malloc.h>

main()
{
    char *buf;
    int y;

    _setvideomode( _VRES16COLOR );
    _ellipse( _GFILLINTERIOR, 100, 100, 200, 200 );
    buf = (char*) malloc(
                  _imagesize( 100, 100, 201, 201 ) );
    if( buf != NULL ) {
        _getimage( 100, 100, 201, 201, buf );
        _putimage( 260, 200, buf, _GPSET );
        _putimage( 420, 100, buf, _GPSET );
        for( y = 100; y < 300; ) {
            _putimage( 420, y, buf, _GXOR );
            y += 20;
            _putimage( 420, y, buf, _GXOR );
        }
        free( buf );
    }
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_getimage - DOS
_getimage_w - DOS
_getimage_wxy - DOS

getline

Synopsis:

#include <stdio.h>
ssize_t getline( char **line, size_t *n, FILE *fp );
Description:
The getline function reads a single line of text from a stream fp and returns the resulting text, including any new line characters, in a buffer pointed to by line when complete.  The buffer pointed to by line should be of the size pointed to by n initially.
The buffer pointed to by line can initially be null and n should reflect the size of line and be set to 0.  When getline is invoked, it will check if the buffer pointed to by line is allocated and large enough.  If not, it will first call realloc to resize the buffer appropriately and adjust the value pointed to by n to reflect the new size of line after reallocation.  If allocation fails, errno will be set to ENOMEM.
Returns:
The function returns the number of characters read into the buffer or -1 on either error or if no further data is available.
Example:

The following program would print out each line in a text file "test.txt"

#include <stdio.h>

int main( void )
  {
    char *line = NULL;
    size_t n = 0;
    FILE *fp;

    fp = fopen("test.txt", "r");
    while(getline(&line, &n, fp) >= 0) {
        printf("> %s", line);
    }
    fclose(fp);
    return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
All, Linux, RDOS, Netware

_getlinestyle

Synopsis:

#include <graph.h>
unsigned short _FAR _getlinestyle( void );
Description:
The _getlinestyle function returns the current line-style mask.
The line-style mask determines the style by which lines and arcs are drawn.  The mask is treated as an array of 16 bits.  As a line is drawn, a pixel at a time, the bits in this array are cyclically tested.  When a bit in the array is 1, the pixel value for the current point is set using the current color according to the current plotting action; otherwise, the pixel value for the point is left unchanged.  A solid line would result from a value of 0xFFFF and a dashed line would result from a value of 0xF0F0

The default line style mask is 0xFFFF
Returns:
The _getlinestyle function returns the current line-style mask.
See Also:
_lineto, _pie, _rectangle, _polygon, _setlinestyle
Example:

#include <conio.h>
#include <graph.h>

#define DASHED 0xf0f0

main()
{
    unsigned old_style;

    _setvideomode( _VRES16COLOR );
    old_style = _getlinestyle();
    _setlinestyle( DASHED );
    _rectangle( _GBORDER, 100, 100, 540, 380 );
    _setlinestyle( old_style );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getmbcp

Synopsis:

#include <mbctype.h>
int _getmbcp( void );
Description:
The _getmbcp function returns the current multibyte code page number.
Returns:
The _getmbcp function returns the current multibyte code page.  A return value of zero indicates that a single-byte character code page is in use.
See Also:
_mbbtombc, _mbcjistojms, _mbcjmstojis, _mbctombb, _ismbbalnum, _ismbbalpha, _ismbbgraph, _ismbbkalnum, _ismbbkalpha, _ismbbkana, _ismbbkprint, _ismbbkpunct, _ismbblead, _ismbbprint, _ismbbpunct, _ismbbtrail, _mbbtombc, _mbcjistojms, _mbcjmstojis, _mbctombb, _mbbtype, _mbsbtype, _setmbcp
Example:

#include <stdio.h>
#include <mbctype.h>

void main()
  {
    printf( "%d\n", _setmbcp( 932 ) );
    printf( "%d\n", _getmbcp() );
  }

produces the following:

0
932
Classification:
WATCOM
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, RDOS

getnetbyaddr

Synopsis:

#include <netdb.h>
struct netent *getnetbyaddr( in_addr_t net, int type );
Description:
The getnetbyaddr function searches the network database for a network with a matching address type, specified by type as AF_INET, AF_INET6, etc., and address matching the net argument.  The function returns information about said network if a match is found.  The routine will query the local database only.
The structure returned is defined as:

struct netent {
    char        *n_name;        /* official network name */
    char        **n_aliases;    /* alias list             */
    int         n_addrtype;     /* address type          */
    uint32_t    n_net;          /* network number        */
};

The pointer returned by getnetbyaddr points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a matching host is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said network are contained in the n_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no matching host is found or an error occurs, the return value will be NULL.
See Also:
getnetent, getnetbyname
Classification:
POSIX 1003.1
Systems:
Linux

getnetbyname

Synopsis:

#include <netdb.h>
struct netent *getnetbyname( const char *name );
Description:
The getnetbyname function searches the network database for a network name and returns information about said network if a match is found.  The routine will query the local database only.
The structure returned is defined as:

struct netent {
    char        *n_name;        /* official network name */
    char        **n_aliases;    /* alias list             */
    int         n_addrtype;     /* address type          */
    uint32_t    n_net;          /* network number        */
};

The pointer returned by getnetbyname points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a matching host is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The addresses are contained in the n_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no matching host is found or an error occurs, the return value will be NULL.
See Also:
getnetent, getnetbyaddr
Classification:
POSIX 1003.1
Systems:
Linux

getnetent

Synopsis:

#include <netdb.h>
struct netent *getnetent( void );
Description:
The getnetent function retrieves the next entry in the network database.  If not proceeded by an appropriate call to setnetent, the function will always return the first network in the database.  The routine will query the local database only.
The structure returned is defined as:

struct netent {
    char        *n_name;        /* official network name */
    char        **n_aliases;    /* alias list             */
    int         n_addrtype;     /* address type          */
    uint32_t    n_net;          /* network number        */
};

The pointer returned by getnetent points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If the database contains more entries, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said network are contained in the n_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no additional network is found or an error occurs, the return value will be NULL.
See Also:
setnetent, endnetent, getnetbyname, getnetbyaddr
Classification:
POSIX 1003.1
Systems:
Linux

getopt

Synopsis:

#include <unistd.h>
int getopt( int argc, char * const argv[],
            const char *optstring );

char   *optarg;
int    optind, opterr, optopt;
Description:
The getopt function is a command-line parser that can be used by applications that follow Utility Syntax Guidelines 3, 4, 5, 6, 7, 9 and 10 in the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
The parameters argc and argv are the argument count and argument array as passed to main.   The argument optstring is a string of recognised option characters; if a character is followed by a colon, the option takes an argument.  All option characters allowed by Utility Syntax Guideline 3 are allowed in optstring.

The global variable optind is the index of the next element of the argv[] vector to be processed.   It is initialised to 1 by the system, and getopt updates it when it finishes with each element of argv[].   When an element of argv[] contains multiple option characters, getopt uses a static variable to determine which options have already been processed.

The getopt function returns the next option character (if one is found) from argv that matches a character in optstring, if there is one that matches.  If the option takes an argument, getopt sets the variable optarg to point to the option-argument as follows:

If the option was the last character in the string pointed to by an element of argv, then optarg contains the next element of argv, and optind is incremented by 2.  If the resulting value of optind is not less than argc, this indicates a missing option-argument, and getopt returns an error indication.

Otherwise, optarg points to the string following the option character in that element of argv, and optind is incremented by 1.

If, when getopt is called:
getopt returns -1 without changing optind.  If argv[optind] points to the string "--", getopt returns -1 after incrementing optind.

If getopt encounters an option character that is not contained in optstring, it returns the question-mark (?) character.  If it detects a missing option-argument, it returns the colon character (:) if the first character of optstring was a colon, or a question-mark character (?) otherwise.  In either case, getopt will set the global variable optopt to the option character that caused the error.  If the application has not set the global variable opterr to 0 and the first character of optstring is not a colon, getopt also prints a diagnostic message to stderr.

The getopt function is not re-entrant and hence not thread-safe.
Returns:
The getopt function returns the next option character specified on the command line.
A colon (:) is returned if getopt detects a missing argument and the first character of optstring was a colon (:).

A question mark (?) is returned if getopt encounters an option character not in optstring or detects a missing argument and the first character of optstring was not a colon (:).

Otherwise, getopt returns -1 when all command line options are parsed.
See Also:
abort, atexit, _bgetcmd, exec..., exit, _Exit, _exit, getcmd, getenv, main, putenv, spawn..., system, _wsystem
Example:

#include <stdio.h>
#include <unistd.h>

int main( int argc, char **argv )
{
    int     c;
    char    *ifile;
    char    *ofile;

    while( (c = getopt( argc, argv, ":abf:o:" )) != -1 ) {
        switch( c ) {
        case 'a':
            printf( "option a is set\n" );
            break;
        case 'b':
            printf( "option b is set\n" );
            break;
        case 'f':
            ifile = optarg;
            printf( "input filename is '%s'\n", ifile );
            break;
        case 'o':
            ofile = optarg;
            printf( "output filename is '%s'\n", ofile );
            break;
        case ':':
            printf( "-%c without filename\n", optopt );
            break;
        case '?':
            printf( "usage: %s -ab -f <filename> -o <filename>\n", argv[0] );
            break;
        }
    }
    return( 0 );
}

produces the following:

option a is set
input filename is 'in'
output filename is 'out'

when the program is executed with the command

<program name> -afin -o out
Classification:
POSIX 1003.1
Systems:
All, Linux

_get_osfhandle

Synopsis:

#include <io.h>
long _get_osfhandle( int posixhandle );
Description:
The _get_osfhandle function returns the operating system's internal file handle that corresponds to the POSIX-level file handle specified by posixhandle.
The value returned by _get_osfhandle can be used as an argument to the _open_osfhandle function which can be used to connect a second POSIX-level handle to an open file.

The example below demonstrates the use of these two functions.  Note that the example shows how the dup2 function can be used to obtain almost identical functionality.

When the POSIX-level file handles associated with one OS file handle are closed, the first one closes successfully but the others return an error (since the first call close the file and released the OS file handle).  So it is important to call close at the right time, i.e., after all I/O operations are completed to the file.
Returns:
If successful, _get_osfhandle returns an operating system file handle corresponding to posixhandle.  Otherwise, it returns -1 and sets errno to EBADF, indicating an invalid file handle.
See Also:
close, dup2, fdopen, _hdopen, open, _open_osfhandle, _os_handle
Example:

#include <stdio.h>
#include <stdlib.h>
#include <io.h>
#include <fcntl.h>

void main()
{
    long os_handle;
    int fh1, fh2, rc;

    fh1 = open( "file",
                O_WRONLY | O_CREAT | O_TRUNC | O_BINARY,
                S_IRUSR | S_IWUSR | S_IRGRP | S_IWGRP );
    if( fh1 == -1 ) {
        printf( "Could not open output file\n" );
        exit( EXIT_FAILURE );
    }
    printf( "First POSIX handle %d\n", fh1 );

#if defined(USE_DUP2)
    fh2 = 6;
    if( dup2( fh1, fh2 ) == -1 ) fh2 = -1;
#else
    os_handle = _get_osfhandle( fh1 );
    printf( "OS Handle %ld\n", os_handle );

    fh2 = _open_osfhandle( os_handle, O_WRONLY |
                                       O_BINARY );
#endif
    if( fh2 == -1 ) {
        printf( "Could not open with second handle\n" );
        exit( EXIT_FAILURE );
    }
    printf( "Second POSIX handle %d\n", fh2 );

    rc = write( fh2, "trash\x0d\x0a", 7 );
    printf( "Write file using second handle %d\n", rc );

    rc = close( fh2 );
    printf( "Closing second handle %d\n", rc );
    rc = close( fh1 );
    printf( "Closing first handle %d\n", rc );
}
Classification:
WATCOM
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux, Netware

getpgrp

Synopsis:

#include <unistd.h>
gid_t getpgrp( void );
Description:
The getpgrp function returns the process group ID for the current process.
Returns:
The process group ID for the current process.
See Also:
getuid, geteuid, getegid
Example:

/*
* Print the process group ID of the process.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
     printf( "I belong to group ID %d\n", getpgrp() );
     return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

_getphyscoord

Synopsis:

#include <graph.h>
struct xycoord _FAR _getphyscoord( short x, short y );
Description:
The _getphyscoord function returns the physical coordinates of the position with view coordinates (x,y).   View coordinates are defined by the _setvieworg and _setviewport functions.
Returns:
The _getphyscoord function returns the physical coordinates, as an xycoord structure, of the given point.
See Also:
_getviewcoord, _setvieworg, _setviewport
Example:

#include <conio.h>
#include <graph.h>
#include <stdlib.h>

main()
{
    struct xycoord pos;

    _setvideomode( _VRES16COLOR );
    _setvieworg( rand() % 640, rand() % 480 );
    pos = _getphyscoord( 0, 0 );
    _rectangle( _GBORDER, - pos.xcoord, - pos.ycoord,
                    639 - pos.xcoord, 479 - pos.ycoord );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

getpid, _getpid

Synopsis:

#include <unistd.h>
pid_t getpid( void );
pid_t _getpid( void );
Description:
The getpid function returns the process ID for the current process.
Returns:
The process ID for the current process.
See Also:
getppid, gettid
Example:

/*
* print out the ID of this process
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
    printf( "I'm process %d\n", getpid() );
    return( 0 );
  }
Classification:
POSIX 1003.1
_getpid is WATCOM
Systems:
getpid - All, Linux, RDOS
_getpid - All, Linux, RDOS

_getpixel, _getpixel_w

Synopsis:

#include <graph.h>
short _FAR _getpixel( short x, short y );

short _FAR _getpixel_w( double x, double y );
Description:
The _getpixel functions return the pixel value for the point with coordinates (x,y).  The _getpixel function uses the view coordinate system.  The _getpixel_w function uses the window coordinate system.
Returns:
The _getpixel functions return the pixel value for the given point when the point lies within the clipping region; otherwise, (-1) is returned.
See Also:
_setpixel
Example:

#include <conio.h>
#include <graph.h>
#include <stdlib.h>

main()
{
    int x, y;
    unsigned i;

    _setvideomode( _VRES16COLOR );
    _rectangle( _GBORDER, 100, 100, 540, 380 );
    for( i = 0; i <= 60000; ++i ) {
        x = 101 + rand() % 439;
        y = 101 + rand() % 279;
        _setcolor( _getpixel( x, y ) + 1 );
        _setpixel( x, y );
    }
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_getpixel - DOS
_getpixel_w - DOS

_getplotaction

Synopsis:

#include <graph.h>
short _FAR _getplotaction( void );
Description:
The _getplotaction function returns the current plotting action.
The drawing functions cause pixels to be set with a pixel value.  By default, the value to be set is obtained by replacing the original pixel value with the supplied pixel value.  Alternatively, the replaced value may be computed as a function of the original and the supplied pixel values.

The plotting action can have one of the following values:
_GPSET
replace the original screen pixel value with the supplied pixel value

_GAND
replace the original screen pixel value with the bitwise and of the original pixel value and the supplied pixel value

_GOR
replace the original screen pixel value with the bitwise or of the original pixel value and the supplied pixel value

_GXOR
replace the original screen pixel value with the bitwise exclusive-or of the original pixel value and the supplied pixel value.  Performing this operation twice will restore the original screen contents, providing an efficient method to produce animated effects.
Returns:
The _getplotaction function returns the current plotting action.
See Also:
_setplotaction
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int old_act;

    _setvideomode( _VRES16COLOR );
    old_act = _getplotaction();
    _setplotaction( _GPSET );
    _rectangle( _GFILLINTERIOR, 100, 100, 540, 380 );
    getch();
    _setplotaction( _GXOR );
    _rectangle( _GFILLINTERIOR, 100, 100, 540, 380 );
    getch();
    _setplotaction( old_act );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

getppid

Synopsis:

#include <unistd.h>
pid_t getppid(void);
Description:
The getppid function allows the calling process to find out its parent ID.
Returns:
The process parent's process ID.
See Also:
getpid
Example:

/*
* Print the parent's process ID.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
    printf( "My parent is %d\n", getppid() );
    return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

getprotobyname

Synopsis:

#include <netdb.h>
struct netent *getprotobyname( const char *name );
Description:
The getprotobyname function searches the protocol database for a protocol matching the specified name, considering both the official name and aliases.  The routine will query the local database only.
The structure returned is defined as:

struct protoent {
    char    *p_name;        /* official protocol name */
    char    **p_aliases;    /* alias list              */
    int     p_proto;        /* protocol number         */
};

The pointer returned by getprotobyname points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the protocol database may affect the return value from this function.
Returns:
If a matching protocol database entry is found, the return value will point to a struct protoent as defined above.
The alias names of said protocol are contained in the p_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no protocol is found or an error occurs, the return value will be NULL.
See Also:
getprotoent, setprotoent, endprotoent, getprotobynumber
Classification:
POSIX 1003.1
Systems:
Linux

getprotobynumber

Synopsis:

#include <netdb.h>
struct netent *getprotobynumber( int protocol );
Description:
The getprotobynumber function searches the protocol database for a protocol matching the specified by the protocol argument.  The routine will query the local database only.
The structure returned is defined as:

struct protoent {
    char    *p_name;        /* official protocol name */
    char    **p_aliases;    /* alias list              */
    int     p_proto;        /* protocol number         */
};

The pointer returned by getprotobynumber points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the protocol database may affect the return value from this function.
Returns:
If a matching protocol database entry is found, the return value will point to a struct protoent as defined above.
The alias names of said protocol are contained in the p_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no protocol is found or an error occurs, the return value will be NULL.
See Also:
getprotoent, setprotoent, endprotoent, getprotobyname
Classification:
POSIX 1003.1
Systems:
Linux

getprotoent

Synopsis:

#include <netdb.h>
struct netent *getprotoent( void );
Description:
The getprotoent function retrieves the next entry in the protocol database.  If not proceeded by an appropriate call to setprotoent, the function will always return the first protocol in the database.  The routine will query the local database only.
The structure returned is defined as:

struct protoent {
    char    *p_name;        /* official protocol name */
    char    **p_aliases;    /* alias list              */
    int     p_proto;        /* protocol number         */
};

The pointer returned by getprotoent points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the protocol database may affect the return value from this function.
Returns:
If the database contains more entries, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said protocol are contained in the p_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no protocol is found or an error occurs, the return value will be NULL.
See Also:
setprotoent, endprotoent, getprotobyname, getprotobynumber
Classification:
POSIX 1003.1
Systems:
Linux

getpwent

Synopsis:

#include <pwd.h>
struct passwd *getpwent( void );
Description:
The getpwent function reads, parses, and returns entries from the password database at /etc/passwd.  The first call will return the first entry, and subsequent calls return subsequent entries.  A null pointer is returned if either an error is encountered or no further entries exist.
The structure returned is defined as:

struct passwd {
    char    *pw_name;       /* user's login name */
    char    *pw_passwd;     /* user's password   */
    uid_t   pw_uid;         /* user ID number     */
    gid_t   pw_gid;         /* group ID number    */
    char    *pw_gecos;      /* real name          */
    char    *pw_dir;        /* home directory     */
    char    *pw_shell;      /* initial program   */
};
On most modern Linux implementations, the resulting password will simply be 'x' as passwords are not normally stored in the password database itself.

The pointer returned by getpwent points to a static location, and the user should free neither the pointer itself nor any of its consituent structure members.

This function is not thread-safe.  Other calls to functions accessing the password database may affect the return value from this function.
Returns:
A parsed password database entry, or NULL if no further entries exist or an error occurred.
See Also:
setpwent, endpwent, getpwnam, getpwuid
Example:

The following program will print out each user and their user ID in the system's password database

#include <stdio.h>
#include <pwd.h>

void main()
  {
    struct passwd *pw;

    setpwent();

    while((pw = getpwent()) != NULL) {
        printf("User id %d is %s\n", (int)pw->pw_uid, pw->pw_name);
    }

    endpwent();

  }
Classification:
POSIX 1003.1
Systems:
Linux

getpwnam

Synopsis:

#include <pwd.h>
struct passwd *getpwnam( const char *name );
Description:
The getpwnam function locates and returns a parsed password database entry for the user with the specified username.   If a matching entry is not found or an error occurs, a null pointer will be returned.
The structure returned is defined as:

struct passwd {
    char    *pw_name;       /* user's login name */
    char    *pw_passwd;     /* user's password   */
    uid_t   pw_uid;         /* user ID number     */
    gid_t   pw_gid;         /* group ID number    */
    char    *pw_gecos;      /* real name          */
    char    *pw_dir;        /* home directory     */
    char    *pw_shell;      /* initial program   */
};
On most modern Linux implementations, the resulting password will simply be 'x' as passwords are not normally stored in the password database itself.

The pointer returned by getpwnam points to a static location, and the user should free neither the pointer itself nor any of its consituent structure members.

This function is not thread-safe.  Other calls to functions accessing the password database may affect the return value from this function.
Returns:
A matching parsed password database entry, or NULL if no match is found.
See Also:
setpwent, endpwent, getpwuid, getpwent
Example:

The following program will locate and print out the user ID corresponding to a user name 'root.'

#include <stdio.h>
#include <pwd.h>

void main()
  {
    struct passwd *pw;

    pw = getpwnam( "root" );
    if(pw) {
        printf("The user id for root is %d\n", (int)pw->pw_uid);
    } else {
        printf("User 'root' was not found.\n");
    }
  }
Classification:
POSIX 1003.1
Systems:
Linux

getpwuid

Synopsis:

#include <pwd.h>
struct passwd *getpwuid( uit_t uid );
Description:
The getpwuid function locates and returns a parsed password database entry for the user with the specified user ID.   If a matching entry is not found or an error occurs, a null pointer will be returned.
The structure returned is defined as:

struct passwd {
    char    *pw_name;       /* user's login name */
    char    *pw_passwd;     /* user's password   */
    uid_t   pw_uid;         /* user ID number     */
    gid_t   pw_gid;         /* group ID number    */
    char    *pw_gecos;      /* real name          */
    char    *pw_dir;        /* home directory     */
    char    *pw_shell;      /* initial program   */
};
On most modern Linux implementations, the resulting password will simply be 'x' as passwords are not normally stored in the password database itself.

The pointer returned by getpwuid points to a static location, and the user should free neither the pointer itself nor any of its consituent structure members.

This function is not thread-safe.  Other calls to functions accessing the password database may affect the return value from this function.
Returns:
A matching parsed password database entry, or NULL if no match is found.
See Also:
setpwent, endpwent, getpwnam, getpwent
Example:

The following program will locate and print out the user name corresponding to a user ID of 1000.

#include <stdio.h>
#include <pwd.h>

void main()
  {
    struct passwd *pw;

    pw = getpwuid( (uid_t)1000 );
    if(pw)
        printf("The corresponding username is '%s'\n", pw->pw_name);
    else
        printf("User id 1000 was not found.\n");
  }
Classification:
POSIX 1003.1
Systems:
Linux

gets, _getws

Synopsis:

#include <stdio.h>
char *gets( char *buf );
#include <stdio.h>
wchar_t *_getws( wchar_t *buf );
Description:
The gets function gets a string of characters from the file designated by stdin and stores them in the array pointed to by buf until end-of-file is encountered or a new-line character is read.  Any new-line character is discarded, and a null character is placed immediately after the last character read into the array.
The _getws function is a wide character version of gets that operates with wide character strings.  The _getws function gets a string of multibyte characters (if present) from the input stream pointed to by stdin, converts them to wide characters, and stores them in the wide character array pointed to by buf until end-of-file is encountered or a wide character new-line character is read.

It is recommended that fgets be used instead of gets because data beyond the array buf will be destroyed if a new-line character is not read from the input stream stdin before the end of the array buf is reached.

A common programming error is to assume the presence of a new-line character in every string that is read into the array.  A new-line character may not appear as the last character in a file, just before end-of-file.
Returns:
The gets function returns buf if successful.  NULL is returned if end-of-file is encountered, or if a read error occurs.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
fgetc, fgetchar, fgets, fopen, getc, getchar, ungetc
Example:

#include <stdio.h>

void main()
  {
    char buffer[80];

    while( gets( buffer ) != NULL )
      puts( buffer );
  }
Classification:
ISO C
_getws is WATCOM
Systems:
gets - All, Linux, RDOS, Netware
_getws - All, Linux

gets_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
char *gets_s( char *s, rsize_t n );
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and gets_s will set s[0] to be the null character, and characters are read and discarded from stdin until a new-line character is read, or end-of-file or a read error occurs.
s shall not be a null pointer.  n shall neither be equal to zero nor be greater than RSIZE_MAX.   A new-line character, end-of-file, or read error shall occur within reading n-1 characters from stdin.
Description:
The gets_s function gets a string of characters from the file designated by stdin and stores them in the array pointed to by s until end-of-file is encountered or a new-line character is read.  Size of the array s is specified by the argument n, this information is used to protect buffer from overflow.  If buffer s is about to be overflown, runtime-constraint is activated.  Any new-line character is discarded, and a null character is placed immediately after the last character read into the array.
Returns:
The gets_s function returns s if successful.  NULL is returned if there was a runtime-constraint violation, or if end-of-file is encountered and no caracters have been read into the array, or if a read error occurs.
See Also:
fgetc, fgetchar, fgets, fopen, getc, getchar, gets, ungetc
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>

int main()
  {
    char buffer[80];

    while( gets_s( buffer, sizeof( buffer ) ) != NULL )
      puts( buffer );
  }
Classification:
TR 24731
Systems:
All, Linux, RDOS, Netware

getservbyname

Synopsis:

#include <netdb.h>
struct servent *getservbyname( const char *name, const char *protocol );
Description:
The getservbyname function searches the service database for a service with matching name and protocol, returning a pointer the a struct servent if found.  The function will search for matching aliases as well.   If protocol is NULL, the first encountered service matching the specified name will be returned regardless of protocol.  The routine will query the local database only.
The structure returned is defined as:

struct servent {
    char    *s_name;        /* official service name */
    char    **s_aliases;    /* alias list             */
    int     s_port;         /* port number            */
    char    *s_proto;       /* protocol to use        */
};

The pointer returned by getservbyname points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a match is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said network are contained in the s_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no additional network is found or an error occurs, the return value will be NULL.
See Also:
getservent, setservent, endservent, getservbyport
Classification:
POSIX 1003.1
Systems:
Linux

getservbyport

Synopsis:

#include <netdb.h>
struct servent *getservbyname( int port, const char *protocol );
Description:
The getservbyport function searches the service database for a service listening on port using protocol, returning a pointer the a struct servent if found.  If protocol is NULL, the first encountered service matching the specified port number will be returned regardless of protocol.  The routine will query the local database only.
The structure returned is defined as:

struct servent {
    char    *s_name;        /* official service name */
    char    **s_aliases;    /* alias list             */
    int     s_port;         /* port number            */
    char    *s_proto;       /* protocol to use        */
};

The pointer returned by getservbyport points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If a match is found, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said network are contained in the s_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no additional network is found or an error occurs, the return value will be NULL.
See Also:
getservent, setservent, endservent, getservbyname
Classification:
POSIX 1003.1
Systems:
Linux

getservent

Synopsis:

#include <netdb.h>
struct servent *getservent( void );
Description:
The getservent function retrieves the next entry in the service database.  If not proceeded by an appropriate call to setservent, the function will always return the first service in the database.  The routine will query the local database only.
The structure returned is defined as:

struct servent {
    char    *s_name;        /* official service name */
    char    **s_aliases;    /* alias list             */
    int     s_port;         /* port number            */
    char    *s_proto;       /* protocol to use        */
};

The pointer returned by getservent points to a private location, and the user should free neither the pointer itself nor any of its constituent structure members.  Subsequent calls to this function may result in the values changing.

This function is not thread-safe.  Other calls to this function or to other functions accessing the hostname database may affect the return value from this function.
Returns:
If the database contains more entries, the return value will be non-NULL.  The returned pointer should not be freed by the calling routine.
The alias names of said network are contained in the s_aliases member as a NULL-terminated list, and this structure entry will never be NULL.

If no additional network is found or an error occurs, the return value will be NULL.
See Also:
setservent, endservent, getservbyname, getservbyport
Classification:
POSIX 1003.1
Systems:
Linux

_gettextcolor

Synopsis:

#include <graph.h>
short _FAR _gettextcolor( void );
Description:
The _gettextcolor function returns the pixel value of the current text color.  This is the color used for displaying text with the _outtext and _outmem functions.  The default text color value is set to 7 whenever a new video mode is selected.
Returns:
The _gettextcolor function returns the pixel value of the current text color.
See Also:
_settextcolor, _setcolor, _outtext, _outmem
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int old_col;
    long old_bk;

    _setvideomode( _TEXTC80 );
    old_col = _gettextcolor();
    old_bk = _getbkcolor();
    _settextcolor( 7 );
    _setbkcolor( _BLUE );
    _outtext( " WATCOM \nGraphics" );
    _settextcolor( old_col );
    _setbkcolor( old_bk );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_gettextcursor

Synopsis:

#include <graph.h>
short _FAR _gettextcursor( void );
Description:
The _gettextcursor function returns the current cursor attribute, or shape.  The cursor shape is set with the _settextcursor function.  See the _settextcursor function for a description of the value returned by the _gettextcursor function.
Returns:
The _gettextcursor function returns the current cursor shape when successful; otherwise, (-1) is returned.
See Also:
_settextcursor, _displaycursor
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int old_shape;

    old_shape = _gettextcursor();
    _settextcursor( 0x0007 );
    _outtext( "\nBlock cursor" );
    getch();
    _settextcursor( 0x0407 );
    _outtext( "\nHalf height cursor" );
    getch();
    _settextcursor( 0x2000 );
    _outtext( "\nNo cursor" );
    getch();
    _settextcursor( old_shape );
}
Classification:
PC Graphics
Systems:
DOS

_gettextextent

Synopsis:

#include <graph.h>
void _FAR _gettextextent( short x, short y,
                           char _FAR *text,
                           struct xycoord _FAR *concat,
                           struct xycoord _FAR *extent );
Description:
The _gettextextent function simulates the effect of using the _grtext function to display the text string text at the position (x,y), using the current text settings.  The concatenation point is returned in the argument concat.  The text extent parallelogram is returned in the array extent.
The concatenation point is the position to use to output text after the given string.  The text extent parallelogram outlines the area where the text string would be displayed.  The four points are returned in counter-clockwise order, starting at the upper-left corner.
Returns:
The _gettextextent function does not return a value.
See Also:
_grtext, _gettextsettings
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct xycoord concat;
    struct xycoord extent[ 4 ];

    _setvideomode( _VRES16COLOR );
    _grtext( 100, 100, "hot" );
    _gettextextent( 100, 100, "hot", &concat, extent );
    _polygon( _GBORDER, 4, extent );
    _grtext( concat.xcoord, concat.ycoord, "dog" );
    getch();
    _setvideomode( _DEFAULTMODE );
}

produces the following:

Classification:
PC Graphics
Systems:
DOS

_gettextposition

Synopsis:

#include <graph.h>
struct rccoord _FAR _gettextposition( void );
Description:
The _gettextposition function returns the current output position for text.  This position is in terms of characters, not pixels.
The current position defaults to the top left corner of the screen, (1,1), when a new video mode is selected.   It is changed by successful calls to the _outtext, _outmem, _settextposition and _settextwindow functions.

Note that the output position for graphics output differs from that for text output.  The output position for graphics output can be set by use of the _moveto function.
Returns:
The _gettextposition function returns, as an rccoord structure, the current output position for text.
See Also:
_outtext, _outmem, _settextposition, _settextwindow, _moveto
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct rccoord old_pos;

    _setvideomode( _TEXTC80 );
    old_pos = _gettextposition();
    _settextposition( 10, 40 );
    _outtext( "WATCOM Graphics" );
    _settextposition( old_pos.row, old_pos.col );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_gettextsettings

Synopsis:

#include <graph.h>
struct textsettings _FAR * _FAR _gettextsettings
    ( struct textsettings _FAR *settings );
Description:
The _gettextsettings function returns information about the current text settings used when text is displayed by the _grtext function.  The information is stored in the textsettings structure indicated by the argument settings.  The structure contains the following fields (all are short fields):
basevectorx
x-component of the current base vector

basevectory
y-component of the current base vector

path
current text path

height
current text height (in pixels)

width
current text width (in pixels)

spacing
current text spacing (in pixels)

horizalign
horizontal component of the current text alignment

vertalign
vertical component of the current text alignment
Returns:
The _gettextsettings function returns information about the current graphics text settings.
See Also:
_grtext, _setcharsize, _setcharspacing, _settextalign, _settextpath, _settextorient
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct textsettings ts;

    _setvideomode( _VRES16COLOR );
    _gettextsettings( &ts );
    _grtext( 100, 100, "WATCOM" );
    _setcharsize( 2 * ts.height, 2 * ts.width );
    _grtext( 100, 300, "Graphics" );
    _setcharsize( ts.height, ts.width );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_gettextwindow

Synopsis:

#include <graph.h>
void _FAR _gettextwindow(
                short _FAR *row1, short _FAR *col1,
                short _FAR *row2, short _FAR *col2 );
Description:
The _gettextwindow function returns the location of the current text window.  A text window is defined with the _settextwindow function.  By default, the text window is the entire screen.
The current text window is a rectangular area of the screen.  Text display is restricted to be within this window.   The top left corner of the text window is placed in the arguments (row1,col1).  The bottom right corner of the text window is placed in (row2,col2).
Returns:
The _gettextwindow function returns the location of the current text window.
See Also:
_settextwindow, _outtext, _outmem, _settextposition, _scrolltextwindow
Example:

#include <conio.h>
#include <graph.h>
#include <stdio.h>

main()
{
    int i;
    short r1, c1, r2, c2;
    char buf[ 80 ];

    _setvideomode( _TEXTC80 );
    _gettextwindow( &r1, &c1, &r2, &c2 );
    _settextwindow( 5, 20, 20, 40 );
    for( i = 1; i <= 20; ++i ) {
        sprintf( buf, "Line %d\n", i );
        _outtext( buf );
    }
    getch();
    _settextwindow( r1, c1, r2, c2 );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

gettid

Synopsis:

#include <process.h>
int gettid(void);
Description:
The gettid function returns the thread id for the current thread on Linux systems.  It provides a wrapper around the appropriate kernel system call.
Returns:
The gettid function returns the thread id for the current thread.
See Also:
getpid
Classification:
WATCOM
Systems:
Linux

getuid

Synopsis:

#include <unistd.h>
uid_t getuid( void );
Description:
The getuid function returns the user ID for the calling process.
Returns:
The user ID for the calling process
See Also:
geteuid, getgid, getegid
Example:

/*
* Print the user ID of this process.
*/
#include <stdio.h>
#include <unistd.h>

int main( void )
  {
    printf( "My userid is %d\n", getuid() );
    return( 0 );
  }
Classification:
POSIX 1003.1
Systems:
Linux

_getvideoconfig

Synopsis:

#include <graph.h>
struct videoconfig _FAR * _FAR _getvideoconfig
    ( struct videoconfig _FAR *config );
Description:
The _getvideoconfig function returns information about the current video mode and the hardware configuration.  The information is returned in the videoconfig structure indicated by the argument config.  The structure contains the following fields (all are short fields):
numxpixels
number of pixels in x-axis

numypixels
number of pixels in y-axis

numtextcols
number of text columns

numtextrows
number of text rows

numcolors
number of actual colors

bitsperpixel
number of bits in a pixel value

numvideopages
number of video pages

mode
current video mode

adapter
adapter type

monitor
monitor type

memory
number of kilobytes (1024 characters) of video memory

The adapter field will contain one of the following values:
_NODISPLAY
no display adapter attached

_UNKNOWN
unknown adapter/monitor type

_MDPA
Monochrome Display/Printer Adapter

_CGA
Color Graphics Adapter

_HERCULES
Hercules Monochrome Adapter

_MCGA
Multi-Color Graphics Array

_EGA
Enhanced Graphics Adapter

_VGA
Video Graphics Array

_SVGA
SuperVGA Adapter

The monitor field will contain one of the following values:
_MONO
regular monochrome

_COLOR
regular color

_ENHANCED
enhanced color

_ANALOGMONO
analog monochrome

_ANALOGCOLOR
analog color

The amount of memory reported by _getvideoconfig will not always be correct for SuperVGA adapters.  Since it is not always possible to determine the amount of memory, _getvideoconfig will always report 256K, the minimum amount.
Returns:
The _getvideoconfig function returns information about the current video mode and the hardware configuration.
See Also:
_setvideomode, _setvideomoderows
Example:

#include <conio.h>
#include <graph.h>
#include <stdio.h>
#include <stdlib.h>

main()
{
    int mode;
    struct videoconfig vc;
    char buf[ 80 ];

    _getvideoconfig( &vc );
    /* select "best" video mode */
    switch( vc.adapter ) {
    case _VGA :
    case _SVGA :
        mode = _VRES16COLOR;
        break;
    case _MCGA :
        mode = _MRES256COLOR;
        break;
    case _EGA :
        if( vc.monitor == _MONO ) {
            mode = _ERESNOCOLOR;
        } else {
            mode = _ERESCOLOR;
        }
        break;
    case _CGA :
        mode = _MRES4COLOR;
        break;
    case _HERCULES :
        mode = _HERCMONO;
        break;
    default :
        puts( "No graphics adapter" );
        exit( 1 );
    }
    if( _setvideomode( mode ) ) {
        _getvideoconfig( &vc );
        sprintf( buf, "%d x %d x %d\n", vc.numxpixels,
                          vc.numypixels, vc.numcolors );
        _outtext( buf );
        getch();
        _setvideomode( _DEFAULTMODE );
    }
}
Classification:
PC Graphics
Systems:
DOS

_getviewcoord, _getviewcoord_w, _getviewcoord_wxy

Synopsis:

#include <graph.h>
struct xycoord _FAR _getviewcoord( short x, short y );

struct xycoord _FAR _getviewcoord_w( double x, double y );

struct xycoord _FAR _getviewcoord_wxy(
                    struct _wxycoord _FAR *p );
Description:
The _getviewcoord functions translate a point from one coordinate system to viewport coordinates.  The _getviewcoord function translates the point (x,y) from physical coordinates.  The _getviewcoord_w and _getviewcoord_wxy functions translate the point from the window coordinate system.
Viewport coordinates are defined by the _setvieworg and _setviewport functions.  Window coordinates are defined by the _setwindow function.

Note:  In previous versions of the software, the _getviewcoord function was called _getlogcoord.  
Returns:
The _getviewcoord functions return the viewport coordinates, as an xycoord structure, of the given point.
See Also:
_getphyscoord, _setvieworg, _setviewport, _setwindow
Example:

#include <conio.h>
#include <graph.h>
#include <stdlib.h>

main()
{
    struct xycoord pos1, pos2;

    _setvideomode( _VRES16COLOR );
    _setvieworg( rand() % 640, rand() % 480 );
    pos1 = _getviewcoord( 0, 0 );
    pos2 = _getviewcoord( 639, 479 );
    _rectangle( _GBORDER, pos1.xcoord, pos1.ycoord,
                           pos2.xcoord, pos2.ycoord );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_getviewcoord - DOS
_getviewcoord_w - DOS
_getviewcoord_wxy - DOS

_getvisualpage

Synopsis:

#include <graph.h>
short _FAR _getvisualpage( void );
Description:
The _getvisualpage function returns the number of the currently selected visual graphics page.
Only some combinations of video modes and hardware allow multiple pages of graphics to exist.  When multiple pages are supported, the active page may differ from the visual page.  The graphics information in the visual page determines what is displayed upon the screen.  Animation may be accomplished by alternating the visual page.  A graphics page can be constructed without affecting the screen by setting the active page to be different than the visual page.

The number of available video pages can be determined by using the _getvideoconfig function.  The default video page is 0.
Returns:
The _getvisualpage function returns the number of the currently selected visual graphics page.
See Also:
_setvisualpage, _setactivepage, _getactivepage, _getvideoconfig
Example:

#include <conio.h>
#include <graph.h>

main()
{
    int old_apage;
    int old_vpage;

    _setvideomode( _HRES16COLOR );
    old_apage = _getactivepage();
    old_vpage = _getvisualpage();
    /* draw an ellipse on page 0 */
    _setactivepage( 0 );
    _setvisualpage( 0 );
    _ellipse( _GFILLINTERIOR, 100, 50, 540, 150 );
    /* draw a rectangle on page 1 */
    _setactivepage( 1 );
    _rectangle( _GFILLINTERIOR, 100, 50, 540, 150 );
    getch();
    /* display page 1 */
    _setvisualpage( 1 );
    getch();
    _setactivepage( old_apage );
    _setvisualpage( old_vpage );
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_getw

Synopsis:

#include <stdio.h>
int _getw( int binint, FILE *fp );
Description:
The _getw function reads a binary value of type int from the current position of the stream fp and increments the associated file pointer to point to the next unread character in the input stream.  _getw does not assume any special alignment of items in the stream.
_getw is provided primarily for compatibility with previous libraries.  Portability problems may occur with _getw because the size of an int and the ordering of bytes within an int differ across systems.
Returns:
The _getw function returns the integer value read or, if a read error or end-of-file occurs, the error indicator is set and _getw returns EOF.  Since EOF is a legitimate value to read from fp, use ferror to verify that an error has occurred.
See Also:
ferror, fgetc, fgetchar, fgets, fopen, getc, getchar, gets, _putw, ungetc
Example:

#include <stdio.h>

void main()
  {
    FILE *fp;
    int c;

    fp = fopen( "file", "r" );
    if( fp != NULL ) {
      while( (c = _getw( fp )) != EOF )
          _putw( c, stdout );
      fclose( fp );
    }
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS, Netware

_getwindowcoord

Synopsis:

#include <graph.h>
struct _wxycoord _FAR _getwindowcoord( short x, short y );
Description:
The _getwindowcoord function returns the window coordinates of the position with view coordinates (x,y).   Window coordinates are defined by the _setwindow function.
Returns:
The _getwindowcoord function returns the window coordinates, as a _wxycoord structure, of the given point.
See Also:
_setwindow, _getviewcoord
Example:

#include <conio.h>
#include <graph.h>

main()
{
    struct xycoord centre;
    struct _wxycoord pos1, pos2;

    /* draw a box 50 pixels square */
    /* in the middle of the screen */
    _setvideomode( _MAXRESMODE );
    centre = _getviewcoord_w( 0.5, 0.5 );
    pos1 = _getwindowcoord( centre.xcoord - 25,
                             centre.ycoord - 25 );
    pos2 = _getwindowcoord( centre.xcoord + 25,
                             centre.ycoord + 25 );
    _rectangle_wxy( _GBORDER, &pos1, &pos2 );
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

gmtime Functions

Synopsis:

#include <time.h>
struct tm * gmtime( const time_t *timer );
struct tm *_gmtime( const time_t *timer,
                    struct tm *tmbuf );

struct  tm {
  int tm_sec;   /* seconds after the minute -- [0,61] */
  int tm_min;   /* minutes after the hour   -- [0,59] */
  int tm_hour;  /* hours after midnight     -- [0,23] */
  int tm_mday;  /* day of the month         -- [1,31] */
  int tm_mon;   /* months since January     -- [0,11] */
  int tm_year;  /* years since 1900                    */
  int tm_wday;  /* days since Sunday        -- [0,6]  */
  int tm_yday;  /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag         */
};
Safer C:
The Safer C Library extension provides the gmtime_s function which is a safer alternative to gmtime.   This newer gmtime_s function is recommended to be used instead of the traditional "unsafe" gmtime function.
Description:
The gmtime functions convert the calendar time pointed to by timer into a broken-down time, expressed as Coordinated Universal Time (UTC) (formerly known as Greenwich Mean Time, or GMT).
The function _gmtime places the converted time in the tm structure pointed to by tmbuf, and the gmtime function places the converted time in a static structure that is re-used each time gmtime is called.

The time set on the computer with the DOS time command and the DOS date command reflects the local time.  The environment variable TZ is used to establish the time zone to which this local time applies.  See the section The TZ Environment Variable for a discussion of how to set the time zone.
Returns:
The gmtime functions return a pointer to a structure containing the broken-down time.
See Also:
asctime Functions, asctime_s, clock, ctime Functions, ctime_s, difftime, gmtime_s, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#include <stdio.h>
#include <time.h>

void main()
{
    time_t time_of_day;
    auto char buf[26];
    auto struct tm tmbuf;

    time_of_day = time( NULL );
    _gmtime( &time_of_day, &tmbuf );
    printf( "It is now: %.24s GMT\n",
            _asctime( &tmbuf, buf ) );
}

produces the following:

It is now: Fri Dec 25 15:58:27 1987 GMT
Classification:
ISO C
_gmtime is WATCOM
Systems:
gmtime - All, Linux, RDOS, Netware
_gmtime - All, Linux, RDOS

gmtime_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <time.h>
struct tm * gmtime_s( const time_t * restrict timer,
                       struct tm * restrict result );

struct  tm {
  int tm_sec;   /* seconds after the minute -- [0,61] */
  int tm_min;   /* minutes after the hour   -- [0,59] */
  int tm_hour;  /* hours after midnight     -- [0,23] */
  int tm_mday;  /* day of the month         -- [1,31] */
  int tm_mon;   /* months since January     -- [0,11] */
  int tm_year;  /* years since 1900                    */
  int tm_wday;  /* days since Sunday        -- [0,6]  */
  int tm_yday;  /* days since January 1     -- [0,365]*/
  int tm_isdst; /* Daylight Savings Time flag         */
};
Constraints:
If any of the following runtime-constraints is violated, the currently active runtime-constraint handler will be invoked and gmtime_s will return a non-zero value to indicate an error, or the runtime-constraint handler aborts the program.
Neither timer nor result shall be a null pointer.  If there is a runtime-constraint violation, there is no attempt to convert the time.
Description:
The gmtime_s function converts the calendar time pointed to by timer into a broken-down time, expressed as UTC.  The broken-down time is stored in the structure pointed to by result.
Returns:
The gmtime_s function returns result, or a null pointer if the specified time cannot be converted to UTC or there is a runtime-constraint violation.
See Also:
asctime Functions, asctime_s, clock, ctime Functions, ctime_s, difftime, gmtime, localtime, localtime_s, mktime, strftime, time, tzset
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <time.h>

void main()
{
    time_t time_of_day;
    auto char buf[26];
    auto struct tm tmbuf;

    time_of_day = time( NULL );
    gmtime_s( &time_of_day, &tmbuf );
    asctime_s( buf, sizeof( buf ), &tmbuf );
    printf( "It is now: %.24s GMT\n", buf );
}

produces the following:

It is now: Thu Jan 31 15:12:27 2006 GMT
Classification:
TR 24731
Systems:
DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32, Linux, RDOS, Netware

_grow_handles

Synopsis:

#include <stdio.h>
int _grow_handles( int new_count );
Description:
The _grow_handles function increases the number of POSIX level files that are allowed to be open at one time.  The parameter new_count is the new requested number of files that are allowed to be opened.  The return value is the number that is allowed to be opened after the call.  This may be less than, equal to, or greater than the number requested.  If the number is less than, an error has occurred and the errno variable should be consulted for the reason.   If the number returned is greater than or equal to the number requested, the call was successful.
Note that even if _grow_handles returns successfully, you still might not be able to open the requested number of files due to some system limit (e.g.  FILES= in the CONFIG.SYS file under DOS) or because some file handles are already in use (stdin, stdout, stderr, etc.).

The number of file handles that the run-time system can open by default is described by _NFILES in <stdio.h> but this can be changed by the application developer.  To change the number of file handles available during execution, follow the steps outlined below.
  1. Let n represent the number of files to be opened concurrently.  Ensure that the stdin, stdout, and stderr files are included in the count.  Also include stdaux and stdprn files in the count for some versions of DOS.  The stdaux and stdprn files are not available for Win32.
  2. For DOS-based systems, change the CONFIG.SYS file to include "FILES=n" where "n" is the number of file handles required by the application plus an additional 5 handles for the standard files.  The number of standard files that are opened by DOS varies from 3 to 5 depending on the version of DOS that you are using.

    If you are running a network such as Novell's NetWare, this will also affect the number of available file handles.   In this case, you may have to increase the number specified in the "FILES=n" statement.
  3. Add a call to _grow_handles in your application similar to that shown in the example below.
Returns:
The _grow_handles function returns the maximum number of file handles which the run-time system can accommodate.   This number can exceed an operating system limit such as that imposed by the "FILES=" statement under DOS.   This limit will be the determining factor in how many files can be open concurrently.
Errors:
When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
_dos_open, fdopen, fileno, fopen, freopen, _fsopen, _hdopen, open, _open_osfhandle, _popen, _sopen, tmpfile
Example:

#include <stdio.h>

FILE *fp[ 50 ];

void main()
  {
    int hndl_count;
    int i;

    hndl_count = _NFILES;
    if( hndl_count < 50 ) {
        hndl_count = _grow_handles( 50 );
    }
    for( i = 0; i < hndl_count; i++ ) {
      fp[ i ] = tmpfile();
      if( fp[ i ] == NULL ) break;
      printf( "File %d successfully opened\n", i );
    }
    printf( "%d files were successfully opened\n", i );
  }
Classification:
WATCOM
Systems:
All, Linux

_grstatus

Synopsis:

#include <graph.h>
short _FAR _grstatus( void );
Description:
The _grstatus function returns the status of the most recently called graphics library function.  The function can be called after any graphics function to determine if any errors or warnings occurred.  The function returns 0 if the previous function was successful.  Values less than 0 indicate an error occurred; values greater than 0 indicate a warning condition.
The following values can be returned: 

     
     Constant              Value   Explanation

     _GROK                    0    no error
     _GRERROR               -1    graphics error
     _GRMODENOTSUPPORTED    -2    video mode not supported
     _GRNOTINPROPERMODE     -3    function n/a in this mode
     _GRINVALIDPARAMETER    -4    invalid parameter(s)
     _GRINSUFFICIENTMEMORY  -5    out of memory
     _GRFONTFILENOTFOUND    -6    can't open font file
     _GRINVALIDFONTFILE     -7    font file has invalid format
     _GRNOOUTPUT             1     nothing was done
     _GRCLIPPED              2    output clipped
Returns:
The _grstatus function returns the status of the most recently called graphics library function.
Example:

#include <conio.h>
#include <graph.h>
#include <stdlib.h>

main()
{
    int x, y;

    _setvideomode( _VRES16COLOR );
    while( _grstatus() == _GROK ) {
        x = rand() % 700;
        y = rand() % 500;
        _setpixel( x, y );
    }
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
DOS

_grtext, _grtext_w

Synopsis:

#include <graph.h>
short _FAR _grtext( short x, short y,
                    char _FAR *text );

short _FAR _grtext_w( double x, double y,
                       char _FAR *text );
Description:
The _grtext functions display a character string.  The _grtext function uses the view coordinate system.   The _grtext_w function uses the window coordinate system.
The character string text is displayed at the point (x,y).  The string must be terminated by a null character ('\0').  The text is displayed in the current color using the current text settings.

The graphics library can display text in three different ways.
  1. The _outtext and _outmem functions can be used in any video mode.  However, this variety of text can be displayed in only one size.
  2. The _grtext function displays text as a sequence of line segments, and can be drawn in different sizes, with different orientations and alignments.
  3. The _outgtext function displays text in the currently selected font.  Both bit-mapped and vector fonts are supported; the size and type of text depends on the fonts that are available.
Returns:
The _grtext functions return a non-zero value when the text was successfully drawn; otherwise, zero is returned.
See Also:
_outtext, _outmem, _outgtext, _setcharsize, _settextalign, _settextpath, _settextorient, _setcharspacing
Example:

#include <conio.h>
#include <graph.h>

main()
{
    _setvideomode( _VRES16COLOR );
    _grtext( 200, 100, " WATCOM" );
    _grtext( 200, 200, "Graphics" );
    getch();
    _setvideomode( _DEFAULTMODE );
}

produces the following:

Classification:
PC Graphics
Systems:
_grtext - DOS
_grtext_w - DOS

halloc

Synopsis:

#include <malloc.h>
void __huge *halloc( long int numb, size_t size );
Description:
The halloc function allocates space for an array of numb objects of size bytes each and initializes each object to 0.  When the size of the array is greater than 64K bytes, then the size of an array element must be a power of 2 since an object could straddle a segment boundary.
Returns:
The halloc function returns a far pointer (of type void huge *) to the start of the allocated memory.  The NULL value is returned if there is insufficient memory available.  The NULL value is also returned if the size of the array is greater than 64K bytes and the size of an array element is not a power of 2.
See Also:
calloc Functions, _expand Functions, free Functions, hfree, malloc Functions, _msize Functions, realloc Functions, sbrk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    long int __huge *big_buffer;

    big_buffer = (long int __huge *)
                  halloc( 1024L, sizeof(long) );
    if( big_buffer == NULL ) {
      printf( "Unable to allocate memory\n" );
    } else {

      /* rest of code goes here */

      hfree( big_buffer );  /* deallocate */
    }
  }
Classification:
WATCOM
Systems:
DOS/16, Windows, OS/2 1.x(all)

_harderr, _hardresume, _hardretn

Synopsis:

#include <dos.h>
void _harderr( int (__far *handler)() );
void _hardresume( int action );
void _hardretn( int error );
Description:
The _harderr routine installs a critical error handler (for INT 0x24) to handle hardware errors.  This critical error handler will call the user-defined function specified by handler when a critical error occurs (for example, attempting to open a file on a floppy disk when the drive door is open).  The parameters to this function are as follows:
     
     int handler( unsigned deverror,
                  unsigned errcode,
                  unsigned __far *devhdr );

The low-order byte of errcode can be one of the following values:
Value
Meaning

0x00
Attempt to write to a write-protected disk

0x01
Unknown unit

0x02
Drive not ready

0x03
Unknown command

0x04
CRC error in data

0x05
Bad drive-request structure length

0x06
Seek error

0x07
Unknown media type

0x08
Sector not found

0x09
Printer out of paper

0x0A
Write fault

0x0B
Read fault

0x0C
General failure

The devhdr argument points to a device header control-block that contains information about the device on which the error occurred.  Your error handler may inspect the information in this control-block but must not change it.

If the error occurred on a disk device, bit 15 of the deverror argument will be 0 and the deverror argument will indicate the following:
Bit
Meaning

bit 15
0 indicates disk error

bit 14
not used

bit 13
0 indicates "Ignore" response not allowed

bit 12
0 indicates "Retry" response not allowed

bit 11
0 indicates "Fail" response not allowed

bit 9,10
location of error
Value
Meaning

00
MS-DOS

01
File Allocation Table (FAT)

10
Directory

11
Data area

bit 8
0 indicates read error, 1 indicates write error

The low-order byte of deverror indicates the drive where the error occurred; (0 = drive A, 1 = drive B, etc.).

The handler is very restricted in the type of system calls that it can perform.  System calls 0x01 through 0x0C, and 0x59 are the only system calls allowed to be issued by the handler.  Therefore, many of the standard C run-time functions such as stream I/O and low-level I/O cannot be used by the handler.  Console I/O is allowed (e.g., cprintf, cputs).

The handler must indicate what action to take by returning one of the following values or calling _hardresume with one of the following values:
Value
Meaning

_HARDERR_IGNORE
Ignore the error

_HARDERR_RETRY
Retry the operation

_HARDERR_ABORT
Abort the program issuing INT 0x23

_HARDERR_FAIL
Fail the system call that is in progress (DOS 3.0 or higher)

Alternatively, the handler can return directly to the application program rather than returning to DOS by using the _hardretn function.  The application program resumes at the point just after the failing I/O function request.  The _hardretn function should be called only from within a user-defined hardware error-handler function.

The error argument of _hardretn should be a DOS error code.  See The MS-DOS Encyclopedia or Programmer's PC Sourcebook, 2nd Edition, for more detailed information on DOS error codes that may be returned by a given DOS function call.

If the failing I/O function request is an INT 0x21 function greater than or equal to function 0x38, _hardretn will return to the application with the carry flag set and the AX register set to the _hardretn error argument.  If the failing INT 0x21 function request is less than function 0x38 abd the function can return an error, the AL register will be set to 0xFF on return to the application.  If the failing INT 0x21 function does not have a way of returning an error condition (which is true of certain INT 0x21 functions below 0x38), the error argument of _hardretn is not used, and no error code is returned to the application.
Returns:
These functions do not return a value.  The _hardresume and _hardretn functions do not return to the caller.
See Also:
_chain_intr, _dos_getvect, _dos_setvect
Example:

#include <stdio.h>
#include <conio.h>
#include <dos.h>

#if defined(__DOS__) && defined(__386__)
    #define FAR __far
#else
    #if defined(__386__)
        #define FAR
    #else
        #define FAR __far
    #endif
#endif

int FAR critical_error_handler( unsigned deverr,
                                 unsigned errcode,
                                 unsigned FAR *devhdr )
  {
    cprintf( "Critical error: " );
    cprintf( "deverr=%4.4X errcode=%d\r\n",
             deverr, errcode );
    cprintf( "devhdr = %Fp\r\n", devhdr );
    return( _HARDERR_IGNORE );
  }

main()
  {
    FILE *fp;

    _harderr( critical_error_handler );
    fp = fopen( "a:tmp.tmp", "r" );
    printf( "fp = %p\n", fp );
  }

produces the following:

Critical error: deverr=1A00 errcode=2
devhdr = 0070:01b6
fp = 0000
Classification:
DOS
Systems:
_harderr - DOS
_hardresume - DOS
_hardretn - DOS/16

_hdopen

Synopsis:

#include <io.h>
int _hdopen( int os_handle, int mode );
Description:
The _hdopen function takes a previously opened operating system file handle specified by os_handle and opened with access and sharing specified by mode, and creates a POSIX-style file handle.
Returns:
The _hdopen function returns the new POSIX-style file handle if successful.  Otherwise, it returns -1.
See Also:
close, _dos_open, fdopen, fopen, freopen, _fsopen, _grow_handles, open, _open_osfhandle, _os_handle, _popen, _sopen
Example:

#include <stdio.h>
#include <dos.h>
#include <fcntl.h>
#include <io.h>
#include <windows.h>

void main()
  {
    HANDLE os_handle;
    DWORD desired_access, share_mode;
    int handle;

    os_handle = CreateFileA( "file", GENERIC_WRITE,
                           0, NULL, CREATE_ALWAYS,
                           FILE_ATTRIBUTE_NORMAL, NULL );

    if( os_handle == INVALID_HANDLE_VALUE ) {
        printf( "Unable to open file\n" );
    } else {
        handle = _hdopen( os_handle, O_RDONLY );
        if( handle != -1 ) {
            write( handle, "hello\n", 6 );
            close( handle );
        } else {
            CloseHandle( os_handle );
        }
    }
  }
Classification:
WATCOM
Systems:
All, Linux, Netware

_heapchk Functions

Synopsis:

#include <malloc.h>
int  _heapchk( void );
int _bheapchk( __segment seg );
int _fheapchk( void );
int _nheapchk( void );
Description:
The _heapchk functions along with _heapset and _heapwalk are provided for debugging heap related problems in programs.
The _heapchk functions perform a consistency check on the unallocated memory space or "heap".  The consistency check determines whether all the heap entries are valid.  Each function checks a particular heap, as listed below:
Function     Heap Checked
_heapchk
Depends on data model of the program

_bheapchk
Based heap specified by seg value; _NULLSEG specifies all based heaps

_fheapchk
Far heap (outside the default data segment)

_nheapchk
Near heap (inside the default data segment)

In a small data memory model, the _heapchk function is equivalent to the _nheapchk function; in a large data memory model, the _heapchk function is equivalent to the _fheapchk function.
Returns:
All four functions return one of the following manifest constants which are defined in <malloc.h>.
Constant     Meaning
_HEAPOK
The heap appears to be consistent.

_HEAPEMPTY
The heap is empty.

_HEAPBADBEGIN
The heap has been damaged.

_HEAPBADNODE
The heap contains a bad node, or is damaged.
See Also:
_heapenable, _heapgrow, _heapmin, _heapset, _heapshrink, _heapwalk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    char *buffer;

    buffer = (char *)malloc( 80 );
    malloc( 1024 );
    free( buffer );
    switch( _heapchk() ) {
    case _HEAPOK:
      printf( "OK - heap is good\n" );
      break;
    case _HEAPEMPTY:
      printf( "OK - heap is empty\n" );
      break;
    case _HEAPBADBEGIN:
      printf( "ERROR - heap is damaged\n" );
      break;
    case _HEAPBADNODE:
      printf( "ERROR - bad node in heap\n" );
      break;
    }
  }
Classification:
WATCOM
Systems:
_heapchk - All, Linux, RDOS
_bheapchk - DOS/16, Windows, OS/2 1.x(all)
_fheapchk - DOS/16, Windows, OS/2 1.x(all)
_nheapchk - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_heapenable

Synopsis:

#include <malloc.h>
int _heapenable( int enabled );
Description:
The _heapenable function is used to control attempts by the heap allocation manager to request more memory from the operating system's memory pool.  If enabled is 0 then all further allocations which would normally go to the operating system for more memory will instead fail and return NULL.  If enabled is 1 then requests for more memory from the operating system's memory pool are re-enabled.
This function can be used to impose a limit on the amount of system memory that is allocated by an application.  For example, if an application wishes to allocate no more than 200K bytes of memory, it could allocate 200K and immediately free it.  It can then call _heapenable to disable any further requests from the system memory pool.  After this, the application can allocate memory from the 200K pool that it has already obtained.
Returns:
The return value is the previous state of the system allocation flag.
See Also:
_heapchk, _heapgrow, _heapmin, _heapset, _heapshrink, _heapwalk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    char *p;

    p = malloc( 200*1024 );
    if( p != NULL ) free( p );
    _heapenable( 0 );
    /*
      allocate memory from a pool that
      has been capped at 200K
    */
  }
Classification:
WATCOM
Systems:
All, Linux, RDOS

_heapgrow Functions

Synopsis:

#include <malloc.h>
void  _heapgrow( void );
void _nheapgrow( void );
void _fheapgrow( void );
Description:
The _nheapgrow function attempts to grow the near heap to the maximum size of 64K.  You will want to do this in the small data models if you are using both malloc and _fmalloc or halloc.  Once a call to _fmalloc or halloc has been made, you may not be able to allocate any memory with malloc unless space has been reserved for the near heap using either malloc, sbrk or _nheapgrow.
The _fheapgrow function doesn't do anything to the heap because the far heap will be extended automatically when needed.  If the current far heap cannot be extended, then another far heap will be started.

In a small data memory model, the _heapgrow function is equivalent to the _nheapgrow function; in a large data memory model, the _heapgrow function is equivalent to the _fheapgrow function.
Returns:
These functions do not return a value.
See Also:
_heapchk, _heapenable, _heapmin, _heapset, _heapshrink, _heapwalk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    char *p, *fmt_string;
    fmt_string = "Amount of memory available is %u\n";
    printf( fmt_string, _memavl() );
    _nheapgrow();
    printf( fmt_string, _memavl() );
    p = (char *) malloc( 2000 );
    printf( fmt_string, _memavl() );
  }

produces the following:

Amount of memory available is 0
Amount of memory available is 62732
Amount of memory available is 60730
Classification:
WATCOM
Systems:
_heapgrow - All, Linux, RDOS
_fheapgrow - DOS/16, Windows, OS/2 1.x(all)
_nheapgrow - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_heapmin Functions

Synopsis:

#include <malloc.h>
int  _heapmin( void );
int _bheapmin( __segment seg );
int _fheapmin( void );
int _nheapmin( void );
Description:
The _heapmin functions attempt to shrink the specified heap to its smallest possible size by returning all free entries at the end of the heap back to the system.  This can be used to free up as much memory as possible before using the system function or one of the spawn... functions.
The various _heapmin functions shrink the following heaps:
Function     Heap Minimized
_heapmin
Depends on data model of the program

_bheapmin
Based heap specified by seg value; _NULLSEG specifies all based heaps

_fheapmin
Far heap (outside the default data segment)

_nheapmin
Near heap (inside the default data segment)

In a small data memory model, the _heapmin function is equivalent to the _nheapmin function; in a large data memory model, the _heapmin function is equivalent to the _fheapmin function.   It is identical to the _heapshrink function.
Returns:
These functions return zero if successful, and non-zero if some error occurred.
See Also:
_heapchk, _heapenable, _heapgrow, _heapset, _heapshrink, _heapwalk
Example:

#include <stdlib.h>
#include <malloc.h>

void main()
  {
    _heapmin();
    system( "chdir c:\\watcomc" );
  }

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single backslash.
Classification:
WATCOM
Systems:
_heapmin - All, Linux, RDOS
_bheapmin - DOS/16, Windows, OS/2 1.x(all)
_fheapmin - DOS/16, Windows, OS/2 1.x(all)
_nheapmin - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_heapset Functions

Synopsis:

#include <malloc.h>
int  _heapset( unsigned int fill_char );
int _bheapset( __segment seg, unsigned int fill_char );
int _fheapset( unsigned int fill_char );
int _nheapset( unsigned int fill_char );
Description:
The _heapset functions along with _heapchk and _heapwalk are provided for debugging heap related problems in programs.
The _heapset functions perform a consistency check on the unallocated memory space or "heap" just as _heapchk does, and sets the heap's free entries with the fill_char value.

Each function checks and sets a particular heap, as listed below:
Function     Heap Filled
_heapset
Depends on data model of the program

_bheapset
Based heap specified by seg value; _NULLSEG specifies all based heaps

_fheapset
Far heap (outside the default data segment)

_nheapset
Near heap (inside the default data segment)

In a small data memory model, the _heapset function is equivalent to the _nheapset function; in a large data memory model, the _heapset function is equivalent to the _fheapset function.
Returns:
The _heapset functions return one of the following manifest constants which are defined in <malloc.h>.
Constant     Meaning
_HEAPOK
The heap appears to be consistent.

_HEAPEMPTY
The heap is empty.

_HEAPBADBEGIN
The heap has been damaged.

_HEAPBADNODE
The heap contains a bad node, or is damaged.
See Also:
_heapchk, _heapenable, _heapgrow, _heapmin, _heapshrink, _heapwalk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    int heap_status;
    char *buffer;

    buffer = (char *)malloc( 80 );
    malloc( 1024 );
    free( buffer );
    heap_status = _heapset( 0xff );
    switch( heap_status ) {
    case _HEAPOK:
      printf( "OK - heap is good\n" );
      break;
    case _HEAPEMPTY:
      printf( "OK - heap is empty\n" );
      break;
    case _HEAPBADBEGIN:
      printf( "ERROR - heap is damaged\n" );
      break;
    case _HEAPBADNODE:
      printf( "ERROR - bad node in heap\n" );
      break;
    }
  }
Classification:
WATCOM
Systems:
_heapset - All, Linux, RDOS
_bheapset - DOS/16, Windows, OS/2 1.x(all)
_fheapset - DOS/16, Windows, OS/2 1.x(all)
_nheapset - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_heapshrink Functions

Synopsis:

#include <malloc.h>
int  _heapshrink( void );
int _bheapshrink( __segment seg );
int _fheapshrink( void );
int _nheapshrink( void );
Description:
The _heapshrink functions attempt to shrink the heap to its smallest possible size by returning all free entries at the end of the heap back to the system.  This can be used to free up as much memory as possible before using the system function or one of the spawn... functions.
The various _heapshrink functions shrink the following heaps:
Function     Heap Shrinked
_heapshrink
Depends on data model of the program

_bheapshrink
Based heap specified by seg value; _NULLSEG specifies all based heaps

_fheapshrink
Far heap (outside the default data segment)

_nheapshrink
Near heap (inside the default data segment)

In a small data memory model, the _heapshrink function is equivalent to the _nheapshrink function; in a large data memory model, the _heapshrink function is equivalent to the _fheapshrink function.  It is identical to the _heapmin function.
Returns:
These functions return zero if successful, and non-zero if some error occurred.
See Also:
_heapchk, _heapenable, _heapgrow, _heapmin, _heapset, _heapwalk
Example:

#include <stdlib.h>
#include <malloc.h>

void main()
  {
    _heapshrink();
    system( "chdir c:\\watcomc" );
  }

Note the use of two adjacent backslash characters (\) within character-string constants to signify a single backslash.
Classification:
WATCOM
Systems:
_heapshrink - All, Linux, RDOS
_bheapshrink - DOS/16, Windows, OS/2 1.x(all)
_fheapshrink - DOS/16, Windows, OS/2 1.x(all)
_nheapshrink - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

_heapwalk Functions

Synopsis:

#include <malloc.h>
int  _heapwalk( struct _heapinfo *entry );
int _bheapwalk( __segment seg, struct _heapinfo *entry );
int _fheapwalk( struct _heapinfo *entry );
int _nheapwalk( struct _heapinfo *entry );

struct _heapinfo {
    void __far *_pentry;   /* heap pointer              */
    size_t     _size;      /* heap entry size           */
    int        _useflag;   /* heap entry 'in-use' flag */
};
#define _USEDENTRY      0
#define _FREEENTRY      1
Description:
The _heapwalk functions along with _heapchk and _heapset are provided for debugging heap related problems in programs.
The _heapwalk functions walk through the heap, one entry per call, updating the _heapinfo structure with information on the next heap entry.  The structure is defined in <malloc.h>.  You must initialize the _pentry field with NULL to start the walk through the heap.

Each function walks a particular heap, as listed below:
Function     Heap Walked
_heapwalk
Depends on data model of the program

_bheapwalk
Based heap specified by seg value; _NULLSEG specifies all based heaps

_fheapwalk
Far heap (outside the default data segment)

_nheapwalk
Near heap (inside the default data segment)

In a small data memory model, the _heapwalk function is equivalent to the _nheapwalk function; in a large data memory model, the _heapwalk function is equivalent to the _fheapwalk function.
Returns:
These functions return one of the following manifest constants which are defined in <malloc.h>.
Constant     Meaning
_HEAPOK
The heap is OK so far, and the _heapinfo structure contains information about the next entry in the heap.

_HEAPEMPTY
The heap is empty.

_HEAPBADPTR
The _pentry field of the entry structure does not contain a valid pointer into the heap.

_HEAPBADBEGIN
The header information for the heap was not found or has been damaged.

_HEAPBADNODE
The heap contains a bad node, or is damaged.

_HEAPEND
The end of the heap was reached successfully.
See Also:
_heapchk, _heapenable, _heapgrow, _heapmin, _heapset, _heapshrink
Example:

#include <stdio.h>
#include <malloc.h>

heap_dump()
  {
    struct _heapinfo h_info;
    int heap_status;

    h_info._pentry = NULL;
    for(;;) {
      heap_status = _heapwalk( &h_info );
      if( heap_status != _HEAPOK ) break;
      printf( "  %s block at %Fp of size %4.4X\n",
        (h_info._useflag == _USEDENTRY ? "USED" : "FREE"),
        h_info._pentry, h_info._size );
    }

    switch( heap_status ) {
    case _HEAPEND:
      printf( "OK - end of heap\n" );
      break;
    case _HEAPEMPTY:
      printf( "OK - heap is empty\n" );
      break;
    case _HEAPBADBEGIN:
      printf( "ERROR - heap is damaged\n" );
      break;
    case _HEAPBADPTR:
      printf( "ERROR - bad pointer to heap\n" );
      break;
    case _HEAPBADNODE:
      printf( "ERROR - bad node in heap\n" );
    }
  }

void main()
  {
    char *p;
    heap_dump();   p = (char *) malloc( 80 );
    heap_dump();   free( p );
    heap_dump();
  }

produces the following:

On 16-bit 80x86 systems, the following output is produced:

OK - heap is empty
  USED block at 23f8:0ab6 of size 0202
  USED block at 23f8:0cb8 of size 0052
  FREE block at 23f8:0d0a of size 1DA2
OK - end of heap
  USED block at 23f8:0ab6 of size 0202
  FREE block at 23f8:0cb8 of size 1DF4
OK - end of heap

On 32-bit 80386/486 systems, the following output is produced:

OK - heap is empty
  USED block at 0014:00002a7c of size 0204
  USED block at 0014:00002c80 of size 0054
  FREE block at 0014:00002cd4 of size 1D98
OK - end of heap
  USED block at 0014:00002a7c of size 0204
  FREE block at 0014:00002c80 of size 1DEC
OK - end of heap
Classification:
WATCOM
Systems:
_heapwalk - All, Linux, RDOS
_bheapwalk - DOS/16, Windows, OS/2 1.x(all)
_fheapwalk - DOS/16, Windows, OS/2 1.x(all)
_nheapwalk - DOS, Windows, Win386, Win32, OS/2 1.x, OS/2 1.x(MT), OS/2-32, Linux, RDOS

hfree

Synopsis:

#include <malloc.h>
void hfree( void __huge *ptr );
Description:
The hfree function deallocates a memory block previously allocated by the halloc function.   The argument ptr points to a memory block to be deallocated.  After the call, the freed block is available for allocation.
Returns:
The hfree function returns no value.
See Also:
calloc Functions, _expand Functions, free Functions, halloc, malloc Functions, _msize Functions, realloc Functions, sbrk
Example:

#include <stdio.h>
#include <malloc.h>

void main()
  {
    long int __huge *big_buffer;

    big_buffer = (long int __huge *)
                  halloc( 1024L, sizeof(long) );
    if( big_buffer == NULL ) {
      printf( "Unable to allocate memory\n" );
    } else {

      /* rest of code goes here */

      hfree( big_buffer );  /* deallocate */
    }
  }
Classification:
WATCOM
Systems:
DOS/16, Windows, OS/2 1.x(all)

hypot

Synopsis:

#include <math.h>
double hypot( double x, double y );
Description:
The hypot function computes the length of the hypotenuse of a right triangle whose sides are x and y adjacent to that right angle.  The calculation is equivalent to
    sqrt( x*x + y*y )

The computation may cause an overflow, in which case the matherr function will be invoked.
Returns:
The value of the hypotenuse is returned.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%f\n", hypot( 3.0, 4.0 ) );
  }

produces the following:

5.000000
Classification:
WATCOM
Systems:
Math

ignore_handler_s

Synopsis:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
void ignore_handler_s(
        const char * restrict msg,
        void * restrict ptr,
        errno_t error );
Description:
A pointer to the ignore_handler_s function may be passed as an argument to the set_constraint_handler_s function.  The ignore_handler_s function simply returns to its caller.
Returns:
The ignore_handler_s function does not returns no value.
See Also:
abort_handler_s, set_constraint_handler_s
Example:

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdlib.h>
#include <stdio.h>

void main( void )
{
    constraint_handler_t    old_handler;

    old_handler =
        set_constraint_handler_s( ignore_handler_s );
    if( getenv_s( NULL, NULL, 0, NULL ) ) {
        printf( "getenv_s failed\n" );
    }
    set_constraint_handler_s( old_handler );
}

produces the following:

getenv_s failed
Classification:
TR 24731
Systems:
All, Linux, RDOS, Netware

ilogb

Synopsis:

#include <math.h>
int ilogb( double x );
Description:
The ilogb function returns the exponent portion of the argument x as an int.
Returns:
If successful, the return value is the exponent of x.  When the argument is zero, the function returns FP_ILOGB0.   When the argument is not-a-number, or NAN, the function returns FP_ILOGBNAN.  For positive or negative infinity, the function returns INT_MAX.
See Also:
logb
Example:

#include <stdio.h>
#include <math.h>

void main()
  {
    printf( "%d\n", ilogb( 1024.0 ) );
  }

produces the following:

10
Classification:
ISO C99
Systems:
Math

_imagesize, _imagesize_w, _imagesize_wxy

Synopsis:

#include <graph.h>
long _FAR _imagesize( short x1, short y1,
                       short x2, short y2 );

long _FAR _imagesize_w( double x1, double y1,
                         double x2, double y2 );

long _FAR _imagesize_wxy( struct _wxycoord _FAR *p1,
                           struct _wxycoord _FAR *p2 );
Description:
The _imagesize functions compute the number of bytes required to store a screen image.  The _imagesize function uses the view coordinate system.  The _imagesize_w and _imagesize_wxy functions use the window coordinate system.
The screen image is the rectangular area defined by the points (x1,y1) and (x2,y2).  The storage area used by the _getimage functions must be at least this large (in bytes).
Returns:
The _imagesize functions return the size of a screen image.
See Also:
_getimage, _putimage
Example:

#include <conio.h>
#include <graph.h>
#include <malloc.h>

main()
{
    char *buf;
    int y;

    _setvideomode( _VRES16COLOR );
    _ellipse( _GFILLINTERIOR, 100, 100, 200, 200 );
    buf = (char*) malloc(
                  _imagesize( 100, 100, 201, 201 ) );
    if( buf != NULL ) {
        _getimage( 100, 100, 201, 201, buf );
        _putimage( 260, 200, buf, _GPSET );
        _putimage( 420, 100, buf, _GPSET );
        for( y = 100; y < 300; ) {
            _putimage( 420, y, buf, _GXOR );
            y += 20;
            _putimage( 420, y, buf, _GXOR );
        }
        free( buf );
    }
    getch();
    _setvideomode( _DEFAULTMODE );
}
Classification:
PC Graphics
Systems:
_imagesize - DOS
_imagesize_w - DOS
_imagesize_wxy - DOS

imaxabs

Synopsis:

#include <inttypes.h>
intmax_t imaxabs( intmax_t j );
Description:
The imaxabs function returns the absolute value of its maximum-size integer argument j.
Returns:
The imaxabs function returns the absolute value of its argument.
See Also:
labs, llabs, abs, fabs
Example:

#include <stdio.h>
#include <inttypes.h>

void main( void )
{
    intmax_t    x, y;

    x = -500000000000;
    y = imaxabs( x );
    printf( "imaxabs(%jd) = %jd\n", x, y );
}

produces the following:

imaxabs(-500000000000) = 500000000000
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

imaxdiv

Synopsis:

#include <stdlib.h>
imaxdiv_t imaxdiv( intmax_t numer, intmax_t denom );

typedef struct {
    intmax_t    quot;  /* quotient  */
    intmax_t    rem;   /* remainder */
} imaxdiv_t;
Description:
The imaxdiv function calculates the quotient and remainder of the division of the numerator numer by the denominator denom.
Returns:
The imaxdiv function returns a structure of type imaxdiv_t that contains the fields quot and rem, which are both of type intmax_t.
See Also:
div, ldiv, lldiv
Example:

#include <stdio.h>
#include <inttypes.h>

void print_time( intmax_t ticks )
{
    imaxdiv_t sec_ticks;
    imaxdiv_t min_sec;

    sec_ticks = imaxdiv( ticks, 1000000 );
    min_sec   = imaxdiv( sec_ticks.quot, 60 );
    printf( "It took %jd minutes and %jd seconds\n",
            min_sec.quot, min_sec.rem );
}

void main( void )
{
    print_time( 9876543210 );
}

produces the following:

It took 164 minutes and 36 seconds
Classification:
ISO C99
Systems:
All, Linux, RDOS, Netware

inp

Synopsis:

#include <conio.h>
unsigned int inp( int port );
Description:
The inp function reads one byte from the 80x86 hardware port whose number is given by port.
A hardware port is used to communicate with a device.  One or two bytes can be read and/or written from each port, depending upon the hardware.  Consult the technical documentation for your computer to determine the port numbers for a device and the expected usage of each port for a device.
Returns:
The value returned is the byte that was read.
See Also:
inpd, inpw, outp, outpd, outpw
Example:

#include <conio.h>

void main()
  {
    /* turn off speaker */
    outp( 0x61, inp( 0x61 ) & 0xFC );
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

inpd

Synopsis:

#include <conio.h>
unsigned long inpd( int port );
Description:
The inpd function reads a double-word (four bytes) from the 80x86 hardware port whose number is given by port.
A hardware port is used to communicate with a device.  One or two bytes can be read and/or written from each port, depending upon the hardware.  Consult the technical documentation for your computer to determine the port numbers for a device and the expected usage of each port for a device.
Returns:
The value returned is the double-word that was read.
See Also:
inp, inpw, outp, outpd, outpw
Example:

#include <conio.h>
#define DEVICE 34

void main()
  {
    unsigned long transmitted;

    transmitted = inpd( DEVICE );
  }
Classification:
Intel
Systems:
DOS/32, Win386, Win32, OS/2-32, Linux, RDOS, Netware

inpw

Synopsis:

#include <conio.h>
unsigned int inpw( int port );
Description:
The inpw function reads a word (two bytes) from the 80x86 hardware port whose number is given by port.
A hardware port is used to communicate with a device.  One or two bytes can be read and/or written from each port, depending upon the hardware.  Consult the technical documentation for your computer to determine the port numbers for a device and the expected usage of each port for a device.
Returns:
The value returned is the word that was read.
See Also:
inp, inpd, outp, outpd, outpw
Example:

#include <conio.h>
#define DEVICE 34

void main()
  {
    unsigned int transmitted;

    transmitted = inpw( DEVICE );
  }
Classification:
Intel
Systems:
All, Linux, RDOS, Netware

int386

Synopsis:

#include <i86.h>
int int386( int inter_no,
           const union REGS *in_regs,
           union REGS *out_regs );
Description:
The int386 function causes the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  This function is present in the 386 C libraries and may be executed on 80386/486 systems.   Before the interrupt, the CPU registers are loaded from the structure located by in_regs.  Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.  These structures may be located at the same location in memory.
You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The int386 function returns the value of the CPU EAX register after the interrupt.
See Also:
bdos, int386x, int86, int86x, intdos, intdosx, intr, intrf, segread
Example:

/*
* This example clears the screen on DOS
*/
#include <i86.h>

void main()
  {
    union REGS  regs;

    regs.w.cx = 0;
    regs.w.dx = 0x1850;
    regs.h.bh = 7;
    regs.w.ax = 0x0600;
#if defined(__386__) && defined(__DOS__)
    int386( 0x10, &regs, &regs );
#else
    int86( 0x10, &regs, &regs );
#endif
  }
Classification:
Intel
Systems:
DOS/32, Linux, RDOS, Netware

int386x

Synopsis:

#include <i86.h>
int int386x( int inter_no,
             const union REGS *in_regs,
             union REGS *out_regs,
             struct SREGS *seg_regs );
Description:
The int386x function causes the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  This function is present in the 32-bit C libraries and may be executed on Intel 386 compatible systems.  Before the interrupt, the CPU registers are loaded from the structure located by in_regs and the DS, ES, FS and GS segment registers are loaded from the structure located by seg_regs.  All of the segment registers must contain valid values.  Failure to do so will cause a segment violation when running in protect mode.  If you don't care about a particular segment register, then it can be set to 0 which will not cause a segment violation.  The function segread can be used to initialize seg_regs to their current values.
Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.  The in_regs and out_regs structures may be located at the same location in memory.  The original values of the DS, ES, FS and GS registers are restored.  The structure seg_regs is updated with the values of the segment registers following the interrupt.

You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The int386x function returns the value of the CPU EAX register after the interrupt.
See Also:
bdos, int386, int86, int86x, intdos, intdosx, intr, intrf, segread
Example:

#include <stdio.h>
#include <i86.h>

/* get current mouse interrupt handler address */

void main()
  {
    union REGS r;
    struct SREGS s;

    s.ds = s.es = s.fs = s.gs = FP_SEG( &s );

#if defined(__PHARLAP__)
    r.w.ax = 0x2503;    /* get real-mode vector */
    r.h.cl = 0x33;      /* interrupt vector 0x33 */
    int386( 0x21, &r, &r );
    printf( "mouse handler real-mode address="
            "%lx\n", r.x.ebx );
    r.w.ax = 0x2502;    /* get protected-mode vector */
    r.h.cl = 0x33;      /* interrupt vector 0x33 */
    int386x( 0x21, &r, &r, &s );
    printf( "mouse handler protected-mode address="
            "%x:%lx\n", s.es, r.x.ebx );

#else
    r.h.ah = 0x35;  /* get vector */
    r.h.al = 0x33;  /* vector 0x33 */
    int386x( 0x21, &r, &r, &s );
    printf( "mouse handler protected-mode address="
            "%x:%lx\n", s.es, r.x.ebx );
#endif
  }
Classification:
Intel
Systems:
DOS/32, Linux, RDOS, Netware

int86

Synopsis:

#include <i86.h>
int int86( int inter_no,
           const union REGS *in_regs,
           union REGS *out_regs );
Description:
The int86 function causes the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  Before the interrupt, the CPU registers are loaded from the structure located by in_regs.   Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.   These structures may be located at the same location in memory.
You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The int86 function returns the value of the CPU AX register after the interrupt.
See Also:
bdos, int386, int386x, int86x, intdos, intdosx, intr, intrf, segread
Example:

/*
* This example clears the screen on DOS
*/
#include <i86.h>

void main()
  {
    union REGS  regs;

    regs.w.cx = 0;
    regs.w.dx = 0x1850;
    regs.h.bh = 7;
    regs.w.ax = 0x0600;
#if defined(__386__) && defined(__DOS__)
    int386( 0x10, &regs, &regs );
#else
    int86( 0x10, &regs, &regs );
#endif
  }
Classification:
Intel
Systems:
DOS/16, Windows, Win386, DOS/PM

int86x

Synopsis:

#include <i86.h>
int int86x( int inter_no,
            const union REGS *in_regs,
            union REGS *out_regs,
            struct SREGS *seg_regs );
Description:
The int86x function causes the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  Before the interrupt, the CPU registers are loaded from the structure located by in_regs and the DS and ES segment registers are loaded from the structure located by seg_regs.  All of the segment registers must contain valid values.  Failure to do so will cause a segment violation when running in protect mode.  If you don't care about a particular segment register, then it can be set to 0 which will not cause a segment violation.  The function segread can be used to initialize seg_regs to their current values.
Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.  The in_regs and out_regs structures may be located at the same location in memory.  The original values of the DS and ES registers are restored.  The structure seg_regs is updated with the values of the segment registers following the interrupt.

You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The function returns the value of the CPU AX register after the interrupt.
See Also:
bdos, int386, int386x, int86, intdos, intdosx, intr, intrf, segread
Example:

#include <stdio.h>
#include <i86.h>

/* get current mouse interrupt handler address */

void main()
  {
    union REGS r;
    struct SREGS s;

    r.h.ah = 0x35;  /* DOS get vector */
    r.h.al = 0x33;  /* interrupt vector 0x33 */
    int86x( 0x21, &r, &r, &s );
    printf( "mouse handler address=%4.4x:%4.4x\n",
            s.es, r.w.bx );
  }
Classification:
Intel
Systems:
DOS/16, Windows, Win386, DOS/PM

intdos

Synopsis:

#include <dos.h>
int intdos( const union REGS *in_regs,
            union REGS *out_regs );
Description:
The intdos function causes the computer's central processor (CPU) to be interrupted with an interrupt number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function.  Before the interrupt, the CPU registers are loaded from the structure located by in_regs.  The AH register contains a number indicating the function requested.   Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.   These structures may be located at the same location in memory.
You should consult the technical documentation for the DOS operating system that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The function returns the value of the AX (EAX in 386 library) register after the interrupt has completed.  The CARRY flag (when set, an error has occurred) is copied into the structure located by out_regs.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
bdos, int386, int386x, int86, int86x, intdosx, intr, intrf, segread
Example:

#include <dos.h>

#define DISPLAY_OUTPUT  2

void main()
  {
    union REGS  in_regs, out_regs;
    int         rc;

    in_regs.h.ah = DISPLAY_OUTPUT;
    in_regs.h.al = 0;

    in_regs.w.dx = 'I';
    rc = intdos( &in_regs, &out_regs );
    in_regs.w.dx = 'N';
    rc = intdos( &in_regs, &out_regs );
    in_regs.w.dx = 'T';
    rc = intdos( &in_regs, &out_regs );
    in_regs.w.dx = 'D';
    rc = intdos( &in_regs, &out_regs );
    in_regs.w.dx = 'O';
    rc = intdos( &in_regs, &out_regs );
    in_regs.w.dx = 'S';
    rc = intdos( &in_regs, &out_regs );
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, DOS/PM

intdosx

Synopsis:

#include <dos.h>
int intdosx( const union REGS *in_regs,
             union REGS *out_regs,
             struct SREGS *seg_regs );
Description:
The intdosx function causes the computer's central processor (CPU) to be interrupted with an interrupt number hexadecimal 21 (0x21), which is a request to invoke a specific DOS function.  Before the interrupt, the CPU registers are loaded from the structure located by in_regs and the segment registers DS and ES are loaded from the structure located by seg_regs.  The AH register contains a number indicating the function requested.  All of the segment registers must contain valid values.  Failure to do so will cause a segment violation when running in protect mode.  If you don't care about a particular segment register, then it can be set to 0 which will not cause a segment violation.  The function segread can be used to initialize seg_regs to their current values.
Following the interrupt, the structure located by out_regs is filled with the contents of the CPU registers.  The in_regs and out_regs structures may be located at the same location in memory.  The original values for the DS and ES registers are restored.  The structure seg_regs is updated with the values of the segment registers following the interrupt.

You should consult the technical documentation for the DOS operating system that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The intdosx function returns the value of the AX (EAX in 32-bit library) register after the interrupt has completed.   The CARRY flag (when set, an error has occurred) is copied into the structure located by out_regs.  When an error has occurred, errno contains a value indicating the type of error that has been detected.
See Also:
bdos, int386, int386x, int86, int86x, intdos, intr, intrf, segread
Example:

#include <stdio.h>
#include <dos.h>

/* get current mouse interrupt handler address */

void main()
  {
    union REGS r;
    struct SREGS s;

#if defined(__386__)
    s.ds = s.es = s.fs = s.gs = FP_SEG( &s );
#endif
    r.h.ah = 0x35;  /* get vector */
    r.h.al = 0x33;  /* vector 0x33 */
    intdosx( &r, &r, &s );
#if defined(__386__)
    printf( "mouse handler address=%4.4x:%lx\n",
            s.es, r.x.ebx );
#else
    printf( "mouse handler address=%4.4x:%4.4x\n",
            s.es, r.x.bx );
#endif
  }
Classification:
DOS
Systems:
DOS, Windows, Win386, DOS/PM

intr

Synopsis:

#include <i86.h>
void intr( int inter_no, union REGPACK *regs );
Description:
The intr functions cause the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  Before the interrupt, the CPU registers are loaded from the structure located by regs.   Low 8-bit of the CPU flags are set to 0.
All of the segment registers must contain valid values.  Failure to do so will cause a segment violation when running in protect mode.  If you don't care about a particular segment register, then it can be set to 0 which will not cause a segment violation.  Following the interrupt, the structure located by regs is filled with the contents of the CPU registers.

intr function is similar to the int86x function, except that only one structure is used for the register values and that the BP (EBP in 386 library) register is included in the set of registers that are passed and saved.

You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The intr function do not return a value.
See Also:
bdos, int386, int386x, int86, int86x, intdos, intdosx, intrf, segread
Example:

#include <stdio.h>
#include <string.h>
#include <i86.h>

void main() /* Print location of Break Key Vector */
  {
    union REGPACK regs;

    memset( &regs, 0, sizeof(union REGPACK) );
    regs.w.ax = 0x3523;
    intr( 0x21, &regs );
    printf( "Break Key vector is "
#if defined(__386__)
            "%x:%lx\n", regs.w.es, regs.x.ebx );
#else
            "%x:%x\n", regs.w.es, regs.x.bx );
#endif
  }

produces the following:

Break Key vector is eef:13c
Classification:
Intel
Systems:
DOS, Windows, Win386, Linux, RDOS, DOS/PM, Netware

intrf

Synopsis:

#include <i86.h>
void intrf( int inter_no, union REGPACK *regs );
Description:
The intrf functions cause the computer's central processor (CPU) to be interrupted with an interrupt whose number is given by inter_no.  Before the interrupt, the CPU registers are loaded from the structure located by regs.   Low 8-bit of the CPU flags is set to the flags member of the structure regs.
All of the segment registers must contain valid values.  Failure to do so will cause a segment violation when running in protect mode.  If you don't care about a particular segment register, then it can be set to 0 which will not cause a segment violation.  Following the interrupt, the structure located by regs is filled with the contents of the CPU registers.

intrf function is similar to the int86x function.  Exception is that only one structure is used for the register values and that the BP (EBP in 386 library) register is included in the set of registers that are passed and saved and the CPU flags are set to flags member of the structure regs

You should consult the technical documentation for the computer that you are using to determine the expected register contents before and after the interrupt in question.
Returns:
The intrf function do not return a value.
See Also:
bdos, int386, int386x, int86, int86x, intdos, intdosx, intr, segread
Example:

#include <stdio.h>
#include <string.h>
#include <i86.h>

void main() /* Print location of Break Key Vector */
  {
    union REGPACK regs;

    memset( &regs, 0, sizeof(union REGPACK) );
    regs.w.ax = 0x3523;
    regs.w.flags = 0;
    intrf( 0x21, &regs );
    printf( "Break Key vector is "
#if defined(__386__)
            "%x:%lx\n", regs.w.es, regs.x.ebx );
#else
            "%x:%x\n", regs.w.es, regs.x.bx );
#endif
  }

produces the following:

Break Key vector is eef:13c
Classification:
Intel
Systems:
DOS, Windows, Win386, Linux, RDOS, DOS/PM, Netware

isalnum, iswalnum

Synopsis:

#include <ctype.h>
int isalnum( int c );
#include <wctype.h>
int iswalnum( wint_t c );
Description:
The isalnum function tests if the argument c is an alphanumeric character ('a' to 'z', 'A' to 'Z', or '0' to '9').  An alphanumeric character is any character for which isalpha or isdigit is true.
The iswalnum function is a wide character version of isalnum that operates with wide character argument.
Returns:
The isalnum function returns zero if the argument is neither an alphabetic character (A-Z or a-z) nor a digit (0-9).   Otherwise, a non-zero value is returned.  The iswalnum function returns a non-zero value if either iswalpha or iswdigit is true for c.
See Also:
isalpha, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, tolower, toupper, isleadbyte, iswalnum, iswalpha, iswblank, iswcntrl, iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit, towlower, towupper, iswctype, wctype, wctrans, towctrans
Example:

#include <stdio.h>
#include <ctype.h>

void main()
{
    if( isalnum( getchar() ) ) {
        printf( "is alpha-numeric\n" );
    }
}
Classification:
ISO C
iswalnum is ISO C95
Systems:
isalnum - All, Linux, RDOS, Netware
iswalnum - All, Linux, RDOS, Netware

isalpha, iswalpha

Synopsis:

#include <ctype.h>
int isalpha( int c );
#include <wctype.h>
int iswalpha( wint_t c );
Description:
The isalpha function tests if the argument c is an alphabetic character ('a' to 'z' and 'A' to 'Z').  An alphabetic character is any character for which isupper or islower is true.
The iswalpha function is a wide character version of isalpha that operates with wide character argument.
Returns:
The isalpha function returns zero if the argument is not an alphabetic character (A-Z or a-z); otherwise, a non-zero value is returned.  The iswalpha function returns a non-zero value only for wide characters for which iswupper or iswlower is true, or any wide character that is one of an implementation-defined set for which none of iswcntrl, iswdigit, iswpunct, or iswspace is true.
See Also:
isalnum, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, tolower, toupper, isleadbyte, iswalnum, iswalpha, iswblank, iswcntrl, iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit, towlower, towupper, iswctype, wctype, wctrans, towctrans
Example:

#include <stdio.h>
#include <ctype.h>

void main()
{
    if( isalpha( getchar() ) ) {
        printf( "is alphabetic\n" );
    }
}
Classification:
ISO C
iswalpha is ISO C95
Systems:
isalpha - All, Linux, RDOS, Netware
iswalpha - All, Linux, RDOS, Netware

isascii, __isascii, iswascii

Synopsis:

#include <ctype.h>
int isascii( int c );
int __isascii( int c );
#include <wctype.h>
int iswascii( wint_t c );
Description:
The isascii function tests for a character in the range from 0 to 127.
The __isascii function is identical to isascii.  Use __isascii for ANSI naming conventions.

The iswascii function is a wide character version of isascii that operates with wide character argument.
Returns:
The isascii function returns a non-zero value when the character is in the range 0 to 127; otherwise, zero is returned.   The iswascii function returns a non-zero value when c is a wide character representation of an ASCII character.
See Also:
isalnum, isalpha, isblank, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace, isupper, isxdigit, tolower, toupper, isleadbyte, iswalnum, iswalpha, iswblank, iswcntrl, iswdigit, iswgraph, iswlower, iswprint, iswpunct, iswspace, iswupper, iswxdigit, towlower, towupper, iswctype, wctype, wctrans, towctrans
Example:

#include <stdio.h>
#include <ctype.h>

char chars[] = {
    'A',
    0x80,
    'Z'
};

#define SIZE sizeof( chars ) / sizeof(